@craftedxp/voice-js 0.5.4 → 0.9.0

package/dist/browser.d.ts

@@ -1,613 +1,17 @@
-import { RemoteTrack, LocalVideoTrack } from 'livekit-client'
-
-interface ClientTool {
-  description: string
-  parameters: Record<string, unknown>
-  usage?: string
-  timeoutMs?: number
-  example?: string
-  handler: (args: Record<string, unknown>) => Promise<string | object> | string | object
-}
-type ClientToolMap = Record<string, ClientTool>
-interface ClientToolCallFrame {
-  toolCallId: string
-  name: string
-  args: Record<string, unknown>
-}
-
-type CallState =
-  | 'idle'
-  | 'connecting'
-  | 'listening'
-  | 'user_speaking'
-  | 'agent_speaking'
-  | 'ended'
-  | 'error'
-type TranscriptEntry =
-  | {
-      id: string
-      role: 'user'
-      text: string
-      committed: boolean
-    }
-  | {
-      id: string
-      role: 'agent'
-      text: string
-      interrupted?: boolean
-    }
-  | {
-      id: string
-      role: 'tool'
-      text: string
-    }
-  | {
-      id: string
-      role: 'system'
-      text: string
-    }
-type CallErrorCode =
-  | 'missing_credentials'
-  | 'forbidden'
-  | 'mic_denied'
-  | 'mic_start_failed'
-  | 'audio_session_failed'
-  | 'token_expired'
-  | 'token_invalid'
-  | 'unauthorized'
-  | 'network_unreachable'
-  | 'socket_error'
-  | 'payment_required'
-  | 'not_found'
-  | 'silence_timeout'
-  | 'server_error'
-interface CallError {
-  code: CallErrorCode
-  message: string
-}
-type CallEndReason = 'agent_ended' | 'user_hangup' | 'timeout' | 'error'
-interface CallEndEvent {
-  reason: CallEndReason
-  errorCode?: CallErrorCode
-  durationMs: number
-}
-interface VolumeEvent {
-  input: number
-  output: number
-}
-type ServerMessage = Record<string, unknown> & {
-  type?: string
-}
-interface ProtocolState {
-  state: CallState
-  transcript: TranscriptEntry[]
-  agentBubbleId: string | null
-  idCounter: number
-  endReason: CallEndReason | null
-}
-declare const createProtocolState: () => ProtocolState
-interface ProtocolCallbacks {
-  onState: (next: CallState) => void
-  onTranscript: (entries: TranscriptEntry[]) => void
-  onError: (err: CallError) => void
-  onInterrupt: () => void
-  onAgentTurnStart: (seq?: number) => void
-  onAgentTurnEnd: (seq?: number) => void
-  onCallEnd: (reason: CallEndReason) => void
-  onConnected: () => void
-  onClientToolCall: (frame: ClientToolCallFrame) => void
-}
-declare function handleServerMessage(raw: string, state: ProtocolState, cb: ProtocolCallbacks): void
-interface BuildWsUrlArgs {
-  apiBase: string
-  agentId: string
-  token: string
-  bargeIn?: boolean
-}
-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>
-}
-declare const joinRoom: (opts: JoinRoomOptions) => Promise<RoomSession>
-
-interface FetchTokenArgs {
-  /** The agent the SDK is about to call. */
-  agentId: string
-  /**
-   * Optional consumer-side user identifier. Round-tripped to the server
-   * as `contactId` for Phase 11 contact memory. The SDK does not
-   * inspect this; your backend uses it to scope the token mint.
-   */
-  userId?: string
-  /**
-   * Per-call structured context lowered into the agent's effective
-   * system prompt server-side at session open. Opaque to the SDK.
-   */
-  context?: Record<string, unknown>
-  /**
-   * String key/value pairs round-tripped on the `call.ended` webhook.
-   * Capped at 1 KB total server-side. NOT lowered into the system prompt.
-   */
-  metadata?: Record<string, string>
-}
-/**
- * What `fetchToken` may return. The rich object form lets the server
- * choose the transport per call. Returning a bare string is backwards-
- * compatible — the SDK treats it as `{ token, transport: 'ws' }`.
- */
-interface FetchTokenResult {
-  /** Raw `ct_` to feed into the WS open / WebRTC offer. */
-  token: string
-  /** Server-selected transport. Default `'ws'` if absent. */
-  transport?: 'ws' | 'webrtc'
-  /** Required when `transport === 'webrtc'` AND the server uses a
-   *  separate signaling gateway. When omitted on a webrtc result, the
-   *  SDK falls back to the API base's Phase-1 routes (local dev). */
-  webrtcGatewayBase?: string
-}
-type FetchToken = (args: FetchTokenArgs) => Promise<string | FetchTokenResult>
-interface VoiceClientConfig {
-  /**
-   * Full HTTPS URL of the Voissia server. The WebSocket scheme is
-   * derived: `https` → `wss`, `http` → `ws`. No trailing slash needed.
-   */
-  apiBase: string
-  /**
-   * Called by the SDK whenever it needs a fresh `ct_` token (initial
-   * connect; mid-call refresh on `token_expired`). Your implementation
-   * should hit YOUR backend, which holds the `sk_` API key and mints
-   * via `POST /v1/call-tokens` (or `client.callTokens.mint` from
-   * @craftedxp/sdk-node). Never embed `sk_` in JS code that ships to a
-   * client.
-   */
-  fetchToken: FetchToken
-  /**
-   * Optional metadata applied to EVERY startCall. Per-call `metadata`
-   * in `startCall` is merged on top (per-call wins on key conflicts).
-   * Useful for dashboard-wide tags like `{ surface: 'web', appVersion }`.
-   */
-  defaultMetadata?: Record<string, string>
-  /**
-   * Optional context applied to EVERY startCall. Per-call `context` in
-   * `startCall` is merged on top. Useful for cross-call invariants like
-   * the signed-in user's locale.
-   */
-  defaultContext?: Record<string, unknown>
-}
-interface StartCallOptions {
-  /** The agent to call. */
-  agentId: string
-  /** Per-call user identifier. Round-tripped to fetchToken as `userId`. */
-  userId?: string
-  /**
-   * Per-call structured context. Merged on top of `defaultContext`
-   * configured at factory time.
-   */
-  context?: Record<string, unknown>
-  /**
-   * Per-call metadata. Merged on top of `defaultMetadata` configured
-   * at factory time.
-   */
-  metadata?: Record<string, string>
-  /**
-   * When false, the SDK + server stay full-duplex but barge-in is
-   * suppressed. Useful for alarm-style flows where the user shouldn't
-   * accidentally interrupt the script. Default true.
-   */
-  bargeIn?: boolean
-  /**
-   * Client-side tools the agent's LLM can call mid-conversation. Each
-   * tool's handler runs on the consumer's side; result is fed back to
-   * the LLM through the existing call WebSocket. Schema and handler
-   * colocate. Validated synchronously at startCall — bad input throws.
-   *
-   * See docs/integration-echocheck.md for the wire protocol and the
-   * server-side guarantees.
-   */
-  clientTools?: ClientToolMap
-  /**
-   * Test-only escape hatch — pass a pre-minted `ct_` directly and skip
-   * the `fetchToken` call. Don't use this in production code: tokens
-   * expire and the SDK can't re-mint without the callback.
-   */
-  token?: string
-  onStateChange?: (state: CallState) => void
-  onTranscript?: (entries: TranscriptEntry[]) => void
-  onError?: (err: CallError) => void
-  onEnd?: (end: CallEndEvent) => void
-  /** Volume-meter event for VU UIs. ~10 Hz cadence (browser bundle only). */
-  onVolume?: (vol: VolumeEvent) => void
-  /**
-   * Fires when the server signals barge-in (the user started talking
-   * mid-agent-turn). The browser bundle automatically flushes its
-   * built-in audio playback before this callback runs; the callback is
-   * fired regardless. Node / Electron consumers with custom playback
-   * should drain their audio queue here so the agent goes silent
-   * immediately.
-   */
-  onInterrupt?: () => void
-  /**
-   * Fires on `agent_turn_start` — the server has begun a new agent
-   * turn. The state-machine transition to `agent_speaking` happens at
-   * the same moment via `onStateChange`; use this when you want a
-   * precise turn anchor (e.g. "agent has been speaking for N ms" UIs)
-   * without diffing state.
-   */
-  onAgentTurnStart?: () => void
-}
-interface Call {
-  /** Current state. Snapshot — subscribe via onStateChange for live updates. */
-  readonly state: CallState
-  /** Full transcript so far. Snapshot — subscribe via onTranscript for live updates. */
-  readonly transcript: TranscriptEntry[]
-  /** True after `mute()` and before `unmute()`. */
-  readonly isMuted: boolean
-  /** End the call locally. Closes the WS, stops the mic, fires onEnd. Idempotent. */
-  end: () => void
-  /** Mute mic frames. Wire stays active so server endpointing doesn't false-positive. Idempotent. */
-  mute: () => void
-  /** Unmute mic frames. Idempotent. */
-  unmute: () => void
-}
-interface VoiceClientFactory {
-  /** Read back the resolved config (post trailing-slash normalisation). */
-  readonly config: VoiceClientConfig
-  /**
-   * Open a fresh call. Returns when the WS is open; rejects on
-   * pre-flight failure (missing config, fetchToken throw, etc). Mid-
-   * call failures arrive via the per-call `onError` callback — they
-   * 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 OnChunk = (pcm: ArrayBuffer) => void
-type OnVolume$1 = (rms01: number) => void
-type OnError = (err: Error) => void
-interface CaptureOptions {
-  onChunk: OnChunk
-  onVolume?: OnVolume$1
-  onError?: OnError
-}
-interface CaptureController {
-  start: () => Promise<void>
-  stop: () => void
-  mute: (muted: boolean) => void
-  isCapturing: () => boolean
-}
-declare const createAudioCapture: (options: CaptureOptions) => CaptureController
-
-type OnVolume = (rms01: number) => void
-type OnAgentSpeakingChange = (speaking: boolean) => void
-interface PlaybackOptions {
-  sampleRate?: number
-  onVolume?: OnVolume
-  onSpeakingChange?: OnAgentSpeakingChange
-}
-interface PlaybackController {
-  enqueue: (pcm: ArrayBuffer) => void
-  flush: () => void
-  close: () => void
-  resume: () => Promise<void>
-}
-declare const createAudioPlayback: (options?: PlaybackOptions) => PlaybackController
-
-type RWSEvent =
-  | {
-      type: 'open'
-    }
-  | {
-      type: 'reconnected'
-    }
-  | {
-      type: 'message'
-      data: string | ArrayBuffer
-    }
-  | {
-      type: 'close'
-      code: number
-      reason: string
-      permanent: boolean
-    }
-  | {
-      type: 'error'
-      error: Error
-    }
-interface WebSocketLike {
-  binaryType: string
-  readyState: number
-  onopen: ((ev: unknown) => void) | null
-  onmessage: ((ev: { data: string | ArrayBuffer }) => void) | null
-  onerror: ((ev: unknown) => void) | null
-  onclose: ((ev: { code: number; reason: string }) => void) | null
-  send: (data: string | ArrayBuffer | ArrayBufferView) => void
-  close: (code?: number, reason?: string) => void
-}
-type WebSocketFactory = (url: string) => WebSocketLike
-interface RWSOptions {
-  url: string
-  wsFactory: WebSocketFactory
-  maxRetries?: number
-  initialBackoffMs?: number
-  maxBackoffMs?: number
-}
-declare const createReconnectingWebSocket: (
-  options: RWSOptions,
-  onEvent: (ev: RWSEvent) => void,
-) => {
-  send: (data: string | ArrayBuffer | ArrayBufferView) => void
-  close: (code?: number, reason?: string) => void
-  readyState: () => number
-}
-type ReconnectingWebSocket = ReturnType<typeof createReconnectingWebSocket>
-
-/**
- * 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
+import { V as VoiceClientConfig, a as VoiceClientFactory } from './config-D2TbvIqT.js';
+export { C as Call, b as CallEndEvent, c as CallEndReason, d as CallError, e as CallErrorCode, f as CallState, g as ChatEvent, h as ClientTool, i as ClientToolMap, F as FetchToken, j as FetchTokenArgs, k as FetchTokenResult, P as ProtocolCallbacks, l as ProtocolState, S as ServerMessage, m as StartCallOptions, n as StartTextSessionOpts, T as TextSession, o as TranscriptEntry, p as VolumeEvent, q as buildWsUrl, r as createProtocolState, s as handleServerMessage, t as startTextSession } from './config-D2TbvIqT.js';
+import { JoinRoomOptions, RoomSession } from './room.js';
+export { AnalysisMessage, RoomEventName, RoomEventPayloads, RoomParticipantInfo, SystemMessage, TranscriptMessage, joinRoom } from './room.js';
+export { C as CaptureController, a as CaptureOptions, I as IncomingCallPayload, O as OnAgentSpeakingChange, b as OnChunk, c as OnError, d as OnVolume, P as PlaybackController, e as PlaybackOptions, R as RWSEvent, f as RWSOptions, g as ReconnectingWebSocket, W as WebSocketFactory, h as WebSocketLike, i as createAudioCapture, j as createAudioPlayback, k as createReconnectingWebSocket, p as parseIncomingCall } from './incomingCall-CfRRzj2P.js';
+import 'livekit-client';
 
 /**
  * One-time SDK setup. Returns a factory you call `startCall` on for
- * every voice call.
- *
- * Example:
- *   const voice = configureVoiceClient({
- *     apiBase: 'https://api.your-server.com',
- *     fetchToken: async ({ agentId }) => {
- *       const r = await fetch('/api/voice-token', {
- *         method: 'POST',
- *         body: JSON.stringify({ agentId }),
- *       })
- *       return (await r.json()).token
- *     },
- *   })
- *
- *   // Per call (typically inside a click handler):
- *   const call = await voice.startCall({
- *     agentId: 'agt_xxx',
- *     onTranscript: (entries) => render(entries),
- *     onEnd: ({ reason }) => log(reason),
- *   })
- *   call.mute()
- *   call.end()
+ * every voice call. Also exposes `joinRoom` as a method for multi-party
+ * room joining (back-compat; prefer `@craftedxp/voice-js/room` for new code).
  */
-declare function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory
+declare function configureVoiceClient(config: VoiceClientConfig): VoiceClientFactory & {
+    joinRoom: (opts: Omit<JoinRoomOptions, 'apiBase'>) => Promise<RoomSession>;
+};
 
-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 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 SystemMessage,
-  type TranscriptEntry,
-  type TranscriptMessage,
-  type VoiceClientConfig,
-  type VoiceClientFactory,
-  type VolumeEvent,
-  type WebSocketFactory,
-  type WebSocketLike,
-  buildWsUrl,
-  configureVoiceClient,
-  createAudioCapture,
-  createAudioPlayback,
-  createProtocolState,
-  createReconnectingWebSocket,
-  handleServerMessage,
-  joinRoom,
-  parseIncomingCall,
-}
+export { JoinRoomOptions, RoomSession, VoiceClientConfig, VoiceClientFactory, configureVoiceClient };