@fiodos/web-core 0.1.0

package/dist/esm/adapters/webVoiceAdapter.js

@@ -0,0 +1,474 @@
+import { detectWakePhrase } from '@fiodos/core';
+function getRecognitionCtor() {
+    if (typeof window === 'undefined')
+        return null;
+    const w = window;
+    return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+/**
+ * iOS Safari/WebKit: continuous passive recognition is not viable (the OS does
+ * not allow background-style mic streaming from a web page, and Web Speech is
+ * effectively unavailable). We refuse wake-word there rather than fake passive
+ * listening the browser actually blocks — push-to-talk / text stay available.
+ */
+function isIosWeb() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const ua = navigator.userAgent || '';
+    const iOSDevice = /iPad|iPhone|iPod/.test(ua);
+    // iPadOS 13+ reports as Mac; detect touch + Mac to be safe.
+    const iPadOS = /Macintosh/.test(ua) &&
+        typeof document !== 'undefined' &&
+        'ontouchend' in document;
+    return iOSDevice || iPadOS;
+}
+export function createWebVoiceAdapter(options = {}) {
+    const Ctor = getRecognitionCtor();
+    let recognition = null;
+    let finalTranscript = '';
+    let stopTimer = null;
+    let aborted = false;
+    let settled = false;
+    let audioEl = null;
+    // ── Wake-word state (separate recognition instance; the browser allows only
+    // one active session, so push-to-talk stops wake first). Desktop-only:
+    // foreground tab while the page is visible — there is no passive background
+    // listening on the web by browser design. ───────────────────────────────────
+    let wakeRec = null;
+    let wakeListening = false;
+    let wakeDetected = false;
+    let wakePhrases = [];
+    let wakeLocale = '';
+    let wakeEvents = null;
+    let wakeRestartTimer = null;
+    function clearWakeRestart() {
+        if (wakeRestartTimer) {
+            clearTimeout(wakeRestartTimer);
+            wakeRestartTimer = null;
+        }
+    }
+    function teardownWake() {
+        clearWakeRestart();
+        if (wakeRec) {
+            wakeRec.onresult = null;
+            wakeRec.onerror = null;
+            wakeRec.onend = null;
+            wakeRec.onstart = null;
+            try {
+                wakeRec.abort();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        wakeRec = null;
+    }
+    function scheduleWakeRestart() {
+        clearWakeRestart();
+        if (!wakeListening || wakeDetected)
+            return;
+        wakeRestartTimer = setTimeout(() => {
+            wakeRestartTimer = null;
+            if (wakeListening && !wakeDetected)
+                startWakeSession();
+        }, 600);
+    }
+    function startWakeSession() {
+        const Ctor2 = getRecognitionCtor();
+        if (!Ctor2 || !wakeListening || wakeDetected)
+            return;
+        // PRIVACY — HONEST LIMITATION (web only): the Web Speech API has NO
+        // on-device mode. On Chrome/Edge the passive audio is sent to the BROWSER
+        // VENDOR's cloud speech service (e.g. Google) for transcription — unlike the
+        // native SDKs, the web wake-word can NOT keep the passive audio on-device.
+        // It only runs while the tab is visible, behind the developer toggle + the
+        // user's explicit hands-free consent, and the consent copy must disclose
+        // this. Fiodos itself still never receives the passive audio (only the
+        // command text after the phrase).
+        // Only run while the tab is visible (honest: no background listening).
+        if (typeof document !== 'undefined' && document.hidden) {
+            scheduleWakeRestart();
+            return;
+        }
+        const rec = new Ctor2();
+        wakeRec = rec;
+        rec.lang = wakeLocale;
+        rec.continuous = true;
+        rec.interimResults = true;
+        rec.maxAlternatives = 1;
+        rec.onresult = (event) => {
+            if (!wakeListening || wakeDetected)
+                return;
+            let text = '';
+            for (let i = 0; i < event.results.length; i += 1) {
+                const result = event.results[i];
+                if (!result)
+                    continue;
+                const alt = result[0];
+                text = `${text} ${alt?.transcript ?? ''}`.trim();
+            }
+            const match = detectWakePhrase(text, wakePhrases);
+            if (!match.matched)
+                return;
+            wakeDetected = true;
+            const events = wakeEvents;
+            teardownWake();
+            events?.onDetected(match.command);
+        };
+        rec.onerror = (event) => {
+            if (event.error === 'aborted' || event.error === 'no-speech') {
+                return; // transient — onend will restart
+            }
+            if (!wakeListening || wakeDetected)
+                return;
+            wakeEvents?.onError?.(new Error(event.error || 'wake recognition error'));
+        };
+        rec.onend = () => {
+            if (!wakeListening || wakeDetected)
+                return;
+            // Browser ended the session (silence / time) — restart while listening.
+            scheduleWakeRestart();
+        };
+        try {
+            rec.start();
+        }
+        catch {
+            scheduleWakeRestart();
+        }
+    }
+    // WebAudio playback: survives the autoplay-after-await gate AND ignores the
+    // iOS hardware mute switch (an <audio> element does not), so the assistant's
+    // reply is actually audible on phones. The context is unlocked on the orb
+    // tap via primePlayback(); decoded MP3s play through it.
+    let audioCtx = null;
+    let currentSource = null;
+    function getAudioCtxCtor() {
+        if (typeof window === 'undefined')
+            return null;
+        const w = window;
+        return w.AudioContext ?? w.webkitAudioContext ?? null;
+    }
+    function ensureAudioCtx() {
+        if (audioCtx)
+            return audioCtx;
+        const Ctor = getAudioCtxCtor();
+        if (!Ctor)
+            return null;
+        try {
+            audioCtx = new Ctor();
+        }
+        catch {
+            audioCtx = null;
+        }
+        return audioCtx;
+    }
+    function base64ToArrayBuffer(base64) {
+        const binary = atob(base64);
+        const len = binary.length;
+        const bytes = new Uint8Array(len);
+        for (let i = 0; i < len; i += 1)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes.buffer;
+    }
+    function stopWebAudioSource() {
+        if (currentSource) {
+            try {
+                currentSource.onended = null;
+                currentSource.stop();
+            }
+            catch {
+                /* already stopped */
+            }
+            currentSource = null;
+        }
+    }
+    async function playViaWebAudio(base64) {
+        const ctx = ensureAudioCtx();
+        if (!ctx)
+            return false;
+        try {
+            if (ctx.state === 'suspended')
+                await ctx.resume();
+            const decoded = await ctx.decodeAudioData(base64ToArrayBuffer(base64));
+            return await new Promise((resolve) => {
+                stopWebAudioSource();
+                const source = ctx.createBufferSource();
+                currentSource = source;
+                source.buffer = decoded;
+                source.connect(ctx.destination);
+                source.onended = () => {
+                    source.onended = null;
+                    if (currentSource === source)
+                        currentSource = null;
+                    resolve(true);
+                };
+                source.start();
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    function clearStopTimer() {
+        if (stopTimer) {
+            clearTimeout(stopTimer);
+            stopTimer = null;
+        }
+    }
+    function teardownRecognition() {
+        clearStopTimer();
+        if (recognition) {
+            recognition.onresult = null;
+            recognition.onerror = null;
+            recognition.onend = null;
+            recognition.onstart = null;
+        }
+        recognition = null;
+    }
+    return {
+        isRecognitionAvailable() {
+            return Ctor != null;
+        },
+        async startListening(opts, events) {
+            if (!Ctor) {
+                events.onError?.(new Error('SpeechRecognition unavailable in this browser'));
+                return;
+            }
+            // Push-to-talk and wake-word share the single browser recognizer: stop
+            // passive listening first so the explicit turn owns the mic.
+            if (wakeListening) {
+                wakeListening = false;
+                wakeDetected = false;
+                wakeEvents = null;
+                teardownWake();
+            }
+            if (recognition) {
+                aborted = true;
+                try {
+                    recognition.abort();
+                }
+                catch {
+                    /* ignore */
+                }
+                teardownRecognition();
+            }
+            finalTranscript = '';
+            aborted = false;
+            settled = false;
+            const rec = new Ctor();
+            recognition = rec;
+            rec.lang = opts.locale;
+            rec.continuous = opts.continuous ?? true;
+            rec.interimResults = true;
+            rec.maxAlternatives = 1;
+            rec.onresult = (event) => {
+                let interim = '';
+                for (let i = event.resultIndex; i < event.results.length; i += 1) {
+                    const result = event.results[i];
+                    if (!result)
+                        continue;
+                    const alt = result[0];
+                    const transcript = alt?.transcript ?? '';
+                    if (result.isFinal) {
+                        finalTranscript = `${finalTranscript} ${transcript}`.trim();
+                    }
+                    else {
+                        interim = `${interim} ${transcript}`.trim();
+                    }
+                }
+                const combined = `${finalTranscript} ${interim}`.trim();
+                if (combined)
+                    events.onInterim?.(combined);
+            };
+            rec.onerror = (event) => {
+                if (event.error === 'aborted' || aborted) {
+                    return;
+                }
+                if (event.error === 'no-speech') {
+                    return;
+                }
+                settled = true;
+                events.onError?.(new Error(event.error || 'speech recognition error'));
+            };
+            rec.onend = () => {
+                clearStopTimer();
+                const wasAborted = aborted;
+                const text = finalTranscript.trim();
+                teardownRecognition();
+                if (settled) {
+                    events.onEnd?.();
+                    return;
+                }
+                if (wasAborted) {
+                    events.onEnd?.();
+                    return;
+                }
+                if (text) {
+                    events.onFinal?.(text);
+                }
+                else {
+                    events.onEnd?.();
+                }
+            };
+            try {
+                rec.start();
+            }
+            catch (e) {
+                teardownRecognition();
+                events.onError?.(e);
+                return;
+            }
+            if (opts.maxSeconds && opts.maxSeconds > 0) {
+                stopTimer = setTimeout(() => {
+                    try {
+                        rec.stop();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }, opts.maxSeconds * 1000);
+            }
+        },
+        stopListening() {
+            clearStopTimer();
+            if (recognition) {
+                try {
+                    recognition.stop();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+        cancelListening() {
+            clearStopTimer();
+            aborted = true;
+            if (recognition) {
+                try {
+                    recognition.abort();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+        primePlayback() {
+            // Must run synchronously inside the user gesture (orb tap). Creating /
+            // resuming the AudioContext here grants it permission for the session so
+            // later programmatic playback (after the network round-trip) is allowed
+            // and audible even with the silent switch on.
+            const ctx = ensureAudioCtx();
+            if (!ctx)
+                return;
+            try {
+                if (ctx.state === 'suspended')
+                    void ctx.resume();
+                // A 1-frame silent buffer fully unlocks playback on iOS Safari.
+                const buffer = ctx.createBuffer(1, 1, ctx.sampleRate);
+                const source = ctx.createBufferSource();
+                source.buffer = buffer;
+                source.connect(ctx.destination);
+                source.start(0);
+            }
+            catch {
+                /* best-effort unlock */
+            }
+        },
+        async playAudioBase64Mp3(base64) {
+            if (typeof window === 'undefined')
+                return;
+            this.stopPlayback();
+            // Preferred path: WebAudio (audible on mobile + survives the async gate).
+            if (await playViaWebAudio(base64))
+                return;
+            // Fallback: <audio> element (desktop browsers without a usable context).
+            if (typeof Audio === 'undefined')
+                return;
+            return new Promise((resolve) => {
+                try {
+                    const el = new Audio(`data:audio/mp3;base64,${base64}`);
+                    audioEl = el;
+                    const done = () => {
+                        el.onended = null;
+                        el.onerror = null;
+                        if (audioEl === el)
+                            audioEl = null;
+                        resolve();
+                    };
+                    el.onended = done;
+                    el.onerror = done;
+                    void el.play().catch(() => done());
+                }
+                catch {
+                    resolve();
+                }
+            });
+        },
+        async speakWithDeviceTts(text, ttsOptions) {
+            if (options.disableDeviceTtsFallback)
+                return;
+            if (typeof window === 'undefined' || !window.speechSynthesis)
+                return;
+            return new Promise((resolve) => {
+                try {
+                    const utter = new SpeechSynthesisUtterance(text);
+                    utter.lang = ttsOptions.locale;
+                    utter.onend = () => resolve();
+                    utter.onerror = () => resolve();
+                    window.speechSynthesis.speak(utter);
+                }
+                catch {
+                    resolve();
+                }
+            });
+        },
+        stopPlayback() {
+            stopWebAudioSource();
+            if (audioEl) {
+                try {
+                    audioEl.pause();
+                }
+                catch {
+                    /* ignore */
+                }
+                audioEl = null;
+            }
+            if (typeof window !== 'undefined' && window.speechSynthesis) {
+                try {
+                    window.speechSynthesis.cancel();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+        // ── Wake-word ("Oye Fiodos") — DESKTOP-ONLY honest support ──────────────────
+        // Real on desktop browsers with Web Speech (Chrome/Edge) while the tab is
+        // active/visible. Refused on iOS web (no usable continuous STT) and where the
+        // API is absent — we never fake passive listening the browser blocks.
+        supportsWakeWordDetection() {
+            return Ctor != null && !isIosWeb();
+        },
+        isWakeWordListening() {
+            return wakeListening;
+        },
+        async startWakeWordDetection(opts, events) {
+            if (!Ctor || isIosWeb()) {
+                events.onError?.(new Error('wake_word_unsupported'));
+                return;
+            }
+            wakePhrases = opts.phrases;
+            wakeLocale = opts.locale;
+            wakeEvents = events;
+            wakeListening = true;
+            wakeDetected = false;
+            startWakeSession();
+        },
+        stopWakeWordDetection() {
+            wakeListening = false;
+            wakeDetected = false;
+            wakeEvents = null;
+            teardownWake();
+        },
+    };
+}

package/dist/esm/api/backendClient.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTTP client for the Fiodos backend — implements @fiodos/core's
+ * AgentBackendClient. Identical wire contract to @fiodos/react and
+ * @fiodos/react-native (POST /assistant/chat, /assistant/preview-tts, /health,
+ * /v1/client/config), so every framework talks to the SAME backend the SAME
+ * way. The only platform dependency is `fetch` + `AbortController` (native in
+ * the browser). No client source code is ever sent — only the manifest payload.
+ */
+import { type AgentBackendClient, type AppManifest } from '@fiodos/core';
+export interface FiodosBackendClientOptions {
+    baseUrl: string;
+    /** Client API key sent as x-api-key. */
+    apiKey?: string;
+    /** End-user id sent as x-user-id (rate limiting / telemetry correlation). */
+    getUserId?: () => string | null;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    turnTimeoutMs?: number;
+    ttsTimeoutMs?: number;
+}
+export declare function createFiodosBackendClient(options: FiodosBackendClientOptions): AgentBackendClient;
+/** Serializes the manifest payloads for a turn request (used by AgentController). */
+export declare function buildManifestPayload(manifest: AppManifest): {
+    appFlow?: string | undefined;
+    appType?: string | undefined;
+    manifestVersion: string;
+    manifestRoutes: import("@fiodos/core").SerializedRouteIntent[];
+    manifestActions: import("@fiodos/core").SerializedActionIntent[];
+    appName: string;
+    appDescription: string;
+};

package/dist/esm/api/backendClient.js

@@ -0,0 +1,178 @@
+/**
+ * HTTP client for the Fiodos backend — implements @fiodos/core's
+ * AgentBackendClient. Identical wire contract to @fiodos/react and
+ * @fiodos/react-native (POST /assistant/chat, /assistant/preview-tts, /health,
+ * /v1/client/config), so every framework talks to the SAME backend the SAME
+ * way. The only platform dependency is `fetch` + `AbortController` (native in
+ * the browser). No client source code is ever sent — only the manifest payload.
+ */
+import { manifestActionsForBackend, manifestRoutesForBackend, parseAgentAction, } from '@fiodos/core';
+import { AgentApiError } from './errors.js';
+const DEFAULT_TURN_TIMEOUT_MS = 15000;
+const DEFAULT_TTS_TIMEOUT_MS = 12000;
+async function fetchWithTimeout(url, init, timeoutMs, externalSignal) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    if (externalSignal) {
+        if (externalSignal.aborted)
+            controller.abort();
+        else
+            externalSignal.addEventListener('abort', () => controller.abort());
+    }
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (e) {
+        if (timedOut)
+            throw new AgentApiError('timeout');
+        if (externalSignal?.aborted)
+            throw new AgentApiError('cancelled');
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new AgentApiError('network', msg);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function errorFromResponse(res) {
+    let body = {};
+    try {
+        const text = await res.text();
+        if (text)
+            body = JSON.parse(text);
+    }
+    catch {
+        /* unparseable body — classify by status alone */
+    }
+    const detail = typeof body.detail === 'string'
+        ? body.detail
+        : typeof body.error === 'string'
+            ? body.error
+            : body.message;
+    if (res.status === 401 || res.status === 403) {
+        return new AgentApiError('unauthorized', detail, res.status);
+    }
+    if (res.status === 429) {
+        const quotaSignal = typeof body.remaining === 'number' || (detail ?? '').toLowerCase().includes('quota');
+        return new AgentApiError(quotaSignal ? 'quota_exceeded' : 'rate_limited', detail, res.status);
+    }
+    if (res.status === 404)
+        return new AgentApiError('not_found', detail, res.status);
+    if (res.status >= 500)
+        return new AgentApiError('server_error', detail, res.status);
+    return new AgentApiError('unknown', detail ?? res.statusText, res.status);
+}
+export function createFiodosBackendClient(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    const turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+    const ttsTimeoutMs = options.ttsTimeoutMs ?? DEFAULT_TTS_TIMEOUT_MS;
+    function buildHeaders() {
+        const userId = options.getUserId?.();
+        return {
+            'Content-Type': 'application/json',
+            ...(options.apiKey ? { 'x-api-key': options.apiKey } : {}),
+            ...(userId ? { 'x-user-id': userId } : {}),
+            ...(options.headers ?? {}),
+        };
+    }
+    return {
+        async sendTurn(request, opts) {
+            const body = {
+                message: request.message.trim(),
+                language: request.language,
+                manifest_version: request.manifestVersion,
+                manifest_routes: request.manifestRoutes,
+                manifest_actions: request.manifestActions,
+                app_name: request.appName,
+                app_description: request.appDescription,
+            };
+            if (request.appType?.trim())
+                body.app_type = request.appType.trim();
+            if (request.appFlow?.trim())
+                body.app_flow = request.appFlow.trim();
+            if (request.voice)
+                body.voice = request.voice;
+            if (request.screenContext?.trim())
+                body.screen_context = request.screenContext.trim();
+            if (request.currentRoute?.trim())
+                body.current_route = request.currentRoute.trim();
+            if (request.conversationHistory?.length) {
+                body.conversation_history = request.conversationHistory.map((t) => ({
+                    role: t.role,
+                    content: t.content.trim(),
+                }));
+            }
+            if (request.conversationSummary?.trim()) {
+                body.conversation_summary = request.conversationSummary.trim();
+            }
+            if (request.llmModel?.trim()) {
+                body.llm_model = request.llmModel.trim();
+            }
+            if (request.sessionId?.trim()) {
+                body.session_id = request.sessionId.trim();
+            }
+            const res = await fetchWithTimeout(`${baseUrl}/assistant/chat`, { method: 'POST', headers: buildHeaders(), body: JSON.stringify(body) }, turnTimeoutMs, opts?.signal);
+            if (!res.ok)
+                throw await errorFromResponse(res);
+            let data;
+            try {
+                data = (await res.json());
+            }
+            catch {
+                throw new AgentApiError('invalid_response');
+            }
+            return {
+                reply: (data.reply ?? '').trim(),
+                audioBase64: data.audio_base64 ?? null,
+                action: parseAgentAction(data.action),
+                wasTruncated: data.was_truncated === true,
+            };
+        },
+        async previewTts(voice, text) {
+            try {
+                const res = await fetchWithTimeout(`${baseUrl}/assistant/preview-tts`, {
+                    method: 'POST',
+                    headers: buildHeaders(),
+                    body: JSON.stringify({ voice, text }),
+                }, ttsTimeoutMs);
+                if (!res.ok)
+                    return null;
+                const data = (await res.json());
+                return data.audio_base64?.length ? data.audio_base64 : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async warmUp() {
+            try {
+                await fetchWithTimeout(`${baseUrl}/health`, { method: 'GET', headers: buildHeaders() }, 5000);
+            }
+            catch {
+                /* best-effort cold-start warm-up */
+            }
+        },
+        async fetchPublishedConfig() {
+            const res = await fetchWithTimeout(`${baseUrl}/v1/client/config`, { method: 'GET', headers: buildHeaders() }, 8000);
+            if (!res.ok)
+                throw await errorFromResponse(res);
+            return (await res.json());
+        },
+    };
+}
+/** Serializes the manifest payloads for a turn request (used by AgentController). */
+export function buildManifestPayload(manifest) {
+    return {
+        manifestVersion: manifest.version,
+        manifestRoutes: manifestRoutesForBackend(manifest),
+        manifestActions: manifestActionsForBackend(manifest),
+        appName: manifest.appName,
+        appDescription: manifest.appDescription,
+        ...(manifest.appType ? { appType: manifest.appType } : {}),
+        ...(manifest.appFlow ? { appFlow: manifest.appFlow } : {}),
+    };
+}