@bonsae/node-red-salesforce 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+<a href="https://bonsaedev.github.io/nrg/"><img src="https://img.shields.io/badge/built%20with-nrg-A80000.svg?labelColor=black&style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDAgMTAwIiB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCI+CiAgPGRlZnM+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9Im91dGxpbmVHcmFkaWVudCIgeDE9IjAlIiB5MT0iMCUiIHgyPSIxMDAlIiB5Mj0iMTAwJSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCUiIHN0eWxlPSJzdG9wLWNvbG9yOiAjODA4MDgwOyBzdG9wLW9wYWNpdHk6IDEiIC8+CiAgICAgIDxzdG9wIG9mZnNldD0iMTAwJSIgc3R5bGU9InN0b3AtY29sb3I6ICM0MDQwNDA7IHN0b3Atb3BhY2l0eTogMSIgLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9ImhleGFnb25HcmFkaWVudCIgeDE9IjAlIiB5MT0iMCUiIHgyPSIxMDAlIiB5Mj0iMTAwJSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCUiIHN0eWxlPSJzdG9wLWNvbG9yOiAjQTgwMDAwOyBzdG9wLW9wYWNpdHk6IDEiIC8+CiAgICAgIDxzdG9wIG9mZnNldD0iMTAwJSIgc3R5bGU9InN0b3AtY29sb3I6ICM0QjAwMDA7IHN0b3Atb3BhY2l0eTogMSIgLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9ImxpZ2h0bmluZ0dyYWRpZW50IiB4MT0iMCUiIHkxPSIwJSIgeDI9IjEwMCUiIHkyPSIxMDAlIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwJSIgc3R5bGU9InN0b3AtY29sb3I6ICNmZmZmZmY7IHN0b3Atb3BhY2l0eTogMSIgLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxMDAlIiBzdHlsZT0ic3RvcC1jb2xvcjogI2UwZTBlMDsgc3RvcC1vcGFjaXR5OiAxIiAvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICA8L2RlZnM+CiAgPHBvbHlnb24gcG9pbnRzPSI1MCwyIDk4LDI1IDk4LDc1IDUwLDk4IDMsNzUgMywyNSIgCiAgICAgICAgICAgc3Ryb2tlPSJ1cmwoI291dGxpbmVHcmFkaWVudCkiIHN0cm9rZS13aWR0aD0iNCIgZmlsbD0idXJsKCNoZXhhZ29uR3JhZGllbnQpIiAvPgoKICA8cGF0aCBkPSJNMzMgMGwxOS43OTcyIDM5LjQ1NzQtMjguNTAyMi0xMS4xMTg0TDc0IDk4IDUxLjA2MDggNDkuMzA1NCA3MSA1NloiIAogICAgICAgIGZpbGw9InVybCgjbGlnaHRuaW5nR3JhZGllbnQpIiBzdHJva2U9Im5vbmUiIC8+Cjwvc3ZnPgo=" alt="built with nrg"/></a>
+<a href="https://www.npmjs.com/package/@bonsae/node-red-salesforce"><img alt="NPM Version" src="https://img.shields.io/npm/v/@bonsae/node-red-salesforce"></a>
+<a href="https://github.com/bonsaedev/node-red-salesforce/actions/workflows/ci.yaml"><img src="https://github.com/bonsaedev/node-red-salesforce/actions/workflows/ci.yaml/badge.svg?branch=main" alt="build status"/></a>
+<a href="https://socket.dev/npm/package/@bonsae/node-red-salesforce"><img src="https://socket.dev/api/badge/npm/package/@bonsae/node-red-salesforce" alt="socket badge"/></a>
+<a href="https://codecov.io/gh/bonsaedev/node-red-salesforce"><img src="https://codecov.io/gh/bonsaedev/node-red-salesforce/graph/badge.svg" alt="codecov"/></a>
+
+# @bonsae/node-red-salesforce
+
+Salesforce nodes for [Node-RED](https://nodered.org) built with [@bonsae/nrg](https://bonsaedev.github.io/nrg/).
+
+## Nodes
+
+| Node | Description |
+| --- | --- |
+| **Connection** | OAuth 2.0 PKCE authentication with token management |
+| **SOQL** | Execute SOQL queries and return matching records |
+| **DML** | Create, read, update, delete, and upsert SObjects |
+| **Bulk** | Bulk API 2.0 operations for large data volumes |
+| **Describe** | Retrieve SObject metadata (fields, relationships, record types) |
+| **Streaming** | Subscribe to Platform Events and Change Data Capture via Pub/Sub API (gRPC) |
+| **Apex** | Invoke Apex REST endpoints |
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 22
+- [pnpm](https://pnpm.io/) >= 10.11.0
+- A Salesforce org with a Connected App configured for OAuth 2.0 with PKCE
+
+## Installation
+
+```bash
+pnpm add @bonsae/node-red-salesforce
+```
+
+## Connected App Setup
+
+Create a Connected App in Salesforce Setup:
+
+1. Go to **Setup > App Manager > New Connected App**
+2. Enable **OAuth Settings**
+3. Set the **Callback URL** to `{your-node-red-url}/salesforce/auth/callback`
+4. Enable **Require Proof Key for Code Exchange (PKCE)**
+5. Add required OAuth scopes (`api`, `refresh_token`)
+6. Save and copy the **Consumer Key** (Client ID)
+
+## Usage
+
+1. Drag a Salesforce node onto the canvas
+2. Double-click to configure
+3. Select or create a **Connection** config node
+4. In the Connection config, enter your **Login URL**, **Client ID**, and **API Version**
+5. Click **Authorize with Salesforce** to complete the OAuth PKCE flow
+6. Configure the node's specific settings (query, SObject type, etc.)
+
+### SOQL Query
+
+Wire an inject node to a SOQL node configured with a query like `SELECT Id, Name FROM Account`. The output `msg.payload` contains the array of records, `msg.totalSize` the total count, and `msg.done` whether all records were fetched.
+
+### DML Operations
+
+Set the operation (create, read, update, delete, upsert) and SObject type. Pass record data in `msg.payload`:
+
+- **create/update/upsert**: a record object or array of records
+- **read/delete**: a record ID or array of IDs
+- **upsert**: also set the External ID Field
+
+### Bulk API 2.0
+
+For large data volumes. Pass an array of records in `msg.payload` for ingest operations, or a SOQL string for bulk queries.
+
+### Describe
+
+Pass the SObject API name and receive the full describe result including fields, child relationships, and record type info.
+
+### Streaming (Pub/Sub API)
+
+Subscribes to Salesforce Platform Events and Change Data Capture events using the gRPC-based Pub/Sub API. This node has no input port -- it emits messages when events are received.
+
+Configure the channel (e.g., `/event/MyEvent__e`), subscribe type (LATEST, EARLIEST, or CUSTOM with a replay ID), and batch size.
+
+### Apex REST
+
+Invoke custom Apex REST endpoints. Set the HTTP method and path (e.g., `/MyEndpoint`). For POST/PUT/PATCH, the request body is taken from `msg.payload`.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start dev server (launches Node-RED with hot reload)
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm tsc:server
+pnpm tsc:client
+
+# Lint and format
+pnpm lint
+pnpm format
+```
+
+## Locales
+
+Labels and auto-generated help docs are available in:
+
+- English (en-US)
+- German (de)
+- Spanish (es-ES)
+- French (fr)
+- Japanese (ja)
+- Korean (ko)
+- Portuguese (pt-BR)
+- Russian (ru)
+- Chinese Simplified (zh-CN)
+- Chinese Traditional (zh-TW)
+
+## License
+
+MIT

package/examples/1-soql-query.json

@@ -0,0 +1,103 @@
+[
+  {
+    "id": "flow-soql",
+    "type": "tab",
+    "label": "SOQL Query",
+    "disabled": false,
+    "info": "Query records from Salesforce using static and dynamic SOQL"
+  },
+  {
+    "id": "config-sf-1",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "inject-static",
+    "type": "inject",
+    "z": "flow-soql",
+    "name": "Query Accounts",
+    "props": [],
+    "repeat": "",
+    "once": false,
+    "x": 140,
+    "y": 80,
+    "wires": [["soql-static"]]
+  },
+  {
+    "id": "soql-static",
+    "type": "salesforce-soql",
+    "z": "flow-soql",
+    "name": "Static Query",
+    "connection": "config-sf-1",
+    "query": {
+      "type": "str",
+      "value": "SELECT Id, Name, Industry, CreatedDate FROM Account ORDER BY CreatedDate DESC LIMIT 10"
+    },
+    "x": 350,
+    "y": 80,
+    "wires": [["debug-static"]]
+  },
+  {
+    "id": "debug-static",
+    "type": "debug",
+    "z": "flow-soql",
+    "name": "Results",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 530,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "inject-dynamic",
+    "type": "inject",
+    "z": "flow-soql",
+    "name": "Query Contacts",
+    "props": [
+      {
+        "p": "query",
+        "v": "SELECT Id, Name, Email FROM Contact LIMIT 5",
+        "vt": "str"
+      }
+    ],
+    "repeat": "",
+    "once": false,
+    "x": 150,
+    "y": 180,
+    "wires": [["soql-dynamic"]]
+  },
+  {
+    "id": "soql-dynamic",
+    "type": "salesforce-soql",
+    "z": "flow-soql",
+    "name": "Dynamic Query",
+    "connection": "config-sf-1",
+    "query": {
+      "type": "msg",
+      "value": "query"
+    },
+    "x": 360,
+    "y": 180,
+    "wires": [["debug-dynamic"]]
+  },
+  {
+    "id": "debug-dynamic",
+    "type": "debug",
+    "z": "flow-soql",
+    "name": "Results",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 530,
+    "y": 180,
+    "wires": []
+  }
+]

package/examples/10-streaming-platform-events.json

@@ -0,0 +1,73 @@
+[
+  {
+    "id": "flow-streaming",
+    "type": "tab",
+    "label": "Platform Events",
+    "disabled": false,
+    "info": "Subscribe to Salesforce Platform Events using the Pub/Sub API (gRPC). Requires a Platform Event defined in your org (e.g., MyEvent__e)."
+  },
+  {
+    "id": "config-sf-9",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "streaming-latest",
+    "type": "salesforce-streaming",
+    "z": "flow-streaming",
+    "name": "New Events",
+    "connection": "config-sf-9",
+    "channelName": "/event/MyEvent__e",
+    "subscribeType": "LATEST",
+    "replayId": "",
+    "numRequested": 100,
+    "x": 150,
+    "y": 80,
+    "wires": [["debug-event"]]
+  },
+  {
+    "id": "debug-event",
+    "type": "debug",
+    "z": "flow-streaming",
+    "name": "Event",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 350,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "streaming-earliest",
+    "type": "salesforce-streaming",
+    "z": "flow-streaming",
+    "name": "Replay All",
+    "connection": "config-sf-9",
+    "channelName": "/event/MyEvent__e",
+    "subscribeType": "EARLIEST",
+    "replayId": "",
+    "numRequested": 50,
+    "x": 140,
+    "y": 200,
+    "wires": [["debug-replay"]]
+  },
+  {
+    "id": "debug-replay",
+    "type": "debug",
+    "z": "flow-streaming",
+    "name": "Replayed Event",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 370,
+    "y": 200,
+    "wires": []
+  }
+]

package/examples/11-streaming-change-data-capture.json

@@ -0,0 +1,73 @@
+[
+  {
+    "id": "flow-cdc",
+    "type": "tab",
+    "label": "Change Data Capture",
+    "disabled": false,
+    "info": "Subscribe to Salesforce Change Data Capture events. Enable CDC for the desired objects in Salesforce Setup > Change Data Capture."
+  },
+  {
+    "id": "config-sf-10",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "streaming-account-cdc",
+    "type": "salesforce-streaming",
+    "z": "flow-cdc",
+    "name": "Account Changes",
+    "connection": "config-sf-10",
+    "channelName": "/data/AccountChangeEvent",
+    "subscribeType": "LATEST",
+    "replayId": "",
+    "numRequested": 100,
+    "x": 160,
+    "y": 80,
+    "wires": [["debug-cdc-account"]]
+  },
+  {
+    "id": "debug-cdc-account",
+    "type": "debug",
+    "z": "flow-cdc",
+    "name": "Account Change",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 390,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "streaming-all-cdc",
+    "type": "salesforce-streaming",
+    "z": "flow-cdc",
+    "name": "All Changes",
+    "connection": "config-sf-10",
+    "channelName": "/data/ChangeEvents",
+    "subscribeType": "LATEST",
+    "replayId": "",
+    "numRequested": 100,
+    "x": 150,
+    "y": 200,
+    "wires": [["debug-cdc-all"]]
+  },
+  {
+    "id": "debug-cdc-all",
+    "type": "debug",
+    "z": "flow-cdc",
+    "name": "Any Change",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "true",
+    "x": 370,
+    "y": 200,
+    "wires": []
+  }
+]

package/examples/2-dml-create.json

@@ -0,0 +1,106 @@
+[
+  {
+    "id": "flow-create",
+    "type": "tab",
+    "label": "DML Create",
+    "disabled": false,
+    "info": "Create records in Salesforce using static JSON and dynamic msg"
+  },
+  {
+    "id": "config-sf-2",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "inject-create-static",
+    "type": "inject",
+    "z": "flow-create",
+    "name": "Create (static JSON)",
+    "props": [],
+    "repeat": "",
+    "once": false,
+    "x": 160,
+    "y": 80,
+    "wires": [["dml-create-static"]]
+  },
+  {
+    "id": "dml-create-static",
+    "type": "salesforce-dml",
+    "z": "flow-create",
+    "name": "Create Account",
+    "connection": "config-sf-2",
+    "operation": "create",
+    "sObjectType": { "type": "str", "value": "Account" },
+    "record": {
+      "type": "json",
+      "value": "{\"Name\":\"Node-RED Test\",\"Industry\":\"Technology\"}"
+    },
+    "externalIdField": "",
+    "x": 390,
+    "y": 80,
+    "wires": [["debug-create-1"]]
+  },
+  {
+    "id": "debug-create-1",
+    "type": "debug",
+    "z": "flow-create",
+    "name": "Result",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "payload",
+    "x": 570,
+    "y": 80,
+    "wires": []
+  },
+  {
+    "id": "inject-create-dynamic",
+    "type": "inject",
+    "z": "flow-create",
+    "name": "Create (from msg)",
+    "props": [
+      {
+        "p": "payload",
+        "v": "{\"Name\":\"Dynamic Account\",\"Industry\":\"Finance\"}",
+        "vt": "json"
+      }
+    ],
+    "repeat": "",
+    "once": false,
+    "x": 160,
+    "y": 180,
+    "wires": [["dml-create-dynamic"]]
+  },
+  {
+    "id": "dml-create-dynamic",
+    "type": "salesforce-dml",
+    "z": "flow-create",
+    "name": "Create Account",
+    "connection": "config-sf-2",
+    "operation": "create",
+    "sObjectType": { "type": "str", "value": "Account" },
+    "record": { "type": "msg", "value": "payload" },
+    "externalIdField": "",
+    "x": 390,
+    "y": 180,
+    "wires": [["debug-create-2"]]
+  },
+  {
+    "id": "debug-create-2",
+    "type": "debug",
+    "z": "flow-create",
+    "name": "Result",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "payload",
+    "x": 570,
+    "y": 180,
+    "wires": []
+  }
+]

package/examples/3-dml-read.json

@@ -0,0 +1,83 @@
+[
+  {
+    "id": "flow-read",
+    "type": "tab",
+    "label": "DML Read",
+    "disabled": false,
+    "info": "Retrieve a record by ID from Salesforce"
+  },
+  {
+    "id": "config-sf-read",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "inject-read",
+    "type": "inject",
+    "z": "flow-read",
+    "name": "Read Account",
+    "props": [],
+    "repeat": "",
+    "once": false,
+    "x": 140,
+    "y": 80,
+    "wires": [["soql-find-for-read"]]
+  },
+  {
+    "id": "soql-find-for-read",
+    "type": "salesforce-soql",
+    "z": "flow-read",
+    "name": "Get First Account ID",
+    "connection": "config-sf-read",
+    "query": {
+      "type": "str",
+      "value": "SELECT Id FROM Account LIMIT 1"
+    },
+    "x": 370,
+    "y": 80,
+    "wires": [["func-extract-read-id"]]
+  },
+  {
+    "id": "func-extract-read-id",
+    "type": "function",
+    "z": "flow-read",
+    "name": "Extract ID",
+    "func": "if (msg.payload && msg.payload.length > 0) {\n    msg.payload = msg.payload[0].Id;\n    return msg;\n}\nnode.warn(\"No account found\");\nreturn null;",
+    "outputs": 1,
+    "x": 570,
+    "y": 80,
+    "wires": [["dml-read"]]
+  },
+  {
+    "id": "dml-read",
+    "type": "salesforce-dml",
+    "z": "flow-read",
+    "name": "Read Account",
+    "connection": "config-sf-read",
+    "operation": "read",
+    "sObjectType": { "type": "str", "value": "Account" },
+    "record": { "type": "msg", "value": "payload" },
+    "externalIdField": "",
+    "x": 750,
+    "y": 80,
+    "wires": [["debug-read"]]
+  },
+  {
+    "id": "debug-read",
+    "type": "debug",
+    "z": "flow-read",
+    "name": "Account Record",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "payload",
+    "x": 940,
+    "y": 80,
+    "wires": []
+  }
+]

package/examples/4-dml-update.json

@@ -0,0 +1,83 @@
+[
+  {
+    "id": "flow-update",
+    "type": "tab",
+    "label": "DML Update",
+    "disabled": false,
+    "info": "Find an account by name and update its Industry"
+  },
+  {
+    "id": "config-sf-3",
+    "type": "salesforce-connection",
+    "name": "Salesforce",
+    "loginUrl": "https://login.salesforce.com",
+    "clientId": "",
+    "apiVersion": "62.0",
+    "callbackUrl": "http://localhost:1880/salesforce/auth/callback",
+    "z": ""
+  },
+  {
+    "id": "inject-update",
+    "type": "inject",
+    "z": "flow-update",
+    "name": "Update Account",
+    "props": [],
+    "repeat": "",
+    "once": false,
+    "x": 140,
+    "y": 80,
+    "wires": [["soql-find-update"]]
+  },
+  {
+    "id": "soql-find-update",
+    "type": "salesforce-soql",
+    "z": "flow-update",
+    "name": "Find Account",
+    "connection": "config-sf-3",
+    "query": {
+      "type": "str",
+      "value": "SELECT Id, Name FROM Account WHERE Name = 'Node-RED Test' LIMIT 1"
+    },
+    "x": 340,
+    "y": 80,
+    "wires": [["func-prep-update"]]
+  },
+  {
+    "id": "func-prep-update",
+    "type": "function",
+    "z": "flow-update",
+    "name": "Prepare Update",
+    "func": "if (msg.payload && msg.payload.length > 0) {\n    msg.payload = {\n        Id: msg.payload[0].Id,\n        Industry: \"Finance\"\n    };\n    return msg;\n}\nnode.warn(\"No account found\");\nreturn null;",
+    "outputs": 1,
+    "x": 540,
+    "y": 80,
+    "wires": [["dml-update"]]
+  },
+  {
+    "id": "dml-update",
+    "type": "salesforce-dml",
+    "z": "flow-update",
+    "name": "Update Account",
+    "connection": "config-sf-3",
+    "operation": "update",
+    "sObjectType": { "type": "str", "value": "Account" },
+    "record": { "type": "msg", "value": "payload" },
+    "externalIdField": "",
+    "x": 740,
+    "y": 80,
+    "wires": [["debug-update"]]
+  },
+  {
+    "id": "debug-update",
+    "type": "debug",
+    "z": "flow-update",
+    "name": "Result",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "complete": "payload",
+    "x": 910,
+    "y": 80,
+    "wires": []
+  }
+]