Client transport と SnaClient

SnaClient は 1 つの baseUrl から HTTP endpoint と WebSocket endpoint を導出します。状態変更と CRUD には HTTP、push event と permission request には WebSocket、長時間の one-shot stream には SSE を使います。

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

認証動作

authToken がある場合、HTTP と SSE request は Authorization: Bearer <authToken> を送ります。WebSocket 接続は browser runtime でも upgrade を認証できるように、同じトークンを ?token=<authToken> として付けます。baseUrl と authToken がずれないよう、 launcher の handle.connection object を渡すのが安全です。

401 はトークンがない、またはサーバーと一致しないことを意味します。403 は request が server の allowedOrigins にない browser Origin から来た ことを意味します。

client.connect()

WebSocket 接続を開始します。すでに接続中または接続済みの場合は no-op です。接続直後に server が sessions.snapshot を push することがあるため、session state が必要な UI では connect の前に sessions.onSnapshot を登録してください。

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

client.disconnect()

WebSocket を閉じ、自動 reconnect を停止します。応答待ちの low-level request promise は disconnected error で reject されます。

client.status / client.connected

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

Reconnect banner、disabled button、loading state の表示に使います。

client.onConnectionStatus(callback)

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

client.request(type, payload?)

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

raw WebSocket request を送り、同じ rid を持つ response を待ちます。通常のアプリケーションでは直接使わず、型付きの client.sessions、client.agent、client.chat namespace を使ってください。

client.onPush(type, handler)

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

sessions.snapshot、agent.event、permission.request など、server が request なしで送る push message を直接購読します。通常は sessions.onSnapshot、agent.onEvent、agent.onPermissionRequest を優先してください。

Transport 選択基準