Client transport and SnaClient

SnaClient derives HTTP and WebSocket endpoints from a single baseUrl. It uses HTTP for state changes and CRUD, WebSocket for push events and permission requests, and SSE for long-running one-shot streams.

new SnaClient(options)

Signature

const client = new SnaClient({
  baseUrl: string;
  authToken?: string;
  ws?: boolean;
  http?: boolean;
  reconnect?: boolean;
  reconnectDelay?: number;
  maxReconnectAttempts?: number;
});

Options

Derived endpoints

Authentication behavior

When authToken is present, HTTP and SSE requests send Authorization: Bearer <authToken>. WebSocket connections attach the same token as ?token=<authToken> so browser runtimes can authenticate the upgrade. Keep baseUrl and authToken paired by passing the launcher's handle.connection object.

401 means the token is missing or does not match the server. 403 means the request came from a browser Origin that is not listed in the server's allowedOrigins.

Example

import { SnaClient } from "@sna-sdk/client";

const client = new SnaClient(handle.connection);

client.connect()

Signature

client.connect(): void

Starts the WebSocket connection. If the client is already connecting or connected, this is a no-op. The server may push sessions.snapshot immediately after connection, so register sessions.onSnapshot before calling connect when the UI depends on session state.

client.sessions.onSnapshot((sessions) => setSessions(sessions));
client.connect();

client.disconnect()

Signature

client.disconnect(): void

Closes the WebSocket connection and disables automatic reconnect. Pending low-level request promises reject with a disconnected error.

client.status / client.connected

Signature

client.status: "connecting" | "connected" | "disconnected"
client.connected: boolean

Use these values for reconnect banners, disabled buttons, and loading states.

client.onConnectionStatus(callback)

Signature

const unsubscribe = client.onConnectionStatus(
  (status: "connecting" | "connected" | "disconnected") => void,
);

Example

const unsubscribe = client.onConnectionStatus((status) => {
  setOnline(status === "connected");
});

client.request(type, payload?)

Signature

await client.request<T = Record<string, unknown>>(
  type: string,
  payload?: Record<string, unknown>,
): Promise<T>

Sends a raw WebSocket request and waits for the response with the same rid. Most applications should not call this directly. Prefer the typed client.sessions, client.agent, and client.chat namespaces.

client.onPush(type, handler)

Signature

const unsubscribe = client.onPush(
  type: string,
  handler: (message: WsMessage) => void,
);

Subscribes directly to server push messages such as sessions.snapshot, agent.event, and permission.request. Most applications should prefer sessions.onSnapshot, agent.onEvent, and agent.onPermissionRequest.

Transport selection