> ## 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

Mints and revokes capped **client tokens** for direct browser use.

For server-side use with API-key credentials, prefer the top-level
[InterhumanClient](#interhumanclient), which authenticates and renews its session for you.

#### Constructors

##### Constructor

```ts theme={null}
new AuthClient(options?): AuthClient;
```

###### Parameters

| Parameter | Type |
| - | - |
| `options` | [`AuthClientOptions`](#authclientoptions) |

###### Returns

[`AuthClient`](#authclient)

#### Methods

##### createClientToken()

```ts theme={null}
createClientToken(request): Promise<ClientTokenResponse>;
```

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 and stream endpoints directly. It
grants the requested scopes (default `interhumanai.stream`) and carries the
caps you set, which the API enforces across upload and stream (the video
budget spans both). 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<void>;
```

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<string>;
```

Return a currently-valid bearer token, minting/refreshing as needed.

###### Returns

`Promise`\<`string`>

###### Implementation of

[`TokenProvider`](#tokenprovider).[`getToken`](#gettoken)

***

### TokenManager

Authenticates with API-key credentials and renews the session shortly before
it expires, so callers can request a valid bearer credential cheaply on every
call. Concurrent requests during a renewal 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<string>;
```

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 your API key (or a client token)
and use [upload](#upload) and [stream](#stream) to call the API.

#### Example

```ts theme={null}
const client = new InterhumanClient({ accessToken: process.env.INTERHUMAN_API_KEY! });

// Upload a finished file to Inter-2 as a job, then wait for the result.
let job = await client.upload.submit({
  file: { data: bytes, filename: "meeting.mp4", contentType: "video/mp4" },
  model: UploadModel.Inter2,
});
job = await client.upload.waitForJob(job);

// Stream a live feed to Inter-2. Pass `apiVersion: "v2"`: the default is v1.
const stream = client.stream({ apiVersion: "v2" });
```

#### 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 and revoking client tokens. |
|  `upload` | `readonly` | [`UploadClient`](#uploadclient) | Upload analysis client: Inter-2 jobs (`POST /v2/upload/analyze`) and Inter-1 (`POST /v1/upload/analyze`). |

#### Methods

##### stream()

```ts theme={null}
stream(options?): 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()`.

By default the session opens `WS /v1/stream/analyze` (Inter-1). Pass
`{ apiVersion: "v2" }` to open `WS /v2/stream/analyze` and have the same
session analyzed by the Inter-2 model — the protocol, handlers and types
are identical.

###### Parameters

| Parameter | Type |
| - | - |
| `options` | [`StreamOptions`](#streamoptions) |

###### Returns

[`StreamClient`](#streamclient)

##### getToken()

```ts theme={null}
getToken(): Promise<string>;
```

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)
* [`UploadJobTimeoutError`](#uploadjobtimeouterror)

#### 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/client_tokens`, `/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, 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. |

***

### UploadJobTimeoutError

An upload job did not reach a terminal state within the wait the caller
allowed ([UploadClient.waitForJob](#waitforjob) with `timeoutMs`). The job itself
keeps running; `job` is the last envelope read, so the caller can keep
polling with its `job_id`.

#### Extends

* [`InterhumanError`](#interhumanerror)

#### Constructors

##### Constructor

```ts theme={null}
new UploadJobTimeoutError(message, job): UploadJobTimeoutError;
```

###### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `job` | `unknown` |

###### Returns

[`UploadJobTimeoutError`](#uploadjobtimeouterror)

###### Overrides

[`InterhumanError`](#interhumanerror).[`constructor`](#constructor-4)

#### Properties

| Property | Modifier | Type | Description |
| - | - | - | - |
|  `job` | `readonly` | `unknown` | The last job envelope read before the wait gave up. |

***

### 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)

***

### `abstract` SessionSocketClient

Base class implementing the shared live-session WebSocket protocol.

Authentication uses the `Sec-WebSocket-Protocol: access_token, <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) surface; outbound video is sent as binary frames and JSON
payloads such as the session config as text frames.

#### Extended by

* [`StreamClient`](#streamclient)

#### 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<TEventMap, TConfig>(options): SessionSocketClient<TEventMap, TConfig>;
```

###### 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` | How configuration error messages name this client. Usually the concrete class name; a client serving several endpoints may qualify it. |
|  `displayName` | `abstract` | `string` | Human-readable surface name used in error messages (e.g. `"Stream"`). |
|  `frameNoun?` | `readonly` | `string` | How frame-decoding messages name the surface mid-sentence (e.g. `"stream"` in "Received a malformed stream frame."). Defaults to the lowercased [displayName](#displayname); set it where that would mangle a proper noun. |
|  `scopeHint` | `abstract` | `string` | Appended to the connect-rejection message to hint at the likely scope issue. |
|  `handshakeQuery?` | `readonly` | `Readonly`\<`Record`\<`string`, `string`>> | Query parameters carried on the upgrade request, beside the SDK identity pair. Unset for a client whose endpoint takes none; the stream client sets it to name the model a `/v2` session opens on. |

#### Accessors

##### isOpen

###### Get Signature

```ts theme={null}
get isOpen(): boolean;
```

Whether the underlying socket is open.

###### Returns

`boolean`

#### Methods

##### on()

```ts theme={null}
on<K>(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<K>(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<K>(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<void>;
```

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<TEventMap["session.ready"]>;
```

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.

Rejects with an [InterhumanError](#interhumanerror) if the connection closes before
the session becomes ready — including when the server accepts the
handshake and then refuses the session, which it reports as an `error`
envelope followed by a close (for example `ih1003` when the endpoint's
backend is not configured). The message names the endpoint, the close
code and reason, and that `error` envelope when there was one. A call
made after such a close rejects immediately rather than waiting forever.

Because the promise rejects rather than hanging, every caller must handle
the rejection: a caller that races it against a timeout, or requests it
before [connect](#connect) and awaits `connect()` first, should attach a
`.catch()` so a refused session is not an unhandled rejection.

###### 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`

##### sendBinary()

```ts theme={null}
protected sendBinary(payload): void;
```

Send an arbitrary binary frame.

###### Parameters

| Parameter | Type |
| - | - |
| `payload` | \| `Blob` \| `ArrayBuffer` \| `Uint8Array`\<`ArrayBufferLike`> \| `ArrayBufferView`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> \| `ArrayBufferView`\<`ArrayBufferLike`> |

###### 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-1).

###### 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, <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.

The client serves both stream endpoints — `/v1/stream/analyze` (Inter-1, the
default) and `/v2/stream/analyze` (Inter-2) — selected by
[StreamClientOptions.apiVersion](#apiversion-1). The protocol is the same on both, and
each names the endpoint it actually opened in the errors it raises: a v2
session reports the Inter-2 stream, a v1 session the Stream.

On `/v2/stream/analyze` the session opens on the model named by
[StreamClientOptions.model](#model-1) (default `"inter-2"`); `interhumanai.stream`
covers every model. `session.ready` lists, under `supported_session_config_options.model`, the models the
deployment serves that the credential may select, and a later
`updateConfig({ model })` switching to one the credential lacks is answered
with a non-fatal `error` envelope (`ih2003`) while the session continues on
its current model.

#### Example

```ts theme={null}
const stream = client.stream();               // Inter-1, /v1/stream/analyze
const streamV2 = client.stream({ apiVersion: "v2" }); // Inter-2, /v2/stream/analyze
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` | [`StreamClientOptions`](#streamclientoptions) |

###### Returns

[`StreamClient`](#streamclient)

###### Overrides

[`SessionSocketClient`](#abstract-sessionsocketclient).[`constructor`](#constructor-8)

#### Properties

| Property | Modifier | Type | Description | Overrides |
| - | - | - | - | - |
|  `endpointPath` | `readonly` | `string` | Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`endpointPath`](#endpointpath) |
|  `clientName` | `readonly` | `string` | How configuration error messages name this client. Usually the concrete class name; a client serving several endpoints may qualify it. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`clientName`](#clientname) |
|  `displayName` | `readonly` | `string` | Human-readable surface name used in error messages (e.g. `"Stream"`). | [`SessionSocketClient`](#abstract-sessionsocketclient).[`displayName`](#displayname) |
|  `frameNoun` | `readonly` | `string` | How frame-decoding messages name the surface mid-sentence (e.g. `"stream"` in "Received a malformed stream frame."). Defaults to the lowercased [displayName](#displayname-1); set it where that would mangle a proper noun. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`frameNoun`](#framenoun) |
|  `scopeHint` | `readonly` | `string` | Appended to the connect-rejection message to hint at the likely scope issue. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`scopeHint`](#scopehint) |
|  `handshakeQuery?` | `readonly` | `Readonly`\<`Record`\<`string`, `string`>> | Query parameters carried on the upgrade request, beside the SDK identity pair. Unset for a client whose endpoint takes none; the stream client sets it to name the model a `/v2` session opens on. | [`SessionSocketClient`](#abstract-sessionsocketclient).[`handshakeQuery`](#handshakequery) |
|  `apiVersion` | `readonly` | [`StreamApiVersion`](#streamapiversion) | The stream endpoint this client opens. | - |
|  `model` | `readonly` | [`StreamModel`](#streammodel-1) \| `undefined` | The model a `"v2"` session opens on, as named at construction; `undefined` on `"v1"` and when the server default (`"inter-2"`) is left to apply. | - |

#### 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)

#### Methods

##### on()

```ts theme={null}
on<K>(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)

##### off()

```ts theme={null}
off<K>(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)

##### once()

```ts theme={null}
once<K>(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)

##### connect()

```ts theme={null}
connect(): Promise<void>;
```

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)

##### waitForSessionReady()

```ts theme={null}
waitForSessionReady(): Promise<SessionReadyEvent>;
```

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.

Rejects with an [InterhumanError](#interhumanerror) if the connection closes before
the session becomes ready — including when the server accepts the
handshake and then refuses the session, which it reports as an `error`
envelope followed by a close (for example `ih1003` when the endpoint's
backend is not configured). The message names the endpoint, the close
code and reason, and that `error` envelope when there was one. A call
made after such a close rejects immediately rather than waiting forever.

Because the promise rejects rather than hanging, every caller must handle
the rejection: a caller that races it against a timeout, or requests it
before [connect](#connect-1) and awaits `connect()` first, should attach a
`.catch()` so a refused session is not an unhandled rejection.

###### Returns

`Promise`\<[`SessionReadyEvent`](#sessionreadyevent)>

###### Inherited from

[`SessionSocketClient`](#abstract-sessionsocketclient).[`waitForSessionReady`](#waitforsessionready)

##### 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)

##### sendBinary()

```ts theme={null}
protected sendBinary(payload): void;
```

Send an arbitrary binary frame.

###### Parameters

| Parameter | Type |
| - | - |
| `payload` | \| `Blob` \| `ArrayBuffer` \| `Uint8Array`\<`ArrayBufferLike`> \| `ArrayBufferView`\<`ArrayBufferLike`> \| `Uint8Array`\<`ArrayBufferLike`> \| `ArrayBufferView`\<`ArrayBufferLike`> |

###### Returns

`void`

###### Inherited from

[`SessionSocketClient`](#abstract-sessionsocketclient).[`sendBinary`](#sendbinary)

##### 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)

##### 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-2).

###### Returns

`void`

###### Inherited from

[`SessionSocketClient`](#abstract-sessionsocketclient).[`requestClose`](#requestclose)

##### 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-1)

##### 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)

##### sendAudio()

```ts theme={null}
sendAudio(frame): void;
```

Send one frame of raw PCM audio as a binary frame.

Only meaningful on `apiVersion: "v2"` with `model: "inter-2-audio"`, after
the session config declared an `audio_format`; the server then reads
every binary frame as signed 16-bit mono PCM at the declared sample rate.
Frames can be any size and cut at any byte boundary. Without that
declaration a binary frame is container media, which [sendVideo](#sendvideo-1)
names.

###### Parameters

| Parameter | Type |
| - | - |
| `frame` | `AudioFrame` |

###### Returns

`void`

***

### UploadClient

Analyzes complete files.

[analyze](#analyze) is the v1 route: the file is analyzed inside the request and
the report comes back with the response. [submit](#submit), [getJob](#getjob) and
[waitForJob](#waitforjob) are the v2 job routes: a file is accepted as a job,
analyzed by an Inter-2 model after the response, and read back by id until
it is `completed` or `failed`.

Every request is sent 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<AnalysisResult>;
```

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).

##### submit()

```ts theme={null}
submit(input): Promise<UploadJob>;
```

Submit a file to `POST /v2/upload/analyze` as an asynchronous job.

The API validates the file and answers with the job envelope before the
analysis runs. With `waitSeconds` above zero the request is held open for
up to that long, and the envelope comes back terminal (`result` or
`error` set) when the job finished in time; otherwise it comes back
`queued` or `running`, and [waitForJob](#waitforjob) or [getJob](#getjob) reads it
later. Check `status` rather than assuming either.

Pass `include` to have the completed job's result carry whole-file views:
`result.conversation_quality` with the Conversation Quality Index in the
sections the CQI flags name, and `result.signals` with the merged signal
list for `signals`. Without a flag the result carries no such section.

###### Parameters

| Parameter | Type |
| - | - |
| `input` | [`SubmitUploadJobInput`](#submituploadjobinput) |

###### Returns

`Promise`\<[`UploadJob`](#uploadjob)>

###### Throws

on a rejected submit: `ih4020` for a model the
route does not serve yet, `ih5008` for a file with no audio stream,
`ih5001` for an `inter-2` file with no video stream, `ih4002` for a
container the model does not read, `ih4007` for media under 3 s,
`ih1003` when no backend serves the model on the deployment, and the
usual auth, size and quota errors.

##### getJob()

```ts theme={null}
getJob(job, options?): Promise<UploadJob>;
```

Read a job's current envelope from `GET /v2/upload/jobs/{job_id}`.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `job` | `string` \| [`UploadJob`](#uploadjob) | The job's id, or the envelope [submit](#submit) returned. |
| `options` | \{ `signal?`: `AbortSignal`; } | - |
| `options.signal?` | `AbortSignal` | - |

###### Returns

`Promise`\<[`UploadJob`](#uploadjob)>

###### Throws

`ih4021` (404) when the id is unknown to this
account or the job has expired, among the usual errors.

##### waitForJob()

```ts theme={null}
waitForJob(job, options?): Promise<UploadJob>;
```

Poll a job until it is `completed` or `failed`, and resolve with it.

A terminal envelope passed in resolves at once without a request. A failed
job resolves, not rejects: read its `error`.

###### Parameters

| Parameter | Type |
| - | - |
| `job` | `string` \| [`UploadJob`](#uploadjob) |
| `options` | [`WaitForJobOptions`](#waitforjoboptions) |

###### Returns

`Promise`\<[`UploadJob`](#uploadjob)>

###### Throws

when `timeoutMs` elapses first. The job
keeps running; the error carries the last envelope read.

## 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<string>;
```

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.

#### 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_<env>_<publicId>_<entropy>`). |

***

### 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 and stream endpoints directly. Every cap is
optional. The token grants only the requested [scopes](#scopes-1) (default
`interhumanai.stream`); the caps are enforced on streaming sessions 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_<env>_<publicId>_<entropy>`). | [`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 and stream. | - |
|  `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_<env>_<publicId>_<entropy>`). | [`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 authenticates with these and renews its session automatically. Provide either `credentials` or `accessToken`. |
|  `accessToken?` | `string` | A client token, or your API key, 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 live-session clients. Defaults to the global `WebSocket` (browsers, Node 22+). |
|  `refreshSkewSeconds?` | `number` | Seconds before stated expiry to refresh a minted token. Defaults to 30. |

***

### StreamOptions

Per-session options for [InterhumanClient.stream](#stream).

#### Properties

| Property | Type | Description |
| - | - | - |
|  `apiVersion?` | [`StreamApiVersion`](#streamapiversion) | Which stream endpoint to open: `"v1"` (Inter-1, the default) or `"v2"` (Inter-2). Both endpoints speak the same protocol and need the same `interhumanai.stream` scope; only the model behind the analysis differs. |
|  `model?` | [`StreamModel`](#streammodel-1) | The Inter-2 model a `"v2"` session opens on (default `"inter-2"`). See [StreamClientOptions.model](#model-1). |

***

### ApiErrorBody

The canonical error body returned by every HTTP error path.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `error_id` | `string` | Machine-readable error code. |
|  `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. |

***

### SessionSocketClientOptions

Options shared by every WebSocket session client.

#### Extended by

* [`StreamClientOptions`](#streamclientoptions)

#### 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). |

***

### StreamClientOptions

Options for constructing a [StreamClient](#streamclient).

#### Extends

* [`SessionSocketClientOptions`](#sessionsocketclientoptions)

#### Properties

| Property | Type | Description | Inherited from |
| - | - | - | - |
|  `tokenProvider` | [`TokenProvider`](#tokenprovider) | Supplies the bearer token used to authenticate the connection. | [`SessionSocketClientOptions`](#sessionsocketclientoptions).[`tokenProvider`](#tokenprovider-1) |
|  `baseUrl?` | `string` | Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`. | [`SessionSocketClientOptions`](#sessionsocketclientoptions).[`baseUrl`](#baseurl-2) |
|  `environment?` | [`Environment`](#environment-2) | Named environment to target. Defaults to `"production"`. | [`SessionSocketClientOptions`](#sessionsocketclientoptions).[`environment`](#environment-3) |
|  `webSocket?` | [`WebSocketFactory`](#websocketfactory) | Custom WebSocket factory. Defaults to the global `WebSocket` (browsers, Node 22+). Supply one backed by the `ws` package on older Node. | [`SessionSocketClientOptions`](#sessionsocketclientoptions).[`webSocket`](#websocket-1) |
|  `apiVersion?` | [`StreamApiVersion`](#streamapiversion) | Which stream endpoint to open. Defaults to `"v1"` (Inter-1). Pass `"v2"` to analyze the same session with the Inter-2 model at `/v2/stream/analyze`; everything else about the session is identical. | - |
|  `model?` | [`StreamModel`](#streammodel-1) | The Inter-2 model a `"v2"` session opens on, sent as the handshake's `model` query parameter. Defaults to `"inter-2"` when omitted. The credential must carry `interhumanai.stream`, which covers every model, or the server refuses the session with `ih2003`. On `"v1"` the option is rejected at construction, since that endpoint offers no model selection. | - |

***

### StreamEnvelopeBase

Fields shared by every server→client envelope.

#### Extended by

* [`ConversationQualityUpdatedEvent`](#conversationqualityupdatedevent)
* [`CoverageDegradedEvent`](#coveragedegradedevent)
* [`CoverageDroppedEvent`](#coveragedroppedevent)
* [`EngagementUpdatedEvent`](#engagementupdatedevent)
* [`FeedbackGeneratedEvent`](#feedbackgeneratedevent)
* [`SessionClosingEvent`](#sessionclosingevent)
* [`SessionEndedEvent`](#sessionendedevent)
* [`SessionReadyEvent`](#sessionreadyevent)
* [`SessionUpdatedEvent`](#sessionupdatedevent)
* [`SignalDetectedEvent`](#signaldetectedevent)
* [`SignalEndedEvent`](#signalendedevent)
* [`SignalUpdatedEvent`](#signalupdatedevent)
* [`StreamErrorEvent`](#streamerrorevent)

#### 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. |

***

### RawAudioFormat

Declares that a session's binary frames are raw audio rather than container
media: signed 16-bit little-endian PCM at `sample_rate`, mono, with no header,
cut at any byte boundary. Accepted on `"inter-2-audio"` sessions only.

#### Properties

| Property | Type |
| - | - |
|  `encoding` | `"pcm_s16le"` |
|  `sample_rate` | [`PcmSampleRate`](#pcmsamplerate) |
|  `channels` | `1` |

***

### 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. |
|  `model` | [`StreamModel`](#streammodel-1)\[] \| `null` | The models the deployment serves on `WS /v2/stream/analyze` that the credential may select; `null` on `WS /v1/stream/analyze`, which offers no model selection. |

***

### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"session.ready"` | - | - |
|  `data` | [`SessionReadyData`](#sessionreadydata) | - | - |

***

### SessionUpdatedData

`session.updated` payload — consolidated config after a config frame applied.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `include` | [`IncludeFlag`](#includeflag-1)\[] | - |
|  `goal_dimensions` | [`GoalDimension`](#goaldimension-1)\[] \| `null` | - |
|  `model` | [`StreamModel`](#streammodel-1) \| `null` | The model analyzing the session, on `WS /v2/stream/analyze`; `null` on v1. |

***

### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"session.ended"` | - | - |
|  `data` | [`SessionEndedData`](#sessionendeddata) | - | - |

***

### SignalDetectedData

#### Properties

| Property | Type | Description |
| - | - | - |
|  `signal_type` | [`SignalType`](#signaltype) | The detected signal. On a `WS /v2/stream/analyze` session opened with `model: "inter-2-audio"`, the types are a subset of the ones `"inter-2"` reports: those it can hear (agreement, confidence, frustration, hesitation, interest and uncertainty). |
|  `start` | `number` | Seconds, absolute session-cumulative time. |
|  `probability` | [`Probability`](#probability-2) \| `null` | - |
|  `rationale` | `string` \| `null` | - |
|  `modality?` | `string`\[] | Analysis modalities that detected this signal, naming the source of the evidence. Sent on `WS /v1/stream/analyze`, where it is `["video"]`. Absent on `WS /v2/stream/analyze`, where the session's model names the evidence instead. |

***

### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"signal.detected"` | - | - |
|  `data` | [`SignalDetectedData`](#signaldetecteddata) | - | - |

***

### SignalUpdatedData

#### Properties

| Property | Type | Description |
| - | - | - |
|  `signal_type` | [`SignalType`](#signaltype) | The signal whose details changed. On a `WS /v2/stream/analyze` session opened with `model: "inter-2-audio"`, the types are a subset of the ones `"inter-2"` reports: those it can hear (agreement, confidence, frustration, hesitation, interest and uncertainty). |
|  `start` | `number` | - |
|  `probability` | [`Probability`](#probability-2) \| `null` | - |
|  `rationale` | `string` \| `null` | - |
|  `modality?` | `string`\[] | Analyses whose evidence produced this signal. Sent on `WS /v1/stream/analyze`, where a change to this set is one of the things that emits `signal.updated`. Absent on `WS /v2/stream/analyze`. |

***

### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"signal.updated"` | - | - |
|  `data` | [`SignalUpdatedData`](#signalupdateddata) | - | - |

***

### SignalEndedData

#### Properties

| Property | Type | Description |
| - | - | - |
|  `signal_type` | [`SignalType`](#signaltype) | The signal that is no longer active. On a `WS /v2/stream/analyze` session opened with `model: "inter-2-audio"`, the types are a subset of the ones `"inter-2"` reports: those it can hear (agreement, confidence, frustration, hesitation, interest and uncertainty). |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"feedback.generated"` | - | - |
|  `data` | [`FeedbackGeneratedData`](#feedbackgenerateddata) | - | - |

***

### CoverageDroppedRange

A contiguous range of session time no analysis covered (not billed).

#### Properties

| Property | Type |
| - | - |
|  `start` | `number` |
|  `end` | `number` |

***

### CoverageDroppedData

Payload of [CoverageDroppedEvent](#coveragedroppedevent): the time ranges no analysis
covers. Emitted when the analysis pipeline sheds buffered video under
backpressure, and when the incoming stream itself skipped ahead — a client
stall whose media never arrived while its recorder clock kept running.
Either way the listed ranges were never analyzed and are not billed.

#### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"coverage.dropped"` | - | - |
|  `data` | [`CoverageDroppedData`](#coveragedroppeddata) | - | - |

***

### CoverageDegradedRange

One time range whose visual coverage was partial, in session seconds.

#### Properties

| Property | Type |
| - | - |
|  `start` | `number` |
|  `end` | `number` |

***

### CoverageDegradedData

Payload of [CoverageDegradedEvent](#coveragedegradedevent): the affected time ranges plus the
reason. Unlike `coverage.dropped`, these windows **were analyzed** (audio
plus whatever video decoded) and are billed normally — only the visual
coverage was partial.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `ranges` | [`CoverageDegradedRange`](#coveragedegradedrange)\[] | - |
|  `reason` | `"video_gap"` | Why the visual coverage was partial. Currently always `"video_gap"`: the windows' video packets covered materially less than the window span (e.g. a keyframe interval longer than the analysis window, as a static screen share produces). |

***

### CoverageDegradedEvent

Informational notice that one or more analysis windows were analyzed with
partial visual coverage. The session stays open and the windows are billed
normally; the ranges tell your application that visual signals over that
stretch drew on partial video.

#### Extends

* [`StreamEnvelopeBase`](#streamenvelopebase)

#### Properties

| Property | Type | Description | Inherited from |
| - | - | - | - |
|  `timestamp` | `string` | ISO 8601 timestamp identifying when the event occurred. | [`StreamEnvelopeBase`](#streamenvelopebase).[`timestamp`](#timestamp) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `type` | `"coverage.degraded"` | - | - |
|  `data` | [`CoverageDegradedData`](#coveragedegradeddata) | - | - |

***

### 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) |
|  `correlation_id` | `string` | Connection correlation id; quote it when contacting support. | [`StreamEnvelopeBase`](#streamenvelopebase).[`correlation_id`](#correlation_id-1) |
|  `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). |
|  `model?` | [`StreamModel`](#streammodel-1) | The model to analyze the session with, on `WS /v2/stream/analyze` only. Unlike `include`, this is session state: a frame that omits it keeps the model in force, and a different model is accepted only before the first media frame. Defaults to `"inter-2"`. |
|  `audio_format?` | [`RawAudioFormat`](#rawaudioformat) | Declares that the session's binary frames are raw PCM audio (see [RawAudioFormat](#rawaudioformat)), on `"inter-2-audio"` sessions only. Fixed once the first frame has been sent. Omit it to send WebM or fragmented-MP4 media. |

***

### 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) | - |
|  `coverage.degraded` | [`CoverageDegradedEvent`](#coveragedegradedevent) | - |
|  `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` | - |
|  `modality` | `string`\[] | Analysis modalities that detected this signal, naming the source of the evidence. When several tracks detect the same signal, every contributing modality is included. |

***

### 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. |

***

### UploadJobSignal

A social signal detected in one window of an upload job. It carries the
window's span as its `start` and `end`. Unlike the v1 [Signal](#signal), it has
no `modality`: the job's `model` names the evidence the model read.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `type` | [`SignalType`](#signaltype) | The detected signal. On an `"inter-2-audio"` job, the types are a subset of the ones `"inter-2"` reports: those it can hear (agreement, confidence, frustration, hesitation, interest and uncertainty). |
|  `start` | `number` | Start of the window, in seconds from the start of the file. |
|  `end` | `number` | End of the window, in seconds from the start of the file. |
|  `probability` | [`Probability`](#probability-2) \| `null` | - |
|  `rationale` | `string` \| `null` | - |

***

### UploadJobWindow

The analysis of one fixed-length window of an upload job's file. Each
signal carries the window's span as its `start` and `end`.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `index` | `number` | Zero-based position of the window in the file. |
|  `start_seconds` | `number` | Where the window starts, in seconds from the start of the file. |
|  `end_seconds` | `number` | Where the window ends, in seconds from the start of the file. |
|  `engagement_status` | [`EngagementLevel`](#engagementlevel) | - |
|  `signals` | [`UploadJobSignal`](#uploadjobsignal)\[] | - |

***

### UploadJobConversationQuality

The Conversation Quality Index of a completed upload job, scored once over
the whole file from every window's signals and engagement. Each section is
present only when [SubmitUploadJobInput.include](#include-4) named its flag:
`overall` for `conversation_quality_overall`, `timeline` for
`conversation_quality_timeline`. A requested section is present even when no
signal was detected; every dimension then reads the neutral 50.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `overall?` | [`ConversationQualityValues`](#conversationqualityvalues) \| `null` | Aggregated scores for the whole file. |
|  `timeline?` | \| [`ConversationQualityTimelineEntry`](#conversationqualitytimelineentry)\[] \| `null` | Scores per consecutive, non-overlapping period across the file. |

***

### UploadJobResult

The result of a completed upload job: one entry per analyzed window, plus
the whole-file views the submit asked for — the signal list and the
Conversation Quality Index.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `duration_seconds` | `number` | Length of the analyzed media, in seconds. |
|  `window_seconds` | `number` | Length of each analysis window, in seconds. |
|  `windows` | [`UploadJobWindow`](#uploadjobwindow)\[] | Per-window analyses, in file order. |
|  `signals?` | [`UploadJobSignal`](#uploadjobsignal)\[] \| `null` | Every window's signals as one list over the whole file, in chronological order, merged by the same rules as [UploadClient.analyze](#analyze) and with no `modality`: signals of the same type in adjacent windows become one span, which keeps the highest probability and that signal's rationale. Like the window signals, an entry omits `probability` or `rationale` when it has none. Present only when [SubmitUploadJobInput.include](#include-4) named `signals`, and then an empty array when nothing was detected. The `windows` are unchanged either way. |
|  `conversation_quality?` | [`UploadJobConversationQuality`](#uploadjobconversationquality) \| `null` | Present only when the submit passed at least one [SubmitUploadJobInput.include](#include-4) flag; carries the sections those flags named. |

***

### UploadJobError

Why an upload job failed, in the API's standard error-body shape.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `error_id` | `string` | Machine-readable error code. |
|  `correlation_id?` | `string` \| `null` | - |
|  `link?` | `string` \| `null` | - |
|  `message?` | `string` \| `null` | - |

***

### UploadJob

The job envelope returned by `POST /v2/upload/analyze` and
`GET /v2/upload/jobs/{job_id}`. `result` is set only when `status` is
`completed`; `error` only when it is `failed`.

#### Properties

| Property | Type | Description |
| - | - | - |
|  `job_id` | `string` | Identifier of the job; use it with [UploadClient.getJob](#getjob). |
|  `status` | [`UploadJobStatus`](#uploadjobstatus) | - |
|  `model` | [`UploadModel`](#uploadmodel-1) | - |
|  `created_at` | `string` | When the job was accepted, as an ISO 8601 UTC timestamp. |
|  `expires_at` | `string` | When the job stops being readable, as an ISO 8601 UTC timestamp. |
|  `status_url` | `string` | Path of the status resource, relative to the API base URL. |
|  `result?` | [`UploadJobResult`](#uploadjobresult) \| `null` | - |
|  `error?` | [`UploadJobError`](#uploadjoberror) \| `null` | - |

***

### SubmitUploadJobInput

Arguments for [UploadClient.submit](#submit).

#### Properties

| Property | Type | Description |
| - | - | - |
|  `file` | [`VideoInput`](#videoinput) | The file to analyze. For `inter-2`: an mp4, mov, avi, mkv, webm or mpeg-ts video carrying both a video and an audio track (`ih5001` without picture, `ih5008` without sound), with at least 3 seconds of media, at most 32 MB, and no longer than the deployment's maximum duration (30 minutes by default; a longer file rejects with `ih4004`). |
|  `filename?` | `string` | Filename used when `file` is a `Blob` without a name. Defaults to `"video"`. |
|  `model` | [`UploadModel`](#uploadmodel-1) | The Inter-2 model to analyze with. |
|  `waitSeconds?` | `number` | How long, in seconds, the API may hold the request open waiting for the job to finish. `0` (the default) answers with the queued envelope at once; when the job finishes within the wait, the envelope comes back terminal. The deployment bounds it; a larger value rejects with `ih4005`. |
|  `include?` | [`UploadJobIncludeFlag`](#uploadjobincludeflag-1)\[] | Whole-file sections the completed job's result should carry. `conversation_quality_overall` and/or `conversation_quality_timeline` (the same flags [UploadClient.analyze](#analyze) takes) add [UploadJobResult.conversation\_quality](#conversation_quality-1); `signals` adds [UploadJobResult.signals](#signals-3). Omit a flag for no such section. |
|  `signal?` | `AbortSignal` | Optional `AbortSignal` to cancel the request. |

***

### WaitForJobOptions

Options for [UploadClient.waitForJob](#waitforjob).

#### Properties

| Property | Type | Description |
| - | - | - |
|  `timeoutMs?` | `number` | Give up after this many milliseconds and reject with [UploadJobTimeoutError](#uploadjobtimeouterror). Omit to wait until the job is terminal. |
|  `pollIntervalMs?` | `number` | Milliseconds between status reads. Defaults to 2000. |
|  `signal?` | `AbortSignal` | Optional `AbortSignal` that stops polling and rejects each read. |

***

### 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.

***

### 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<T> = (payload) => void;
```

An event handler registered via `on`/`once`.

#### Type Parameters

| Type Parameter |
| - |
| `T` |

#### Parameters

| Parameter | Type |
| - | - |
| `payload` | `T` |

#### Returns

`void`

***

### StreamApiVersion

```ts theme={null}
type StreamApiVersion = "v1" | "v2";
```

Which stream endpoint a [StreamClient](#streamclient) opens.

* `"v1"` — `WS /v1/stream/analyze`, analyzed by the Inter-1 model.
* `"v2"` — `WS /v2/stream/analyze`, analyzed by the Inter-2 model.

The two endpoints share one protocol: the same authentication, the same
`session.ready` limits and session config, the same video framing, and the
same server→client envelopes in the same order. Only the model behind the
analysis differs, so the same client, handlers and types serve both.

***

### StreamModel

```ts theme={null}
type StreamModel = "inter-2" | "inter-2-audio";
```

Inter-2 models a `WS /v2/stream/analyze` session can select, on the
handshake or through its session config.

`"inter-2"` (the default) reads the video. `"inter-2-audio"` hears the audio
alone: it accepts the same WebM and fragmented MP4 clips, with or without a
video track, and raw PCM frames once the session config declares
`audio_format`, and reports a subset of the signals `"inter-2"` reports
(agreement, confidence, frustration, hesitation, interest, uncertainty).
`WS /v1/stream/analyze` offers no selection and rejects any value.

***

### PcmSampleRate

```ts theme={null}
type PcmSampleRate = 16000 | 24000;
```

Sample rates accepted for raw PCM frames.

***

### StreamEvent

```ts theme={null}
type StreamEvent = 
  | SessionReadyEvent
  | SessionUpdatedEvent
  | SessionClosingEvent
  | SessionEndedEvent
  | SignalDetectedEvent
  | SignalUpdatedEvent
  | SignalEndedEvent
  | EngagementUpdatedEvent
  | ConversationQualityUpdatedEvent
  | FeedbackGeneratedEvent
  | CoverageDroppedEvent
  | CoverageDegradedEvent
  | 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";
```

OAuth-style scopes an API key can carry.

A scope names one endpoint family across every API version: `Scope.Upload`
covers `POST /v1/upload/analyze` and `POST /v2/upload/analyze` with every
model it serves; `Scope.Stream` covers `WS /v1/stream/analyze` and
`WS /v2/stream/analyze` with every model it serves. No scope implies
another. The token response's `scope` is authoritative.

***

### SignalType

```ts theme={null}
type SignalType =
  | "agreement"
  | "confidence"
  | "confusion"
  | "disagreement"
  | "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"`.

***

### UploadModel

```ts theme={null}
type UploadModel = "inter-2" | "inter-2-audio";
```

Inter-2 models a `POST /v2/upload/analyze` job can name.

`inter-2` reads a video (picture and sound together): an mp4, mov, avi,
mkv, webm or mpeg-ts file carrying both a video and an audio track.
`inter-2-audio` reads the audio alone: a wav, flac, mp3, m4a or ogg file,
or a webm or mp4 carrying an audio track. It reports a subset of the
signals `inter-2` reports (agreement, confidence, frustration, hesitation,
interest, uncertainty).

***

### UploadJobIncludeFlag

```ts theme={null}
type UploadJobIncludeFlag = IncludeFlag | "signals";
```

Whole-file sections a `POST /v2/upload/analyze` job's result can carry,
requested with [SubmitUploadJobInput.include](#include-4): the two
[IncludeFlag](#includeflag) Conversation Quality Index sections, plus `signals` for
the whole-file signal list ([UploadJobResult.signals](#signals-3)). `signals` is a
v2 upload option only; [UploadClient.analyze](#analyze) and the stream do not
take it.

***

### UploadJobStatus

```ts theme={null}
type UploadJobStatus = "queued" | "running" | "completed" | "failed";
```

Lifecycle of a `POST /v2/upload/analyze` job. `queued` and `running` are
transient; `completed` and `failed` are terminal, and the job stays readable
until its `expires_at`.

## Variables

### HTTP\_BASE\_URLS

```ts theme={null}
const HTTP_BASE_URLS: Record<Environment, string>;
```

HTTP base URLs per named environment.

***

### SDK\_NAME

```ts theme={null}
const SDK_NAME: "typescript" = "typescript";
```

This SDK's canonical name in API telemetry.

***

### SDK\_VERSION

```ts theme={null}
const SDK_VERSION: string = packageJson.version;
```

This SDK's package version, read from `package.json` at build time so there
is no second version literal to keep in sync.

***

### SDK\_HEADER\_NAME

```ts theme={null}
const SDK_HEADER_NAME: "X-Interhuman-SDK" = "X-Interhuman-SDK";
```

HTTP header carrying the SDK identity.

***

### STREAM\_ENDPOINT\_PATHS

```ts theme={null}
const STREAM_ENDPOINT_PATHS: Readonly<Record<StreamApiVersion, string>>;
```

Endpoint path opened for each [StreamApiVersion](#streamapiversion).

***

### StreamModel

```ts theme={null}
StreamModel: {
  Inter2: "inter-2";
  Inter2Audio: "inter-2-audio";
};
```

Named stream-model constants.

#### Type Declaration

##### Inter2

```ts theme={null}
readonly Inter2: "inter-2" = "inter-2";
```

##### Inter2Audio

```ts theme={null}
readonly Inter2Audio: "inter-2-audio" = "inter-2-audio";
```

***

### 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";
};
```

Named scope constants.

#### Type Declaration

##### Upload

```ts theme={null}
readonly Upload: "interhumanai.upload" = "interhumanai.upload";
```

Grants `POST /v1/upload/analyze`, `POST /v2/upload/analyze` with every
model it serves, and reading the account's jobs.

##### Stream

```ts theme={null}
readonly Stream: "interhumanai.stream" = "interhumanai.stream";
```

Grants `WS /v1/stream/analyze` and `WS /v2/stream/analyze` with every model it serves.

***

### 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";
```

***

### UploadModel

```ts theme={null}
UploadModel: {
  Inter2: "inter-2";
  Inter2Audio: "inter-2-audio";
};
```

Named upload-model constants.

#### Type Declaration

##### Inter2

```ts theme={null}
readonly Inter2: "inter-2" = "inter-2";
```

##### Inter2Audio

```ts theme={null}
readonly Inter2Audio: "inter-2-audio" = "inter-2-audio";
```

***

### UploadJobIncludeFlag

```ts theme={null}
UploadJobIncludeFlag: {
  ConversationQualityOverall: "conversation_quality_overall";
  ConversationQualityTimeline: "conversation_quality_timeline";
  Signals: "signals";
};
```

Named upload-job 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";
```

##### Signals

```ts theme={null}
readonly Signals: "signals" = "signals";
```

***

### DEFAULT\_JOB\_POLL\_INTERVAL\_MS

```ts theme={null}
const DEFAULT_JOB_POLL_INTERVAL_MS: 2000 = 2000;
```

Default interval between status reads in [UploadClient.waitForJob](#waitforjob).

## 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`

***

### sdkHeaderValue()

```ts theme={null}
function sdkHeaderValue(): string;
```

The `X-Interhuman-SDK` value this SDK sends: `typescript/<version>`.

#### Returns

`string`

***

### isTerminal()

```ts theme={null}
function isTerminal(job): boolean;
```

Whether a job has finished, successfully or not.

#### Parameters

| Parameter | Type |
| - | - |
| `job` | [`UploadJob`](#uploadjob) |

#### Returns

`boolean`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.