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.

10 min read
View .mdEdit on GitHub

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 get requests, 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

Terminal
npm install sockudo
# or: pnpm add sockudo
# or: yarn add sockudo
# or: bun add sockudo

The 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:

Terminal
cd server-sdks/sockudo-http-node
npm install
npm run build

The module exports the Sockudo class itself (module.exports = Sockudo), not a named export:

import.ts
// ESM, or TypeScript with esModuleInterop
import Sockudo from "sockudo";
// CommonJS
// const Sockudo = require("sockudo");

Configure the client

src/sockudo.ts
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,
});
OptionTypeDefaultDescription
appIdstringrequiredSockudo app ID; used in every /apps/{appId}/... path.
keystringrequiredApp key, sent as auth_key and used as the prefix of auth signatures.
secretstringrequiredApp secret used for HMAC-SHA256 signing. Never send it to a client.
hoststring"localhost"HTTP API host without a scheme.
portstringscheme defaultHTTP API port. When omitted, the URL has no port, so 80 or 443 applies.
useTLSbooleanfalseUse https. Enable it whenever traffic leaves a trusted network.
timeoutnumbernonePer-request timeout in milliseconds. Without it, requests wait for the socket.
agenthttp.AgentNode defaultCustom agent for keep-alive pools, proxies, or TLS settings.
encryptionMasterKeyBase64stringnoneBase64 key that must decode to exactly 32 bytes; validated in the constructor.
autoIdempotencyKeybooleantrueAttach a generated key to every trigger and batch item that has none.
maxRetriesnumber3Total 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:

src/sockudo.ts
// SOCKUDO_URL=https://app-key:app-secret@realtime-api.example.com/apps/12345
export 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

src/orders.ts
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:

ParamDescription
socket_idExclude this connection from delivery. Must look like 123.456.
infoComma-separated attributes to return, such as subscription_count or user_count.
idempotency_keyStable 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:

src/orders.ts
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:

src/orders.ts
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 trigger before sending.
  • The server’s defaults are [event_limits] max_channels_at_once = 100, max_batch_size = 10, max_payload_in_kb = 100, and max_name_length = 200. The SDK does not check batch size or payload size, so oversized requests fail with a 4xx from the server.
  • private-encrypted-* channels can only be published one channel per trigger call; 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_key or the X-Idempotency-Key header; the body field wins when both are present. trigger sends 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 200 response without publishing again.
  • In a batch, X-Idempotency-Key identifies the whole batch and each item’s idempotency_key identifies 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 gets 503 backpressure with Retry-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:

MechanismScopeSurvives an application-level retry?
idempotency_key: "..." on trigger or a batch itemOne publish or batch itemYes, when derived from business data
autoIdempotencyKey (default true){processId}:{serial} per trigger; {processId}:{serial}:{index} per batch itemNo, it covers only the SDK’s own retries
idempotency_key: trueA new UUID for every request attemptNo, 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.

src/server.ts
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:

src/server.ts
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:

src/admin.ts
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.

src/server.ts
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:

src/server.ts
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:

src/state.ts
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

src/history.ts
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

src/history.ts
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:

src/messages.ts
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:

src/messages.ts
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.

src/push.ts
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.

AreaMethods
DevicesactivateDevice, updateDeviceRegistration, getDeviceRegistration, listDeviceRegistrations, deleteDeviceRegistration, removeDeviceRegistrationsByClient
Channel subscriptionsupsertChannelPushSubscription, listChannelPushSubscriptions, listChannelPushSubscriptionChannels, deleteChannelPushSubscriptions
CredentialsputPushCredential, listPushCredentials
PublishpublishPush, publishPushBatch, schedulePush (requires notBeforeMs), getPublishStatus, cancelScheduledPush, postPushDeliveryStatus
Live ActivitiescreateApnsLiveActivityChannel, 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:

src/live-activity.ts
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. status holds the HTTP status for responses >= 400 and is undefined for network errors and timeouts, where error holds the underlying cause. body holds the response text.
  • Invalid input throws synchronously with a plain Error: a malformed socket_id or channel name, an event name over 200 characters, more than 100 channels, a multi-channel encrypted publish, or a missing encryption master key.
src/orders.ts
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.

Next steps