node-red-contrib-whatsapp-api 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+UNLICENSED
+
+All rights reserved.
+
+This package is not licensed for public reuse, modification, or redistribution
+unless the copyright holder grants permission separately.

package/README.md

@@ -0,0 +1,267 @@
+# node-red-contrib-whatsapp-api
+
+Node-RED nodes for driving a WhatsApp Web session with [Baileys](https://github.com/WhiskeySockets/Baileys).
+
+## What it includes
+
+- `whatsapp-api-config`: stores reconnect settings and the local runtime data directory
+- `whatsapp-api-in`: emits normalized incoming WhatsApp messages
+- `whatsapp-api-send`: sends text or media to a chat
+- `whatsapp-api-history`: reads recent messages from the local persisted store
+
+## Runtime requirements
+
+- Node.js 20+
+- Node-RED 4+
+- A phone that can scan the WhatsApp Web QR code
+
+## Install locally
+
+```bash
+npm install
+npm run build
+cd ~/.node-red
+npm install /absolute/path/to/node-red-contrib-whatsapp-api-0.1.0.tgz
+```
+
+Then restart Node-RED and add the `whatsapp-api` nodes from the palette.
+
+The packed module ships as a bundled runtime, so target installs do not need to rebuild or reshuffle the Baileys dependency tree on the Node-RED host.
+
+## Install from npm
+
+After the package has been published:
+
+```bash
+cd ~/.node-red
+npm install node-red-contrib-whatsapp-api
+```
+
+## Login flow
+
+This palette uses a deploy-first QR flow.
+
+1. Add a `whatsapp-api-config` node and deploy the flow.
+2. Open the config node again in the editor.
+3. Click `Connect`.
+4. Scan the QR code with WhatsApp on your phone.
+5. Wait for the status to show `Connected`.
+
+The runtime keeps its auth state on disk and now attempts to reuse it automatically after every Node-RED restart. Use `Disconnect` to clear the stored session and force a fresh QR login.
+
+## Local message history
+
+`whatsapp-api-history` reads from a local JSON store that is updated by the connected runtime. It returns messages the session has already synced or seen. It is not a server-side fetch of arbitrary WhatsApp chat history.
+
+The history node can also return only the newest incoming messages that the linked WhatsApp account still has unread for the selected chat.
+
+## Example Node-RED flow
+
+Import this JSON from the Node-RED editor (`Menu -> Import -> Clipboard`) to get a starter flow with:
+
+- one `whatsapp-api-config` node
+- one `whatsapp-api-send` example
+- one `whatsapp-api-in` listener
+- one `whatsapp-api-history` example
+
+Replace the sample peer with a real WhatsApp JID such as `393331234567@s.whatsapp.net`.
+
+```json
+[
+  {
+    "id": "a1f4d7c2e9b00101",
+    "type": "tab",
+    "label": "WhatsApp Example",
+    "disabled": false,
+    "info": ""
+  },
+  {
+    "id": "b2f4d7c2e9b00102",
+    "type": "whatsapp-api-config",
+    "name": "My WhatsApp",
+    "reconnectMinMs": "2000",
+    "reconnectMaxMs": "30000",
+    "dataDir": ""
+  },
+  {
+    "id": "c3f4d7c2e9b00103",
+    "type": "inject",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Send test message",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "payload": "hello from Node-RED",
+    "payloadType": "str",
+    "x": 170,
+    "y": 100,
+    "wires": [
+      [
+        "d4f4d7c2e9b00104"
+      ]
+    ]
+  },
+  {
+    "id": "d4f4d7c2e9b00104",
+    "type": "whatsapp-api-send",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Send WhatsApp",
+    "account": "b2f4d7c2e9b00102",
+    "peer": "393331234567@s.whatsapp.net",
+    "x": 450,
+    "y": 100,
+    "wires": [
+      [
+        "e5f4d7c2e9b00105"
+      ]
+    ]
+  },
+  {
+    "id": "e5f4d7c2e9b00105",
+    "type": "debug",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Send result",
+    "active": true,
+    "tosidebar": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 720,
+    "y": 100,
+    "wires": []
+  },
+  {
+    "id": "f6f4d7c2e9b00106",
+    "type": "whatsapp-api-in",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Incoming messages",
+    "account": "b2f4d7c2e9b00102",
+    "includeRaw": false,
+    "x": 190,
+    "y": 200,
+    "wires": [
+      [
+        "07f4d7c2e9b00107"
+      ]
+    ]
+  },
+  {
+    "id": "07f4d7c2e9b00107",
+    "type": "debug",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Incoming debug",
+    "active": true,
+    "tosidebar": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 470,
+    "y": 200,
+    "wires": []
+  },
+  {
+    "id": "18f4d7c2e9b00108",
+    "type": "inject",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Read last 5",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "payload": "",
+    "payloadType": "date",
+    "x": 150,
+    "y": 300,
+    "wires": [
+      [
+        "29f4d7c2e9b00109"
+      ]
+    ]
+  },
+  {
+    "id": "29f4d7c2e9b00109",
+    "type": "whatsapp-api-history",
+    "z": "a1f4d7c2e9b00101",
+    "name": "Recent Chat History",
+    "account": "b2f4d7c2e9b00102",
+    "peer": "393331234567@s.whatsapp.net",
+    "limit": "5",
+    "includeRaw": false,
+    "x": 450,
+    "y": 300,
+    "wires": [
+      [
+        "3af4d7c2e9b0010a"
+      ]
+    ]
+  },
+  {
+    "id": "3af4d7c2e9b0010a",
+    "type": "debug",
+    "z": "a1f4d7c2e9b00101",
+    "name": "History debug",
+    "active": true,
+    "tosidebar": true,
+    "complete": "true",
+    "targetType": "full",
+    "x": 730,
+    "y": 300,
+    "wires": []
+  }
+]
+```
+
+## Message contract
+
+Incoming and action nodes use this shape:
+
+- `msg.payload`: the main payload for the node
+- `msg.whatsapp`: normalized WhatsApp metadata
+
+Common metadata fields:
+
+- `msg.whatsapp.peer`: `{ id, type, title, ref }`
+- `msg.whatsapp.chatId`
+- `msg.whatsapp.senderId`
+- `msg.whatsapp.messageId`
+- `msg.whatsapp.media`
+- `msg.whatsapp.raw` when the node is configured with `Include Raw`
+
+## Send node input patterns
+
+Text only:
+
+```json
+{
+  "payload": "hello from Node-RED",
+  "whatsapp": {
+    "peer": "393331234567@s.whatsapp.net"
+  }
+}
+```
+
+Media with a file path:
+
+```json
+{
+  "payload": "daily report",
+  "whatsapp": {
+    "peer": "393331234567@s.whatsapp.net",
+    "mediaPath": "/tmp/report.pdf"
+  }
+}
+```
+
+Media with a Buffer:
+
+```js
+msg.payload = Buffer.from("file-bytes");
+msg.whatsapp = {
+  peer: "393331234567@s.whatsapp.net",
+  fileName: "image.jpg",
+  caption: "generated by a flow",
+  mimeType: "image/jpeg"
+};
+return msg;
+```

package/dist/nodes/whatsapp-api.html

@@ -0,0 +1,358 @@
+<script type="text/html" data-template-name="whatsapp-api-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="WhatsApp account" />
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-reconnectMinMs"><i class="fa fa-repeat"></i> Reconnect Min</label>
+    <input type="number" id="node-config-input-reconnectMinMs" placeholder="2000" />
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-reconnectMaxMs"><i class="fa fa-repeat"></i> Reconnect Max</label>
+    <input type="number" id="node-config-input-reconnectMaxMs" placeholder="30000" />
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-dataDir"><i class="fa fa-folder-open"></i> Data Dir</label>
+    <input type="text" id="node-config-input-dataDir" placeholder="Default under Node-RED userDir" />
+  </div>
+
+  <div class="form-row whatsapp-api-auth-panel">
+    <label><i class="fa fa-whatsapp"></i> Session</label>
+    <div class="whatsapp-api-auth-body">
+      <div id="whatsapp-api-auth-status" class="form-tips">Save and deploy before connecting.</div>
+      <div class="whatsapp-api-auth-actions">
+        <a href="#" class="editor-button" id="whatsapp-api-connect">Connect</a>
+        <a href="#" class="editor-button" id="whatsapp-api-test">Test Connection</a>
+        <a href="#" class="editor-button" id="whatsapp-api-disconnect">Disconnect</a>
+      </div>
+      <div id="whatsapp-api-qr-panel" class="whatsapp-api-qr-panel" style="display:none">
+        <img id="whatsapp-api-qr-image" alt="WhatsApp QR code" />
+      </div>
+      <div id="whatsapp-api-session-summary" class="form-tips">
+        Deploy the config node, then use Connect to start the WhatsApp QR login flow.
+      </div>
+    </div>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="whatsapp-api-config">
+  <p>Stores the runtime settings for the WhatsApp Web session used by the other nodes in this palette.</p>
+  <p>Save and deploy first, then use <b>Connect</b> in the editor to start the QR login flow against the deployed runtime.</p>
+</script>
+
+<script type="text/html" data-template-name="whatsapp-api-in">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-account"><i class="fa fa-user"></i> Account</label>
+    <input type="text" id="node-input-account" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-includeRaw"><i class="fa fa-code"></i> Include Raw</label>
+    <input type="checkbox" id="node-input-includeRaw" style="width:auto" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="whatsapp-api-in">
+  <p>Emits normalized incoming WhatsApp messages from the configured session.</p>
+  <p><code>msg.payload</code> contains the message body. <code>msg.whatsapp</code> carries normalized WhatsApp metadata.</p>
+</script>
+
+<script type="text/html" data-template-name="whatsapp-api-send">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-account"><i class="fa fa-user"></i> Account</label>
+    <input type="text" id="node-input-account" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-peer"><i class="fa fa-comment"></i> Default Chat</label>
+    <input type="text" id="node-input-peer" placeholder="393331234567 or 393331234567@s.whatsapp.net" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="whatsapp-api-send">
+  <p>Sends a WhatsApp text or media message.</p>
+  <p>Use <code>msg.payload</code> for text, or provide a Buffer/path through <code>msg.payload</code> and <code>msg.whatsapp.mediaPath</code>.</p>
+</script>
+
+<script type="text/html" data-template-name="whatsapp-api-history">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-account"><i class="fa fa-user"></i> Account</label>
+    <input type="text" id="node-input-account" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-peer"><i class="fa fa-comment"></i> Default Chat</label>
+    <input type="text" id="node-input-peer" placeholder="393331234567@s.whatsapp.net" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-limit"><i class="fa fa-list-ol"></i> Limit</label>
+    <input type="number" id="node-input-limit" placeholder="10" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-includeRaw"><i class="fa fa-code"></i> Include Raw</label>
+    <input type="checkbox" id="node-input-includeRaw" style="width:auto" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-unreadOnly"><i class="fa fa-envelope"></i> Unread Only</label>
+    <input type="checkbox" id="node-input-unreadOnly" style="width:auto" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="whatsapp-api-history">
+  <p>Reads recent messages from the local WhatsApp message store maintained by the connected session.</p>
+  <p>The node outputs an array of normalized messages in <code>msg.payload</code>.</p>
+  <p>When <code>Unread Only</code> is enabled, the node returns the newest incoming messages that WhatsApp still marks as unread for that chat.</p>
+</script>
+
+<style>
+  .whatsapp-api-auth-panel .whatsapp-api-auth-body {
+    width: calc(100% - 110px);
+    margin-left: 110px;
+  }
+
+  .whatsapp-api-auth-actions {
+    display: flex;
+    gap: 8px;
+    margin-top: 8px;
+  }
+
+  .whatsapp-api-qr-panel {
+    margin-top: 12px;
+  }
+
+  .whatsapp-api-qr-panel img {
+    background: #fff;
+    border: 1px solid #d3d7db;
+    border-radius: 8px;
+    display: block;
+    max-width: 240px;
+    padding: 8px;
+  }
+</style>
+
+<script type="text/javascript">
+  (function() {
+    function apiRequest(method, url, data) {
+      return $.ajax({
+        contentType: "application/json; charset=utf-8",
+        data: data ? JSON.stringify(data) : undefined,
+        dataType: "json",
+        type: method,
+        url: url
+      });
+    }
+
+    function showError(xhr) {
+      var message = xhr && xhr.responseJSON && xhr.responseJSON.error ? xhr.responseJSON.error : "WhatsApp request failed.";
+      RED.notify(message, "error");
+    }
+
+    function updateAuthUi(status, hasNodeId) {
+      var state = status && status.state ? status.state : "disconnected";
+      var label = status && status.label ? status.label : "Disconnected";
+      var qrDataUrl = status && status.qrDataUrl ? status.qrDataUrl : null;
+
+      $("#whatsapp-api-auth-status").text(label);
+
+      if (qrDataUrl && state === "awaiting_qr") {
+        $("#whatsapp-api-qr-image").attr("src", qrDataUrl);
+        $("#whatsapp-api-qr-panel").show();
+        $("#whatsapp-api-session-summary").text("Scan the QR code with WhatsApp on your phone to finish linking this runtime session.");
+        return;
+      }
+
+      $("#whatsapp-api-qr-image").attr("src", "");
+      $("#whatsapp-api-qr-panel").hide();
+
+      if (!hasNodeId) {
+        $("#whatsapp-api-session-summary").text("Deploy the config node before starting the WhatsApp QR login flow.");
+      } else if (state === "connected") {
+        $("#whatsapp-api-session-summary").text("WhatsApp is connected. The runtime will reuse the stored auth state after restart.");
+      } else if (state === "connecting") {
+        $("#whatsapp-api-session-summary").text("Starting the WhatsApp session.");
+      } else if (state === "disconnected") {
+        $("#whatsapp-api-session-summary").text("Use Connect to start a fresh WhatsApp QR login flow.");
+      } else if (state === "error") {
+        $("#whatsapp-api-session-summary").text("The WhatsApp session hit an error. You can try Test Connection or Connect again.");
+      }
+    }
+
+    function registerSimpleNode(type, options) {
+      RED.nodes.registerType(type, $.extend(true, {
+        align: "right",
+        category: "whatsapp-api",
+        color: "#c8f2cf",
+        defaults: {
+          account: { required: true, type: "whatsapp-api-config" },
+          name: { value: "" }
+        }
+      }, options));
+    }
+
+    RED.nodes.registerType("whatsapp-api-config", {
+      category: "config",
+      defaults: {
+        dataDir: { value: "" },
+        name: { value: "" },
+        reconnectMaxMs: { value: 30000, validate: RED.validators.number() },
+        reconnectMinMs: { value: 2000, validate: RED.validators.number() }
+      },
+      label: function() {
+        return this.name || "whatsapp-api";
+      },
+      oneditprepare: function() {
+        var node = this;
+        var pollingHandle = null;
+
+        function stopPolling() {
+          if (pollingHandle) {
+            clearInterval(pollingHandle);
+            pollingHandle = null;
+          }
+        }
+
+        function pollRuntimeStatus() {
+          if (!node.id) {
+            updateAuthUi({ label: "Disconnected", state: "disconnected" }, false);
+            return;
+          }
+
+          apiRequest("GET", "whatsapp-api/config/" + encodeURIComponent(node.id) + "/status")
+            .done(function(response) {
+              updateAuthUi(response.status, true);
+            })
+            .fail(function(xhr) {
+              if (xhr && xhr.status !== 404) {
+                showError(xhr);
+              }
+            });
+        }
+
+        function startPolling() {
+          stopPolling();
+          pollingHandle = setInterval(pollRuntimeStatus, 1500);
+        }
+
+        $("#whatsapp-api-connect").on("click", function(event) {
+          event.preventDefault();
+
+          if (!node.id) {
+            RED.notify("Deploy the config node before connecting WhatsApp.", "warning");
+            return;
+          }
+
+          apiRequest("POST", "whatsapp-api/config/" + encodeURIComponent(node.id) + "/connect")
+            .done(function(response) {
+              updateAuthUi(response.status, true);
+              startPolling();
+            })
+            .fail(showError);
+        });
+
+        $("#whatsapp-api-test").on("click", function(event) {
+          event.preventDefault();
+
+          if (!node.id) {
+            RED.notify("Deploy the config node before testing the WhatsApp session.", "warning");
+            return;
+          }
+
+          apiRequest("POST", "whatsapp-api/config/" + encodeURIComponent(node.id) + "/test")
+            .done(function(response) {
+              updateAuthUi(response.status, true);
+            })
+            .fail(showError);
+        });
+
+        $("#whatsapp-api-disconnect").on("click", function(event) {
+          event.preventDefault();
+
+          if (!node.id) {
+            updateAuthUi({ label: "Disconnected", state: "disconnected" }, false);
+            return;
+          }
+
+          apiRequest("POST", "whatsapp-api/config/" + encodeURIComponent(node.id) + "/disconnect")
+            .done(function(response) {
+              updateAuthUi(response.status, true);
+            })
+            .fail(showError);
+        });
+
+        updateAuthUi({ label: "Disconnected", state: "disconnected" }, Boolean(node.id));
+        pollRuntimeStatus();
+        startPolling();
+
+        this._whatsappApiCleanup = function() {
+          stopPolling();
+        };
+      },
+      oneditsave: function() {
+        if (this._whatsappApiCleanup) {
+          this._whatsappApiCleanup();
+          this._whatsappApiCleanup = null;
+        }
+      },
+      oneditcancel: function() {
+        if (this._whatsappApiCleanup) {
+          this._whatsappApiCleanup();
+          this._whatsappApiCleanup = null;
+        }
+      }
+    });
+
+    registerSimpleNode("whatsapp-api-in", {
+      defaults: {
+        account: { required: true, type: "whatsapp-api-config" },
+        includeRaw: { value: false },
+        name: { value: "" }
+      },
+      icon: "font-awesome/fa-inbox",
+      inputs: 0,
+      label: function() {
+        return this.name || "whatsapp-api in";
+      },
+      outputs: 1
+    });
+
+    registerSimpleNode("whatsapp-api-send", {
+      defaults: {
+        account: { required: true, type: "whatsapp-api-config" },
+        name: { value: "" },
+        peer: { value: "" }
+      },
+      icon: "font-awesome/fa-paper-plane",
+      inputs: 1,
+      label: function() {
+        return this.name || "whatsapp-api send";
+      },
+      outputs: 1
+    });
+
+    registerSimpleNode("whatsapp-api-history", {
+      defaults: {
+        account: { required: true, type: "whatsapp-api-config" },
+        includeRaw: { value: false },
+        limit: { value: 10, validate: RED.validators.number() },
+        name: { value: "" },
+        peer: { value: "" },
+        unreadOnly: { value: false }
+      },
+      icon: "font-awesome/fa-history",
+      inputs: 1,
+      label: function() {
+        return this.name || "whatsapp-api history";
+      },
+      outputs: 1
+    });
+  })();
+</script>