JavaScript SDK Reference

<!-- Generated from OneSay canonical specs. Source SHA-256: b4b9c06106eeaacd9b3d12592b48d82b4247853bea70c203aa8fe5e76500d37f. DO NOT EDIT. -->
# JavaScript SDK Contract

Status: `owner-approved/canonical-pcm-protocol-runtime`; runtime implemented: `true`; publishable: `false`.

Local package candidate: `@onesay/sdk@0.0.0-e7-local`; license: `Apache-2.0`; bytes: `PASS-LOCAL-BYTE-IDENTICAL-INDEPENDENT-BUILDS`. This candidate remains private and does not reserve or publish a public namespace.

## Environments

| Environment | Control API | Realtime |
|---|---|---|
| production | `https://api.onesay.com/v1` | `wss://realtime.onesay.com/v1` |
| staging | `https://api.staging.onesay.com/v1` | `wss://realtime.staging.onesay.com/v1` |

## Room events

- `Connected` -> `room.connected`
- `Disconnected` -> `room.disconnected`
- `Reconnecting` -> `room.reconnecting`
- `Reconnected` -> `room.reconnected`
- `ParticipantJoined` -> `participant.joined`
- `ParticipantLeft` -> `participant.left`
- `SignalOpened` -> `signal.opened`
- `SignalEnded` -> `signal.ended`
- `Error` -> `error`

## Task events

- `Created` -> `task.created`
- `Started` -> `task.started`
- `TranscriptPartial` -> `artifact.delta`
- `TranscriptFinal` -> `artifact.finalized`
- `Completed` -> `task.completed`
- `Failed` -> `task.failed`
- `Cancelled` -> `task.cancelled`

Browser authentication is token-provider-only. Audio transport accepts caller-supplied 16000 Hz mono PCM16LE; acquisition belongs to the caller and silent drop is forbidden. Pure sample-buffer conversion is available. Browser protocol and synthetic cross-engine evidence require requalification after the public capture API removal. Staging and publication remain unexecuted or unauthorized.

## Task voice

- Entry points: `client.tasks.create`, `client.tasks.get`, `client.tasks.list`, `client.tasks.cancel`, `RealtimeClient`
- Transport: onesay.realtime.v1 WebSocket with canonical PCM frames, contiguous ACK, unacked-only replay and bounded resume
- Results: Task and Artifact readback

## Realtime RTC

- Entry points: `client.rtc.connect`, `client.rtc.get`, `client.rtc.revoke`, `client.rtc.endPublication`, `client.rtc.agents.create`, `client.rtc.agents.get`, `client.rtc.agents.stop`
- Transport: OneSay RTC session over the locked native SDK, loaded lazily on the first RTC operation
- Results: publications, subscriptions, packets, streams, RPC, data tracks and explicit Agent executions

## RTC session states

- `connected`
- `reconnecting`
- `closed`

The RTC session state is local client information, not server authorization or proof of effective revocation.

## Declared capabilities

| Capability | Support | Detail |
|---|---|---|
| Task voice (WSS, ACK, replay, resume) | supported | Supported (browser, Node) |
| RTC audio | supported | Publish, subscribe, mute, playback (browser) |
| Packets | supported | Send and receive |
| Streams | supported | Send and receive |
| RPC | supported | Call and handle |
| DataTrack | supported | Supported (`livekit-client` 2.22.3) |
| Agents | supported | Explicit Agent executions and read-only Agent state |
| State, device, error, release | supported | Session state, quality, microphone selection, OneSay errors, close |
| Selected-mode media encryption | conditional | Conditional: where the browser can run the packaged worker |

Not exposed: native room, track and participant objects; native token or connection material; native SDK types; an escape hatch to the native SDK. Unsupported entries fail explicitly; generated profile types confer no runtime support.

See the [capability and compatibility page](sdk-compatibility.md).