@oshara/voice-sdk 0.1.0

package/src/react/index.ts

@@ -0,0 +1,238 @@
+/**
+ * @oshara/voice-sdk/react — thin React bindings over the headless core.
+ *
+ * - `useVoiceAgent(config)` creates and owns a client, subscribes to its
+ *   events, and returns reactive state + bound actions.
+ * - `<VoiceWidget config />` mounts the prebuilt UI into a div.
+ *
+ * `react`/`react-dom` are optional peer dependencies; importing this entry is
+ * what pulls them in.
+ */
+
+import {
+  createElement,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  createVoiceAgent,
+  type AppearanceConfig,
+  type AudioStateSnapshot,
+  type FieldValidationError,
+  type FormDefinition,
+  type OrbState,
+  type VoiceAgentClient,
+  type VoiceAgentConfig,
+} from "../core";
+
+export interface TranscriptItem {
+  key: string;
+  role: "user" | "agent";
+  text: string;
+  isFinal: boolean;
+}
+
+export interface ActiveForm {
+  definition: FormDefinition;
+  values: Record<string, string>;
+  stepIndex: number;
+}
+
+export interface UseVoiceAgentResult {
+  client: VoiceAgentClient;
+  ready: boolean;
+  orb: OrbState;
+  statusLabel: string | null;
+  callStatus: string;
+  connected: boolean;
+  muted: boolean;
+  appearance: AppearanceConfig;
+  audio: AudioStateSnapshot | null;
+  transcript: TranscriptItem[];
+  activeForm: ActiveForm | null;
+  formErrors: FieldValidationError[];
+  formSubmitting: boolean;
+  // actions
+  start: () => Promise<void>;
+  end: () => Promise<void>;
+  toggleMute: () => Promise<boolean>;
+  sendText: (text: string) => Promise<void>;
+  updateFormValues: (values: Record<string, string>) => void;
+  submitForm: () => void;
+  stepForm: (direction: "next" | "back" | number) => void;
+  closeForm: () => void;
+}
+
+/**
+ * Create and manage a voice-agent client for the lifetime of the component.
+ * The `config` is read once on mount (changing it later does not recreate the
+ * client — remount the component, e.g. with a `key`, to switch agents).
+ */
+export function useVoiceAgent(config: VoiceAgentConfig): UseVoiceAgentResult {
+  // Freeze the initial config so the client is created exactly once.
+  const configRef = useRef(config);
+  const client = useMemo(() => createVoiceAgent(configRef.current), []);
+
+  const [ready, setReady] = useState(false);
+  const [orb, setOrb] = useState<OrbState>("idle");
+  const [statusLabel, setStatusLabel] = useState<string | null>(null);
+  const [callStatus, setCallStatus] = useState("");
+  const [connected, setConnected] = useState(false);
+  const [muted, setMuted] = useState(false);
+  const [appearance, setAppearance] = useState<AppearanceConfig>(
+    client.getAppearance(),
+  );
+  const [audio, setAudio] = useState<AudioStateSnapshot | null>(null);
+  const [transcript, setTranscript] = useState<TranscriptItem[]>([]);
+  const [activeForm, setActiveForm] = useState<ActiveForm | null>(null);
+  const [formErrors, setFormErrors] = useState<FieldValidationError[]>([]);
+  const [formSubmitting, setFormSubmitting] = useState(false);
+
+  useEffect(() => {
+    const offs = [
+      client.on("appearance", setAppearance),
+      client.on("state", ({ orb: o, statusLabel: s }) => {
+        setOrb(o);
+        setStatusLabel(o === "thinking" ? s : null);
+      }),
+      client.on("call:status", ({ status }) => setCallStatus(status)),
+      client.on("connection", ({ phase }) => {
+        setConnected(phase === "connected" || phase === "connecting");
+        if (phase === "disconnected" || phase === "failed") setConnected(false);
+      }),
+      client.on("mute", ({ muted: m }) => setMuted(m)),
+      client.on("audio", (a) => setAudio(a)),
+      client.on("transcript:clear", () => setTranscript([])),
+      client.on("transcript", ({ role, segmentId, text, isFinal }) => {
+        const key = `${role}:${segmentId}`;
+        setTranscript((prev) => {
+          const idx = prev.findIndex((t) => t.key === key);
+          const item: TranscriptItem = { key, role, text, isFinal };
+          if (idx === -1) return [...prev, item];
+          const next = prev.slice();
+          next[idx] = item;
+          return next;
+        });
+      }),
+      client.on("form:show", () => {
+        setFormErrors([]);
+        setActiveForm(client.getActiveForm());
+      }),
+      client.on("form:update", () => setActiveForm(client.getActiveForm())),
+      client.on("form:validation", ({ errors }) => setFormErrors(errors)),
+      client.on("form:submitting", () => {
+        setFormSubmitting(true);
+        setFormErrors([]);
+      }),
+      client.on("form:submitted", () => setFormSubmitting(false)),
+      client.on("form:error", () => setFormSubmitting(false)),
+      client.on("form:close", () => {
+        setActiveForm(null);
+        setFormErrors([]);
+        setFormSubmitting(false);
+      }),
+    ];
+
+    let cancelled = false;
+    void client.init().then(() => {
+      if (!cancelled) setReady(true);
+    });
+
+    return () => {
+      cancelled = true;
+      for (const off of offs) off();
+      client.destroy();
+    };
+  }, [client]);
+
+  return {
+    client,
+    ready,
+    orb,
+    statusLabel,
+    callStatus,
+    connected,
+    muted,
+    appearance,
+    audio,
+    transcript,
+    activeForm,
+    formErrors,
+    formSubmitting,
+    start: client.start,
+    end: client.end,
+    toggleMute: client.toggleMute,
+    sendText: client.sendText,
+    updateFormValues: client.updateFormValues,
+    submitForm: client.submitForm,
+    stepForm: client.stepForm,
+    closeForm: client.closeForm,
+  };
+}
+
+export interface VoiceWidgetProps {
+  config: VoiceAgentConfig;
+  /** Forwarded to mountVoiceUI. */
+  inline?: boolean;
+  openChat?: boolean;
+  closeButtonHide?: boolean;
+  className?: string;
+  style?: Record<string, string | number>;
+}
+
+/**
+ * Drop-in prebuilt widget for React apps. Creates a client, mounts the prebuilt
+ * UI into a container div, and tears both down on unmount.
+ */
+export function VoiceWidget(props: VoiceWidgetProps) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    let destroyed = false;
+    let cleanup: (() => void) | null = null;
+
+    const client = createVoiceAgent(props.config);
+    void client.init().then(() => {
+      if (destroyed) {
+        client.destroy();
+        return;
+      }
+      // Dynamically import the UI layer so a headless-only React app that never
+      // renders <VoiceWidget> doesn't pull the DOM UI into its bundle.
+      void import("../ui").then(({ mountVoiceUI }) => {
+        if (destroyed) {
+          client.destroy();
+          return;
+        }
+        const ui = mountVoiceUI(client, {
+          target: host,
+          inline: props.inline ?? true,
+          openChat: props.openChat,
+          closeButtonHide: props.closeButtonHide,
+        });
+        cleanup = () => {
+          ui.destroy();
+          client.destroy();
+        };
+      });
+    });
+
+    return () => {
+      destroyed = true;
+      if (cleanup) cleanup();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return createElement("div", {
+    ref: hostRef,
+    className: props.className,
+    style: props.style,
+  });
+}
+
+export type { VoiceAgentConfig, VoiceAgentClient } from "../core";