@craftedxp/voice-js 0.10.0 → 0.12.0

package/dist/browser.mjs

@@ -9,10 +9,11 @@ import {
   normalizeConfig,
   parseIncomingCall,
   startTextSession
-} from "./chunk-3BYNC25N.mjs";
+} from "./chunk-C2U6V5NI.mjs";
 import {
   joinRoom
-} from "./chunk-LV7JGPYW.mjs";
+} from "./chunk-VSY43NGD.mjs";
+import "./chunk-OS2GZAR7.mjs";
 
 // src/browser.ts
 function configureVoiceClient2(config) {

package/dist/browser.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["// Browser entry — `import { configureVoiceClient } from '@craftedxp/voice-js'`\n//\n// @deprecated Import from '@craftedxp/voice-js/assistant', '@craftedxp/voice-js/room',\n// or '@craftedxp/voice-js/transcribe' instead. This barrel will be removed in 1.0.\n//\n// Backwards-compatible re-export barrel. The factory returned here also\n// exposes `joinRoom` as a method so consumers who call `voice.joinRoom()`\n// keep working unchanged.\n//\n// Pre-injects:\n//   - native `WebSocket` (globalThis.WebSocket)\n//   - browser audio adapter (AudioContext + AudioWorklet + getUserMedia)\n//\n// Electron renderer + browser tabs both pick this entry via the\n// `browser` condition in package.json `exports`.\n\nimport { configureVoiceClient as configureAssistant } from './assistant'\nimport { joinRoom as joinRoomImpl } from './room'\nimport { normalizeConfig } from './config'\nimport type { VoiceClientConfig, VoiceClientFactory } from './config'\nimport type { JoinRoomOptions, RoomSession } from './room'\n\n/**\n * One-time SDK setup. Returns a factory you call `startCall` on for\n * every voice call. Also exposes `joinRoom` as a method for multi-party\n * room joining (back-compat; prefer `@craftedxp/voice-js/room` for new code).\n */\nexport function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory & {\n  joinRoom: (opts: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>\n} {\n  const normalized = normalizeConfig(config)\n  const factory = configureAssistant(normalized)\n  return {\n    ...factory,\n    // Re-compose joinRoom onto the factory so barrel consumers who call\n    // `voice.joinRoom(...)` keep working unchanged.\n    joinRoom: (opts: Omit<JoinRoomOptions, 'apiBase'>) =>\n      joinRoomImpl({ apiBase: normalized.apiBase, ...opts }),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public re-exports — assistant surface (types + advanced primitives).\n// ---------------------------------------------------------------------------\n\nexport type {\n  Call,\n  ClientTool,\n  ClientToolMap,\n  FetchToken,\n  FetchTokenArgs,\n  FetchTokenResult,\n  StartCallOptions,\n  VoiceClientConfig,\n  VoiceClientFactory,\n} from './config'\n\nexport type {\n  CallEndEvent,\n  CallEndReason,\n  CallError,\n  CallErrorCode,\n  CallState,\n  TranscriptEntry,\n  VolumeEvent,\n} from './protocol'\n\n// Low-level primitives — exposed for advanced consumers who want to\n// drive just the mic, just the playback, or build a custom transport on\n// top of the protocol decoder. Most users should stick to\n// `configureVoiceClient().startCall()`.\nexport { createAudioCapture } from './AudioCapture'\nexport type { CaptureController, CaptureOptions, OnChunk, OnError, OnVolume } from './AudioCapture'\n\nexport { createAudioPlayback } from './AudioPlayback'\nexport type { PlaybackController, PlaybackOptions, OnAgentSpeakingChange } from './AudioPlayback'\n\nexport { createReconnectingWebSocket } from './ReconnectingWebSocket'\nexport type {\n  ReconnectingWebSocket,\n  RWSEvent,\n  RWSOptions,\n  WebSocketFactory,\n  WebSocketLike,\n} from './ReconnectingWebSocket'\n\nexport { handleServerMessage, createProtocolState, buildWsUrl } from './protocol'\nexport type { ProtocolState, ProtocolCallbacks, ServerMessage } from './protocol'\n\n// Multi-party room (Phase 7 video) surface. Exposed as a method on the\n// factory (`voice.joinRoom({...})`) and re-exported here as a free\n// function for consumers that prefer not to instantiate a full factory\n// just to attend a room as a guest.\nexport { joinRoom } from './room'\nexport type {\n  JoinRoomOptions,\n  RoomEventName,\n  RoomEventPayloads,\n  RoomParticipantInfo,\n  RoomSession,\n} from './room'\nexport type { SystemMessage, TranscriptMessage, AnalysisMessage } from './roomProtocol'\n\nexport { parseIncomingCall } from './incomingCall'\nexport type { IncomingCallPayload } from './incomingCall'\n\nexport { startTextSession } from './textSession'\nexport type { ChatEvent, StartTextSessionOpts, TextSession } from './textSession'\n"],"mappings":";;;;;;;;;;;;;;;;;AA2BO,SAASA,sBAAqB,QAEnC;AACA,QAAM,aAAa,gBAAgB,MAAM;AACzC,QAAM,UAAU,qBAAmB,UAAU;AAC7C,SAAO;AAAA,IACL,GAAG;AAAA;AAAA;AAAA,IAGH,UAAU,CAAC,SACT,SAAa,EAAE,SAAS,WAAW,SAAS,GAAG,KAAK,CAAC;AAAA,EACzD;AACF;","names":["configureVoiceClient"]}
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["// Browser entry — `import { configureVoiceClient } from '@craftedxp/voice-js'`\n//\n// @deprecated Import from '@craftedxp/voice-js/assistant', '@craftedxp/voice-js/room',\n// or '@craftedxp/voice-js/transcribe' instead. This barrel will be removed in 1.0.\n//\n// Backwards-compatible re-export barrel. The factory returned here also\n// exposes `joinRoom` as a method so consumers who call `voice.joinRoom()`\n// keep working unchanged.\n//\n// Pre-injects:\n//   - native `WebSocket` (globalThis.WebSocket)\n//   - browser audio adapter (AudioContext + AudioWorklet + getUserMedia)\n//\n// Electron renderer + browser tabs both pick this entry via the\n// `browser` condition in package.json `exports`.\n\nimport { configureVoiceClient as configureAssistant } from './assistant'\nimport { joinRoom as joinRoomImpl } from './room'\nimport { normalizeConfig } from './config'\nimport type { VoiceClientConfig, VoiceClientFactory } from './config'\nimport type { JoinRoomOptions, RoomSession } from './room'\n\n/**\n * One-time SDK setup. Returns a factory you call `startCall` on for\n * every voice call. Also exposes `joinRoom` as a method for multi-party\n * room joining (back-compat; prefer `@craftedxp/voice-js/room` for new code).\n */\nexport function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory & {\n  joinRoom: (opts: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>\n} {\n  const normalized = normalizeConfig(config)\n  const factory = configureAssistant(normalized)\n  return {\n    ...factory,\n    // Re-compose joinRoom onto the factory so barrel consumers who call\n    // `voice.joinRoom(...)` keep working unchanged.\n    joinRoom: (opts: Omit<JoinRoomOptions, 'apiBase'>) =>\n      joinRoomImpl({ apiBase: normalized.apiBase, ...opts }),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public re-exports — assistant surface (types + advanced primitives).\n// ---------------------------------------------------------------------------\n\nexport type {\n  Call,\n  CallTransport,\n  ClientTool,\n  ClientToolMap,\n  FetchToken,\n  FetchTokenArgs,\n  FetchTokenResult,\n  StartCallOptions,\n  TransportChangeEvent,\n  VoiceClientConfig,\n  VoiceClientFactory,\n} from './config'\n\nexport type {\n  CallEndEvent,\n  CallEndReason,\n  CallError,\n  CallErrorCode,\n  CallState,\n  TranscriptEntry,\n  VolumeEvent,\n} from './protocol'\n\n// Low-level primitives — exposed for advanced consumers who want to\n// drive just the mic, just the playback, or build a custom transport on\n// top of the protocol decoder. Most users should stick to\n// `configureVoiceClient().startCall()`.\nexport { createAudioCapture } from './AudioCapture'\nexport type { CaptureController, CaptureOptions, OnChunk, OnError, OnVolume } from './AudioCapture'\n\nexport { createAudioPlayback } from './AudioPlayback'\nexport type { PlaybackController, PlaybackOptions, OnAgentSpeakingChange } from './AudioPlayback'\n\nexport { createReconnectingWebSocket } from './ReconnectingWebSocket'\nexport type {\n  ReconnectingWebSocket,\n  RWSEvent,\n  RWSOptions,\n  WebSocketFactory,\n  WebSocketLike,\n} from './ReconnectingWebSocket'\n\nexport { handleServerMessage, createProtocolState, buildWsUrl } from './protocol'\nexport type { ProtocolState, ProtocolCallbacks, ServerMessage } from './protocol'\n\n// Multi-party room (Phase 7 video) surface. Exposed as a method on the\n// factory (`voice.joinRoom({...})`) and re-exported here as a free\n// function for consumers that prefer not to instantiate a full factory\n// just to attend a room as a guest.\nexport { joinRoom } from './room'\nexport type {\n  JoinRoomOptions,\n  RoomEventName,\n  RoomEventPayloads,\n  RoomParticipantInfo,\n  RoomSession,\n} from './room'\nexport type { SystemMessage, TranscriptMessage, AnalysisMessage } from './roomProtocol'\n\nexport { parseIncomingCall } from './incomingCall'\nexport type { IncomingCallPayload } from './incomingCall'\n\nexport { startTextSession } from './textSession'\nexport type { ChatEvent, StartTextSessionOpts, TextSession } from './textSession'\n"],"mappings":";;;;;;;;;;;;;;;;;;AA2BO,SAASA,sBAAqB,QAEnC;AACA,QAAM,aAAa,gBAAgB,MAAM;AACzC,QAAM,UAAU,qBAAmB,UAAU;AAC7C,SAAO;AAAA,IACL,GAAG;AAAA;AAAA;AAAA,IAGH,UAAU,CAAC,SACT,SAAa,EAAE,SAAS,WAAW,SAAS,GAAG,KAAK,CAAC;AAAA,EACzD;AACF;","names":["configureVoiceClient"]}

package/dist/{chunk-3BYNC25N.mjs → chunk-C2U6V5NI.mjs}

@@ -1,3 +1,7 @@
+import {
+  loadLiveKit
+} from "./chunk-OS2GZAR7.mjs";
+
 // src/config.ts
 function normalizeConfig(config) {
   if (!config) throw new Error("configureVoiceClient: config is required");
@@ -478,7 +482,8 @@ function buildWsUrl(args) {
   const base = new URL(args.apiBase);
   const proto = base.protocol === "https:" ? "wss:" : "ws:";
   const bargeQS = args.bargeIn === false ? "&barge=off" : "";
-  return `${proto}//${base.host}/v1/agents/${encodeURIComponent(args.agentId)}/call?token=${encodeURIComponent(args.token)}${bargeQS}`;
+  const mediaQS = args.media === "livekit" ? "&media=livekit" : "";
+  return `${proto}//${base.host}/v1/agents/${encodeURIComponent(args.agentId)}/call?token=${encodeURIComponent(args.token)}${bargeQS}${mediaQS}`;
 }
 
 // src/clientTools.ts
@@ -632,7 +637,75 @@ var createClientMarksBuffer = (args) => {
   };
 };
 
+// src/livekit/createLiveKitMedia.ts
+var toError = (e) => e instanceof Error ? e : new Error(String(e));
+function createLiveKitMedia(lk, opts = {}) {
+  let room = null;
+  let audioEl = null;
+  let muted = false;
+  const attach = (track) => {
+    if (track.kind !== lk.Track.Kind.Audio) return;
+    if (typeof document === "undefined") return;
+    if (!audioEl) {
+      audioEl = document.createElement("audio");
+      audioEl.autoplay = true;
+      audioEl.style.display = "none";
+      document.body.appendChild(audioEl);
+    }
+    track.attach(audioEl);
+  };
+  return {
+    connect: async (url, token) => {
+      const r = new lk.Room({ adaptiveStream: false, dynacast: false });
+      room = r;
+      r.on(lk.RoomEvent.TrackSubscribed, (track) => attach(track));
+      await r.connect(url, token);
+      if (room !== r) {
+        return;
+      }
+      await r.localParticipant.setMicrophoneEnabled(!muted);
+      if (room !== r) {
+        return;
+      }
+      try {
+        await r.startAudio();
+      } catch {
+      }
+    },
+    disconnect: () => {
+      const r = room;
+      room = null;
+      if (r) void r.disconnect().catch(() => void 0);
+      audioEl?.remove();
+      audioEl = null;
+    },
+    setMuted: (m) => {
+      muted = m;
+      const r = room;
+      if (!r) return;
+      void r.localParticipant.setMicrophoneEnabled(!m).catch((e) => opts.onError?.(toError(e)));
+    }
+  };
+}
+
 // src/VoiceClient.ts
+var parseMediaFrame = (raw) => {
+  if (!raw.includes('"livekit_')) return null;
+  try {
+    const m = JSON.parse(raw);
+    if (m.type === "livekit_join" && typeof m.url === "string" && typeof m.token === "string") {
+      return { type: "livekit_join", url: m.url, token: m.token };
+    }
+    if (m.type === "livekit_fallback") {
+      return {
+        type: "livekit_fallback",
+        reason: typeof m.reason === "string" ? m.reason : void 0
+      };
+    }
+  } catch {
+  }
+  return null;
+};
 var BrowserVoiceClient = class {
   constructor(args) {
     this.rws = null;
@@ -644,6 +717,9 @@ var BrowserVoiceClient = class {
     this.startedAt = null;
     this.endedFired = false;
     this.lastError = null;
+    this.mediaMode = "ws";
+    this.lkMedia = null;
+    this.lkJoinSeen = false;
     this.end = () => {
       this.teardown("user_hangup");
     };
@@ -651,11 +727,73 @@ var BrowserVoiceClient = class {
       if (this.muted) return;
       this.muted = true;
       this.capture?.mute(true);
+      this.lkMedia?.setMuted(true);
     };
     this.unmute = () => {
       if (!this.muted) return;
       this.muted = false;
       this.capture?.mute(false);
+      this.lkMedia?.setMuted(false);
+    };
+    this.ensureWsPlayback = async () => {
+      if (this.playback) return;
+      const createPlayback = this.args.audio?.createPlayback ?? createAudioPlayback;
+      this.playback = createPlayback({
+        onVolume: (v) => {
+          this.outputVolume = v;
+          this.args.options.onVolume?.({ input: this.inputVolume, output: v });
+        }
+      });
+      try {
+        await this.playback.resume();
+      } catch {
+      }
+    };
+    // ---------------------------------------------------------------
+    // LiveKit media lifecycle (phase 35)
+    // ---------------------------------------------------------------
+    this.joinLiveKit = async (url, token) => {
+      this.lkJoinSeen = true;
+      const lk = this.args.media?.lk;
+      if (!lk) {
+        this.fallbackToWs("livekit-client unavailable");
+        return;
+      }
+      const media = createLiveKitMedia(lk, {
+        onError: (e) => this.emitError({ code: "mic_start_failed", message: e.message })
+      });
+      this.lkMedia = media;
+      if (this.muted) media.setMuted(true);
+      try {
+        await media.connect(url, token);
+        if (this.lkMedia !== media) return;
+        this.mediaMode = "livekit";
+        this.rws?.send(JSON.stringify({ type: "livekit_ready" }));
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        media.disconnect();
+        if (this.lkMedia === media) this.lkMedia = null;
+        this.rws?.send(JSON.stringify({ type: "livekit_failed", reason }));
+        this.fallbackToWs(reason);
+      }
+    };
+    // Idempotent: whichever side gives up first (client join error, server
+    // livekit_fallback, `connected` without a join) lands here once.
+    this.fallbackToWs = (reason) => {
+      if (this.mediaMode === "ws") return;
+      this.mediaMode = "ws";
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
+      void this.ensureWsPlayback();
+      void this.startCapture();
+      this.args.options.onTransportChange?.({ requested: "livekit", actual: "ws", reason });
+    };
+    this.resetLiveKitForReconnect = () => {
+      if (this.args.media?.kind !== "livekit") return;
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
+      this.lkJoinSeen = false;
+      this.mediaMode = "livekit-pending";
     };
     // ---------------------------------------------------------------
     // Internal
@@ -676,17 +814,27 @@ var BrowserVoiceClient = class {
     this.handleSocketEvent = (ev) => {
       switch (ev.type) {
         case "open":
-          void this.startCapture();
+          if (this.mediaMode === "ws") void this.startCapture();
           break;
         case "reconnected":
           this.proto.transcript = [];
           this.proto.agentBubbleId = null;
           this.args.options.onTranscript?.(this.proto.transcript);
-          void this.startCapture();
+          this.resetLiveKitForReconnect();
+          if (this.mediaMode === "ws") void this.startCapture();
           this.setState("listening");
           break;
         case "message":
           if (typeof ev.data === "string") {
+            const media = parseMediaFrame(ev.data);
+            if (media?.type === "livekit_join") {
+              if (this.mediaMode === "livekit-pending") void this.joinLiveKit(media.url, media.token);
+              break;
+            }
+            if (media?.type === "livekit_fallback") {
+              this.fallbackToWs(media.reason ?? "server_fallback");
+              break;
+            }
             handleServerMessage(ev.data, this.proto, {
               onState: this.setState,
               onTranscript: (entries) => this.args.options.onTranscript?.(entries),
@@ -703,7 +851,12 @@ var BrowserVoiceClient = class {
                 if (typeof seq === "number") this.marks.onAgentTurnEnd(seq);
               },
               onCallEnd: (reason) => this.teardown(reason),
-              onConnected: () => this.sendClientToolsRegister(),
+              onConnected: () => {
+                if (this.mediaMode === "livekit-pending" && !this.lkJoinSeen) {
+                  this.fallbackToWs("server_declined");
+                }
+                this.sendClientToolsRegister();
+              },
               onClientToolCall: (frame) => dispatchClientToolCall(
                 (f) => this.rws?.send(JSON.stringify(f)),
                 this.args.options.clientTools ?? {},
@@ -711,6 +864,8 @@ var BrowserVoiceClient = class {
               )
             });
           } else {
+            if (this.mediaMode === "livekit") break;
+            if (!this.playback) void this.ensureWsPlayback();
             this.marks.markFirstAudibleOutput();
             this.playback?.enqueue(ev.data);
           }
@@ -728,7 +883,8 @@ var BrowserVoiceClient = class {
     };
     this.startCapture = async () => {
       if (this.capture?.isCapturing()) return;
-      this.capture = createAudioCapture({
+      const createCapture = this.args.audio?.createCapture ?? createAudioCapture;
+      this.capture = createCapture({
         onChunk: (pcm) => {
           this.marks.markFirstOutboundAudio();
           this.rws?.send(pcm);
@@ -757,6 +913,8 @@ var BrowserVoiceClient = class {
       }
       this.capture?.stop();
       this.capture = null;
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
       this.playback?.close();
       this.playback = null;
       try {
@@ -809,28 +967,17 @@ var BrowserVoiceClient = class {
   async start() {
     this.setState("connecting");
     this.startedAt = Date.now();
+    this.mediaMode = this.args.media?.kind === "livekit" ? "livekit-pending" : "ws";
     const url = buildWsUrl({
       apiBase: this.args.config.apiBase,
       agentId: this.args.options.agentId,
       token: this.args.token,
-      bargeIn: this.args.options.bargeIn
-    });
-    this.playback = createAudioPlayback({
-      onVolume: (v) => {
-        this.outputVolume = v;
-        this.args.options.onVolume?.({ input: this.inputVolume, output: v });
-      }
+      bargeIn: this.args.options.bargeIn,
+      media: this.mediaMode === "ws" ? void 0 : "livekit"
     });
-    try {
-      await this.playback.resume();
-    } catch {
-    }
+    if (this.mediaMode === "ws") await this.ensureWsPlayback();
     this.rws = createReconnectingWebSocket(
-      {
-        url,
-        wsFactory: this.args.wsFactory,
-        maxRetries: 3
-      },
+      { url, wsFactory: this.args.wsFactory, maxRetries: 3 },
       (ev) => this.handleSocketEvent(ev)
     );
   }
@@ -1111,7 +1258,7 @@ var parseIncomingCall = (raw) => {
   if (typeof p.agentId !== "string" || p.agentId.length === 0) {
     throw new Error("parseIncomingCall: missing `agentId`");
   }
-  const transport = p.transport === "webrtc" ? "webrtc" : "ws";
+  const transport = p.transport === "webrtc" ? "webrtc" : p.transport === "livekit" ? "livekit" : "ws";
   const out = { token: p.token, agentId: p.agentId, transport };
   if (transport === "webrtc" && typeof p.webrtcGatewayBase === "string") {
     out.webrtcGatewayBase = p.webrtcGatewayBase;
@@ -1168,6 +1315,27 @@ var AssistantVoiceFactory = class {
           clientTools: options.clientTools
         });
       }
+      if (resolved.transport === "livekit") {
+        let lk = null;
+        let loadError = "";
+        try {
+          lk = await loadLiveKit("transport 'livekit'");
+        } catch (e) {
+          loadError = e instanceof Error ? e.message : String(e);
+        }
+        if (!lk) {
+          options.onTransportChange?.({ requested: "livekit", actual: "ws", reason: loadError });
+        }
+        const client2 = new BrowserVoiceClient({
+          config: this.config,
+          options: { ...options, context, metadata },
+          token: resolved.token,
+          wsFactory: browserWsFactory,
+          media: lk ? { kind: "livekit", lk } : void 0
+        });
+        await client2.start();
+        return client2;
+      }
       const client = new BrowserVoiceClient({
         config: this.config,
         // Carry merged context/metadata through to startCall so server can
@@ -1205,4 +1373,4 @@ export {
   parseIncomingCall,
   configureVoiceClient
 };
-//# sourceMappingURL=chunk-3BYNC25N.mjs.map
+//# sourceMappingURL=chunk-C2U6V5NI.mjs.map