@chanl/widget-sdk 0.2.0-canary.0

package/dist/react/widget.js

@@ -0,0 +1,188 @@
+"use strict";
+'use client';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChanlWidget = ChanlWidget;
+/**
+ * <ChanlWidget> — v1 drop-in React component wrapping the embed loader.
+ *
+ * Minimal by design: takes props, calls `ChanlChat.init()` on mount,
+ * `ChanlChat.destroy()` on unmount (deferred 150ms to survive React
+ * StrictMode double-mount in dev). No provider, no event bus, no
+ * programmatic API surface on the component itself — those land in v2
+ * via `<ChanlProvider>` + `useChanlClient()`.
+ *
+ * Identity (`user` + `userHash`) is forwarded to the iframe as URL params.
+ * Compute `userHash` server-side using `computeUserHash` from
+ * `@chanl/widget-sdk/next`:
+ *
+ * ```tsx
+ * // app/dashboard/page.tsx  (React Server Component)
+ * import { computeUserHash } from '@chanl/widget-sdk/next';
+ * import { ChanlWidget } from '@chanl/widget-sdk/react';
+ *
+ * export default async function Page() {
+ *   const user = await getCurrentUser();  // Firebase/Clerk/NextAuth/Auth0/custom
+ *   const userHash = computeUserHash(user.id, process.env.CHANL_IDENTITY_SECRET!);
+ *   return (
+ *     <ChanlWidget
+ *       pubKey={process.env.NEXT_PUBLIC_CHANL_PUB_KEY!}
+ *       agentId="agent_xxx"
+ *       user={{ externalId: user.id, email: user.email, name: user.name }}
+ *       userHash={userHash}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * Performance note: per react-best-practices `rerender-dependencies`,
+ * the re-init effect depends on primitive fields only (`externalId`,
+ * `theme`, etc.), not on the `user` object identity. If you pass a fresh
+ * `user` object on every parent render but the underlying primitives are
+ * stable, the widget will NOT re-init. Other user fields (email, name,
+ * avatarUrl, attributes) are captured at init time from the latest render
+ * — they flow in but do not trigger re-init by themselves.
+ */
+const react_1 = require("react");
+function ChanlWidget(props) {
+    const { pubKey, agentId, user, userHash, baseUrl, chatHost, theme, position, color, branding, agentName, agentSubtitle, agentInitials, agentAvatarUrl, greeting, placeholder, darkBg, privacyUrl, locale, } = props;
+    // Hold the latest config in a ref so the effect body reads the freshest
+    // props even when the effect re-runs for primitive-only dependency changes.
+    const latestPropsRef = (0, react_1.useRef)(props);
+    latestPropsRef.current = props;
+    // Defer destroy by 150ms — StrictMode's intentional double-mount in dev
+    // runs mount → unmount → mount within that window, and the second mount
+    // cancels the pending destroy from the first unmount.
+    const destroyTimer = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        if (typeof window === 'undefined')
+            return;
+        // Cancel any pending destroy from a previous cleanup (StrictMode).
+        if (destroyTimer.current) {
+            clearTimeout(destroyTimer.current);
+            destroyTimer.current = null;
+        }
+        // `cancelled` guards the async loader — if the component unmounts
+        // before the dynamic import resolves (fast navigation), skip init.
+        let cancelled = false;
+        const build = () => {
+            const p = latestPropsRef.current;
+            return {
+                agentId: p.agentId,
+                apiKey: p.pubKey,
+                user: p.user,
+                userHash: p.userHash,
+                baseUrl: p.baseUrl,
+                chatHost: p.chatHost,
+                theme: p.theme,
+                position: p.position,
+                color: p.color,
+                branding: p.branding,
+                agentName: p.agentName,
+                agentSubtitle: p.agentSubtitle,
+                agentInitials: p.agentInitials,
+                agentAvatarUrl: p.agentAvatarUrl,
+                greeting: p.greeting,
+                placeholder: p.placeholder,
+                darkBg: p.darkBg,
+                privacyUrl: p.privacyUrl,
+                locale: p.locale,
+            };
+        };
+        // Lazily load the loader module. Side-effect import runs the IIFE
+        // which registers `window.ChanlChat`. Stays out of the SSR bundle
+        // and avoids leaking `declare global` into type consumers.
+        void Promise.resolve().then(() => __importStar(require('../embed/loader'))).then(() => {
+            if (cancelled)
+                return;
+            const ChanlChat = window.ChanlChat;
+            if (!ChanlChat)
+                return;
+            if (ChanlChat._initialized) {
+                try {
+                    ChanlChat.destroy();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            ChanlChat.init(build());
+        });
+        return () => {
+            cancelled = true;
+            destroyTimer.current = setTimeout(() => {
+                if (typeof window !== 'undefined') {
+                    const live = window.ChanlChat;
+                    if (live && live._initialized) {
+                        try {
+                            live.destroy();
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }
+                }
+                destroyTimer.current = null;
+            }, 150);
+        };
+    }, 
+    // Primitive-only dependencies per react-best-practices `rerender-dependencies`.
+    // Re-init fires when any of these change. Non-primitive user fields
+    // (email, name, avatarUrl, attributes) flow via the ref on the next
+    // init — they don't trigger re-init on their own.
+    [
+        agentId,
+        pubKey,
+        user?.externalId,
+        userHash,
+        baseUrl,
+        chatHost,
+        theme,
+        position,
+        color,
+        branding,
+        agentName,
+        agentSubtitle,
+        agentInitials,
+        agentAvatarUrl,
+        greeting,
+        placeholder,
+        darkBg,
+        privacyUrl,
+        locale,
+    ]);
+    return null;
+}
+//# sourceMappingURL=widget.js.map

package/dist/react/widget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../src/react/widget.tsx"],"names":[],"mappings":"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"}

package/dist/storage/session-storage.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Widget Session Storage — localStorage helpers for the persistent-session
+ * feature (int-050).
+ *
+ * Lifecycle:
+ *   1. Widget loader on host page reads `_chanl_session_{publicKey}_{agentId}`
+ *      on init.
+ *   2. If present, loader passes the token into the iframe URL so the
+ *      chat-client can call GET /interactions/:id/resume.
+ *   3. On createSession or successful resume, the iframe posts the new
+ *      token back to the loader via postMessage; loader writes it.
+ *   4. On 4xx from resume (signature mismatch, expired, deleted), the
+ *      iframe posts `session-token-cleared`; loader clears the key.
+ *
+ * Per-publicKey + per-agent scoping: a single host site can mount multiple
+ * agents (sales + support widgets side-by-side) — each gets its own
+ * resumable session. publicKey is already in loader config; agentId is
+ * already in the widget mount call. No extra wiring needed to namespace.
+ *
+ * Failure mode: localStorage can throw (Safari private mode, quota
+ * exceeded, sandboxed iframe with storage blocked). All three helpers
+ * catch and fail-silent so the widget keeps working — just without
+ * resumability (= fresh session every load, the pre-int-050 behavior).
+ *
+ * Note: these helpers run in the LOADER's host-origin context. The chat
+ * iframe is on a different origin and CANNOT touch this localStorage —
+ * all I/O bounces through postMessage. Anyone tempted to call these from
+ * inside the iframe will succeed locally but the loader won't see the
+ * value because they're separate origin localStorage stores.
+ */
+/**
+ * Read a previously-stored session token. Returns the raw JWT string, or
+ * `null` when no token exists, the storage call throws, or we're in a
+ * non-browser context (SSR).
+ */
+export declare function readSessionToken(publicKey: string, agentId: string): string | null;
+/**
+ * Persist a freshly-issued session token. No-op on storage error so the
+ * widget continues to function (just without resumability on next load).
+ */
+export declare function writeSessionToken(publicKey: string, agentId: string, token: string): void;
+/**
+ * Clear the stored token. Called when the server tells us the token is no
+ * longer valid (403/410/404) or when the host explicitly resets the
+ * conversation via the "New conversation" button.
+ */
+export declare function clearSessionToken(publicKey: string, agentId: string): void;
+//# sourceMappingURL=session-storage.d.ts.map

package/dist/storage/session-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.d.ts","sourceRoot":"","sources":["../../src/storage/session-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOlF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOzF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAO1E"}

package/dist/storage/session-storage.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Widget Session Storage — localStorage helpers for the persistent-session
+ * feature (int-050).
+ *
+ * Lifecycle:
+ *   1. Widget loader on host page reads `_chanl_session_{publicKey}_{agentId}`
+ *      on init.
+ *   2. If present, loader passes the token into the iframe URL so the
+ *      chat-client can call GET /interactions/:id/resume.
+ *   3. On createSession or successful resume, the iframe posts the new
+ *      token back to the loader via postMessage; loader writes it.
+ *   4. On 4xx from resume (signature mismatch, expired, deleted), the
+ *      iframe posts `session-token-cleared`; loader clears the key.
+ *
+ * Per-publicKey + per-agent scoping: a single host site can mount multiple
+ * agents (sales + support widgets side-by-side) — each gets its own
+ * resumable session. publicKey is already in loader config; agentId is
+ * already in the widget mount call. No extra wiring needed to namespace.
+ *
+ * Failure mode: localStorage can throw (Safari private mode, quota
+ * exceeded, sandboxed iframe with storage blocked). All three helpers
+ * catch and fail-silent so the widget keeps working — just without
+ * resumability (= fresh session every load, the pre-int-050 behavior).
+ *
+ * Note: these helpers run in the LOADER's host-origin context. The chat
+ * iframe is on a different origin and CANNOT touch this localStorage —
+ * all I/O bounces through postMessage. Anyone tempted to call these from
+ * inside the iframe will succeed locally but the loader won't see the
+ * value because they're separate origin localStorage stores.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSessionToken = readSessionToken;
+exports.writeSessionToken = writeSessionToken;
+exports.clearSessionToken = clearSessionToken;
+const KEY_PREFIX = '_chanl_session_';
+function makeKey(publicKey, agentId) {
+    return `${KEY_PREFIX}${publicKey}_${agentId}`;
+}
+/**
+ * Read a previously-stored session token. Returns the raw JWT string, or
+ * `null` when no token exists, the storage call throws, or we're in a
+ * non-browser context (SSR).
+ */
+function readSessionToken(publicKey, agentId) {
+    if (typeof window === 'undefined' || !window.localStorage)
+        return null;
+    try {
+        return window.localStorage.getItem(makeKey(publicKey, agentId));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a freshly-issued session token. No-op on storage error so the
+ * widget continues to function (just without resumability on next load).
+ */
+function writeSessionToken(publicKey, agentId, token) {
+    if (typeof window === 'undefined' || !window.localStorage)
+        return;
+    try {
+        window.localStorage.setItem(makeKey(publicKey, agentId), token);
+    }
+    catch {
+        // localStorage quota, sandboxed iframe, etc. Fail silent.
+    }
+}
+/**
+ * Clear the stored token. Called when the server tells us the token is no
+ * longer valid (403/410/404) or when the host explicitly resets the
+ * conversation via the "New conversation" button.
+ */
+function clearSessionToken(publicKey, agentId) {
+    if (typeof window === 'undefined' || !window.localStorage)
+        return;
+    try {
+        window.localStorage.removeItem(makeKey(publicKey, agentId));
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=session-storage.js.map

package/dist/storage/session-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.js","sourceRoot":"","sources":["../../src/storage/session-storage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;AAaH,4CAOC;AAMD,8CAOC;AAOD,8CAOC;AA7CD,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAErC,SAAS,OAAO,CAAC,SAAiB,EAAE,OAAe;IACjD,OAAO,GAAG,UAAU,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,SAAiB,EAAE,OAAe;IACjE,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,SAAiB,EAAE,OAAe,EAAE,KAAa;IACjF,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO;IAClE,IAAI,CAAC;QACH,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,SAAiB,EAAE,OAAe;IAClE,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO;IAClE,IAAI,CAAC;QACH,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Chanl Chat SDK — Standalone types
+ * No external dependencies.
+ */
+export interface ChatClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    /**
+     * Identified end-user. When present, activates the widget identity
+     * path — backend verifies `userHash` as HMAC-SHA256(externalId, secret),
+     * upserts a Customer by externalId, and attaches customer context to the
+     * chat session. Custom attributes flow into the agent prompt as
+     * `{{customer:<key>}}` variables.
+     */
+    user?: ChanlUser;
+    /** HMAC-SHA256 of `user.externalId` using workspace identity secret. */
+    userHash?: string;
+    /**
+     * Stable anon-Lead identifier read from `localStorage._chanl_anon` on the
+     * chat-host iframe origin. Used when `user` is absent to persist memory
+     * across sessions for cold visitors.
+     */
+    anonymousId?: string;
+}
+/**
+ * Identified end-user for the widget identity path (Intercom-style).
+ *
+ * The host app resolves its own user via whatever auth system it already
+ * has (Firebase, Clerk, NextAuth, Auth0, custom) and passes the stable
+ * `externalId`. The `userHash` is computed server-side via
+ * `computeUserHash(externalId, CHANL_IDENTITY_SECRET)` from the
+ * `@chanl/widget-sdk/next` subpath.
+ */
+export interface ChanlUser {
+    /**
+     * Stable external user identifier — any string the host app uses for
+     * the user in its own system (Firebase uid, Auth0 sub, database id, ...).
+     */
+    externalId: string;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    /**
+     * Custom attributes (plan, role, workspace id, etc.). Flow into the
+     * agent prompt as `customer:<key>` variables automatically.
+     */
+    attributes?: Record<string, unknown>;
+}
+export interface CreateSessionInput {
+    systemPrompt?: string;
+    variables?: Record<string, string>;
+    /** @deprecated prefer `user.externalId` for client-side embeds. */
+    customerId?: string;
+    /** HMAC-SHA256 of the identifier (externalId when `user` is present, otherwise customerId). */
+    userHash?: string;
+    /** Identified end-user — activates the widget identity path. */
+    user?: ChanlUser;
+    /**
+     * Anonymous browser identifier (Intercom Lead path). Stable UUID minted in
+     * `localStorage._chanl_anon` on the chat-host iframe origin so cold visitors
+     * persist across sessions even without a verified `user`. Backend upserts a
+     * Customer with `externalId = "anon_<uuid>"`. Ignored when `user` or
+     * `customerId` is present.
+     */
+    anonymousId?: string;
+    metadata?: Record<string, unknown>;
+    toolsetId?: string;
+}
+export interface ChatSession {
+    interactionId: string;
+    sessionId: string;
+    agentId: string;
+    agentName?: string;
+    model?: string;
+    createdAt: string;
+    /**
+     * Signed JWT (HS256) issued by the server. Widget loader stores this in
+     * localStorage keyed by publicKey+agentId and presents it back on resume
+     * calls so the server can verify session ownership. Absent when the
+     * workspace has no identitySecret configured — session still works but
+     * cannot be resumed across host-page refreshes.
+     */
+    sessionToken?: string;
+}
+/**
+ * Response from GET /interactions/:id/resume. Rehydrates the conversation
+ * view + carries a refreshed token (rolling TTL — widget MUST replace its
+ * stored token with the new value).
+ */
+export interface ResumedChatSession extends ChatSession {
+    status: string;
+    messages: Array<{
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+        timestamp?: string;
+    }>;
+    /** Refreshed JWT — overwrite the stored one in localStorage. */
+    sessionToken: string;
+}
+export interface ToolInvocation {
+    toolCallId: string;
+    toolName: string;
+    state: 'call' | 'result';
+    args?: Record<string, unknown>;
+    result?: unknown;
+}
+export interface MessagePart {
+    type: 'text' | 'tool-invocation';
+    text?: string;
+    toolInvocation?: ToolInvocation;
+}
+export interface ChatMessageResponse {
+    sessionId: string;
+    message: string;
+    parts?: MessagePart[];
+    toolCalls?: unknown[];
+    latencyMs?: number;
+}
+export interface WidgetConfig {
+    id: string;
+    agent: {
+        id: string;
+        name: string;
+    };
+    launcher: {
+        position: string;
+        modality: 'voice' | 'chat' | 'both';
+    };
+    style: {
+        primaryColor?: string;
+        backgroundColor?: string;
+        logoUrl?: string;
+        agentAvatar?: string;
+    };
+    banner?: {
+        header?: string;
+        description?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Chanl Chat SDK — Standalone types
+ * No external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/voice/audio-recorder.d.ts

@@ -0,0 +1,43 @@
+export interface AudioRecorderConfig {
+    /** Audio track constraints for getUserMedia */
+    trackConstraints?: MediaTrackConstraints;
+    /** Time slice in milliseconds for data chunks */
+    timeSlice?: number;
+    /** Callback for each chunk of audio data */
+    onData: (data: string) => void;
+    /** Callback for recording state changes */
+    onStateChange?: (state: RecordingState) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+}
+export type RecordingState = 'inactive' | 'recording' | 'paused';
+/**
+ * High-quality audio recorder using extendable-media-recorder
+ * Handles WAV encoding and streaming of audio data
+ */
+export declare class AudioRecorder {
+    private recorder;
+    private stream;
+    private readonly config;
+    constructor({ trackConstraints, timeSlice, onData, onStateChange, onError, }: AudioRecorderConfig);
+    /**
+     * Initialize the WAV encoder and start recording
+     */
+    start(): Promise<void>;
+    /**
+     * Stop recording and cleanup resources
+     */
+    stop(): void;
+    /**
+     * Get current recording state
+     */
+    getState(): RecordingState;
+    /**
+     * Check if currently recording
+     */
+    isRecording(): boolean;
+    private handleDataAvailable;
+    private handleStop;
+    private cleanup;
+}
+//# sourceMappingURL=audio-recorder.d.ts.map

package/dist/voice/audio-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-recorder.d.ts","sourceRoot":"","sources":["../../src/voice/audio-recorder.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,0BAA0B;IAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjE;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAE3C,EACV,gBAA6C,EAC7C,SAAc,EACd,MAAM,EACN,aAAyB,EACzB,OAAoD,GACrD,EAAE,mBAAmB;IAUtB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC5B;;OAEG;IACH,IAAI,IAAI,IAAI;IAcZ;;OAEG;IACH,QAAQ,IAAI,cAAc;IAI1B;;OAEG;IACH,WAAW,IAAI,OAAO;YAIR,mBAAmB;IAajC,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,OAAO;CAiBhB"}

package/dist/voice/audio-recorder.js

@@ -0,0 +1,127 @@
+"use strict";
+/*
+ * AudioRecorder captures microphone audio, down-samples to 16 kHz mono and encodes
+ * to base64-encoded linear16 PCM chunks suitable for the backend.
+ *
+ * Note: implementation keeps things simple; production apps may want to use a
+ * WebAudio AudioWorklet for lower latency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioRecorder = void 0;
+const extendable_media_recorder_1 = require("extendable-media-recorder");
+const extendable_media_recorder_wav_encoder_1 = require("extendable-media-recorder-wav-encoder");
+const utils_1 = require("./utils");
+/**
+ * High-quality audio recorder using extendable-media-recorder
+ * Handles WAV encoding and streaming of audio data
+ */
+class AudioRecorder {
+    constructor({ trackConstraints = { echoCancellation: true }, timeSlice = 10, onData, onStateChange = () => { }, onError = (e) => console.error('[AudioRecorder]', e), }) {
+        this.recorder = null;
+        this.stream = null;
+        this.config = {
+            trackConstraints,
+            timeSlice,
+            onData,
+            onStateChange,
+            onError,
+        };
+    }
+    /**
+     * Initialize the WAV encoder and start recording
+     */
+    async start() {
+        try {
+            // Register WAV encoder if not already registered
+            if (!extendable_media_recorder_1.MediaRecorder.isTypeSupported('audio/wav')) {
+                console.debug("[AudioRecorder] Registering WAV encoder");
+                await (0, extendable_media_recorder_1.register)(await (0, extendable_media_recorder_wav_encoder_1.connect)());
+            }
+            // Get audio stream
+            this.stream = await navigator.mediaDevices.getUserMedia({
+                audio: this.config.trackConstraints,
+            });
+            const micSettings = this.stream?.getAudioTracks()[0].getSettings();
+            console.debug('[AudioRecorder] Mic settings:', micSettings);
+            // Create recorder with WAV encoding
+            this.recorder = new extendable_media_recorder_1.MediaRecorder(this.stream, {
+                mimeType: 'audio/wav',
+            });
+            // Set up event handlers
+            this.recorder.ondataavailable = this.handleDataAvailable.bind(this);
+            this.recorder.onstop = this.handleStop.bind(this);
+            this.recorder.onerror = (event) => this.config.onError(new Error(event.error.message));
+            this.recorder.addEventListener('statechange', () => this.config.onStateChange(this.recorder?.state ?? 'inactive'));
+            // Start recording
+            this.recorder.start(this.config.timeSlice);
+            console.debug('[AudioRecorder] Started recording');
+        }
+        catch (error) {
+            this.config.onError(error instanceof Error ? error : new Error('Failed to start recording'));
+            throw error;
+        }
+    }
+    /**
+     * Stop recording and cleanup resources
+     */
+    stop() {
+        if (!this.recorder)
+            return;
+        try {
+            if (this.recorder.state === 'recording') {
+                this.recorder.stop();
+            }
+            this.cleanup();
+            console.debug('[AudioRecorder] Stopped recording');
+        }
+        catch (error) {
+            this.config.onError(error instanceof Error ? error : new Error('Failed to stop recording'));
+        }
+    }
+    /**
+     * Get current recording state
+     */
+    getState() {
+        return this.recorder?.state ?? 'inactive';
+    }
+    /**
+     * Check if currently recording
+     */
+    isRecording() {
+        return this.recorder?.state === 'recording';
+    }
+    async handleDataAvailable(event) {
+        if (!event.data.size)
+            return;
+        try {
+            const base64 = await (0, utils_1.blobToBase64)(event.data);
+            if (base64) {
+                this.config.onData(base64);
+            }
+        }
+        catch (error) {
+            this.config.onError(error instanceof Error ? error : new Error('Failed to convert audio data'));
+        }
+    }
+    handleStop() {
+        this.cleanup();
+    }
+    cleanup() {
+        // Stop all tracks
+        this.stream?.getTracks().forEach(track => track.stop());
+        this.stream = null;
+        // Clear recorder
+        if (this.recorder) {
+            this.recorder.onstop = null;
+            this.recorder.ondataavailable = null;
+            this.recorder.onerror = null;
+            this.recorder.removeEventListener('dataavailable', this.handleDataAvailable.bind(this));
+            this.recorder.removeEventListener('stop', this.handleStop.bind(this));
+            this.recorder.removeEventListener('error', () => { });
+            this.recorder.removeEventListener('statechange', () => { });
+            this.recorder = null;
+        }
+    }
+}
+exports.AudioRecorder = AudioRecorder;
+//# sourceMappingURL=audio-recorder.js.map