Added node-based file attachment upload example

Author: ssddanbrown

Diff for: node-upload-attachment/index.js

@@ -0,0 +1,76 @@
+// Libraries used
+const fs = require('fs');
+const path = require('path');
+const axios = require('axios');
+const FormData = require('form-data');
+
+// BookStack API variables
+// Uses values on the environment unless hardcoded
+// To hardcode, add values to the empty strings in the below.
+const bookStackConfig = {
+    base_url: '' || process.env.BS_URL,
+    token_id: '' || process.env.BS_TOKEN_ID,
+    token_secret: '' || process.env.BS_TOKEN_SECRET,
+};
+
+// Script Logic
+////////////////
+
+// Check arguments provided
+if (process.argv.length < 4) {
+    console.error('Both <page_id> and <file_path> arguments need to be provided');
+    return;
+}
+
+// Get arguments passed via command
+const [_exec, _script, pageId, filePath] = process.argv;
+
+// Check the given file exists
+if (!fs.existsSync(filePath)) {
+    console.error(`File at "${filePath}" could not be found`);
+    return;
+}
+
+// Get the file name and create a read stream from the given file
+const fileStream = fs.createReadStream(filePath);
+const fileName = path.basename(filePath);
+
+// Gather our form data with all the required bits
+const formPostData = new FormData();
+formPostData.append('file', fileStream);
+formPostData.append('name', fileName);
+formPostData.append('uploaded_to', pageId);
+
+// Create an axios instance for our API
+const api = axios.create({
+    baseURL: bookStackConfig.base_url.replace(/\/$/, '') + '/api/',
+    timeout: 30000,
+    headers: { 'Authorization' : `Token ${bookStackConfig.token_id}:${bookStackConfig.token_secret}` },
+});
+
+// Wrap the rest of our code in an async function, so we can await within.
+(async function() {
+
+    // Upload the file using the gathered data
+    // Sends it with a "Content-Type: multipart/form-data" with the post
+    // body formatted as multipart/form-data content, with the "FormData" object
+    // from the "form-data" library does for us.
+    const {data: attachment} = await api.post('/attachments', formPostData, {
+        headers: formPostData.getHeaders(),
+    });
+
+    // Output the results
+    console.info(`File successfully uploaded to page ${pageId}.`);
+    console.info(` - Attachment ID: ${attachment.id}`);
+    console.info(` - Attachment Name: ${attachment.name}`);
+
+})().catch(err => {
+    // Handle API errors
+    if (err.response) {
+        console.error(`Request failed with status ${err.response.status} [${err.response.statusText}]`);
+        console.error(JSON.stringify(err.response.data));
+        return;
+    }
+    // Output all other errors
+    console.error(err)
+});

Diff for: node-upload-attachment/package-lock.json

@@ -0,0 +1,16 @@
+{
+  "name": "upload-attachment",
+  "version": "1.0.0",
+  "description": "This script will upload the passed file into a BookStack book via the API.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Dan Brown",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^0.25.0",
+    "form-data": "^4.0.0"
+  }
+}

Diff for: node-upload-attachment/package.json

@@ -0,0 +1,41 @@
+# Upload a file attachment to a BookStack page
+
+This script will take a path to any local file and attempt
+to upload it to a BookStack page as an attachment
+using the API using a multipart/form-data request.
+
+This is a simplistic example of a NodeJS script. You will likely want to
+alter and extend this script to suit your use-case.
+
+## Requirements
+
+You will need NodeJS installed (Tested on v16, may work on earlier versions). 
+
+## Running
+
+First, download all the files in the same directory as this readme to a folder on your system
+and run the below from within that directory.
+
+```bash
+# Install NodeJS dependencies via NPM
+npm install 
+
+# Setup
+# ALTERNATIVELY: Open the script and add to the empty strings in the variables at the top.
+export BS_URL=https://bookstack.example.com # Set to be your BookStack base URL
+export BS_TOKEN_ID=abc123 # Set to be your API token_id
+export BS_TOKEN_SECRET=123abc # Set to be your API token_secret
+
+# Running the script
+node index.js <page_id> <file_path>
+```
+
+- `<page_id>` - The ID of the page you want to upload the attachment to.
+- `<file_path>` - File you want to upload as an attachment.
+        
+## Examples
+
+```bash
+# Upload the 'cat-image-collection.zip' file as an attachment to page of ID 205
+node index.js 205 ./cat-image-collection.zip
+```