Client API

npm install @useceleris/client

The package runs in browsers, Node.js 22.15+, Bun 1.3+ and Deno 2.5+. It ships as ESM with a tested CommonJS entry point. The only runtime dependency is Zod.

createClient(options)

function createClient(options: ClientOptions): Client;

createClient performs no network work. The SDK validates known options and strips unknown option keys at runtime. TypeScript callers should use only the documented options.

The timeout options must be integers from 1 to 900000, as JavaScript numbers in milliseconds. A value larger than 15 minutes gives a ConfigurationError. The two size options must also be positive safe integers. maximumReconnectAttempts must be an integer from 1 to 100. Any other value gives a ConfigurationError. Strings, bigint, fractional values, and non-finite values are invalid. The default URL is wss://realtime.useceleris.com. baseUrl is the realtime socket endpoint, not your HTTP credential endpoint.

Client

class Client {
  channel(reference: string): Channel;
}

channel() is side-effect free and returns a new connection handle on every call. A reference is 1–255 characters of [a-zA-Z0-9_-].

Channel

class Channel {
  readonly state: ChannelState;
  connect(options?: { signal?: AbortSignal }): Promise<void>;
  close(): Promise<void>;
  segment(segmentId: string): Segment;
  defaultSegment(): Segment; // segment("default")
  events(): ChannelEventHandler;
}

You can recover a failed channel when you call connect() again. You cannot recover a closed channel. The SDK does not automatically retry an initial connection failure. See Reconnection and Recovery for triggers, deadlines, retry budgets, and restored subscriptions.

A successful connect() automatically joins default. Use defaultSegment().onMessage(listener) to receive its messages. defaultSegment().subscribe() is not required. Read and write permissions still apply, and default membership does not include other segments or presence subscriptions. This automatic join also happens on reconnect.

Segment

class Segment {
  readonly segmentId: string;
  subscribe(): Subscription;
  onMessage(listener: MessageListener): () => void;
  onPresence(listener: (event: PresenceEvent) => void): () => void;
  publish(options: {
    payload: Uint8Array;
    messageId?: string;
    signal?: AbortSignal;
  }): Promise<void>;
  subscribePresence(): Subscription;
  presenceList(options: {
    page: number;
    perPage: number;
    signal?: AbortSignal;
  }): Promise<PresencePage>;
}

Payload helpers

function textPayload(value: string): Uint8Array;
function jsonPayload(value: unknown): Uint8Array;
function readText(payload: Uint8Array): string;
function readJson<T>(payload: Uint8Array): T; // asserts, does not validate

type PayloadCodec<T> = {
  encode(value: T): Uint8Array;
  decode(bytes: Uint8Array): T;
};

type BoundPayloadCodec<T> = {
  encodePayload(value: T): Uint8Array;
  readPayload(payload: Uint8Array): T;
};

function createPayloadCodec<T>(codec: PayloadCodec<T>): BoundPayloadCodec<T>;

jsonPayload throws ConfigurationError when JSON serialization fails. readText and readJson reject invalid UTF-8 or JSON. textPayload uses the platform's UTF-8 TextEncoder. A failure thrown by your own encode or decode propagates unchanged. No size check happens here: publish() enforces the encoded-command bound.

Types

type ChannelState =
  | "idle"
  | "connecting"
  | "connected"
  | "reconnecting"
  | "failed"
  | "closing"
  | "closed";

type ChannelError =
  ConfigurationError | ConnectionError | ProtocolError | ServerError;

type MessageMetadata = {
  readonly tokenReference: string;
  readonly segmentId: string;
  readonly messageId: string; // always present; the SDK generates one if you omit it
  readonly timestamp: bigint;
};

type MessageListener = (payload: Uint8Array, metadata: MessageMetadata) => void;

type PresenceEvent = {
  readonly segmentId: string;
  readonly tokenReference: string;
  readonly connectionId: string;
  readonly joined: boolean; // false = left
  readonly timestamp: bigint;
};

type PresencePage = {
  readonly segmentId: string;
  readonly total: number;
  readonly perPage: number;
  readonly currentPage: number;
  readonly from: number; // from > to past the last page
  readonly to: number;
  readonly connections: readonly PresenceConnection[];
};

type PresenceConnection = {
  readonly tokenReference: string;
  readonly connectionId: string;
  readonly timestamp: bigint;
};

type ServerNotice = {
  readonly timestamp: bigint;
  readonly payload: Uint8Array;
};

type RecoveryEvent = {
  readonly retryIndex: number;
  readonly possibleGaps: true;
  readonly possibleDuplicates: true;
};

type CredentialRequest = {
  readonly channelReference: string;
  readonly reason: "initial" | "reconnect";
  readonly disconnectedAt?: number;
  readonly replayLookbackMs?: number;
  readonly signal: AbortSignal;
};

type Credentials = { readonly payload: string; readonly signature: string };
type CredentialProvider = (request: CredentialRequest) => Promise<Credentials>;

interface Subscription {
  cancel(): void;
}

Numeric values

The protocol's Integer32 values decode to number. Integer64 values decode to bigint. A timestamp remains a bigint even when its value would fit in a safe JavaScript number. The SDK exposes PresenceEvent.joined as a boolean, not a numeric flag.

The SDK validates presence request values and does not coerce or clamp them. Use { page: 1, perPage: 25 }, not strings or bigint literals. Returned page figures do not need conversion before arithmetic. Empty pages can have from > to.

JSON.stringify() handles number fields directly but throws on bigint values. Use the serialization examples to convert timestamps, and any bigint values in error resources, to decimal strings. Do not convert every value with Number(), because that can lose precision.

ChannelEventHandler

interface ChannelEventHandler {
  onStateChange(listener: (state: ChannelState) => void): () => void;
  onRecovery(listener: (event: RecoveryEvent) => void): () => void;
  onNotice(listener: (notice: ServerNotice) => void): () => void;
  onError(listener: (error: ChannelError) => void): () => void;
  onMessage(listener: MessageListener): () => void;
}

Each method returns its own disposer. Listeners run synchronously in registration order. The SDK contains a synchronous failure and reports it through onError. The SDK also guards failures in onError callbacks against recursive error dispatch. Handle promise rejections inside asynchronous listener work yourself. A recovery event follows the connected state change. It does not signal replay completion. See Reconnection and Recovery.

onMessage receives all messages from all segments of the connection. It gets each message after the segment listeners, and it gets each message ID one time. All listeners of a message get the same payload. Do not change the payload. The function that onMessage returns removes only this listener. The other listeners and the subscriptions do not change, and when you call it again, it has no effect.

onNotice delivers raw server prose, such as subscription acknowledgments and refusals. It carries no segment id and no correlation id. Do not parse it.

Errors

There are four error classes. The SDK itself raises three: ConfigurationError (code: "Configuration"), ConnectionError (a code from the table below) and ProtocolError (with field and offset). Their messages say what failed and which rule or limit it broke, for example Invalid channel reference. Must not be empty., or a field path such as connectTimeoutMs. The messages never carry your input, credentials or server text. A ProtocolError message also names its field and byte offset. The fourth class, ServerError, carries an error that the server sent. The section below describes it. Match SDK errors on code and server errors on type, never on message text.

ProtocolError means the SDK could not decode one message. The SDK drops that message and reports the error, and the connection stays up. The SDK silently skips a command that this SDK version does not recognize, so a newer server cannot break a deployed client.

There is no Authentication code. No runtime exposes the WebSocket handshake status to script, so the SDK reports a rejected handshake as Transport and does not guess.

ServerError

type ServerErrorType =
  | "ParserError"
  | "SendError"
  | "PermissionDeniedError"
  | "RateLimitError"
  | "MessageSizeLimitError"
  | "InternalError";

type ServerErrorResource =
  null | string | number | bigint | readonly ServerErrorResource[];

class ServerError extends Error {
  readonly type: ServerErrorType | (string & {});
  readonly subType: string | null; // the command it answers, e.g. "PUB"
  readonly message: string; // the server's own text, unchanged
  readonly resource: ServerErrorResource; // what that command names, e.g. the segment
}

A ServerError is an error the server sent, with every field exactly as sent, and the connection stays up. It arrives through onError, after the call that caused it, except for a presence query error, which rejects presenceList() instead. type also accepts types a newer server adds, so switch on the six below and keep a default branch. ServerError has no code, so narrow with instanceof before you read code on an error from onError.

resource is not always a string. Integer32 resources are numbers, Integer64 resources are bigints, and arrays can nest these alongside strings and null. Narrow the value with typeof or Array.isArray() before you use it. Do not assume every numeric resource is a timestamp.

Limits

The SDK does not check the size of received messages. A message is already in the platform's buffer when it arrives, so the SDK processes whatever the server sends. A publish rejected by the server for your plan's size limit still counts toward your usage. A local encoded-command size rejection sends nothing.

What this SDK will not do

The SDK does not do these tasks:

• Confirm delivery. There are no receipts anywhere in the protocol.
• Keep a durable offline queue. The publish queue is in memory. It keeps publishes across a reconnect, but not after failed or close(). The SDK resends publishes only after a rate limit, once each, with their original ID.
• Provide durable history or global ordering. Replay is a bounded window, not a cursor.
• Sign anything, or expose a signing facility to the browser.