import { Backend, type BackendOptions, type StreamUser, type TokenSource, type UserTokenOptions, } from "./backend.js"; import { ConfigurationError, errorOf, RouterError } from "./errors.js"; import type { components, paths } from "./generated/api.js"; import { ANONYMOUS_GUEST_REFUSED, claimGuestUser, forgetGuest, guestUser, type Guest, type GuestStore, type GuestUserOptions, } from "./guests.js"; import { AgentHandle } from "./handle.js"; import { Memories } from "./memories.js"; import { Router, type RouterOptions } from "./router.js"; import { ScheduledTasks } from "./scheduled-tasks.js"; import { Simulations } from "./simulations.js"; import { SpendLimits } from "./spend-limits.js"; import { StreamPeers, type StreamClients } from "./stream.js"; import { Teams } from "./teams.js"; /** The schemas from the spec, so callers can name a request or a response they build. */ export type Schemas = components["schemas"]; /** The methods the router serves. */ export type Method = "get" | "post" | "put" | "patch" | "delete"; type Operation

= M extends keyof paths[P] ? NonNullable : never; /** The paths that answer to one method, which is what keeps `get` off a POST-only path. */ export type PathsWith = { [P in keyof paths]: [Operation] extends [never] ? never : P; }[keyof paths]; type ParametersOf = Op extends { readonly parameters: infer P } ? P : unknown; /** * The parameters an operation takes, with a query value allowed to be undefined. * * A caller passing one through from somewhere that may not have it should not have to * build the object conditionally: an undefined value is left off the query string rather * than sent as the word. */ type QueryOf

= { [K in keyof P]: K extends "query" ? { [Q in keyof NonNullable]: NonNullable[Q] | undefined } : P[K]; }; /** * The JSON body an operation takes, required exactly when the spec requires it. * * Three cases rather than two, because an optional body and no body at all are different: * attaching a number takes one and does not need one, and a caller should be able to leave * it out without being able to invent one where the spec has none. */ type BodyOf = Op extends { readonly requestBody: { readonly content: { readonly "application/json": infer B } }; } ? { readonly body: B } : Op extends { readonly requestBody?: { readonly content: { readonly "application/json": infer B } }; } ? { readonly body?: B } : { readonly body?: never }; /** * Everything one call needs, taken from the operation. * * The generated `parameters` already says which of `path` and `query` an operation has and * which are required, so it is reused rather than restated: an endpoint that grows a * required parameter starts failing to compile here. */ export type RequestOptions = QueryOf, "header" | "cookie">> & BodyOf & { readonly signal?: AbortSignal; /** Sent alongside the credentials, for a header a deployment of its own wants. */ readonly headers?: Readonly>; /** * Whether sending the request twice does what sending it once does, so a failure in * between may be retried. GET, PUT and DELETE are; a POST or PATCH is only when it says * so, such as one carrying a request id the router answers once. */ readonly idempotent?: boolean; }; type ResponsesOf = Op extends { readonly responses: infer R } ? R : never; /** * What a call answers with. * * 204 has no body and becomes void, which is most of the ways a session is acted on. */ export type Result = { [S in Extract, 200 | 201 | 202 | 204>]: ResponsesOf[S] extends { content: { readonly "application/json": infer B }; } ? B : ResponsesOf[S] extends { content: { readonly "text/event-stream": string } } ? ReadableStream : ResponsesOf[S] extends { content: { readonly "text/plain": string } } ? string : void; }[Extract, 200 | 201 | 202 | 204>]; /** Whether the options can be left out entirely, which they can when nothing is required. */ type Arguments = Record extends RequestOptions ? [options?: RequestOptions] : [options: RequestOptions]; /** * The router's API, as resources: `api.simulations`, `api.memories`, `api.agent(name)`. * * ```ts * const api = new Client(); * const simulation = await api.simulations.create({ name, config_id, scenario, assertion }); * const session = await api.agent("docs").sessions.create(); * ``` * * Underneath, `get`, `post`, `put`, `patch` and `delete` take any path in the spec, typed from * it. They are what the resources are built on, and the way to reach an endpoint no resource * covers yet; code a customer reads uses the resource. */ export class Client { readonly backend: Backend; /** What the app's agents remember about its users. */ readonly memories: Memories; /** Conversations to test an agent with, and their runs. */ readonly simulations: Simulations; /** The reminders and later work agents hold for the user `setUser` named. */ readonly scheduledTasks: ScheduledTasks; /** The customer's spend limits. Server side only. */ readonly spendLimits: SpendLimits; /** The organization's teams and their spend limits. Server side only. */ readonly teams: Teams; /** @internal The chat and video clients this client's sessions share. */ readonly peers: StreamPeers; constructor(backend: Backend | BackendOptions = {}) { this.backend = backend instanceof Backend ? backend : new Backend(backend); this.memories = new Memories(this); this.simulations = new Simulations(this); this.scheduledTasks = new ScheduledTasks(this); this.spendLimits = new SpendLimits(this); this.teams = new Teams(this, this.spendLimits); this.peers = new StreamPeers(this.backend); } /** * Says who this client is acting for, and hands over the token that proves it. * * ```ts * const api = new Client({ url: accelerate, apiKey }); * await api.setUser({ id: "jlahey", name: "Jim Lahey" }, userToken); * ``` * * From here on the conversations this client opens belong to that user, and the ones it * lists are that user's own. A browser gets the token from the app's own backend, which is * the thing that authenticated them; nothing here mints it, because minting it needs the * secret and a secret in a page is a secret published. */ setUser(user: StreamUser | string, token: TokenSource): Promise; /** Acts as a guest from `guestUser`, with the token it was minted with. */ setUser(guest: Guest): Promise; setUser(user: StreamUser | string | Guest, token?: TokenSource): Promise { if (isGuest(user)) { // Only who they are goes on, never the token they carry, which would otherwise be sent to // Stream Chat and Video as a field of the user. return this.backend.setUser({ id: user.id, ...(user.name ? { name: user.name } : {}) }, token ?? user.token); } return this.backend.setUser(user, token as TokenSource); } /** * The token a backend hands to one user's device, naming the user's team and usage * categories, fixed when it is signed so the device cannot move its work to another team. * Server side only: it is signed with the secret. * * ```ts * const token = await api.createUserToken("user-42", { team: "finance" }); * ``` */ createUserToken(userId: string, options: UserTokenOptions = {}): Promise { return this.backend.createUserToken(userId, options); } /** * Forgets the user, which is what signing out is. The Stream clients `session.chat()` and * `session.video()` built stay connected as them until `disconnect`. */ clearUser(): void { this.backend.clearUser(); } /** * Hands over the app's own `StreamChat` and `StreamVideoClient`, so every session opens on * them rather than on second ones. Connecting them, as the user `setUser` named, stays the * app's job, and `disconnect` leaves them alone. * * ```ts * api.use({ chat: streamChat, video: videoClient }); * ``` */ use(clients: StreamClients): void { this.peers.use(clients); } /** * Disconnects the Stream chat and video clients `session.chat()` and `session.video()` * built. Closing a session leaves them connected, since other sessions share them. */ disconnect(): Promise { return this.peers.disconnect(); } /** * Search, the one routed modality a device may reach, under a stored router config and with * cost labels when given. No request is made until a call. * * ```ts * const answer = await api.router({ config: "healthcare" }).search("what changed in the pricing page"); * ``` */ router(options: RouterOptions = {}): Router { return new Router(this, options); } /** * An agent, by the name it is configured under. * * ```ts * const agent = api.agent("docs"); * ``` * * No request is made: this is the name in a wrapper, and a name that matches nothing is * refused when a session is opened rather than here. Which means addressing an agent costs * nothing, and is the same line whether the config was written this morning or last year. */ agent(name: string): AgentHandle { return new AgentHandle(this, name); } /** * Gets or creates a guest, so somebody can talk to an agent before they sign up. * * Remembered in a cookie or in localStorage where there is one, so reloading the page is * the same guest with the same history rather than a stranger. Nothing is remembered on a * server, where there is no "this person" to remember. */ guestUser(options: GuestUserOptions = {}, store?: GuestStore): Promise { return store === undefined ? guestUser(this, options) : guestUser(this, options, store); } /** Forgets the remembered guest, which is what signing in has to do. */ forgetGuest(store?: GuestStore): void { return store === undefined ? forgetGuest() : forgetGuest(store); } /** * Moves a guest's conversations onto the account they turned out to be. * * Server side only: only the backend that just authenticated the account knows which guest * it was, and a page able to ask could claim anybody's conversations by guessing an id. */ claimGuestUser( guest: Guest | string, real: StreamUser | string, ): Promise { return claimGuestUser(this, guest, real); } get

>( path: P, ...options: Arguments> ): Promise>> { return this.send("get", path, options[0]); } post

>( path: P, ...options: Arguments> ): Promise>> { return this.send("post", path, options[0]); } put

>( path: P, ...options: Arguments> ): Promise>> { return this.send("put", path, options[0]); } patch

>( path: P, ...options: Arguments> ): Promise>> { return this.send("patch", path, options[0]); } delete

>( path: P, ...options: Arguments> ): Promise>> { return this.send("delete", path, options[0]); } private async send(method: Method, template: string, options: unknown): Promise { const { path, query, body, signal, headers, idempotent, [ON_RETRY]: resending } = (options ?? {}) as { path?: Record; query?: Record; body?: unknown; signal?: AbortSignal; headers?: Record; idempotent?: boolean; [ON_RETRY]?: () => void; }; const operation = `${method.toUpperCase()} ${template}`; const anonymously = operation === "POST /v1/agents/guests" && this.backend.anonymous; const retryable = idempotent ?? (method === "get" || method === "put" || method === "delete"); const url = new URL(this.backend.url + fill(template, path)); for (const [name, value] of Object.entries({ ...this.backend.query(), ...query })) { if (value === undefined || value === null) { continue; } for (const one of Array.isArray(value) ? value : [value]) { url.searchParams.append(name, String(one)); } } // The token the last attempt carried, so a 401 forgets that one and not a newer one. let sent: string | undefined; const attempt = async (): Promise => { const credentials = await this.backend.headers(anonymously); sent = credentials["Authorization"]?.replace(/^Bearer /, ""); const request: RequestInit = { method: method.toUpperCase(), headers: { ...credentials, ...headers }, }; if (body !== undefined) { request.headers = { ...request.headers, "Content-Type": "application/json" }; request.body = JSON.stringify(body); } if (signal) { request.signal = signal; } try { return await this.backend.request(url.toString(), request); } catch (cause) { // The caller's own abort is theirs to see as it is: reported as a router that could // not be reached, a caller retrying those would send again what it just cancelled. if (signal?.aborted) { throw signal.reason ?? cause; } // A request that never arrived is reported as such rather than as a status, because // a caller retrying on a network failure and one retrying on a 500 are different. throw new RouterError(0, operation, `could not reach the router: ${String(cause)}`, { cause }); } }; let retries = 0; let refreshed = false; while (true) { let response: Response; try { response = await attempt(); } catch (cause) { if (!(cause instanceof RouterError) || !retryable || retries >= this.backend.maxRetries) { throw cause; } await pause(backoff(retries), signal); retries += 1; resending?.(); continue; } // A 401 is the token having expired more often than anything else, so a token function // is asked for a fresh one and the request sent once more. Once: a second refusal is the // token being wrong rather than old, and asking again would only ask the app's backend // the same question in a loop. if (response.status === 401 && !refreshed && !anonymously && this.backend.expireToken(sent)) { refreshed = true; await response.body?.cancel(); continue; } // A router that is busy or being replaced says so with these, and answers the same // request a moment later. Only one that is safe to send twice is, and only a few times: // past that the failure is the caller's to see rather than this client's to hide. if (retryable && TRANSIENT.has(response.status) && retries < this.backend.maxRetries) { const after = retryAfterMs(response); if (after === undefined || after <= MAX_RETRY_AFTER_MS) { await response.body?.cancel(); await pause(after ?? backoff(retries), signal); retries += 1; resending?.(); continue; } } if (anonymously && response.status === 401) { throw new ConfigurationError(ANONYMOUS_GUEST_REFUSED); } if (!response.ok) { throw await errorOf(response, operation); } const mediaType = response.headers.get("Content-Type")?.split(";")[0]?.trim().toLowerCase(); if ( response.status === 204 || (response.headers.get("Content-Length") === "0" && mediaType !== "text/plain" && mediaType !== "text/event-stream") ) { return undefined as T; } if (mediaType === "text/event-stream") { if (!response.body) { throw new RouterError(response.status, operation, "the router returned no event stream"); } return response.body as T; } let content: string; try { content = await response.text(); } catch (cause) { if (signal?.aborted) { throw signal.reason ?? cause; } if (retryable && retries < this.backend.maxRetries) { await pause(backoff(retries), signal); retries += 1; resending?.(); continue; } throw new RouterError(0, operation, "the connection ended before the router's response was read", { cause, requestId: response.headers.get("X-Request-Id") || undefined, }); } if (mediaType === "text/plain") { return content as T; } try { return JSON.parse(content) as T; } catch (cause) { throw new RouterError(response.status, operation, "the router returned invalid JSON", { cause, requestId: response.headers.get("X-Request-Id") || undefined, }); } } } } const ON_RETRY = Symbol("stream-agents.onRetry"); /** * @internal Request options that call `heard` each time the request is sent again, for a caller * whose answer means something different when the router may have seen it before. */ export function onRetry(heard: () => void): Record { return { [ON_RETRY]: heard }; } /** The answers that say the router could not take the request just now, rather than that it was wrong. */ const TRANSIENT = new Set([429, 502, 503, 504]); /** The first wait before a retry; each one after doubles it, up to `MAX_BACKOFF_MS`. */ const BASE_BACKOFF_MS = 250; const MAX_BACKOFF_MS = 4_000; /** The longest `Retry-After` waited out; a router asking for longer is reported instead. */ const MAX_RETRY_AFTER_MS = 30_000; /** * How long to wait before retry `retries` (from 0): doubling, with half of it random so a * burst of clients refused together does not come back together. */ function backoff(retries: number): number { const ceiling = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** retries); return ceiling / 2 + Math.random() * (ceiling / 2); } /** What the response's `Retry-After` asks for, in milliseconds, as seconds or as a date. */ function retryAfterMs(response: Response): number | undefined { const header = response.headers.get("Retry-After"); if (!header) { return undefined; } const seconds = Number(header); if (Number.isFinite(seconds)) { return Math.max(0, seconds * 1000); } const at = Date.parse(header); return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now()); } /** Waits, or rejects with the signal's reason as soon as it aborts. */ function pause(ms: number, signal: AbortSignal | undefined): Promise { return new Promise((resolve, reject) => { if (signal?.aborted) { reject(signal.reason); return; } const aborted = () => { clearTimeout(timer); reject(signal?.reason); }; const timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms); signal?.addEventListener("abort", aborted, { once: true }); }); } /** Puts the path parameters into the template, so `{id}` is never sent literally. */ function fill(template: string, path: Record | undefined): string { return template.replace(/\{(\w+)\}/g, (_, name: string) => { const value = path?.[name]; if (value === undefined) { // Nothing was sent: this is a mistake in the call, which no retry would fix. throw new ConfigurationError(`${template} needs a ${name}`); } return encodeURIComponent(String(value)); }); } /** Whether `setUser` was handed a guest, which carries the token it was minted with. */ function isGuest(user: StreamUser | string | Guest): user is Guest { return typeof user === "object" && typeof user["token"] === "string"; }