Client transport와 SnaClient

SnaClient는 하나의 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 요청은 Authorization: Bearer <authToken>을 보냅니다. WebSocket 연결은 browser runtime도 upgrade를 인증할 수 있도록 같은 토큰을 ?token=<authToken>으로 붙입니다. baseUrl과 authToken이 어긋나지 않도록 launcher의 handle.connection object를 전달하는 방식이 가장 안전합니다.

401은 토큰이 없거나 서버와 맞지 않는다는 뜻입니다. 403은 요청이 서버의 allowedOrigins에 없는 browser Origin에서 왔다는 뜻입니다.

Example

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

const client = new SnaClient(handle.connection);

client.connect()

Signature

client.connect(): void

WebSocket 연결을 시작합니다. 이미 연결 중이거나 연결되어 있으면 no-op입니다. 연결 직후 서버는 sessions.snapshot push를 보낼 수 있으므로, session UI가 필요하다면 sessions.onSnapshot을 먼저 등록하십시오.

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

client.disconnect()

Signature

client.disconnect(): void

WebSocket을 닫고 자동 reconnect를 중지합니다. 아직 응답을 기다리는 low-level request promise는 disconnected error로 reject됩니다.

client.status / client.connected

Signature

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

UI에서 reconnect banner, disabled button, loading state를 표시할 때 사용합니다.

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>

WebSocket으로 raw request를 보내고 같은 rid를 가진 response를 기다립니다. 일반 앱에서는 직접 사용하지 말고 client.sessions, client.agent, client.chat namespace를 사용하십시오.

Example

// 권장하지 않음: 타입 안정성이 낮습니다.
const response = await client.request("sessions.list");

client.onPush(type, handler)

Signature

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

서버가 request 없이 보내는 push message를 직접 구독합니다. 예: sessions.snapshot, agent.event, permission.request. 일반 앱에서는 sessions.onSnapshot, agent.onEvent, agent.onPermissionRequest를 우선 사용하십시오.

Transport 선택 기준