@oshara/voice-sdk 0.1.0

package/src/core/index.ts

@@ -0,0 +1,121 @@
+/**
+ * @oshara/voice-sdk — headless core.
+ *
+ * `import { createVoiceAgent } from "@oshara/voice-sdk"` pulls in zero DOM/UI
+ * code. Build a custom UI on the events, or mount the prebuilt UI from
+ * `@oshara/voice-sdk/ui`.
+ */
+
+export { createVoiceAgent } from "./createVoiceAgent";
+export type { VoiceAgentConfig, VoiceAgentClient } from "./createVoiceAgent";
+
+// Events
+export { Emitter } from "./events";
+export type {
+  VoiceAgentEvents,
+  EventName,
+  EventHandler,
+  Emit,
+} from "./events";
+
+// Core types
+export type {
+  OrbState,
+  SessionInit,
+  ConnectionPhase,
+  ControlsState,
+  DeepFilterUrls,
+} from "./types";
+export { DEFAULT_DEEPFILTER_MODULE_URL } from "./types";
+
+// Voice controller (advanced / direct use)
+export {
+  createVoiceController,
+} from "./voice";
+export type {
+  VoiceController,
+  VoiceControllerOptions,
+  AudioStateSnapshot,
+  AudioStats,
+} from "./voice";
+
+// Forms
+export {
+  createFormController,
+} from "./formController";
+export type { FormController } from "./formController";
+export {
+  buildFieldSchema,
+  collectInputFields,
+  extractFormDraft,
+  fieldsForStep,
+  handleFormAction,
+  initialFormValues,
+  matchForm,
+  mergeFormDraft,
+  normalizeFormDefinitions,
+  submitForm,
+  totalSteps,
+  validateFields,
+  DEFAULT_FORM_DEFINITIONS,
+} from "./forms";
+export type {
+  FormDefinition,
+  FormFieldDef,
+  FormFieldType,
+  FormFieldOption,
+  FormStep,
+  FormLayout,
+  FormStateSnapshot,
+  FieldValidationError,
+} from "./forms";
+
+// Appearance
+export {
+  fetchAppearance,
+  mergeAppearance,
+  DEFAULT_APPEARANCE,
+} from "./appearance";
+export type {
+  AppearanceConfig,
+  AppearanceTheme,
+  AppearanceDimensions,
+  AppearanceLayout,
+  AppearanceLabels,
+  AppearanceLanguage,
+  WidgetPosition,
+} from "./appearance";
+
+// Audio settings
+export {
+  DEFAULT_AUDIO_PREFS,
+  loadAudioPrefs,
+  saveAudioPrefs,
+  enumerateAudioDevices,
+  probeAudioCapabilities,
+} from "./audioSettings";
+export type {
+  AudioPrefs,
+  NoiseFilterEngine,
+  AudioDevices,
+  AudioCapabilities,
+} from "./audioSettings";
+
+// Persistence helpers
+export {
+  loadPrevContext,
+  savePrevContext,
+  clearPrevContext,
+  formatPrevContextForAgent,
+} from "./prevContext";
+export type { PrevTurn } from "./prevContext";
+export { loadConsent, saveConsent, hasAcceptedTerms } from "./consent";
+export { trackWidgetEvent, getVisitorId } from "./analytics";
+
+// Transport
+export {
+  buildHeaders,
+  fetchSession,
+  warnIfBrowserSecret,
+} from "./transport";
+export type { TransportConfig, FetchSessionArgs } from "./transport";

package/src/core/prevContext.ts

@@ -0,0 +1,153 @@
+/**
+ * Per-agent storage for the most-recent conversation transcript, so the
+ * agent can be primed with prior context when the user returns.
+ *
+ * The widget stores the *raw last turns* (not an LLM-generated summary) —
+ * the agent-side LLM is perfectly capable of using the transcript as
+ * context, and skipping a summarization step keeps the widget standalone.
+ */
+
+const STORAGE_PREFIX = "voiceAgent.prevContext";
+const MAX_STORED_CHARS = 4000;
+const MAX_STORED_TURNS = 30;
+const MAX_TURN_CHARS = 500;
+const MAX_SUMMARY_CHARS = 1500;
+/** Drop saved context older than this so stale conversations don't haunt new ones. */
+const STALE_AFTER_MS = 14 * 24 * 60 * 60 * 1000;
+
+export interface PrevTurn {
+  role: "user" | "agent";
+  text: string;
+}
+
+export interface PrevContextRecord {
+  savedAt: number;
+  turns: PrevTurn[];
+  /** Agent-generated short user-profile summary (preferred over raw turns
+   *  when priming the next session). May be empty. */
+  summary?: string;
+}
+
+function storageKey(agentSlug: string): string {
+  return `${STORAGE_PREFIX}.${agentSlug}`;
+}
+
+function safeLocalStorage(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function loadPrevContext(agentSlug: string): PrevContextRecord | 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;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as Partial<PrevContextRecord>;
+  const savedAt = typeof obj.savedAt === "number" ? obj.savedAt : 0;
+  if (!savedAt || Date.now() - savedAt > STALE_AFTER_MS) {
+    clearPrevContext(agentSlug);
+    return null;
+  }
+
+  const turns: PrevTurn[] = [];
+  if (Array.isArray(obj.turns)) {
+    for (const t of obj.turns) {
+      if (!t || typeof t !== "object") continue;
+      const role = (t as PrevTurn).role;
+      const text = (t as PrevTurn).text;
+      if ((role !== "user" && role !== "agent") || typeof text !== "string") continue;
+      const cleaned = text.trim();
+      if (!cleaned) continue;
+      turns.push({ role, text: cleaned });
+    }
+  }
+  const summary =
+    typeof obj.summary === "string" ? obj.summary.trim().slice(0, MAX_SUMMARY_CHARS) : "";
+  if (!turns.length && !summary) return null;
+  return { savedAt, turns, summary };
+}
+
+export function savePrevContext(
+  agentSlug: string,
+  turns: PrevTurn[],
+  summary?: string,
+): void {
+  if (!agentSlug) return;
+  const ls = safeLocalStorage();
+  if (!ls) return;
+
+  // Trim per-turn, drop empties, keep most recent MAX_STORED_TURNS, then
+  // truncate from the front until we fit MAX_STORED_CHARS.
+  const cleaned: PrevTurn[] = [];
+  for (const t of turns) {
+    const text = (t.text || "").trim().slice(0, MAX_TURN_CHARS);
+    if (!text) continue;
+    cleaned.push({ role: t.role, text });
+  }
+  const recent = cleaned.slice(-MAX_STORED_TURNS);
+
+  let totalChars = recent.reduce((n, t) => n + t.text.length, 0);
+  while (recent.length > 1 && totalChars > MAX_STORED_CHARS) {
+    const dropped = recent.shift();
+    if (dropped) totalChars -= dropped.text.length;
+  }
+
+  const trimmedSummary = (summary || "").trim().slice(0, MAX_SUMMARY_CHARS);
+  if (!recent.length && !trimmedSummary) {
+    clearPrevContext(agentSlug);
+    return;
+  }
+
+  const record: PrevContextRecord = {
+    savedAt: Date.now(),
+    turns: recent,
+    summary: trimmedSummary,
+  };
+  try {
+    ls.setItem(storageKey(agentSlug), JSON.stringify(record));
+  } catch {
+    // Quota or privacy mode — silently drop.
+  }
+}
+
+export function clearPrevContext(agentSlug: string): void {
+  if (!agentSlug) return;
+  const ls = safeLocalStorage();
+  if (!ls) return;
+  try {
+    ls.removeItem(storageKey(agentSlug));
+  } catch {
+    // ignore
+  }
+}
+
+/** Format stored context for the agent's system prompt.
+ *  Prefers the agent-generated user-profile summary when available; falls
+ *  back to a labelled raw-turn transcript otherwise. */
+export function formatPrevContextForAgent(record: PrevContextRecord): string {
+  const summary = (record.summary || "").trim();
+  if (summary) return `User profile from previous session:\n${summary}`;
+  const lines = record.turns.map((t) =>
+    t.role === "user" ? `User: ${t.text}` : `Assistant: ${t.text}`,
+  );
+  return lines.join("\n");
+}

package/src/core/transport.ts

@@ -0,0 +1,118 @@
+/**
+ * HTTP transport helpers shared by every backend call the SDK makes
+ * (session minting, appearance, form submit, analytics).
+ *
+ * Two auth modes (see docs/Authentication):
+ *  - Public browser embed (default): no key. The backend gates on the
+ *    AICharacter's origin allow-list. This is exactly how the widget works.
+ *  - Trusted/server mode: an `sk_…` key sent as `x-api-key`, bypassing origin
+ *    gating. Intended for Node / server-side usage. We warn loudly if such a
+ *    secret key is used in a browser, where it would be world-readable.
+ */
+
+import type { SessionInit } from "./types";
+
+export interface TransportConfig {
+  apiUrl: string;
+  /** Secret API key (sk_…). Sent as `x-api-key`. Omit for public embeds. */
+  apiKey?: string;
+  /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+}
+
+/** Merge auth headers onto a base header set. */
+export function buildHeaders(
+  config: Pick<TransportConfig, "apiKey">,
+  base: Record<string, string> = {},
+): Record<string, string> {
+  const headers: Record<string, string> = { ...base };
+  const key = config.apiKey?.trim();
+  if (key) headers["x-api-key"] = key;
+  return headers;
+}
+
+/** Resolve a usable fetch implementation or throw a helpful error. */
+export function resolveFetch(fetchImpl?: typeof fetch): typeof fetch {
+  if (fetchImpl) return fetchImpl;
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+  throw new Error(
+    "[voice-agent] No global fetch available. Pass `fetch` in the SDK config (Node < 18).",
+  );
+}
+
+/**
+ * Warn when a secret key is embedded in browser JS, where it is exposed to
+ * anyone who views source. Call once at init.
+ */
+export function warnIfBrowserSecret(apiKey?: string): void {
+  if (
+    apiKey &&
+    apiKey.trim().startsWith("sk_") &&
+    typeof window !== "undefined"
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[voice-agent] A secret API key (sk_…) was provided in a browser context — " +
+        "it is visible to anyone who views the page. For public embeds omit `apiKey` " +
+        "and rely on origin allow-listing; reserve `apiKey` for server-side/Node usage.",
+    );
+  }
+}
+
+export interface FetchSessionArgs {
+  apiUrl: string;
+  agentSlug: string;
+  language: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+  /** Page URL recorded server-side; defaults to window.location.href. */
+  originUrl?: string;
+  /** Optional extra fields honored only with a valid x-api-key (system_prompt, etc.). */
+  extra?: Record<string, unknown>;
+}
+
+/** Mint a LiveKit session token. Moved verbatim from the widget's fetchSession. */
+export async function fetchSession(args: FetchSessionArgs): Promise<SessionInit> {
+  const doFetch = resolveFetch(args.fetch);
+  // The browser's Origin/Referer headers don't survive server-side relays.
+  // Send the page URL explicitly so the backend can record where the session
+  // was initiated regardless of the network path.
+  const originUrl =
+    args.originUrl ??
+    ((typeof window !== "undefined" && window.location?.href) || "");
+
+  const r = await doFetch(`${args.apiUrl}/api/agents/agent-session/`, {
+    method: "POST",
+    headers: buildHeaders(args, { "Content-Type": "application/json" }),
+    body: JSON.stringify({
+      agent: args.agentSlug,
+      origin_url: originUrl,
+      language: args.language,
+      ...(args.extra ?? {}),
+    }),
+  });
+
+  let body: any;
+  try {
+    body = await r.json();
+  } catch {
+    throw new Error(`session request failed (${r.status}): non-JSON response`);
+  }
+
+  if (!r.ok || body?.success === false) {
+    const msg = body?.message || `HTTP ${r.status}`;
+    throw new Error(`session request failed: ${msg}`);
+  }
+
+  const data = body?.data ?? body;
+  if (!data?.livekit_url || !data?.token) {
+    throw new Error(
+      `session response missing livekit_url/token (got keys: ${Object.keys(
+        data || {},
+      ).join(",")})`,
+    );
+  }
+  return data as SessionInit;
+}

package/src/core/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Cross-cutting types shared between the headless core, the prebuilt UI, and
+ * external SDK consumers. Kept free of any DOM or LiveKit imports so this
+ * module is safe to import from anywhere (including Node).
+ */
+
+/** Visual state of the agent orb / call indicator. */
+export type OrbState =
+  | "idle"
+  | "listening"
+  | "speaking"
+  | "connecting"
+  | "thinking";
+
+/** Shape returned by Django's `POST /api/agents/agent-session/`. */
+export interface SessionInit {
+  token: string;
+  livekit_url: string;
+  room_name: string;
+  participant_identity: string;
+  expires_in_seconds: number;
+  session_id: string;
+  character_slug: string;
+  system_prompt: string;
+  greeting: string;
+  voice_inference_url: string;
+}
+
+/** High-level connection lifecycle phase, surfaced via the `connection` event. */
+export type ConnectionPhase =
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "disconnected"
+  | "failed";
+
+/**
+ * Which call controls the UI should enable. Replaces the direct
+ * `refs.startBtn.disabled = …` side effects the controller used to perform.
+ */
+export interface ControlsState {
+  canStart: boolean;
+  canMute: boolean;
+  canEnd: boolean;
+}
+
+/**
+ * DeepFilterNet3 asset overrides. Mirrors the widget's boot config exactly,
+ * including precedence: `wasmUrl`/`onnxUrl` take priority over `cdnUrl`.
+ * Passed to the voice controller per-instance (no module-level globals) so
+ * multiple agents can coexist on one page.
+ */
+export interface DeepFilterUrls {
+  /** Base CDN URL; the package appends `/v2/pkg/df_bg.wasm` etc. Empty = default. */
+  cdnUrl?: string;
+  /** Direct URL to `df_bg.wasm`. Takes precedence over `cdnUrl`. */
+  wasmUrl?: string;
+  /** Direct URL to `DeepFilterNet3_onnx.tar.gz`. Takes precedence over `cdnUrl`. */
+  onnxUrl?: string;
+  /** Where the DeepFilterNet3 ESM module is loaded from. Empty = esm.sh default. */
+  moduleUrl?: string;
+}
+
+/** Default DeepFilterNet3 ESM module mirror (esm.sh) when none is configured. */
+export const DEFAULT_DEEPFILTER_MODULE_URL =
+  "https://esm.sh/deepfilternet3-noise-filter@1.2.1";