![\"Salesforce\"](\"https://raw.githubusercontent.com/bonsaedev/node-red-salesforce/main/src/resources/icons/salesforce-connection.png\"){kind=icon}
\n\n \n
![\"built](\"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=\"){kind=icon}
\n![\"NPM](\"https://img.shields.io/npm/v/@bonsae/node-red-salesforce\")
\n![\"build](\"https://github.com/bonsaedev/node-red-salesforce/actions/workflows/ci.yaml/badge.svg?branch=main\"){kind=icon}
\n![\"codecov\"/](\"https://codecov.io/gh/bonsaedev/node-red-salesforce/graph/badge.svg\"){kind=icon}
\n\n# @bonsae/node-red-salesforce\n\nSalesforce nodes for [Node-RED](https://nodered.org) built with [@bonsae/nrg](https://bonsaedev.github.io/nrg/).\n\n## Nodes\n\n| Node | Description |\n| --- | --- |\n| **Connection** | OAuth 2.0 PKCE authentication with token management |\n| **SOQL** | Execute SOQL queries and return matching records |\n| **DML** | Create, read, update, delete, and upsert SObjects |\n| **Bulk** | Bulk API 2.0 operations for large data volumes |\n| **Describe** | Retrieve SObject metadata (fields, relationships, record types) |\n| **Streaming** | Subscribe to Platform Events and Change Data Capture via Pub/Sub API (gRPC) |\n| **Apex Invocation** | Call existing Apex REST endpoints or Invocable Actions |\n| **Apex Code** | Deploy and execute custom inline Apex code (Invocable or REST) |\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) >= 22\n- [pnpm](https://pnpm.io/) >= 10.11.0\n- A Salesforce org with a Connected App configured for OAuth 2.0 with PKCE\n\n## Installation\n\n```bash\nnpm install @bonsae/node-red-salesforce\n```\n\n## Connected App Setup\n\nCreate a Connected App in Salesforce Setup:\n\n1. Go to **Setup > App Manager > New Connected App**\n2. Enable **OAuth Settings**\n3. Set the **Callback URL** to `{your-node-red-url}/salesforce/auth/callback`\n4. Enable **Require Proof Key for Code Exchange (PKCE)**\n5. Add required OAuth scopes (`api`, `refresh_token`)\n6. Save and copy the **Consumer Key** (Client ID)\n\n## Usage\n\n1. Drag a Salesforce node onto the canvas\n2. Double-click to configure\n3. Select or create a **Connection** config node\n4. In the Connection config, enter your **Login URL**, **Client ID**, and **API Version**\n5. Click **Authorize with Salesforce** to complete the OAuth PKCE flow\n6. Configure the node's specific settings (query, SObject type, etc.)\n\n### SOQL Query\n\nWire an inject node to a SOQL node configured with a query like `SELECT Id, Name FROM Account`. The node merges its results onto the message: `msg.records` holds the array of records, `msg.totalSize` the total count, and `msg.done` whether all records were fetched.\n\n### DML Operations\n\nSet the operation (create, read, update, delete, upsert) and SObject type. Pass record data in `msg.payload`:\n\n- **create/update/upsert**: a record object or array of records\n- **read/delete**: a record ID or array of IDs\n- **upsert**: also set the External ID Field\n\n### Bulk API 2.0\n\nFor large data volumes. Supports three input types:\n\n- **Record array**: `msg.payload` as `Record[]` for ingest operations\n- **CSV string**: `msg.payload` as a CSV string\n- **Readable stream**: `msg.payload` as a Node.js `Readable` stream (for streaming from files)\n- **SOQL string**: `msg.payload` as a SOQL query string when operation is \"query\"\n\nOperations: insert, update, upsert, delete, hardDelete, query.\n\nFor ingest operations, the node merges `msg.result` onto the message as `{ successfulResults, failedResults, unprocessedRecords }`. For queries, each record is streamed as a separate message with the record on `msg.result` (or, in stream mode, `msg.result` is a single readable stream). Job lifecycle progress is reported via the status port.\n\n### Describe\n\nPass the SObject API name and receive the full describe result including fields, child relationships, and record type info.\n\n### Streaming (Pub/Sub API)\n\nSubscribes 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.\n\nConfigure the channel (e.g., `/event/MyEvent__e`), subscribe type (LATEST, EARLIEST, or CUSTOM with a replay ID), and batch size.\n\n### Apex Invocation\n\nCall existing Apex endpoints deployed in your Salesforce org. Select the type (REST or Invocable), then pick the endpoint or action from a dropdown that queries your org. For REST, choose the HTTP method and endpoint path. For Invocable, select the action by name. The payload is passed in `msg.payload`.\n\n### Apex Code\n\nDeploy and execute custom Apex code directly from Node-RED. Select the type (Invocable Method or REST Resource), enter a class name, and write your Apex code in the built-in editor. The node automatically deploys the class to Salesforce on Node-RED deploy and removes it when the node is deleted.\n\nYou write the `run()` method and any helper methods or inner classes. The node wraps your code in the required Salesforce boilerplate (annotations, Input/Output classes, etc.):\n\n```apex\nprivate static Object run(String payload) {\n Map