@craftedxp/voice-js 0.4.1 → 0.5.4

package/dist/node.d.mts

@@ -1,3 +1,5 @@
+import { RemoteTrack, LocalVideoTrack } from 'livekit-client';
+
 interface ClientTool {
     description: string;
     parameters: Record<string, unknown>;
@@ -79,6 +81,145 @@ interface BuildWsUrlArgs {
 }
 declare function buildWsUrl(args: BuildWsUrlArgs): string;
 
+type SystemMessage = {
+    kind: 'room.starting';
+    at: string;
+} | {
+    kind: 'room.ending.soon';
+    minutesRemaining: 5 | 1;
+} | {
+    kind: 'room.ended';
+    reason: 'duration_reached' | 'manual' | 'empty';
+} | {
+    kind: 'role.promoted';
+    participantId: string;
+    name: string;
+} | {
+    kind: 'role.demoted';
+    participantId: string;
+    name: string;
+} | {
+    kind: 'participant.removed';
+    participantId: string;
+    name: string;
+    byHost?: string;
+} | {
+    kind: 'notetaker.connected';
+} | {
+    kind: 'notetaker.disconnected';
+} | {
+    kind: 'notetaker.partial_degraded';
+    participantId: string;
+};
+type TranscriptMessage = {
+    kind: 'partial';
+    participantId: string;
+    speakerName: string;
+    text: string;
+    startedAt: string;
+};
+
+interface JoinRoomOptions {
+    /** Full HTTPS URL of the Voissia server. Same shape as VoiceClientConfig.apiBase. */
+    apiBase: string;
+    /** Server-generated room id (`rm_…`). */
+    roomId: string;
+    /** Shared room join token from the invite link. Mints a fresh participant each call. */
+    joinCode: string;
+    /** Display name the joiner registers under for this participant. */
+    name: string;
+}
+interface RoomParticipantInfo {
+    /** Stable participant id (`p_…`); strips any `guest:` LiveKit identity prefix. */
+    participantId: string;
+    /** Display name as the worker registered it; may be empty. */
+    name: string;
+}
+type RoomTrackKind = 'audio' | 'video';
+/** What a track is — lets consumers tell a camera apart from a screen share
+ *  (a participant can publish both at once). Mirrors livekit `Track.Source`. */
+type RoomTrackSource = 'camera' | 'microphone' | 'screen_share' | 'screen_share_audio' | 'unknown';
+interface RoomTrackEvent {
+    /** Stable participant id (`p_…`); `guest:` prefix stripped. */
+    participantId: string;
+    kind: RoomTrackKind;
+    /** Distinguishes camera vs screen_share so each can render as its own tile. */
+    source: RoomTrackSource;
+    /** livekit-client track — call `.attach(el)` / `.detach()` to render. */
+    track: RemoteTrack;
+}
+type RoomEventName = 'participant.joined' | 'participant.left' | 'transcript.partial' | 'transcript.final' | 'system.message' | 'room.ended' | 'track.subscribed' | 'track.unsubscribed' | 'active.speakers';
+interface RoomEventPayloads {
+    'participant.joined': RoomParticipantInfo;
+    'participant.left': RoomParticipantInfo;
+    'transcript.partial': TranscriptMessage;
+    /**
+     * Reserved — the worker currently emits only partials over the transcript
+     * topic. Final-utterance events will land in Phase 8 once the worker
+     * publishes a `final` kind; the SDK keeps the slot reserved so consumers
+     * can register handlers today.
+     */
+    'transcript.final': {
+        participantId: string;
+        speakerName: string;
+        text: string;
+        startedAt: string;
+    };
+    'system.message': SystemMessage;
+    'room.ended': undefined;
+    'track.subscribed': RoomTrackEvent;
+    'track.unsubscribed': RoomTrackEvent;
+    /** participantIds currently speaking (drives an active-speaker UI). */
+    'active.speakers': string[];
+}
+type Handler<E extends RoomEventName> = (payload: RoomEventPayloads[E]) => void;
+interface RoomSession {
+    /** This session's own stable participant id (`p_…`). Useful to filter
+     *  yourself out of `active.speakers`, which includes the local participant. */
+    readonly participantId: string;
+    /** Snapshot of the remote participants currently connected. */
+    readonly participants: RoomParticipantInfo[];
+    /** Subscribe to a typed event. No unsubscribe surface yet (mirrors `Call.onX`). */
+    on<E extends RoomEventName>(event: E, handler: Handler<E>): void;
+    /** Publish the local mic track. Resolves once the track is live on LiveKit. */
+    publishMic(): Promise<void>;
+    /** Publish the local camera track. */
+    publishCamera(): Promise<void>;
+    /** Mid-call mute/unmute of the local mic. */
+    setMicEnabled(on: boolean): Promise<void>;
+    /** Mid-call camera on/off. */
+    setCameraEnabled(on: boolean): Promise<void>;
+    /** Current local mic state (for toggle UI). */
+    isMicEnabled(): boolean;
+    /** Current local camera state (for toggle UI). */
+    isCameraEnabled(): boolean;
+    /** The local camera track for self-view, or null before publishCamera resolves. */
+    getLocalCameraTrack(): LocalVideoTrack | null;
+    /**
+     * Remote tracks already subscribed at this moment. A late joiner misses the
+     * live `track.subscribed` events for tracks published before it connected
+     * (LiveKit delivers them during `connect`, before consumer listeners attach).
+     * Call this right after registering `track.subscribed` to backfill them.
+     */
+    getRemoteTracks(): RoomTrackEvent[];
+    /**
+     * Start/stop sharing the screen (via `getDisplayMedia`). Pass `{ audio: true }`
+     * to also capture shared/system audio where the browser allows it (Chrome:
+     * tab or system audio; macOS Chrome is tab-audio only; Safari/Firefox don't
+     * capture share audio). Publishes a `screen_share` video track (+ optional
+     * `screen_share_audio`); remote peers receive them via `track.subscribed`.
+     */
+    setScreenShareEnabled(on: boolean, opts?: {
+        audio?: boolean;
+    }): Promise<void>;
+    /** Current local screen-share state (for toggle UI). */
+    isScreenShareEnabled(): boolean;
+    /** The local screen-share video track for self-preview, or null when off. */
+    getLocalScreenTrack(): LocalVideoTrack | null;
+    /** Disconnect from LiveKit. Idempotent. Triggers `room.ended` via Disconnected. */
+    leave(): Promise<void>;
+}
+
 interface FetchTokenArgs {
     /** The agent the SDK is about to call. */
     agentId: string;
@@ -228,6 +369,16 @@ interface VoiceClientFactory {
      * don't reject this promise.
      */
     startCall: (options: StartCallOptions) => Promise<Call>;
+    /**
+     * Phase 7 (multi-party rooms). Browser only. Exchange a single-use
+     * joinCode for a LiveKit JWT and connect to the room. The returned
+     * `RoomSession` exposes a typed event surface
+     * (participant.joined / participant.left / transcript.partial /
+     *  transcript.final / system.message / room.ended) plus
+     * publishMic / publishCamera / leave. The Node bundle does NOT
+     * implement this — livekit-client is a browser-only WebRTC client.
+     */
+    joinRoom?: (options: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>;
 }
 
 type RWSEvent = {
@@ -308,6 +459,31 @@ interface NodeVoiceClientFactory {
     startCall: (options: NodeStartCallOptions) => Promise<NodeCall>;
 }
 
+/**
+ * Canonical payload a tenant places in their VoIP/FCM push so an
+ * agent-initiated call can connect. It is the `callTokens.mint` result
+ * (token + transport) plus two optional display fields for the native
+ * incoming-call UI. The host receives the push, runs `parseIncomingCall`,
+ * and on accept passes `token` (+ transport / webrtcGatewayBase) into the
+ * voice client. Web background-wake is best-effort (Web Push); native is
+ * the real target. See docs/sdks.md "Agent-initiated calls".
+ */
+interface IncomingCallPayload {
+    token: string;
+    agentId: string;
+    transport: 'ws' | 'webrtc';
+    webrtcGatewayBase?: string;
+    expiresAt?: number;
+    agentName?: string;
+    agentAvatarUrl?: string;
+}
+/**
+ * Validate + normalise a raw push payload into an IncomingCallPayload.
+ * Throws synchronously on malformed input. Unknown transports fall back to
+ * 'ws'; webrtcGatewayBase is ignored unless transport === 'webrtc'.
+ */
+declare const parseIncomingCall: (raw: unknown) => IncomingCallPayload;
+
 /**
  * One-time SDK setup for Node.js / Electron-main consumers. Returns a
  * factory you call `startCall` on for every voice call. Same shape as
@@ -338,4 +514,4 @@ interface NodeVoiceClientFactory {
  */
 declare function configureVoiceClient(config: VoiceClientConfig): NodeVoiceClientFactory;
 
-export { type Call, type CallEndEvent, type CallEndReason, type CallError, type CallErrorCode, type CallState, type ClientTool, type ClientToolMap, type FetchToken, type FetchTokenArgs, type FetchTokenResult, type NodeCall, type NodeStartCallOptions, type NodeVoiceClientFactory, 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, createProtocolState, createReconnectingWebSocket, handleServerMessage };
+export { type Call, type CallEndEvent, type CallEndReason, type CallError, type CallErrorCode, type CallState, type ClientTool, type ClientToolMap, type FetchToken, type FetchTokenArgs, type FetchTokenResult, type IncomingCallPayload, type NodeCall, type NodeStartCallOptions, type NodeVoiceClientFactory, 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, createProtocolState, createReconnectingWebSocket, handleServerMessage, parseIncomingCall };

package/dist/node.d.ts

@@ -1,3 +1,5 @@
+import { RemoteTrack, LocalVideoTrack } from 'livekit-client'
+
 interface ClientTool {
   description: string
   parameters: Record<string, unknown>
@@ -104,6 +106,166 @@ interface BuildWsUrlArgs {
 }
 declare function buildWsUrl(args: BuildWsUrlArgs): string
 
+type SystemMessage =
+  | {
+      kind: 'room.starting'
+      at: string
+    }
+  | {
+      kind: 'room.ending.soon'
+      minutesRemaining: 5 | 1
+    }
+  | {
+      kind: 'room.ended'
+      reason: 'duration_reached' | 'manual' | 'empty'
+    }
+  | {
+      kind: 'role.promoted'
+      participantId: string
+      name: string
+    }
+  | {
+      kind: 'role.demoted'
+      participantId: string
+      name: string
+    }
+  | {
+      kind: 'participant.removed'
+      participantId: string
+      name: string
+      byHost?: string
+    }
+  | {
+      kind: 'notetaker.connected'
+    }
+  | {
+      kind: 'notetaker.disconnected'
+    }
+  | {
+      kind: 'notetaker.partial_degraded'
+      participantId: string
+    }
+type TranscriptMessage = {
+  kind: 'partial'
+  participantId: string
+  speakerName: string
+  text: string
+  startedAt: string
+}
+
+interface JoinRoomOptions {
+  /** Full HTTPS URL of the Voissia server. Same shape as VoiceClientConfig.apiBase. */
+  apiBase: string
+  /** Server-generated room id (`rm_…`). */
+  roomId: string
+  /** Shared room join token from the invite link. Mints a fresh participant each call. */
+  joinCode: string
+  /** Display name the joiner registers under for this participant. */
+  name: string
+}
+interface RoomParticipantInfo {
+  /** Stable participant id (`p_…`); strips any `guest:` LiveKit identity prefix. */
+  participantId: string
+  /** Display name as the worker registered it; may be empty. */
+  name: string
+}
+type RoomTrackKind = 'audio' | 'video'
+/** What a track is — lets consumers tell a camera apart from a screen share
+ *  (a participant can publish both at once). Mirrors livekit `Track.Source`. */
+type RoomTrackSource = 'camera' | 'microphone' | 'screen_share' | 'screen_share_audio' | 'unknown'
+interface RoomTrackEvent {
+  /** Stable participant id (`p_…`); `guest:` prefix stripped. */
+  participantId: string
+  kind: RoomTrackKind
+  /** Distinguishes camera vs screen_share so each can render as its own tile. */
+  source: RoomTrackSource
+  /** livekit-client track — call `.attach(el)` / `.detach()` to render. */
+  track: RemoteTrack
+}
+type RoomEventName =
+  | 'participant.joined'
+  | 'participant.left'
+  | 'transcript.partial'
+  | 'transcript.final'
+  | 'system.message'
+  | 'room.ended'
+  | 'track.subscribed'
+  | 'track.unsubscribed'
+  | 'active.speakers'
+interface RoomEventPayloads {
+  'participant.joined': RoomParticipantInfo
+  'participant.left': RoomParticipantInfo
+  'transcript.partial': TranscriptMessage
+  /**
+   * Reserved — the worker currently emits only partials over the transcript
+   * topic. Final-utterance events will land in Phase 8 once the worker
+   * publishes a `final` kind; the SDK keeps the slot reserved so consumers
+   * can register handlers today.
+   */
+  'transcript.final': {
+    participantId: string
+    speakerName: string
+    text: string
+    startedAt: string
+  }
+  'system.message': SystemMessage
+  'room.ended': undefined
+  'track.subscribed': RoomTrackEvent
+  'track.unsubscribed': RoomTrackEvent
+  /** participantIds currently speaking (drives an active-speaker UI). */
+  'active.speakers': string[]
+}
+type Handler<E extends RoomEventName> = (payload: RoomEventPayloads[E]) => void
+interface RoomSession {
+  /** This session's own stable participant id (`p_…`). Useful to filter
+   *  yourself out of `active.speakers`, which includes the local participant. */
+  readonly participantId: string
+  /** Snapshot of the remote participants currently connected. */
+  readonly participants: RoomParticipantInfo[]
+  /** Subscribe to a typed event. No unsubscribe surface yet (mirrors `Call.onX`). */
+  on<E extends RoomEventName>(event: E, handler: Handler<E>): void
+  /** Publish the local mic track. Resolves once the track is live on LiveKit. */
+  publishMic(): Promise<void>
+  /** Publish the local camera track. */
+  publishCamera(): Promise<void>
+  /** Mid-call mute/unmute of the local mic. */
+  setMicEnabled(on: boolean): Promise<void>
+  /** Mid-call camera on/off. */
+  setCameraEnabled(on: boolean): Promise<void>
+  /** Current local mic state (for toggle UI). */
+  isMicEnabled(): boolean
+  /** Current local camera state (for toggle UI). */
+  isCameraEnabled(): boolean
+  /** The local camera track for self-view, or null before publishCamera resolves. */
+  getLocalCameraTrack(): LocalVideoTrack | null
+  /**
+   * Remote tracks already subscribed at this moment. A late joiner misses the
+   * live `track.subscribed` events for tracks published before it connected
+   * (LiveKit delivers them during `connect`, before consumer listeners attach).
+   * Call this right after registering `track.subscribed` to backfill them.
+   */
+  getRemoteTracks(): RoomTrackEvent[]
+  /**
+   * Start/stop sharing the screen (via `getDisplayMedia`). Pass `{ audio: true }`
+   * to also capture shared/system audio where the browser allows it (Chrome:
+   * tab or system audio; macOS Chrome is tab-audio only; Safari/Firefox don't
+   * capture share audio). Publishes a `screen_share` video track (+ optional
+   * `screen_share_audio`); remote peers receive them via `track.subscribed`.
+   */
+  setScreenShareEnabled(
+    on: boolean,
+    opts?: {
+      audio?: boolean
+    },
+  ): Promise<void>
+  /** Current local screen-share state (for toggle UI). */
+  isScreenShareEnabled(): boolean
+  /** The local screen-share video track for self-preview, or null when off. */
+  getLocalScreenTrack(): LocalVideoTrack | null
+  /** Disconnect from LiveKit. Idempotent. Triggers `room.ended` via Disconnected. */
+  leave(): Promise<void>
+}
+
 interface FetchTokenArgs {
   /** The agent the SDK is about to call. */
   agentId: string
@@ -253,6 +415,16 @@ interface VoiceClientFactory {
    * don't reject this promise.
    */
   startCall: (options: StartCallOptions) => Promise<Call>
+  /**
+   * Phase 7 (multi-party rooms). Browser only. Exchange a single-use
+   * joinCode for a LiveKit JWT and connect to the room. The returned
+   * `RoomSession` exposes a typed event surface
+   * (participant.joined / participant.left / transcript.partial /
+   *  transcript.final / system.message / room.ended) plus
+   * publishMic / publishCamera / leave. The Node bundle does NOT
+   * implement this — livekit-client is a browser-only WebRTC client.
+   */
+  joinRoom?: (options: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>
 }
 
 type RWSEvent =
@@ -336,6 +508,31 @@ interface NodeVoiceClientFactory {
   startCall: (options: NodeStartCallOptions) => Promise<NodeCall>
 }
 
+/**
+ * Canonical payload a tenant places in their VoIP/FCM push so an
+ * agent-initiated call can connect. It is the `callTokens.mint` result
+ * (token + transport) plus two optional display fields for the native
+ * incoming-call UI. The host receives the push, runs `parseIncomingCall`,
+ * and on accept passes `token` (+ transport / webrtcGatewayBase) into the
+ * voice client. Web background-wake is best-effort (Web Push); native is
+ * the real target. See docs/sdks.md "Agent-initiated calls".
+ */
+interface IncomingCallPayload {
+  token: string
+  agentId: string
+  transport: 'ws' | 'webrtc'
+  webrtcGatewayBase?: string
+  expiresAt?: number
+  agentName?: string
+  agentAvatarUrl?: string
+}
+/**
+ * Validate + normalise a raw push payload into an IncomingCallPayload.
+ * Throws synchronously on malformed input. Unknown transports fall back to
+ * 'ws'; webrtcGatewayBase is ignored unless transport === 'webrtc'.
+ */
+declare const parseIncomingCall: (raw: unknown) => IncomingCallPayload
+
 /**
  * One-time SDK setup for Node.js / Electron-main consumers. Returns a
  * factory you call `startCall` on for every voice call. Same shape as
@@ -378,6 +575,7 @@ export {
   type FetchToken,
   type FetchTokenArgs,
   type FetchTokenResult,
+  type IncomingCallPayload,
   type NodeCall,
   type NodeStartCallOptions,
   type NodeVoiceClientFactory,
@@ -399,4 +597,5 @@ export {
   createProtocolState,
   createReconnectingWebSocket,
   handleServerMessage,
+  parseIncomingCall,
 }

package/dist/node.js

@@ -42,6 +42,7 @@ __export(node_exports, {
   createProtocolState: () => createProtocolState,
   createReconnectingWebSocket: () => createReconnectingWebSocket,
   handleServerMessage: () => handleServerMessage,
+  parseIncomingCall: () => parseIncomingCall,
 })
 module.exports = __toCommonJS(node_exports)
 
@@ -629,6 +630,29 @@ var NodeVoiceClient = class {
   }
 }
 
+// src/incomingCall.ts
+var parseIncomingCall = (raw) => {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error('parseIncomingCall: payload must be an object')
+  }
+  const p = raw
+  if (typeof p.token !== 'string' || !p.token.startsWith('ct_')) {
+    throw new Error('parseIncomingCall: missing or invalid `token` (expected a ct_ string)')
+  }
+  if (typeof p.agentId !== 'string' || p.agentId.length === 0) {
+    throw new Error('parseIncomingCall: missing `agentId`')
+  }
+  const transport = p.transport === 'webrtc' ? 'webrtc' : 'ws'
+  const out = { token: p.token, agentId: p.agentId, transport }
+  if (transport === 'webrtc' && typeof p.webrtcGatewayBase === 'string') {
+    out.webrtcGatewayBase = p.webrtcGatewayBase
+  }
+  if (typeof p.expiresAt === 'number') out.expiresAt = p.expiresAt
+  if (typeof p.agentName === 'string') out.agentName = p.agentName
+  if (typeof p.agentAvatarUrl === 'string') out.agentAvatarUrl = p.agentAvatarUrl
+  return out
+}
+
 // src/node.ts
 var cachedWsCtor = null
 var loadWsCtor = async () => {
@@ -675,6 +699,11 @@ var NodeVoiceFactory = class {
         if (!token) {
           throw new Error('configureVoiceClient.fetchToken returned an object without `token`')
         }
+        if (typeof r !== 'string' && r.transport === 'webrtc') {
+          console.warn(
+            '@craftedxp/voice-js (node): agent is configured for WebRTC but the Node bundle only supports WebSocket \u2014 falling back to WS. Use the browser bundle for WebRTC transport.',
+          )
+        }
       }
       const client = new NodeVoiceClient({
         config: this.config,
@@ -699,5 +728,6 @@ function configureVoiceClient(config) {
     createProtocolState,
     createReconnectingWebSocket,
     handleServerMessage,
+    parseIncomingCall,
   })
 //# sourceMappingURL=node.js.map