@processlink/node-red-contrib-processlink 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Process Link
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @processlink/node-red-contrib-processlink
+
+Node-RED nodes for Process Link platform integration.
+
+## Available Nodes
+
+| Node | Category | Description |
+|------|----------|-------------|
+| **files upload** | Process Link | Upload files to Process Link Files API |
+
+*More nodes coming soon: mail, downtime, notes*
+
+## Installation
+
+### Via Node-RED Palette Manager (Recommended)
+
+1. Open Node-RED
+2. Go to **Menu → Manage palette → Install**
+3. Search for `@processlink/node-red-contrib-processlink`
+4. Click **Install**
+
+### Via npm
+
+```bash
+cd ~/.node-red
+npm install @processlink/node-red-contrib-processlink
+```
+
+Then restart Node-RED.
+
+## Quick Start
+
+1. **Get your credentials** from your Process Link app:
+   - Go to **Settings → API Keys**
+   - Click **Generate API Key**
+   - Copy the **Site ID** and **API Key**
+
+2. **Add a node** to your flow:
+   - Find nodes in the palette under "Process Link"
+   - Drag one into your flow
+
+3. **Configure credentials**:
+   - Double-click the node
+   - Click the pencil icon next to "Config"
+   - Enter your **Site ID** and **API Key**
+   - Click **Add**, then **Done**
+
+## Node Reference
+
+### Files Upload
+
+Uploads files to the Process Link Files API.
+
+#### Inputs
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `msg.payload` | Buffer \| string | The file content to upload |
+| `msg.filename` | string | (Optional) Filename to use |
+
+#### Outputs
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `msg.payload` | object | API response with `ok`, `file_id`, `created_at` |
+| `msg.file_id` | string | The UUID of the uploaded file |
+| `msg.statusCode` | number | HTTP status code (201 on success) |
+
+#### Status Indicators
+
+- Yellow: Uploading in progress
+- Green: Upload successful
+- Red: Error occurred
+
+## Example Flow
+
+Upload a file from disk:
+
+```
+[File In] → [files upload] → [Debug]
+```
+
+1. Configure a **File In** node to read your file
+2. Connect it to the **files upload** node
+3. Add a **Debug** node to see the result
+4. Configure the upload node with your Site ID and API Key
+
+### Dynamic Filename
+
+Set the filename dynamically in a Function node:
+
+```javascript
+msg.filename = "report-" + new Date().toISOString().split('T')[0] + ".csv";
+return msg;
+```
+
+## Error Handling
+
+| Status Code | Meaning | Solution |
+|-------------|---------|----------|
+| 201 | Success | File uploaded successfully |
+| 400 | Bad Request | Check that payload is a valid file buffer |
+| 401 | Unauthorized | Check your API key is correct |
+| 403 | Forbidden | Enable API access in site settings |
+| 404 | Not Found | Check your Site ID is correct |
+| 429 | Rate Limited | Slow down - max 30 uploads/minute per site |
+| 507 | Storage Full | Contact your administrator to increase storage |
+
+## Rate Limits
+
+The API allows **30 uploads per minute** per site. If you exceed this limit, you'll receive a 429 status code. The node will still output the message so you can implement retry logic in your flow.
+
+## Security
+
+- API keys are stored encrypted by Node-RED
+- All communication uses HTTPS
+- Keys are never logged or exposed in flow exports
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/process-link/node-red-contrib-processlink/issues)
+- **Email**: support@processlink.com.au
+
+## License
+
+MIT

package/examples/files-upload.json

@@ -0,0 +1,140 @@
+[
+    {
+        "id": "pl-example-flow",
+        "type": "tab",
+        "label": "Process Link File Upload",
+        "disabled": false,
+        "info": "Example flow demonstrating how to upload files to Process Link Files API"
+    },
+    {
+        "id": "pl-inject",
+        "type": "inject",
+        "z": "pl-example-flow",
+        "name": "Trigger Upload",
+        "props": [],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 130,
+        "y": 100,
+        "wires": [
+            [
+                "pl-file-in"
+            ]
+        ]
+    },
+    {
+        "id": "pl-file-in",
+        "type": "file in",
+        "z": "pl-example-flow",
+        "name": "Read File",
+        "filename": "/path/to/your/file.pdf",
+        "filenameType": "str",
+        "format": "",
+        "chunk": false,
+        "sendError": false,
+        "encoding": "none",
+        "allProps": true,
+        "x": 310,
+        "y": 100,
+        "wires": [
+            [
+                "pl-upload"
+            ]
+        ]
+    },
+    {
+        "id": "pl-upload",
+        "type": "processlink-files-upload",
+        "z": "pl-example-flow",
+        "name": "Upload to Process Link",
+        "server": "",
+        "filename": "",
+        "timeout": "30000",
+        "apiUrl": "https://files.processlink.com.au/api/upload",
+        "x": 530,
+        "y": 100,
+        "wires": [
+            [
+                "pl-switch"
+            ]
+        ]
+    },
+    {
+        "id": "pl-switch",
+        "type": "switch",
+        "z": "pl-example-flow",
+        "name": "Check Status",
+        "property": "statusCode",
+        "propertyType": "msg",
+        "rules": [
+            {
+                "t": "eq",
+                "v": "201",
+                "vt": "num"
+            },
+            {
+                "t": "else"
+            }
+        ],
+        "checkall": "true",
+        "repair": false,
+        "outputs": 2,
+        "x": 730,
+        "y": 100,
+        "wires": [
+            [
+                "pl-debug-success"
+            ],
+            [
+                "pl-debug-error"
+            ]
+        ]
+    },
+    {
+        "id": "pl-debug-success",
+        "type": "debug",
+        "z": "pl-example-flow",
+        "name": "Upload Success",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "complete": "file_id",
+        "targetType": "msg",
+        "statusVal": "file_id",
+        "statusType": "msg",
+        "x": 940,
+        "y": 80,
+        "wires": []
+    },
+    {
+        "id": "pl-debug-error",
+        "type": "debug",
+        "z": "pl-example-flow",
+        "name": "Upload Error",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "complete": "payload",
+        "targetType": "msg",
+        "statusVal": "payload.error",
+        "statusType": "msg",
+        "x": 930,
+        "y": 120,
+        "wires": []
+    },
+    {
+        "id": "pl-comment",
+        "type": "comment",
+        "z": "pl-example-flow",
+        "name": "Instructions: Configure the 'Upload to Process Link' node with your Site ID and API Key",
+        "info": "1. Double-click the orange 'Upload to Process Link' node\n2. Click the pencil icon next to 'Config'\n3. Enter your Site ID and API Key from the Process Link Files app\n4. Update the 'Read File' node with the path to your file\n5. Click the inject button to upload",
+        "x": 330,
+        "y": 40,
+        "wires": []
+    }
+]

package/icons/processlink.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40">
+  <g fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+    <polyline points="8,14 14,6 20,14"/>
+    <polyline points="20,14 26,6 32,14"/>
+    <polyline points="32,17 38,23 32,29"/>
+    <polyline points="32,26 26,34 20,26"/>
+    <polyline points="20,26 14,34 8,26"/>
+    <polyline points="8,29 2,23 8,17"/>
+  </g>
+</svg>

package/nodes/config/processlink-config.html

@@ -0,0 +1,65 @@
+<script type="text/javascript">
+  RED.nodes.registerType("processlink-config", {
+    category: "config",
+    defaults: {
+      name: { value: "" },
+      siteId: { value: "", required: true },
+    },
+    credentials: {
+      apiKey: { type: "password" },
+    },
+    label: function () {
+      return this.name || "Process Link Config";
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="processlink-config">
+  <div class="form-row">
+    <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-config-input-name" placeholder="My Site Config" />
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-siteId"><i class="fa fa-building"></i> Site ID</label>
+    <input
+      type="text"
+      id="node-config-input-siteId"
+      placeholder="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-apiKey"><i class="fa fa-key"></i> API Key</label>
+    <input type="password" id="node-config-input-apiKey" placeholder="Your API key" />
+  </div>
+  <div class="form-tips">
+    <p>
+      Get your Site ID and API Key from
+      <a href="https://processlink.com.au" target="_blank">Process Link</a>.
+    </p>
+    <p>
+      Go to <strong>Settings → API Keys</strong> in your app to generate a new key.
+    </p>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="processlink-config">
+  <p>Configuration node for Process Link API authentication.</p>
+
+  <h3>Properties</h3>
+  <dl class="message-properties">
+    <dt>Name <span class="property-type">string</span></dt>
+    <dd>Optional friendly name for this configuration.</dd>
+    <dt>Site ID <span class="property-type">string</span></dt>
+    <dd>The UUID of your site from Process Link. Found in your site settings.</dd>
+    <dt>API Key <span class="property-type">string</span></dt>
+    <dd>
+      The API key for authentication. Generate one from Settings → API Keys in your Process Link app.
+    </dd>
+  </dl>
+
+  <h3>Details</h3>
+  <p>
+    This configuration is shared across all Process Link nodes in your flow. The API key is stored
+    encrypted by Node-RED.
+  </p>
+</script>

package/nodes/config/processlink-config.js

@@ -0,0 +1,19 @@
+/**
+ * Process Link Configuration Node
+ * Shared credentials for all Process Link nodes
+ */
+
+module.exports = function (RED) {
+  function ProcessLinkConfigNode(config) {
+    RED.nodes.createNode(this, config);
+    this.name = config.name;
+    this.siteId = config.siteId;
+    // API key is stored in this.credentials.apiKey (encrypted by Node-RED)
+  }
+
+  RED.nodes.registerType("processlink-config", ProcessLinkConfigNode, {
+    credentials: {
+      apiKey: { type: "password" },
+    },
+  });
+};

package/nodes/files/processlink-files-upload.html

@@ -0,0 +1,113 @@
+<script type="text/javascript">
+  RED.nodes.registerType("processlink-files-upload", {
+    category: "Process Link",
+    color: "#f97316",
+    defaults: {
+      name: { value: "" },
+      server: { value: "", type: "processlink-config", required: true },
+      filename: { value: "" },
+      timeout: { value: "30000" },
+      apiUrl: { value: "https://files.processlink.com.au/api/upload" },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "processlink.svg",
+    paletteLabel: "files upload",
+    label: function () {
+      return this.name || "files upload";
+    },
+    labelStyle: function () {
+      return this.name ? "node_label_italic" : "";
+    },
+    inputLabels: "file buffer",
+    outputLabels: "response",
+  });
+</script>
+
+<script type="text/html" data-template-name="processlink-files-upload">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Config</label>
+    <input type="text" id="node-input-server" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-filename"><i class="fa fa-file"></i> Filename</label>
+    <input type="text" id="node-input-filename" placeholder="msg.filename (or specify default)" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-timeout"><i class="fa fa-clock-o"></i> Timeout</label>
+    <input type="text" id="node-input-timeout" placeholder="30000" />
+    <span style="margin-left: 5px; color: #888">ms</span>
+  </div>
+  <div class="form-row" style="display: none">
+    <label for="node-input-apiUrl"><i class="fa fa-link"></i> API URL</label>
+    <input type="text" id="node-input-apiUrl" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="processlink-files-upload">
+  <p>Uploads files to the Process Link Files API.</p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">buffer | string</span></dt>
+    <dd>The file content to upload.</dd>
+    <dt class="optional">filename <span class="property-type">string</span></dt>
+    <dd>The filename to use. Defaults to the configured filename or "file.bin".</dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object</span></dt>
+    <dd>The API response containing <code>ok</code>, <code>file_id</code>, and <code>created_at</code>.</dd>
+    <dt>file_id <span class="property-type">string</span></dt>
+    <dd>The UUID of the uploaded file (convenience property).</dd>
+    <dt>statusCode <span class="property-type">number</span></dt>
+    <dd>The HTTP status code (201 on success).</dd>
+  </dl>
+
+  <h3>Details</h3>
+  <p>
+    This node uploads files to your Process Link site. The file content should be passed in
+    <code>msg.payload</code> as a Buffer (from a file-in node) or as a string.
+  </p>
+  <p>
+    The filename can be set in <code>msg.filename</code> or configured in the node properties. If
+    the filename contains a path, only the basename will be used.
+  </p>
+
+  <h3>Status Codes</h3>
+  <ul>
+    <li><strong>201</strong> - Upload successful</li>
+    <li><strong>400</strong> - Bad request (missing file, invalid site ID)</li>
+    <li><strong>401</strong> - Invalid API key</li>
+    <li><strong>403</strong> - API access not enabled for this site</li>
+    <li><strong>404</strong> - Site not found</li>
+    <li><strong>429</strong> - Rate limit exceeded (max 30 uploads/minute)</li>
+    <li><strong>507</strong> - Storage limit exceeded</li>
+  </ul>
+
+  <h3>Example Flow</h3>
+  <pre>
+[File In] → [Process Link Upload] → [Debug]
+
+The File In node reads a file and outputs msg.payload (Buffer)
+and msg.filename. Connect directly to this node to upload.</pre>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://files.processlink.com.au" target="_blank">Process Link Files</a> - Manage
+      your files and API keys
+    </li>
+    <li>
+      <a href="https://github.com/process-link/node-red-contrib-processlink" target="_blank"
+        >GitHub</a
+      >
+      - Source code and issues
+    </li>
+  </ul>
+</script>

package/nodes/files/processlink-files-upload.js

@@ -0,0 +1,172 @@
+/**
+ * Process Link Files Upload Node
+ * Uploads files to Process Link Files API
+ */
+
+module.exports = function (RED) {
+  const https = require("https");
+  const http = require("http");
+
+  function ProcessLinkFilesUploadNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    // Get the config node
+    this.server = RED.nodes.getNode(config.server);
+
+    node.on("input", function (msg, send, done) {
+      // For Node-RED 0.x compatibility
+      send = send || function () { node.send.apply(node, arguments); };
+      done = done || function (err) { if (err) node.error(err, msg); };
+
+      // Validate config
+      if (!node.server) {
+        node.status({ fill: "red", shape: "ring", text: "no config" });
+        done(new Error("No Process Link configuration selected"));
+        return;
+      }
+
+      const siteId = node.server.siteId;
+      const apiKey = node.server.credentials?.apiKey;
+
+      if (!siteId) {
+        node.status({ fill: "red", shape: "ring", text: "no site ID" });
+        done(new Error("Site ID not configured"));
+        return;
+      }
+
+      if (!apiKey) {
+        node.status({ fill: "red", shape: "ring", text: "no API key" });
+        done(new Error("API Key not configured"));
+        return;
+      }
+
+      // Validate payload
+      let fileBuffer;
+      if (Buffer.isBuffer(msg.payload)) {
+        fileBuffer = msg.payload;
+      } else if (typeof msg.payload === "string") {
+        fileBuffer = Buffer.from(msg.payload);
+      } else {
+        node.status({ fill: "red", shape: "ring", text: "invalid payload" });
+        done(new Error("msg.payload must be a Buffer or string"));
+        return;
+      }
+
+      // Get filename
+      const filename = msg.filename || config.filename || "file.bin";
+      const basename = filename.split(/[\\/]/).pop();
+
+      // Build multipart form data
+      const boundary = "----NodeREDProcessLink" + Date.now() + Math.random().toString(36).substring(2);
+
+      const header = Buffer.from(
+        `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="file"; filename="${basename}"\r\n` +
+        `Content-Type: application/octet-stream\r\n\r\n`
+      );
+      const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+      const body = Buffer.concat([header, fileBuffer, footer]);
+
+      // Parse URL
+      const apiUrl = config.apiUrl || "https://files.processlink.com.au/api/upload";
+      const url = new URL(apiUrl);
+      const isHttps = url.protocol === "https:";
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": `multipart/form-data; boundary=${boundary}`,
+          "Content-Length": body.length,
+          "x-site-id": siteId,
+          "x-api-key": apiKey,
+        },
+      };
+
+      node.status({ fill: "yellow", shape: "dot", text: "uploading..." });
+
+      const transport = isHttps ? https : http;
+      const req = transport.request(options, (res) => {
+        let responseData = "";
+
+        res.on("data", (chunk) => {
+          responseData += chunk;
+        });
+
+        res.on("end", () => {
+          let parsedResponse;
+          try {
+            parsedResponse = JSON.parse(responseData);
+          } catch (e) {
+            parsedResponse = { raw: responseData };
+          }
+
+          msg.payload = parsedResponse;
+          msg.statusCode = res.statusCode;
+          msg.headers = res.headers;
+
+          if (res.statusCode === 201 && parsedResponse.ok) {
+            // Success
+            msg.file_id = parsedResponse.file_id;
+            node.status({
+              fill: "green",
+              shape: "dot",
+              text: `uploaded: ${parsedResponse.file_id?.substring(0, 8)}...`,
+            });
+            send(msg);
+            done();
+
+            // Clear status after 5 seconds
+            setTimeout(() => node.status({}), 5000);
+          } else {
+            // API error
+            const errorMsg = parsedResponse.error || parsedResponse.message || `HTTP ${res.statusCode}`;
+            node.status({ fill: "red", shape: "dot", text: errorMsg });
+
+            // Still send the message so users can handle errors in their flow
+            send(msg);
+            done();
+
+            // Clear status after 10 seconds
+            setTimeout(() => node.status({}), 10000);
+          }
+        });
+      });
+
+      req.on("error", (err) => {
+        node.status({ fill: "red", shape: "ring", text: "request failed" });
+        msg.payload = { error: err.message };
+        msg.statusCode = 0;
+        send(msg);
+        done(err);
+
+        setTimeout(() => node.status({}), 10000);
+      });
+
+      // Set timeout
+      const timeout = parseInt(config.timeout) || 30000;
+      req.setTimeout(timeout, () => {
+        req.destroy();
+        node.status({ fill: "red", shape: "ring", text: "timeout" });
+        msg.payload = { error: "Request timed out" };
+        msg.statusCode = 0;
+        send(msg);
+        done(new Error("Request timed out"));
+
+        setTimeout(() => node.status({}), 10000);
+      });
+
+      req.write(body);
+      req.end();
+    });
+
+    node.on("close", function () {
+      node.status({});
+    });
+  }
+
+  RED.nodes.registerType("processlink-files-upload", ProcessLinkFilesUploadNode);
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@processlink/node-red-contrib-processlink",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "Node-RED nodes for Process Link platform integration",
+  "keywords": [
+    "node-red",
+    "processlink",
+    "process-link",
+    "files",
+    "upload",
+    "api",
+    "industrial",
+    "iot",
+    "automation"
+  ],
+  "node-red": {
+    "version": ">=2.0.0",
+    "nodes": {
+      "processlink-config": "nodes/config/processlink-config.js",
+      "processlink-files-upload": "nodes/files/processlink-files-upload.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "author": "Process Link <support@processlink.com.au>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/process-link/node-red-contrib-processlink.git"
+  },
+  "bugs": {
+    "url": "https://github.com/process-link/node-red-contrib-processlink/issues"
+  },
+  "homepage": "https://github.com/process-link/node-red-contrib-processlink#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}