> ## Documentation Index > Fetch the complete documentation index at: https://docs.interhuman.ai/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript SDK > API reference for @interhumanai/sdk — the official TypeScript client for auth, upload, and stream. ## Classes ### AuthClient Exchanges API-key credentials for a short-lived bearer access token. The token returned by [createToken](#createtoken) carries only the scopes you request and expires after `expires_in` seconds (typically 15 minutes). For hands-off token lifecycle management, prefer the top-level [InterhumanClient](#interhumanclient), which uses a [TokenManager](#tokenmanager) to fetch and refresh tokens for you. #### Constructors ##### Constructor ```ts theme={null} new AuthClient(options?): AuthClient; ``` ###### Parameters | Parameter | Type | | --------- | ----------------------------------------- | | `options` | [`AuthClientOptions`](#authclientoptions) | ###### Returns [`AuthClient`](#authclient) #### Methods ##### createToken() ```ts theme={null} createToken(request): Promise; ``` Mint an access token for the given credentials and scopes. ###### Parameters | Parameter | Type | | --------- | ------------------------------- | | `request` | [`TokenRequest`](#tokenrequest) | ###### Returns `Promise`\<[`TokenResponse`](#tokenresponse)> ###### Throws when the credentials are invalid (401), lack a requested scope (403), or the request is otherwise rejected. ##### createClientToken() ```ts theme={null} createClientToken(request): Promise; ``` Mint a short-lived, capped **client token** for direct browser use. Call this from your backend with your API key; the returned token is safe to hand to a browser to call the upload, stream, or real-time endpoints directly. It grants the requested scopes (default `interhumanai.stream`) and carries the caps you set, which the API enforces across upload, stream, and real-time (the video budget spans all three). Omitted fields are left unset (the server applies its defaults, e.g. a single concurrent session and a 300s TTL). ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `request` | [`ClientTokenRequest`](#clienttokenrequest) | ###### Returns `Promise`\<[`ClientTokenResponse`](#clienttokenresponse)> ###### Throws when the credentials are invalid (401), the key lacks a requested scope (403), or the mint rate limit is exceeded (429). ##### revokeClientToken() ```ts theme={null} revokeClientToken(request): Promise; ``` Revoke a previously minted client token. Call this from your backend with the same API key that minted the token. Once revoked, the token is rejected on new requests and any live streaming session it opened is torn down on its next chunk. Revoking an already-expired token is a harmless no-op. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------------- | | `request` | [`RevokeClientTokenRequest`](#revokeclienttokenrequest) | ###### Returns `Promise`\<`void`> ###### Throws when the credentials or token are invalid (401). *** ### StaticTokenProvider A [TokenProvider](#tokenprovider) that always returns the same pre-issued token. #### Implements * [`TokenProvider`](#tokenprovider) #### Constructors ##### Constructor ```ts theme={null} new StaticTokenProvider(token): StaticTokenProvider; ``` ###### Parameters | Parameter | Type | | --------- | -------- | | `token` | `string` | ###### Returns [`StaticTokenProvider`](#statictokenprovider) #### Methods ##### getToken() ```ts theme={null} getToken(): Promise; ``` Return a currently-valid bearer token, minting/refreshing as needed. ###### Returns `Promise`\<`string`> ###### Implementation of [`TokenProvider`](#tokenprovider).[`getToken`](#gettoken) *** ### TokenManager Mints access tokens from API-key credentials via [AuthClient](#authclient) and caches them until shortly before they expire, so callers can request a valid bearer token cheaply on every call. Concurrent requests while a token is being minted share a single in-flight request. #### Implements * [`TokenProvider`](#tokenprovider) #### Constructors ##### Constructor ```ts theme={null} new TokenManager(options): TokenManager; ``` ###### Parameters | Parameter | Type | | --------- | --------------------------------------------- | | `options` | [`TokenManagerOptions`](#tokenmanageroptions) | ###### Returns [`TokenManager`](#tokenmanager) #### Methods ##### getToken() ```ts theme={null} getToken(): Promise; ``` Return a valid bearer token, minting or refreshing transparently. ###### Returns `Promise`\<`string`> ###### Implementation of [`TokenProvider`](#tokenprovider).[`getToken`](#gettoken) ##### invalidate() ```ts theme={null} invalidate(): void; ``` Drop any cached token so the next [getToken](#gettoken-2) mints a fresh one. ###### Returns `void` *** ### InterhumanClient The main entry point. Construct it once with credentials (or a token) and use [upload](#upload), [stream](#stream), and [realtime](#realtime) to call the API; token lifecycle is handled for you. #### Example ```ts theme={null} const client = new InterhumanClient({ credentials: { keyId: "...", keySecret: "..." }, }); const report = await client.upload.analyze({ file: bytes, filename: "clip.mp4" }); ``` #### Constructors ##### Constructor ```ts theme={null} new InterhumanClient(options): InterhumanClient; ``` ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------- | | `options` | [`InterhumanClientOptions`](#interhumanclientoptions) | ###### Returns [`InterhumanClient`](#interhumanclient) #### Properties | Property | Modifier | Type | Description | | -------------------------- | ---------- | ------------------------------- | ----------------------------------------------------------------- | | `auth` | `readonly` | [`AuthClient`](#authclient) | Low-level auth client for minting tokens directly via `/v1/auth`. | | `upload` | `readonly` | [`UploadClient`](#uploadclient) | Upload-mode analysis client (`POST /v1/upload/analyze`). | #### Methods ##### stream() ```ts theme={null} stream(): StreamClient; ``` Create a new [StreamClient](#streamclient) for a live analysis session. Each call returns a fresh client (one per WebSocket session); register handlers and then call `connect()`. ###### Returns [`StreamClient`](#streamclient) ##### realtime() ```ts theme={null} realtime(): RealtimeClient; ``` Create a new [RealtimeClient](#realtimeclient) for a real-time multi-track analysis session (`WS /v0/realtime/analyze`). Each call returns a fresh client (one per WebSocket session); register handlers and then call `connect()`. For the current temporary release the endpoint accepts tokens holding either the stream or the realtime scope, so the default scopes work as-is; pass `scopes: [Scope.Realtime]` to mint realtime-scoped tokens explicitly. ###### Returns [`RealtimeClient`](#realtimeclient) ##### getToken() ```ts theme={null} getToken(): Promise; ``` Return a currently-valid bearer token (minting/refreshing as needed). ###### Returns `Promise`\<`string`> *** ### InterhumanError Base class for every error the SDK throws. #### Extends * `Error` #### Extended by * [`InterhumanApiError`](#interhumanapierror) * [`InterhumanConfigError`](#interhumanconfigerror) #### Constructors ##### Constructor ```ts theme={null} new InterhumanError(message): InterhumanError; ``` ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`InterhumanError`](#interhumanerror) ###### Overrides ```ts theme={null} Error.constructor ``` *** ### InterhumanApiError An error response from an HTTP endpoint (`/v1/auth`, `/v1/upload/analyze`). `errorId`, `correlationId`, and `link` are surfaced from the canonical [ApiErrorBody](#apierrorbody) when the server returned one. #### Extends * [`InterhumanError`](#interhumanerror) #### Constructors ##### Constructor ```ts theme={null} new InterhumanApiError(args): InterhumanApiError; ``` ###### Parameters | Parameter | Type | | --------------- | ---------------------------------------------------------------------------------------- | | `args` | \{ `status`: `number`; `body?`: [`ApiErrorBody`](#apierrorbody); `message?`: `string`; } | | `args.status` | `number` | | `args.body?` | [`ApiErrorBody`](#apierrorbody) | | `args.message?` | `string` | ###### Returns [`InterhumanApiError`](#interhumanapierror) ###### Overrides [`InterhumanError`](#interhumanerror).[`constructor`](#constructor-4) #### Properties | Property | Modifier | Type | Description | | ----------------------------------------- | ---------- | ------------------------------- | ------------------------------------------------------------ | | `status` | `readonly` | `number` | HTTP status code. | | `errorId?` | `readonly` | `string` | Machine-readable error code (e.g. `"ih2001"`), when present. | | `correlationId?` | `readonly` | `string` | Correlation id for support, when present. | | `link?` | `readonly` | `string` | Documentation link for the error, when present. | | `body?` | `readonly` | [`ApiErrorBody`](#apierrorbody) | The raw parsed error body, when the server returned JSON. | *** ### InterhumanConfigError A configuration/usage error caught before any network call. Stream `error` envelopes are not thrown — they are delivered as typed [StreamErrorEvent](#streamerrorevent)s through the stream client's `on("error", …)` surface, and transport-level socket failures arrive on `"socketError"` as a base [InterhumanError](#interhumanerror). #### Extends * [`InterhumanError`](#interhumanerror) #### Constructors ##### Constructor ```ts theme={null} new InterhumanConfigError(message): InterhumanConfigError; ``` ###### Parameters | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [`InterhumanConfigError`](#interhumanconfigerror) ###### Inherited from [`InterhumanError`](#interhumanerror).[`constructor`](#constructor-4) *** ### RealtimeClient A typed client over the real-time WebSocket protocol. The real-time endpoint shares the stream endpoint's session mechanics (subprotocol bearer auth, binary video frames, JSON envelopes down, and the `requestClose()` graceful shutdown handshake) and adds multi-track analysis, a caller-supplied transcript ([sendTranscript](#sendtranscript)), a live server transcript (`transcript.generated`), and a periodic feedback step (`realtime_feedback.generated`) enabled through the session config's `realtime_feedback_instructions`. Unlike the stream endpoint it never emits `engagement.updated` or `conversation_quality.updated`. **Temporary release:** the endpoint currently ships under the **v0** path (`/v0/realtime/analyze`) and accepts credentials holding *either* the `interhumanai.stream` or the `interhumanai.realtime` scope, so existing stream-scoped keys work without a new permission. Both aspects may change when the endpoint graduates to v1. The previous hyphenated spelling (`/v0/real-time/analyze`) still works as a temporary compatibility alias, but new integrations should use `/v0/realtime/analyze`. #### Example ```ts theme={null} const realtime = client.realtime(); realtime.on("signal.detected", (e) => console.log(e.data.signal_type)); realtime.on("realtime_feedback.generated", (e) => console.log(e.data.text)); await realtime.connect(); await realtime.waitForSessionReady(); realtime.updateConfig({ realtime_feedback_instructions: "Goal: help me close a sales call.", realtime_feedback_frequency: "medium", }); realtime.sendVideo(chunk); realtime.requestClose(); // graceful: drains (incl. feedback), then session.ended + close ``` #### Extends * [`SessionSocketClient`](#abstract-sessionsocketclient)\<[`RealtimeEventMap`](#realtimeeventmap), [`RealtimeSessionConfig`](#realtimesessionconfig)> #### Constructors ##### Constructor ```ts theme={null} new RealtimeClient(options): RealtimeClient; ``` ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------- | | `options` | [`SessionSocketClientOptions`](#sessionsocketclientoptions) | ###### Returns [`RealtimeClient`](#realtimeclient) ###### Overrides [`SessionSocketClient`](#abstract-sessionsocketclient).[`constructor`](#constructor-8) #### Properties | Property | Modifier | Type | Default value | Description | Overrides | | -------------------------------------- | ---------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `endpointPath` | `readonly` | `"/v0/realtime/analyze"` | `"/v0/realtime/analyze"` | Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`endpointPath`](#endpointpath-1) | | `clientName` | `readonly` | `"RealtimeClient"` | `"RealtimeClient"` | Concrete class name used in configuration error messages. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`clientName`](#clientname-1) | | `displayName` | `readonly` | `"Real-time"` | `"Real-time"` | Human-readable surface name used in error messages (e.g. `"Stream"`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`displayName`](#displayname-1) | | `scopeHint` | `readonly` | `"The credentials may be invalid or lack the stream or realtime scope."` | `"The credentials may be invalid or lack the stream or realtime scope."` | Appended to the connect-rejection message to hint at the likely scope issue. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`scopeHint`](#scopehint-1) | #### Accessors ##### isOpen ###### Get Signature ```ts theme={null} get isOpen(): boolean; ``` Whether the underlying socket is open. ###### Returns `boolean` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`isOpen`](#isopen-1) #### Methods ##### sendTranscript() ```ts theme={null} sendTranscript(transcript): void; ``` Send (or replace) the caller-supplied transcript as a `transcript.updated` text frame. The most recent transcript replaces any prior one for the session and is rendered into the feedback prompt. A transcript that does not match the segment shape is rejected by the server with a non-fatal `error` envelope; the session stays open. ###### Parameters | Parameter | Type | | ------------ | -------------------------------------------- | | `transcript` | [`TranscriptSegment`](#transcriptsegment)\[] | ###### Returns `void` ##### on() ```ts theme={null} on(event, handler): () => void; ``` Subscribe to an event. Returns an unsubscribe function. Use a specific envelope `type` (e.g. `"signal.detected"`), `"message"` for every envelope, or a lifecycle event (`"open"`, `"close"`, `"socketError"`). ###### Type Parameters | Type Parameter | | ----------------------------------------------------------- | | `K` *extends* keyof [`RealtimeEventMap`](#realtimeeventmap) | ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`RealtimeEventMap`](#realtimeeventmap)\[`K`]> | ###### Returns () => `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`on`](#on-1) ##### off() ```ts theme={null} off(event, handler): void; ``` Unsubscribe a previously registered handler. ###### Type Parameters | Type Parameter | | ----------------------------------------------------------- | | `K` *extends* keyof [`RealtimeEventMap`](#realtimeeventmap) | ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`RealtimeEventMap`](#realtimeeventmap)\[`K`]> | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`off`](#off-1) ##### once() ```ts theme={null} once(event, handler): () => void; ``` Subscribe to the next occurrence of an event, then auto-unsubscribe. ###### Type Parameters | Type Parameter | | ----------------------------------------------------------- | | `K` *extends* keyof [`RealtimeEventMap`](#realtimeeventmap) | ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`RealtimeEventMap`](#realtimeeventmap)\[`K`]> | ###### Returns () => `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`once`](#once-1) ##### connect() ```ts theme={null} connect(): Promise; ``` Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials). ###### Returns `Promise`\<`void`> ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`connect`](#connect-1) ##### waitForSessionReady() ```ts theme={null} waitForSessionReady(): Promise; ``` Wait for the `session.ready` envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after [connect](#connect) without racing the frame. ###### Returns `Promise`\<[`RealtimeSessionReadyEvent`](#realtimesessionreadyevent)> ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`waitForSessionReady`](#waitforsessionready-1) ##### sendVideo() ```ts theme={null} sendVideo(chunk): void; ``` Send a chunk of WebM or fragmented-MP4 video as a binary frame. ###### Parameters | Parameter | Type | | --------- | --------------------------- | | `chunk` | [`VideoChunk`](#videochunk) | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`sendVideo`](#sendvideo-1) ##### updateConfig() ```ts theme={null} updateConfig(config): void; ``` Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a `session.updated` envelope. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------- | | `config` | [`RealtimeSessionConfig`](#realtimesessionconfig) | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`updateConfig`](#updateconfig-1) ##### requestClose() ```ts theme={null} requestClose(): void; ``` Request a graceful end-of-analysis shutdown (`session.close`). The server acknowledges with a `session.closing` envelope whose `data.max_drain_seconds` is the longest you should wait for the final `session.ended` envelope. After the acknowledgment the server rejects new video, finishes analyzing the video it already accepted (emitting the normal envelopes in order, plus `signal.ended` for still-active signals), sends `session.ended`, and closes the socket with code 1000 — so listen for `"session.ended"` (or `"close"`) rather than calling [close](#close). ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`requestClose`](#requestclose-1) ##### close() ```ts theme={null} close(code?, reason?): void; ``` Close the connection immediately, without the graceful drain handshake. ###### Parameters | Parameter | Type | | --------- | -------- | | `code?` | `number` | | `reason?` | `string` | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`close`](#close-3) ##### sendJson() ```ts theme={null} protected sendJson(payload): void; ``` Send an arbitrary JSON payload as a text frame. ###### Parameters | Parameter | Type | | --------- | --------- | | `payload` | `unknown` | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`sendJson`](#sendjson-1) *** ### `abstract` SessionSocketClient Base class implementing the shared live-session WebSocket protocol. Authentication uses the `Sec-WebSocket-Protocol: access_token, ` subprotocol pair, which is portable across browsers and Node (the standard `WebSocket` constructor cannot set an `Authorization` header). Inbound frames are decoded into the protocol's envelope union and dispatched through the typed [on](#on-1) surface; outbound video is sent as binary frames and JSON payloads (session config, and for real-time the transcript) as text frames. #### Extended by * [`StreamClient`](#streamclient) * [`RealtimeClient`](#realtimeclient) #### Type Parameters | Type Parameter | Description | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `TEventMap` *extends* [`SessionSocketEventMapBase`](#sessionsocketeventmapbase)\<`unknown`, `unknown`> | Event payloads keyed by event name (envelope `type`s plus the lifecycle events of [SessionSocketEventMapBase](#sessionsocketeventmapbase)). | | `TConfig` *extends* `object` | The client→server session-config shape. | #### Constructors ##### Constructor ```ts theme={null} new SessionSocketClient(options): SessionSocketClient; ``` ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------- | | `options` | [`SessionSocketClientOptions`](#sessionsocketclientoptions) | ###### Returns [`SessionSocketClient`](#abstract-sessionsocketclient)\<`TEventMap`, `TConfig`> #### Properties | Property | Modifier | Type | Description | | ---------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | | `endpointPath` | `abstract` | `string` | Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`). | | `clientName` | `abstract` | `string` | Concrete class name used in configuration error messages. | | `displayName` | `abstract` | `string` | Human-readable surface name used in error messages (e.g. `"Stream"`). | | `scopeHint` | `abstract` | `string` | Appended to the connect-rejection message to hint at the likely scope issue. | #### Accessors ##### isOpen ###### Get Signature ```ts theme={null} get isOpen(): boolean; ``` Whether the underlying socket is open. ###### Returns `boolean` #### Methods ##### on() ```ts theme={null} on(event, handler): () => void; ``` Subscribe to an event. Returns an unsubscribe function. Use a specific envelope `type` (e.g. `"signal.detected"`), `"message"` for every envelope, or a lifecycle event (`"open"`, `"close"`, `"socketError"`). ###### Type Parameters | Type Parameter | | ---------------------------------------------- | | `K` *extends* `string` \| `number` \| `symbol` | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<`TEventMap`\[`K`]> | ###### Returns () => `void` ##### off() ```ts theme={null} off(event, handler): void; ``` Unsubscribe a previously registered handler. ###### Type Parameters | Type Parameter | | ---------------------------------------------- | | `K` *extends* `string` \| `number` \| `symbol` | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<`TEventMap`\[`K`]> | ###### Returns `void` ##### once() ```ts theme={null} once(event, handler): () => void; ``` Subscribe to the next occurrence of an event, then auto-unsubscribe. ###### Type Parameters | Type Parameter | | ---------------------------------------------- | | `K` *extends* `string` \| `number` \| `symbol` | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<`TEventMap`\[`K`]> | ###### Returns () => `void` ##### connect() ```ts theme={null} connect(): Promise; ``` Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials). ###### Returns `Promise`\<`void`> ##### waitForSessionReady() ```ts theme={null} waitForSessionReady(): Promise; ``` Wait for the `session.ready` envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after [connect](#connect-1) without racing the frame. ###### Returns `Promise`\<`TEventMap`\[`"session.ready"`]> ##### sendVideo() ```ts theme={null} sendVideo(chunk): void; ``` Send a chunk of WebM or fragmented-MP4 video as a binary frame. ###### Parameters | Parameter | Type | | --------- | --------------------------- | | `chunk` | [`VideoChunk`](#videochunk) | ###### Returns `void` ##### updateConfig() ```ts theme={null} updateConfig(config): void; ``` Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a `session.updated` envelope. ###### Parameters | Parameter | Type | | --------- | --------- | | `config` | `TConfig` | ###### Returns `void` ##### requestClose() ```ts theme={null} requestClose(): void; ``` Request a graceful end-of-analysis shutdown (`session.close`). The server acknowledges with a `session.closing` envelope whose `data.max_drain_seconds` is the longest you should wait for the final `session.ended` envelope. After the acknowledgment the server rejects new video, finishes analyzing the video it already accepted (emitting the normal envelopes in order, plus `signal.ended` for still-active signals), sends `session.ended`, and closes the socket with code 1000 — so listen for `"session.ended"` (or `"close"`) rather than calling [close](#close-3). ###### Returns `void` ##### close() ```ts theme={null} close(code?, reason?): void; ``` Close the connection immediately, without the graceful drain handshake. ###### Parameters | Parameter | Type | | --------- | -------- | | `code?` | `number` | | `reason?` | `string` | ###### Returns `void` ##### sendJson() ```ts theme={null} protected sendJson(payload): void; ``` Send an arbitrary JSON payload as a text frame. ###### Parameters | Parameter | Type | | --------- | --------- | | `payload` | `unknown` | ###### Returns `void` *** ### StreamClient A typed client over the stream WebSocket protocol. Authentication uses the `Sec-WebSocket-Protocol: access_token, ` subprotocol pair, which is portable across browsers and Node (the standard `WebSocket` constructor cannot set an `Authorization` header). Inbound frames are decoded into the `StreamEvent` union and dispatched through the typed `on` surface inherited from [SessionSocketClient](#abstract-sessionsocketclient); outbound video is sent as binary frames and session config as a JSON text frame. #### Example ```ts theme={null} const stream = client.stream(); stream.on("signal.detected", (e) => console.log(e.data.signal_type)); await stream.connect(); await stream.waitForSessionReady(); stream.updateConfig({ include: ["conversation_quality_overall"] }); stream.sendVideo(chunk); stream.requestClose(); // graceful: drains, then session.ended + close ``` #### Extends * [`SessionSocketClient`](#abstract-sessionsocketclient)\<[`StreamEventMap`](#streameventmap), [`StreamSessionConfig`](#streamsessionconfig)> #### Constructors ##### Constructor ```ts theme={null} new StreamClient(options): StreamClient; ``` ###### Parameters | Parameter | Type | | --------- | ----------------------------------------------------------- | | `options` | [`SessionSocketClientOptions`](#sessionsocketclientoptions) | ###### Returns [`StreamClient`](#streamclient) ###### Overrides [`SessionSocketClient`](#abstract-sessionsocketclient).[`constructor`](#constructor-8) #### Properties | Property | Modifier | Type | Default value | Description | Overrides | | ---------------------------------------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `endpointPath` | `readonly` | `"/v1/stream/analyze"` | `"/v1/stream/analyze"` | Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`endpointPath`](#endpointpath-1) | | `clientName` | `readonly` | `"StreamClient"` | `"StreamClient"` | Concrete class name used in configuration error messages. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`clientName`](#clientname-1) | | `displayName` | `readonly` | `"Stream"` | `"Stream"` | Human-readable surface name used in error messages (e.g. `"Stream"`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`displayName`](#displayname-1) | | `scopeHint` | `readonly` | `"The credentials may be invalid or lack the stream scope."` | `"The credentials may be invalid or lack the stream scope."` | Appended to the connect-rejection message to hint at the likely scope issue. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`scopeHint`](#scopehint-1) | #### Accessors ##### isOpen ###### Get Signature ```ts theme={null} get isOpen(): boolean; ``` Whether the underlying socket is open. ###### Returns `boolean` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`isOpen`](#isopen-1) #### Methods ##### on() ```ts theme={null} on(event, handler): () => void; ``` Subscribe to an event. Returns an unsubscribe function. Use a specific envelope `type` (e.g. `"signal.detected"`), `"message"` for every envelope, or a lifecycle event (`"open"`, `"close"`, `"socketError"`). ###### Type Parameters | Type Parameter | | ------------------------------------------------------- | | `K` *extends* keyof [`StreamEventMap`](#streameventmap) | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`StreamEventMap`](#streameventmap)\[`K`]> | ###### Returns () => `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`on`](#on-1) ##### off() ```ts theme={null} off(event, handler): void; ``` Unsubscribe a previously registered handler. ###### Type Parameters | Type Parameter | | ------------------------------------------------------- | | `K` *extends* keyof [`StreamEventMap`](#streameventmap) | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`StreamEventMap`](#streameventmap)\[`K`]> | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`off`](#off-1) ##### once() ```ts theme={null} once(event, handler): () => void; ``` Subscribe to the next occurrence of an event, then auto-unsubscribe. ###### Type Parameters | Type Parameter | | ------------------------------------------------------- | | `K` *extends* keyof [`StreamEventMap`](#streameventmap) | ###### Parameters | Parameter | Type | | --------- | ------------------------------------------------------------------- | | `event` | `K` | | `handler` | [`Listener`](#listener)\<[`StreamEventMap`](#streameventmap)\[`K`]> | ###### Returns () => `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`once`](#once-1) ##### connect() ```ts theme={null} connect(): Promise; ``` Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials). ###### Returns `Promise`\<`void`> ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`connect`](#connect-1) ##### waitForSessionReady() ```ts theme={null} waitForSessionReady(): Promise; ``` Wait for the `session.ready` envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after [connect](#connect-2) without racing the frame. ###### Returns `Promise`\<[`SessionReadyEvent`](#sessionreadyevent)> ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`waitForSessionReady`](#waitforsessionready-1) ##### sendVideo() ```ts theme={null} sendVideo(chunk): void; ``` Send a chunk of WebM or fragmented-MP4 video as a binary frame. ###### Parameters | Parameter | Type | | --------- | --------------------------- | | `chunk` | [`VideoChunk`](#videochunk) | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`sendVideo`](#sendvideo-1) ##### updateConfig() ```ts theme={null} updateConfig(config): void; ``` Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a `session.updated` envelope. ###### Parameters | Parameter | Type | | --------- | --------------------------------------------- | | `config` | [`StreamSessionConfig`](#streamsessionconfig) | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`updateConfig`](#updateconfig-1) ##### requestClose() ```ts theme={null} requestClose(): void; ``` Request a graceful end-of-analysis shutdown (`session.close`). The server acknowledges with a `session.closing` envelope whose `data.max_drain_seconds` is the longest you should wait for the final `session.ended` envelope. After the acknowledgment the server rejects new video, finishes analyzing the video it already accepted (emitting the normal envelopes in order, plus `signal.ended` for still-active signals), sends `session.ended`, and closes the socket with code 1000 — so listen for `"session.ended"` (or `"close"`) rather than calling [close](#close-4). ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`requestClose`](#requestclose-1) ##### close() ```ts theme={null} close(code?, reason?): void; ``` Close the connection immediately, without the graceful drain handshake. ###### Parameters | Parameter | Type | | --------- | -------- | | `code?` | `number` | | `reason?` | `string` | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`close`](#close-3) ##### sendJson() ```ts theme={null} protected sendJson(payload): void; ``` Send an arbitrary JSON payload as a text frame. ###### Parameters | Parameter | Type | | --------- | --------- | | `payload` | `unknown` | ###### Returns `void` ###### Inherited from [`SessionSocketClient`](#abstract-sessionsocketclient).[`sendJson`](#sendjson-1) *** ### UploadClient Analyzes a complete video file and returns a single report. The request is sent as `multipart/form-data` with the bearer token attached automatically from the configured [TokenProvider](#tokenprovider). #### Constructors ##### Constructor ```ts theme={null} new UploadClient(options): UploadClient; ``` ###### Parameters | Parameter | Type | | --------- | --------------------------------------------- | | `options` | [`UploadClientOptions`](#uploadclientoptions) | ###### Returns [`UploadClient`](#uploadclient) #### Methods ##### analyze() ```ts theme={null} analyze(input): Promise; ``` Analyze a video file in upload mode. ###### Parameters | Parameter | Type | | --------- | ------------------------------------------- | | `input` | [`AnalyzeUploadInput`](#analyzeuploadinput) | ###### Returns `Promise`\<[`AnalysisResult`](#analysisresult)> ###### Throws on a rejected request (auth, validation, too-large/too-short media, quota, unprocessable video, server error). ## Interfaces ### AuthClientOptions Options for constructing an [AuthClient](#authclient). #### Properties | Property | Type | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `baseUrl?` | `string` | Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`. | | `environment?` | [`Environment`](#environment-2) | Named environment to target. Defaults to `"production"`. | | `fetch?` | \{ (`input`, `init?`): `Promise`\<`Response`>; (`input`, `init?`): `Promise`\<`Response`>; } | Custom `fetch` implementation. Defaults to the global `fetch`. | *** ### TokenProvider Anything that can supply a bearer token on demand. #### Methods ##### getToken() ```ts theme={null} getToken(): Promise; ``` Return a currently-valid bearer token, minting/refreshing as needed. ###### Returns `Promise`\<`string`> *** ### TokenManagerOptions Options for a [TokenManager](#tokenmanager). #### Properties | Property | Type | Description | | --------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `authClient` | [`AuthClient`](#authclient) | - | | `credentials` | [`ApiKeyCredentials`](#apikeycredentials) | - | | `scopes` | [`ScopeValue`](#scopevalue)\[] | Scopes to request when minting tokens. | | `refreshSkewSeconds?` | `number` | Refresh a cached token this many seconds *before* its stated expiry, to absorb clock skew and request latency. Defaults to 30. | | `now?` | () => `number` | Injectable clock (milliseconds). Defaults to `Date.now`. Test seam. | *** ### ApiKeyCredentials Credentials issued in the Interhuman customer platform. #### Extended by * [`TokenRequest`](#tokenrequest) #### Properties | Property | Type | Description | | -------------------------------- | -------- | ---------------------------------- | | `keyId` | `string` | API key ID from the dashboard. | | `keySecret` | `string` | API key secret from the dashboard. | *** ### ApiKeyCredential A full API key string used to mint and revoke client tokens. #### Extended by * [`ClientTokenRequest`](#clienttokenrequest) * [`RevokeClientTokenRequest`](#revokeclienttokenrequest) #### Properties | Property | Type | Description | | -------------------------- | -------- | ----------------------------------------------------------------------- | | `apiKey` | `string` | Your full API key from the dashboard (`ih___`). | *** ### TokenRequest Request body for `POST /v1/auth`. #### Extends * [`ApiKeyCredentials`](#apikeycredentials) #### Properties | Property | Type | Description | Inherited from | | ---------------------------------- | ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------- | | `keyId` | `string` | API key ID from the dashboard. | [`ApiKeyCredentials`](#apikeycredentials).[`keyId`](#keyid) | | `keySecret` | `string` | API key secret from the dashboard. | [`ApiKeyCredentials`](#apikeycredentials).[`keySecret`](#keysecret) | | `scopes` | [`ScopeValue`](#scopevalue)\[] | Requested scopes; at least one is required. | - | *** ### TokenResponse Response body from `POST /v1/auth`. #### Properties | Property | Type | Description | | -------------------------------------- | -------- | ------------------------------------------------ | | `access_token` | `string` | The minted bearer access token (a JWT). | | `token_type` | `string` | Token type; always `"Bearer"`. | | `expires_in` | `number` | Seconds until the token expires (typically 900). | | `scope` | `string` | Space-separated list of granted scopes. | *** ### ClientTokenRequest Request for minting an ephemeral, capped **client token** (`POST /v1/client_tokens`). Call this server-side with your API key; the returned token is safe to hand to a browser to call the upload, stream, or real-time endpoints directly. Every cap is optional. The token grants only the requested [scopes](#scopes-2) (default `interhumanai.stream`); the caps are enforced on streaming sessions (stream / real-time) and the video budget additionally spans upload. #### Extends * [`ApiKeyCredential`](#apikeycredential) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `apiKey` | `string` | Your full API key from the dashboard (`ih___`). | [`ApiKeyCredential`](#apikeycredential).[`apiKey`](#apikey) | | `scopes?` | [`ScopeValue`](#scopevalue)\[] | Scopes to grant the token. Defaults to `["interhumanai.stream"]`. | - | | `expiresIn?` | `number` | Requested lifetime in seconds. Clamped to 60–3600; defaults to 300. | - | | `maxDurationSeconds?` | `number` | Max wall-clock duration, in seconds, of a session opened with this token. | - | | `maxBytes?` | `number` | Max cumulative video bytes a session opened with this token may send. | - | | `maxConcurrent?` | `number` | Max number of concurrent sessions opened with this token. Defaults to 1 (one session at a time) when omitted server-side. | - | | `maxVideoSeconds?` | `number` | Max total seconds of video the token may process across upload/stream/real-time. | - | | `allowedOrigins?` | `string`\[] | Allow-list of browser `Origin` values permitted to use this token. | - | *** ### ClientTokenResponse Response body from `POST /v1/client_tokens`. #### Properties | Property | Type | Description | | ------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------- | | `access_token` | `string` | The minted client token (a JWT). | | `token_type` | `string` | Token type; always `"Bearer"`. | | `expires_in` | `number` | Seconds until the token expires. | | `scope` | `string` | Space-separated list of granted scopes. | | `max_duration_seconds?` | `number` \| `null` | Per-token max session duration that will be enforced, if any. | | `max_bytes?` | `number` \| `null` | Per-token max cumulative session bytes that will be enforced, if any. | | `max_concurrent?` | `number` \| `null` | Per-token max concurrent sessions that will be enforced, if any. | | `max_video_seconds?` | `number` \| `null` | Per-token total video-seconds budget that will be enforced, if any. | | `allowed_origins?` | `string`\[] \| `null` | Per-token allow-list of browser origins that will be enforced, if any. | *** ### RevokeClientTokenRequest Request for revoking a client token (`POST /v1/client_tokens/revoke`). #### Extends * [`ApiKeyCredential`](#apikeycredential) #### Properties | Property | Type | Description | Inherited from | | ---------------------------- | -------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- | | `apiKey` | `string` | Your full API key from the dashboard (`ih___`). | [`ApiKeyCredential`](#apikeycredential).[`apiKey`](#apikey) | | `token` | `string` | The client token to revoke (as returned in `access_token`). | - | *** ### InterhumanClientOptions Options for constructing an [InterhumanClient](#interhumanclient). #### Properties | Property | Type | Description | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credentials?` | [`ApiKeyCredentials`](#apikeycredentials) | API-key credentials. The client exchanges these at `/v1/auth` and refreshes the resulting token automatically. Provide either `credentials` or `accessToken`. | | `accessToken?` | `string` | A pre-issued bearer access token, used as-is. Provide either `accessToken` or `credentials`. | | `scopes?` | [`ScopeValue`](#scopevalue)\[] | Scopes requested when minting tokens from `credentials`. Defaults to upload + stream. Ignored when `accessToken` is supplied. | | `environment?` | [`Environment`](#environment-2) | Named environment to target. Defaults to `"production"`. | | `baseUrl?` | `string` | Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`. | | `fetch?` | \{ (`input`, `init?`): `Promise`\<`Response`>; (`input`, `init?`): `Promise`\<`Response`>; } | Custom `fetch` implementation. Defaults to the global `fetch`. | | `webSocket?` | [`WebSocketFactory`](#websocketfactory) | Custom WebSocket factory for the stream and real-time clients. Defaults to the global `WebSocket` (browsers, Node 22+). | | `refreshSkewSeconds?` | `number` | Seconds before stated expiry to refresh a minted token. Defaults to 30. | *** ### ApiErrorBody The canonical error body returned by every HTTP error path. #### Properties | Property | Type | Description | | ------------------------------------------- | ------------------ | -------------------------------------------------------------------- | | `error_id` | `string` | Machine-readable error code, e.g. `"ih2001"`. | | `correlation_id?` | `string` \| `null` | Connection/request correlation id; quote it when contacting support. | | `link?` | `string` \| `null` | URL with more information about this error, when available. | | `message?` | `string` \| `null` | Human-readable explanation, when available. | *** ### TranscriptSegment One diarized utterance of a real-time transcript. The same shape is used for the transcript you send (`sendTranscript`) and the live transcript the server streams back (`transcript.generated`). #### Properties | Property | Type | Description | | ---------------------------- | -------- | --------------------------------------------------------- | | `start` | `number` | Start time of the utterance, in seconds. | | `end` | `number` | End time of the utterance, in seconds. | | `text` | `string` | The spoken text of this segment. | | `speaker` | `number` | Zero-based index identifying the speaker of this segment. | *** ### RealtimeSessionConfig Client-to-server real-time session config (sent as a JSON text frame). The last config sent fully replaces the active one; the server acknowledges with a `session.updated` envelope. The stream `include` flags are not accepted — the real-time endpoint never emits the conversation-quality or engagement updates those flags control. #### Properties | Property | Type | Description | | --------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `analysis_groups?` | [`AnalysisGroup`](#analysisgroup-1)\[] | Analysis surfaces to run for this session, any subset of what the server advertises on `session.ready` under `supported_session_config_options.analysis_groups`. Must be non-empty when present: an empty array — like selecting a group the server has not enabled — is rejected with an `error` envelope. When omitted, the server default is `audio` + `visual` (not `video`), clamped to what the deployment allows. | | `realtime_feedback_frequency?` | [`RealtimeFeedbackFrequency`](#realtimefeedbackfrequency-1) | How often feedback runs once enabled. Has no effect until a non-empty `realtime_feedback_instructions` enables feedback. | | `realtime_feedback_instructions?` | `string` | Configuration block for the periodic feedback step, and the switch that enables it: feedback runs only when this is a non-empty string (there is no default prompt). It sets the goal, domain/context, and the focus, tone, or output style of the guidance. It is treated as untrusted configuration data — it shapes the guidance but cannot override the server's feedback task or output contract. | *** ### TranscriptUpdatedFrame The inbound `transcript.updated` text frame carrying a caller-supplied transcript. Sent by `RealtimeClient.sendTranscript`; the most recent transcript replaces any prior one and is rendered into the feedback prompt. #### Properties | Property | Type | Description | | ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------- | | `type` | `"transcript.updated"` | - | | `transcript` | [`TranscriptSegment`](#transcriptsegment)\[] | The full transcript as `{start, end, text, speaker}` segments, in spoken order. | *** ### RealtimeSessionReadyConfigOptions Supported real-time session-config options advertised on `session.ready`. Unlike the stream options, only the real-time controls appear here — never the stream `include` / `goal_dimensions` options. #### Properties | Property | Type | Description | | ---------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `realtime_feedback_instructions` | `"string"` | Always the literal `"string"`: `realtime_feedback_instructions` takes free-form text, so its accepted JSON type is advertised instead of a value list. | | `realtime_feedback_frequency` | [`RealtimeFeedbackFrequency`](#realtimefeedbackfrequency-1)\[] | Accepted `realtime_feedback_frequency` values. | | `analysis_groups` | [`AnalysisGroup`](#analysisgroup-1)\[] | Analysis groups this deployment allows — the valid values for the config's `analysis_groups` field, so you can pick a subset without round-tripping a rejection. | *** ### RealtimeSessionReadyData `session.ready` payload — the same connection-level limits as the stream `session.ready`, with the real-time supported-config options. #### Properties | Property | Type | Description | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `session_idle_timeout_seconds` | `number` | Idle seconds tolerated before the server closes the session (`0` = disabled). | | `session_max_duration_seconds` | `number` | Maximum total session duration in seconds (`0` = disabled). | | `max_segment_duration_seconds` | `number` \| `null` | Max probed duration of one inbound chunk, or `null` when only the size cap binds. | | `min_segment_size_bytes` | `number` | Minimum size in bytes of one inbound chunk. | | `max_segment_size_bytes` | `number` | Maximum size in bytes of one inbound chunk. | | `supported_session_config_options` | [`RealtimeSessionReadyConfigOptions`](#realtimesessionreadyconfigoptions) | - | *** ### RealtimeSessionReadyEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `type` | `"session.ready"` | - | - | | `data` | [`RealtimeSessionReadyData`](#realtimesessionreadydata) | - | - | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | *** ### RealtimeSessionUpdatedData `session.updated` payload — the consolidated real-time config after a config frame applied. Reports only the real-time options, never the stream-only `include` / `goal_dimensions` fields. #### Properties | Property | Type | Description | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `realtime_feedback_instructions` | `string` \| `null` | The applied `realtime_feedback_instructions`, echoed back verbatim; `null` when unset. | | `realtime_feedback_frequency` | [`RealtimeFeedbackFrequency`](#realtimefeedbackfrequency-1) \| `null` | The active feedback frequency; `null` when unset. | | `analysis_groups` | [`AnalysisGroup`](#analysisgroup-1)\[] | The effective analysis-group selection in force, already clamped to what the deployment allows (the server default when you have not chosen one). | *** ### RealtimeSessionUpdatedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `type` | `"session.updated"` | - | - | | `data` | [`RealtimeSessionUpdatedData`](#realtimesessionupdateddata) | - | - | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | *** ### TranscriptGeneratedEvent `transcript.generated` — the server's own live transcription of the analyzed audio, emitted when the deployment's transcription track produced new speech. Each event carries only text not already sent, so concatenating the `text` of successive events reconstructs the running transcript without duplication. `speaker` is always `0` (single-speaker transcription). #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `type` | `"transcript.generated"` | - | - | | `data` | [`TranscriptSegment`](#transcriptsegment) | - | - | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | *** ### RealtimeFeedbackGeneratedData `realtime_feedback.generated` payload — one feedback run's guidance text. #### Properties | Property | Type | Description | | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `string` | The guidance text returned by the feedback model — one short recommendation for the responding speaker, or the literal `NO_GUIDANCE` when the signals warrant no adjustment. | | `start` | `number` | Start of the analyzed interval this feedback covers (seconds, session time). | | `end` | `number` | End of the analyzed interval this feedback covers (seconds, session time). | *** ### RealtimeFeedbackGeneratedEvent `realtime_feedback.generated` — the periodic feedback result. Emitted only when `realtime_feedback_instructions` has enabled feedback, paced by `realtime_feedback_frequency`. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `type` | `"realtime_feedback.generated"` | - | - | | `data` | [`RealtimeFeedbackGeneratedData`](#realtimefeedbackgenerateddata) | - | - | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | *** ### RealtimeEventMap Event payloads keyed by event name, for the typed `on`/`off` surface of the real-time client. The envelope `type`s map to their envelope objects; the remaining keys are client-level lifecycle events. #### Properties | Property | Type | Description | | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ | | `session.ready` | [`RealtimeSessionReadyEvent`](#realtimesessionreadyevent) | - | | `session.updated` | [`RealtimeSessionUpdatedEvent`](#realtimesessionupdatedevent) | - | | `session.closing` | [`SessionClosingEvent`](#sessionclosingevent) | - | | `session.ended` | [`SessionEndedEvent`](#sessionendedevent) | - | | `signal.detected` | [`SignalDetectedEvent`](#signaldetectedevent) | - | | `signal.updated` | [`SignalUpdatedEvent`](#signalupdatedevent) | - | | `signal.ended` | [`SignalEndedEvent`](#signalendedevent) | - | | `transcript.generated` | [`TranscriptGeneratedEvent`](#transcriptgeneratedevent) | - | | `realtime_feedback.generated` | [`RealtimeFeedbackGeneratedEvent`](#realtimefeedbackgeneratedevent) | - | | `coverage.dropped` | [`CoverageDroppedEvent`](#coveragedroppedevent) | - | | `error` | [`StreamErrorEvent`](#streamerrorevent) | - | | `message` | [`RealtimeEvent`](#realtimeevent) | Fires for every server→client envelope, regardless of type. | | `open` | `void` | Fires once when the WebSocket connection opens. | | `close` | [`StreamCloseInfo`](#streamcloseinfo) | Fires once when the connection closes. | | `socketError` | `Error` | Transport-level socket error (distinct from the `error` envelope). | *** ### SessionSocketClientOptions Options shared by every WebSocket session client. #### Properties | Property | Type | Description | | ------------------------------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `tokenProvider` | [`TokenProvider`](#tokenprovider) | Supplies the bearer token used to authenticate the connection. | | `baseUrl?` | `string` | Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`. | | `environment?` | [`Environment`](#environment-2) | Named environment to target. Defaults to `"production"`. | | `webSocket?` | [`WebSocketFactory`](#websocketfactory) | Custom WebSocket factory. Defaults to the global `WebSocket` (browsers, Node 22+). Supply one backed by the `ws` package on older Node. | *** ### SessionSocketEventMapBase The lifecycle and wildcard events every session event map carries, alongside its protocol-specific envelope `type` keys. `TEvent` is the protocol's envelope union and `TReady` its `session.ready` envelope. #### Type Parameters | Type Parameter | | -------------- | | `TEvent` | | `TReady` | #### Properties | Property | Type | Description | | ----------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ | | `session.ready` | `TReady` | The `session.ready` envelope — first frame after the handshake. | | `message` | `TEvent` | Fires for every server→client envelope, regardless of type. | | `open` | `void` | Fires once when the WebSocket connection opens. | | `close` | [`StreamCloseInfo`](#streamcloseinfo) | Fires once when the connection closes. | | `socketError` | `Error` | Transport-level socket error (distinct from the `error` envelope). | *** ### StreamEnvelopeBase Fields shared by every server→client envelope. #### Extended by * [`ConversationQualityUpdatedEvent`](#conversationqualityupdatedevent) * [`CoverageDroppedEvent`](#coveragedroppedevent) * [`EngagementUpdatedEvent`](#engagementupdatedevent) * [`FeedbackGeneratedEvent`](#feedbackgeneratedevent) * [`SessionClosingEvent`](#sessionclosingevent) * [`SessionEndedEvent`](#sessionendedevent) * [`SessionReadyEvent`](#sessionreadyevent) * [`SessionUpdatedEvent`](#sessionupdatedevent) * [`SignalDetectedEvent`](#signaldetectedevent) * [`SignalEndedEvent`](#signalendedevent) * [`SignalUpdatedEvent`](#signalupdatedevent) * [`StreamErrorEvent`](#streamerrorevent) * [`RealtimeSessionReadyEvent`](#realtimesessionreadyevent) * [`RealtimeSessionUpdatedEvent`](#realtimesessionupdatedevent) * [`RealtimeFeedbackGeneratedEvent`](#realtimefeedbackgeneratedevent) * [`TranscriptGeneratedEvent`](#transcriptgeneratedevent) #### Properties | Property | Type | Description | | -------------------------------------------- | -------- | ------------------------------------------------------------ | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | *** ### SessionReadyConfigOptions Supported session-config options advertised on `session.ready`. #### Properties | Property | Type | Description | | -------------------------------------------- | ------------------------------------------------ | --------------------------------------------- | | `include` | [`IncludeFlag`](#includeflag-1)\[] | - | | `goal_dimensions` | [`GoalDimension`](#goaldimension-1)\[] \| `null` | `null` when the feedback feature is disabled. | *** ### SessionReadyData `session.ready` payload — session limits and supported config. #### Properties | Property | Type | Description | | -------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------- | | `session_idle_timeout_seconds` | `number` | Idle seconds tolerated before the server closes the session (`0` = disabled). | | `session_max_duration_seconds` | `number` | Maximum total session duration in seconds (`0` = disabled). | | `max_segment_duration_seconds` | `number` \| `null` | Max probed duration of one inbound chunk, or `null` when only the size cap binds. | | `min_segment_size_bytes` | `number` | Minimum size in bytes of one inbound chunk. | | `max_segment_size_bytes` | `number` | Maximum size in bytes of one inbound chunk. | | `supported_session_config_options` | [`SessionReadyConfigOptions`](#sessionreadyconfigoptions) | - | *** ### SessionReadyEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"session.ready"` | - | - | | `data` | [`SessionReadyData`](#sessionreadydata) | - | - | *** ### SessionUpdatedData `session.updated` payload — consolidated config after a config frame applied. #### Properties | Property | Type | | ---------------------------------------------- | ------------------------------------------------ | | `include` | [`IncludeFlag`](#includeflag-1)\[] | | `goal_dimensions` | [`GoalDimension`](#goaldimension-1)\[] \| `null` | *** ### SessionUpdatedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"session.updated"` | - | - | | `data` | [`SessionUpdatedData`](#sessionupdateddata) | - | - | *** ### SessionClosingData `session.closing` payload — the graceful-close drain contract. #### Properties | Property | Type | Description | | ------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `max_drain_seconds` | `number` | Maximum seconds the server will spend draining accepted work before it closes the session; `session.ended` arrives no later than this. The session closes earlier when the accepted work finishes sooner. | *** ### SessionClosingEvent Acknowledges a caller-initiated `session.close` request. From this point the server rejects new video, finishes analyzing the video it already accepted, emits final lifecycle envelopes (`signal.ended` for still-active signals), sends `session.ended`, and closes the socket. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"session.closing"` | - | - | | `data` | [`SessionClosingData`](#sessionclosingdata) | - | - | *** ### SessionEndedData `session.ended` payload — why the session ended. #### Properties | Property | Type | Description | | -------------------------- | ------------------- | ---------------------------------------------------------- | | `reason` | `"client_shutdown"` | `client_shutdown` = the caller requested a graceful close. | *** ### SessionEndedEvent The final message of a gracefully closed session: all analysis is closed and the server closes the WebSocket (code 1000) immediately after sending it. No further analysis messages follow. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | -------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"session.ended"` | - | - | | `data` | [`SessionEndedData`](#sessionendeddata) | - | - | *** ### SignalDetectedData #### Properties | Property | Type | Description | | ------------------------------------ | ----------------------------------------- | ------------------------------------------ | | `signal_type` | [`SignalType`](#signaltype) | - | | `start` | `number` | Seconds, absolute session-cumulative time. | | `probability` | [`Probability`](#probability-2) \| `null` | - | | `rationale` | `string` \| `null` | - | *** ### SignalDetectedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"signal.detected"` | - | - | | `data` | [`SignalDetectedData`](#signaldetecteddata) | - | - | *** ### SignalUpdatedData #### Properties | Property | Type | | -------------------------------------- | ----------------------------------------- | | `signal_type` | [`SignalType`](#signaltype) | | `start` | `number` | | `probability` | [`Probability`](#probability-2) \| `null` | | `rationale` | `string` \| `null` | *** ### SignalUpdatedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"signal.updated"` | - | - | | `data` | [`SignalUpdatedData`](#signalupdateddata) | - | - | *** ### SignalEndedData #### Properties | Property | Type | Description | | -------------------------------------- | --------------------------- | ------------------------------------------ | | `signal_type` | [`SignalType`](#signaltype) | - | | `end` | `number` | Seconds, absolute session-cumulative time. | *** ### SignalEndedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"signal.ended"` | - | - | | `data` | [`SignalEndedData`](#signalendeddata) | - | - | *** ### EngagementUpdatedData #### Properties | Property | Type | | -------------------------- | ------------------------------------- | | `state` | [`EngagementLevel`](#engagementlevel) | | `start` | `number` | *** ### EngagementUpdatedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"engagement.updated"` | - | - | | `data` | [`EngagementUpdatedData`](#engagementupdateddata) | - | - | *** ### ConversationQualityUpdatedData #### Properties | Property | Type | Description | | ------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `overall` | [`ConversationQualityValues`](#conversationqualityvalues) \| `null` | Non-null when `conversation_quality_overall` was requested. | | `timeline` | \| [`ConversationQualityTimelineEntry`](#conversationqualitytimelineentry)\[] \| `null` | Non-null when `conversation_quality_timeline` was requested and the period had signals. | *** ### ConversationQualityUpdatedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"conversation_quality.updated"` | - | - | | `data` | [`ConversationQualityUpdatedData`](#conversationqualityupdateddata) | - | - | *** ### FeedbackGeneratedData #### Properties | Property | Type | Description | | ------------------------------ | -------- | --------------------------------------------------------------------------- | | `feedback` | `string` | Comma-separated relevant signal types observed since the previous emission. | *** ### FeedbackGeneratedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"feedback.generated"` | - | - | | `data` | [`FeedbackGeneratedData`](#feedbackgenerateddata) | - | - | *** ### CoverageDroppedRange A contiguous range of media skipped under backpressure (not billed). #### Properties | Property | Type | | -------------------------- | -------- | | `start` | `number` | | `end` | `number` | *** ### CoverageDroppedData #### Properties | Property | Type | | -------------------------- | -------------------------------------------------- | | `ranges` | [`CoverageDroppedRange`](#coveragedroppedrange)\[] | *** ### CoverageDroppedEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"coverage.dropped"` | - | - | | `data` | [`CoverageDroppedData`](#coveragedroppeddata) | - | - | *** ### StreamErrorData #### Properties | Property | Type | Description | | ------------------------------ | ------------------ | -------------------------------------------------------- | | `code` | `string` | Machine-readable error code (e.g. `"ih6002"`). | | `message` | `string` | - | | `link` | `string` \| `null` | - | | `segment` | `number` \| `null` | Inbound caller-chunk index when applicable, else `null`. | *** ### StreamErrorEvent Fields shared by every server→client envelope. #### Extends * [`StreamEnvelopeBase`](#streamenvelopebase) #### Properties | Property | Type | Description | Inherited from | | --------------------------------------------- | ------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp-4) | | `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-5) | | `type` | `"error"` | - | - | | `data` | [`StreamErrorData`](#streamerrordata) | - | - | *** ### StreamSessionConfig Client-to-server session config (sent as a JSON text frame). #### Properties | Property | Type | Description | | ----------------------------------------------- | -------------------------------------- | ------------------------------------------------------------ | | `include?` | [`IncludeFlag`](#includeflag-1)\[] | Conversation-quality sections to include in result messages. | | `goal_dimensions?` | [`GoalDimension`](#goaldimension-1)\[] | Goal dimensions for this session (drive periodic feedback). | *** ### SessionCloseRequest Client-to-server graceful close request (sent as a JSON text frame). Tells the server the caller is done sending video; the server acknowledges with `session.closing` and ends the session with `session.ended`. #### Properties | Property | Type | | ------------------------- | ----------------- | | `type` | `"session.close"` | *** ### StreamCloseInfo Information about a closed stream connection. #### Properties | Property | Type | | ---------------------------- | -------- | | `code` | `number` | | `reason` | `string` | *** ### StreamEventMap Event payloads keyed by event name, for the typed `on`/`off` surface. The twelve envelope `type`s map to their envelope objects; the remaining keys are client-level lifecycle events. #### Properties | Property | Type | Description | | --------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ | | `session.ready` | [`SessionReadyEvent`](#sessionreadyevent) | - | | `session.updated` | [`SessionUpdatedEvent`](#sessionupdatedevent) | - | | `session.closing` | [`SessionClosingEvent`](#sessionclosingevent) | - | | `session.ended` | [`SessionEndedEvent`](#sessionendedevent) | - | | `signal.detected` | [`SignalDetectedEvent`](#signaldetectedevent) | - | | `signal.updated` | [`SignalUpdatedEvent`](#signalupdatedevent) | - | | `signal.ended` | [`SignalEndedEvent`](#signalendedevent) | - | | `engagement.updated` | [`EngagementUpdatedEvent`](#engagementupdatedevent) | - | | `conversation_quality.updated` | [`ConversationQualityUpdatedEvent`](#conversationqualityupdatedevent) | - | | `feedback.generated` | [`FeedbackGeneratedEvent`](#feedbackgeneratedevent) | - | | `coverage.dropped` | [`CoverageDroppedEvent`](#coveragedroppedevent) | - | | `error` | [`StreamErrorEvent`](#streamerrorevent) | - | | `message` | [`StreamEvent`](#streamevent) | Fires for every server→client envelope, regardless of type. | | `open` | `void` | Fires once when the WebSocket connection opens. | | `close` | [`StreamCloseInfo`](#streamcloseinfo) | Fires once when the connection closes. | | `socketError` | `Error` | Transport-level socket error (distinct from the `error` envelope). | *** ### WebSocketLike The subset of the WHATWG `WebSocket` interface the SDK relies on. Both the browser `WebSocket` and Node 22+'s global `WebSocket` satisfy this. #### Properties | Property | Modifier | Type | | ---------------------------------- | ---------- | -------- | | `readyState` | `readonly` | `number` | | `binaryType` | `public` | `string` | #### Methods ##### send() ```ts theme={null} send(data): void; ``` ###### Parameters | Parameter | Type | | --------- | -------------------------------------------------------------------------------- | | `data` | `string` \| `Blob` \| `ArrayBufferLike` \| `ArrayBufferView`\<`ArrayBufferLike`> | ###### Returns `void` ##### close() ```ts theme={null} close(code?, reason?): void; ``` ###### Parameters | Parameter | Type | | --------- | -------- | | `code?` | `number` | | `reason?` | `string` | ###### Returns `void` ##### addEventListener() ```ts theme={null} addEventListener(type, listener): void; ``` ###### Parameters | Parameter | Type | | ---------- | ------------------- | | `type` | `string` | | `listener` | (`event`) => `void` | ###### Returns `void` ##### removeEventListener() ```ts theme={null} removeEventListener(type, listener): void; ``` ###### Parameters | Parameter | Type | | ---------- | ------------------- | | `type` | `string` | | `listener` | (`event`) => `void` | ###### Returns `void` *** ### Signal A single social signal detected over a span of the analyzed media. #### Properties | Property | Type | Description | | -------------------------------------- | ----------------------------------------- | ---------------------- | | `type` | [`SignalType`](#signaltype) | - | | `start` | `number` | Start time in seconds. | | `end` | `number` | End time in seconds. | | `probability` | [`Probability`](#probability-2) \| `null` | - | | `rationale` | `string` \| `null` | - | *** ### EngagementStateEntry A contiguous stretch of media labeled with a single engagement state. #### Properties | Property | Type | | -------------------------- | ------------------------------------- | | `state` | [`EngagementLevel`](#engagementlevel) | | `start` | `number` | | `end` | `number` | *** ### ConversationQualityValues The five conversation-quality dimension scores plus their mean (0–100). #### Properties | Property | Type | | ---------------------------------------- | -------- | | `quality_index` | `number` | | `clarity` | `number` | | `authority` | `number` | | `energy` | `number` | | `rapport` | `number` | | `learning` | `number` | *** ### ConversationQualityTimelineEntry Conversation-quality scores for one window of the timeline. #### Properties | Property | Type | | -------------------------- | --------------------------------------------------------- | | `start` | `number` | | `end` | `number` | | `values` | [`ConversationQualityValues`](#conversationqualityvalues) | *** ### ConversationQuality Overall and time-varying conversation-quality scores. #### Properties | Property | Type | | -------------------------------- | -------------------------------------------------------------------------- | | `overall` | [`ConversationQualityValues`](#conversationqualityvalues) | | `timeline` | [`ConversationQualityTimelineEntry`](#conversationqualitytimelineentry)\[] | *** ### InteractionFeedback Structured interaction feedback returned by the coach model. #### Properties | Property | Type | | ------------------------------------------------- | -------------------------------------- | | `type` | [`FeedbackType`](#feedbacktype) | | `message?` | `string` \| `null` | | `active_dimensions?` | [`GoalDimension`](#goaldimension-1)\[] | | `primary_signal?` | [`SignalType`](#signaltype) \| `null` | | `reason?` | `string` \| `null` | *** ### AnalysisResult The full report returned by `POST /v1/upload/analyze`. #### Properties | Property | Type | | ------------------------------------------------------- | ------------------------------------------------------- | | `signals` | [`Signal`](#signal)\[] | | `engagement_state` | [`EngagementStateEntry`](#engagementstateentry)\[] | | `feedback?` | [`InteractionFeedback`](#interactionfeedback) \| `null` | | `conversation_quality?` | [`ConversationQuality`](#conversationquality) \| `null` | *** ### AnalyzeUploadInput Arguments for [UploadClient.analyze](#analyze). #### Properties | Property | Type | Description | | ----------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `file` | [`VideoInput`](#videoinput) | The video file to analyze (mp4/avi/mov/mkv/mpeg-ts/webm, ≥3s, ≤32MB). | | `filename?` | `string` | Filename used when `file` is a `Blob` without a name. Defaults to `"video"`. | | `include?` | [`IncludeFlag`](#includeflag-1)\[] | Optional response sections to include. When omitted, conversation-quality scores are not returned. | | `goalDimensions?` | [`GoalDimension`](#goaldimension-1)\[] | Optional goal dimensions for this interaction. Supplying at least one triggers interaction feedback. Ignored when `conversationContext` is set. | | `conversationContext?` | `string` | Optional free-text scenario description. When set, it is the sole source of context for feedback generation and `goalDimensions` is ignored. | | `signal?` | `AbortSignal` | Optional `AbortSignal` to cancel the request. | *** ### UploadClientOptions Options for constructing an [UploadClient](#uploadclient). #### Properties | Property | Type | Description | | ------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `tokenProvider` | [`TokenProvider`](#tokenprovider) | Supplies the bearer token attached to each request. | | `baseUrl?` | `string` | Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`. | | `environment?` | [`Environment`](#environment-2) | Named environment to target. Defaults to `"production"`. | | `fetch?` | \{ (`input`, `init?`): `Promise`\<`Response`>; (`input`, `init?`): `Promise`\<`Response`>; } | Custom `fetch` implementation. Defaults to the global `fetch`. | ## Type Aliases ### Environment ```ts theme={null} type Environment = "production" | "staging"; ``` A named Interhuman API environment. *** ### RealtimeClientOptions ```ts theme={null} type RealtimeClientOptions = SessionSocketClientOptions; ``` Options for constructing a [RealtimeClient](#realtimeclient). *** ### AnalysisGroup ```ts theme={null} type AnalysisGroup = "video" | "visual" | "audio"; ``` Top-level analysis surfaces a real-time session can run. Each group maps to one or more server-side analysis tracks: `video` is the Inter-1 social-signal analysis, `visual` the visual-signals track, and `audio` the audio tracks. *** ### RealtimeFeedbackFrequency ```ts theme={null} type RealtimeFeedbackFrequency = "high" | "medium" | "low"; ``` How often the feedback step runs, measured in analyzed video: `high` = every 10 seconds, `medium` = every 20 seconds, `low` = every 30 seconds. Only takes effect once `realtime_feedback_instructions` has enabled feedback. *** ### RealtimeEvent ```ts theme={null} type RealtimeEvent = | RealtimeSessionReadyEvent | RealtimeSessionUpdatedEvent | SessionClosingEvent | SessionEndedEvent | SignalDetectedEvent | SignalUpdatedEvent | SignalEndedEvent | TranscriptGeneratedEvent | RealtimeFeedbackGeneratedEvent | CoverageDroppedEvent | StreamErrorEvent; ``` Discriminated union of every real-time server→client envelope. *** ### VideoChunk ```ts theme={null} type VideoChunk = Uint8Array | ArrayBuffer | ArrayBufferView | Blob; ``` A chunk of WebM or fragmented-MP4 video to stream to the server. *** ### Listener ```ts theme={null} type Listener = (payload) => void; ``` An event handler registered via `on`/`once`. #### Type Parameters | Type Parameter | | -------------- | | `T` | #### Parameters | Parameter | Type | | --------- | ---- | | `payload` | `T` | #### Returns `void` *** ### StreamClientOptions ```ts theme={null} type StreamClientOptions = SessionSocketClientOptions; ``` Options for constructing a [StreamClient](#streamclient). *** ### StreamEvent ```ts theme={null} type StreamEvent = | SessionReadyEvent | SessionUpdatedEvent | SessionClosingEvent | SessionEndedEvent | SignalDetectedEvent | SignalUpdatedEvent | SignalEndedEvent | EngagementUpdatedEvent | ConversationQualityUpdatedEvent | FeedbackGeneratedEvent | CoverageDroppedEvent | StreamErrorEvent; ``` Discriminated union of every server→client envelope. *** ### WebSocketFactory ```ts theme={null} type WebSocketFactory = (url, protocols?) => WebSocketLike; ``` Constructs a [WebSocketLike](#websocketlike) from a URL and optional subprotocols. #### Parameters | Parameter | Type | | ------------ | ----------------------- | | `url` | `string` | | `protocols?` | `string` \| `string`\[] | #### Returns [`WebSocketLike`](#websocketlike) *** ### ScopeValue ```ts theme={null} type ScopeValue = | "interhumanai.upload" | "interhumanai.stream" | "interhumanai.realtime"; ``` OAuth-style scopes an API key can carry. *** ### SignalType ```ts theme={null} type SignalType = | "agreement" | "confidence" | "confusion" | "disagreement" | "disengagement" | "engagement" | "frustration" | "hesitation" | "interest" | "skepticism" | "stress" | "uncertainty"; ``` Social signal types the model can detect. *** ### Probability ```ts theme={null} type Probability = "high" | "medium" | "low"; ``` Confidence level attached to a detected signal. *** ### EngagementLevel ```ts theme={null} type EngagementLevel = "engaged" | "neutral" | "disengaged"; ``` Engagement state of the analyzed subject. *** ### GoalDimension ```ts theme={null} type GoalDimension = "clarity" | "authority" | "energy" | "rapport" | "learning"; ``` Conversation-quality dimensions a caller can flag as a session goal. *** ### IncludeFlag ```ts theme={null} type IncludeFlag = "conversation_quality_overall" | "conversation_quality_timeline"; ``` Optional response sections the caller may request. *** ### FeedbackType ```ts theme={null} type FeedbackType = "feedback" | "no_feedback"; ``` Discriminator for the structured interaction-feedback result. *** ### VideoInput ```ts theme={null} type VideoInput = | Blob | { data: Uint8Array | ArrayBuffer | Blob; filename?: string; contentType?: string; }; ``` The video to analyze. Either a `Blob`/`File` (browsers, or Node 18+ where `Blob` is global) or raw bytes plus a filename. #### Union Members `Blob` *** ##### Type Literal ```ts theme={null} { data: Uint8Array | ArrayBuffer | Blob; filename?: string; contentType?: string; } ``` ###### data ```ts theme={null} data: Uint8Array | ArrayBuffer | Blob; ``` Raw video bytes. ###### filename? ```ts theme={null} optional filename?: string; ``` Filename to report in the multipart part, e.g. `"clip.mp4"`. ###### contentType? ```ts theme={null} optional contentType?: string; ``` MIME type, e.g. `"video/mp4"`. ## Variables ### HTTP\_BASE\_URLS ```ts theme={null} const HTTP_BASE_URLS: Record; ``` HTTP base URLs per named environment. *** ### AnalysisGroup ```ts theme={null} AnalysisGroup: { Video: "video"; Visual: "visual"; Audio: "audio"; }; ``` Named analysis-group constants. #### Type Declaration ##### Video ```ts theme={null} readonly Video: "video" = "video"; ``` Inter-1 social-signal analysis. ##### Visual ```ts theme={null} readonly Visual: "visual" = "visual"; ``` The visual-signals track. ##### Audio ```ts theme={null} readonly Audio: "audio" = "audio"; ``` The audio tracks. *** ### RealtimeFeedbackFrequency ```ts theme={null} RealtimeFeedbackFrequency: { High: "high"; Medium: "medium"; Low: "low"; }; ``` Named feedback-frequency constants. #### Type Declaration ##### High ```ts theme={null} readonly High: "high" = "high"; ``` Feedback runs every 10 seconds of analyzed video. ##### Medium ```ts theme={null} readonly Medium: "medium" = "medium"; ``` Feedback runs every 20 seconds of analyzed video. ##### Low ```ts theme={null} readonly Low: "low" = "low"; ``` Feedback runs every 30 seconds of analyzed video. *** ### WS\_READY\_STATE ```ts theme={null} const WS_READY_STATE: { CONNECTING: 0; OPEN: 1; CLOSING: 2; CLOSED: 3; }; ``` `readyState` constants, mirrored from the WHATWG WebSocket spec. #### Type Declaration ##### CONNECTING ```ts theme={null} readonly CONNECTING: 0 = 0; ``` ##### OPEN ```ts theme={null} readonly OPEN: 1 = 1; ``` ##### CLOSING ```ts theme={null} readonly CLOSING: 2 = 2; ``` ##### CLOSED ```ts theme={null} readonly CLOSED: 3 = 3; ``` *** ### Scope ```ts theme={null} const Scope: { Upload: "interhumanai.upload"; Stream: "interhumanai.stream"; Realtime: "interhumanai.realtime"; }; ``` Named scope constants. #### Type Declaration ##### Upload ```ts theme={null} readonly Upload: "interhumanai.upload" = "interhumanai.upload"; ``` Grants access to `POST /v1/upload/analyze`. ##### Stream ```ts theme={null} readonly Stream: "interhumanai.stream" = "interhumanai.stream"; ``` Grants access to `WS /v1/stream/analyze`. ##### Realtime ```ts theme={null} readonly Realtime: "interhumanai.realtime" = "interhumanai.realtime"; ``` Grants access to `WS /v0/realtime/analyze`. *** ### GoalDimension ```ts theme={null} GoalDimension: { Clarity: "clarity"; Authority: "authority"; Energy: "energy"; Rapport: "rapport"; Learning: "learning"; }; ``` Named goal-dimension constants. #### Type Declaration ##### Clarity ```ts theme={null} readonly Clarity: "clarity" = "clarity"; ``` ##### Authority ```ts theme={null} readonly Authority: "authority" = "authority"; ``` ##### Energy ```ts theme={null} readonly Energy: "energy" = "energy"; ``` ##### Rapport ```ts theme={null} readonly Rapport: "rapport" = "rapport"; ``` ##### Learning ```ts theme={null} readonly Learning: "learning" = "learning"; ``` *** ### IncludeFlag ```ts theme={null} IncludeFlag: { ConversationQualityOverall: "conversation_quality_overall"; ConversationQualityTimeline: "conversation_quality_timeline"; }; ``` Named include-flag constants. #### Type Declaration ##### ConversationQualityOverall ```ts theme={null} readonly ConversationQualityOverall: "conversation_quality_overall" = "conversation_quality_overall"; ``` ##### ConversationQualityTimeline ```ts theme={null} readonly ConversationQualityTimeline: "conversation_quality_timeline" = "conversation_quality_timeline"; ``` ## Functions ### resolveHttpBaseUrl() ```ts theme={null} function resolveHttpBaseUrl(options): string; ``` Resolve the HTTP base URL for a client. `baseUrl` takes precedence (use it to point at a local server, e.g. `http://localhost:8080`); otherwise the named `environment` is used, defaulting to production. The returned URL never has a trailing slash. #### Parameters | Parameter | Type | | ---------------------- | --------------------------------------------------------------------------- | | `options` | \{ `baseUrl?`: `string`; `environment?`: [`Environment`](#environment-2); } | | `options.baseUrl?` | `string` | | `options.environment?` | [`Environment`](#environment-2) | #### Returns `string` *** ### httpToWsBaseUrl() ```ts theme={null} function httpToWsBaseUrl(httpBaseUrl): string; ``` Derive the WebSocket origin from an HTTP base URL: `https`→`wss`, `http`→`ws`. Any path on the base URL is preserved (so a proxy mount point survives), with the trailing slash trimmed. #### Parameters | Parameter | Type | | ------------- | -------- | | `httpBaseUrl` | `string` | #### Returns `string`