@craftedxp/voice-js 0.3.2 → 0.4.0

package/CONSUMING.md

@@ -102,7 +102,7 @@ Browsers require a user gesture to start `AudioContext`. The SDK calls `audioCon
 
 For consumers running on a strict CSP, allow:
 
-- `connect-src wss://your-voxline-server.com`
+- `connect-src wss://your-voissia-server.com`
 - `worker-src 'self' blob:` (the audio worklet is registered from a Blob URL)
 
 Browsers also need `https` for `getUserMedia` (or `localhost` during dev).

package/README.md

@@ -4,7 +4,7 @@ JS SDK for embedding a voice agent call in any JS environment — browser tabs,
 
 Companion to [`@craftedxp/voice-rn`](https://www.npmjs.com/package/@craftedxp/voice-rn) (React Native) and [`@craftedxp/sdk-node`](https://www.npmjs.com/package/@craftedxp/sdk-node) (server-side `sk_` SDK).
 
-> **Internal testing release.** API surface may evolve before a stable release. **0.3.1** adds Node-consumer ergonomics: `onInterrupt`/`onAgentTurnStart` callbacks on `startCall`, and the `NodeVoiceClientFactory` return type from the Node entry. **0.3.0** added [client tools](#client-tools) — handlers the agent's LLM can call on the consumer's machine. **0.2.0** was a breaking rename + redesign of the previous `@voxline/web@0.1.0` — the singleton-`VoiceClient`-with-`apiKey` pattern is gone in favour of a `configureVoiceClient({ fetchToken })` factory that mirrors `voice-rn` 0.3.x. See [Migrating from `@voxline/web`](#migrating-from-voxlineweb) below.
+> **Internal testing release.** API surface may evolve before a stable release. **0.3.2** is a bug fix release — `onStateChange` now fires correctly for state transitions driven by server frames; the callback was silently swallowed since 0.2.0 for `connected → listening`, `agent_turn_start → agent_speaking`, etc. Consumers using only `onTranscript` were unaffected; anyone building UI from `onStateChange` should upgrade. **0.3.1** added Node-consumer ergonomics (`onInterrupt`/`onAgentTurnStart` callbacks, `NodeVoiceClientFactory` return type) — those depend on the state-callback path so 0.3.2 is the minimum recommended. **0.3.0** added [client tools](#client-tools) — handlers the agent's LLM can call on the consumer's machine. **0.2.0** was a breaking rename + redesign of the previous `@voxline/web@0.1.0` — the singleton-`VoiceClient`-with-`apiKey` pattern is gone in favour of a `configureVoiceClient({ fetchToken })` factory that mirrors `voice-rn` 0.3.x. See [Migrating from `@voxline/web`](#migrating-from-voxlineweb) below.
 
 ## Install
 
@@ -22,11 +22,11 @@ The same three-party flow as `voice-rn`. Your backend mints `ct_` tokens with it
 
 ```
 ┌─────────────────┐        ┌──────────────────┐        ┌─────────────────┐
-│  Your web app   │        │ Your backend     │        │ Voxline server  │
+│  Your web app   │        │ Your backend     │        │ Voissia server  │
 │                 │        │                  │        │                 │
-│  fetchToken ────┼───────►│  call Voxline ──┼───────►│  mint ct_       │
-│        │        │        │  with sk_       │        │       │         │
-│        │◄───────┼────────┼──── ct_ ────────┼────────┼─── ct_          │
+│  fetchToken ────┼───────►│  call Voissia  ──┼───────►│  mint ct_       │
+│        │        │        │  with sk_        │        │       │         │
+│        │◄───────┼────────┼──── ct_  ────────┼────────┼─── ct_          │
 │  startCall(...) ┼────────┼──── WSS /v1/agents/.../call?token=ct_ ─────►│
 └─────────────────┘        └──────────────────┘        └─────────────────┘
 ```
@@ -133,7 +133,7 @@ The Node bundle has the same `configureVoiceClient` / `startCall` shape, plus an
 
 | Field             | Type                        | Notes                                                                                                                                           |
 | ----------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiBase`         | `string`                    | Full HTTPS URL of the Voxline server. WS scheme derived: `https`→`wss`. Trailing slash optional.                                                |
+| `apiBase`         | `string`                    | Full HTTPS URL of the Voissia server. WS scheme derived: `https`→`wss`. Trailing slash optional.                                                |
 | `fetchToken`      | `(args) => Promise<string>` | Called by the SDK whenever it needs a fresh `ct_`. Mirrors `@craftedxp/voice-rn`'s shape exactly — `{ agentId, userId?, context?, metadata? }`. |
 | `defaultMetadata` | `Record<string, string>?`   | Applied to every `startCall`. Per-call merges on top.                                                                                           |
 | `defaultContext`  | `Record<string, unknown>?`  | Applied to every `startCall`. Per-call merges on top.                                                                                           |
@@ -344,7 +344,8 @@ Renders a floating call button with a Shadow-DOM transcript panel. Pre-mint the
 
 ## Status
 
-- **0.3.1** (current) — adds `onInterrupt` / `onAgentTurnStart` callbacks on `StartCallOptions` and `NodeVoiceClientFactory` proper return type for the Node entry. Backwards-compatible.
+- **0.3.2** (current) — bug fix: `onStateChange` now fires for state transitions driven by server frames (`connected → listening`, `agent_turn_start → agent_speaking`, etc.). Latent regression since 0.2.0; `onTranscript`-only consumers were unaffected, but anyone deriving UI from `onStateChange` should upgrade. No API changes — drop-in.
+- 0.3.1 — adds `onInterrupt` / `onAgentTurnStart` callbacks on `StartCallOptions` and `NodeVoiceClientFactory` proper return type for the Node entry. Backwards-compatible. **Use 0.3.2 instead** — both new callbacks depend on the state-callback path that 0.3.2 fixes.
 - 0.3.0 — adds client-tools support. New `clientTools` option on `startCall` accepts a `ClientToolMap` (description, parameters, handler, optional usage/timeoutMs/example). Browser and Node bundles both supported. Backwards-compatible — existing consumers see no change.
 - 0.2.0 — first `@craftedxp/voice-js` release. Browser + Node dual bundle, `fetchToken` factory, voice-rn 0.3.x parity. Migration path from `@voxline/web@0.1.0` documented above.
 - 0.1.0 — `@voxline/web`. Singleton `VoiceClient` class, `apiKey` accepted. Retired in 0.2.0; never published to npm so no deprecation window.

package/dist/browser.d.mts

@@ -64,7 +64,8 @@ interface ProtocolCallbacks {
     onTranscript: (entries: TranscriptEntry[]) => void;
     onError: (err: CallError) => void;
     onInterrupt: () => void;
-    onAgentTurnStart: () => void;
+    onAgentTurnStart: (seq?: number) => void;
+    onAgentTurnEnd: (seq?: number) => void;
     onCallEnd: (reason: CallEndReason) => void;
     onConnected: () => void;
     onClientToolCall: (frame: ClientToolCallFrame) => void;
@@ -98,10 +99,25 @@ interface FetchTokenArgs {
      */
     metadata?: Record<string, string>;
 }
-type FetchToken = (args: FetchTokenArgs) => Promise<string>;
+/**
+ * What `fetchToken` may return. The rich object form lets the server
+ * choose the transport per call. Returning a bare string is backwards-
+ * compatible — the SDK treats it as `{ token, transport: 'ws' }`.
+ */
+interface FetchTokenResult {
+    /** Raw `ct_` to feed into the WS open / WebRTC offer. */
+    token: string;
+    /** Server-selected transport. Default `'ws'` if absent. */
+    transport?: 'ws' | 'webrtc';
+    /** Required when `transport === 'webrtc'` AND the server uses a
+     *  separate signaling gateway. When omitted on a webrtc result, the
+     *  SDK falls back to the API base's Phase-1 routes (local dev). */
+    webrtcGatewayBase?: string;
+}
+type FetchToken = (args: FetchTokenArgs) => Promise<string | FetchTokenResult>;
 interface VoiceClientConfig {
     /**
-     * Full HTTPS URL of the Voxline server. The WebSocket scheme is
+     * Full HTTPS URL of the Voissia server. The WebSocket scheme is
      * derived: `https` → `wss`, `http` → `ws`. No trailing slash needed.
      */
     apiBase: string;
@@ -318,4 +334,4 @@ type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>;
  */
 declare function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory;
 
-export { type Call, type CallEndEvent, type CallEndReason, type CallError, type CallErrorCode, type CallState, type CaptureController, type CaptureOptions, type ClientTool, type ClientToolMap, type FetchToken, type FetchTokenArgs, type OnAgentSpeakingChange, type OnChunk, type OnError, type OnVolume$1 as OnVolume, type PlaybackController, type PlaybackOptions, type ProtocolCallbacks, type ProtocolState, type RWSEvent, type RWSOptions, type ReconnectingWebSocket, type ServerMessage, type StartCallOptions, type TranscriptEntry, type VoiceClientConfig, type VoiceClientFactory, type VolumeEvent, type WebSocketFactory, type WebSocketLike, buildWsUrl, configureVoiceClient, createAudioCapture, createAudioPlayback, createProtocolState, createReconnectingWebSocket, handleServerMessage };
+export { type Call, type CallEndEvent, type CallEndReason, type CallError, type CallErrorCode, type CallState, type CaptureController, type CaptureOptions, type ClientTool, type ClientToolMap, type FetchToken, type FetchTokenArgs, type FetchTokenResult, type OnAgentSpeakingChange, type OnChunk, type OnError, type OnVolume$1 as OnVolume, type PlaybackController, type PlaybackOptions, type ProtocolCallbacks, type ProtocolState, type RWSEvent, type RWSOptions, type ReconnectingWebSocket, type ServerMessage, type StartCallOptions, type TranscriptEntry, type VoiceClientConfig, type VoiceClientFactory, type VolumeEvent, type WebSocketFactory, type WebSocketLike, buildWsUrl, configureVoiceClient, createAudioCapture, createAudioPlayback, createProtocolState, createReconnectingWebSocket, handleServerMessage };