@craftedxp/voice-js 0.4.2 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONSUMING.md +10 -2
- package/README.md +69 -11
- package/dist/browser.d.mts +242 -1
- package/dist/browser.d.ts +242 -1
- package/dist/browser.js +301 -2
- package/dist/browser.js.map +1 -1
- package/dist/browser.mjs +301 -1
- package/dist/browser.mjs.map +1 -1
- package/dist/embed.iife.js +43 -3
- package/dist/node.d.mts +240 -1
- package/dist/node.d.ts +240 -1
- package/dist/node.js +27 -2
- package/dist/node.js.map +1 -1
- package/dist/node.mjs +25 -1
- package/dist/node.mjs.map +1 -1
- package/package.json +5 -1
package/CONSUMING.md
CHANGED
|
@@ -79,14 +79,22 @@ export async function POST(req) {
|
|
|
79
79
|
|
|
80
80
|
// Mint with the user's identity. Server attaches contactId, applies the
|
|
81
81
|
// org's tier gate, etc.
|
|
82
|
-
const
|
|
82
|
+
const result = await platform.callTokens.mint({
|
|
83
83
|
agentId,
|
|
84
84
|
contactId: session.userId,
|
|
85
85
|
context,
|
|
86
86
|
metadata,
|
|
87
87
|
ttlSeconds: 600,
|
|
88
88
|
})
|
|
89
|
-
|
|
89
|
+
// Forward transport + webrtcGatewayBase so the browser SDK can
|
|
90
|
+
// dispatch WS vs WebRTC per the agent's configuration. New agents
|
|
91
|
+
// default to WebRTC since 2026-05-16; legacy agents keep their
|
|
92
|
+
// stored 'ws' setting.
|
|
93
|
+
return Response.json({
|
|
94
|
+
token: result.token,
|
|
95
|
+
transport: result.transport,
|
|
96
|
+
webrtcGatewayBase: result.webrtcGatewayBase,
|
|
97
|
+
})
|
|
90
98
|
}
|
|
91
99
|
```
|
|
92
100
|
|
package/README.md
CHANGED
|
@@ -41,13 +41,22 @@ import { configureVoiceClient } from '@craftedxp/voice-js'
|
|
|
41
41
|
const voice = configureVoiceClient({
|
|
42
42
|
apiBase: 'https://api.your-server.com',
|
|
43
43
|
// SDK calls this whenever it needs a fresh ct_ — initial connect
|
|
44
|
-
// and any mid-call token refresh. Your backend handles the mint
|
|
44
|
+
// and any mid-call token refresh. Your backend handles the mint and
|
|
45
|
+
// forwards the mint response's `transport` + `webrtcGatewayBase` so
|
|
46
|
+
// the SDK can dispatch WS vs WebRTC per the agent's configuration.
|
|
47
|
+
// (New agents default to WebRTC since 2026-05-16. The bare-string
|
|
48
|
+
// form below is still accepted for back-compat — it always uses WS.)
|
|
45
49
|
fetchToken: async ({ agentId }) => {
|
|
46
50
|
const r = await fetch('/api/voice/mint', {
|
|
47
51
|
method: 'POST',
|
|
48
52
|
body: JSON.stringify({ agentId }),
|
|
49
53
|
})
|
|
50
|
-
|
|
54
|
+
const body = await r.json()
|
|
55
|
+
return {
|
|
56
|
+
token: body.token,
|
|
57
|
+
transport: body.transport, // 'ws' | 'webrtc'
|
|
58
|
+
webrtcGatewayBase: body.webrtcGatewayBase, // present when transport=webrtc
|
|
59
|
+
}
|
|
51
60
|
},
|
|
52
61
|
// Optional — applied to every call. Per-call options merge on top.
|
|
53
62
|
defaultMetadata: { surface: 'web', appVersion: '1.4.0' },
|
|
@@ -131,12 +140,12 @@ The Node bundle has the same `configureVoiceClient` / `startCall` shape, plus an
|
|
|
131
140
|
|
|
132
141
|
### `configureVoiceClient(config)`
|
|
133
142
|
|
|
134
|
-
| Field | Type
|
|
135
|
-
| ----------------- |
|
|
136
|
-
| `apiBase` | `string`
|
|
137
|
-
| `fetchToken` | `(args) => Promise<string>` | Called by the SDK whenever it needs a fresh `ct_`.
|
|
138
|
-
| `defaultMetadata` | `Record<string, string>?`
|
|
139
|
-
| `defaultContext` | `Record<string, unknown>?`
|
|
143
|
+
| Field | Type | Notes |
|
|
144
|
+
| ----------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| `apiBase` | `string` | Full HTTPS URL of the Voissia server. WS scheme derived: `https`→`wss`. Trailing slash optional. |
|
|
146
|
+
| `fetchToken` | `(args) => Promise<string \| FetchTokenResult>` | Called by the SDK whenever it needs a fresh `ct_`. Args: `{ agentId, userId?, context?, metadata? }`. Return either a bare `ct_` string (always WS, back-compat) or the rich `{ token, transport, webrtcGatewayBase? }` object so the SDK can dispatch WS vs WebRTC per the agent's configuration. |
|
|
147
|
+
| `defaultMetadata` | `Record<string, string>?` | Applied to every `startCall`. Per-call merges on top. |
|
|
148
|
+
| `defaultContext` | `Record<string, unknown>?` | Applied to every `startCall`. Per-call merges on top. |
|
|
140
149
|
|
|
141
150
|
Returns a `VoiceClientFactory` with one method:
|
|
142
151
|
|
|
@@ -211,6 +220,50 @@ type CallErrorCode =
|
|
|
211
220
|
type CallEndReason = 'agent_ended' | 'user_hangup' | 'timeout' | 'error'
|
|
212
221
|
```
|
|
213
222
|
|
|
223
|
+
## Animating while the agent is talking
|
|
224
|
+
|
|
225
|
+
Four optional callbacks on `startCall` give you everything you need to drive an "agent is talking" animation:
|
|
226
|
+
|
|
227
|
+
| Callback | What |
|
|
228
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
229
|
+
| `onStateChange(state)` | `state === 'agent_speaking'` is true while the agent is in its speaking turn. |
|
|
230
|
+
| `onAgentTurnStart()` | Fires the moment the agent starts a turn — a discrete trigger if you want an "activation" cue. |
|
|
231
|
+
| `onInterrupt()` | The user barged in. End the animation early. |
|
|
232
|
+
| `onVolume({ input, output })` | Real-time amplitude. `output` is the agent's playback level (≈ what the listener hears); `input` is your mic. |
|
|
233
|
+
|
|
234
|
+
`onStateChange === 'agent_speaking'` is **protocol-driven**: it flips on as soon as the server begins the turn, _before_ the first audio sample reaches the speaker. For a visual that follows what the listener actually hears, drive it from `onVolume.output`.
|
|
235
|
+
|
|
236
|
+
The usual recipe is a stable gate × live amplitude:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
let isAgentTurn = false
|
|
240
|
+
let amplitude = 0
|
|
241
|
+
|
|
242
|
+
const call = await client.startCall({
|
|
243
|
+
agentId,
|
|
244
|
+
onStateChange: (s) => {
|
|
245
|
+
isAgentTurn = s === 'agent_speaking'
|
|
246
|
+
render()
|
|
247
|
+
},
|
|
248
|
+
onInterrupt: () => {
|
|
249
|
+
isAgentTurn = false
|
|
250
|
+
render()
|
|
251
|
+
},
|
|
252
|
+
onVolume: ({ output }) => {
|
|
253
|
+
amplitude = output
|
|
254
|
+
render()
|
|
255
|
+
},
|
|
256
|
+
})
|
|
257
|
+
|
|
258
|
+
function render() {
|
|
259
|
+
if (isAgentTurn)
|
|
260
|
+
showPulse({ scale: 1 + amplitude }) // your renderer
|
|
261
|
+
else hidePulse()
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
> 1:1 calls only — in multi-party rooms (`joinRoom`) the in-room agent is a silent notetaker and has no speaking turn, so none of these signals fire for it.
|
|
266
|
+
|
|
214
267
|
## Client tools
|
|
215
268
|
|
|
216
269
|
You can declare tools the agent's LLM can call **on the consumer's machine**. The
|
|
@@ -251,7 +304,7 @@ sent back; throws become `{ error: ... }` frames. The server enforces a default
|
|
|
251
304
|
10s / max 30s timeout per `timeoutMs` in your declaration.
|
|
252
305
|
|
|
253
306
|
For the full wire protocol, sequencing, and constraints see
|
|
254
|
-
[`docs/
|
|
307
|
+
[`docs/sdks.md` → Client tools](../../docs/sdks.md#client-tools).
|
|
255
308
|
|
|
256
309
|
## Migrating from `@voxline/web`
|
|
257
310
|
|
|
@@ -324,7 +377,7 @@ false-positive VAD on background noise). Three quick fixes, in order:
|
|
|
324
377
|
|
|
325
378
|
For the full diagnostic walkthrough (including the rarer Gemini-Live
|
|
326
379
|
stale-audio-leak case and audio-handling guidance for Node/Electron consumers),
|
|
327
|
-
see [`docs/
|
|
380
|
+
see [`docs/sdks.md` → Audio quality troubleshooting](../../docs/sdks.md#audio-quality-troubleshooting).
|
|
328
381
|
|
|
329
382
|
## Embed widget
|
|
330
383
|
|
|
@@ -344,7 +397,12 @@ Renders a floating call button with a Shadow-DOM transcript panel. Pre-mint the
|
|
|
344
397
|
|
|
345
398
|
## Status
|
|
346
399
|
|
|
347
|
-
- **0.4
|
|
400
|
+
- **0.5.4** (current) — Screen sharing. `setScreenShareEnabled(on, { audio })` publishes a `screen_share` video track (and, where the browser allows, a `screen_share_audio` track — Chrome captures tab/system audio; macOS Chrome is tab-audio only; Safari/Firefox don't capture share audio). `RoomTrackEvent` gains a `source` field (`camera` / `microphone` / `screen_share` / `screen_share_audio` / `unknown`) so a screen share can render as its own tile instead of replacing the participant's camera. Adds `isScreenShareEnabled()` and `getLocalScreenTrack()`. No 1:1 call-surface change. Drop-in for 0.5.3 consumers (the new `source` field is additive).
|
|
401
|
+
- 0.5.3 — `session.participantId` (this session's own stable `p_…` id). `active.speakers` includes the local participant, so a focus-tile UI rendered you as a remote when you spoke (no remote track → blank tile with the raw id). Filter `participantId` out of `active.speakers` to focus only remote speakers (self-view when none). No 1:1 call-surface change. Drop-in upgrade for 0.5.2 consumers.
|
|
402
|
+
- 0.5.2 — `getRemoteTracks(): RoomTrackEvent[]`. Returns remote tracks already subscribed at call time. A late joiner misses the live `track.subscribed` events for tracks published before it connected (LiveKit delivers them during `connect`, before consumer listeners attach), so it never rendered participants who already had their camera on (e.g. the host). Call `getRemoteTracks()` right after registering `track.subscribed` to backfill them. No 1:1 call-surface change. Drop-in upgrade for 0.5.1 consumers.
|
|
403
|
+
- 0.5.1 — Room video surface. `RoomSession` gains: `track.subscribed` / `track.unsubscribed` events with payload `{ participantId: string; kind: 'audio' | 'video'; track: RemoteTrack }` (raw livekit-client track — call `track.attach(el)` / `track.detach()`); `active.speakers` event (`string[]` of participantIds currently speaking, drives active-speaker UI); `setMicEnabled(on: boolean): Promise<void>` / `setCameraEnabled(on: boolean): Promise<void>` (mid-call toggles); `isMicEnabled(): boolean` / `isCameraEnabled(): boolean` (read current state for toggle button UI); `getLocalCameraTrack(): LocalVideoTrack | null` (attach to self-view element). No API changes to the 1:1 call surface (`startCall` / `Call`). Drop-in upgrade for 0.5.0 consumers.
|
|
404
|
+
- 0.5.0 — Multi-party rooms. `joinRoom({ roomId, joinCode, name })` returns a typed `RoomSession` with `participant.{joined,left}`, `transcript.partial`, `system.message`, `room.ended` events. Adds `livekit-client` as a direct dependency (~250 KB gzipped, tree-shakes if unused). `publishMic()` / `publishCamera()` / `leave()` methods. See [`docs/sdks.md` → Multi-party rooms](../../docs/sdks.md#multi-party-rooms).
|
|
405
|
+
- 0.4.2 — WebRTC reliability: `onicecandidate` + `onconnectionstatechange` listeners now register before `setLocalDescription` (where ICE gathering starts). Candidates emitted before `callId` is known are buffered and flushed once the answer arrives. Browsers buffer candidates internally so the prior listen-after-`setRemoteDescription` pattern worked in Chrome/Safari, but the explicit ordering is correct per spec and matches the fix shipped in `@craftedxp/voice-rn@0.4.1`. No API surface change — drop-in upgrade.
|
|
348
406
|
- 0.4.1 — `client_tools` over the WebRTC DataChannel — tool register on `connected`, dispatch on `client_tool_call` frames, parity with the WS transport.
|
|
349
407
|
- 0.4.0 — WebRTC transport support. `fetchToken` may now return `{ token, transport, webrtcGatewayBase? }`; the SDK dispatches WS vs WebRTC accordingly. Backwards-compatible — bare-string returns still always use WS.
|
|
350
408
|
- 0.3.2 — 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.
|
package/dist/browser.d.mts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { RemoteTrack, LocalVideoTrack } from 'livekit-client';
|
|
2
|
+
|
|
1
3
|
interface ClientTool {
|
|
2
4
|
description: string;
|
|
3
5
|
parameters: Record<string, unknown>;
|
|
@@ -79,6 +81,201 @@ interface BuildWsUrlArgs {
|
|
|
79
81
|
}
|
|
80
82
|
declare function buildWsUrl(args: BuildWsUrlArgs): string;
|
|
81
83
|
|
|
84
|
+
type SystemMessage = {
|
|
85
|
+
kind: 'room.starting';
|
|
86
|
+
at: string;
|
|
87
|
+
} | {
|
|
88
|
+
kind: 'room.ending.soon';
|
|
89
|
+
minutesRemaining: 5 | 1;
|
|
90
|
+
} | {
|
|
91
|
+
kind: 'room.ended';
|
|
92
|
+
reason: 'duration_reached' | 'manual' | 'empty';
|
|
93
|
+
} | {
|
|
94
|
+
kind: 'role.promoted';
|
|
95
|
+
participantId: string;
|
|
96
|
+
name: string;
|
|
97
|
+
} | {
|
|
98
|
+
kind: 'role.demoted';
|
|
99
|
+
participantId: string;
|
|
100
|
+
name: string;
|
|
101
|
+
} | {
|
|
102
|
+
kind: 'participant.removed';
|
|
103
|
+
participantId: string;
|
|
104
|
+
name: string;
|
|
105
|
+
byHost?: string;
|
|
106
|
+
} | {
|
|
107
|
+
kind: 'notetaker.connected';
|
|
108
|
+
} | {
|
|
109
|
+
kind: 'notetaker.disconnected';
|
|
110
|
+
} | {
|
|
111
|
+
kind: 'notetaker.partial_degraded';
|
|
112
|
+
participantId: string;
|
|
113
|
+
};
|
|
114
|
+
type TranscriptMessage = {
|
|
115
|
+
kind: 'partial';
|
|
116
|
+
participantId: string;
|
|
117
|
+
speakerName: string;
|
|
118
|
+
text: string;
|
|
119
|
+
startedAt: string;
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
interface JoinRoomOptions {
|
|
123
|
+
/** Full HTTPS URL of the Voissia server. Same shape as VoiceClientConfig.apiBase. */
|
|
124
|
+
apiBase: string;
|
|
125
|
+
/** Server-generated room id (`rm_…`). */
|
|
126
|
+
roomId: string;
|
|
127
|
+
/** Shared room join token from the invite link. Mints a fresh participant each call. */
|
|
128
|
+
joinCode: string;
|
|
129
|
+
/** Display name the joiner registers under for this participant. */
|
|
130
|
+
name: string;
|
|
131
|
+
}
|
|
132
|
+
interface RoomParticipantInfo {
|
|
133
|
+
/** Stable participant id (`p_…`); strips any `guest:` LiveKit identity prefix. */
|
|
134
|
+
participantId: string;
|
|
135
|
+
/** Display name as the worker registered it; may be empty. */
|
|
136
|
+
name: string;
|
|
137
|
+
}
|
|
138
|
+
type RoomTrackKind = 'audio' | 'video';
|
|
139
|
+
/** What a track is — lets consumers tell a camera apart from a screen share
|
|
140
|
+
* (a participant can publish both at once). Mirrors livekit `Track.Source`. */
|
|
141
|
+
type RoomTrackSource = 'camera' | 'microphone' | 'screen_share' | 'screen_share_audio' | 'unknown';
|
|
142
|
+
interface RoomTrackEvent {
|
|
143
|
+
/** Stable participant id (`p_…`); `guest:` prefix stripped. */
|
|
144
|
+
participantId: string;
|
|
145
|
+
kind: RoomTrackKind;
|
|
146
|
+
/** Distinguishes camera vs screen_share so each can render as its own tile. */
|
|
147
|
+
source: RoomTrackSource;
|
|
148
|
+
/** livekit-client track — call `.attach(el)` / `.detach()` to render. */
|
|
149
|
+
track: RemoteTrack;
|
|
150
|
+
}
|
|
151
|
+
type RoomEventName = 'participant.joined' | 'participant.left' | 'transcript.partial' | 'transcript.final' | 'system.message' | 'room.ended' | 'track.subscribed' | 'track.unsubscribed' | 'active.speakers';
|
|
152
|
+
interface RoomEventPayloads {
|
|
153
|
+
'participant.joined': RoomParticipantInfo;
|
|
154
|
+
'participant.left': RoomParticipantInfo;
|
|
155
|
+
'transcript.partial': TranscriptMessage;
|
|
156
|
+
/**
|
|
157
|
+
* Reserved — the worker currently emits only partials over the transcript
|
|
158
|
+
* topic. Final-utterance events will land in Phase 8 once the worker
|
|
159
|
+
* publishes a `final` kind; the SDK keeps the slot reserved so consumers
|
|
160
|
+
* can register handlers today.
|
|
161
|
+
*/
|
|
162
|
+
'transcript.final': {
|
|
163
|
+
participantId: string;
|
|
164
|
+
speakerName: string;
|
|
165
|
+
text: string;
|
|
166
|
+
startedAt: string;
|
|
167
|
+
};
|
|
168
|
+
'system.message': SystemMessage;
|
|
169
|
+
'room.ended': undefined;
|
|
170
|
+
'track.subscribed': RoomTrackEvent;
|
|
171
|
+
'track.unsubscribed': RoomTrackEvent;
|
|
172
|
+
/** participantIds currently speaking (drives an active-speaker UI). */
|
|
173
|
+
'active.speakers': string[];
|
|
174
|
+
}
|
|
175
|
+
type Handler<E extends RoomEventName> = (payload: RoomEventPayloads[E]) => void;
|
|
176
|
+
interface RoomSession {
|
|
177
|
+
/** This session's own stable participant id (`p_…`). Useful to filter
|
|
178
|
+
* yourself out of `active.speakers`, which includes the local participant. */
|
|
179
|
+
readonly participantId: string;
|
|
180
|
+
/** Snapshot of the remote participants currently connected. */
|
|
181
|
+
readonly participants: RoomParticipantInfo[];
|
|
182
|
+
/** Subscribe to a typed event. No unsubscribe surface yet (mirrors `Call.onX`). */
|
|
183
|
+
on<E extends RoomEventName>(event: E, handler: Handler<E>): void;
|
|
184
|
+
/** Publish the local mic track. Resolves once the track is live on LiveKit. */
|
|
185
|
+
publishMic(): Promise<void>;
|
|
186
|
+
/** Publish the local camera track. */
|
|
187
|
+
publishCamera(): Promise<void>;
|
|
188
|
+
/** Mid-call mute/unmute of the local mic. */
|
|
189
|
+
setMicEnabled(on: boolean): Promise<void>;
|
|
190
|
+
/** Mid-call camera on/off. */
|
|
191
|
+
setCameraEnabled(on: boolean): Promise<void>;
|
|
192
|
+
/** Current local mic state (for toggle UI). */
|
|
193
|
+
isMicEnabled(): boolean;
|
|
194
|
+
/** Current local camera state (for toggle UI). */
|
|
195
|
+
isCameraEnabled(): boolean;
|
|
196
|
+
/** The local camera track for self-view, or null before publishCamera resolves. */
|
|
197
|
+
getLocalCameraTrack(): LocalVideoTrack | null;
|
|
198
|
+
/**
|
|
199
|
+
* Remote tracks already subscribed at this moment. A late joiner misses the
|
|
200
|
+
* live `track.subscribed` events for tracks published before it connected
|
|
201
|
+
* (LiveKit delivers them during `connect`, before consumer listeners attach).
|
|
202
|
+
* Call this right after registering `track.subscribed` to backfill them.
|
|
203
|
+
*/
|
|
204
|
+
getRemoteTracks(): RoomTrackEvent[];
|
|
205
|
+
/**
|
|
206
|
+
* Start/stop sharing the screen (via `getDisplayMedia`). Pass `{ audio: true }`
|
|
207
|
+
* to also capture shared/system audio where the browser allows it (Chrome:
|
|
208
|
+
* tab or system audio; macOS Chrome is tab-audio only; Safari/Firefox don't
|
|
209
|
+
* capture share audio). Publishes a `screen_share` video track (+ optional
|
|
210
|
+
* `screen_share_audio`); remote peers receive them via `track.subscribed`.
|
|
211
|
+
*/
|
|
212
|
+
setScreenShareEnabled(on: boolean, opts?: {
|
|
213
|
+
audio?: boolean;
|
|
214
|
+
}): Promise<void>;
|
|
215
|
+
/** Current local screen-share state (for toggle UI). */
|
|
216
|
+
isScreenShareEnabled(): boolean;
|
|
217
|
+
/** The local screen-share video track for self-preview, or null when off. */
|
|
218
|
+
getLocalScreenTrack(): LocalVideoTrack | null;
|
|
219
|
+
/** Disconnect from LiveKit. Idempotent. Triggers `room.ended` via Disconnected. */
|
|
220
|
+
leave(): Promise<void>;
|
|
221
|
+
}
|
|
222
|
+
declare const joinRoom: (opts: JoinRoomOptions) => Promise<RoomSession>;
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Browser-friendly text-channel chat session. Mint a `ct_` token with
|
|
226
|
+
* `channel: 'text'` on your backend, then call `startTextSession({...})`
|
|
227
|
+
* to open the SSE stream.
|
|
228
|
+
*
|
|
229
|
+
* Each `.send(text)` is a fresh POST; SSE-per-turn means the connection
|
|
230
|
+
* closes when each turn ends. Conversation state lives server-side on the
|
|
231
|
+
* underlying CallRecord.
|
|
232
|
+
*/
|
|
233
|
+
type ChatEvent = {
|
|
234
|
+
type: 'chat.started';
|
|
235
|
+
chatId: string;
|
|
236
|
+
callId: string;
|
|
237
|
+
} | {
|
|
238
|
+
type: 'token';
|
|
239
|
+
text: string;
|
|
240
|
+
} | {
|
|
241
|
+
type: 'tool.call';
|
|
242
|
+
name: string;
|
|
243
|
+
args: unknown;
|
|
244
|
+
} | {
|
|
245
|
+
type: 'tool.result';
|
|
246
|
+
name: string;
|
|
247
|
+
ok?: boolean;
|
|
248
|
+
[key: string]: unknown;
|
|
249
|
+
} | {
|
|
250
|
+
type: 'turn.end';
|
|
251
|
+
finishReason: 'stop' | 'aborted' | 'length' | 'tool_error';
|
|
252
|
+
committedText?: string;
|
|
253
|
+
} | {
|
|
254
|
+
type: 'error';
|
|
255
|
+
code: string;
|
|
256
|
+
message: string;
|
|
257
|
+
};
|
|
258
|
+
interface StartTextSessionOpts {
|
|
259
|
+
baseUrl: string;
|
|
260
|
+
token: string;
|
|
261
|
+
agentId: string;
|
|
262
|
+
/** Optional inline first user message; otherwise the agent's greeting opens the stream. */
|
|
263
|
+
text?: string;
|
|
264
|
+
/** Override the global fetch (useful for tests; defaults to globalThis.fetch). */
|
|
265
|
+
fetch?: typeof fetch;
|
|
266
|
+
}
|
|
267
|
+
interface TextSession {
|
|
268
|
+
id: string;
|
|
269
|
+
callId: string;
|
|
270
|
+
/** Async iterable for the opening turn — greeting tokens / first reply if text was inlined. */
|
|
271
|
+
greeting: AsyncIterable<ChatEvent>;
|
|
272
|
+
/** Send a user message; returns an async iterable for the agent's reply. */
|
|
273
|
+
send(text: string): Promise<AsyncIterable<ChatEvent>>;
|
|
274
|
+
/** End the session — DELETE /v1/calls/:callId. */
|
|
275
|
+
end(): Promise<void>;
|
|
276
|
+
}
|
|
277
|
+
declare function startTextSession(opts: StartTextSessionOpts): Promise<TextSession>;
|
|
278
|
+
|
|
82
279
|
interface FetchTokenArgs {
|
|
83
280
|
/** The agent the SDK is about to call. */
|
|
84
281
|
agentId: string;
|
|
@@ -228,6 +425,25 @@ interface VoiceClientFactory {
|
|
|
228
425
|
* don't reject this promise.
|
|
229
426
|
*/
|
|
230
427
|
startCall: (options: StartCallOptions) => Promise<Call>;
|
|
428
|
+
/**
|
|
429
|
+
* Phase 7 (multi-party rooms). Browser only. Exchange a single-use
|
|
430
|
+
* joinCode for a LiveKit JWT and connect to the room. The returned
|
|
431
|
+
* `RoomSession` exposes a typed event surface
|
|
432
|
+
* (participant.joined / participant.left / transcript.partial /
|
|
433
|
+
* transcript.final / system.message / room.ended) plus
|
|
434
|
+
* publishMic / publishCamera / leave. The Node bundle does NOT
|
|
435
|
+
* implement this — livekit-client is a browser-only WebRTC client.
|
|
436
|
+
*/
|
|
437
|
+
joinRoom?: (options: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>;
|
|
438
|
+
/**
|
|
439
|
+
* Open a text-channel chat session (no microphone / audio required).
|
|
440
|
+
* Mint a `ct_` token with `channel: 'text'` server-side, then call
|
|
441
|
+
* this to connect. Returns a `TextSession` with:
|
|
442
|
+
* - `.greeting` — async iterable for the opening turn
|
|
443
|
+
* - `.send(text)` — send a user message; returns an async iterable for the reply
|
|
444
|
+
* - `.end()` — close the session (DELETE /v1/calls/:callId)
|
|
445
|
+
*/
|
|
446
|
+
startTextSession?: (opts: Omit<StartTextSessionOpts, 'baseUrl' | 'fetch'>) => Promise<TextSession>;
|
|
231
447
|
}
|
|
232
448
|
|
|
233
449
|
type OnChunk = (pcm: ArrayBuffer) => void;
|
|
@@ -307,6 +523,31 @@ declare const createReconnectingWebSocket: (options: RWSOptions, onEvent: (ev: R
|
|
|
307
523
|
};
|
|
308
524
|
type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>;
|
|
309
525
|
|
|
526
|
+
/**
|
|
527
|
+
* Canonical payload a tenant places in their VoIP/FCM push so an
|
|
528
|
+
* agent-initiated call can connect. It is the `callTokens.mint` result
|
|
529
|
+
* (token + transport) plus two optional display fields for the native
|
|
530
|
+
* incoming-call UI. The host receives the push, runs `parseIncomingCall`,
|
|
531
|
+
* and on accept passes `token` (+ transport / webrtcGatewayBase) into the
|
|
532
|
+
* voice client. Web background-wake is best-effort (Web Push); native is
|
|
533
|
+
* the real target. See docs/sdks.md "Agent-initiated calls".
|
|
534
|
+
*/
|
|
535
|
+
interface IncomingCallPayload {
|
|
536
|
+
token: string;
|
|
537
|
+
agentId: string;
|
|
538
|
+
transport: 'ws' | 'webrtc';
|
|
539
|
+
webrtcGatewayBase?: string;
|
|
540
|
+
expiresAt?: number;
|
|
541
|
+
agentName?: string;
|
|
542
|
+
agentAvatarUrl?: string;
|
|
543
|
+
}
|
|
544
|
+
/**
|
|
545
|
+
* Validate + normalise a raw push payload into an IncomingCallPayload.
|
|
546
|
+
* Throws synchronously on malformed input. Unknown transports fall back to
|
|
547
|
+
* 'ws'; webrtcGatewayBase is ignored unless transport === 'webrtc'.
|
|
548
|
+
*/
|
|
549
|
+
declare const parseIncomingCall: (raw: unknown) => IncomingCallPayload;
|
|
550
|
+
|
|
310
551
|
/**
|
|
311
552
|
* One-time SDK setup. Returns a factory you call `startCall` on for
|
|
312
553
|
* every voice call.
|
|
@@ -334,4 +575,4 @@ type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>;
|
|
|
334
575
|
*/
|
|
335
576
|
declare function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory;
|
|
336
577
|
|
|
337
|
-
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 };
|
|
578
|
+
export { type Call, type CallEndEvent, type CallEndReason, type CallError, type CallErrorCode, type CallState, type CaptureController, type CaptureOptions, type ChatEvent, type ClientTool, type ClientToolMap, type FetchToken, type FetchTokenArgs, type FetchTokenResult, type IncomingCallPayload, type JoinRoomOptions, 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 RoomEventName, type RoomEventPayloads, type RoomParticipantInfo, type RoomSession, type ServerMessage, type StartCallOptions, type StartTextSessionOpts, type SystemMessage, type TextSession, type TranscriptEntry, type TranscriptMessage, type VoiceClientConfig, type VoiceClientFactory, type VolumeEvent, type WebSocketFactory, type WebSocketLike, buildWsUrl, configureVoiceClient, createAudioCapture, createAudioPlayback, createProtocolState, createReconnectingWebSocket, handleServerMessage, joinRoom, parseIncomingCall, startTextSession };
|