@aihumanity/voice-sdk 0.1.0

package/dist/react.js

@@ -0,0 +1,572 @@
+import { useRef, useState, useEffect, useCallback } from 'react';
+import { UltravoxSession, UltravoxSessionStatus } from 'ultravox-client';
+
+// src/react.ts
+
+// src/client.ts
+async function fetchJoinUrl(opts) {
+  if (opts.fetchJoinUrl) {
+    return opts.fetchJoinUrl();
+  }
+  if (!opts.apiUrl) {
+    throw new Error("[aihumanity/voice-sdk] apiUrl is required when fetchJoinUrl is not provided.");
+  }
+  const baseUrl = opts.apiUrl.replace(/\/+$/, "");
+  const body = {
+    username: opts.username,
+    agentName: opts.agentName,
+    ...opts.extraJoinUrlBody ?? {}
+  };
+  if (opts.dataConnection) {
+    body.dataConnection = {
+      websocketUrl: opts.dataConnection.websocketUrl,
+      audioConfig: {
+        sampleRate: opts.dataConnection.audioConfig?.sampleRate ?? 16e3,
+        channelMode: opts.dataConnection.audioConfig?.channelMode ?? "CHANNEL_MODE_SEPARATED"
+      },
+      // Spread user-supplied flags first, then apply defaults for the two
+      // most common flags so they're always present if not explicitly set.
+      dataMessages: {
+        ...opts.dataConnection.dataMessages ?? {},
+        userStartedSpeaking: opts.dataConnection.dataMessages?.userStartedSpeaking ?? true,
+        userStoppedSpeaking: opts.dataConnection.dataMessages?.userStoppedSpeaking ?? true
+      }
+    };
+  }
+  if (opts.publicKey) {
+    const url2 = baseUrl + (opts.joinUrlPath ?? "/v1/voice/joinurl");
+    const res2 = await fetch(url2, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Public-Key": opts.publicKey
+      },
+      body: JSON.stringify(body)
+    });
+    return parseJoinUrlResponse(res2);
+  }
+  const token = typeof opts.authToken === "function" ? await opts.authToken() : opts.authToken;
+  if (!token) {
+    throw new Error(
+      "[aihumanity/voice-sdk] Provide publicKey (for browser-direct) or authToken (for server-side)."
+    );
+  }
+  const path = opts.joinUrlPath ?? "/ultravox/secure/joinurl";
+  const url = baseUrl + path;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify(body)
+  });
+  return parseJoinUrlResponse(res);
+}
+async function parseJoinUrlResponse(res) {
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(
+      `[aihumanity/voice-sdk] joinUrl request failed (${res.status}): ${text}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(
+      `[aihumanity/voice-sdk] joinUrl response was not valid JSON: ${text}`
+    );
+  }
+  if (!parsed.joinUrl) {
+    throw new Error(
+      "[aihumanity/voice-sdk] joinUrl response did not include `joinUrl`."
+    );
+  }
+  return parsed;
+}
+
+// src/emitter.ts
+var TypedEmitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  on(event, listener) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  once(event, listener) {
+    const off = this.on(event, ((payload) => {
+      off();
+      listener(payload);
+    }));
+    return off;
+  }
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const fn of Array.from(set)) {
+      try {
+        fn(payload);
+      } catch (err) {
+        console.error("[aihumanity/voice-sdk] listener error:", err);
+      }
+    }
+  }
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+};
+
+// src/types.ts
+var CallStatus = /* @__PURE__ */ ((CallStatus2) => {
+  CallStatus2["IDLE"] = "idle";
+  CallStatus2["CONNECTING"] = "connecting";
+  CallStatus2["CONNECTED"] = "connected";
+  CallStatus2["LISTENING"] = "listening";
+  CallStatus2["THINKING"] = "thinking";
+  CallStatus2["SPEAKING"] = "speaking";
+  CallStatus2["DISCONNECTING"] = "disconnecting";
+  CallStatus2["DISCONNECTED"] = "disconnected";
+  return CallStatus2;
+})(CallStatus || {});
+var Speaker = /* @__PURE__ */ ((Speaker2) => {
+  Speaker2["USER"] = "user";
+  Speaker2["AGENT"] = "agent";
+  return Speaker2;
+})(Speaker || {});
+
+// src/VoiceCall.ts
+var DEFAULT_EMOTION_PATTERN = /\[EMOTION_CONTEXT\][^:]*:\s*(\w+)/i;
+var CONTACT_SAVED_PATTERN = /I['']ve (noted|saved|got|recorded) your (contact|info|details|number|email)/i;
+var LIVE_STATUSES = /* @__PURE__ */ new Set([
+  "connected" /* CONNECTED */,
+  "listening" /* LISTENING */,
+  "thinking" /* THINKING */,
+  "speaking" /* SPEAKING */
+]);
+var VoiceCall = class {
+  constructor(opts) {
+    this.emitter = new TypedEmitter();
+    this.session = null;
+    this._status = "idle" /* IDLE */;
+    this._callId = null;
+    this._sessionToken = null;
+    this._transcripts = [];
+    this._lastEmotion = null;
+    this._contactSaved = false;
+    this._starting = false;
+    this._emotionMeta = null;
+    this._pollTimer = null;
+    this.opts = opts;
+  }
+  // ── Public read-only state ────────────────────────────────────────────────
+  get status() {
+    return this._status;
+  }
+  get callId() {
+    return this._callId;
+  }
+  get sessionToken() {
+    return this._sessionToken;
+  }
+  get transcripts() {
+    return this._transcripts.slice();
+  }
+  get lastEmotion() {
+    return this._lastEmotion;
+  }
+  get contactSaved() {
+    return this._contactSaved;
+  }
+  get isMicMuted() {
+    return this.session?.isMicMuted ?? false;
+  }
+  get isSpeakerMuted() {
+    return this.session?.isSpeakerMuted ?? false;
+  }
+  /** Server-reported wiring info from the join-url response, if any. */
+  get emotionMeta() {
+    return this._emotionMeta;
+  }
+  /** Underlying ultravox-client session. Use sparingly — for power users. */
+  get rawSession() {
+    return this.session;
+  }
+  // ── Event API ─────────────────────────────────────────────────────────────
+  on(event, listener) {
+    return this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  once(event, listener) {
+    return this.emitter.once(event, listener);
+  }
+  // ── Control ───────────────────────────────────────────────────────────────
+  /**
+   * Fetches a joinUrl from the backend, opens an Ultravox session, and starts
+   * the call. Resolves once `joinCall` has been kicked off (the call goes
+   * "live" asynchronously via status events).
+   */
+  async start() {
+    if (this._starting) return;
+    if (this._status !== "idle" /* IDLE */ && this._status !== "disconnected" /* DISCONNECTED */) {
+      return;
+    }
+    this._starting = true;
+    this.resetMutableState();
+    this.setStatus("connecting" /* CONNECTING */);
+    try {
+      const payload = await fetchJoinUrl(this.opts);
+      this._callId = payload.callId ?? null;
+      this._sessionToken = payload.sessionToken ?? null;
+      this._emotionMeta = payload.emotion ?? null;
+      this.surfaceEmotionWarnings(payload);
+      const session = new UltravoxSession({
+        audioContext: this.opts.audioContext,
+        additionalMessages: this.opts.additionalMessages
+      });
+      this.session = session;
+      this.attachSessionListeners(session);
+      session.joinCall(payload.joinUrl);
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.emitter.emit("error", e);
+      this.setStatus("idle" /* IDLE */);
+    } finally {
+      this._starting = false;
+    }
+  }
+  /** Hangs up. Resolves when ultravox-client confirms disconnection. */
+  async end() {
+    if (!this.session) return;
+    this.setStatus("disconnecting" /* DISCONNECTING */);
+    try {
+      await this.session.leaveCall();
+    } catch (err) {
+      this.emitter.emit(
+        "error",
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+  }
+  muteMic() {
+    this.session?.muteMic();
+    this.emitter.emit("mic_muted", true);
+  }
+  unmuteMic() {
+    this.session?.unmuteMic();
+    this.emitter.emit("mic_muted", false);
+  }
+  toggleMicMute() {
+    if (!this.session) return false;
+    this.session.toggleMicMute();
+    const muted = this.session.isMicMuted;
+    this.emitter.emit("mic_muted", muted);
+    return muted;
+  }
+  muteSpeaker() {
+    this.session?.muteSpeaker();
+    this.emitter.emit("speaker_muted", true);
+  }
+  unmuteSpeaker() {
+    this.session?.unmuteSpeaker();
+    this.emitter.emit("speaker_muted", false);
+  }
+  toggleSpeakerMute() {
+    if (!this.session) return false;
+    this.session.toggleSpeakerMute();
+    const muted = this.session.isSpeakerMuted;
+    this.emitter.emit("speaker_muted", muted);
+    return muted;
+  }
+  /** Sends a text message into the call (no spoken audio from the user). */
+  sendText(text, deferResponse = false) {
+    this.session?.sendText(text, deferResponse);
+  }
+  /** Sends an arbitrary data message over Ultravox's data channel. */
+  sendData(obj) {
+    this.session?.sendData(obj);
+  }
+  /** Removes all listeners and aborts any active session. */
+  dispose() {
+    this.stopEmotionPolling();
+    void this.session?.leaveCall().catch(() => {
+    });
+    this.session = null;
+    this.emitter.removeAllListeners();
+    this._status = "idle" /* IDLE */;
+  }
+  // ── Internals ─────────────────────────────────────────────────────────────
+  resetMutableState() {
+    this._callId = null;
+    this._sessionToken = null;
+    this._transcripts = [];
+    this._lastEmotion = null;
+    this._contactSaved = false;
+    this._emotionMeta = null;
+    this.stopEmotionPolling();
+  }
+  attachSessionListeners(session) {
+    session.addEventListener("status", () => this.handleStatusChange(session));
+    session.addEventListener("transcripts", () => this.handleTranscripts(session));
+    session.addEventListener(
+      "experimental_message",
+      (evt) => this.handleDataMessage(evt)
+    );
+  }
+  handleStatusChange(session) {
+    const raw = session.status;
+    this.emitter.emit("raw_status", String(raw));
+    const prevStatus = this._status;
+    let next;
+    switch (raw) {
+      case UltravoxSessionStatus.CONNECTING:
+        next = "connecting" /* CONNECTING */;
+        break;
+      case UltravoxSessionStatus.IDLE:
+        next = "connected" /* CONNECTED */;
+        break;
+      case UltravoxSessionStatus.LISTENING:
+        next = "listening" /* LISTENING */;
+        break;
+      case UltravoxSessionStatus.THINKING:
+        next = "thinking" /* THINKING */;
+        break;
+      case UltravoxSessionStatus.SPEAKING:
+        next = "speaking" /* SPEAKING */;
+        break;
+      case UltravoxSessionStatus.DISCONNECTING:
+        next = "disconnecting" /* DISCONNECTING */;
+        break;
+      case UltravoxSessionStatus.DISCONNECTED:
+        next = "disconnected" /* DISCONNECTED */;
+        break;
+      default:
+        next = this._status;
+    }
+    this.setStatus(next);
+    const wasLive = LIVE_STATUSES.has(prevStatus);
+    const nowLive = LIVE_STATUSES.has(next);
+    if (!wasLive && nowLive && this._callId && this.opts.pollEmotion) {
+      this.startEmotionPolling();
+    }
+    if (next === "disconnected" /* DISCONNECTED */) {
+      this.stopEmotionPolling();
+      this.session = null;
+      this.emitter.emit("ended", void 0);
+      this.setStatus("idle" /* IDLE */);
+    }
+  }
+  handleTranscripts(session) {
+    const raw = session.transcripts ?? [];
+    const mapped = raw.map(toPublicTranscript);
+    const previous = this._transcripts;
+    this._transcripts = mapped;
+    for (let i = 0; i < mapped.length; i++) {
+      const cur = mapped[i];
+      if (!cur) continue;
+      const prev = previous[i];
+      if (!prev || prev.text !== cur.text || prev.isFinal !== cur.isFinal) {
+        this.emitter.emit("transcript", cur);
+      }
+    }
+    this.emitter.emit("transcripts", mapped);
+    if (!this._contactSaved) {
+      const saved = mapped.some(
+        (t) => t.speaker === "agent" /* AGENT */ && t.text && CONTACT_SAVED_PATTERN.test(t.text)
+      );
+      if (saved) {
+        this._contactSaved = true;
+        this.emitter.emit("contact_saved", void 0);
+      }
+    }
+  }
+  handleDataMessage(evt) {
+    const anyEvt = evt;
+    const raw = anyEvt.message ?? anyEvt.data ?? evt;
+    this.emitter.emit("data_message", raw);
+    const text = typeof raw === "string" ? raw : safeStringify(raw);
+    const pattern = this.opts.emotionPattern ?? DEFAULT_EMOTION_PATTERN;
+    const match = text.match(pattern);
+    if (match && match[1]) {
+      const label = match[1].toLowerCase();
+      this._lastEmotion = label;
+      this.emitter.emit("emotion", { label, raw });
+    }
+  }
+  startEmotionPolling() {
+    this.stopEmotionPolling();
+    if (!this.opts.pollEmotion || !this._callId) return;
+    const callId = this._callId;
+    const sessionToken = this._sessionToken ?? void 0;
+    const interval = this.opts.emotionPollIntervalMs ?? 15e3;
+    const poll = async () => {
+      try {
+        const label = await this.opts.pollEmotion(callId, sessionToken);
+        if (label) {
+          const normalized = label.toLowerCase();
+          this._lastEmotion = normalized;
+          this.emitter.emit("emotion", { label: normalized, raw: label });
+        }
+      } catch {
+      }
+    };
+    poll();
+    this._pollTimer = setInterval(poll, interval);
+  }
+  stopEmotionPolling() {
+    if (this._pollTimer !== null) {
+      clearInterval(this._pollTimer);
+      this._pollTimer = null;
+    }
+  }
+  setStatus(next) {
+    if (next === this._status) return;
+    this._status = next;
+    this.emitter.emit("status", next);
+  }
+  surfaceEmotionWarnings(payload) {
+    const e = payload.emotion;
+    if (!e) return;
+    if (e.dataConnectionEnabled === false) {
+      this.emitter.emit(
+        "warning",
+        "dataConnection not enabled \u2014 check emotion WebSocket URL."
+      );
+    }
+    if (e.audioEnabled === false) {
+      this.emitter.emit(
+        "warning",
+        "audio not enabled \u2014 audioConfig missing on backend request."
+      );
+    }
+    if (e.emotionBridgeConfigured === false) {
+      this.emitter.emit(
+        "warning",
+        "emotionBridge not configured on the backend."
+      );
+    }
+    if (e.autoSendEnabled === false) {
+      this.emitter.emit(
+        "warning",
+        "auto-send not enabled \u2014 emotion will not feed back into the agent."
+      );
+    }
+  }
+};
+function toPublicTranscript(t) {
+  return {
+    text: t.text,
+    isFinal: t.isFinal,
+    speaker: t.speaker,
+    medium: t.medium,
+    ordinal: t.ordinal
+  };
+}
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+// src/react.ts
+var LIVE_STATES = /* @__PURE__ */ new Set([
+  "connected" /* CONNECTED */,
+  "listening" /* LISTENING */,
+  "thinking" /* THINKING */,
+  "speaking" /* SPEAKING */
+]);
+function useVoiceCall(options) {
+  const optsRef = useRef(options);
+  optsRef.current = options;
+  const callRef = useRef(null);
+  if (callRef.current === null) {
+    callRef.current = new VoiceCall({
+      ...options,
+      authToken: typeof options.authToken === "function" ? () => optsRef.current.authToken() : options.authToken
+    });
+  }
+  const call = callRef.current;
+  const [status, setStatus] = useState(call.status);
+  const [transcripts, setTranscripts] = useState(call.transcripts);
+  const [lastEmotion, setLastEmotion] = useState(call.lastEmotion);
+  const [contactSaved, setContactSaved] = useState(call.contactSaved);
+  const [micMuted, setMicMuted] = useState(call.isMicMuted);
+  const [speakerMuted, setSpeakerMuted] = useState(call.isSpeakerMuted);
+  const [warning, setWarning] = useState(null);
+  const [error, setError] = useState(null);
+  const [callId, setCallId] = useState(call.callId);
+  const [sessionToken, setSessionToken] = useState(call.sessionToken);
+  useEffect(() => {
+    const offs = [
+      call.on("status", (s) => {
+        setStatus(s);
+        setCallId(call.callId);
+        setSessionToken(call.sessionToken);
+      }),
+      call.on("transcripts", (all) => setTranscripts(all)),
+      call.on("emotion", (e) => setLastEmotion(e.label)),
+      call.on("contact_saved", () => setContactSaved(true)),
+      call.on("mic_muted", (m) => setMicMuted(m)),
+      call.on("speaker_muted", (m) => setSpeakerMuted(m)),
+      call.on("warning", (w) => setWarning(w)),
+      call.on("error", (e) => setError(e))
+    ];
+    return () => {
+      for (const off of offs) off();
+    };
+  }, [call]);
+  useEffect(() => {
+    return () => {
+      call.dispose();
+    };
+  }, [call]);
+  const start = useCallback(() => {
+    setError(null);
+    setWarning(null);
+    return call.start();
+  }, [call]);
+  const end = useCallback(() => call.end(), [call]);
+  const toggleMicMute = useCallback(() => call.toggleMicMute(), [call]);
+  const toggleSpeakerMute = useCallback(() => call.toggleSpeakerMute(), [call]);
+  const sendText = useCallback(
+    (text, deferResponse) => call.sendText(text, deferResponse),
+    [call]
+  );
+  return {
+    status,
+    isBusy: status === "connecting" /* CONNECTING */ || status === "disconnecting" /* DISCONNECTING */,
+    isLive: LIVE_STATES.has(status),
+    transcripts,
+    lastEmotion,
+    contactSaved,
+    micMuted,
+    speakerMuted,
+    warning,
+    error,
+    callId,
+    sessionToken,
+    start,
+    end,
+    toggleMicMute,
+    toggleSpeakerMute,
+    sendText,
+    call
+  };
+}
+
+export { CallStatus, Speaker, VoiceCall, useVoiceCall };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map