Node.js
Publish events, sign channel and user auth, validate webhooks, read history, mutate versioned messages, and manage push from Node.js with the sockudo package.
sockudo is the trusted backend library for calling the Sockudo HTTP API from Node.js 16+. It runs
inside your API servers, workers, and serverless functions, signs every request with your app
secret, and ships TypeScript declarations. It does not hold a WebSocket subscription; use
@sockudo/client to receive events.
- Signed HTTP publishing to one channel, up to 100 channels, or a batch of events
- Automatic and explicit idempotency keys, with built-in retries for 5xx and network failures
- Private, presence, encrypted-channel, and user (signin) authentication signing
- Webhook signature validation, including key rotation
- Channel state through signed
getrequests, durable history, and presence history - Versioned messages (get, versions, update, delete, append) and annotations (publish, list, delete)
- Push device registration, channel subscriptions, publish, scheduling, publish status, and Apple Live Activities
- Terminate or force-reconnect every connection of a user
Install
npm install sockudo# or: pnpm add sockudo# or: yarn add sockudo# or: bun add sockudoThe package supports Node.js 16 and newer and bundles its type definitions; no separate @types
package is needed. Version 2.2.0 is the current release.
Contributors working inside the Sockudo monorepo can build the SDK from its package directory:
cd server-sdks/sockudo-http-nodenpm installnpm run buildThe module exports the Sockudo class itself (module.exports = Sockudo), not a named export:
// ESM, or TypeScript with esModuleInteropimport Sockudo from "sockudo";
// CommonJS// const Sockudo = require("sockudo");Configure the client
import Sockudo from "sockudo";import { Agent } from "node:https";
export const sockudo = new Sockudo({ appId: process.env.SOCKUDO_APP_ID!, key: process.env.SOCKUDO_KEY!, secret: process.env.SOCKUDO_SECRET!, host: process.env.SOCKUDO_HOST ?? "127.0.0.1", port: process.env.SOCKUDO_PORT ?? "6001", useTLS: process.env.SOCKUDO_USE_TLS === "true", timeout: 5_000, agent: new Agent({ keepAlive: true }), // Required only for private-encrypted-* channels. encryptionMasterKeyBase64: process.env.SOCKUDO_ENCRYPTION_MASTER_KEY,});| Option | Type | Default | Description |
|---|---|---|---|
appId | string | required | Sockudo app ID; used in every /apps/{appId}/... path. |
key | string | required | App key, sent as auth_key and used as the prefix of auth signatures. |
secret | string | required | App secret used for HMAC-SHA256 signing. Never send it to a client. |
host | string | "localhost" | HTTP API host without a scheme. |
port | string | scheme default | HTTP API port. When omitted, the URL has no port, so 80 or 443 applies. |
useTLS | boolean | false | Use https. Enable it whenever traffic leaves a trusted network. |
timeout | number | none | Per-request timeout in milliseconds. Without it, requests wait for the socket. |
agent | http.Agent | Node default | Custom agent for keep-alive pools, proxies, or TLS settings. |
encryptionMasterKeyBase64 | string | none | Base64 key that must decode to exactly 32 bytes; validated in the constructor. |
autoIdempotencyKey | boolean | true | Attach a generated key to every trigger and batch item that has none. |
maxRetries | number | 3 | Total attempts for trigger and triggerBatch, including the first. |
encrypted is a deprecated alias for useTLS; setting both throws. encryptionMasterKey (a raw
32-character string) is deprecated in favour of encryptionMasterKeyBase64.
Build a client from a single connection URL kept in your secret manager:
// SOCKUDO_URL=https://app-key:app-secret@realtime-api.example.com/apps/12345export const sockudo = Sockudo.forURL(process.env.SOCKUDO_URL!, { timeout: 5_000,});forURL takes the scheme, host, port, key, and secret from the URL and parses the last path segment
as an integer app ID, so use it only with numeric app IDs. Never write the URL to logs; it contains
the secret.
Why the secret stays on the server
The app secret signs every HTTP API call and every channel and user authorization. Anyone holding it can publish to any channel, read history, register push devices, and impersonate any user on a presence channel. Load it from a secret manager or environment variable at startup and keep it out of browser bundles, mobile apps, and logs.
Publish an event
import { sockudo } from "./sockudo";
const response = await sockudo.trigger( "orders", "order.created", { id: "ord_123", total: 4200 }, { idempotency_key: "order.created:tenant-42:ord_123:v1" },);
console.log(response.status, response.idempotencyKey);trigger(channels, event, data, params?) resolves to the node-fetch Response from the server,
with an idempotencyKey property set to the key that was sent. Non-string data is serialized with
JSON.stringify; strings are sent as is. Event names longer than 200 characters and invalid channel
names throw before any request is made.
params accepts:
| Param | Description |
|---|---|
socket_id | Exclude this connection from delivery. Must look like 123.456. |
info | Comma-separated attributes to return, such as subscription_count or user_count. |
idempotency_key | Stable key for this logical publish, or true for a random UUID. |
Pass socket_id when the sender has already applied the change optimistically. The server delivers
to every subscriber except that connection, so the originating client does not process its own
update twice.
Publish to many channels or in a batch
Pass an array to send the same event to several channels in one request:
await sockudo.trigger( ["tenant-42-orders", "user-7-orders"], "order.updated", { id: "ord_124", status: "paid" }, { socket_id: req.body.socket_id, idempotency_key: "order.paid:tenant-42:ord_124:v3", },);Use triggerBatch when several independent events can share one HTTP request:
await sockudo.triggerBatch([ { channel: "orders", name: "order.created", data: { id: "ord_125" }, idempotency_key: "order.created:tenant-42:ord_125:v1", }, { channel: "private-user-7", name: "order.receipt", data: { id: "ord_125" }, idempotency_key: "order.receipt:tenant-42:ord_125:v1", },]);Limits:
- The SDK rejects more than 100 channels per
triggerbefore sending. - The server’s defaults are
[event_limits] max_channels_at_once = 100,max_batch_size = 10,max_payload_in_kb = 100, andmax_name_length = 200. The SDK does not check batch size or payload size, so oversized requests fail with a4xxfrom the server. private-encrypted-*channels can only be published one channel pertriggercall; mixing an encrypted channel into a multi-channel publish throws. Batch items are encrypted individually.
Idempotency and retries
A timeout does not tell you whether Sockudo published the event. The request may have failed before it arrived, or the server may have published and the response was lost. Retrying without a key can deliver the event twice; an idempotency key lets the server recognise the retry.
Server semantics:
- The key can be sent as the body field
idempotency_keyor theX-Idempotency-Keyheader; the body field wins when both are present.triggersends the key in both. [idempotency]defaults:enabled = true,ttl_seconds = 120,max_key_length = 128. Empty keys are rejected.- A duplicate inside the TTL returns the original cached
200response without publishing again. - In a batch,
X-Idempotency-Keyidentifies the whole batch and each item’sidempotency_keyidentifies only that event; the two key domains do not collide. - If the coordination backend is unavailable, the server returns
503 service_unavailable. A concurrent retry while the first attempt is still in flight gets503 backpressurewithRetry-After: 1. Retry both with the same key.
A key names a logical operation, such as order.created:tenant-42:ord_123:v1, not an HTTP attempt.
Never reuse a key for a different payload.
How this SDK sets keys:
| Mechanism | Scope | Survives an application-level retry? |
|---|---|---|
idempotency_key: "..." on trigger or a batch item | One publish or batch item | Yes, when derived from business data |
autoIdempotencyKey (default true) | {processId}:{serial} per trigger; {processId}:{serial}:{index} per batch item | No, it covers only the SDK’s own retries |
idempotency_key: true | A new UUID for every request attempt | No, and not across the SDK’s own retries either |
triggerBatch sends keys per item only; it does not send a batch-level X-Idempotency-Key. The
response exposes the keys it sent as response.idempotencyKeys.
trigger and triggerBatch retry automatically, immediately and without backoff, up to
maxRetries total attempts, when the request fails with a network error or a 5xx status. They do
not retry 4xx responses (including 429) or requests aborted by timeout. Every attempt reuses
the same idempotency key, except when you pass idempotency_key: true. Other methods, such as
get, post, history, and push calls, do not retry.
Authorize private and presence channels
When a client subscribes to a private- or presence- channel, it asks your backend for a
signature. authorizeChannel only produces that signature; it does not decide whether the user may
join. Your route must check the session, decide whether this user may access this exact channel, and
take presence identity from your own user record, never from the request body.
import express from "express";import { sockudo } from "./sockudo";import { requireUser, canAccessChannel } from "./auth";
const app = express();
app.post( "/sockudo/auth", express.urlencoded({ extended: false }), async (req, res) => { const user = await requireUser(req); // your session check if (!user) return res.status(401).end();
const { socket_id, channel_name } = req.body; if (typeof socket_id !== "string" || typeof channel_name !== "string") { return res.status(400).end(); } if (!(await canAccessChannel(user, channel_name))) { return res.status(403).end(); }
try { if (channel_name.startsWith("presence-")) { return res.json( sockudo.authorizeChannel(socket_id, channel_name, { user_id: user.id, user_info: { name: user.displayName }, }), ); } return res.json(sockudo.authorizeChannel(socket_id, channel_name)); } catch { // Malformed socket_id or channel name. return res.status(400).end(); } },);authorizeChannel(socketId, channel, presenceData?) validates the socket ID and channel name (it
throws on invalid input) and returns { auth, channel_data?, shared_secret? }. channel_data is
present when you pass presence data; shared_secret is present for private-encrypted-* channels.
authenticate is a deprecated alias.
User authentication
Clients sign in to receive user-targeted events and to be identifiable for
terminateUserConnections. Expose a separate authenticated endpoint:
app.post( "/sockudo/user-auth", express.urlencoded({ extended: false }), async (req, res) => { const user = await requireUser(req); if (!user) return res.status(401).end();
res.json( sockudo.authenticateUser(req.body.socket_id, { id: user.id, user_info: { name: user.displayName }, }), ); },);authenticateUser(socketId, userData) requires a non-empty userData.id and returns
{ auth, user_data }. Send an event to every connection signed in as that user with
sockudo.sendToUser(userId, event, data).
Encrypted channels
For private-encrypted-* channels, configure encryptionMasterKeyBase64. The SDK then encrypts
published data with a per-channel key derived from the master key and returns that key as
shared_secret in the auth response, so Sockudo only ever sees ciphertext. Generate a key with
openssl rand -base64 32 and store and rotate it like the app secret.
Authorize and publish to a given encrypted channel with the same SDK; each SDK derives the channel key from the master key in its own way.
Terminate user connections
Disconnect every socket for a compromised or changed user, or ask them to reconnect and re-authenticate:
await sockudo.terminateUserConnections("user-42");await sockudo.forceReconnectUser("user-42");Validate webhooks
Sockudo signs each webhook with HMAC-SHA256 over the exact request body bytes and sends the key and
signature in X-Pusher-Key and X-Pusher-Signature. Parsing the body to JSON and serializing it
again changes whitespace and key order, so the signature no longer matches. Capture the raw body on
the webhook route before any global JSON parser consumes it.
app.post( "/sockudo/webhook", express.raw({ type: "application/json", limit: "1mb" }), (req, res) => { const webhook = sockudo.webhook({ rawBody: req.body.toString("utf8"), headers: req.headers, });
if (!webhook.isValid()) { return res.status(401).send("invalid signature"); }
// Acknowledge fast; process asynchronously and idempotently. enqueueWebhookEvents(webhook.getTime(), webhook.getEvents()); return res.sendStatus(200); },);webhook({ rawBody, headers }) expects lowercase header names, as Express provides them.
isValid() returns false unless the content-type is application/json, the body parses as
JSON, the key matches, and the signature verifies with a constant-time comparison. getEvents() and
getTime() throw Sockudo.WebHookError for an invalid body.
During key rotation, pass the previous credentials so both are accepted for a bounded overlap window:
webhook.isValid([{ key: process.env.OLD_SOCKUDO_KEY!, secret: process.env.OLD_SOCKUDO_SECRET! }]);Sockudo may retry delivery, so acknowledge quickly and make processing idempotent. Do not log the raw body or the signature.
Channel state and history
Channel state has no typed helpers; use the signed get helper, which resolves to a Response:
const channels = await ( await sockudo.get({ path: "/channels", params: { filter_by_prefix: "presence-" } })).json();
const info = await ( await sockudo.get({ path: "/channels/orders", params: { info: "subscription_count" } })).json();
const members = await (await sockudo.get({ path: "/channels/presence-lobby/users" })).json();State endpoints describe current occupancy. Use them for diagnostics and dashboards, not as an authorization database.
History
let page = await sockudo.channelHistory("orders", { limit: 50, direction: "newest_first",});
while (page.has_more && page.next_cursor) { page = await sockudo.channelHistory("orders", { cursor: page.next_cursor });}channelHistory resolves to a typed HistoryPage with items, has_more, next_cursor,
bounds, and continuity. It also accepts start_serial, end_serial, start_time_ms, and
end_time_ms. Cursors are opaque: pass next_cursor back unchanged and never build one yourself.
Presence history
const transitions = await sockudo.channelPresenceHistory("presence-lobby", { limit: 100, direction: "oldest_first",});
const snapshot = await sockudo.channelPresenceSnapshot("presence-lobby", { at_time_ms: Date.now() - 60_000,});Presence history returns member_added and member_removed transitions with their cause; the
snapshot replays them to reconstruct membership at a time or serial. Both require a presence-
channel and throw otherwise. See History and recovery.
Versioned messages and annotations
When versioned messages are enabled for a channel, publishes receive a message_serial, and you can
read and mutate the message by that serial:
const { item } = await sockudo.getMessage("chat-room-1", messageSerial);
const versions = await sockudo.getMessageVersions("chat-room-1", messageSerial, { limit: 20 });
await sockudo.updateMessage("chat-room-1", messageSerial, { data: JSON.stringify({ text: "Edited text" }),});
await sockudo.appendMessage("chat-room-1", messageSerial, { data: " more text" });
await sockudo.deleteMessage("chat-room-1", messageSerial);Mutations resolve to a MutationResponse with message_serial, action, accepted,
version_serial, history_serial, delivery_serial, and status. appendMessage requires a
string data fragment. Field semantics, op_id replay, and authorization rules are described in
Mutable messages.
Annotations attach reactions and other typed metadata to a message:
const { annotationSerial } = await sockudo.publishAnnotation("chat-room-1", messageSerial, { type: "reactions:distinct.v1", name: "thumbs-up", clientId: "user-42",});
const annotations = await sockudo.listAnnotations("chat-room-1", messageSerial, { limit: 50 });
await sockudo.deleteAnnotation("chat-room-1", messageSerial, annotationSerial);Push notifications
Register devices and publish notifications from the backend so app secrets and provider credentials
never reach a browser or mobile app. Push helpers send the push-admin capability header.
import Sockudo from "sockudo";import { sockudo } from "./sockudo";
const registration = await sockudo.activateDevice({ appId: process.env.SOCKUDO_APP_ID!, // replaced by the app in the URL id: "device-123", clientId: "user-42", formFactor: "phone", platform: "android", deviceSecret: "issued-by-server", // replaced on push-admin registration timezone: "Europe/Bucharest", locale: "en-US", push: { recipient: { transportType: "gcm", registrationToken: fcmToken }, state: "ACTIVE", },});
// Returned on first registration (or rotation); hand it to the device.const deviceIdentityToken = registration.deviceIdentityToken;
await sockudo.upsertChannelPushSubscription({ appId: process.env.SOCKUDO_APP_ID!, channel: "orders", deviceId: "device-123", clientId: "user-42", provider: "fcm", tokenHash: registration.tokenHash, // The bundled type marks credentialVersion as required; the server treats it as optional.} as Sockudo.PushChannelSubscription);
const accepted = await sockudo.publishPush({ publishId: "order-ord_123-packed", recipients: [{ type: "channel", channel: "orders" }], payload: { title: "Order updated", body: "Order ord_123 is packed", },});
const status = await sockudo.getPublishStatus(accepted.publishId!);publishPush always sends sync: false, so the server admits the request and fans out
asynchronously. The 202 response is an admission record (publishId, status,
expectedRecipients, fanoutRegime), not a delivery receipt; poll getPublishStatus or consume
delivery callbacks for outcomes. A stable publishId makes a retried publish return the original
admission instead of sending twice.
| Area | Methods |
|---|---|
| Devices | activateDevice, updateDeviceRegistration, getDeviceRegistration, listDeviceRegistrations, deleteDeviceRegistration, removeDeviceRegistrationsByClient |
| Channel subscriptions | upsertChannelPushSubscription, listChannelPushSubscriptions, listChannelPushSubscriptionChannels, deleteChannelPushSubscriptions |
| Credentials | putPushCredential, listPushCredentials |
| Publish | publishPush, publishPushBatch, schedulePush (requires notBeforeMs), getPublishStatus, cancelScheduledPush, postPushDeliveryStatus |
| Live Activities | createApnsLiveActivityChannel, getApnsLiveActivityChannel, listApnsLiveActivityChannels, deleteApnsLiveActivityChannel |
See Push notifications for provider setup and recipient types.
Apple Live Activities
For iOS 16.1+ direct Live Activities, use an apnsLiveActivity recipient and the typed
liveActivity payload. For iOS 18 shared-content audiences, create one APNs channel and publish one
O(1) broadcast request:
const channel = await sockudo.createApnsLiveActivityChannel("mostRecent");
await sockudo.publishPush({ publishId: "match-90-score-3-1", recipients: [{ type: "recipient", recipient: { transportType: "apnsLiveActivityBroadcast", channelId: channel.channelId, storagePolicy: channel.storagePolicy, }, }], payload: {}, liveActivity: { event: "update", timestamp: Math.floor(Date.now() / 1000), contentState: { home: 3, away: 1 }, priority: "conservePower", },});See Apple Live Activities for start and end fields, storage policy, token rotation, sandbox endpoints, and operating limits.
Errors and timeouts
Two kinds of failure reach your code:
- HTTP and network failures reject with
Sockudo.RequestError.statusholds the HTTP status for responses>= 400and isundefinedfor network errors and timeouts, whereerrorholds the underlying cause.bodyholds the response text. - Invalid input throws synchronously with a plain
Error: a malformedsocket_idor channel name, an event name over 200 characters, more than 100 channels, a multi-channel encrypted publish, or a missing encryption master key.
import Sockudo from "sockudo";import { sockudo } from "./sockudo";
const key = `order.created:${tenantId}:${orderId}:v1`;
try { await sockudo.trigger("orders", "order.created", payload, { idempotency_key: key });} catch (error) { if (error instanceof Sockudo.RequestError) { const status = error.status; if (status === undefined || status === 429 || status >= 500) { // Built-in retries are exhausted or skipped: retry later with the SAME key. await retryLater(key); return; } // 400, 401, 403, 413: retrying unchanged will not help. } throw error;}Without timeout, a request can hang until the socket gives up; set it below the route or job
deadline, keeping in mind that trigger can make up to maxRetries attempts. Retry network errors,
429, and 5xx with bounded, jittered backoff and the same idempotency key. Do not retry 400,
401, 403, or 413 unchanged.