Call Realtime from your backend

@lessly/realtime is the Node package your backend uses to talk to Realtime. It publishes messages, reads history, mints capability tokens for your users, and manages namespaces, grants, presence and webhooks. The current published version is 0.5.0.

How much of that a given client reaches is decided by the credential you construct it with. An SDK Identity token reaches every resource in the package; a product public key reaches the five public routes and no management resource. The boundary is below.

It is a server-side package. It carries a credential, so it must never be bundled into a browser — for the browser see the browser client.

Install and construct

npm install @lessly/realtime

The package targets Node 22 and above and uses the global fetch. Realtime takes one of two construction forms, one per credential. Passing both throws cannot combine a bearer token with apiKey — pick one auth mode.

With a product public key

The SDK builds the base URL for you as {edgeUrl}/{productId}/realtime and sends the key as Authorization: Bearer <apiKey>. The option is still named apiKey; what changed in 0.5.0 is the header it travels in.

import { Realtime } from '@lessly/realtime'

const realtime = new Realtime({
  apiKey: process.env.REALTIME_API_KEY!,   // lpk_… , or an older rtk_… key
  productId: process.env.PRODUCT_ID!,
})

DEFAULT_EDGE_URL is exported and is https://public.lessly.com — production.

.com and .dev are separate environments with separate databases, so a key created on production fails with 401 public_key_invalid against a .dev origin — and nothing in that response says the host was the problem. Set edgeUrl only to point at a non-production environment.

An empty apiKey or productId throws. The message never contains the credential.

With an SDK Identity token

The other form takes an SDK Identity token as the first argument and an explicit baseUrl. The SDK sends the token as Authorization: Bearer <token>. This is the credential the management resources answer to.

const realtime = new Realtime(process.env.REALTIME_TOKEN!, {
  baseUrl: process.env.REALTIME_BASE_URL!,
})

An empty token or an empty baseUrl throws. timeout, retry and headers mean the same thing in both forms.

The constructed client exposes six resources as readonly properties, whichever credential it carries: messages, tokens, namespaces, grants, presence, webhooks.

The access boundary

The resources are the same; what answers them is not. An SDK Identity token reaches every method on this page. A product public key reaches the public HTTP routes, and those serve these five methods:

The rest of the client — tokens.create, the namespaces, grants and webhooks resources, and presence.enter / update / leave — is outside what a product public key reaches. The management resources answer to an SDK Identity token, and the same records are edited by hand in the workspace, under Realtime → Namespaces, Realtime → Grants and Realtime → Webhooks.

The key itself is on neither list. Public keys are created, scoped and revoked by a product Owner or Admin on the Product → Settings → Public Access page; no method of this SDK mints, lists or revokes one. Presence is entered and updated from the browser client, on the connection that is present.

Publish and read history

publish(channel: string, data: unknown): Promise<PublishMessageResponse>
history(channel: string, query: HistoryQuery): Promise<HistoryGetResponse>

publish sends data to every subscriber of channel. The response is { channel, published: true }, plus offset and epoch when the namespace history policy stored the message.

const result = await realtime.messages.publish('chat:room-1', {
  text: 'hello',
  from: 'ada',
})
// result.offset — pass it to a client so it can resume from here

history reads back what was sent. The query is either a cursor or a window:

type HistoryQuery =
  | { cursor: { offset: string; epoch: string } }
  | { lastN?: number; lastMs?: number }

const page = await realtime.messages.history('chat:room-1', { lastN: 50 })
if (!page.recovered) {
  // the cursor epoch no longer matches, or the entries aged out — resync
}
for (const entry of page.entries) {
  // entry.id, entry.ts, entry.offset, and entry.data or entry.ref
}

recovered is false when the cursor cannot be honoured; treat that as “start again from a snapshot”, covered in history. An entry carries either an inline data payload or a ref ({ bucket_key, size, content_type }) when the payload was too large to inline.

Mint tokens

Two methods mint, and only one of them is the one you want:

issue takes the subject, the concrete channels and the operations the user may perform on each:

interface IssueTokenInput {
  subject: string                  // 1..128 chars
  channels: { name: string; ops: ChannelOp[] }[]   // 1..32 concrete channels, no wildcards
  ttlSeconds?: number              // 60..3600, defaults to 3600 server-side
}

type ChannelOp = 'subscribe' | 'publish' | 'presence' | 'history'

const { token, gatewayUrl, expiresAt } = await realtime.tokens.issue({
  subject: user.id,
  channels: [{ name: 'chat:room-1', ops: ['subscribe', 'history', 'presence'] }],
  ttlSeconds: 900,
})

The declared operations are narrowed by namespace policy when the token is minted, and a request whose capabilities are stripped entirely fails with 422. Return token and gatewayUrl to the browser; expiresAt is the ISO-8601 expiry. See authentication.

create mints a token for the calling credential itself, optionally scoped to a list of channels, and returns { token, gatewayUrl }. It does not mint for one of your end users and is not reachable with a product public key — use issue.

Retries

Every request goes through the retry policy.

interface RetryConfig {
  maxAttempts?: number   // default 3
  initialDelay?: number  // default 500 (ms)
  maxDelay?: number      // default 5000 (ms)
}

A request is retried when it fails with HTTP 429, any status of 500 or above, or a network error (status code 0). Every other failure is thrown immediately.

The delay before the next attempt is initialDelay * 2 ** attempt, capped at maxDelay. When the response carried a Retry-After header, that value wins and the SDK waits exactly that many seconds instead. maxAttempts counts the first attempt, so the default of 3 means one call and at most two retries; the error from the last attempt is thrown.

Errors

Failures throw RealtimeError or one of its subclasses. Every instance carries:

The subclass is chosen by status:

NetworkError covers a failed or timed-out connection. It has status code 0 and error type Network Error; a timeout reports Request timed out after {timeout}ms.

import { RateLimitError, RealtimeError } from '@lessly/realtime'

try {
  await realtime.messages.publish('chat:room-1', { text: 'hello' })
} catch (error) {
  if (error instanceof RateLimitError) {
    // error.retryAfter is the server's advice, in seconds
  } else if (error instanceof RealtimeError) {
    console.error(error.statusCode, error.errorType, error.message)
  }
}

parseErrorBody(status, body) and createErrorFromResponse(status, body, retryAfter?) are exported too, for code that handles raw HTTP responses itself.

Namespaces, grants and webhooks

These methods answer to an SDK Identity token; a product public key does not reach them. The same records are created and edited by hand in the workspace, under Realtime → Namespaces, Realtime → Grants and Realtime → Webhooks. The shapes are documented here because the policy they carry decides what your channels allow, and because your endpoint has to handle what a webhook delivers.

create(input: { name: string } & NamespacePolicyInput): Promise<NamespaceView>
list(): Promise<NamespaceView[]>
get(name: string): Promise<NamespaceView>
update(name: string, patch: NamespacePolicyInput): Promise<NamespaceView>
delete(name: string): Promise<{ deleted: true }>

The policy fields, all optional on both create and update:

NamespaceView returns the resolved policy plus id, name, createdAt and updatedAt. The rest of the namespace resource is list(), get(name) and delete(name), which answers { deleted: true }.

subscribeProxySecret — the full signing secret for the subscribe proxy — appears only in the response that set or changed subscribeProxyUrl. Afterwards only subscribeProxySecretPrefix is visible, and it is null when no proxy URL is set.

A grant is a durable permission: a subject, a channel pattern and a set of operations. The resource carries create(input), list(filter?) — optionally filtered by subject — and revoke(id), which answers { revoked: true }. CreateGrantInput is { subject, pattern, ops }, where subject is an identity id or * for every identity in the product, and pattern is a channel pattern such as chat:* in which * matches exactly one segment. GrantView is { id, subject, pattern, ops, createdAt }. The pattern rules are on Realtime.

The webhooks resource carries create, list, get, update, delete, rotateSecret and deliveries.

• create takes { url, events, description? } and answers { webhook, secret }, where secret is the full signing secret and is returned exactly once, at creation.
• update accepts url, events, description (null clears it) and active. An inactive webhook receives no deliveries.
• rotateSecret returns the new secret — again only once — its prefix, and previousExpiresAt, the moment the rotated-out secret stops verifying. Until then both secrets verify, so a receiver can be updated without dropping deliveries.
• WebhookView never contains a secret. It lists secrets as metadata only: { prefix, expiresAt, createdAt }, where expiresAt is null for the current signer and the prefix matches the X-Realtime-Key header on a delivery.
• deliveries returns the recent attempts, newest first, each as { id, eventType, eventId, status, attempts, responseStatus, lastError, lastAttemptAt, createdAt } with status one of pending, succeeded, failed.

What a delivery looks like and how to verify it is on webhooks.

The presence resource reads a roster with get(channel) and stats(channel); its enter, update and leave methods are not reachable with a product public key, because a member enters presence from the browser client, on the connection that is present. See presence.

Next steps

• Connect a browser tab: the other half of the loop.
• Authenticate your backend and your users: what the token you mint can and cannot carry.
• Replay what a client missed: cursors, windows and what a refused recovery means.
• Call the public HTTP routes: the same five routes without the SDK.
• Look up a limit or an error: quotas, status codes and payload sizes.