node-red-contrib-vectorprime 0.1.9 → 0.1.11

package/README.md

@@ -1,68 +1,45 @@
 # node-red-contrib-vectorprime
 
-Official VectorPrime Decision Kernel node for Node-RED.
+**VectorPrime Rank** — automatically rank tasks, alerts, or decisions using the VectorPrime Decision Kernel.
 
-This node sends a decision request to VectorPrime and returns a ranked result.
+This node helps you pick the **best next action** when you have multiple choices and need to choose the optimal one fast.
 
----
-
-## ✅ What this node does
-
-- **Input:** `msg.payload` (your decision request JSON)
-- **Output:** `msg.payload` (VectorPrime response JSON)
+✅ Prioritize tasks  
+✅ Rank alerts by urgency  
+✅ Choose the best option from multiple choices  
+✅ Turn “too many choices” into a single clear answer  
+✅ Works inside Node-RED flows with 1 click
 
 ---
 
-## ✅ Quick Start
+## What it does (in 1 sentence)
 
-### Endpoint
-
-`/v1/kernel/rank`
+**Send a list of options → get them ranked best-to-worst with a recommended top choice.**
 
 ---
 
-## ✅ How to use in Node-RED
-
-### 1) Drag these nodes into your flow:
+## Why developers install this
 
-- **Inject**
-- **VectorPrime**
-- **Debug**
+Most automation flows break down when you have **multiple possible actions** and don’t know which one to run.
 
-### 2) Connect them like this:
+VectorPrime solves that by turning this:
 
-Inject → VectorPrime → Debug
+- “Which alert should fire first?”
+- “Which ticket should I do next?”
+- “Which customer should get priority?”
+- “Which action gives the best outcome with least risk?”
+- “Which fix should I deploy first?”
 
-### 3) Configure the VectorPrime node
+Into:
 
-Double-click the **VectorPrime** node, then:
-
-✅ Paste your VectorPrime API key into the node field  
-(or use the **Get Free Key** button if enabled)
-
-### 4) Run it
-
-1. Click **Deploy**
-2. Press the **Inject** button
-3. View output in the **Debug** sidebar
+✅ **One ranked result** (best option on top)
 
 ---
 
-## ✅ Example Inject Payload
-
-### IMPORTANT:
-Your Inject node must send a JSON object inside `msg.payload`.
+## Quick Start (60 seconds)
 
-Set your Inject node payload type to **JSON** and paste this:
+### ✅ 1) Install the node
+In your Node-RED user directory (usually `C:\Users\mxz\.node-red`):
 
-```json
-{
-  "decision_id": "node-red-demo-001",
-  "prompt": "Pick one.",
-  "options": [
-    { "id": "a", "label": "Option A" },
-    { "id": "b", "label": "Option B" }
-  ],
-  "engine": "classical",
-  "seed": 123
-}
+```bash
+npm install node-red-contrib-vectorprime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-vectorprime",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "VectorPrime Decision Kernel node for Node-RED",
   "main": "vectorprime.js",
   "license": "MIT",

package/vectorprime.html

@@ -1,4 +1,7 @@
-<script type="text/html" data-template-name="vectorprime-config">
+<!-- =========================
+   VectorPrime Config Template
+========================= -->
+<script type="text/x-red" data-template-name="vectorprime-config">
   <div class="form-row">
     <label for="node-config-input-baseUrl">
       <i class="fa fa-globe"></i> Base URL
@@ -105,7 +108,7 @@
 </script>
 
 <!-- ✅ HELP TAB: vectorprime-config -->
-<script type="text/html" data-help-name="vectorprime-config">
+<script type="text/x-red" data-help-name="vectorprime-config">
   <p><b>VectorPrime Config</b> stores your Base URL and API key securely.</p>
 
   <h3>Quick Setup</h3>
@@ -130,7 +133,10 @@
 
 <hr />
 
-<script type="text/html" data-template-name="vectorprime-rank">
+<!-- =========================
+   VectorPrime Rank Template
+========================= -->
+<script type="text/x-red" data-template-name="vectorprime-rank">
   <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="Rank Decision (VectorPrime)">
@@ -169,9 +175,6 @@
     // ✅ This is the name users see in the palette
     paletteLabel: "Rank Decision (VectorPrime)",
 
-    // ✅ This is the short description used in the tooltip card
-    description: "Automatically ranks tasks, alerts, or choices in msg.payload so your flow can pick the best next action.",
-
     label: function () {
       return this.name || "Rank Decision (VectorPrime)";
     }
@@ -179,29 +182,29 @@
 </script>
 
 <!-- ✅ HELP TAB: vectorprime-rank -->
-<script type="text/html" data-help-name="vectorprime-rank">
+<script type="text/x-red" data-help-name="vectorprime-rank">
   <p>
-    <b>Rank Decision (VectorPrime)</b> sorts your options and returns the best next action.
-    Use it anywhere you need <b>priority scoring</b> or <b>decision ranking</b> inside a flow.
+    <b>Rank Decision (VectorPrime)</b> picks the best next action automatically.
+    Use it anywhere your flow needs <b>priority scoring</b> or <b>decision ranking</b>.
   </p>
 
   <h3>What it does</h3>
   <ul>
-    <li>Reads input from <code>msg.payload</code></li>
-    <li>Calls VectorPrime Rank API</li>
-    <li>Returns the ranked decision in <code>msg.payload</code></li>
+    <li>Reads options from <code>msg.payload</code></li>
+    <li>Calls the VectorPrime Decision Kernel Rank API</li>
+    <li>Returns the ranked decision inside <code>msg.payload</code></li>
   </ul>
 
-  <h3>Best use cases</h3>
+  <h3>Where developers use this most</h3>
   <ul>
-    <li><b>Incident response:</b> rank alerts by urgency</li>
-    <li><b>Task automation:</b> choose the best next action automatically</li>
-    <li><b>Ops + IoT:</b> prioritize device events and maintenance actions</li>
-    <li><b>Workflows:</b> sort leads, tickets, jobs, or notifications</li>
+    <li><b>Incident response:</b> rank alerts → fix the most critical first</li>
+    <li><b>Automation flows:</b> choose the best next action from multiple tasks</li>
+    <li><b>Ops / IoT:</b> prioritize device events + maintenance decisions</li>
+    <li><b>Ticketing & work queues:</b> rank jobs, leads, or support tickets</li>
   </ul>
 
-  <h3>Input format (example)</h3>
-  <p>Send a list of options to rank inside <code>msg.payload</code>:</p>
+  <h3>Input format (simple)</h3>
+  <p>Send a list to rank inside <code>msg.payload.items</code>:</p>
 
   <pre><code>{
   "items": [
@@ -211,17 +214,14 @@
   ]
 }</code></pre>
 
-  <h3>Output</h3>
   <p>
-    The response is returned in <code>msg.payload</code> (ranked order + decision result).
-    If your free tier limit is reached, the node may return an <b>upgrade URL</b>.
+    ✅ The node automatically converts <code>items</code> into the backend format
+    (<code>decision_id</code>, <code>prompt</code>, <code>options</code>) so flows stay easy.
   </p>
 
   <h3>1-Click Example Flow (Import This)</h3>
   <p>
-    Copy the JSON below, then go to:
-    <br/>
-    <b>Node-RED Menu → Import → Clipboard → Paste → Import</b>
+    Copy the JSON below → Node-RED Menu → Import → Clipboard → Paste → Import
   </p>
 
   <pre><code>[
@@ -237,11 +237,7 @@
     "type": "inject",
     "z": "a111111111111111",
     "name": "Run VectorPrime Rank (1-click)",
-    "props": [
-      {
-        "p": "payload"
-      }
-    ],
+    "props": [{ "p": "payload" }],
     "payload": "{\"items\":[{\"id\":\"fix-prod-bug\",\"label\":\"Fix production bug\",\"urgency\":10,\"impact\":10},{\"id\":\"ship-feature\",\"label\":\"Ship new feature\",\"urgency\":7,\"impact\":8},{\"id\":\"refactor\",\"label\":\"Refactor module\",\"urgency\":3,\"impact\":5}]}",
     "payloadType": "json",
     "repeat": "",
@@ -249,13 +245,9 @@
     "once": false,
     "onceDelay": 0.1,
     "topic": "",
-    "x": 220,
+    "x": 230,
     "y": 160,
-    "wires": [
-      [
-        "c111111111111111"
-      ]
-    ]
+    "wires": [["c111111111111111"]]
   },
   {
     "id": "c111111111111111",
@@ -264,13 +256,9 @@
     "name": "VectorPrime Rank",
     "config": "d111111111111111",
     "endpoint": "/v1/kernel/rank",
-    "x": 460,
+    "x": 470,
     "y": 160,
-    "wires": [
-      [
-        "e111111111111111"
-      ]
-    ]
+    "wires": [["e111111111111111"]]
   },
   {
     "id": "e111111111111111",
@@ -283,8 +271,6 @@
     "tostatus": false,
     "complete": "payload",
     "targetType": "msg",
-    "statusVal": "",
-    "statusType": "auto",
     "x": 700,
     "y": 160,
     "wires": []
@@ -296,10 +282,4 @@
     "baseUrl": "https://vectorprime-kernel-backend.onrender.com"
   }
 ]</code></pre>
-
-  <h3>Advanced tip: override Authorization</h3>
-  <p>
-    If you set <code>msg.headers.Authorization</code> before this node runs, it will use your header instead
-    of the stored key.
-  </p>
 </script>

package/vectorprime.js

@@ -1,7 +1,11 @@
 module.exports = function (RED) {
-    // ✅ Works with node-fetch v2 or v3
-    const fetch = (...args) =>
-        import("node-fetch").then((mod) => (mod.default ? mod.default(...args) : mod(...args)));
+    "use strict";
+
+    // ✅ Node 22 has global fetch, but keep fallback for safety
+    const fetchFn =
+        typeof fetch === "function"
+            ? fetch
+            : (...args) => import("node-fetch").then(({ default: f }) => f(...args));
 
     function normalizeBaseUrl(url) {
         url = (url || "").trim();
@@ -12,27 +16,30 @@ module.exports = function (RED) {
 
     function normalizeEndpoint(path) {
         path = (path || "").trim();
-        if (!path) return "/v1/kernel/rank";
         if (!path.startsWith("/")) path = "/" + path;
         return path;
     }
 
-    // ✅ REQUIRED: runtime config node registration
+    // -----------------------------
+    // Config Node (stores Base URL + API Key)
+    // -----------------------------
     function VectorPrimeConfigNode(n) {
         RED.nodes.createNode(this, n);
 
-        // baseUrl stored in node settings (non-credential)
-        this.baseUrl = n.baseUrl || "https://vectorprime-kernel-backend.onrender.com";
+        this.baseUrl =
+            (n.baseUrl && String(n.baseUrl).trim()) ||
+            "https://vectorprime-kernel-backend.onrender.com";
     }
 
-    // ✅ IMPORTANT: credentials must be declared here too
     RED.nodes.registerType("vectorprime-config", VectorPrimeConfigNode, {
         credentials: {
             apiKey: { type: "password" },
         },
     });
 
-    // ✅ Main node
+    // -----------------------------
+    // Rank Node (calls VectorPrime backend)
+    // -----------------------------
     function VectorPrimeRankNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
@@ -40,19 +47,17 @@ module.exports = function (RED) {
         node.name = config.name;
         node.endpoint = config.endpoint || "/v1/kernel/rank";
 
+        const cfg = RED.nodes.getNode(config.config);
+
         node.on("input", async function (msg, send, done) {
             send = send || function () { node.send.apply(node, arguments); };
 
             try {
-                const cfg = RED.nodes.getNode(config.config);
                 if (!cfg) {
                     node.status({ fill: "red", shape: "ring", text: "missing config" });
-                    msg.payload = {
-                        error: "VectorPrime config missing. Open node settings and set Config.",
-                    };
-                    send(msg);
-                    if (done) done();
-                    return;
+                    throw new Error(
+                        "VectorPrime config missing. Open node settings and select/create a Config."
+                    );
                 }
 
                 const baseUrl = normalizeBaseUrl(cfg.baseUrl);
@@ -60,94 +65,82 @@ module.exports = function (RED) {
 
                 if (!baseUrl.startsWith("http")) {
                     node.status({ fill: "red", shape: "ring", text: "invalid base url" });
-                    msg.payload = { error: `Base URL missing/invalid: ${baseUrl}` };
-                    send(msg);
-                    if (done) done();
-                    return;
+                    throw new Error(`Base URL missing/invalid: ${baseUrl}`);
                 }
 
-                // ✅ Ensure headers object exists
-                msg.headers = msg.headers || {};
-
-                // ✅ Allow incoming Authorization override (advanced users)
-                const incomingAuth =
-                    msg.headers.authorization ||
-                    msg.headers.Authorization ||
-                    "";
-
                 const storedKey =
                     cfg.credentials && cfg.credentials.apiKey
                         ? String(cfg.credentials.apiKey).trim()
                         : "";
 
-                // ✅ If user didn't provide Authorization, use stored key from config credentials
-                if (!incomingAuth) {
-                    if (!storedKey) {
-                        node.status({ fill: "red", shape: "ring", text: "missing api key" });
-                        msg.payload = {
-                            error: "No API key. Open VectorPrime Config and click 'Get Free Key'.",
-                        };
-                        send(msg);
-                        if (done) done();
-                        return;
-                    }
-                    msg.headers.Authorization = `Bearer ${storedKey}`;
+                if (!storedKey) {
+                    node.status({ fill: "red", shape: "ring", text: "missing api key" });
+                    throw new Error(
+                        "No API key. Open VectorPrime Config and click 'Get Free Key' or paste your paid key."
+                    );
                 }
 
-                // ✅ Force JSON
-                msg.headers["Content-Type"] = "application/json";
+                // -----------------------------
+                // ✅ AUTO-CONVERT ITEMS → OPTIONS (YOUR REQUIRED FIX)
+                // Backend expects: decision_id, prompt, options
+                // Users send: {items:[...]}
+                // -----------------------------
+                let payload = msg.payload || {};
+
+                if (payload && typeof payload === "object" && Array.isArray(payload.items) && !payload.options) {
+                    const decision_id = payload.decision_id || `node-red-${Date.now()}`;
+                    const prompt = payload.prompt || "Rank the best next action from these options.";
+
+                    const options = payload.items.map((it, idx) => ({
+                        id: it.id || `opt-${idx + 1}`,
+                        label: it.label || it.title || it.id || `Option ${idx + 1}`,
+                        urgency: it.urgency,
+                        impact: it.impact,
+                        effort: it.effort,
+                    }));
+
+                    payload = { decision_id, prompt, options };
+                }
 
-                const payload = msg.payload || {};
+                // Validate final expected shape
+                if (!payload.decision_id || !payload.prompt || !payload.options) {
+                    node.status({ fill: "red", shape: "ring", text: "bad payload" });
+                    throw new Error(
+                        "Invalid payload. Provide { items:[...] } or full { decision_id, prompt, options }."
+                    );
+                }
 
                 node.status({ fill: "blue", shape: "dot", text: "ranking..." });
 
-                const resp = await fetch(`${baseUrl}${endpoint}`, {
+                const resp = await fetchFn(`${baseUrl}${endpoint}`, {
                     method: "POST",
-                    headers: msg.headers,
+                    headers: {
+                        "Authorization": `Bearer ${storedKey}`,
+                        "Content-Type": "application/json",
+                    },
                     body: JSON.stringify(payload),
                 });
 
                 const text = await resp.text();
                 let data;
-                try {
-                    data = JSON.parse(text);
-                } catch {
-                    data = { raw: text };
-                }
+                try { data = JSON.parse(text); } catch { data = { raw: text }; }
 
-                // ✅ Free tier limit hit → return upgrade url inside Node-RED
                 if (!resp.ok) {
-                    const upgradeUrl = data.upgrade_url || data.checkout_url || null;
-
-                    if (resp.status === 402 && upgradeUrl) {
-                        node.status({
-                            fill: "yellow",
-                            shape: "ring",
-                            text: "limit reached → upgrade",
-                        });
-                        msg.payload = data;
-                        msg.vectorprime = { upgrade_url: upgradeUrl };
-                        send(msg);
-                        if (done) done();
-                        return;
-                    }
-
                     node.status({ fill: "red", shape: "ring", text: `error ${resp.status}` });
-                    msg.payload = data;
-                    send(msg);
-                    if (done) done();
-                    return;
+                    throw new Error(`VectorPrime API ${resp.status}: ${JSON.stringify(data)}`);
                 }
 
                 node.status({ fill: "green", shape: "dot", text: "ok" });
+
+                // ✅ Replace payload with ranked result
                 msg.payload = data;
+
                 send(msg);
-                if (done) done();
+                done();
             } catch (err) {
                 node.status({ fill: "red", shape: "ring", text: "failed" });
-                msg.payload = { error: err.message || String(err) };
-                send(msg);
-                if (done) done(err);
+                node.error(err, msg);
+                done(err);
             }
         });
     }