@gamaro.io/widget 0.6.0

package/dist/iframe-loader.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Iframe loader with timeout + retry (issue #867).
+ *
+ * Promotes a skeleton placeholder into an operational iframe with a per-attempt
+ * timeout and a configurable backoff between retries. Single responsibility —
+ * the host (`VersiqWidget`) keeps the application FSM, this module owns the
+ * mechanics of getting the iframe up.
+ *
+ * Success criterion: iframe `load` event AND a `versiq:ready` postMessage from
+ * the embed React app. The AND is mandatory — a 5xx Next page rendered inside
+ * the iframe still fires `load`; relying on that alone would mask deployment
+ * failures as silent successes.
+ *
+ * Source: Harel, *Statecharts: A Visual Formalism for Complex Systems*, 1987
+ * (FSM); Akkoyunlu et al., *Some Constraints and Tradeoffs in the Design of
+ * Network Communications*, SOSP 1975 (Two-Generals handshake); Martin,
+ * *Clean Architecture* §7 (SRP).
+ */
+/** Per-attempt timeout (ms). */
+export declare const IFRAME_LOAD_TIMEOUT_MS = 5000;
+/**
+ * Backoff delays between retries (ms). Length determines the number of retries
+ * (total attempts = length + 1). [1s, 3s] covers the 5-15s Docker redeploy
+ * window observed on this project without exceeding the visitor patience
+ * threshold (19s wall-time worst case). Aligned with `resolveConfig()` which
+ * already does a 1s retry on the config fetch. No jitter — single client per
+ * page, no thundering-herd risk.
+ */
+export declare const IFRAME_LOAD_BACKOFF_MS: readonly [1000, 3000];
+export type IframeLoadFailureReason = "timeout" | "error";
+export type IframeLoadState = {
+    kind: "loading";
+    attempt: number;
+} | {
+    kind: "loaded";
+    iframe: HTMLIFrameElement;
+} | {
+    kind: "retrying";
+    attempt: number;
+    reason: IframeLoadFailureReason;
+} | {
+    kind: "failed";
+    reason: IframeLoadFailureReason;
+    attempts: number;
+};
+export interface IframeLoaderOptions {
+    /** Factory producing a fresh iframe on every attempt. */
+    buildIframe: () => HTMLIFrameElement;
+    /** DOM node the iframe will be appended to. */
+    container: HTMLElement;
+    /** Allowed origins for the `versiq:ready` ack (passed to `isValidOrigin`). */
+    allowedOrigins: string[];
+    /** Per-attempt timeout in ms. Defaults to `IFRAME_LOAD_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Backoff delays between retries; length = number of retries. */
+    backoffMs?: readonly number[];
+    /** Notified on every FSM transition. */
+    onStateChange?: (state: IframeLoadState) => void;
+    /** Abort signal — rejects pending attempt and cleans up. */
+    signal?: AbortSignal;
+}
+export declare class IframeLoadError extends Error {
+    readonly reason: IframeLoadFailureReason;
+    readonly attempts: number;
+    constructor(reason: IframeLoadFailureReason, attempts: number);
+}
+/**
+ * Load an iframe with timeout + retry. Resolves with the live iframe on
+ * success; throws `IframeLoadError` (reason + final attempt count) on final
+ * failure, or `DOMException("AbortError")` when `opts.signal` aborts.
+ *
+ * The `versiq:ready` message is observed via a LOCAL listener that is detached
+ * the moment the handshake completes — the caller is expected to attach its
+ * own applicative listener AFTER this resolves, and to manually set
+ * `isReady = true` + send any post-ready commands, since the embed React app
+ * only emits `versiq:ready` once on mount.
+ */
+export declare function loadIframeWithRetry(opts: IframeLoaderOptions): Promise<HTMLIFrameElement>;

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Versiq Widget SDK
+ *
+ * Entry point for the widget SDK. Supports both auto-initialization from
+ * script tags and programmatic usage.
+ *
+ * Auto-init usage (canonical integrator surface — #726):
+ * ```html
+ * <script
+ *   src="https://unpkg.com/@gamaro.io/widget@latest/dist/widget.umd.js"
+ *   data-api-key="pk_live_xxx">
+ * </script>
+ * ```
+ *
+ * The integrator's HTML carries only the publishable key (plus optional
+ * host-context attributes like `data-container` / `data-debug` / identity
+ * fields). Theme, position, language, showProfile, and the default open
+ * state are configured from the admin portal (`/portal/widget`) and
+ * resolved at load time via the publishable key — editing them from
+ * HTML is no longer supported. The legacy `data-theme` / `data-position` /
+ * `data-language` / `data-show-profile` / `data-open` attributes are
+ * silently ignored.
+ *
+ * Programmatic usage (internal dev surface — admin preview, marketing
+ * demo — not recommended for partner integrations):
+ * ```javascript
+ * import { createWidget } from '@gamaro.io/widget';
+ *
+ * const widget = createWidget({ apiKey: 'pk_live_xxx' });
+ * widget.on('qualified', () => sendToAnalytics()); // signal only, no data
+ * ```
+ *
+ * Programmatic `theme` / `position` / ... overrides are preserved for the
+ * admin sandbox's live-preview use case (client-wins merge). Partner
+ * integrators should configure those fields from the admin portal.
+ */
+import { VersiqWidget, createWidget } from "./loader";
+import type { WidgetConfig } from "./types";
+export { createWidget, VersiqWidget };
+export { parseScriptAttributes as __parseScriptAttributes };
+export { getCurrentScript as __getCurrentScript };
+export { autoInit as __autoInit };
+export { themeConfigSchema, widgetPositionSchema, widgetConfigSchema, b2bProfileSchema, widgetMessageSchema, applicationConfigResponseSchema, } from "./types";
+export type { WidgetConfig, WidgetPosition, ColorScheme, ThemeConfig, B2BProfile, WidgetProfile, WidgetMessage, WidgetEvent, WidgetEventType, WidgetEventHandler, VersiqAPI, ApplicationConfigResponse, } from "./types";
+export { fetchApplicationConfig, ConfigFetchError } from "./config";
+/**
+ * Parse script tag data attributes to extract widget config (#726).
+ *
+ * Only host-context attributes are read here — fields that cannot live
+ * server-side because they are tied to the integrator's page (DOM
+ * selectors, dev flags, HMAC-verified identity). Theme, position,
+ * language, showProfile, and the default open state are resolved from
+ * the admin portal via `fetchApplicationConfig` in `loader.ts`.
+ */
+declare function parseScriptAttributes(script: HTMLScriptElement): WidgetConfig | null;
+/**
+ * Find the current script tag.
+ */
+declare function getCurrentScript(): HTMLScriptElement | null;
+/**
+ * Initialize widgets from script tags with data-api-key attributes.
+ * Supports multiple widgets on the same page (multi-instance).
+ */
+declare function autoInit(): void;

package/dist/loader.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Widget Loader
+ *
+ * Creates and manages the widget iframe, handling:
+ * - iFrame injection and positioning
+ * - postMessage communication
+ * - Public API exposure
+ */
+import type { WidgetConfig, WidgetEventType, WidgetEventHandler, VersiqAPI, ColorScheme, ThemeConfig } from "./types";
+export declare function __resetInstanceCounter(): void;
+export declare class VersiqWidget implements VersiqAPI {
+    readonly version = "0.1.0";
+    /**
+     * Original config as passed by the caller — preserved separately from
+     * `this.config` (which has defaults merged on top) so the server-config
+     * merge in `resolveConfig()` can tell "field not set by the caller,
+     * use the server value" from "caller explicitly passed a default".
+     */
+    private originalConfig;
+    private config;
+    private iframe;
+    private container;
+    private skeletonButton;
+    private isOpen;
+    private isReady;
+    private isInitialized;
+    private isDestroyed;
+    private fetchAbortController;
+    private iframeLoadAbortController;
+    private _applicationId;
+    private vertical;
+    private instanceId;
+    private pendingCommands;
+    private eventHandlers;
+    private cleanupListener;
+    private debugLog;
+    private currentViewportMode;
+    private mobileMediaQuery;
+    private tabletMediaQuery;
+    private debounceTimer;
+    private viewportChangeHandler;
+    get applicationId(): string;
+    constructor(config: WidgetConfig);
+    /**
+     * Minimal placeholder launcher rendered synchronously before the server
+     * config arrives. Uses the default position (bottom-right) unless the
+     * caller explicitly provided one. Replaced by the real iframe in
+     * `init()` after `resolveConfig()` succeeds.
+     */
+    private renderSkeleton;
+    /**
+     * Insert the skeleton button into the given container. Extracted so the
+     * post-config `init()` can re-create the skeleton inside a fresh container
+     * (positioned per the server config) and keep it visible across iframe
+     * load + retries (#867 — the skeleton survives until either the iframe
+     * resolves or the loader exhausts retries, at which point it mutates to
+     * the "unavailable" state).
+     */
+    private renderSkeletonInto;
+    /**
+     * Mutate the skeleton to its degraded "unavailable" state (#867). Called
+     * when `loadIframeWithRetry` reports a final `failed` transition.
+     *
+     * Snap the opacity instantly (no 300ms fade) — by the time this fires
+     * the user has already waited 9-19s and a slow fade would feel like
+     * the widget is still working (Nielsen heuristic #1 — visibility of
+     * system status: degraded states must be unambiguous). The
+     * `data-state="unavailable"` attribute also gives integrators a CSS
+     * hook to override the visual treatment without touching the SDK.
+     * No-op in inline mode (the skeleton is never rendered there — the
+     * integrator owns the UI).
+     */
+    private setSkeletonStateUnavailable;
+    /**
+     * Resolve the widget runtime config from the server (#726). Retries once
+     * with a 1s backoff on *transient* failures (network, timeout, 5xx) —
+     * 4xx and parse errors are permanent config/setup problems that a
+     * retry cannot fix, so we surface them immediately. If both attempts
+     * fail, the skeleton stays visible and the widget emits `error` —
+     * visible degraded mode rather than a silently absent widget.
+     */
+    private resolveConfig;
+    private isTransientFetchError;
+    /**
+     * Merge the server-resolved application config into the widget state
+     * and promote the skeleton to a fully-initialised iframe.
+     *
+     * Merge semantics (#726):
+     *  1. Fields explicitly passed to `createWidget(...)` win (`originalConfig`).
+     *     This keeps the admin sandbox's live preview working: unsaved edits
+     *     stay visible on the preview widget.
+     *  2. Otherwise the server's `widget` block (from the publishable key
+     *     lookup) provides theme/position/language/showProfile/open.
+     *  3. Legacy `server.theme` is still merged underneath `server.widget.theme`
+     *     for backward compatibility with pre-#726 data shapes — it will
+     *     be removed once all consumers land the new contract.
+     */
+    private applyServerConfig;
+    private flushPendingCommands;
+    private init;
+    /**
+     * Strip any path from `baseUrl` so the resulting string matches the
+     * `event.origin` field of a `versiq:ready` postMessage (which is always
+     * scheme + host + port, no path). Falls back to the raw value if parsing
+     * fails so a malformed config does not silently break the loader gate.
+     */
+    private resolveReadyOrigin;
+    /** Insert the active container in the host DOM at the configured slot. */
+    private attachContainerToDom;
+    private createContainer;
+    private createIframe;
+    private buildIframeUrl;
+    private setupViewportListener;
+    private handleViewportChange;
+    private getViewportMode;
+    /**
+     * Re-apply the container resize transition, gated on the host's current
+     * reduced-motion preference. Called before every geometry change (open/close
+     * AND viewport-mode change) so a mid-session OS reduced-motion toggle is
+     * honoured on whichever path runs next, not only on open/close.
+     */
+    private applyContainerTransition;
+    private updateContainerForViewport;
+    private handleMessage;
+    private sendConfig;
+    private updateVisibility;
+    private emit;
+    open(): void;
+    close(): void;
+    reset(): void;
+    identify(params: {
+        email: string;
+        userId?: string;
+        userHash: string;
+    }): void;
+    setTheme(theme: ThemeConfig): void;
+    setColorScheme(scheme: ColorScheme): void;
+    on<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    off<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    destroy(): void;
+    private log;
+}
+/**
+ * Create a new widget instance.
+ */
+export declare function createWidget(config: WidgetConfig): VersiqWidget;

package/dist/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Widget Logger
+ *
+ * Lightweight logger for the widget SDK with consistent prefix.
+ * Provides a centralized logging interface for debug, info, warn, and error levels.
+ */
+/**
+ * Log an error message.
+ */
+export declare function logError(msg: string, ...args: unknown[]): void;
+/**
+ * Log a warning message.
+ */
+export declare function logWarn(msg: string, ...args: unknown[]): void;
+/**
+ * Log an info message.
+ */
+export declare function logInfo(msg: string, ...args: unknown[]): void;
+/**
+ * Log a debug message.
+ */
+export declare function logDebug(msg: string, ...args: unknown[]): void;
+/**
+ * Create a conditional debug logger based on debug flag.
+ */
+export declare function createDebugLogger(enabled: boolean): typeof logDebug;

package/dist/postmessage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * postMessage Protocol
+ *
+ * Handles secure bidirectional communication between the parent page
+ * and the widget iframe using the postMessage API.
+ */
+import type { WidgetCommand, WidgetEvent } from "./types";
+/**
+ * Validate that a message origin is trusted.
+ *
+ * Exact match only — no subdomain wildcarding. Every real caller compares
+ * against a single origin derived from the widget's own configured `baseUrl`
+ * (`resolveReadyOrigin()`), never a family of subdomains, so a suffix match
+ * only widens the trusted surface without covering a legitimate case.
+ */
+export declare function isValidOrigin(origin: string, allowedOrigins: string[]): boolean;
+/**
+ * Check if an event contains a valid Versiq message.
+ */
+export declare function isVersiqMessage(event: MessageEvent): event is MessageEvent<WidgetCommand | WidgetEvent>;
+/**
+ * Send a command to the widget iframe.
+ */
+export declare function sendCommand(iframe: HTMLIFrameElement, command: WidgetCommand, targetOrigin: string): void;
+/**
+ * Send an event to the parent window.
+ * Used by the embedded widget to notify the parent of state changes.
+ */
+export declare function sendEvent(event: WidgetEvent, targetOrigin: string): void;
+export interface MessageListenerOptions {
+    /** Allowed origins for incoming messages */
+    allowedOrigins?: string[];
+    /** Callback for received messages */
+    onMessage: (message: WidgetCommand | WidgetEvent, origin: string) => void;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Only accept messages from this window (for multi-instance isolation) */
+    sourceWindow?: Window | null;
+}
+/**
+ * Create a message listener with origin validation.
+ * Returns a cleanup function to remove the listener.
+ */
+export declare function createMessageListener(options: MessageListenerOptions): () => void;
+/**
+ * Encode theme config for URL parameter.
+ */
+export declare function encodeTheme(theme: object): string;
+/**
+ * Decode theme config from URL parameter.
+ */
+export declare function decodeTheme<T>(encoded: string): T | null;

package/dist/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Widget SDK Types
+ *
+ * Cross-workspace contracts (viewport, theme, widget config, application
+ * config, postMessage protocol) now live in `@gamaro.io/core-types` — this file
+ * re-exports them so existing consumers (`apps/marketing`,
+ * `apps/app/src/components/portal/sandbox`) keep working unchanged. The only
+ * types still defined locally are widget-specific SDK surfaces (B2B profile
+ * schemas, `VersiqAPI`, `window` augmentation).
+ */
+import { z } from "zod";
+import type { ColorScheme, ThemeConfig, WidgetEventHandler, WidgetEventType } from "@gamaro.io/core-types";
+export { applicationConfigResponseSchema, breakpointsConfigSchema, MESSAGE_TYPES, messageRoleSchema, resolveTheme, responsiveConfigSchema, themeConfigSchema, viewportModeSchema, widgetConfigSchema, widgetMessageSchema, widgetPositionSchema, } from "@gamaro.io/core-types";
+export type { ApplicationConfigResponse, BreakpointsConfig, ColorScheme, MessageRole, MessageType, ResolvedTheme, ResponsiveConfig, ThemeConfig, ThemeDefaults, ViewportMode, WidgetCommand, WidgetConfig, WidgetEvent, WidgetEventHandler, WidgetEventType, WidgetMessage, WidgetPosition, WidgetProfile, WidgetUnavailablePayload, } from "@gamaro.io/core-types";
+/**
+ * User type enum.
+ */
+export declare const b2bUserTypeSchema: z.ZodEnum<{
+    prospect: "prospect";
+    partner: "partner";
+    unknown: "unknown";
+}>;
+/**
+ * Business sector enum.
+ */
+export declare const b2bSectorSchema: z.ZodEnum<{
+    ecommerce: "ecommerce";
+    "real-estate": "real-estate";
+    automotive: "automotive";
+    travel: "travel";
+    recruitment: "recruitment";
+    other: "other";
+}>;
+/**
+ * Company size enum.
+ */
+export declare const b2bCompanySizeSchema: z.ZodEnum<{
+    startup: "startup";
+    pme: "pme";
+    eti: "eti";
+    "grand-groupe": "grand-groupe";
+}>;
+/**
+ * Monthly traffic enum.
+ */
+export declare const b2bMonthlyTrafficSchema: z.ZodEnum<{
+    "< 10k": "< 10k";
+    "10k-50k": "10k-50k";
+    "50k-200k": "50k-200k";
+    "> 200k": "> 200k";
+}>;
+/**
+ * Business objectives enum.
+ */
+export declare const b2bObjectiveSchema: z.ZodEnum<{
+    other: "other";
+    "lead-qualification": "lead-qualification";
+    personalization: "personalization";
+    "cart-abandonment": "cart-abandonment";
+    conversion: "conversion";
+}>;
+/**
+ * E-commerce platform enum.
+ */
+export declare const b2bPlatformSchema: z.ZodEnum<{
+    shopify: "shopify";
+    woocommerce: "woocommerce";
+    prestashop: "prestashop";
+    custom: "custom";
+    none: "none";
+}>;
+/**
+ * Implementation timeline enum.
+ */
+export declare const b2bTimelineSchema: z.ZodEnum<{
+    immediate: "immediate";
+    "1-month": "1-month";
+    "3-months": "3-months";
+    exploring: "exploring";
+}>;
+/**
+ * Budget range enum.
+ */
+export declare const b2bBudgetRangeSchema: z.ZodEnum<{
+    "< 500": "< 500";
+    "500-2000": "500-2000";
+    "2000-5000": "2000-5000";
+    "> 5000": "> 5000";
+}>;
+/**
+ * B2B qualification profile schema.
+ */
+export declare const b2bProfileSchema: z.ZodObject<{
+    userType: z.ZodOptional<z.ZodEnum<{
+        prospect: "prospect";
+        partner: "partner";
+        unknown: "unknown";
+    }>>;
+    sector: z.ZodOptional<z.ZodEnum<{
+        ecommerce: "ecommerce";
+        "real-estate": "real-estate";
+        automotive: "automotive";
+        travel: "travel";
+        recruitment: "recruitment";
+        other: "other";
+    }>>;
+    companySize: z.ZodOptional<z.ZodEnum<{
+        startup: "startup";
+        pme: "pme";
+        eti: "eti";
+        "grand-groupe": "grand-groupe";
+    }>>;
+    monthlyTraffic: z.ZodOptional<z.ZodEnum<{
+        "< 10k": "< 10k";
+        "10k-50k": "10k-50k";
+        "50k-200k": "50k-200k";
+        "> 200k": "> 200k";
+    }>>;
+    objectives: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        other: "other";
+        "lead-qualification": "lead-qualification";
+        personalization: "personalization";
+        "cart-abandonment": "cart-abandonment";
+        conversion: "conversion";
+    }>>>;
+    platform: z.ZodOptional<z.ZodEnum<{
+        shopify: "shopify";
+        woocommerce: "woocommerce";
+        prestashop: "prestashop";
+        custom: "custom";
+        none: "none";
+    }>>;
+    timeline: z.ZodOptional<z.ZodEnum<{
+        immediate: "immediate";
+        "1-month": "1-month";
+        "3-months": "3-months";
+        exploring: "exploring";
+    }>>;
+    budgetRange: z.ZodOptional<z.ZodEnum<{
+        "< 500": "< 500";
+        "500-2000": "500-2000";
+        "2000-5000": "2000-5000";
+        "> 5000": "> 5000";
+    }>>;
+}, z.core.$strip>;
+export type B2BProfile = z.infer<typeof b2bProfileSchema>;
+/**
+ * Public API exposed on window.Versiq.
+ */
+export interface VersiqAPI {
+    /** Application ID (available after config resolution) */
+    readonly applicationId: string;
+    /** Open the widget */
+    open(): void;
+    /** Close the widget */
+    close(): void;
+    /** Reset the conversation */
+    reset(): void;
+    /** Update theme dynamically */
+    setTheme(theme: ThemeConfig): void;
+    /**
+     * Update only the color scheme. Sugar over `setTheme({ colorScheme })` so
+     * integrators can wire their own dark-mode toggle without rebuilding the
+     * full theme object: `window.Versiq.setColorScheme("dark")`.
+     */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Identify the current user with host-attested HMAC verification */
+    identify(params: {
+        email: string;
+        userId?: string;
+        userHash: string;
+    }): void;
+    /** Subscribe to events */
+    on<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    /** Unsubscribe from events */
+    off<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    /** Widget version */
+    version: string;
+}
+declare global {
+    interface Window {
+        Versiq?: VersiqAPI;
+        VersiqApps?: Map<string, VersiqAPI>;
+    }
+}