@fiodos/web-core 0.1.0

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

@@ -0,0 +1,23 @@
+/**
+ * Default Fiodos telemetry adapter (web) — identical wire contract to the
+ * React / React Native ones. Maps the SDK's agent events to the backend's
+ * privacy-safe usage events and ships them to POST /v1/agent/events.
+ *
+ * Privacy: ONLY the event type, the action intent and an opaque session id
+ * leave the browser. Never any message, transcript or context content.
+ */
+import type { TelemetryAdapter } from '@fiodos/core';
+export interface FiodosTelemetryOptions {
+    baseUrl: string;
+    /** Client API key sent as x-api-key (same contract as the backend client). */
+    apiKey?: string;
+    /** End-user id sent as x-user-id (rate-limit correlation). */
+    getUserId?: () => string | null;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Max ms to buffer events before flushing (default 4000). */
+    flushIntervalMs?: number;
+    /** Max events buffered before an immediate flush (default 20). */
+    maxBatch?: number;
+}
+export declare function createFiodosTelemetry(options: FiodosTelemetryOptions): TelemetryAdapter;

package/dist/esm/api/backendTelemetry.js

@@ -0,0 +1,77 @@
+function mapEvent(params) {
+    const intent = params.intentDetected ?? null;
+    const sessionId = params.sessionId ?? null;
+    switch (params.eventType) {
+        case 'agent_session_started':
+            return [{ type: 'session', session_id: sessionId }];
+        case 'action_executed': {
+            const events = [{ type: 'action', intent, session_id: sessionId }];
+            const confirmed = params.actionExecuted != null &&
+                params.actionExecuted.confirmed === true;
+            if (confirmed) {
+                events.push({ type: 'confirmation_completed', intent, session_id: sessionId });
+            }
+            return events;
+        }
+        case 'action_confirmation_requested':
+            return [{ type: 'confirmation_requested', intent, session_id: sessionId }];
+        default:
+            return [];
+    }
+}
+export function createFiodosTelemetry(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    const flushIntervalMs = options.flushIntervalMs ?? 4000;
+    const maxBatch = options.maxBatch ?? 20;
+    let queue = [];
+    let timer = null;
+    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 ?? {}),
+        };
+    }
+    function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (queue.length === 0)
+            return;
+        const batch = queue;
+        queue = [];
+        void (async () => {
+            try {
+                await fetch(`${baseUrl}/v1/agent/events`, {
+                    method: 'POST',
+                    headers: buildHeaders(),
+                    body: JSON.stringify({ events: batch }),
+                });
+            }
+            catch {
+                /* drop — analytics are best-effort */
+            }
+        })();
+    }
+    function scheduleFlush() {
+        if (timer)
+            return;
+        timer = setTimeout(flush, flushIntervalMs);
+    }
+    return {
+        logEvent(params) {
+            const mapped = mapEvent(params);
+            if (mapped.length === 0)
+                return;
+            for (const ev of mapped)
+                queue.push(ev);
+            if (queue.length >= maxBatch)
+                flush();
+            else
+                scheduleFlush();
+        },
+    };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Client self-bootstrap helpers — the web equivalent of what @fiodos/react's
+ * <FiodosAgent/> does internally:
+ *
+ *   1. fetchClientManifest()  → GET  /v1/client/manifest  (by x-api-key)
+ *      so a drop-in never forces the developer to paste the manifest JSON.
+ *   2. sendOrbSeen()          → POST /v1/client/orb-seen   (by x-api-key)
+ *      the heartbeat the dashboard "Conexión" step waits on to prove the orb
+ *      actually booted inside the running app (not merely that a manifest was
+ *      published). Every web binding (Vue/Svelte/Angular) inherits this through
+ *      createFiodosAgent, so the dashboard detects the orb on ALL of them.
+ *
+ * No client source code is ever sent — only the API key header.
+ */
+import type { AppManifest } from '@fiodos/core';
+/**
+ * Default public Fiodos backend, mirrored from @fiodos/react's DEFAULT_API_URL.
+ * A drop-in that only receives an apiKey talks to this unless apiUrl is given.
+ */
+export declare const DEFAULT_WEB_API_URL = "https://api.fyodos.com";
+export type ManifestBootstrapStatus = 'ready' | 'no-manifest';
+export interface ManifestBootstrapResult {
+    status: ManifestBootstrapStatus;
+    manifest: AppManifest | null;
+}
+/**
+ * Fetch the published manifest by API key. Throws a descriptive Error on a
+ * rejected key / network failure so a silent orb is never a mystery (same
+ * philosophy as the React drop-in). Returns `{ status: 'no-manifest' }` when
+ * the project exists but nothing has been published yet.
+ */
+export declare function fetchClientManifest(opts: {
+    baseUrl: string;
+    apiKey: string;
+}): Promise<ManifestBootstrapResult>;
+/**
+ * Best-effort heartbeat proving the orb booted. Never throws and never blocks
+ * the orb — failures are swallowed (the dashboard simply won't flip to ✓).
+ */
+export declare function sendOrbSeen(opts: {
+    baseUrl: string;
+    apiKey: string;
+    platform?: string;
+}): Promise<void>;

package/dist/esm/api/clientBootstrap.js

@@ -0,0 +1,63 @@
+/**
+ * Default public Fiodos backend, mirrored from @fiodos/react's DEFAULT_API_URL.
+ * A drop-in that only receives an apiKey talks to this unless apiUrl is given.
+ */
+export const DEFAULT_WEB_API_URL = 'https://api.fyodos.com';
+function trimUrl(baseUrl) {
+    return baseUrl.replace(/\/$/, '');
+}
+/**
+ * Fetch the published manifest by API key. Throws a descriptive Error on a
+ * rejected key / network failure so a silent orb is never a mystery (same
+ * philosophy as the React drop-in). Returns `{ status: 'no-manifest' }` when
+ * the project exists but nothing has been published yet.
+ */
+export async function fetchClientManifest(opts) {
+    const baseUrl = trimUrl(opts.baseUrl);
+    if (!opts.apiKey) {
+        throw new Error('[fyodos] A drop-in agent requires an apiKey. Set it to the project key ' +
+            'from your Fiodos dashboard (e.g. VITE_FYODOS_API_KEY).');
+    }
+    const res = await fetch(`${baseUrl}/v1/client/manifest`, {
+        method: 'GET',
+        headers: { 'x-api-key': opts.apiKey },
+    });
+    if (!res.ok) {
+        if (res.status === 401) {
+            throw new Error(`[fyodos] The orb did not load: the API key was rejected (HTTP 401) by ${baseUrl}. ` +
+                'Check that your FYODOS API key matches the current project key in the dashboard ' +
+                '(a deleted/recreated project gets a NEW key).');
+        }
+        throw new Error(`[fyodos] The orb did not load: could not fetch the manifest (HTTP ${res.status}) from ${baseUrl}.`);
+    }
+    const data = (await res.json());
+    if (!data.manifest) {
+        return { status: 'no-manifest', manifest: null };
+    }
+    return { status: 'ready', manifest: data.manifest };
+}
+function detectPlatform() {
+    if (typeof navigator !== 'undefined' && /Mobi|Android|iPhone|iPad/i.test(navigator.userAgent)) {
+        return 'web-mobile';
+    }
+    return 'web';
+}
+/**
+ * Best-effort heartbeat proving the orb booted. Never throws and never blocks
+ * the orb — failures are swallowed (the dashboard simply won't flip to ✓).
+ */
+export async function sendOrbSeen(opts) {
+    if (!opts.apiKey)
+        return;
+    const baseUrl = trimUrl(opts.baseUrl);
+    try {
+        await fetch(`${baseUrl}/v1/client/orb-seen`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'x-api-key': opts.apiKey },
+            body: JSON.stringify({ platform: opts.platform ?? detectPlatform() }),
+        });
+    }
+    catch {
+        /* heartbeat is best-effort; never block the orb on it */
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Typed agent API errors — shared by every web framework binding. Identical
+ * contract to @fiodos/react's errors so the orchestrator can branch on codes.
+ */
+export type AgentApiErrorCode = 'timeout' | 'cancelled' | 'network' | 'unauthorized' | 'rate_limited' | 'quota_exceeded' | 'not_found' | 'server_error' | 'invalid_response' | 'unknown';
+export declare class AgentApiError extends Error {
+    readonly code: AgentApiErrorCode;
+    readonly status?: number;
+    constructor(code: AgentApiErrorCode, message?: string, status?: number);
+}
+export declare function isAgentApiError(value: unknown): value is AgentApiError;

package/dist/esm/api/errors.js

@@ -0,0 +1,11 @@
+export class AgentApiError extends Error {
+    constructor(code, message, status) {
+        super(message ?? code);
+        this.name = 'AgentApiError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isAgentApiError(value) {
+    return value instanceof AgentApiError;
+}

package/dist/esm/bridge/createBridge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bridge pattern — connect SDK action handlers to app state that lives in a
+ * framework's reactive store (Pinia, Svelte stores, Angular services…), which
+ * cannot be referenced from a plain handler function. Framework-agnostic.
+ */
+export interface Bridge<T extends object> {
+    /** Debug name surfaced in error messages. */
+    readonly name: string;
+    set(impl: T | null): void;
+    /** Current implementation, or null if the app has not registered it yet. */
+    get(): T | null;
+}
+export declare function createBridge<T extends object>(name?: string): Bridge<T>;

package/dist/esm/bridge/createBridge.js

@@ -0,0 +1,12 @@
+export function createBridge(name = 'bridge') {
+    let current = null;
+    return {
+        name,
+        set(impl) {
+            current = impl;
+        },
+        get() {
+            return current;
+        },
+    };
+}

package/dist/esm/config/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Web SDK configuration — the single place where a web app plugs everything in.
+ * Mirrors @fiodos/react's FiodosWebAgentConfig (same adapters, same lifecycle).
+ * Shared by every framework binding through the AgentController.
+ */
+import type { ActionRegistries, AgentBackendClient, AgentMessages, AppManifest, ConfirmationLexicon, MessageCatalog, NavigationAdapter, Sanitizer, StorageAdapter, TelemetryAdapter, VoiceAdapter } from '@fiodos/core';
+import type { ResolveUiMessagesOptions, WebUiMessages } from '../ui/messages.js';
+export type AgentPhase = 'idle' | 'listening' | 'thinking' | 'speaking' | 'confirming';
+export interface AgentTimings {
+    /** Watchdog: 'thinking' may never outlive this. */
+    thinkingWatchdogMs: number;
+    /** Hard cap on a listening session (seconds). */
+    maxListeningSeconds: number;
+    /** Voice-confirmation listening window after speaking the question. */
+    confirmationVoiceWindowMs: number;
+    /** Transcripts shorter than this are treated as noise. */
+    minTranscriptChars: number;
+}
+export declare const DEFAULT_AGENT_TIMINGS: AgentTimings;
+export type TurnGateVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message?: string;
+};
+export interface FiodosWebAgentConfig {
+    /** The app manifest (validated with validateManifest on mount). */
+    manifest: AppManifest;
+    /** Agent locale (reply language, message catalogs). MANDATORY. */
+    locale: string;
+    /** Speech recognition locale, e.g. 'en-US', 'es-ES'. MANDATORY. */
+    sttLocale: string;
+    /** Device-TTS fallback locale. Defaults to sttLocale. */
+    ttsLocale?: string;
+    navigation: NavigationAdapter;
+    registries: ActionRegistries;
+    backend: AgentBackendClient;
+    voice: VoiceAdapter;
+    storage: StorageAdapter;
+    telemetry?: TelemetryAdapter;
+    /** Host auth check, required by manifest actions declaring requiresAuth. */
+    isAuthenticated?: () => boolean;
+    messages?: {
+        catalogs?: Record<string, MessageCatalog>;
+        overrides?: Partial<AgentMessages>;
+    };
+    uiMessages?: ResolveUiMessagesOptions;
+    confirmationLexicon?: ConfirmationLexicon;
+    getUserContextText?: () => string | null;
+    sanitizer?: Sanitizer;
+    contextMaxChars?: number;
+    routeContextFallback?: (route: string | null) => string | null;
+    gateTurn?: () => TurnGateVerdict;
+    onTurnCompleted?: () => void;
+    onPhaseChange?: (phase: AgentPhase, previous: AgentPhase) => void;
+    /** Error surface. Default: console.error. The orb also shows a transient note. */
+    notifyError?: (message: string) => void;
+    onQuotaExceeded?: () => void;
+    ttsVoice?: string | (() => string | undefined);
+    consentVersion?: number;
+    timings?: Partial<AgentTimings>;
+}
+export type { WebUiMessages };

package/dist/esm/config/types.js

@@ -0,0 +1,6 @@
+export const DEFAULT_AGENT_TIMINGS = {
+    thinkingWatchdogMs: 25000,
+    maxListeningSeconds: 60,
+    confirmationVoiceWindowMs: 8000,
+    minTranscriptChars: 2,
+};

package/dist/esm/context/screenContextStore.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Screen-context store — screens register WHAT IS VISIBLE while mounted; the
+ * agent reads it lazily when a turn is invoked. Framework-agnostic (the same
+ * store the React/React Native bindings use).
+ */
+import type { AgentScreenContext } from '@fiodos/core';
+export interface AgentScreenSnapshot {
+    /** App-defined tag of the screen type (free string, for telemetry/debug). */
+    kind: string;
+    /** Pre-formatted context text for the LLM (the app's own language/wording). */
+    text: string;
+    /** Structured snapshot used by 'execute' actions (target ids, etc.). */
+    context?: AgentScreenContext;
+}
+export interface ScreenContextStore {
+    set(ownerId: symbol, snapshot: AgentScreenSnapshot): void;
+    clear(ownerId: symbol): void;
+    /** Registered text, or the route fallback, or null. */
+    getText(): string | null;
+    /** Structured snapshot or null. */
+    getSnapshot(): AgentScreenSnapshot | null;
+}
+export declare function createScreenContextStore(options: {
+    getCurrentRoute: () => string | null;
+    routeFallback?: (route: string | null) => string | null;
+}): ScreenContextStore;

package/dist/esm/context/screenContextStore.js

@@ -0,0 +1,22 @@
+export function createScreenContextStore(options) {
+    let entry = null;
+    return {
+        set(ownerId, snapshot) {
+            entry = { ownerId, snapshot };
+        },
+        clear(ownerId) {
+            if (entry?.ownerId === ownerId)
+                entry = null;
+        },
+        getText() {
+            const registered = entry?.snapshot.text?.trim();
+            if (registered)
+                return registered;
+            const fallback = options.routeFallback?.(options.getCurrentRoute())?.trim();
+            return fallback || null;
+        },
+        getSnapshot() {
+            return entry?.snapshot ?? null;
+        },
+    };
+}

package/dist/esm/controller/AgentController.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AgentController — the framework-free orchestrator.
+ *
+ * This is the vanilla port of @fiodos/react's `useAgent` hook: it assembles the
+ * @fiodos/core runtime (executor, consent, sanitizer, telemetry, messages,
+ * lexicon, conversation) ONCE, drives the listen → think → (confirm) → speak
+ * state machine, and exposes its state through a `subscribe` listener and
+ * imperative methods. Every framework binding (Vue, Svelte, Angular) wraps the
+ * SAME controller, so the security and reasoning behaviour is identical across
+ * frameworks and matches React / React Native.
+ *
+ * Security invariants (unchanged from the shared core):
+ *  - The MANIFEST decides what needs confirmation, never the LLM.
+ *  - Strict (payment-grade) confirmations still require the exact phrase or a
+ *    deliberate modal tap; a loose "yes" never confirms them.
+ *  - The agent only ever executes actions declared in the manifest.
+ */
+import { type AgentMessages, type ConfirmationLexicon } from '@fiodos/core';
+import { type ScreenContextStore } from '../context/screenContextStore.js';
+import { type AgentPhase, type FiodosWebAgentConfig } from '../config/types.js';
+import { type WebUiMessages } from '../ui/messages.js';
+export interface AgentExchange {
+    userText: string;
+    replyText: string;
+}
+/** The reactive snapshot every framework binding renders. */
+export interface AgentState {
+    phase: AgentPhase;
+    interimText: string;
+    volumeLevel: number;
+    showWaveform: boolean;
+    showThinking: boolean;
+    isBusy: boolean;
+    isListening: boolean;
+    lastExchange: AgentExchange | null;
+    /** Confirmation question to show in the modal, or null. */
+    confirmationMessage: string | null;
+    /** Visible-only hint for strict actions (the exact phrase), or null. */
+    confirmationVoiceHint: string | null;
+    consentModalVisible: boolean;
+    /** Mic denied/unusable: the orb should fall back to the keyboard channel. */
+    voiceBlocked: boolean;
+}
+export declare class AgentController {
+    readonly config: FiodosWebAgentConfig;
+    readonly messages: AgentMessages;
+    readonly ui: WebUiMessages;
+    readonly lexicon: ConfirmationLexicon;
+    readonly screenStore: ScreenContextStore;
+    private readonly sanitizer;
+    private readonly telemetry;
+    private readonly consent;
+    private readonly executor;
+    private readonly timings;
+    private readonly ttsLocale;
+    private readonly speech;
+    private readonly notifyError;
+    private enabled;
+    private phase;
+    private lastExchange;
+    private confirmationMessage;
+    private confirmationVoiceHint;
+    private consentModalVisible;
+    private readonly sessionId;
+    private sessionStarted;
+    private readonly conversation;
+    private pending;
+    private confirmationReasked;
+    private confirmationVoiceActive;
+    private silentTurn;
+    private voiceBlocked;
+    private abort;
+    private watchdog;
+    private confirmWindow;
+    private pendingConsentIntent;
+    private readonly listeners;
+    private unsubscribeSpeech;
+    constructor(config: FiodosWebAgentConfig);
+    getState(): AgentState;
+    /** Whether speech recognition can actually run (API present AND mic not denied). */
+    get voiceAvailable(): boolean;
+    /** Unlock audio playback inside a user gesture (orb tap) so the spoken reply
+     *  is allowed/audible on mobile browsers. Must be called synchronously from
+     *  the tap handler, before any await. No-op where unnecessary. */
+    primeAudio(): void;
+    /** Flag the mic as denied/unusable (called on a permission error or upfront
+     *  permission detection) so the orb routes taps to the keyboard instead. */
+    markVoiceBlocked(blocked: boolean): void;
+    subscribe(listener: (state: AgentState) => void): () => void;
+    private emit;
+    setEnabled(value: boolean): void;
+    private getTtsVoice;
+    private setPhase;
+    private clearWatchdog;
+    private clearConfirmWindow;
+    private speakReply;
+    private beginConfirmationVoiceWindow;
+    confirmPendingAction(): Promise<void>;
+    cancelPendingAction(): void;
+    private handleConfirmationTranscript;
+    private handleTranscript;
+    private onTranscript;
+    private onSpeechError;
+    private beginListening;
+    toggleListening(): Promise<void>;
+    submitTextTurn(text: string, options?: {
+        speak?: boolean;
+    }): Promise<void>;
+    acceptConsent(): Promise<void>;
+    declineConsent(): void;
+    cancelAll(): void;
+    /** Best-effort backend warm-up (cold-start mitigation). */
+    warmUp(): void;
+    dispose(): void;
+}