@processlink/node-red-contrib-processlink 1.1.1 → 1.2.1

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd folder/area support to upload API\n\n- Add areaId and folderId params to /api/upload endpoint\n- Add API key auth to /api/sites/[siteId]/folders endpoint\n- Add new /api/sites/[siteId]/areas endpoint with API key auth\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd location selector for file uploads \\(v1.2.0\\)\n\n- Add Location dropdown showing Area > Folder hierarchy\n- Fetch areas and folders from Files API with API key auth\n- Send areaId and folderId in upload requests\n- Update README documentation\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md - AI Assistant Guidelines
+
+## Critical: This is a Published NPM Package
+
+This package (`@processlink/node-red-contrib-processlink`) is **published to NPM** and used by real customers in production Node-RED environments. Changes here can break many people's workflows.
+
+### Before Making Any Changes
+
+1. **Understand the impact** - Changes affect all users who update the package
+2. **Backwards compatibility** - Existing node configurations must continue to work
+3. **Test thoroughly** - Test in a real Node-RED instance before publishing
+4. **Version carefully** - Follow semver (patch for fixes, minor for features, major for breaking changes)
+
+### Publishing Checklist
+
+Before running `npm publish`:
+- [ ] Test all nodes in Node-RED editor (deploy, configure, run)
+- [ ] Verify existing flows still work after update
+- [ ] Check browser console for JavaScript errors
+- [ ] Test error handling paths
+- [ ] Update version in package.json appropriately
+- [ ] Document changes in commit message
+
+## Architecture Notes
+
+### Node-RED Security Model
+
+**Important**: Credentials (API keys, passwords) are stored server-side only and are NEVER accessible from the browser/editor HTML code.
+
+- `node.credentials.apiKey` - Only accessible in `.js` files (server-side)
+- `configNode.credentials` - Always `undefined` in `.html` files (client-side)
+
+To access credentials from the editor, create an admin HTTP endpoint:
+```javascript
+// In the .js file
+RED.httpAdmin.get("/your-endpoint/:id", function(req, res) {
+  const node = RED.nodes.getNode(req.params.id);
+  const apiKey = node.credentials?.apiKey; // Access credentials here
+  // Make API calls server-side, return results to client
+});
+```
+
+### File Structure
+
+```
+nodes/
+  config/
+    processlink-config.js    # Shared credentials config node
+    processlink-config.html
+  files/
+    processlink-files-upload.js   # File upload node
+    processlink-files-upload.html
+  system/
+    processlink-system-info.js    # System info node
+    processlink-system-info.html
+```
+
+### Node-RED Conventions
+
+- Dual outputs: First output for success, second for errors
+- Status indicators: green=success, yellow=processing, red=error
+- Config nodes: Store shared credentials, referenced by other nodes
+- Always use `send` and `done` callbacks for proper async handling

package/README.md

@@ -71,35 +71,44 @@ Then restart Node-RED.
 ### 3. Connect Your Flow
 
 ```
-[File In] → [files upload] ─┬─ Output 1 (success) → [Debug]
-                            └─ Output 2 (error)   → [Debug]
+[Inject] → [File In] → [files upload] ─┬─ Output 1 (success) → [Debug]
+                                       └─ Output 2 (error)   → [Debug]
 ```
 
 ---
 
 ## Node Reference
 
-### Files Upload
+---
+
+## Files Upload
 
 Uploads files to the Process Link Files API.
 
-#### Configuration
+### Configuration
 
 | Property | Description |
 |----------|-------------|
 | Config | Your Process Link credentials (Site ID + API Key) |
-| Filename | Default filename (optional, can be set via `msg.filename`) |
-| Prefix with timestamp | Adds `YYYY-MM-DD_HH-MM-SS_` prefix to filename |
+| Filename | Filename for uploaded file (takes priority over `msg.filename`) |
+| Location | Destination area/folder in the Files app (default: site root) |
+| Prefix with timestamp | Adds `YYYY-MM-DD_HH-mm-ss_` prefix to filename (ISO 8601 format) |
 | Timeout | Request timeout in milliseconds (default: 30000) |
 
-#### Inputs
+**Filename priority:** Config filename → `msg.filename` → `file.bin`
+
+**Location:** The dropdown shows your site's folder structure organized by area. Select where uploaded files should be stored. Areas and folders are fetched from the Files API when you open the node configuration.
+
+**Timestamp prefix:** When enabled, always prepends the current date/time to the filename, regardless of whether it came from config or `msg.filename`.
+
+### Inputs
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `msg.payload` | Buffer \| string | The file content to upload |
-| `msg.filename` | string | *(Optional)* Filename to use |
+| `msg.filename` | string | *(Optional)* Fallback filename if not set in config |
 
-#### Outputs
+### Outputs
 
 This node has **two outputs**:
 
@@ -108,15 +117,15 @@ This node has **two outputs**:
 | **1 - Success** | HTTP 201 | `msg.payload.ok`, `msg.payload.file_id`, `msg.file_id`, `msg.statusCode` |
 | **2 - Error** | API error, network error, timeout | `msg.payload.error`, `msg.statusCode` |
 
-#### Status Indicators
+### Status Indicators
 
 | Color | Meaning |
 |-------|---------|
+| 🔴 Red | Error occurred |
 | 🟡 Yellow | Uploading in progress |
 | 🟢 Green | Upload successful |
-| 🔴 Red | Error occurred |
 
-#### Status Codes
+### Status Codes
 
 | Code | Meaning |
 |------|---------|
@@ -130,22 +139,22 @@ This node has **two outputs**:
 
 ---
 
-### System Info
+## System Info
 
 Outputs system information for diagnostics and monitoring.
 
-#### Configuration
+### Configuration
 
 | Property | Description |
 |----------|-------------|
 | Send on deploy | When checked (default), outputs system info when the flow is deployed |
 
-#### Triggers
+### Triggers
 
 - **On deploy** (if enabled) - Automatically sends when flow starts
 - **On input** - Any incoming message triggers a fresh reading
 
-#### Output
+### Output
 
 `msg.payload` contains:
 
@@ -169,7 +178,7 @@ Outputs system information for diagnostics and monitoring.
 | `nodejs` | version |
 | `processMemory` | rss, heapTotal, heapUsed |
 
-#### Uptime/Memory Structure
+### Uptime/Memory Structure
 
 ```json
 {
@@ -293,7 +302,6 @@ Copy the JSON below and import into Node-RED: **Menu → Import → Clipboard**
 
 ## Support
 
-- 📖 **Documentation**: [GitHub Wiki](https://github.com/process-link/node-red-contrib-processlink/wiki)
 - 🐛 **Issues**: [GitHub Issues](https://github.com/process-link/node-red-contrib-processlink/issues)
 - 📧 **Email**: support@processlink.com.au
 - 🌐 **Website**: [processlink.com.au](https://processlink.com.au)

package/nodes/config/processlink-config.js

@@ -4,6 +4,8 @@
  */
 
 module.exports = function (RED) {
+  const https = require("https");
+
   function ProcessLinkConfigNode(config) {
     RED.nodes.createNode(this, config);
     this.name = config.name;
@@ -16,4 +18,95 @@ module.exports = function (RED) {
       apiKey: { type: "password" },
     },
   });
+
+  // Admin endpoint to fetch locations (areas and folders) for a config node
+  RED.httpAdmin.get("/processlink/locations/:id", function (req, res) {
+    const configNode = RED.nodes.getNode(req.params.id);
+    if (!configNode) {
+      return res.status(404).json({ error: "Config node not found" });
+    }
+
+    const siteId = configNode.siteId;
+    const apiKey = configNode.credentials?.apiKey;
+
+    if (!siteId || !apiKey) {
+      return res.status(400).json({ error: "Config not ready" });
+    }
+
+    const baseUrl = `/api/sites/${siteId}`;
+    const headers = {
+      Authorization: `Bearer ${apiKey}`,
+    };
+
+    // Fetch both areas and folders
+    let areasData = [];
+    let foldersData = [];
+    let completed = 0;
+    let hasError = false;
+
+    function checkComplete() {
+      completed++;
+      if (completed === 2 && !hasError) {
+        res.json({ areas: areasData, folders: foldersData });
+      }
+    }
+
+    // Fetch areas
+    const areasReq = https.request(
+      {
+        hostname: "files.processlink.com.au",
+        path: `${baseUrl}/areas`,
+        method: "GET",
+        headers: headers,
+      },
+      (areasRes) => {
+        let data = "";
+        areasRes.on("data", (chunk) => (data += chunk));
+        areasRes.on("end", () => {
+          try {
+            areasData = JSON.parse(data);
+          } catch (e) {
+            areasData = [];
+          }
+          checkComplete();
+        });
+      }
+    );
+    areasReq.on("error", () => {
+      if (!hasError) {
+        hasError = true;
+        res.status(500).json({ error: "Failed to fetch areas" });
+      }
+    });
+    areasReq.end();
+
+    // Fetch folders
+    const foldersReq = https.request(
+      {
+        hostname: "files.processlink.com.au",
+        path: `${baseUrl}/folders`,
+        method: "GET",
+        headers: headers,
+      },
+      (foldersRes) => {
+        let data = "";
+        foldersRes.on("data", (chunk) => (data += chunk));
+        foldersRes.on("end", () => {
+          try {
+            foldersData = JSON.parse(data);
+          } catch (e) {
+            foldersData = [];
+          }
+          checkComplete();
+        });
+      }
+    );
+    foldersReq.on("error", () => {
+      if (!hasError) {
+        hasError = true;
+        res.status(500).json({ error: "Failed to fetch folders" });
+      }
+    });
+    foldersReq.end();
+  });
 };

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

@@ -6,6 +6,8 @@
       name: { value: "" },
       server: { value: "", type: "processlink-config", required: true },
       filename: { value: "" },
+      areaId: { value: "" },
+      folderId: { value: "" },
       timestampPrefix: { value: false },
       timeout: { value: "30000" },
       apiUrl: { value: "https://files.processlink.com.au/api/upload" },
@@ -22,6 +24,129 @@
     },
     inputLabels: "file buffer",
     outputLabels: ["success", "error"],
+    oneditprepare: function () {
+      var node = this;
+      var $location = $("#node-input-location");
+      var $areaId = $("#node-input-areaId");
+      var $folderId = $("#node-input-folderId");
+      var $server = $("#node-input-server");
+
+      function loadLocations() {
+        var configId = $server.val();
+        if (!configId) {
+          $location.html('<option value="">-- Select config first --</option>');
+          return;
+        }
+
+        var configNode = RED.nodes.node(configId);
+        if (!configNode || !configNode.siteId) {
+          $location.html('<option value="">-- Config not ready --</option>');
+          return;
+        }
+
+        $location.html('<option value="">Loading...</option>');
+
+        // Fetch locations via server-side endpoint (credentials are not accessible client-side)
+        $.ajax({
+          url: "processlink/locations/" + configId,
+          method: "GET",
+        }).done(function (result) {
+          var areas = result.areas || [];
+          var folders = result.folders || [];
+
+          // Build current selection key for matching
+          var currentAreaId = node.areaId || "";
+          var currentFolderId = node.folderId || "";
+          var currentKey = currentAreaId + "|" + currentFolderId;
+
+          var options = '<option value="|" data-area="" data-folder="">Site root (default)</option>';
+
+          // Group folders by area
+          var foldersByArea = {};
+          folders.forEach(function (f) {
+            var areaKey = f.area_id || "";
+            if (!foldersByArea[areaKey]) foldersByArea[areaKey] = [];
+            foldersByArea[areaKey].push(f);
+          });
+
+          // Add areas with their folders
+          areas.forEach(function (area) {
+            var areaFolders = foldersByArea[area.id] || [];
+            options += '<optgroup label="' + area.area_name + '">';
+
+            // Area root option
+            var areaRootKey = area.id + "|";
+            var areaRootSelected = areaRootKey === currentKey ? ' selected' : '';
+            options += '<option value="' + areaRootKey + '" data-area="' + area.id + '" data-folder=""' + areaRootSelected + '>' + area.area_name + ' (root)</option>';
+
+            // Root folders in this area
+            var rootFolders = areaFolders.filter(function (f) { return !f.parent_id; });
+            rootFolders.sort(function (a, b) { return a.name.localeCompare(b.name); });
+
+            rootFolders.forEach(function (folder) {
+              var folderKey = area.id + "|" + folder.id;
+              var selected = folderKey === currentKey ? ' selected' : '';
+              options += '<option value="' + folderKey + '" data-area="' + area.id + '" data-folder="' + folder.id + '"' + selected + '>&nbsp;&nbsp;' + folder.name + '</option>';
+
+              // Child folders
+              var children = areaFolders.filter(function (c) { return c.parent_id === folder.id; });
+              children.sort(function (a, b) { return a.name.localeCompare(b.name); });
+              children.forEach(function (child) {
+                var childKey = area.id + "|" + child.id;
+                var childSelected = childKey === currentKey ? ' selected' : '';
+                options += '<option value="' + childKey + '" data-area="' + area.id + '" data-folder="' + child.id + '"' + childSelected + '>&nbsp;&nbsp;&nbsp;&nbsp;' + child.name + '</option>';
+              });
+            });
+
+            options += '</optgroup>';
+          });
+
+          // Add folders without an area
+          var noAreaFolders = foldersByArea[""] || [];
+          if (noAreaFolders.length > 0) {
+            options += '<optgroup label="No Area">';
+            var rootFolders = noAreaFolders.filter(function (f) { return !f.parent_id; });
+            rootFolders.sort(function (a, b) { return a.name.localeCompare(b.name); });
+
+            rootFolders.forEach(function (folder) {
+              var folderKey = "|" + folder.id;
+              var selected = folderKey === currentKey ? ' selected' : '';
+              options += '<option value="' + folderKey + '" data-area="" data-folder="' + folder.id + '"' + selected + '>' + folder.name + '</option>';
+
+              var children = noAreaFolders.filter(function (c) { return c.parent_id === folder.id; });
+              children.sort(function (a, b) { return a.name.localeCompare(b.name); });
+              children.forEach(function (child) {
+                var childKey = "|" + child.id;
+                var childSelected = childKey === currentKey ? ' selected' : '';
+                options += '<option value="' + childKey + '" data-area="" data-folder="' + child.id + '"' + childSelected + '>&nbsp;&nbsp;' + child.name + '</option>';
+              });
+            });
+            options += '</optgroup>';
+          }
+
+          $location.html(options);
+        }).fail(function (xhr) {
+          console.error("Failed to load locations:", xhr.responseText);
+          // Still allow site root if API fails
+          $location.html('<option value="|">Site root (default)</option><option disabled>-- Failed to load locations --</option>');
+        });
+      }
+
+      // Update hidden inputs when selection changes
+      $location.on("change", function () {
+        var $selected = $location.find(":selected");
+        $areaId.val($selected.data("area") || "");
+        $folderId.val($selected.data("folder") || "");
+      });
+
+      // Load locations when config changes
+      $server.on("change", function () {
+        loadLocations();
+      });
+
+      // Initial load
+      loadLocations();
+    },
   });
 </script>
 
@@ -38,10 +163,18 @@
     <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-location"><i class="fa fa-folder"></i> Location</label>
+    <select id="node-input-location" style="width: 70%">
+      <option value="|">Site root (default)</option>
+    </select>
+    <input type="hidden" id="node-input-areaId" />
+    <input type="hidden" id="node-input-folderId" />
+  </div>
   <div class="form-row">
     <label for="node-input-timestampPrefix">&nbsp;</label>
     <input type="checkbox" id="node-input-timestampPrefix" style="width: auto; margin-right: 10px;">
-    <span>Prefix filename with timestamp (YYYY-MM-DD_HH-MM-SS_)</span>
+    <span>Prefix filename with timestamp (YYYY-MM-DD_HH-mm-ss_)</span>
   </div>
   <div class="form-row">
     <label for="node-input-timeout"><i class="fa fa-clock-o"></i> Timeout</label>
@@ -62,7 +195,7 @@
     <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>Filename for the upload. Can be set via <code>msg.filename</code> or in the node config. Defaults to "file.bin".</dd>
+    <dd>Fallback filename if not set in config. Priority: config → <code>msg.filename</code> → "file.bin".</dd>
   </dl>
 
   <h3>Outputs</h3>
@@ -95,9 +228,11 @@
   <h3>Configuration</h3>
   <dl class="message-properties">
     <dt>Filename <span class="property-type">string</span></dt>
-    <dd>Default filename if <code>msg.filename</code> is not set.</dd>
+    <dd>Filename for uploaded file. Takes priority over <code>msg.filename</code>.</dd>
+    <dt>Location <span class="property-type">select</span></dt>
+    <dd>Destination area/folder in the Files app. Default: site root.</dd>
     <dt>Prefix with timestamp <span class="property-type">boolean</span></dt>
-    <dd>Adds <code>YYYY-MM-DD_HH-MM-SS_</code> prefix to filename.</dd>
+    <dd>Adds <code>YYYY-MM-DD_HH-mm-ss_</code> prefix (ISO 8601). Applied regardless of filename source.</dd>
     <dt>Timeout <span class="property-type">number</span></dt>
     <dd>Request timeout in ms. Default: 30000.</dd>
   </dl>

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

@@ -53,8 +53,8 @@ module.exports = function (RED) {
         return;
       }
 
-      // Get filename
-      const filename = msg.filename || config.filename || "file.bin";
+      // Get filename (config takes priority over msg.filename)
+      const filename = config.filename || msg.filename || "file.bin";
       let basename = filename.split(/[\\/]/).pop();
 
       // Add timestamp prefix if enabled
@@ -71,14 +71,38 @@ module.exports = function (RED) {
 
       // Build multipart form data
       const boundary = "----NodeREDProcessLink" + Date.now() + Math.random().toString(36).substring(2);
+      const parts = [];
 
-      const header = Buffer.from(
+      // Add file part
+      parts.push(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]);
+      ));
+      parts.push(fileBuffer);
+
+      // Add areaId if specified
+      if (config.areaId) {
+        parts.push(Buffer.from(
+          `\r\n--${boundary}\r\n` +
+          `Content-Disposition: form-data; name="areaId"\r\n\r\n` +
+          config.areaId
+        ));
+      }
+
+      // Add folderId if specified
+      if (config.folderId) {
+        parts.push(Buffer.from(
+          `\r\n--${boundary}\r\n` +
+          `Content-Disposition: form-data; name="folderId"\r\n\r\n` +
+          config.folderId
+        ));
+      }
+
+      // Add closing boundary
+      parts.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+
+      const body = Buffer.concat(parts);
 
       // Parse URL
       const apiUrl = config.apiUrl || "https://files.processlink.com.au/api/upload";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Node-RED nodes for Process Link platform integration - upload files, send notifications, and connect to industrial automation systems",
   "keywords": [
     "node-red",