Required dependencies

npm install user@example.com
npm install agentkeepalive buffer cbor-js cbor-sync fast-text-encoding fflate form-data lil-uuid node-fetch proxy-agent
npm install --save-dev typescript ts-node @types/node @types/node-fetch

No native modules, iOS pod install, Android linking, or Expo prebuild steps are required for a Node.js target.

Project setup

1. Copy the source/ directory into your project, e.g. src/pubnub-src/.

2. Update tsconfig.json to include the source and enable the required compiler options:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "pubnub-src/*": ["src/pubnub-src/*"]
    }
  },
  "include": ["src/**/*"]
}

3. Set your PubNub keys as environment variables:

export PUBNUB_PUBLISH_KEY=your_publish_key
export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key
export PUBNUB_SECRET_KEY=your_secret_key   # only for server-side PAM
export PUBNUB_USER_ID=your-unique-user-id

4. For the Node.js adapter, import from src/pubnub-src/node/ which wires the Node-specific transport (node-fetch + agentkeepalive) to the core client. Do not import from web/, react_native/, or nativescript/.

5. If you use ts-node directly: npx ts-node -r tsconfig-paths/register src/index.ts

Public API

EventEngine

import { EventEngine } from 'pubnub-src/event-engine/index';

class EventEngine {
  channels: string[];
  groups: string[];
  get subscriptionTimetoken(): string | undefined;
  constructor(dependencies: Dependencies);
}

Drives the subscribe lifecycle as a state machine. Instantiate it with a Dependencies object (provided internally by the core client). Use channels and groups to inspect active subscriptions and subscriptionTimetoken to read the current timetoken for catch-up.

Engine / Dispatcher (event-engine/core)

import { Engine, Dispatcher, createEvent, createEffect, createManagedEffect } from 'pubnub-src/event-engine/core/index';

Low-level primitives for the event engine. Engine owns the state machine and emits change notifications; Dispatcher maps effect invocations to async handlers. Use createEvent and createEffect to extend the engine with custom states when forking the SDK behavior.

Legacy Cryptography Module

// core/components/cryptography/index.ts
export default class LegacyCryptor {
  encrypt(data: string | ArrayBuffer): string;
  decrypt(data: string): string | null;
  encryptFile(file: File | Blob, cryptoModule?: unknown): Promise<File | Blob>;
  decryptFile(file: File | Blob, cryptoModule?: unknown): Promise<File | Blob>;
}

Provides AES-CBC (default) or AES-ECB encryption for message payloads and files. Used internally for cipher key-based encryption. Access via the core client's cryptoModule or instantiate directly for standalone encrypt/decrypt of payloads.

ResultCallback / StatusCallback (core/types/api)

import { ResultCallback, StatusCallback, Status } from 'pubnub-src/core/types/api/index';

type ResultCallback<ResponseType> = (status: Status, response: ResponseType | null) => void;
type StatusCallback = (status: Status) => void;

Callback types used by every endpoint. ResultCallback receives both a Status and a typed response; StatusCallback is used for acknowledgment-only endpoints (e.g., publish when you only need confirmation).

Working examples

Scenario - Initialize and publish a message

Create a PubNub client via the Node adapter and publish a message to a channel using environment-sourced keys.

import PubNub from 'pubnub'; // compiled adapter; swap with node/ adapter when building from source

const client = new PubNub({
  publishKey: process.env.PUBNUB_PUBLISH_KEY!,
  subscribeKey: process.env.PUBNUB_SUBSCRIBE_KEY!,
  userId: process.env.PUBNUB_USER_ID!,
});

async function publishMessage() {
  const result = await client.publish({
    channel: 'my_channel',
    message: { text: 'Hello from Node.js' },
  });
  console.log('Timetoken:', result.timetoken);
}

publishMessage().catch(console.error);

Scenario - Subscribe with the entity API and typed listeners

Use the channel entity subscription model (introduced in v8+) with per-event typed handlers.

import PubNub from 'pubnub';
import type { ResultCallback } from 'pubnub-src/core/types/api/index';

const client = new PubNub({
  subscribeKey: process.env.PUBNUB_SUBSCRIBE_KEY!,
  userId: process.env.PUBNUB_USER_ID!,
});

const channel = client.channel('my_channel');
const subscription = channel.subscription({ receivePresenceEvents: true });

subscription.onMessage = (event) => {
  console.log('Message received:', event.message, 'on', event.channel);
};

subscription.onPresence = (event) => {
  console.log('Presence:', event.action, event.uuid, 'occupancy:', event.occupancy);
};

subscription.onSignal = (event) => {
  console.log('Signal:', event.message);
};

subscription.subscribe();

// Graceful shutdown after 30 s
setTimeout(() => {
  subscription.unsubscribe();
  client.destroy();
}, 30_000);

Scenario - Inspect EventEngine state and active subscriptions

Access the internal event engine (exposed on the client instance) to read live subscription state.

import PubNub from 'pubnub';
import { EventEngine } from 'pubnub-src/event-engine/index';

const client = new PubNub({
  subscribeKey: process.env.PUBNUB_SUBSCRIBE_KEY!,
  userId: process.env.PUBNUB_USER_ID!,
});

// The SDK exposes _ee internally; cast for introspection
const engine = (client as unknown as { _ee: EventEngine })._ee;

const ch = client.channel('diagnostics');
const sub = ch.subscription();
sub.subscribe();

setTimeout(() => {
  console.log('Active channels:', engine.channels);
  console.log('Active groups:', engine.groups);
  console.log('Current timetoken:', engine.subscriptionTimetoken);
  sub.unsubscribe();
  client.destroy();
}, 5_000);

File walkthrough

• cbor/ and cbor/common.ts - Decode PAMv3 access tokens encoded as CBOR binary; depends on cbor-js and cbor-sync.
• core/pubnub-common.ts - Platform-agnostic base class; wires all endpoints, components, and the event engine together.
• core/components/configuration.ts - Validates and normalizes constructor options into a typed configuration object.
• core/components/cryptography/index.ts - Legacy AES cryptor; wraps the bundled hmac-sha256.js CryptoJS subset.
• core/components/retry-policy.ts - Pluggable retry strategy (linear or exponential) with per-endpoint overrides.
• core/components/token_manager.ts - Stores, parses, and exposes PAMv3 auth tokens for channel/group-level grants.
• core/endpoints/publish.ts - Constructs and sends publish REST requests; handles cipher encryption when configured.
• core/endpoints/subscribe.ts - Long-poll subscribe request; feeds raw envelopes into the event engine.
• core/endpoints/fetch_messages.ts - Batch history with optional message actions, UUID metadata, and file info.
• event-engine/index.ts - EventEngine class: starts the state machine, dispatches effects, surfaces timetoken.
• event-engine/core/index.ts - Re-exports Engine, Dispatcher, and factory helpers for custom state extensions.
• node/ - Node.js platform adapter: wires node-fetch, agentkeepalive, form-data, and proxy-agent.
• transport/ - HTTP transport interface and concrete implementations used by both Node and browser adapters.
• entities/ - Channel, ChannelGroup, User entity classes returned by client.channel(), client.channelGroup(), etc.
• errors/ - PubNubError and PubNubAPIError with typed status fields matching Status from core/types/api.
• file/ - Cross-platform PubNubFile abstraction used by upload/download endpoints.
• loggers/ - ConsoleLogger and the LoggerManager that gates log levels before forwarding.

Common pitfalls and fixes

• Missing userId: The SDK throws synchronously at construction if userId is absent; always pass it explicitly, never rely on a default.
• ESM/CJS interop with node-fetch: node-fetch@2 is CJS; node-fetch@3 is ESM-only. Pin node-fetch@^2.6.9 and set "esModuleInterop": true in tsconfig.json.
• crypto module conflicts: Node's built-in crypto and the bundled hmac-sha256.js CryptoJS subset share no interface; never import Node's crypto into files that also import core/components/cryptography/index.ts.
• Secret key on the client side: secretKey enables request signing and PAM grant; never expose it in browser or React Native bundles - restrict it to server-side Node processes only.
• buffer polyfill: The SDK depends on the npm buffer package for base64 operations in non-Node environments; in a Node.js project this is provided natively but the buffer npm package must still be listed in dependencies for bundlers (webpack, esbuild) targeting mixed environments.
• Retry policy and subscribe: The default retry policy retries failed subscribe long-polls; if you run integration tests against a mock server, set retryConfiguration to PubNub.LinearRetryPolicy({ delay: 0, maximumRetry: 0 }) to prevent flaky timeouts.

Vibe-coding prompt template

I have dropped the PubNub JavaScript SDK source (pubnub@11.0.0) into `src/pubnub-src/`
in my Node.js TypeScript project. The integration guide is in `USAGE.md` at the project root.

Please help me integrate it step by step:

1. Read `USAGE.md` and `src/pubnub-src/node/` to understand the Node.js adapter entry point.
2. Create a `src/pubnub-client.ts` module that initializes a PubNub client using
   environment variables (PUBNUB_PUBLISH_KEY, PUBNUB_SUBSCRIBE_KEY, PUBNUB_USER_ID)
   and exports it as a singleton.
3. Add a `src/messaging/publisher.ts` that exposes a typed `publish(channel, payload)` function.
4. Add a `src/messaging/subscriber.ts` that subscribes to a given channel and routes
   message/presence/signal events to provided callbacks.
5. Show me the `tsconfig.json` changes needed to resolve `pubnub-src/*` path aliases.
6. Show the exact `npm install` commands for all runtime dependencies listed in USAGE.md.
7. Point out any gotchas specific to my project setup (ESM vs CJS, secret key handling, retry policy).

Base all imports on real exports visible in `src/pubnub-src/` and documented in `USAGE.md`.
Do not invent API surface that is not present in those files.

License and credit

The PubNub JavaScript SDK is published under the MIT License. See source/LICENSE if present in this block, or refer to the upstream repository. Upstream package: user@example.com - maintained by PubNub Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free