@nightzeros/chatai-widget-core 1.0.0 → 1.1.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/dist/index.js CHANGED
@@ -1,4 +1,819 @@
1
+ // src/control-health.ts
2
+ var CONTROL_HEALTH_DEFAULTS = {
3
+ intervalMs: 5e3,
4
+ reconnectIntervalMs: 2e3,
5
+ requestTimeoutMs: 4e3,
6
+ failuresToReconnect: 2,
7
+ silenceToReconnectMs: 12e3,
8
+ reconnectGraceMs: 2e4,
9
+ lostCloseWindowMs: 1e4,
10
+ tickMs: 500
11
+ };
12
+ function initialControlHealth(now) {
13
+ return {
14
+ status: "healthy",
15
+ failures: 0,
16
+ lastSuccessAt: now,
17
+ reconnectingSince: null,
18
+ closingSince: null,
19
+ endReason: null,
20
+ cause: null
21
+ };
22
+ }
23
+ function isControlMuted(status) {
24
+ return status === "reconnecting" || status === "closing";
25
+ }
26
+ function terminated(state, endReason, cause) {
27
+ return { ...state, status: "terminated", endReason, cause };
28
+ }
29
+ function reconnecting(state, now) {
30
+ return { ...state, status: "reconnecting", reconnectingSince: state.reconnectingSince ?? now };
31
+ }
32
+ function reduceControlHealth(state, input, now, settings = CONTROL_HEALTH_DEFAULTS) {
33
+ if (state.status === "terminated") return state;
34
+ switch (input.kind) {
35
+ case "tick":
36
+ if (state.status === "closing" && now - (state.closingSince ?? now) >= settings.lostCloseWindowMs) {
37
+ return terminated(state, "disconnected", "lost");
38
+ }
39
+ if (state.status === "reconnecting" && now - (state.reconnectingSince ?? now) >= settings.reconnectGraceMs) {
40
+ return terminated(state, "disconnected", "grace_expired");
41
+ }
42
+ if ((state.status === "healthy" || state.status === "suspect") && now - state.lastSuccessAt >= settings.silenceToReconnectMs) {
43
+ return reconnecting(state, now);
44
+ }
45
+ return state;
46
+ case "healthy":
47
+ if (state.status === "closing") return state;
48
+ return { ...state, status: "healthy", failures: 0, lastSuccessAt: now, reconnectingSince: null };
49
+ case "degraded":
50
+ if (state.status === "closing") return state;
51
+ return reconnecting({ ...state, failures: 0 }, now);
52
+ case "neutral":
53
+ return state;
54
+ case "failure": {
55
+ const failures = state.failures + 1;
56
+ if (state.status === "healthy" || state.status === "suspect") {
57
+ return failures >= settings.failuresToReconnect ? reconnecting({ ...state, failures }, now) : { ...state, status: "suspect", failures };
58
+ }
59
+ return { ...state, failures };
60
+ }
61
+ case "ended":
62
+ return terminated(state, input.endReason ?? "disconnected", "ended");
63
+ case "lost":
64
+ if (state.status === "closing") return state;
65
+ return { ...state, status: "closing", closingSince: now, failures: 0 };
66
+ }
67
+ }
68
+ function classifyHeartbeatResponse(status, body) {
69
+ const data = body && typeof body === "object" ? body : {};
70
+ const nextMs = typeof data.nextHeartbeatMs === "number" && data.nextHeartbeatMs > 0 ? data.nextHeartbeatMs : void 0;
71
+ if (status === 421 || status === 429) return { kind: "neutral", ...nextMs ? { nextMs } : {} };
72
+ if (status === 404) return { kind: "lost" };
73
+ if (status !== 200) return { kind: "failure" };
74
+ switch (data.state) {
75
+ case "healthy":
76
+ return { kind: "healthy", ...nextMs ? { nextMs } : {} };
77
+ case "degraded":
78
+ return { kind: "degraded", ...nextMs ? { nextMs } : {} };
79
+ case "ended":
80
+ return { kind: "ended", endReason: typeof data.endReason === "string" ? data.endReason : null };
81
+ case "lost":
82
+ return { kind: "lost" };
83
+ default:
84
+ return { kind: "failure" };
85
+ }
86
+ }
87
+ function createControlHealthMonitor(options) {
88
+ const now = options.now ?? (() => Date.now());
89
+ const settings = {
90
+ ...CONTROL_HEALTH_DEFAULTS,
91
+ ...options.settings,
92
+ ...options.intervalMs && options.intervalMs > 0 ? { intervalMs: options.intervalMs } : {}
93
+ };
94
+ let state = initialControlHealth(now());
95
+ let running = false;
96
+ let beatTimer = null;
97
+ let tickTimer = null;
98
+ let inFlight = null;
99
+ let requestTimer = null;
100
+ const stop = () => {
101
+ running = false;
102
+ if (beatTimer) clearTimeout(beatTimer);
103
+ beatTimer = null;
104
+ if (requestTimer) clearTimeout(requestTimer);
105
+ requestTimer = null;
106
+ if (tickTimer) clearInterval(tickTimer);
107
+ tickTimer = null;
108
+ const request = inFlight;
109
+ inFlight = null;
110
+ request?.abort();
111
+ };
112
+ const apply = (input) => {
113
+ if (!running) return;
114
+ const previous = state;
115
+ const next = reduceControlHealth(previous, input, now(), settings);
116
+ state = next;
117
+ if (next.status === previous.status) return;
118
+ if (next.status === "terminated") stop();
119
+ options.onChange(next, previous);
120
+ };
121
+ const schedule = (delayMs) => {
122
+ if (!running) return;
123
+ if (beatTimer) clearTimeout(beatTimer);
124
+ beatTimer = setTimeout(() => void beat(), Math.max(0, delayMs));
125
+ };
126
+ const beat = async () => {
127
+ beatTimer = null;
128
+ if (!running || inFlight) return;
129
+ const controller = new AbortController();
130
+ inFlight = controller;
131
+ const abortedOrTimedOut = new Promise((resolve) => {
132
+ controller.signal.addEventListener("abort", () => resolve({ kind: "failure" }), { once: true });
133
+ requestTimer = setTimeout(() => controller.abort(), settings.requestTimeoutMs);
134
+ });
135
+ const outcome = await Promise.race([
136
+ options.send(controller.signal).catch(() => ({ kind: "failure" })),
137
+ abortedOrTimedOut
138
+ ]);
139
+ if (inFlight !== controller) return;
140
+ if (requestTimer) clearTimeout(requestTimer);
141
+ requestTimer = null;
142
+ inFlight = null;
143
+ apply(outcome);
144
+ if (!running) return;
145
+ const hinted = "nextMs" in outcome ? outcome.nextMs : void 0;
146
+ const fast = isControlMuted(state.status);
147
+ schedule(fast ? Math.min(hinted ?? settings.reconnectIntervalMs, settings.reconnectIntervalMs) : hinted ?? settings.intervalMs);
148
+ };
149
+ return {
150
+ start() {
151
+ if (running || state.status === "terminated") return;
152
+ running = true;
153
+ state = initialControlHealth(now());
154
+ schedule(settings.intervalMs);
155
+ tickTimer = setInterval(() => apply({ kind: "tick" }), settings.tickMs);
156
+ },
157
+ stop,
158
+ state: () => state
159
+ };
160
+ }
161
+
162
+ // src/voice-state.ts
163
+ var VOICE_ACTIVITY_HOLD_MS = 450;
164
+ var VOICE_INTERRUPTED_HOLD_MS = 1500;
165
+ var VOICE_PHASE_LABELS = {
166
+ idle: "Voice is off",
167
+ requesting_mic: "Allow microphone access",
168
+ connecting: "Connecting\u2026",
169
+ listening: "Listening",
170
+ user_speaking: "Hearing you",
171
+ processing: "Looking that up\u2026",
172
+ assistant_speaking: "Speaking",
173
+ interrupted: "Interrupted \u2014 go ahead",
174
+ reconnecting: "Reconnecting\u2026",
175
+ error: "Voice stopped",
176
+ ended: "Voice ended"
177
+ };
178
+ function recent(at, now, windowMs) {
179
+ return at !== null && now - at < windowMs;
180
+ }
181
+ function isUserActive(signals) {
182
+ return recent(signals.userVoiceAt, signals.now, VOICE_ACTIVITY_HOLD_MS);
183
+ }
184
+ function isAssistantActive(signals) {
185
+ return recent(signals.assistantVoiceAt, signals.now, VOICE_ACTIVITY_HOLD_MS);
186
+ }
187
+ function deriveVoicePhase(signals) {
188
+ switch (signals.connection) {
189
+ case "idle":
190
+ return "idle";
191
+ case "requesting_mic":
192
+ return "requesting_mic";
193
+ case "connecting":
194
+ return "connecting";
195
+ case "reconnecting":
196
+ return "reconnecting";
197
+ case "failed":
198
+ return "error";
199
+ case "ended":
200
+ return "ended";
201
+ case "connected":
202
+ break;
203
+ }
204
+ if (recent(signals.interruptedAt, signals.now, VOICE_INTERRUPTED_HOLD_MS)) return "interrupted";
205
+ if (isUserActive(signals)) return "user_speaking";
206
+ if (signals.processing) return "processing";
207
+ if (isAssistantActive(signals)) return "assistant_speaking";
208
+ return "listening";
209
+ }
210
+ function detectInterruption(input) {
211
+ return !input.userWasActive && input.userIsActive && input.assistantIsActive;
212
+ }
213
+ function isVoiceActive(connection) {
214
+ return connection === "requesting_mic" || connection === "connecting" || connection === "connected" || connection === "reconnecting";
215
+ }
216
+
217
+ // src/voice-transcript.ts
218
+ var BARGE_IN_MIN_WORDS = 2;
219
+ function words(text) {
220
+ return text.trim().split(/\s+/).filter(Boolean).length;
221
+ }
222
+ function createVoiceTranscript(idPrefix) {
223
+ const turns = [];
224
+ let pending = null;
225
+ let assistantEndMs = Number.NEGATIVE_INFINITY;
226
+ let counter = 0;
227
+ const push = (role, text) => {
228
+ turns.push({ id: `${idPrefix}:${counter++}`, role, text, interrupted: false });
229
+ };
230
+ const commitPending = () => {
231
+ if (!pending) return;
232
+ const last = turns.at(-1);
233
+ if (last?.role === "assistant") last.interrupted = true;
234
+ push("user", pending.text);
235
+ pending = null;
236
+ };
237
+ return {
238
+ input(delta, startMs) {
239
+ if (!delta) return;
240
+ const last = turns.at(-1);
241
+ if (pending) {
242
+ if (startMs >= assistantEndMs && pending.startMs < assistantEndMs && words(pending.text) < BARGE_IN_MIN_WORDS) {
243
+ pending = null;
244
+ push("user", delta);
245
+ return;
246
+ }
247
+ pending.text += delta;
248
+ if (words(pending.text) >= BARGE_IN_MIN_WORDS) commitPending();
249
+ return;
250
+ }
251
+ if (last?.role === "user") {
252
+ last.text += delta;
253
+ return;
254
+ }
255
+ if (last?.role === "assistant" && startMs < assistantEndMs) {
256
+ pending = { text: delta, startMs };
257
+ if (words(pending.text) >= BARGE_IN_MIN_WORDS) commitPending();
258
+ return;
259
+ }
260
+ push("user", delta);
261
+ },
262
+ output(delta, endMs) {
263
+ if (!delta) return;
264
+ pending = null;
265
+ assistantEndMs = Math.max(assistantEndMs, endMs);
266
+ const last = turns.at(-1);
267
+ if (last?.role === "assistant") {
268
+ last.text += delta;
269
+ return;
270
+ }
271
+ push("assistant", delta);
272
+ },
273
+ /** Committed turns in spoken order (copies). */
274
+ turns() {
275
+ return turns.filter((turn) => turn.text.trim()).map((turn) => ({ ...turn, text: turn.text.trim() }));
276
+ },
277
+ /** Ends the transcript; short speech still overlapping the assistant is dropped. */
278
+ finish() {
279
+ pending = null;
280
+ return this.turns();
281
+ }
282
+ };
283
+ }
284
+
285
+ // src/voice.ts
286
+ var VOICE_END_NOTICES = {
287
+ voice_unavailable: "Voice is unavailable for the rest of this conversation, but we can keep chatting here.",
288
+ superseded: "Voice continued in another tab or window. You can keep typing here.",
289
+ disconnected: "Voice disconnected. You can keep typing here.",
290
+ idle: "Voice ended after a period of silence. You can keep typing here.",
291
+ max_duration: "Voice reached its maximum length. You can keep typing here."
292
+ };
293
+ function visitorEndReason(reported) {
294
+ switch (reported) {
295
+ case "voice_unavailable":
296
+ case "usage_limit":
297
+ return "voice_unavailable";
298
+ case "superseded":
299
+ return "superseded";
300
+ case "idle":
301
+ return "idle";
302
+ case "max_duration":
303
+ return "max_duration";
304
+ case "disconnected":
305
+ case "heartbeat_lost":
306
+ case "control_lost":
307
+ case "shutdown":
308
+ return "disconnected";
309
+ default:
310
+ return null;
311
+ }
312
+ }
313
+ var VOICE_ERROR_MESSAGES = {
314
+ unsupported: "Voice needs a browser with microphone and WebRTC support on a secure (HTTPS) page.",
315
+ mic_denied: "Microphone access is blocked. Allow it in your browser settings to talk, or keep typing.",
316
+ mic_unavailable: "No microphone is available. Check that one is connected and not in use by another app.",
317
+ voice_unavailable: "Voice isn't available right now. You can keep typing.",
318
+ rate_limited: "Too many voice requests. Please wait a moment and try again.",
319
+ network: "Unable to reach the voice service. Check your connection and try again.",
320
+ media_failed: "The voice connection dropped. Try again to continue.",
321
+ server: "Voice could not start. Please try again."
322
+ };
323
+ var MIC_RMS_THRESHOLD = 0.02;
324
+ var REMOTE_RMS_THRESHOLD = 0.01;
325
+ var TICK_MS = 100;
326
+ var ICE_GATHER_TIMEOUT_MS = 4e3;
327
+ var FILLER_WINDOW_MS = 1200;
328
+ var PROCESSING_TIMEOUT_MS = 2e4;
329
+ var DISCONNECT_GRACE_MS = 5e3;
330
+ var MOCK_SDP_MARKER = "a=chatai-mock-session:";
331
+ function browserVoiceMedia() {
332
+ if (typeof window === "undefined" || typeof navigator === "undefined") return null;
333
+ if (window.isSecureContext === false) return null;
334
+ const mediaDevices = navigator.mediaDevices;
335
+ if (!mediaDevices?.getUserMedia || typeof RTCPeerConnection === "undefined") return null;
336
+ return {
337
+ getUserMedia: (constraints) => mediaDevices.getUserMedia(constraints),
338
+ createPeerConnection: () => new RTCPeerConnection(),
339
+ createAudioContext: () => {
340
+ const Ctor = globalThis.AudioContext ?? globalThis.webkitAudioContext;
341
+ try {
342
+ return Ctor ? new Ctor() : null;
343
+ } catch {
344
+ return null;
345
+ }
346
+ },
347
+ createAudioElement: () => {
348
+ if (typeof document === "undefined") return null;
349
+ const audio = document.createElement("audio");
350
+ audio.autoplay = true;
351
+ audio.setAttribute("playsinline", "");
352
+ return audio;
353
+ }
354
+ };
355
+ }
356
+ function micError(error) {
357
+ const name = error instanceof Error || error instanceof DOMException ? error.name : "";
358
+ if (name === "NotAllowedError" || name === "SecurityError" || name === "PermissionDeniedError") {
359
+ return { code: "mic_denied", message: VOICE_ERROR_MESSAGES.mic_denied };
360
+ }
361
+ if (name === "NotFoundError" || name === "NotReadableError" || name === "OverconstrainedError") {
362
+ return { code: "mic_unavailable", message: VOICE_ERROR_MESSAGES.mic_unavailable };
363
+ }
364
+ return { code: "server", message: VOICE_ERROR_MESSAGES.server };
365
+ }
366
+ async function mintError(response) {
367
+ const body = await response.json().catch(() => ({}));
368
+ if (response.status === 402 || body.reason === "voice_unavailable" || body.reason === "voice_minutes_exhausted" || body.reason === "voice_concurrency_limit") {
369
+ return { code: "voice_unavailable", message: VOICE_ERROR_MESSAGES.voice_unavailable };
370
+ }
371
+ if (response.status === 429) return { code: "rate_limited", message: VOICE_ERROR_MESSAGES.rate_limited };
372
+ if (response.status >= 500) {
373
+ return { code: "voice_unavailable", message: VOICE_ERROR_MESSAGES.voice_unavailable };
374
+ }
375
+ if (response.status === 403 && /voice is not enabled/i.test(body.error ?? "")) {
376
+ return { code: "voice_unavailable", message: VOICE_ERROR_MESSAGES.voice_unavailable };
377
+ }
378
+ return { code: "server", message: body.error?.slice(0, 200) || VOICE_ERROR_MESSAGES.server };
379
+ }
380
+ function waitForIceGathering(pc) {
381
+ if (pc.iceGatheringState === "complete") return Promise.resolve();
382
+ return new Promise((resolve) => {
383
+ const timer = setTimeout(done, ICE_GATHER_TIMEOUT_MS);
384
+ function done() {
385
+ clearTimeout(timer);
386
+ pc.removeEventListener("icegatheringstatechange", check);
387
+ resolve();
388
+ }
389
+ function check() {
390
+ if (pc.iceGatheringState === "complete") done();
391
+ }
392
+ pc.addEventListener("icegatheringstatechange", check);
393
+ });
394
+ }
395
+ function rms(analyser) {
396
+ if (!analyser) return 0;
397
+ analyser.node.getFloatTimeDomainData(analyser.buffer);
398
+ let sum = 0;
399
+ for (const sample of analyser.buffer) sum += sample * sample;
400
+ return Math.sqrt(sum / analyser.buffer.length);
401
+ }
402
+ function analyse(ctx, stream) {
403
+ if (!ctx) return null;
404
+ try {
405
+ const node = ctx.createAnalyser();
406
+ node.fftSize = 512;
407
+ ctx.createMediaStreamSource(stream).connect(node);
408
+ return { node, buffer: new Float32Array(node.fftSize) };
409
+ } catch {
410
+ return null;
411
+ }
412
+ }
413
+ function createVoiceSession(options) {
414
+ const fetcher = options.fetch;
415
+ const now = options.now ?? (() => Date.now());
416
+ const transcript = createVoiceTranscript(`voice_${now().toString(36)}`);
417
+ const signals = {
418
+ connection: "idle",
419
+ now: now(),
420
+ userVoiceAt: null,
421
+ assistantVoiceAt: null,
422
+ processing: false,
423
+ interruptedAt: null
424
+ };
425
+ let phase = "idle";
426
+ let error;
427
+ let ephemeral;
428
+ let transcriptSaved;
429
+ let conversationId;
430
+ let recording;
431
+ let endReason;
432
+ let mock = false;
433
+ let sessionId = null;
434
+ let lastHeaders = { "Content-Type": "application/json" };
435
+ let stopped = false;
436
+ let mic = null;
437
+ let pc = null;
438
+ let audio = null;
439
+ let audioCtx = null;
440
+ let micAnalyser = null;
441
+ let remoteAnalyser = null;
442
+ let tick = null;
443
+ let disconnectTimer = null;
444
+ let health = null;
445
+ let processingSince = 0;
446
+ let userWasActive = false;
447
+ const levels = { input: 0, output: 0 };
448
+ const snapshot = () => ({
449
+ connection: signals.connection,
450
+ phase,
451
+ ...error ? { error } : {},
452
+ ...ephemeral !== void 0 ? { ephemeral } : {},
453
+ ...transcriptSaved !== void 0 ? { transcriptSaved } : {},
454
+ ...conversationId !== void 0 ? { conversationId } : {},
455
+ ...recording !== void 0 ? { recording } : {},
456
+ ...endReason ? { endReason, notice: VOICE_END_NOTICES[endReason] } : {},
457
+ mock,
458
+ turns: transcript.turns()
459
+ });
460
+ const emit = () => options.onChange(snapshot());
461
+ const refreshPhase = (force = false) => {
462
+ signals.now = now();
463
+ const next = deriveVoicePhase(signals);
464
+ if (next !== phase || force) {
465
+ phase = next;
466
+ emit();
467
+ }
468
+ };
469
+ const setConnection = (next) => {
470
+ signals.connection = next;
471
+ refreshPhase(true);
472
+ };
473
+ const onTick = () => {
474
+ const at = now();
475
+ if (signals.connection === "reconnecting") {
476
+ levels.input = 0;
477
+ levels.output = 0;
478
+ refreshPhase();
479
+ return;
480
+ }
481
+ levels.input = rms(micAnalyser);
482
+ levels.output = rms(remoteAnalyser);
483
+ if (levels.input > MIC_RMS_THRESHOLD) signals.userVoiceAt = at;
484
+ if (levels.output > REMOTE_RMS_THRESHOLD) signals.assistantVoiceAt = at;
485
+ if (signals.processing && at - processingSince > PROCESSING_TIMEOUT_MS) signals.processing = false;
486
+ signals.now = at;
487
+ const userActive = isUserActive(signals);
488
+ if (detectInterruption({
489
+ userWasActive,
490
+ userIsActive: userActive,
491
+ assistantIsActive: isAssistantActive(signals)
492
+ })) {
493
+ signals.interruptedAt = at;
494
+ }
495
+ userWasActive = userActive;
496
+ refreshPhase();
497
+ };
498
+ const teardownMedia = () => {
499
+ health?.stop();
500
+ health = null;
501
+ if (tick) clearInterval(tick);
502
+ tick = null;
503
+ if (disconnectTimer) clearTimeout(disconnectTimer);
504
+ disconnectTimer = null;
505
+ pc?.getSenders().forEach((sender) => sender.track?.stop());
506
+ pc?.close();
507
+ pc = null;
508
+ mic?.getTracks().forEach((track) => track.stop());
509
+ mic = null;
510
+ if (audio) {
511
+ audio.pause?.();
512
+ audio.srcObject = null;
513
+ }
514
+ audio = null;
515
+ void audioCtx?.close().catch(() => void 0);
516
+ audioCtx = null;
517
+ micAnalyser = null;
518
+ remoteAnalyser = null;
519
+ levels.input = 0;
520
+ levels.output = 0;
521
+ signals.processing = false;
522
+ signals.userVoiceAt = null;
523
+ signals.assistantVoiceAt = null;
524
+ signals.interruptedAt = null;
525
+ };
526
+ const endServerSession = async (reason, keepalive) => {
527
+ const id = sessionId;
528
+ sessionId = null;
529
+ if (!id) return;
530
+ const headers = keepalive ? lastHeaders : await options.headers().catch(() => lastHeaders);
531
+ const response = await fetcher(
532
+ `${options.apiUrl}/api/v1/voice/sessions/${encodeURIComponent(id)}/end`,
533
+ {
534
+ method: "POST",
535
+ headers,
536
+ body: JSON.stringify({ reason, visitorId: options.visitorId, source: "widget" }),
537
+ keepalive
538
+ }
539
+ ).catch(() => null);
540
+ if (!response?.ok) return;
541
+ const body = await response.json().catch(() => null);
542
+ const reported = visitorEndReason(body?.endReason);
543
+ if (reported) {
544
+ endReason = reported;
545
+ if (signals.connection === "failed") {
546
+ error = void 0;
547
+ signals.connection = "ended";
548
+ }
549
+ refreshPhase(true);
550
+ }
551
+ };
552
+ const fail = async (next, reason = "error") => {
553
+ if (stopped) return;
554
+ stopped = true;
555
+ error = next;
556
+ teardownMedia();
557
+ transcript.finish();
558
+ setConnection("failed");
559
+ await endServerSession(reason, false);
560
+ };
561
+ const setMediaMuted = (muted) => {
562
+ mic?.getTracks().forEach((track) => {
563
+ track.enabled = !muted;
564
+ });
565
+ if (audio) audio.muted = muted;
566
+ };
567
+ const terminateForControl = async (reported) => {
568
+ if (stopped) return;
569
+ stopped = true;
570
+ endReason = visitorEndReason(reported) ?? "disconnected";
571
+ teardownMedia();
572
+ transcript.finish();
573
+ setConnection("ended");
574
+ await endServerSession("connection_lost", false);
575
+ };
576
+ const onControlHealth = (next, previous) => {
577
+ if (stopped) return;
578
+ if (next.status === "terminated") {
579
+ void terminateForControl(next.endReason);
580
+ return;
581
+ }
582
+ const muted = isControlMuted(next.status);
583
+ if (muted && !isControlMuted(previous.status)) {
584
+ setMediaMuted(true);
585
+ signals.processing = false;
586
+ signals.userVoiceAt = null;
587
+ signals.assistantVoiceAt = null;
588
+ signals.interruptedAt = null;
589
+ userWasActive = false;
590
+ setConnection("reconnecting");
591
+ } else if (!muted && signals.connection === "reconnecting") {
592
+ setMediaMuted(false);
593
+ setConnection("connected");
594
+ }
595
+ };
596
+ const startControlHealth = (id, token, intervalMs) => {
597
+ const { now: healthNow, ...settings } = options.controlHealth ?? {};
598
+ const send = async (signal) => {
599
+ const response = await fetcher(
600
+ `${options.apiUrl}/api/v1/voice/sessions/${encodeURIComponent(id)}/heartbeat`,
601
+ {
602
+ method: "POST",
603
+ headers: { "Content-Type": "application/json" },
604
+ body: JSON.stringify({ token }),
605
+ signal
606
+ }
607
+ );
608
+ return classifyHeartbeatResponse(response.status, await response.json().catch(() => null));
609
+ };
610
+ health = createControlHealthMonitor({
611
+ send,
612
+ onChange: onControlHealth,
613
+ intervalMs,
614
+ settings,
615
+ ...healthNow ? { now: healthNow } : {}
616
+ });
617
+ health.start();
618
+ };
619
+ const mediaLost = () => {
620
+ if (signals.connection === "reconnecting") {
621
+ void terminateForControl("disconnected");
622
+ return;
623
+ }
624
+ void fail({ code: "media_failed", message: VOICE_ERROR_MESSAGES.media_failed }, "connection_lost");
625
+ };
626
+ const handleEvent = (event) => {
627
+ const at = now();
628
+ if (signals.connection === "reconnecting") {
629
+ if (event.type === "session.closed") void terminateForControl("disconnected");
630
+ return;
631
+ }
632
+ switch (event.type) {
633
+ case "session.started":
634
+ if (signals.connection === "connecting") setConnection("connected");
635
+ return;
636
+ case "session.input_transcript.delta":
637
+ signals.userVoiceAt = at;
638
+ transcript.input(event.delta ?? "", event.start_ms ?? at);
639
+ refreshPhase(true);
640
+ return;
641
+ case "session.output_transcript.delta":
642
+ signals.assistantVoiceAt = at;
643
+ if (signals.processing && at - processingSince >= FILLER_WINDOW_MS) signals.processing = false;
644
+ transcript.output(event.delta ?? "", event.end_ms ?? at);
645
+ refreshPhase(true);
646
+ return;
647
+ case "session.delegation.created":
648
+ signals.processing = true;
649
+ processingSince = at;
650
+ refreshPhase();
651
+ return;
652
+ case "session.closed":
653
+ void session.end("remote_hangup");
654
+ return;
655
+ }
656
+ };
657
+ const session = {
658
+ snapshot,
659
+ /** Mic/speaker levels (0–1-ish RMS) for visual feedback; read on animation frames. */
660
+ levels() {
661
+ return { ...levels };
662
+ },
663
+ async start() {
664
+ if (signals.connection !== "idle") return;
665
+ audio = options.media.createAudioElement();
666
+ audioCtx = options.media.createAudioContext();
667
+ setConnection("requesting_mic");
668
+ try {
669
+ mic = await options.media.getUserMedia({
670
+ audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
671
+ });
672
+ } catch (caught) {
673
+ await fail(micError(caught));
674
+ return;
675
+ }
676
+ if (stopped) {
677
+ teardownMedia();
678
+ return;
679
+ }
680
+ setConnection("connecting");
681
+ void audioCtx?.resume?.().catch(() => void 0);
682
+ micAnalyser = analyse(audioCtx, mic);
683
+ let answer;
684
+ try {
685
+ const peer = options.media.createPeerConnection();
686
+ pc = peer;
687
+ mic.getTracks().forEach((track) => peer.addTrack(track, mic));
688
+ peer.addEventListener("track", (event) => {
689
+ const [remote] = event.streams;
690
+ if (!remote || pc !== peer) return;
691
+ if (audio) {
692
+ audio.srcObject = remote;
693
+ void audio.play?.().catch(() => void 0);
694
+ }
695
+ remoteAnalyser = analyse(audioCtx, remote);
696
+ });
697
+ peer.addEventListener("connectionstatechange", () => {
698
+ if (pc !== peer || stopped) return;
699
+ const state = peer.connectionState;
700
+ if (state === "connected") {
701
+ if (disconnectTimer) clearTimeout(disconnectTimer);
702
+ disconnectTimer = null;
703
+ if (signals.connection === "connecting") setConnection("connected");
704
+ } else if (state === "failed") {
705
+ mediaLost();
706
+ } else if (state === "disconnected" && !disconnectTimer) {
707
+ disconnectTimer = setTimeout(() => {
708
+ disconnectTimer = null;
709
+ if (pc === peer && peer.connectionState !== "connected") mediaLost();
710
+ }, DISCONNECT_GRACE_MS);
711
+ }
712
+ });
713
+ const events = peer.createDataChannel("oai-events");
714
+ events.addEventListener("message", (message) => {
715
+ try {
716
+ handleEvent(JSON.parse(String(message.data)));
717
+ } catch {
718
+ }
719
+ });
720
+ await peer.setLocalDescription(await peer.createOffer());
721
+ await waitForIceGathering(peer);
722
+ if (stopped) {
723
+ teardownMedia();
724
+ return;
725
+ }
726
+ lastHeaders = await options.headers();
727
+ const response = await fetcher(`${options.apiUrl}/api/v1/voice/sessions`, {
728
+ method: "POST",
729
+ headers: lastHeaders,
730
+ body: JSON.stringify({
731
+ assistantId: options.assistantId,
732
+ sdpOffer: peer.localDescription?.sdp ?? "",
733
+ visitorId: options.visitorId,
734
+ source: "widget",
735
+ ...options.conversationId ? { conversationId: options.conversationId } : {},
736
+ ...options.history.length ? { history: options.history } : {},
737
+ ...options.recordingConsent ? { recordingConsent: true } : {},
738
+ capabilities: ["heartbeat"]
739
+ })
740
+ });
741
+ if (!response.ok) {
742
+ await fail(await mintError(response));
743
+ return;
744
+ }
745
+ answer = await response.json();
746
+ if (!answer.sessionId || !answer.sdpAnswer) {
747
+ await fail({ code: "server", message: VOICE_ERROR_MESSAGES.server });
748
+ return;
749
+ }
750
+ sessionId = answer.sessionId;
751
+ if (stopped) {
752
+ await endServerSession("close_requested", false);
753
+ return;
754
+ }
755
+ ephemeral = Boolean(answer.ephemeral);
756
+ transcriptSaved = answer.transcriptSaved ?? !ephemeral;
757
+ conversationId = answer.conversationId ?? null;
758
+ recording = Boolean(answer.recording);
759
+ mock = answer.sdpAnswer.includes(MOCK_SDP_MARKER);
760
+ if (!mock) await peer.setRemoteDescription({ type: "answer", sdp: answer.sdpAnswer });
761
+ } catch (caught) {
762
+ const offline = caught instanceof TypeError;
763
+ await fail(
764
+ offline ? { code: "network", message: VOICE_ERROR_MESSAGES.network } : { code: "server", message: VOICE_ERROR_MESSAGES.server },
765
+ "error"
766
+ );
767
+ return;
768
+ }
769
+ if (stopped) return;
770
+ tick = setInterval(onTick, TICK_MS);
771
+ if (answer.controlToken && sessionId) {
772
+ startControlHealth(sessionId, answer.controlToken, answer.heartbeatIntervalMs);
773
+ }
774
+ if (mock) setConnection("connected");
775
+ else emit();
776
+ },
777
+ /**
778
+ * Stops the mic and media immediately, then finalizes the server session.
779
+ * `keepalive` lets the end request outlive a closing page.
780
+ */
781
+ async end(reason = "close_requested", opts = {}) {
782
+ if (stopped) {
783
+ if (sessionId) await endServerSession(reason, Boolean(opts.keepalive));
784
+ return;
785
+ }
786
+ stopped = true;
787
+ teardownMedia();
788
+ transcript.finish();
789
+ setConnection(signals.connection === "idle" ? "idle" : "ended");
790
+ await endServerSession(reason, Boolean(opts.keepalive));
791
+ }
792
+ };
793
+ return session;
794
+ }
795
+
1
796
  // src/client.ts
797
+ var CLIENT_HISTORY_LIMIT = 12;
798
+ var CLIENT_HISTORY_MAX_CHARS = 1500;
799
+ var IDLE_VOICE = { connection: "idle", phase: "idle" };
800
+ function clientHistory(messages) {
801
+ return messages.filter((message) => message.content.trim() && !message.live && !message.unsaved).slice(-CLIENT_HISTORY_LIMIT).map((message) => ({
802
+ role: message.role,
803
+ content: message.content.slice(0, CLIENT_HISTORY_MAX_CHARS)
804
+ }));
805
+ }
806
+ function voiceMessages(turns, live, unsaved) {
807
+ return turns.map((turn, index) => ({
808
+ id: void 0,
809
+ role: turn.role,
810
+ content: turn.text,
811
+ modality: "voice",
812
+ ...turn.interrupted ? { interrupted: true } : {},
813
+ ...live && index === turns.length - 1 ? { live: true } : {},
814
+ ...unsaved ? { unsaved: true } : {}
815
+ }));
816
+ }
2
817
  function resolveApiUrl(value) {
3
818
  let url;
4
819
  try {
@@ -85,7 +900,12 @@ function createWidgetController(options) {
85
900
  const visitorKey = `chatai.widget.${options.assistantId}.visitor`;
86
901
  const conversationKey = `chatai.widget.${options.assistantId}.conversation`;
87
902
  const listeners = /* @__PURE__ */ new Set();
88
- let state = { status: "loading", messages: [] };
903
+ let state = { status: "loading", messages: [], voice: IDLE_VOICE };
904
+ const voiceMedia = options.voiceMedia === void 0 ? browserVoiceMedia() : options.voiceMedia;
905
+ let voiceSession = null;
906
+ let voiceBase = 0;
907
+ let voiceUnavailable = false;
908
+ let removePageHide = null;
89
909
  const origin = () => resolveApiUrl(options.apiUrl);
90
910
  const emit = () => listeners.forEach((listener) => listener(state));
91
911
  const setState = (next) => {
@@ -128,6 +948,91 @@ function createWidgetController(options) {
128
948
  }
129
949
  return body.signature;
130
950
  };
951
+ const requestHeaders = async (vid) => {
952
+ const headers = { "Content-Type": "application/json" };
953
+ const signature = await fetchSignatureHeader(vid);
954
+ if (signature) headers["X-ChatAI-Signature"] = signature;
955
+ return headers;
956
+ };
957
+ const applyVoiceSnapshot = (session, snap) => {
958
+ if (voiceSession !== session) return;
959
+ const active = isVoiceActive(snap.connection);
960
+ if (snap.endReason === "voice_unavailable") voiceUnavailable = true;
961
+ let conversationId = state.conversationId;
962
+ if (snap.conversationId) {
963
+ conversationId = snap.conversationId;
964
+ storage?.setItem(conversationKey, snap.conversationId);
965
+ }
966
+ state = {
967
+ ...state,
968
+ conversationId,
969
+ messages: [
970
+ ...state.messages.slice(0, voiceBase),
971
+ ...voiceMessages(snap.turns, active, snap.ephemeral === false && snap.transcriptSaved === false)
972
+ ],
973
+ voice: {
974
+ connection: snap.connection,
975
+ phase: snap.phase,
976
+ ...snap.error ? { error: snap.error } : {},
977
+ ...snap.ephemeral !== void 0 ? { ephemeral: snap.ephemeral } : {},
978
+ ...snap.transcriptSaved !== void 0 ? { transcriptSaved: snap.transcriptSaved } : {},
979
+ ...snap.recording ? { recording: true } : {},
980
+ ...snap.notice ? { notice: snap.notice } : {},
981
+ ...snap.mock ? { mock: true } : {}
982
+ }
983
+ };
984
+ if (!active) {
985
+ removePageHide?.();
986
+ removePageHide = null;
987
+ }
988
+ emit();
989
+ };
990
+ const watchPageHide = (session) => {
991
+ if (typeof window === "undefined") return;
992
+ const onPageHide = () => void session.end("close_requested", { keepalive: true });
993
+ window.addEventListener("pagehide", onPageHide);
994
+ removePageHide = () => window.removeEventListener("pagehide", onPageHide);
995
+ };
996
+ const consentRequired = () => Boolean(state.config?.voice?.enabled && state.config.voice.recording?.consentRequired);
997
+ const beginVoice = async (recordingConsent) => {
998
+ if (!voiceMedia) {
999
+ state = {
1000
+ ...state,
1001
+ voice: {
1002
+ connection: "failed",
1003
+ phase: "error",
1004
+ error: { code: "unsupported", message: VOICE_ERROR_MESSAGES.unsupported }
1005
+ }
1006
+ };
1007
+ emit();
1008
+ return;
1009
+ }
1010
+ let apiUrl;
1011
+ try {
1012
+ apiUrl = origin();
1013
+ } catch (error) {
1014
+ setState({ ...state, error: humanizeNetworkError(error, "Unable to start voice.") });
1015
+ return;
1016
+ }
1017
+ const vid = visitorId();
1018
+ voiceBase = state.messages.length;
1019
+ const session = createVoiceSession({
1020
+ apiUrl,
1021
+ assistantId: options.assistantId,
1022
+ visitorId: vid,
1023
+ conversationId: state.conversationId,
1024
+ history: clientHistory(state.messages),
1025
+ recordingConsent,
1026
+ fetch: fetcher,
1027
+ media: voiceMedia,
1028
+ headers: () => requestHeaders(vid),
1029
+ onChange: (snap) => applyVoiceSnapshot(session, snap)
1030
+ });
1031
+ voiceSession = session;
1032
+ state = { ...state, error: void 0 };
1033
+ watchPageHide(session);
1034
+ await session.start();
1035
+ };
131
1036
  return {
132
1037
  getState() {
133
1038
  return state;
@@ -161,9 +1066,10 @@ function createWidgetController(options) {
161
1066
  },
162
1067
  async send(message) {
163
1068
  const content = message.trim();
164
- if (!content || state.status === "streaming") return;
1069
+ if (!content || state.status === "streaming" || isVoiceActive(state.voice.connection)) return;
165
1070
  const userMessage = { role: "user", content };
166
1071
  let assistantMessage = { role: "assistant", content: "" };
1072
+ const history = clientHistory(state.messages);
167
1073
  setState({
168
1074
  ...state,
169
1075
  status: "streaming",
@@ -173,11 +1079,7 @@ function createWidgetController(options) {
173
1079
  try {
174
1080
  const apiUrl = origin();
175
1081
  const vid = visitorId();
176
- const headers = { "Content-Type": "application/json" };
177
- const signature = await fetchSignatureHeader(vid);
178
- if (signature) {
179
- headers["X-ChatAI-Signature"] = signature;
180
- }
1082
+ const headers = await requestHeaders(vid);
181
1083
  const response = await fetcher(`${apiUrl}/api/v1/chat`, {
182
1084
  method: "POST",
183
1085
  headers,
@@ -186,7 +1088,9 @@ function createWidgetController(options) {
186
1088
  message: content,
187
1089
  conversationId: state.conversationId,
188
1090
  visitorId: vid,
189
- source: "widget"
1091
+ source: "widget",
1092
+ ...history.length ? { history } : {},
1093
+ ...voiceUnavailable ? { voiceUnavailable: true } : {}
190
1094
  })
191
1095
  });
192
1096
  if (!response.ok || !response.body) {
@@ -230,11 +1134,7 @@ function createWidgetController(options) {
230
1134
  try {
231
1135
  const apiUrl = origin();
232
1136
  const vid = visitorId();
233
- const headers = { "Content-Type": "application/json" };
234
- const signature = await fetchSignatureHeader(vid);
235
- if (signature) {
236
- headers["X-ChatAI-Signature"] = signature;
237
- }
1137
+ const headers = await requestHeaders(vid);
238
1138
  const response = await fetcher(`${apiUrl}/api/v1/feedback`, {
239
1139
  method: "POST",
240
1140
  headers,
@@ -259,14 +1159,82 @@ function createWidgetController(options) {
259
1159
  throw error;
260
1160
  }
261
1161
  },
1162
+ /** Voice can be offered: enabled for this assistant and supported by this browser. */
1163
+ voiceAvailable() {
1164
+ return Boolean(state.config?.voice?.enabled);
1165
+ },
1166
+ voiceSupported() {
1167
+ return voiceMedia !== null;
1168
+ },
1169
+ /** Voice sessions are recorded, so starting one shows the disclosure first. */
1170
+ voiceConsentRequired() {
1171
+ return consentRequired();
1172
+ },
1173
+ /**
1174
+ * Start Voice. When sessions are recorded this only opens the disclosure;
1175
+ * the mic and the session wait for `acceptRecordingConsent()`.
1176
+ */
1177
+ async startVoice() {
1178
+ if (!state.config?.voice?.enabled) return;
1179
+ if (isVoiceActive(state.voice.connection) || state.status === "streaming") return;
1180
+ if (consentRequired()) {
1181
+ setState({ ...state, error: void 0, voice: { ...IDLE_VOICE, consentPending: true } });
1182
+ return;
1183
+ }
1184
+ await beginVoice(false);
1185
+ },
1186
+ async acceptRecordingConsent() {
1187
+ if (!state.voice.consentPending) return;
1188
+ state = { ...state, voice: IDLE_VOICE };
1189
+ await beginVoice(true);
1190
+ },
1191
+ /** Back to text chat; nothing was requested or started. */
1192
+ declineRecordingConsent() {
1193
+ if (!state.voice.consentPending) return;
1194
+ setState({ ...state, voice: IDLE_VOICE });
1195
+ },
1196
+ async endVoice() {
1197
+ await voiceSession?.end("close_requested");
1198
+ },
1199
+ /** Live mic/speaker levels for the waveform; zeros when Voice is off. */
1200
+ voiceLevels() {
1201
+ return voiceSession?.levels() ?? { input: 0, output: 0 };
1202
+ },
1203
+ /** Clears a Voice error or end notice so the visitor can return to text or try again. */
1204
+ dismissVoiceError() {
1205
+ if (isVoiceActive(state.voice.connection)) return;
1206
+ setState({ ...state, voice: IDLE_VOICE });
1207
+ },
262
1208
  destroy() {
1209
+ const session = voiceSession;
1210
+ voiceSession = null;
1211
+ removePageHide?.();
1212
+ removePageHide = null;
1213
+ void session?.end("close_requested", { keepalive: true });
263
1214
  listeners.clear();
264
1215
  }
265
1216
  };
266
1217
  }
267
1218
  export {
1219
+ BARGE_IN_MIN_WORDS,
1220
+ CONTROL_HEALTH_DEFAULTS,
1221
+ VOICE_END_NOTICES,
1222
+ VOICE_ERROR_MESSAGES,
1223
+ VOICE_PHASE_LABELS,
1224
+ browserVoiceMedia,
1225
+ classifyHeartbeatResponse,
1226
+ clientHistory,
1227
+ createControlHealthMonitor,
268
1228
  createSseParser,
1229
+ createVoiceSession,
1230
+ createVoiceTranscript,
269
1231
  createWidgetController,
270
- resolveApiUrl
1232
+ deriveVoicePhase,
1233
+ initialControlHealth,
1234
+ isControlMuted,
1235
+ isVoiceActive,
1236
+ reduceControlHealth,
1237
+ resolveApiUrl,
1238
+ visitorEndReason
271
1239
  };
272
1240
  //# sourceMappingURL=index.js.map