TypeScript realtime SDK reference

Installation

npm install @insforge/sdk@latest

yarn add @insforge/sdk@latest

pnpm add @insforge/sdk@latest

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.insforge.app',
  anonKey: 'your-anon-key'  // Optional: for public/unauthenticated requests
});

Find the anon key with npx @insforge/cli secrets get ANON_KEY, or in the dashboard: click Install and open API Keys.

Mental model

The TypeScript SDK opens one Socket.IO connection to your InsForge backend. You subscribe to named channels, listen for event names, and optionally publish events back to channels you have joined. Events can come from two places:

Database triggers that call realtime.publish(channel, event, payload).
Clients that call insforge.realtime.publish(channel, event, payload).

For the backend channel and RLS model, see Realtime overview.

Quick start

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.insforge.app',
  anonKey: 'your-anon-key'
});

insforge.realtime.on('connect', () => {
  console.log('Connected:', insforge.realtime.socketId);
});

insforge.realtime.on('error', (error) => {
  console.error(error.code, error.message);
});

await insforge.realtime.connect();

const subscription = await insforge.realtime.subscribe('order:123');

if (!subscription.ok) {
  throw new Error(subscription.error.message);
}

insforge.realtime.on('status_changed', (message) => {
  console.log(message.status);
  console.log(message.meta.messageId);
});

Register connect, disconnect, connect_error, and error handlers before calling connect() so early connection failures are visible.

connect()

Establish a WebSocket connection.

await insforge.realtime.connect();

Returns:

Promise<void>

Notes:

The SDK includes the current auth token when one exists. If there is no signed-in user, it can use the configured anon key.
Multiple connect() calls while a connection is already in progress reuse the same connection promise.
The connection attempt times out after 10 seconds.

Subscribe to a channel and receive the current presence snapshot.

const response = await insforge.realtime.subscribe('chat:room-1');

if (response.ok) {
  console.log(response.channel);
  console.log(response.presence.members);
} else {
  console.error(response.error.code, response.error.message);
}

Parameters:

Parameter	Type	Description
`channel`	`string`	Resolved channel name, such as `orders`, `order:123`, or `chat:room-1`.

Returns:

type SubscribeResponse =
  | {
      ok: true;
      channel: string;
      presence: {
        members: PresenceMember[];
      };
    }
  | {
      ok: false;
      channel: string;
      error: {
        code: string;
        message: string;
      };
    };

subscribe() auto-connects if needed. Calling connect() explicitly is still recommended so connection event handlers are already attached. subscribe() is idempotent: calling it again for a channel you already joined re-requests the subscription and resolves the server’s current presence snapshot. The server tracks presence per logical member, so repeated subscribes never produce duplicate members or spurious presence:join events.

publish()

Publish an event to a channel.

await insforge.realtime.publish('chat:room-1', 'new_message', {
  text: 'Hello',
  sentAt: new Date().toISOString()
});

Parameters:

Parameter	Type	Description
`channel`	`string`	Channel to publish to. The client must already be subscribed.
`event`	`string`	Event name that subscribers listen for.
`payload`	`Record<string, unknown>`	JSON-serializable message payload.

Publishing requires a prior successful subscription to the same channel. If RLS is enabled on realtime.messages, publish is also checked against INSERT policies.

Publish failures are emitted through the error event.

on()

Listen for custom events, connection events, presence events, and realtime errors.

insforge.realtime.on('new_message', (message) => {
  console.log(message.text);
  console.log(message.meta.senderType);
});

Reserved events:

Event	Payload	Description
`connect`	None	The WebSocket connected.
`connect_error`	`Error`	Initial connection or reconnect failed.
`disconnect`	`string`	The WebSocket disconnected.
`error`	`RealtimeErrorPayload`	Subscribe or publish failed.
`presence:join`	`PresenceJoinMessage`	A logical member became present in a channel.
`presence:leave`	`PresenceLeaveMessage`	A logical member is no longer present in a channel.
`presence:sync`	`PresenceSyncEvent`	A fresh presence snapshot for a channel. Fired on every successful subscribe, including automatic resubscribes after a reconnect.

once()

Listen for an event once, then remove the listener automatically.

insforge.realtime.once('checkout_completed', (message) => {
  console.log('Completed:', message.orderId);
});

off()

Remove an event listener.

function handleStatus(message: OrderStatusMessage) {
  console.log(message.status);
}

insforge.realtime.on('status_changed', handleStatus);
insforge.realtime.off('status_changed', handleStatus);

unsubscribe()

Leave a channel.

insforge.realtime.unsubscribe('chat:room-1');

unsubscribe() is fire-and-forget. If this was the final socket for a logical member, other subscribers receive presence:leave.

disconnect()

Close the WebSocket and clear local subscriptions.

insforge.realtime.disconnect();

Message shape

Delivered messages include your payload fields plus server metadata.

import type { SocketMessage } from '@insforge/sdk';

interface OrderStatusMessage extends SocketMessage {
  id: string;
  status: string;
}

insforge.realtime.on<OrderStatusMessage>('status_changed', (message) => {
  console.log(message.id);
  console.log(message.status);
  console.log(message.meta.messageId);
  console.log(message.meta.senderType);
  console.log(message.meta.senderId);
  console.log(message.meta.timestamp);
});

Metadata:

interface SocketMessageMeta {
  channel?: string;
  messageId: string;
  senderType: 'system' | 'user';
  senderId?: string;
  timestamp: string;
}

senderType is system for database-triggered messages and user for client-published messages.

Presence

A successful subscription returns the current presence snapshot.

const response = await insforge.realtime.subscribe('chat:room-1');

if (response.ok) {
  for (const member of response.presence.members) {
    console.log(member.type, member.presenceId, member.joinedAt);
  }
}

Presence member:

type PresenceMember =
  | {
      type: 'user';
      presenceId: string;
      joinedAt: string;
    }
  | {
      type: 'anonymous';
      presenceId: string;
      joinedAt: string;
    };

Listen for changes:

insforge.realtime.on('presence:join', (message) => {
  console.log('Joined:', message.member.presenceId);
});

insforge.realtime.on('presence:leave', (message) => {
  console.log('Left:', message.member.presenceId);
});

Reading presence state

The SDK maintains the member list for every subscribed channel — seeded from the subscribe snapshot and kept current from presence:join/presence:leave deltas and reconnect resyncs. Read it at any time instead of merging deltas yourself:

const members = insforge.realtime.getPresenceState('chat:room-1');

Returns an empty array for channels you are not subscribed to. While the socket is briefly disconnected it holds the last known state, replaced by a fresh snapshot as soon as the channel resubscribes.

Reconnects

When the connection drops, the SDK automatically resubscribes to every channel on reconnect and emits presence:sync with the fresh presence snapshot for each. Members who joined or left while you were disconnected produce no individual presence:join/presence:leave deltas, so replace — don’t merge — any state you keep outside the SDK:

import type { PresenceSyncEvent } from '@insforge/sdk';

insforge.realtime.on<PresenceSyncEvent>('presence:sync', ({ channel, presence }) => {
  replaceMembers(channel, presence.members);
});

If you render directly from getPresenceState(), presence:sync is simply your re-render signal. If a resubscribe is rejected (for example the user’s access was revoked while disconnected), the SDK drops the channel and emits error instead.

Token refreshes

When the signed-in user’s access token refreshes, the SDK leaves an established socket connected — there is no in-band re-authentication, reconnect, or presence churn. A later initial connection or network reconnect obtains the latest access token before its handshake. Sign-in, sign-out, or switching users reconnects the socket under the new identity. Access reductions apply lazily on a live connection. Publishing is re-checked against RLS on every message, and new subscribes are re-checked at join time. Continued receipt on already-joined channels persists until the client unsubscribes or reconnects.

Properties

Property	Type	Description
`isConnected`	`boolean`	Whether the socket is currently connected.
`connectionState`	`'disconnected' \| 'connecting' \| 'connected'`	Current SDK connection state.
`socketId`	`string \| undefined`	Socket.IO ID when connected.
`getSubscribedChannels()`	`() => string[]`	Local list of subscribed channels.
`getPresenceState(channel)`	`(channel: string) => PresenceMember[]`	Current members of a subscribed channel, maintained by the SDK.

Error handling

insforge.realtime.on('connect_error', (error) => {
  console.error('Connection failed:', error.message);
});

insforge.realtime.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});

insforge.realtime.on('error', (error) => {
  console.error(error.channel, error.code, error.message);
});

Common realtime error codes:

Code	Meaning
`REALTIME_UNAUTHORIZED`	RLS or channel matching denied subscribe or publish.
`REALTIME_NOT_SUBSCRIBED`	The client tried to publish before subscribing to the channel.
`INTERNAL_ERROR`	The backend could not complete the realtime operation.

Complete example

const channel = `order:${orderId}`;

insforge.realtime.on('error', (error) => {
  console.error(error.code, error.message);
});

await insforge.realtime.connect();

const response = await insforge.realtime.subscribe(channel);

if (!response.ok) {
  throw new Error(response.error.message);
}

insforge.realtime.on('status_changed', (message) => {
  renderOrderStatus(message.status);
});

await insforge.realtime.publish(channel, 'customer_viewed', {
  orderId,
  viewedAt: new Date().toISOString()
});

function cleanup() {
  insforge.realtime.unsubscribe(channel);
  insforge.realtime.disconnect();
}

TypeScript

Swift

Kotlin

REST API

Examples

TypeScript realtime SDK reference

Installation

Mental model

Quick start

connect()

publish()

on()

once()

off()

unsubscribe()

disconnect()

Message shape

Presence

Reading presence state

Reconnects

Token refreshes

Properties

Error handling

Complete example

​Installation

​Mental model

​Quick start

​connect()

​subscribe()

​publish()

​on()

​once()

​off()

​unsubscribe()

​disconnect()

​Message shape

​Presence

​Reading presence state

​Reconnects

​Token refreshes

​Properties

​Error handling

​Complete example

Installation

Mental model

Quick start

connect()

subscribe()

publish()

on()

once()

off()

unsubscribe()

disconnect()

Message shape

Presence

Reading presence state

Reconnects

Token refreshes

Properties

Error handling

Complete example