@fiodos/web-core 0.1.0 → 0.1.1

package/dist/cjs/dropin/createFiodosAgent.js

@@ -22,6 +22,7 @@ const webStorageAdapter_1 = require("../adapters/webStorageAdapter");
 const webVoiceAdapter_1 = require("../adapters/webVoiceAdapter");
 const AgentController_1 = require("../controller/AgentController");
 const mountOrb_1 = require("../orb/mountOrb");
+const devErrorBadge_1 = require("../orb/devErrorBadge");
 const clientBootstrap_1 = require("../api/clientBootstrap");
 function defaultNavigate(route) {
     if (typeof window !== 'undefined' && window.location)
@@ -108,9 +109,11 @@ function createFiodosAgent(options) {
             if (cancelled)
                 return null;
             if (result.status === 'no-manifest' || !result.manifest) {
+                const reason = '[fyodos] No hay manifest publicado para esta API key todavía. Ejecuta ' +
+                    '`npx @fiodos/cli analyze . --publish` o publícalo desde el dashboard, y recarga.';
                 // eslint-disable-next-line no-console
-                console.warn('[fyodos] The orb is idle: this project has no published manifest yet. ' +
-                    'Run the analysis from your Fiodos dashboard, then reload.');
+                console.warn(reason);
+                (0, devErrorBadge_1.showOrbDevError)(reason, { baseUrl });
                 return null;
             }
             // Fail loudly here (not deep inside the controller) so onError is precise.
@@ -135,6 +138,7 @@ function createFiodosAgent(options) {
             const error = e instanceof Error ? e : new Error(String(e));
             // eslint-disable-next-line no-console
             console.error(error.message);
+            (0, devErrorBadge_1.showOrbDevError)(error.message, { baseUrl });
             options.onError?.(error);
             return null;
         }

package/dist/cjs/orb/devErrorBadge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dev-only visible failure badge.
+ *
+ * When the orb cannot mount (rejected key, no published manifest, unreachable
+ * backend), the SDK otherwise renders nothing — historically a silent failure
+ * that left developers with no clue WHY the orb never appeared (only a console
+ * line that is easy to miss). This renders a small, dismissible badge where the
+ * orb would be, stating the EXACT, actionable reason.
+ *
+ * Hard rule: this is DEVELOPMENT-ONLY. In production builds the badge never
+ * renders (the orb stays invisible, exactly as before) so end users never see
+ * Fiodos diagnostics. Gating is on `process.env.NODE_ENV === 'production'`,
+ * which every major bundler (Next, Vite, webpack, esbuild) statically replaces.
+ */
+/**
+ * True only in a development build. Bundlers replace `process.env.NODE_ENV`
+ * with a string literal; if `process` is genuinely absent (rare unbundled use)
+ * we default to NOT showing the badge — production safety wins over visibility.
+ */
+export declare function isDevEnvironment(): boolean;
+/**
+ * Mount (or update) the dev error badge. No-op in production, in non-DOM
+ * environments (SSR), or when called repeatedly (the message is updated in
+ * place rather than stacking badges).
+ */
+export declare function showOrbDevError(reason: string, opts?: {
+    baseUrl?: string;
+}): void;

package/dist/cjs/orb/devErrorBadge.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Dev-only visible failure badge.
+ *
+ * When the orb cannot mount (rejected key, no published manifest, unreachable
+ * backend), the SDK otherwise renders nothing — historically a silent failure
+ * that left developers with no clue WHY the orb never appeared (only a console
+ * line that is easy to miss). This renders a small, dismissible badge where the
+ * orb would be, stating the EXACT, actionable reason.
+ *
+ * Hard rule: this is DEVELOPMENT-ONLY. In production builds the badge never
+ * renders (the orb stays invisible, exactly as before) so end users never see
+ * Fiodos diagnostics. Gating is on `process.env.NODE_ENV === 'production'`,
+ * which every major bundler (Next, Vite, webpack, esbuild) statically replaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDevEnvironment = isDevEnvironment;
+exports.showOrbDevError = showOrbDevError;
+const BADGE_ID = 'fiodos-dev-error-badge';
+/**
+ * True only in a development build. Bundlers replace `process.env.NODE_ENV`
+ * with a string literal; if `process` is genuinely absent (rare unbundled use)
+ * we default to NOT showing the badge — production safety wins over visibility.
+ */
+function isDevEnvironment() {
+    try {
+        return process.env.NODE_ENV !== 'production';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mount (or update) the dev error badge. No-op in production, in non-DOM
+ * environments (SSR), or when called repeatedly (the message is updated in
+ * place rather than stacking badges).
+ */
+function showOrbDevError(reason, opts) {
+    if (!isDevEnvironment())
+        return;
+    if (typeof document === 'undefined' || !document.body)
+        return;
+    const message = cleanReason(reason);
+    let badge = document.getElementById(BADGE_ID);
+    if (badge) {
+        const body = badge.querySelector('[data-fiodos-badge-msg]');
+        if (body)
+            body.textContent = message;
+        return;
+    }
+    badge = document.createElement('div');
+    badge.id = BADGE_ID;
+    badge.setAttribute('role', 'alert');
+    badge.style.cssText = [
+        'position:fixed',
+        'bottom:20px',
+        'right:20px',
+        'z-index:2147483000',
+        'max-width:340px',
+        'padding:12px 14px',
+        'border-radius:12px',
+        'background:#1b1b1f',
+        'color:#fff',
+        "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
+        'font-size:13px',
+        'line-height:1.45',
+        'box-shadow:0 8px 28px rgba(0,0,0,0.35)',
+        'border:1px solid rgba(255,255,255,0.12)',
+    ].join(';');
+    const header = document.createElement('div');
+    header.style.cssText =
+        'display:flex;align-items:center;gap:6px;margin-bottom:6px;font-weight:600;color:#ffd166';
+    header.textContent = '◉ Fiodos · el orbe no se montó (solo desarrollo)';
+    const close = document.createElement('button');
+    close.textContent = '×';
+    close.setAttribute('aria-label', 'Cerrar aviso de Fiodos');
+    close.style.cssText = [
+        'margin-left:auto',
+        'background:transparent',
+        'border:0',
+        'color:rgba(255,255,255,0.6)',
+        'font-size:18px',
+        'line-height:1',
+        'cursor:pointer',
+        'padding:0 2px',
+    ].join(';');
+    close.addEventListener('click', () => badge?.remove());
+    header.appendChild(close);
+    const body = document.createElement('div');
+    body.setAttribute('data-fiodos-badge-msg', '');
+    body.textContent = message;
+    const hint = document.createElement('div');
+    hint.style.cssText = 'margin-top:8px;color:rgba(255,255,255,0.55);font-size:11.5px';
+    hint.textContent =
+        'Comprueba que la API key y la URL de tu app son las del MISMO proyecto donde publicaste. Este aviso solo aparece en desarrollo.';
+    badge.appendChild(header);
+    badge.appendChild(body);
+    badge.appendChild(hint);
+    document.body.appendChild(badge);
+}
+/** Strip the internal "[fyodos]" prefix so the badge reads cleanly to a human. */
+function cleanReason(reason) {
+    return reason.replace(/^\[fyodos\]\s*/i, '').trim() || 'No se pudo montar el orbe.';
+}

package/dist/esm/dropin/createFiodosAgent.js

@@ -19,6 +19,7 @@ import { createWebStorageAdapter } from '../adapters/webStorageAdapter.js';
 import { createWebVoiceAdapter } from '../adapters/webVoiceAdapter.js';
 import { AgentController } from '../controller/AgentController.js';
 import { mountOrb } from '../orb/mountOrb.js';
+import { showOrbDevError } from '../orb/devErrorBadge.js';
 import { DEFAULT_WEB_API_URL, fetchClientManifest, sendOrbSeen } from '../api/clientBootstrap.js';
 function defaultNavigate(route) {
     if (typeof window !== 'undefined' && window.location)
@@ -105,9 +106,11 @@ export function createFiodosAgent(options) {
             if (cancelled)
                 return null;
             if (result.status === 'no-manifest' || !result.manifest) {
+                const reason = '[fyodos] No hay manifest publicado para esta API key todavía. Ejecuta ' +
+                    '`npx @fiodos/cli analyze . --publish` o publícalo desde el dashboard, y recarga.';
                 // eslint-disable-next-line no-console
-                console.warn('[fyodos] The orb is idle: this project has no published manifest yet. ' +
-                    'Run the analysis from your Fiodos dashboard, then reload.');
+                console.warn(reason);
+                showOrbDevError(reason, { baseUrl });
                 return null;
             }
             // Fail loudly here (not deep inside the controller) so onError is precise.
@@ -132,6 +135,7 @@ export function createFiodosAgent(options) {
             const error = e instanceof Error ? e : new Error(String(e));
             // eslint-disable-next-line no-console
             console.error(error.message);
+            showOrbDevError(error.message, { baseUrl });
             options.onError?.(error);
             return null;
         }

package/dist/esm/orb/devErrorBadge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dev-only visible failure badge.
+ *
+ * When the orb cannot mount (rejected key, no published manifest, unreachable
+ * backend), the SDK otherwise renders nothing — historically a silent failure
+ * that left developers with no clue WHY the orb never appeared (only a console
+ * line that is easy to miss). This renders a small, dismissible badge where the
+ * orb would be, stating the EXACT, actionable reason.
+ *
+ * Hard rule: this is DEVELOPMENT-ONLY. In production builds the badge never
+ * renders (the orb stays invisible, exactly as before) so end users never see
+ * Fiodos diagnostics. Gating is on `process.env.NODE_ENV === 'production'`,
+ * which every major bundler (Next, Vite, webpack, esbuild) statically replaces.
+ */
+/**
+ * True only in a development build. Bundlers replace `process.env.NODE_ENV`
+ * with a string literal; if `process` is genuinely absent (rare unbundled use)
+ * we default to NOT showing the badge — production safety wins over visibility.
+ */
+export declare function isDevEnvironment(): boolean;
+/**
+ * Mount (or update) the dev error badge. No-op in production, in non-DOM
+ * environments (SSR), or when called repeatedly (the message is updated in
+ * place rather than stacking badges).
+ */
+export declare function showOrbDevError(reason: string, opts?: {
+    baseUrl?: string;
+}): void;

package/dist/esm/orb/devErrorBadge.js

@@ -0,0 +1,100 @@
+/**
+ * Dev-only visible failure badge.
+ *
+ * When the orb cannot mount (rejected key, no published manifest, unreachable
+ * backend), the SDK otherwise renders nothing — historically a silent failure
+ * that left developers with no clue WHY the orb never appeared (only a console
+ * line that is easy to miss). This renders a small, dismissible badge where the
+ * orb would be, stating the EXACT, actionable reason.
+ *
+ * Hard rule: this is DEVELOPMENT-ONLY. In production builds the badge never
+ * renders (the orb stays invisible, exactly as before) so end users never see
+ * Fiodos diagnostics. Gating is on `process.env.NODE_ENV === 'production'`,
+ * which every major bundler (Next, Vite, webpack, esbuild) statically replaces.
+ */
+const BADGE_ID = 'fiodos-dev-error-badge';
+/**
+ * True only in a development build. Bundlers replace `process.env.NODE_ENV`
+ * with a string literal; if `process` is genuinely absent (rare unbundled use)
+ * we default to NOT showing the badge — production safety wins over visibility.
+ */
+export function isDevEnvironment() {
+    try {
+        return process.env.NODE_ENV !== 'production';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mount (or update) the dev error badge. No-op in production, in non-DOM
+ * environments (SSR), or when called repeatedly (the message is updated in
+ * place rather than stacking badges).
+ */
+export function showOrbDevError(reason, opts) {
+    if (!isDevEnvironment())
+        return;
+    if (typeof document === 'undefined' || !document.body)
+        return;
+    const message = cleanReason(reason);
+    let badge = document.getElementById(BADGE_ID);
+    if (badge) {
+        const body = badge.querySelector('[data-fiodos-badge-msg]');
+        if (body)
+            body.textContent = message;
+        return;
+    }
+    badge = document.createElement('div');
+    badge.id = BADGE_ID;
+    badge.setAttribute('role', 'alert');
+    badge.style.cssText = [
+        'position:fixed',
+        'bottom:20px',
+        'right:20px',
+        'z-index:2147483000',
+        'max-width:340px',
+        'padding:12px 14px',
+        'border-radius:12px',
+        'background:#1b1b1f',
+        'color:#fff',
+        "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
+        'font-size:13px',
+        'line-height:1.45',
+        'box-shadow:0 8px 28px rgba(0,0,0,0.35)',
+        'border:1px solid rgba(255,255,255,0.12)',
+    ].join(';');
+    const header = document.createElement('div');
+    header.style.cssText =
+        'display:flex;align-items:center;gap:6px;margin-bottom:6px;font-weight:600;color:#ffd166';
+    header.textContent = '◉ Fiodos · el orbe no se montó (solo desarrollo)';
+    const close = document.createElement('button');
+    close.textContent = '×';
+    close.setAttribute('aria-label', 'Cerrar aviso de Fiodos');
+    close.style.cssText = [
+        'margin-left:auto',
+        'background:transparent',
+        'border:0',
+        'color:rgba(255,255,255,0.6)',
+        'font-size:18px',
+        'line-height:1',
+        'cursor:pointer',
+        'padding:0 2px',
+    ].join(';');
+    close.addEventListener('click', () => badge?.remove());
+    header.appendChild(close);
+    const body = document.createElement('div');
+    body.setAttribute('data-fiodos-badge-msg', '');
+    body.textContent = message;
+    const hint = document.createElement('div');
+    hint.style.cssText = 'margin-top:8px;color:rgba(255,255,255,0.55);font-size:11.5px';
+    hint.textContent =
+        'Comprueba que la API key y la URL de tu app son las del MISMO proyecto donde publicaste. Este aviso solo aparece en desarrollo.';
+    badge.appendChild(header);
+    badge.appendChild(body);
+    badge.appendChild(hint);
+    document.body.appendChild(badge);
+}
+/** Strip the internal "[fyodos]" prefix so the badge reads cleanly to a human. */
+function cleanReason(reason) {
+    return reason.replace(/^\[fyodos\]\s*/i, '').trim() || 'No se pudo montar el orbe.';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/web-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-agnostic browser layer for the Fiodos agent: a vanilla AgentController (orchestrator), DOM adapters (navigation/voice/storage), HTTP client and decision engine over @fiodos/core. Shared base for @fiodos/vue, @fiodos/svelte and @fiodos/angular (no framework imports).",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/dist/cjs/dropin/createFyodosAgent.d.ts

@@ -1,60 +0,0 @@
-/**
- * Vanilla drop-in — assembles the default browser adapters, builds an
- * AgentController and (optionally) mounts the DOM orb in one call. Frameworks
- * use the AgentController + their own components; this is the zero-framework
- * path (and the reference the Vue/Svelte/Angular drop-ins follow).
- *
- * PARITY WITH @fyodos/react's <FyodosAgent/>: when `manifest` is omitted, the
- * agent self-bootstraps — it fetches the published manifest by `apiKey`
- * (GET /v1/client/manifest), assembles default browser adapters, mounts the orb
- * and posts the `orb-seen` heartbeat. So a one-line drop-in needs only an
- * apiKey, exactly like React. Passing a manifest keeps the fully-synchronous,
- * manual path.
- */
-import { type ActionRegistries, type AppManifest } from '@fyodos/core';
-import { AgentController } from '../controller/AgentController';
-import { type MountOrbOptions, type MountedOrb } from '../orb/mountOrb';
-import type { FyodosWebAgentConfig } from '../config/types';
-export interface CreateFyodosAgentOptions {
-    /** Backend base URL. Defaults to the public Fyodos backend. */
-    baseUrl?: string;
-    /** Client API key (x-api-key). Required when `manifest` is omitted (auto-fetch). */
-    apiKey?: string;
-    /**
-     * The validated app manifest. OPTIONAL: omit it to self-fetch the published
-     * manifest by apiKey (the React-parity drop-in path).
-     */
-    manifest?: AppManifest;
-    /** Action handlers / context validators (defaults to empty registries). */
-    registries?: ActionRegistries;
-    /** Agent reply locale (e.g. 'es', 'en'). Defaults to the browser language. */
-    locale?: string;
-    /** STT locale (e.g. 'es-ES', 'en-US'). Defaults to the browser language. */
-    sttLocale?: string;
-    /** Host router navigate delegate. Defaults to location.assign. */
-    navigate?: (route: string) => void;
-    /** Host auth check for actions requiring auth. */
-    isAuthenticated?: () => boolean;
-    /** Voice id forwarded to the backend TTS. */
-    ttsVoice?: string | (() => string | undefined);
-    /** End-user id for rate limiting / telemetry correlation. */
-    getUserId?: () => string | null;
-    /** Mount the built-in DOM orb. Default: true. Pass false to render your own. */
-    mount?: boolean;
-    orb?: MountOrbOptions;
-    /** Escape hatch: extra config merged into the controller config. */
-    configOverrides?: Partial<FyodosWebAgentConfig>;
-    /** Called once the manifest loaded and the orb mounted (auto-fetch path). */
-    onReady?: (controller: AgentController) => void;
-    /** Called when self-bootstrap fails (network / rejected key / no manifest). */
-    onError?: (error: Error) => void;
-}
-export interface FyodosAgentHandle {
-    /** Null until the async self-bootstrap resolves (auto-fetch path). */
-    controller: AgentController | null;
-    orb: MountedOrb | null;
-    /** Resolves once the controller is ready (immediately on the manual path). */
-    ready: Promise<AgentController | null>;
-    destroy(): void;
-}
-export declare function createFyodosAgent(options: CreateFyodosAgentOptions): FyodosAgentHandle;

package/dist/cjs/dropin/createFyodosAgent.js

@@ -1,143 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFyodosAgent = createFyodosAgent;
-/**
- * Vanilla drop-in — assembles the default browser adapters, builds an
- * AgentController and (optionally) mounts the DOM orb in one call. Frameworks
- * use the AgentController + their own components; this is the zero-framework
- * path (and the reference the Vue/Svelte/Angular drop-ins follow).
- *
- * PARITY WITH @fyodos/react's <FyodosAgent/>: when `manifest` is omitted, the
- * agent self-bootstraps — it fetches the published manifest by `apiKey`
- * (GET /v1/client/manifest), assembles default browser adapters, mounts the orb
- * and posts the `orb-seen` heartbeat. So a one-line drop-in needs only an
- * apiKey, exactly like React. Passing a manifest keeps the fully-synchronous,
- * manual path.
- */
-const core_1 = require("@fyodos/core");
-const backendClient_1 = require("../api/backendClient");
-const backendTelemetry_1 = require("../api/backendTelemetry");
-const webNavigationAdapter_1 = require("../adapters/webNavigationAdapter");
-const webStorageAdapter_1 = require("../adapters/webStorageAdapter");
-const webVoiceAdapter_1 = require("../adapters/webVoiceAdapter");
-const AgentController_1 = require("../controller/AgentController");
-const mountOrb_1 = require("../orb/mountOrb");
-const clientBootstrap_1 = require("../api/clientBootstrap");
-function defaultNavigate(route) {
-    if (typeof window !== 'undefined' && window.location)
-        window.location.assign(route);
-}
-function browserLocale() {
-    const lang = typeof navigator !== 'undefined' && navigator.language ? navigator.language : 'en-US';
-    return { locale: lang.split('-')[0] || 'en', sttLocale: lang };
-}
-/** Build the controller + adapters from a known manifest (shared by both paths). */
-function assemble(options, manifest, baseUrl) {
-    const fallback = browserLocale();
-    const locale = options.locale ?? fallback.locale;
-    const sttLocale = options.sttLocale ?? options.locale ?? fallback.sttLocale;
-    const backend = (0, backendClient_1.createFyodosBackendClient)({
-        baseUrl,
-        apiKey: options.apiKey,
-        getUserId: options.getUserId,
-    });
-    const telemetry = (0, backendTelemetry_1.createFyodosTelemetry)({
-        baseUrl,
-        apiKey: options.apiKey,
-        getUserId: options.getUserId,
-    });
-    const config = {
-        manifest,
-        locale,
-        sttLocale,
-        navigation: (0, webNavigationAdapter_1.createWebNavigationAdapter)({ navigate: options.navigate ?? defaultNavigate }),
-        registries: options.registries ?? { handlers: {}, idempotencyCheckers: {} },
-        backend,
-        voice: (0, webVoiceAdapter_1.createWebVoiceAdapter)(),
-        storage: (0, webStorageAdapter_1.createWebStorageAdapter)(),
-        telemetry,
-        isAuthenticated: options.isAuthenticated,
-        ttsVoice: options.ttsVoice,
-        ...options.configOverrides,
-    };
-    const controller = new AgentController_1.AgentController(config);
-    controller.warmUp();
-    return controller;
-}
-function createFyodosAgent(options) {
-    const baseUrl = (options.baseUrl ?? clientBootstrap_1.DEFAULT_WEB_API_URL).replace(/\/$/, '');
-    const shouldMount = options.mount !== false;
-    // ── Manual path: manifest provided → fully synchronous (back-compat). ───────
-    if (options.manifest) {
-        const controller = assemble(options, options.manifest, baseUrl);
-        const orb = shouldMount ? (0, mountOrb_1.mountOrb)(controller, options.orb) : null;
-        if (shouldMount && options.apiKey) {
-            void (0, clientBootstrap_1.sendOrbSeen)({ baseUrl, apiKey: options.apiKey });
-        }
-        options.onReady?.(controller);
-        const handle = {
-            controller,
-            orb,
-            ready: Promise.resolve(controller),
-            destroy() {
-                orb?.unmount();
-                controller.dispose();
-            },
-        };
-        return handle;
-    }
-    // ── Auto path (React parity): fetch manifest by apiKey, then assemble. ──────
-    const handle = {
-        controller: null,
-        orb: null,
-        ready: Promise.resolve(null),
-        destroy() {
-            cancelled = true;
-            handle.orb?.unmount();
-            handle.controller?.dispose();
-        },
-    };
-    let cancelled = false;
-    handle.ready = (async () => {
-        try {
-            if (!options.apiKey) {
-                throw new Error('[fyodos] createFyodosAgent requires either a `manifest` or an `apiKey` ' +
-                    '(to self-fetch the published manifest).');
-            }
-            const result = await (0, clientBootstrap_1.fetchClientManifest)({ baseUrl, apiKey: options.apiKey });
-            if (cancelled)
-                return null;
-            if (result.status === 'no-manifest' || !result.manifest) {
-                // eslint-disable-next-line no-console
-                console.warn('[fyodos] The orb is idle: this project has no published manifest yet. ' +
-                    'Run the analysis from your Fyodos dashboard, then reload.');
-                return null;
-            }
-            // Fail loudly here (not deep inside the controller) so onError is precise.
-            const check = (0, core_1.validateManifest)(result.manifest);
-            if (!check.valid) {
-                throw new Error(`[fyodos] Invalid manifest for "${result.manifest.appId}":\n- ${check.errors.join('\n- ')}`);
-            }
-            const controller = assemble(options, result.manifest, baseUrl);
-            if (cancelled) {
-                controller.dispose();
-                return null;
-            }
-            handle.controller = controller;
-            handle.orb = shouldMount ? (0, mountOrb_1.mountOrb)(controller, options.orb) : null;
-            if (shouldMount && options.apiKey) {
-                void (0, clientBootstrap_1.sendOrbSeen)({ baseUrl, apiKey: options.apiKey });
-            }
-            options.onReady?.(controller);
-            return controller;
-        }
-        catch (e) {
-            const error = e instanceof Error ? e : new Error(String(e));
-            // eslint-disable-next-line no-console
-            console.error(error.message);
-            options.onError?.(error);
-            return null;
-        }
-    })();
-    return handle;
-}

package/dist/esm/dropin/createFyodosAgent.d.ts

@@ -1,60 +0,0 @@
-/**
- * Vanilla drop-in — assembles the default browser adapters, builds an
- * AgentController and (optionally) mounts the DOM orb in one call. Frameworks
- * use the AgentController + their own components; this is the zero-framework
- * path (and the reference the Vue/Svelte/Angular drop-ins follow).
- *
- * PARITY WITH @fyodos/react's <FyodosAgent/>: when `manifest` is omitted, the
- * agent self-bootstraps — it fetches the published manifest by `apiKey`
- * (GET /v1/client/manifest), assembles default browser adapters, mounts the orb
- * and posts the `orb-seen` heartbeat. So a one-line drop-in needs only an
- * apiKey, exactly like React. Passing a manifest keeps the fully-synchronous,
- * manual path.
- */
-import { type ActionRegistries, type AppManifest } from '@fyodos/core';
-import { AgentController } from '../controller/AgentController.js';
-import { type MountOrbOptions, type MountedOrb } from '../orb/mountOrb.js';
-import type { FyodosWebAgentConfig } from '../config/types.js';
-export interface CreateFyodosAgentOptions {
-    /** Backend base URL. Defaults to the public Fyodos backend. */
-    baseUrl?: string;
-    /** Client API key (x-api-key). Required when `manifest` is omitted (auto-fetch). */
-    apiKey?: string;
-    /**
-     * The validated app manifest. OPTIONAL: omit it to self-fetch the published
-     * manifest by apiKey (the React-parity drop-in path).
-     */
-    manifest?: AppManifest;
-    /** Action handlers / context validators (defaults to empty registries). */
-    registries?: ActionRegistries;
-    /** Agent reply locale (e.g. 'es', 'en'). Defaults to the browser language. */
-    locale?: string;
-    /** STT locale (e.g. 'es-ES', 'en-US'). Defaults to the browser language. */
-    sttLocale?: string;
-    /** Host router navigate delegate. Defaults to location.assign. */
-    navigate?: (route: string) => void;
-    /** Host auth check for actions requiring auth. */
-    isAuthenticated?: () => boolean;
-    /** Voice id forwarded to the backend TTS. */
-    ttsVoice?: string | (() => string | undefined);
-    /** End-user id for rate limiting / telemetry correlation. */
-    getUserId?: () => string | null;
-    /** Mount the built-in DOM orb. Default: true. Pass false to render your own. */
-    mount?: boolean;
-    orb?: MountOrbOptions;
-    /** Escape hatch: extra config merged into the controller config. */
-    configOverrides?: Partial<FyodosWebAgentConfig>;
-    /** Called once the manifest loaded and the orb mounted (auto-fetch path). */
-    onReady?: (controller: AgentController) => void;
-    /** Called when self-bootstrap fails (network / rejected key / no manifest). */
-    onError?: (error: Error) => void;
-}
-export interface FyodosAgentHandle {
-    /** Null until the async self-bootstrap resolves (auto-fetch path). */
-    controller: AgentController | null;
-    orb: MountedOrb | null;
-    /** Resolves once the controller is ready (immediately on the manual path). */
-    ready: Promise<AgentController | null>;
-    destroy(): void;
-}
-export declare function createFyodosAgent(options: CreateFyodosAgentOptions): FyodosAgentHandle;

package/dist/esm/dropin/createFyodosAgent.js

@@ -1,140 +0,0 @@
-/**
- * Vanilla drop-in — assembles the default browser adapters, builds an
- * AgentController and (optionally) mounts the DOM orb in one call. Frameworks
- * use the AgentController + their own components; this is the zero-framework
- * path (and the reference the Vue/Svelte/Angular drop-ins follow).
- *
- * PARITY WITH @fyodos/react's <FyodosAgent/>: when `manifest` is omitted, the
- * agent self-bootstraps — it fetches the published manifest by `apiKey`
- * (GET /v1/client/manifest), assembles default browser adapters, mounts the orb
- * and posts the `orb-seen` heartbeat. So a one-line drop-in needs only an
- * apiKey, exactly like React. Passing a manifest keeps the fully-synchronous,
- * manual path.
- */
-import { validateManifest } from '@fyodos/core';
-import { createFyodosBackendClient } from '../api/backendClient.js';
-import { createFyodosTelemetry } from '../api/backendTelemetry.js';
-import { createWebNavigationAdapter } from '../adapters/webNavigationAdapter.js';
-import { createWebStorageAdapter } from '../adapters/webStorageAdapter.js';
-import { createWebVoiceAdapter } from '../adapters/webVoiceAdapter.js';
-import { AgentController } from '../controller/AgentController.js';
-import { mountOrb } from '../orb/mountOrb.js';
-import { DEFAULT_WEB_API_URL, fetchClientManifest, sendOrbSeen } from '../api/clientBootstrap.js';
-function defaultNavigate(route) {
-    if (typeof window !== 'undefined' && window.location)
-        window.location.assign(route);
-}
-function browserLocale() {
-    const lang = typeof navigator !== 'undefined' && navigator.language ? navigator.language : 'en-US';
-    return { locale: lang.split('-')[0] || 'en', sttLocale: lang };
-}
-/** Build the controller + adapters from a known manifest (shared by both paths). */
-function assemble(options, manifest, baseUrl) {
-    const fallback = browserLocale();
-    const locale = options.locale ?? fallback.locale;
-    const sttLocale = options.sttLocale ?? options.locale ?? fallback.sttLocale;
-    const backend = createFyodosBackendClient({
-        baseUrl,
-        apiKey: options.apiKey,
-        getUserId: options.getUserId,
-    });
-    const telemetry = createFyodosTelemetry({
-        baseUrl,
-        apiKey: options.apiKey,
-        getUserId: options.getUserId,
-    });
-    const config = {
-        manifest,
-        locale,
-        sttLocale,
-        navigation: createWebNavigationAdapter({ navigate: options.navigate ?? defaultNavigate }),
-        registries: options.registries ?? { handlers: {}, idempotencyCheckers: {} },
-        backend,
-        voice: createWebVoiceAdapter(),
-        storage: createWebStorageAdapter(),
-        telemetry,
-        isAuthenticated: options.isAuthenticated,
-        ttsVoice: options.ttsVoice,
-        ...options.configOverrides,
-    };
-    const controller = new AgentController(config);
-    controller.warmUp();
-    return controller;
-}
-export function createFyodosAgent(options) {
-    const baseUrl = (options.baseUrl ?? DEFAULT_WEB_API_URL).replace(/\/$/, '');
-    const shouldMount = options.mount !== false;
-    // ── Manual path: manifest provided → fully synchronous (back-compat). ───────
-    if (options.manifest) {
-        const controller = assemble(options, options.manifest, baseUrl);
-        const orb = shouldMount ? mountOrb(controller, options.orb) : null;
-        if (shouldMount && options.apiKey) {
-            void sendOrbSeen({ baseUrl, apiKey: options.apiKey });
-        }
-        options.onReady?.(controller);
-        const handle = {
-            controller,
-            orb,
-            ready: Promise.resolve(controller),
-            destroy() {
-                orb?.unmount();
-                controller.dispose();
-            },
-        };
-        return handle;
-    }
-    // ── Auto path (React parity): fetch manifest by apiKey, then assemble. ──────
-    const handle = {
-        controller: null,
-        orb: null,
-        ready: Promise.resolve(null),
-        destroy() {
-            cancelled = true;
-            handle.orb?.unmount();
-            handle.controller?.dispose();
-        },
-    };
-    let cancelled = false;
-    handle.ready = (async () => {
-        try {
-            if (!options.apiKey) {
-                throw new Error('[fyodos] createFyodosAgent requires either a `manifest` or an `apiKey` ' +
-                    '(to self-fetch the published manifest).');
-            }
-            const result = await fetchClientManifest({ baseUrl, apiKey: options.apiKey });
-            if (cancelled)
-                return null;
-            if (result.status === 'no-manifest' || !result.manifest) {
-                // eslint-disable-next-line no-console
-                console.warn('[fyodos] The orb is idle: this project has no published manifest yet. ' +
-                    'Run the analysis from your Fyodos dashboard, then reload.');
-                return null;
-            }
-            // Fail loudly here (not deep inside the controller) so onError is precise.
-            const check = validateManifest(result.manifest);
-            if (!check.valid) {
-                throw new Error(`[fyodos] Invalid manifest for "${result.manifest.appId}":\n- ${check.errors.join('\n- ')}`);
-            }
-            const controller = assemble(options, result.manifest, baseUrl);
-            if (cancelled) {
-                controller.dispose();
-                return null;
-            }
-            handle.controller = controller;
-            handle.orb = shouldMount ? mountOrb(controller, options.orb) : null;
-            if (shouldMount && options.apiKey) {
-                void sendOrbSeen({ baseUrl, apiKey: options.apiKey });
-            }
-            options.onReady?.(controller);
-            return controller;
-        }
-        catch (e) {
-            const error = e instanceof Error ? e : new Error(String(e));
-            // eslint-disable-next-line no-console
-            console.error(error.message);
-            options.onError?.(error);
-            return null;
-        }
-    })();
-    return handle;
-}