@oshara/voice-sdk 0.1.0

package/src/core/consent.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-agent localStorage record of the user's acceptance of the terms &
+ * conditions presented in the welcome screen. Starting a call implicitly
+ * accepts the terms; we persist that acceptance so we can show a quieter
+ * "accepted" state on return visits and have an audit trail of which
+ * terms_url version was accepted.
+ */
+
+const STORAGE_PREFIX = "voiceAgent.consent";
+
+export interface ConsentRecord {
+  /** ms-since-epoch when the user first accepted. */
+  acceptedAt: number;
+  /** The terms_url that was in effect at acceptance time. */
+  termsUrl: string;
+}
+
+function storageKey(agentSlug: string): string {
+  return `${STORAGE_PREFIX}.${agentSlug}`;
+}
+
+function safeLocalStorage(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function loadConsent(agentSlug: string): ConsentRecord | null {
+  if (!agentSlug) return null;
+  const ls = safeLocalStorage();
+  if (!ls) return null;
+
+  let raw: string | null = null;
+  try {
+    raw = ls.getItem(storageKey(agentSlug));
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    const acceptedAt =
+      typeof parsed.acceptedAt === "number" ? parsed.acceptedAt : 0;
+    const termsUrl =
+      typeof parsed.termsUrl === "string" ? parsed.termsUrl : "";
+    if (!acceptedAt) return null;
+    return { acceptedAt, termsUrl };
+  } catch {
+    return null;
+  }
+}
+
+/** Returns true if the user has accepted the *current* terms_url before. */
+export function hasAcceptedTerms(agentSlug: string, termsUrl: string): boolean {
+  const record = loadConsent(agentSlug);
+  if (!record) return false;
+  // If the link has changed since acceptance, require fresh acknowledgement.
+  return record.termsUrl === termsUrl;
+}
+
+export function saveConsent(agentSlug: string, termsUrl: string): void {
+  if (!agentSlug) return;
+  const ls = safeLocalStorage();
+  if (!ls) return;
+  const record: ConsentRecord = {
+    acceptedAt: Date.now(),
+    termsUrl,
+  };
+  try {
+    ls.setItem(storageKey(agentSlug), JSON.stringify(record));
+  } catch {
+    // Quota or privacy mode — silently drop.
+  }
+}

package/src/core/createVoiceAgent.ts

@@ -0,0 +1,280 @@
+/**
+ * createVoiceAgent — the headless entry point of the SDK.
+ *
+ * A developer adds their agent slug (and optionally an API key) and everything
+ * initializes exactly like the widget: appearance is fetched, the voice
+ * controller + form controller are wired, agent-triggered forms surface as
+ * events. Build a fully custom UI on the events, or mount the prebuilt UI from
+ * `@oshara/voice-sdk/ui`.
+ */
+
+import { trackWidgetEvent } from "./analytics";
+import {
+  AppearanceConfig,
+  DEFAULT_APPEARANCE,
+  fetchAppearance,
+} from "./appearance";
+import {
+  AudioPrefs,
+  AudioCapabilities,
+  AudioDevices,
+  DEFAULT_AUDIO_PREFS,
+  enumerateAudioDevices,
+  loadAudioPrefs,
+  probeAudioCapabilities,
+} from "./audioSettings";
+import { Emitter, EventHandler, EventName } from "./events";
+import {
+  createFormController,
+  FormController,
+} from "./formController";
+import {
+  FormDefinition,
+  extractFormDraft,
+  handleFormAction,
+  matchForm,
+} from "./forms";
+import { fetchSession, warnIfBrowserSecret } from "./transport";
+import type { DeepFilterUrls } from "./types";
+import {
+  AudioStateSnapshot,
+  AudioStats,
+  createVoiceController,
+  VoiceController,
+} from "./voice";
+
+export interface VoiceAgentConfig {
+  /** AICharacter.slug on the backend. Required. */
+  agentSlug: string;
+  /** Backend base URL. Default "https://api.oshara.ai". */
+  apiUrl?: string;
+  /**
+   * Secret API key (sk_…) sent as `x-api-key`, bypassing origin gating.
+   * OMIT for public browser embeds (rely on the origin allow-list). Intended
+   * for server-side / Node usage; warns if used in a browser.
+   */
+  apiKey?: string;
+  /** Override the appearance endpoint URL. */
+  appearanceUrl?: string;
+  /** UI language (BCP-47 short). Default "en". */
+  language?: string;
+  /** DeepFilterNet3 asset overrides (same defaults/precedence as the widget). */
+  deepFilter?: DeepFilterUrls;
+  /** Auto-fetch appearance during init() (default true). */
+  fetchAppearanceOnInit?: boolean;
+  /** Disable analytics events (default false). */
+  disableAnalytics?: boolean;
+  /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+  /**
+   * Seed audio preferences. Merged over DEFAULT_AUDIO_PREFS and (when
+   * persistAudioPrefs) the stored per-agent prefs.
+   */
+  audio?: Partial<AudioPrefs>;
+  /** Read/write audio prefs to localStorage (default true). */
+  persistAudioPrefs?: boolean;
+}
+
+export interface VoiceAgentClient {
+  /** The AICharacter slug this client targets. */
+  readonly agentSlug: string;
+  /** Fetch appearance (if enabled) and prepare the agent. Idempotent. */
+  init: () => Promise<{ appearance: AppearanceConfig }>;
+  /** Start a call. */
+  start: () => Promise<void>;
+  /** End the call. */
+  end: () => Promise<void>;
+  /** Tear down listeners + any active call. */
+  destroy: () => void;
+
+  toggleMute: () => Promise<boolean>;
+  isActive: () => boolean;
+  sessionId: () => string | null;
+  /** Send a typed text message to the agent (also emits a transcript line). */
+  sendText: (text: string) => Promise<void>;
+  publishData: (payload: unknown, topic: string) => Promise<void>;
+
+  updateAudioSettings: (
+    delta: Partial<AudioPrefs>,
+  ) => Promise<AudioStateSnapshot>;
+  getAudioState: () => AudioStateSnapshot;
+  getAudioStats: () => Promise<AudioStats | null>;
+  enumerateAudioDevices: () => Promise<AudioDevices>;
+  getAudioCapabilities: () => AudioCapabilities;
+
+  // ── forms ──
+  getActiveForm: () => ReturnType<FormController["getActive"]>;
+  /** Push on-screen form edits into the model (custom UIs call this on input). */
+  updateFormValues: (values: Record<string, string>) => void;
+  stepForm: (direction: "next" | "back" | number) => void;
+  submitForm: () => void;
+  closeForm: () => void;
+  /** Programmatically open a form. */
+  openForm: (definition: FormDefinition, draft?: Record<string, string>) => void;
+
+  getAppearance: () => AppearanceConfig;
+  setLanguage: (code: string) => void;
+  getLanguage: () => string;
+
+  /** Report an engagement event (widget_loaded / bubble_clicked). */
+  trackEvent: (
+    type: "widget_loaded" | "bubble_clicked",
+    metadata?: Record<string, unknown>,
+  ) => void;
+
+  on: <K extends EventName>(event: K, handler: EventHandler<K>) => () => void;
+  off: <K extends EventName>(event: K, handler: EventHandler<K>) => void;
+}
+
+const DEFAULT_API_URL = "https://api.oshara.ai";
+
+export function createVoiceAgent(config: VoiceAgentConfig): VoiceAgentClient {
+  if (!config.agentSlug) {
+    // eslint-disable-next-line no-console
+    console.error("[voice-agent] agentSlug is required");
+  }
+  warnIfBrowserSecret(config.apiKey);
+
+  const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+  const persistAudioPrefs = config.persistAudioPrefs ?? true;
+  let language = config.language ?? "en";
+
+  const emitter = new Emitter();
+  const emit = emitter.emit;
+
+  // Resolve audio prefs: defaults < stored (if persisting) < explicit config.
+  const initialPrefs: AudioPrefs = {
+    ...DEFAULT_AUDIO_PREFS,
+    ...(persistAudioPrefs ? loadAudioPrefs(config.agentSlug) : {}),
+    ...(config.audio ?? {}),
+  };
+
+  let appearance: AppearanceConfig = DEFAULT_APPEARANCE;
+  const getAppearance = () => appearance;
+
+  const voice: VoiceController = createVoiceController({
+    fetchSession: () =>
+      fetchSession({
+        apiUrl,
+        agentSlug: config.agentSlug,
+        language,
+        apiKey: config.apiKey,
+        fetch: config.fetch,
+      }),
+    agentSlug: config.agentSlug,
+    getAppearance,
+    emit,
+    deepFilter: config.deepFilter,
+    initialPrefs,
+    persistPrefs: persistAudioPrefs,
+  });
+
+  const forms: FormController = createFormController({
+    emit,
+    voice,
+    apiUrl,
+    agentSlug: config.agentSlug,
+    apiKey: config.apiKey,
+    fetch: config.fetch,
+  });
+
+  // Route agent data messages → handoff / form actions / form render.
+  emitter.on("data", ({ data, topic }) => {
+    if (topic === "voice.agent_handoff") {
+      const agentName =
+        data && typeof data === "object" &&
+        typeof (data as { agent_name?: unknown }).agent_name === "string"
+          ? ((data as { agent_name: string }).agent_name || "").trim()
+          : "";
+      emit("agent:handoff", { agentName });
+      return;
+    }
+    // Agent-driven step / submit / close. Must run before matchForm.
+    if (handleFormAction(topic, data, forms)) return;
+
+    const match = matchForm(topic, data, getAppearance().forms);
+    if (!match) return;
+    const draft = extractFormDraft(data, match) ?? {};
+    if (forms.current() === match.id) forms.merge(draft);
+    else forms.open(match, draft);
+  });
+
+  const trackEvent = (
+    type: "widget_loaded" | "bubble_clicked",
+    metadata: Record<string, unknown> = {},
+  ) =>
+    trackWidgetEvent(
+      {
+        apiUrl,
+        agentSlug: config.agentSlug,
+        apiKey: config.apiKey,
+        fetch: config.fetch,
+        disabled: config.disableAnalytics,
+      },
+      type,
+      metadata,
+    );
+
+  let initialized = false;
+  const init = async (): Promise<{ appearance: AppearanceConfig }> => {
+    if (!initialized && (config.fetchAppearanceOnInit ?? true)) {
+      appearance = await fetchAppearance({
+        appearanceUrl: config.appearanceUrl ?? "",
+        apiUrl,
+        slug: config.agentSlug,
+        apiKey: config.apiKey,
+        fetch: config.fetch,
+      });
+    }
+    initialized = true;
+    emit("appearance", appearance);
+    return { appearance };
+  };
+
+  const destroy = () => {
+    if (voice.isActive()) void voice.end();
+    emitter.clear();
+  };
+
+  return {
+    agentSlug: config.agentSlug,
+    init,
+    start: voice.start,
+    end: voice.end,
+    destroy,
+    toggleMute: voice.toggleMute,
+    isActive: voice.isActive,
+    sessionId: voice.sessionId,
+    sendText: async (text: string) => {
+      const t = (text || "").trim();
+      if (!t || !voice.isActive()) return;
+      emit("transcript", {
+        role: "user",
+        segmentId: `typed-${Date.now()}`,
+        text: t,
+        isFinal: true,
+      });
+      await voice.publishData({ type: "user_text", text: t }, "voice.user_text");
+    },
+    publishData: voice.publishData,
+    updateAudioSettings: voice.updateAudioSettings,
+    getAudioState: voice.getAudioState,
+    getAudioStats: voice.getAudioStats,
+    enumerateAudioDevices,
+    getAudioCapabilities: probeAudioCapabilities,
+    getActiveForm: forms.getActive,
+    updateFormValues: forms.updateValues,
+    stepForm: forms.step,
+    submitForm: forms.submit,
+    closeForm: forms.close,
+    openForm: forms.open,
+    getAppearance,
+    setLanguage: (code: string) => {
+      language = code || "en";
+    },
+    getLanguage: () => language,
+    trackEvent,
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+  };
+}

package/src/core/events.ts

@@ -0,0 +1,120 @@
+/**
+ * Typed event emitter for the voice-agent SDK.
+ *
+ * The headless core publishes everything that the widget used to do via direct
+ * UI calls (orb state, transcripts, call status, mute, forms, …) as typed
+ * events. The prebuilt UI subscribes to these and renders; custom UIs do the
+ * same. This is the seam that decouples logic from presentation.
+ */
+
+import type { AppearanceConfig } from "./appearance";
+import type { FormDefinition, FieldValidationError } from "./forms";
+import type { AudioStateSnapshot } from "./voice";
+import type { OrbState, ConnectionPhase, ControlsState } from "./types";
+
+export interface VoiceAgentEvents {
+  /** Orb state machine + contextual status line (e.g. "Searching…"). */
+  state: { orb: OrbState; statusLabel: string | null };
+  /** Free-form call status text (Connecting…, Connected, Muted, errors). */
+  "call:status": { status: string };
+  /** Remaining call time in ms, or null to hide the timer. */
+  "call:timer": { remainingMs: number | null };
+  /** Connection lifecycle. UI maps this to which screen to show. */
+  connection: { phase: ConnectionPhase; error?: string };
+  /** Which call controls should be enabled. */
+  controls: ControlsState;
+  /** A transcript segment (interim or final) for either party. */
+  transcript: {
+    role: "user" | "agent";
+    segmentId: string;
+    text: string;
+    isFinal: boolean;
+  };
+  /** Clear all transcript content (new call). */
+  "transcript:clear": Record<string, never>;
+  /** A system transcript line (e.g. agent handoff transition message). */
+  "transcript:system": { text: string };
+  /** Mute state changed. */
+  mute: { muted: boolean };
+  /** Audio preferences / applied settings snapshot changed. */
+  audio: AudioStateSnapshot;
+  /** Raw JSON data message received from the agent over LiveKit. */
+  data: { data: unknown; topic: string | undefined };
+  /** A form should be shown (agent-triggered or programmatic). */
+  "form:show": {
+    definition: FormDefinition;
+    draft: Record<string, string>;
+    stepIndex: number;
+    inCall: boolean;
+    transcriptionEnabled: boolean;
+  };
+  /** The form values / current step changed (agent merge or step nav). */
+  "form:update": { values: Record<string, string>; stepIndex: number };
+  /** Client-side validation failed; render these inline errors. */
+  "form:validation": { errors: FieldValidationError[] };
+  /** A submit POST is in flight. */
+  "form:submitting": Record<string, never>;
+  /** A form was submitted successfully. */
+  "form:submitted": {
+    formId: string;
+    values: Record<string, string>;
+    successMessage: string;
+  };
+  /** A submit POST failed. */
+  "form:error": { message: string };
+  /** The active form was closed. */
+  "form:close": Record<string, never>;
+  /** Mid-call handoff to another agent. */
+  "agent:handoff": { agentName: string };
+  /** Appearance config resolved (after init fetch). */
+  appearance: AppearanceConfig;
+  /** A non-fatal error occurred in some scope. */
+  error: { scope: string; error: Error };
+}
+
+export type EventName = keyof VoiceAgentEvents;
+export type EventHandler<K extends EventName> = (
+  payload: VoiceAgentEvents[K],
+) => void;
+export type Emit = <K extends EventName>(
+  event: K,
+  payload: VoiceAgentEvents[K],
+) => void;
+
+/** Minimal typed event emitter. No deps, works in browser and Node. */
+export class Emitter {
+  private listeners = new Map<EventName, Set<EventHandler<EventName>>>();
+
+  on<K extends EventName>(event: K, handler: EventHandler<K>): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler as EventHandler<EventName>);
+    return () => this.off(event, handler);
+  }
+
+  off<K extends EventName>(event: K, handler: EventHandler<K>): void {
+    this.listeners.get(event)?.delete(handler as EventHandler<EventName>);
+  }
+
+  emit: Emit = (event, payload) => {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    // Iterate a copy so a handler can unsubscribe during dispatch.
+    for (const handler of Array.from(set)) {
+      try {
+        (handler as EventHandler<typeof event>)(payload);
+      } catch (err) {
+        // A faulty listener must never break the controller's control flow.
+        // eslint-disable-next-line no-console
+        console.error(`[voice-agent] listener for "${String(event)}" threw`, err);
+      }
+    }
+  };
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}