@hubtalk-ai/web-sdk 0.2.0

package/README.md

@@ -0,0 +1,509 @@
+# @hubtalk-ai/web-sdk
+
+Browser SDK for running a WebRTC voice call with a HubTalk AI Conversation
+Flow agent from your own website. It is a thin wrapper over
+[`livekit-client`](https://github.com/livekit/client-sdk-js) and the
+platform's existing voice path (`POST /v1/calls/web`): the SDK has no
+transport of its own, holds no API key, and never calls the platform's HTTP
+API — see §9 “Web calls” of the partner integration guide
+(`docs/integration-guide.md` in the platform repository) for the
+backend → frontend → SDK sequence.
+
+## Installation
+
+With a bundler:
+
+```bash
+npm install @hubtalk-ai/web-sdk
+```
+
+```ts
+import { VoiceClient } from '@hubtalk-ai/web-sdk';
+```
+
+Without a build step, load the self-contained bundle (carries its own copy
+of `livekit-client`):
+
+```html
+<script src="voice-client.bundle.js"></script>
+<script>
+  const client = new VoiceClient();
+</script>
+```
+
+## Quickstart
+
+```ts
+import { VoiceClient } from '@hubtalk-ai/web-sdk';
+
+const client = new VoiceClient();
+
+startCallButton.addEventListener('click', async () => {
+  // session = whatever your backend returned from POST /v1/calls/web
+  const session = await fetch('/api/start-voice-call', { method: 'POST' }).then((r) => r.json());
+  await client.startCall(session);
+});
+
+client.on('connectionStateChanged', ({ state }) => console.log('connection:', state));
+client.on('agentSpeakingStarted', () => console.log('agent speaking'));
+client.on('callEnded', ({ reason }) => console.log('call ended:', reason));
+
+endCallButton.addEventListener('click', () => client.stopCall());
+```
+
+**`startCall` must run inside a user gesture handler** (a click, a tap) — the
+browser's autoplay policy requires it for the agent's audio to play without
+being blocked, and getting microphone permission works the same way.
+
+## API
+
+### `new VoiceClient(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `audioContainer` | `HTMLElement` | a hidden `<div>` the SDK creates | Where agent `<audio>` elements are appended. |
+| `logger` | `{ error, debug }` | `console` | Custom log sink; the SDK still masks tokens before calling it. |
+| `logLevel` | `'silent' \| 'error' \| 'debug'` | `'error'` | Verbose logging is opt-in. |
+| `connectTimeoutMs` | `number` | livekit-client default (15s) | Peer connection / WebSocket connect timeout. |
+
+### Methods
+
+| Method | Behavior |
+|---|---|
+| `startCall({ accessToken, url }, options?)` | Connects and publishes the microphone. Accepts either `{accessToken, url}` or the raw `POST /v1/calls/web` response body (`{access_token, url, …}`) — extra fields are ignored. Resolves once the microphone is published. A second call while a call is active rejects with `ALREADY_IN_CALL`. `options.audio: false` starts a chat-only call — see below. |
+| `stopCall()` | Ends the call. Idempotent — resolves without an `error` event if no call is active. Cancels an in-flight `startCall` if called during `connecting`. |
+| `getState()` | Connection axis: `idle \| connecting \| connected \| reconnecting \| disconnected \| error`. |
+| `getAgentState()` | Agent-activity axis: `unknown \| initializing \| listening \| thinking \| speaking`. Independent of the connection axis. |
+| `sendText(text)` | Sends a typed reply into the conversation (topic `lk.chat`). The agent interrupts its speech and answers it as it would answer speech. Rejects with `NOT_IN_CALL` outside a call; an empty or whitespace-only string is a silent no-op; anything longer than 1000 characters is truncated. Your own message is **not** inserted into the chat by the SDK — it comes back as a `transcript` event with `role: 'user'`. |
+| `getCallId()` | The call's room name (same value as `call_id` in `GET /v1/calls/{call_id}`), or `null` before connecting. |
+| `on(event, handler)` / `off(event, handler)` / `once(event, handler)` | Subscribe / unsubscribe / subscribe-once. |
+| `destroy()` | Stops the call, removes every subscription, releases all resources. The instance is not usable afterward. |
+
+### Events
+
+| Event | Payload |
+|---|---|
+| `callStarted` | `{ callId }` |
+| `callEnded` | `{ callId, reason }` — `reason`: `local` (`stopCall`), `remote` (the agent/flow ended it), `connection_lost`, `error` |
+| `connectionStateChanged` | `{ state, previous }` |
+| `agentStateChanged` | `{ state, previous }` |
+| `agentSpeakingStarted` / `agentSpeakingStopped` | `{}` |
+| `transcript` | `{ role, text, final, id }` — `role`: `user` \| `agent`; `text` is the reply so far; `final: false` while it is still growing; `id` is the segment id — deltas of one reply share it, so render one bubble per `id`. Agent text arrives as it is **spoken**, so an interrupted reply never shows its unspoken tail. |
+| `error` | `VoiceError` — see below |
+
+### Chat-only calls
+
+`startCall(session, { audio: false })` runs the same call without audio: no
+microphone is published, and the agent's audio is subscribed but never played,
+so the browser never asks for microphone permission and nothing is heard. Text
+keeps working in both directions — `sendText()` and the `transcript` event —
+which makes it the mode for a visitor who cannot or will not talk.
+
+```ts
+await client.startCall(session, { audio: false });
+```
+
+Two consequences of that mode, both worth knowing before you ship it:
+
+- Neither `MICROPHONE_PERMISSION_DENIED` nor `MICROPHONE_UNAVAILABLE` can
+  occur, and `WEBRTC_UNSUPPORTED` no longer requires `getUserMedia` — only a
+  secure context and `RTCPeerConnection`, which LiveKit needs for the data
+  channel either way.
+- The agent's audio is **subscribed and discarded**, not left unsubscribed.
+  That is not waste for its own sake: in `livekit-agents`, the agent's audio
+  output blocks on its track being subscribed
+  (`_ParticipantAudioOutput.capture_frame` awaits a future that only
+  `publication.wait_for_subscription()` resolves), and the agent's transcript
+  is routed through a synchronizer bound to that same output. With no
+  subscriber the first frame of speech blocks forever and the agent's text
+  never arrives at all — while the echo of the visitor's own typed replies
+  still does, because that goes out on a separate, unsynchronized path.
+- The agent therefore still synthesizes speech nobody hears, and LiveKit paces
+  the transcript to that playback. So the text arrives at speaking speed
+  rather than as fast as the model produces it, and the call costs the same in
+  TTS as a voice call. Removing both is a platform-side change — the agent
+  needs `RoomOutputOptions(audio_enabled=False)` — not an SDK one.
+
+### Error codes
+
+Every failure is a structured `VoiceError`: `{ code, message, state, cause? }`
+— `cause` is the original browser/`livekit-client` error, for your own logs.
+
+| Code | When | Resulting state |
+|---|---|---|
+| `INVALID_PARAMS` | `accessToken` or `url` missing/empty | `error` |
+| `WEBRTC_UNSUPPORTED` | No WebRTC support, or not a secure context (HTTPS) | `error` |
+| `MICROPHONE_PERMISSION_DENIED` | Microphone access denied (voice calls only) | `error` |
+| `MICROPHONE_UNAVAILABLE` | No usable microphone device (voice calls only) | `error` |
+| `TOKEN_EXPIRED` | Token's `exp` already passed (checked locally before connecting) | `error` |
+| `TOKEN_INVALID` | Server rejected the token | `error` |
+| `CONNECTION_FAILED` | Could not establish the connection | `error` |
+| `CONNECTION_LOST` | Reconnect attempts exhausted after a successful connection | `disconnected` |
+| `ALREADY_IN_CALL` | `startCall` called while a call is already active | unchanged |
+| `NOT_IN_CALL` | `sendText` called outside an active call | unchanged |
+| `SERVER_ERROR` | Any other signalling/service failure | `error` |
+
+## Browser matrix
+
+Bounded by [`livekit-client`](https://github.com/livekit/client-sdk-js)'s own
+WebRTC support matrix. **Not yet verified against a live deployment** —
+tracked as an open pre-check of the source requirement (`docs/patches/patch132-web-voice-sdk.md`
+§7.3); this table is filled in once that manual pass runs, before the first
+release.
+
+| Browser | Verified |
+|---|---|
+| Chrome (desktop) | — |
+| Firefox (desktop) | — |
+| Safari (desktop) | — |
+| Chrome (Android) | — |
+| Safari (iOS) | — |
+
+iOS Safari needs special attention: both microphone publish and
+`startAudio()` must run strictly inside the user gesture, no exceptions.
+
+## Share links
+
+You do not always need a backend of your own. The platform's cabinet can
+issue a temporary link to one published agent — an expiry, a cap on calls
+and one-click revocation — and the page behind that link mints the session
+itself. Whoever opens it talks to the agent with no account, no API key and
+no setup.
+
+That page is part of the platform, and it drives the call through this SDK
+without a single change to it: the response it mints has the same shape as
+`POST /v1/calls/web`, so `startCall(session)` takes it as it comes. Nothing
+in the SDK knows about links, and nothing here holds the link token — the
+same rule as for the API key.
+
+Use a share link when someone just needs to hear the agent. Use your own
+backend, as in `example/server.py`, when the call has to start from your
+site, under your own domain, with variables your system knows.
+
+## What this SDK does not do (phase 1)
+
+- No chat or call-button UI — you build the interface, the SDK reports state
+  and takes text. `example/index.html` shows the wiring, it is not a
+  shipped component. The reference widget of the example pages is not
+  shipped either: copy it, do not import it.
+- No link handling — a share link is opened by the platform's own page, and
+  `startCall` takes the session that page already minted. There is no
+  `startCall({ demoToken })` and the SDK never presents a secret.
+- No transcript history — the SDK holds no list of replies; whoever renders
+  them keeps them.
+- No dynamic variables of its own — they are set once, by your backend, in
+  the `POST /v1/calls/web` body that mints the session. By the time the SDK
+  has that session the variables are fixed, and there is no API to read or
+  change them. `example/server.py` shows the backend side.
+- No `cf.voice`: node names and cascade transitions stay internal. Post-call
+  data comes from `GET /v1/calls/{call_id}` or a
+  `call_ended`/`call_analyzed` webhook.
+- No rate limit on `sendText` — every message is an LLM turn and TTS
+  synthesis, so a page that sends in a loop spends the workspace's money.
+- No token refresh — a call cannot outlive the token's TTL
+  (`expires_in` in the `POST /v1/calls/web` response).
+- No video, DTMF, custom TURN/ICE, or client-side audio processing.
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm run format:check
+npm run build   # dist/index.js (ESM) + dist/voice-client.bundle.js (script tag) + dist/*.d.ts
+
+python3 example/server.py --selftest   # the demo backend's field/merge logic
+```
+
+`--selftest` is the check that guards the parts of `example/server.py` with
+branches in them: `@today` and keyless fields in `demo_fields`, the
+allowlist in `merge_variables`, and every shipped scenario file parsing into
+a renderable form. It starts no server and needs no `.env`.
+
+### Running the example pages
+
+`example/server.py` is the backend half of the example: it holds the API key,
+mints a room through `POST /v1/calls/web` and serves the pages. Standard
+library only, no dependencies. Every call parameter comes from `.env` — copy
+`.env.example` and fill it in:
+
+```
+CFLOW_API_URL=http://localhost:8100
+CFLOW_API_KEY=cfk_…
+CFLOW_AGENT_ID=my_agent_v1      # fallback when the page sends no agent_id
+# optional JSON objects, passed straight to POST /v1/calls/web
+# CFLOW_DYNAMIC_VARIABLES={"name": "Aigerim"}
+# CFLOW_METADATA={"source": "example"}
+# optional: which scenario to open with, and per-half overrides of it
+# CFLOW_DEMO_SCENARIO=missed-deposit
+# CFLOW_DEMO_FIELDS=[{"key":"rl_clientName","label":"Client name","default":"John"}]
+# CFLOW_DEMO_HERO={"headline":"Missed deposit follow-up"}
+```
+
+**One file per demo scenario.** `example/scenarios/<id>.json` declares the
+dynamic variables the pages let a visitor edit — the ones the agent may
+reference as `{{key}}` — plus the copy of the call page's left column. The id
+is the file name. Two ship filled in:
+
+| id | Shows |
+|---|---|
+| `missed-deposit` | a client whose scheduled deposit was returned; 14 variables |
+| `identity-verification` | verifying the client, then their enrolled creditor accounts; 21 variables |
+
+**Exactly one is active, and the server picks it** — the one whose file says
+`"default": true`, or `CFLOW_DEMO_SCENARIO`. That is not a missing feature:
+these variables are the variables of the agent in `CFLOW_AGENT_ID`, and one
+agent is configured at a time, so a page-level switch could only ever produce
+variables the running agent never references. The scenario travels with the
+agent, in `.env`. Relying on file order for the default would let a new file
+quietly replace what a live demo shows, hence the explicit marker.
+
+A new demo is a new file plus one `.env` line — no HTML.
+
+Per field: `key`, `label`, and optionally `default` (`"@today"` resolves to
+today's date on the server), `placeholder`, `type`, `readonly`, `half` (two
+fields share a row).
+
+The server serves the active scenario from `GET /api/config`, `/` and `/call`
+render it (`/free` declares its own), and `POST /api/session` accepts values
+**only** for that scenario's keys — a key belonging to another scenario is
+dropped like an invented one, and everything else in
+`CFLOW_DYNAMIC_VARIABLES` stays server-side. That
+filter is not demo scaffolding: a production backend owes the same guarantee,
+since the browser names values and never the contract.
+
+**Three pages, one widget.** `/` is the widget on a host page, `/call` the
+call as the whole page, `/free` the widget with nothing configured — the
+agent name and every dynamic variable are typed into the form, `+ Variable`
+adds a key/value row.
+
+The allowlist follows the agent, not the page: a request for the agent in
+`CFLOW_AGENT_ID`, on `.env`'s own key, is filtered against the active
+scenario's keys, and a request for any other agent — or on a key the page
+brought — has its keys sent through unfiltered. That is what makes `/free`
+work — it brings its own agent, whose contract the active scenario does not
+describe — and it is why naming a different agent on `/` or `/call` drops the
+filter too.
+
+**Which agent is called.** The page names it: `const AGENT_ID = '…'` in the
+widget options of `example/index.html` and `example/call-details.html`, sent
+as `agent_id` in `POST /api/session`. It is the agent's **name**, the same
+string `CFLOW_AGENT_ID` holds — not a uuid. Left empty — the shipped
+default — the form grows an Agent name input and the visitor names it per
+call. That input rides the same form as the variables but is never one of
+them: it carries the reserved key `__agent_id` (`HtDemo.AGENT_KEY`), which
+the wiring strips out before posting. The server falls back to
+`CFLOW_AGENT_ID` only when the request names no agent, and answers 503 when
+neither does.
+
+**Which organisation the call runs as.** The key decides, and `.env`'s
+`CFLOW_API_KEY` is again only the fallback: `/free` carries an **Organisation
+API key** field in the middle of the page — not in the widget, since the key
+is not a call parameter — and a key typed there is sent as `api_key` and used
+for that call instead. One deployment can therefore demo any organisation
+without an `.env` edit and a restart. No organisation id goes with it:
+`POST /v1/calls/web` authenticates on the bearer key alone. The field is a
+demo affordance and not a template — a production backend holds its key
+server-side and never lets the browser name one — and the server's own key
+still never travels to a page.
+
+```bash
+npm run build                 # the page loads ../dist/voice-client.bundle.js
+python3 example/server.py     # http://localhost:8000/, /call and /free
+```
+
+Real environment variables win over `.env`, so `CFLOW_AGENT_ID=other python3
+example/server.py` overrides one parameter for a single run.
+
+Every press of Call asks the server for a fresh room. That is what keeps the
+short-lived LiveKit `access_token` fresh: a page left open for longer than the
+token TTL still starts a working call. The browser never talks to `/v1`
+directly, so no `CFLOW_CORS_ORIGINS` entry is needed — and the API key never
+reaches the page. That is the shape a production integration has too, with
+your own backend in place of `server.py`; `startCall()` accepts the
+`POST /v1/calls/web` response as-is.
+
+The example server exposes only the three example pages, their stylesheet
+(`example/widget.css`), their shared wiring (`example/demo-call.js`), the
+bundle and the two `/api/*` endpoints (the scenario files are read on the
+server, never served); it never serves the project directory
+or `.env`. Every page offers both a voice call and a chat-only one:
+
+| Page | What it shows |
+|---|---|
+| `/` | a demo site with the call widget pinned in the corner — the call starts from the launcher, and “Call details” inside the panel holds the dynamic variables |
+| `/call` | the call as the whole page: a branded column plus the same form, switching to the conversation once the call starts |
+| `/free` | the corner widget with nothing configured — agent name and variables are typed in, `+ Variable` adds a row; the organisation's API key is a field in the page itself |
+
+All three are clean URLs — no `.html`, since these links get pasted to
+clients. The old paths (`/index.html`, `/call-details.html`,
+`/free-form.html`, anything under `/example/`) answer `301` to the short
+form, so a link already shared keeps working.
+
+On iOS Safari, note that the network round trip between the click and
+`startCall()` can consume the user gesture that audio playback requires. A
+widget that has to support iOS should fetch the session before the click and
+hand it straight to `startCall()`.
+
+### Embedding the widget
+
+The SDK is headless: it ships no markup, no CSS and no themes. Your page owns
+every pixel. `example/index.html` together with `example/widget.css` is a
+reference you copy into your project and edit — not a component the package
+delivers.
+
+**Markup.** The widget is a launcher plus a panel, both inside one root
+element that carries the tokens:
+
+```html
+<div class="ht-widget">
+  <button class="ht-launcher" id="launcher">…</button>
+  <section class="ht-panel" id="panel" hidden>
+    <header class="ht-head">
+      <span class="ht-title">Voice agent</span>
+      <span class="ht-pill" id="pill">Ready</span>
+      <span class="ht-timer" id="timer" hidden>0:00</span>
+      <button class="ht-icon" id="collapse">…</button>
+    </header>
+    <details class="ht-details" id="details" open>
+      <summary>Call details</summary>
+      <div class="ht-fields" id="fields"></div>
+    </details>
+    <div class="ht-log" id="log"></div>
+    <div class="ht-debug" id="state"></div>
+    <div class="ht-composer">
+      <input id="message" disabled />
+      <button class="ht-icon" id="send" disabled>…</button>
+    </div>
+    <div class="ht-actions">
+      <button class="ht-btn" id="call">Call</button>
+      <button class="ht-btn ht-btn-ghost" id="chat">Chat</button>
+      <button class="ht-btn ht-btn-danger" id="hangup" disabled>Hang up</button>
+    </div>
+  </section>
+</div>
+```
+
+The `<details>` block is where the dynamic variables are typed; the widget
+hides it for the duration of a call. `Chat` is the same call with
+`{ audio: false }` — see “Chat-only calls” above.
+
+**The wiring is shared, not duplicated.** `example/demo-call.js` holds the
+part that is identical on all three example pages — transcript bubbles, the
+timer, the composer, session creation, `startCall` — and each page passes its
+own nodes and its own layout hooks:
+
+```js
+HtDemo.mountCall({
+  client: new VoiceClient(),
+  agentId: AGENT_ID, // '' → the form asks the visitor for an Agent name
+  refs: { pill, timer, state, log, empty, message, send, call, chat, hangup, liveDot },
+  readVariables: () => HtDemo.readValues(fieldsEl),
+  onCallStarted: () => { /* your layout switch */ },
+  onCallEnded: (reason) => { /* and back */ },
+});
+```
+
+Every `refs` node is optional — a page passes what its markup has, and the
+wiring skips the rest. `mountCall` returns `{ startVoice, startChatOnly,
+stop, render }` for a page that wants to drive the call from something other
+than the `call` / `chat` / `hangup` buttons.
+
+The rest of `HtDemo` is the form half, which is why no page repeats it:
+
+| Helper | Does |
+|---|---|
+| `loadConfig()` | `GET /api/config` — the active scenario's `fields` and `hero` |
+| `renderFields(container, fields, agentId)` | the variable inputs, preceded by an Agent name input when `agentId` is empty |
+| `readValues(container)` | what the visitor typed, keyed by dynamic variable, read off the DOM |
+| `applyHero(root, hero)` | fills every `[data-hero="<key>"]` node, keeping the markup's own copy as the fallback |
+| `createSession(variables, agentId)` | `POST /api/session` |
+
+**Wiring.** Which SDK event drives which node:
+
+| Event | Node |
+|---|---|
+| `connectionStateChanged`, `agentStateChanged` | the state pill and the raw debug line |
+| `transcript` | one bubble per segment `id`; `final: false` renders as interim |
+| `callStarted` | clears the log, starts the timer, enables the composer and Hang up |
+| `callEnded` | stops the timer, disables the composer, appends why it ended |
+| `error` | stops the timer, hides the live dot, appends the code plus its English line to the log |
+
+Collapsing the panel is presentation only — never call `stopCall()` from it,
+or a visitor loses the conversation by tidying the widget away.
+
+**Restyling.** Override the tokens on `.ht-widget`; nothing else needs
+touching:
+
+| Token | What it paints |
+|---|---|
+| `--accent`, `--accent-contrast` | the launcher, the Call button, the visitor's bubbles |
+| `--bg-panel`, `--bg-elev` | the panel surface and the agent's bubbles |
+| `--text`, `--text-dim` | primary and secondary text |
+| `--border` | every hairline |
+| `--radius`, `--radius-sm` | corner softness |
+| `--hero-bg`, `--hero-text` | the branded column of the call page (deliberately the same in both schemes — a brand block does not invert) |
+
+```css
+.ht-widget {
+  --accent: #1f6feb;
+  --accent-contrast: #ffffff;
+  --radius: 8px;
+}
+```
+
+The file ships both palettes and follows `prefers-color-scheme`; override a
+token inside your own media query to diverge per scheme.
+
+**Boundaries.** The tokens are declared on the `.ht-demo` / `.ht-call` /
+`.ht-widget` roots rather than on `:root`, and every class carries the `ht-`
+prefix — loading the file cannot repaint your site. Copy the `.ht-widget`
+block plus the shared form primitives (`.ht-details`, `.ht-fields`,
+`.ht-field*`, `.ht-btn*`) and leave the `.ht-demo` / `.ht-call` page sections
+behind. The package does not serve the stylesheet: copy it into your own
+build.
+
+### Deploying the example
+
+The deployment script builds the SDK and runs the example server on the same
+machine. Put the required API configuration in `.env` at the project root.
+
+```bash
+scripts/deploy-example.sh
+```
+
+Set `PORT` to choose a port (default `8000`). For public access, put this
+server behind an HTTPS reverse proxy, since browsers require a secure context
+for microphone and WebRTC access.
+
+### Running with systemd
+
+The included unit runs the example after the network is available and restarts
+it after a failure. It ships configured for the demo box — user
+`cybernet-adm`, checkout at `/home/cybernet-adm/hubtalk-web-sdk` — so edit
+`User` and `WorkingDirectory` before installing it anywhere else. It passes
+no `EnvironmentFile`: the server reads `.env` from the checkout itself.
+
+```bash
+sudo cp example/hubtalk-webrtc-example.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now hubtalk-webrtc-example
+sudo systemctl status hubtalk-webrtc-example
+```
+
+**`dist/` is gitignored, so `git pull` never updates the bundle the browser
+loads.** A pull plus a restart keeps serving the SDK that was last built on
+that machine — the page works, it is just the previous code, which is a very
+quiet way to lose an afternoon. Always build:
+
+```bash
+npm run build
+sudo systemctl restart hubtalk-webrtc-example
+```
+
+Two guards make that hard to forget: the unit re-copied from
+`example/hubtalk-webrtc-example.service` rebuilds on every restart
+(`ExecStartPre`), and the server prints a loud warning at startup when
+`dist/voice-client.bundle.js` is older than `src/`. The pages and the bundle
+are served `Cache-Control: no-store`, so a plain reload is enough — no
+Ctrl+F5.

package/dist/audio.d.ts

@@ -0,0 +1,16 @@
+import type { RemoteTrack } from 'livekit-client';
+/**
+ * По одному <audio>-элементу на трек (§2.3 ТЗ №132): общий элемент
+ * перезаписывает srcObject — фоновый звук глушил голос агента
+ * (VoiceCallPanel.tsx:442-446). track.attach()/detach() уже создают/
+ * возвращают элемент на трек — здесь только контейнер и уборка.
+ */
+export declare class AudioElements {
+    readonly element: HTMLElement;
+    private readonly owned;
+    constructor(container?: HTMLElement);
+    attach(track: RemoteTrack): void;
+    detach(track: RemoteTrack): void;
+    clear(): void;
+    destroy(): void;
+}

package/dist/bundle-entry.d.ts

@@ -0,0 +1 @@
+export { VoiceClient as default } from './voice-client';

package/dist/emitter.d.ts

@@ -0,0 +1,10 @@
+import type { VoiceClientEventHandler, VoiceClientEventMap, VoiceClientEventName } from './types';
+/** Малый типизированный emitter — своей событийной модели без зависимостей. */
+export declare class Emitter {
+    private readonly listeners;
+    on<E extends VoiceClientEventName>(event: E, handler: VoiceClientEventHandler<E>): void;
+    off<E extends VoiceClientEventName>(event: E, handler: VoiceClientEventHandler<E>): void;
+    once<E extends VoiceClientEventName>(event: E, handler: VoiceClientEventHandler<E>): void;
+    emit<E extends VoiceClientEventName>(event: E, payload: VoiceClientEventMap[E]): void;
+    clear(): void;
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { ConnectionState, VoiceError, VoiceErrorCode } from './types';
+export declare class VoiceCallError extends Error implements VoiceError {
+    readonly code: VoiceErrorCode;
+    readonly state: ConnectionState;
+    readonly cause?: unknown;
+    constructor(code: VoiceErrorCode, state: ConnectionState, cause?: unknown);
+}
+/**
+ * Классификация ошибки room.connect() — по факту (livekit-client 2.20.0,
+ * ConnectionError/ConnectionErrorReason, см. §7 пред-проверку в ТЗ №132:
+ * NotAllowed приходит и на просроченный, и на отклонённый токен — TOKEN_EXPIRED
+ * уже отфильтрован локальным пред-чеком до connect, поэтому здесь это
+ * TOKEN_INVALID).
+ */
+export declare function connectErrorCode(error: unknown): VoiceErrorCode;
+/** MediaDeviceFailure.getFailure — классификатор ошибок getUserMedia из
+ * самого livekit-client (не переизобретаем разбор DOMException.name). */
+export declare function microphoneErrorCode(error: unknown): VoiceErrorCode;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { VoiceClient } from './voice-client';
+export { VoiceCallError } from './errors';
+export type { AgentState, AgentStateChangedEvent, CallEndedEvent, CallEndedReason, CallStartedEvent, ConnectionState, ConnectionStateChangedEvent, LogLevel, Logger, StartCallOptions, StartCallParams, TranscriptEvent, VoiceClientEventHandler, VoiceClientEventMap, VoiceClientEventName, VoiceClientOptions, VoiceError, VoiceErrorCode, } from './types';