Registry / communication / salesforce-pubsub-api-client

salesforce-pubsub-api-client

JSON →
library5.5.2jsnpmunverified

The `salesforce-pubsub-api-client` is a Node.js client library for interacting with the Salesforce Pub/Sub API, a gRPC-based event streaming service. Currently at stable version 5.5.2, it is actively maintained with frequent minor and patch releases, addressing bug fixes, dependency updates, and feature enhancements. The client abstracts the complexities of gRPC communication, offering multiple authentication flows (username/password, JWT bearer, client credentials), schema management for event data, and features like batch publishing and robust subscription management with replay IDs and flow control. A key differentiator in version 5 is its shift from an `EventEmitter`-based event handling model to a synchronous callback system, ensuring ordered event processing, and a simplified configuration approach via constructor options.

npm install salesforce-pubsub-api-client
INSTALL
IMPORT
SIG · SALESFORCE-PUBSUB-
S
salesforce-pubsub-api-client
communicationjavascriptv5.5.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PubSubApiClient
import { PubSubApiClient } from 'salesforce-pubsub-api-client';
const PubSubApiClient = require('salesforce-pubsub-api-client');
The library primarily targets ESM. For CommonJS, use `const { PubSubApiClient } = require('salesforce-pubsub-api-client');`, but ESM is recommended especially since v5.5.1 improved `nodeNext` module resolution.
SubscribeCallback
import type { SubscribeCallback } from 'salesforce-pubsub-api-client';
import { SubscribeCallback } from 'salesforce-pubsub-api-client';
This is a TypeScript type definition. Always use `import type` to avoid bundling issues and indicate it's a type-only import.
Configuration
import type { Configuration } from 'salesforce-pubsub-api-client';
import { Configuration } from 'salesforce-pubsub-api-client';
Provides type definitions for the client constructor options. Use `import type` for type-only imports in TypeScript.

Demonstrates how to connect to the Salesforce Pub/Sub API, authenticate using username/password flow, and subscribe to a platform event topic using the v5 synchronous callback model.

import { PubSubApiClient } from 'salesforce-pubsub-api-client'; import type { SubscribeCallback, SubscriptionInfo } from 'salesforce-pubsub-api-client'; // Ensure these environment variables are set for authentication const CLIENT_ID = process.env.SF_CLIENT_ID ?? 'YOUR_SALESFORCE_CLIENT_ID'; const CLIENT_SECRET = process.env.SF_CLIENT_SECRET ?? 'YOUR_SALESFORCE_CLIENT_SECRET'; const USERNAME = process.env.SF_USERNAME ?? 'your.email@example.com'; const PASSWORD = process.env.SF_PASSWORD ?? 'YOUR_SALESFORCE_PASSWORD'; const LOGIN_URL = process.env.SF_LOGIN_URL ?? 'https://login.salesforce.com'; // Or https://test.salesforce.com async function main() { const client = new PubSubApiClient({ instanceUrl: LOGIN_URL, auth: { username: USERNAME, password: PASSWORD, clientId: CLIENT_ID, clientSecret: CLIENT_SECRET }, isDebugLogEnabled: true // Enable debug logging }); // Define the callback function for incoming events and lifecycle events const subscribeCallback: SubscribeCallback = ( subscription: SubscriptionInfo, callbackType: 'data' | 'unsubscribing' | 'error' | 'reconnecting', data: any ) => { if (callbackType === 'data') { console.log(`Received event on ${subscription.topicName}:`, JSON.stringify(data, null, 2)); } else if (callbackType === 'error') { console.error(`Subscription error on ${subscription.topicName}:`, data); } else { console.log(`Subscription lifecycle event on ${subscription.topicName}: ${callbackType}`); } }; try { await client.connect(); console.log('Connected to Salesforce Pub/Sub API.'); // Subscribe to a Platform Event or Change Data Capture topic const topicName = '/event/My_Platform_Event__e'; // Replace with your topic await client.subscribe(topicName, subscribeCallback); console.log(`Subscribed to topic: ${topicName}. Waiting for events...`); // Keep the process alive to receive events process.on('SIGINT', async () => { console.log('Disconnecting from Pub/Sub API...'); await client.disconnect(); console.log('Disconnected. Exiting.'); process.exit(0); }); } catch (error) { console.error('Failed to connect or subscribe:', error); await client.disconnect(); } } main().catch(console.error);
Debug
Known issues
breakingVersion 5 and above completely changed the configuration method. Configuration is now passed as an object to the `PubSubApiClient` constructor, rather than relying on environment variables or `.env` files. The `connect()` method is now singular, replacing `connect()` and `connectWithAuth()`.
fix
Migrate your configuration from `.env` variables to a configuration object passed directly to the `PubSubApiClient` constructor. Use the unified `await client.connect()` method.
affects: >=5.0.0
breakingThe event handling mechanism was overhauled in v5. The client no longer uses an asynchronous `EventEmitter` (`client.on('data', ...)`) for incoming messages. Instead, a synchronous callback function is passed directly to the `subscribe()` method to ensure event order.
fix
Replace `eventEmitter.on('data', ...)` logic with a single `SubscribeCallback` function passed as the second argument to `client.subscribe(topic, subscribeCallback)`.
affects: >=5.0.0
gotchaWhen using private key authentication (e.g., for JWT bearer flow), older versions and specific environments might require the private key to start with `BEGIN RSA PRIVATE KEY`. Version 5.3.0 fixed this, making the `BEGIN RSA` header optional.
fix
Upgrade to v5.3.0 or newer. If stuck on an older version, ensure your private key file includes the `BEGIN RSA PRIVATE KEY` and `END RSA PRIVATE KEY` headers.
affects: <5.3.0
breakingVersion 5.4.0 upgraded to Node.js 22 and removed the deprecated `certifi` library, bundling recent CA certificates directly. This means users on older Node.js versions might face compatibility issues or changes in certificate trust behavior.
fix
Ensure your Node.js runtime is updated to version 22 or newer for full compatibility. Review your application's certificate management if you had custom `certifi` configurations.
affects: >=5.4.0
gotchaEarly v5 versions had issues with `nodeNext` module type resolution, particularly affecting projects using specific TypeScript module settings, leading to potential import errors.
fix
Upgrade to `salesforce-pubsub-api-client@5.5.1` or newer to resolve `nodeNext` module type resolution issues.
affects: <5.5.1
Errors
Common errors & fixes
Error: Invalid configuration property: instanceUrl is required
The `instanceUrl` property, or other required configuration properties, were not provided or were incorrectly structured in the `PubSubApiClient` constructor for versions 5+.
fix
Ensure you pass a complete `Configuration` object to the `PubSubApiClient` constructor, including `instanceUrl` and a valid `auth` object with the chosen authentication flow details. Consult the README's 'Configuration' section.
TypeError: client.on is not a function
You are attempting to use the `EventEmitter`-based event handling (`client.on('data', ...)`) which was deprecated and removed in version 5.x of the client.
fix
Refactor your event handling code to use the new synchronous callback function, which is passed directly as the second argument to the `client.subscribe()` method.
Error: Failed to connect: 16 UNAUTHENTICATED
The client failed to authenticate with Salesforce. This usually indicates incorrect `clientId`, `clientSecret`, `username`, `password`, or `instanceUrl`, or insufficient permissions on the Salesforce connected app.
fix
Verify all authentication credentials (client ID, client secret, username, password) and the `instanceUrl` in your `Configuration` object. Confirm that your Salesforce connected app has the necessary OAuth scopes and permissions.
Upgrade
Version history
5.5.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
2
Resources
salesforce-pubsub-api-client — npm install salesforce-pubsub-api-client · libregistry