@gengage/assistant-fe 0.5.7 → 0.6.0

package/dist/common/suggested-search-keywords.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compact browse-card keyword line for `aiSuggestedSearches`.
+ *
+ * Prefer backend `display_keywords`; otherwise derive short fragments from
+ * `chosen_attribute` / `short_name`. Does not use `why_different` (avoids long
+ * explanatory sentences in the tertiary line).
+ */
+export type SuggestedSearchKeywordSource = {
+    display_keywords?: string[];
+    chosen_attribute?: string;
+    short_name?: string;
+};
+/**
+ * Ordered unique keywords (max 3) for suggested-search browse cards.
+ */
+export declare function getSuggestedSearchKeywords(search: SuggestedSearchKeywordSource): string[];
+/** Join keywords for the tertiary browse line (e.g. "A • B • C"). */
+export declare function getSuggestedSearchKeywordsText(search: SuggestedSearchKeywordSource): string;

package/dist/common/theme-utils.d.ts

@@ -0,0 +1,15 @@
+import type { WidgetTheme } from './types.js';
+/**
+ * Shared baseline tokens used by account customizations.
+ *
+ * These values come from historical Gengage host defaults and are
+ * intentionally conservative so account themes can override only what differs.
+ */
+export declare const BASE_WIDGET_THEME: WidgetTheme;
+/**
+ * Merge account overrides on top of the shared base theme.
+ *
+ * Account customization files should call this helper so shared defaults stay
+ * centralized under src/common.
+ */
+export declare function withBaseTheme(overrides: WidgetTheme): WidgetTheme;

package/dist/common/transport.d.ts

@@ -0,0 +1,75 @@
+import type { BackendContext, PageContext, StreamEvent, UISpec } from './types.js';
+export interface BackendRequestMeta {
+    outputLanguage: string;
+    parentUrl: string;
+    windowWidth: string;
+    windowHeight: string;
+    selfUrl: string;
+    id: string;
+    userId: string;
+    appId: string;
+    threads: unknown[];
+    createdAt: string;
+    kvkkApproved: boolean;
+    voiceEnabled: boolean;
+    threadId: string;
+    isControlGroup: boolean;
+    isMobile: boolean;
+    viewId?: string;
+    assistantMode?: string;
+    openPdpSimilars?: boolean;
+}
+export interface ProcessActionRequest {
+    account_id: string;
+    session_id: string;
+    correlation_id: string;
+    user_id?: string;
+    view_id?: string;
+    /**
+     * @deprecated Use top-level `type` and `payload` instead.
+     * Kept for one release cycle of backward compatibility.
+     */
+    action?: {
+        title: string;
+        type: string;
+        payload?: unknown;
+    };
+    /** Backend action type identifier (preferred over `action.type`). */
+    type?: string;
+    /** Arbitrary action data passed to the backend (preferred over `action.payload`). */
+    payload?: unknown;
+    sku?: string;
+    page_type?: string;
+    locale?: string;
+    meta?: BackendRequestMeta;
+    context?: {
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        [key: string]: unknown;
+    };
+}
+export interface ActionEnrichmentContext {
+    pageContext?: PageContext | undefined;
+    backendContext?: BackendContext | null | undefined;
+    isMobile?: boolean | undefined;
+}
+export interface StreamCallbacks {
+    onTextChunk: (content: string, isFinal: boolean, extra?: {
+        productMentions?: Array<{
+            sku: string;
+            short_name: string;
+        }> | undefined;
+        skuToProductItem?: Record<string, Record<string, unknown>> | undefined;
+        conversationMode?: string | undefined;
+        renderHint?: string | undefined;
+        kvkk?: boolean | undefined;
+    }) => void;
+    onUISpec: (spec: UISpec, widget: string, panelHint?: 'panel', clearPanel?: boolean) => void;
+    onAction: (event: StreamEvent) => void;
+    onMetadata: (event: StreamEvent) => void;
+    onError: (err: Error) => void;
+    onDone: () => void;
+}
+export type InjectorAdapter = (request: ProcessActionRequest, callbacks: StreamCallbacks, signal: AbortSignal, attachment?: File) => void | Promise<void>;

package/dist/common/tts-player.d.ts

@@ -0,0 +1,13 @@
+/** Returned by `playTtsAudio` on successful playback initiation. */
+export interface AudioHandle {
+    /** Stop playback immediately. Safe to call multiple times. */
+    stop: () => void;
+}
+/**
+ * Plays a base64-encoded audio clip.
+ * Returns an `AudioHandle` that can stop playback, or `null` if playback
+ * could not be initiated (blocked by browser, unsupported environment, etc.).
+ */
+export declare function playTtsAudio(base64: string, contentType?: string): AudioHandle | null;
+/** Stop and release all active TTS audio elements. */
+export declare function destroyAllTtsAudio(): void;

package/dist/common/types.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Core shared types for all Gengage widgets.
+ *
+ * These types define the public contract between:
+ *   - The host page and widgets (PageContext, WidgetConfig)
+ *   - The backend wire protocol and widgets (StreamEvent, UISpec)
+ *   - Widgets and each other (GengageEvent, SessionContext)
+ */
+import type { InjectorAdapter } from './transport.js';
+/**
+ * Describes the current page's context.
+ * Widgets use this to tailor their behaviour (e.g. show/hide, fetch the right SKU).
+ *
+ * CSR/SPA: call widget.update(context) on every navigation.
+ * SSR: set window.gengage.pageContext before loading widget scripts.
+ */
+export interface PageContext {
+    /** The current page type. Determines which features activate. */
+    pageType: 'pdp' | 'plp' | 'home' | 'cart' | 'search' | 'other';
+    /** Product SKU — required on PDP pages for QNA and Similar Products. */
+    sku?: string;
+    /** Product SKU list — for PLP pages, used with the launchProductList init action. */
+    skuList?: string[];
+    /** Product price, formatted as a string (e.g. "149.99"). */
+    price?: string;
+    /** Category path array, from broad to specific (e.g. ["Electronics", "TVs"]). */
+    categoryTree?: string[];
+    /** Raw page URL (defaults to window.location.href). */
+    url?: string;
+    /** Arbitrary key/value metadata the host page wants to pass through to the backend. */
+    extra?: Record<string, unknown>;
+}
+export interface SessionContext {
+    /**
+     * A UUID created once per browser session, shared across all widgets.
+     * Used as correlation_id in backend logging and frontend event correlation.
+     *
+     * Bootstrap:
+     *   window.__gengageSessionId =
+     *     window.__gengageSessionId
+     *     ?? sessionStorage.getItem('gengage_session_id')
+     *     ?? crypto.randomUUID();
+     *   sessionStorage.setItem('gengage_session_id', window.__gengageSessionId);
+     */
+    sessionId: string;
+    /** Opaque user identifier set by the host site's auth system. */
+    userId?: string;
+    /** View/visit identifier (e.g. from analytics platform). */
+    viewId?: string;
+    /** AB test variant assignment (e.g. 'control', 'treatment'). */
+    abTestVariant?: string;
+    /** AB test experiment identifier (e.g. 'exp_chat_v2'). */
+    abTestExperimentId?: string;
+}
+export interface BaseWidgetConfig {
+    /** Your Gengage account identifier. */
+    accountId: string;
+    /** Backend middleware URL — must be explicitly provided, no default. */
+    middlewareUrl: string;
+    /** AGENTIC_ADAPTER_SEAM: optional in-browser adaptor exposed by gengage-assistant-injector. */
+    injectorAdapter?: InjectorAdapter;
+    /** Session context for backend requests and frontend event correlation. */
+    session?: SessionContext;
+    /** Initial page context. Can be updated later via widget.update(). */
+    pageContext?: PageContext;
+    /** Where to mount the widget's root element. */
+    mountTarget?: HTMLElement | string;
+    /**
+     * Theme tokens applied as CSS custom properties on the widget root.
+     * Consumers can override these in their own CSS; these are just the defaults.
+     */
+    theme?: WidgetTheme;
+    /** Price formatting options. Defaults to Turkish locale (TL, dot thousands, comma decimal). */
+    pricing?: import('./price-formatter.js').PriceFormatConfig;
+}
+export interface WidgetTheme {
+    primaryColor?: string;
+    primaryForeground?: string;
+    backgroundColor?: string;
+    foregroundColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    /** Arbitrary additional CSS custom properties */
+    [cssVar: string]: string | undefined;
+}
+export interface GengageWidget<TConfig extends BaseWidgetConfig = BaseWidgetConfig> {
+    /** Mount the widget and fetch initial data. Must be called once. */
+    init(config: TConfig): Promise<void>;
+    /**
+     * Update page context after SPA navigation or page state changes.
+     * Widgets re-fetch relevant data (e.g. QNA buttons for new SKU).
+     */
+    update(context: Partial<PageContext>): void;
+    /** Make the widget visible. No-op if already visible. */
+    show(): void;
+    /** Hide the widget. Preserves state (conversation history, etc.). */
+    hide(): void;
+    /** Fully remove the widget from the DOM and release all resources. */
+    destroy(): void;
+    /**
+     * Subscribe to widget events.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const off = widget.on('open', () => console.log('chat opened'));
+     * // later:
+     * off();
+     */
+    on(event: string, handler: (...args: unknown[]) => void): () => void;
+}
+/**
+ * Every event sent over the stream has a `type` discriminant.
+ * Events are newline-delimited JSON (NDJSON) over a streaming HTTP response.
+ */
+export type StreamEvent = StreamEventMetadata | StreamEventTextChunk | StreamEventUISpec | StreamEventAction | StreamEventError | StreamEventDone;
+/** First event in every stream — session and model info. */
+export interface StreamEventMetadata {
+    type: 'metadata';
+    sessionId: string;
+    model: string;
+    /** Any extra server-side metadata the backend wants to forward. */
+    meta?: Record<string, unknown>;
+}
+/** A chunk of assistant text (streamed word-by-word or sentence-by-sentence). */
+export interface StreamEventTextChunk {
+    type: 'text_chunk';
+    content: string;
+    /** If true this chunk closes the current text block. */
+    final?: boolean;
+    /** AGENTIC_ADAPTER_SEAM: product mentions may come from legacy NDJSON or adapter events. */
+    productMentions?: Array<{
+        sku: string;
+        short_name: string;
+    }>;
+    /** Map from SKU to full product data (for enriching product mention links). */
+    skuToProductItem?: Record<string, Record<string, unknown>>;
+    /** Current conversation mode from outputText (e.g., 'product_search'). */
+    conversationMode?: string;
+    /** Backend render hint for special rendering (e.g. 'photo_analysis'). */
+    renderHint?: string;
+    /** True when the outputText contains KVKK consent content (set by backend). */
+    kvkk?: boolean;
+}
+/**
+ * A json-render UI spec sent from the backend.
+ * The frontend renders it using the active widget registry.
+ * Backend can send UI specs mid-stream to show product cards,
+ * action buttons, or any structured component alongside text.
+ */
+export interface StreamEventUISpec {
+    type: 'ui_spec';
+    /** Which widget catalog this spec targets. */
+    widget: 'chat' | 'qna' | 'simrel';
+    /** The json-render spec: root + elements map. */
+    spec: UISpec;
+    /** Routing hint for two-panel layout: 'panel' = detail/results panel, default = chat thread. */
+    panelHint?: 'panel';
+    /** When present, dismiss panel loading and hide/clear the assistant side panel. */
+    clearPanel?: true;
+}
+/** A discrete action the backend instructs the widget to perform. */
+export interface StreamEventAction {
+    type: 'action';
+    action: {
+        kind: 'open_chat';
+        payload?: ActionPayload;
+    } | {
+        kind: 'navigate';
+        url: string;
+        newTab?: boolean;
+    } | {
+        kind: 'save_session';
+        sessionId: string;
+        sku: string;
+    } | {
+        kind: 'add_to_cart';
+        sku: string;
+        quantity: number;
+        cartCode: string;
+    } | {
+        kind: 'script_call';
+        name: string;
+        payload?: Record<string, unknown>;
+    } | {
+        kind: string;
+        [key: string]: unknown;
+    };
+}
+export interface StreamEventError {
+    type: 'error';
+    code: string;
+    message: string;
+}
+export interface StreamEventDone {
+    type: 'done';
+}
+/**
+ * A json-render spec is a flat map of element IDs to element definitions
+ * plus a root element ID.
+ *
+ * See: https://github.com/vercel-labs/json-render
+ */
+export interface UISpec {
+    root: string;
+    elements: Record<string, UIElement>;
+}
+export interface UIElement {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: string[];
+}
+/**
+ * Shape of `context.panel` as returned by the backend's `context` event
+ * and sent back with each request. Field names match the backend `SessionContext`.
+ *
+ * This is intentionally extensible (index signature) because the backend
+ * may add fields without a frontend release.
+ */
+interface BackendPanelContext {
+    screen_type?: 'product_list' | 'product_details' | 'comparison_table';
+    screen_summary?: string;
+    screen_sku_list?: string[];
+    chat_mentioned_skus?: string[];
+    conversation_stage?: 'exploring' | 'evaluating' | 'deciding' | 'refining';
+    last_search_query?: string;
+    last_search_offset?: number;
+    last_search_page_size?: number;
+    last_search_end_of_list?: boolean;
+    last_search_category_id?: string;
+    last_search_title?: string;
+    last_search_max_budget?: number;
+    product_refs?: Array<{
+        ref: string;
+        sku: string;
+        name: string;
+        brand?: string;
+        price?: number;
+    }>;
+    session_memory?: Record<string, unknown>;
+    suggested_action_titles?: string[];
+    [key: string]: unknown;
+}
+/**
+ * The full backend context object stored between turns.
+ * Contains `panel` (session state), `messages` (conversation history),
+ * and `message_id` (last message identifier).
+ */
+export interface BackendContext {
+    panel?: BackendPanelContext;
+    messages?: Array<{
+        role?: string;
+        content?: string;
+    }>;
+    message_id?: string;
+    [key: string]: unknown;
+}
+/** Params passed to add-to-cart callbacks across all widgets. */
+export interface AddToCartParams {
+    sku: string;
+    cartCode: string;
+    quantity: number;
+}
+/** Add-to-cart callbacks may complete synchronously or after host cart confirmation. */
+export type AddToCartHandlerResult = void | Promise<void>;
+export interface ActionPayload {
+    /** Display label shown to the user. */
+    title: string;
+    /** Backend action type identifier. */
+    type: string;
+    /** Arbitrary action data passed to the backend as-is. */
+    payload?: unknown;
+}
+/**
+ * All inter-widget and host-page events follow this naming convention:
+ *   gengage:<widget>:<action>
+ *
+ * Widgets dispatch these; host pages and other widgets listen.
+ */
+export type GengageEventName = 'gengage:chat:open' | 'gengage:chat:close' | 'gengage:chat:ready' | 'gengage:chat:metadata' | 'gengage:chat:voice' | 'gengage:chat:redirect' | 'gengage:chat:script-call' | 'gengage:chat:add-to-cart' | 'gengage:chat:product-favorite' | 'gengage:qna:action' | 'gengage:qna:open-chat' | 'gengage:similar:product-click' | 'gengage:similar:grouping-click' | 'gengage:similar:products-impression' | 'gengage:similar:add-to-cart' | 'gengage:global:error' | 'gengage:checkout:start' | 'gengage:checkout:complete' | 'gengage:context:update';
+export type GengageEventDetailMap = {
+    'gengage:chat:open': {
+        state?: 'full' | 'half';
+    };
+    'gengage:chat:close': Record<string, never>;
+    'gengage:chat:ready': Record<string, never>;
+    'gengage:chat:metadata': {
+        payload: Record<string, unknown>;
+    };
+    'gengage:chat:voice': {
+        payload: unknown;
+    };
+    'gengage:chat:redirect': {
+        target: unknown;
+        payload: unknown;
+    };
+    'gengage:chat:script-call': {
+        name: string;
+        payload?: Record<string, unknown>;
+    };
+    'gengage:chat:add-to-cart': {
+        sku: string;
+        cartCode: string;
+        quantity: number;
+        sessionId: string | null;
+    };
+    'gengage:chat:product-favorite': {
+        sku: string;
+        product: Record<string, unknown>;
+        favorited: boolean;
+        sessionId: string | null;
+    };
+    'gengage:qna:action': ActionPayload;
+    'gengage:qna:open-chat': Record<string, never>;
+    'gengage:similar:product-click': {
+        sku: string;
+        url: string;
+        sessionId: string | null;
+        productName?: string;
+    };
+    'gengage:similar:grouping-click': {
+        grouping_label: string;
+        grouping_index: number;
+        sessionId: string | null;
+    };
+    'gengage:similar:products-impression': {
+        source_sku: string;
+        product_count: number;
+        grouped: boolean;
+        sessionId: string | null;
+    };
+    'gengage:similar:add-to-cart': {
+        sku: string;
+        quantity: number;
+        cartCode: string;
+    };
+    'gengage:global:error': {
+        source: 'chat' | 'qna' | 'simrel' | 'sdk';
+        message: string;
+        code?: string;
+        durationMs?: number;
+        sticky?: boolean;
+    };
+    'gengage:checkout:start': {
+        attribution_source: 'chat' | 'qna' | 'simrel';
+        attribution_action_id: string;
+        cart_value: number;
+        currency: string;
+        line_items: number;
+    };
+    'gengage:checkout:complete': {
+        attribution_source: 'chat' | 'qna' | 'simrel';
+        attribution_action_id: string;
+        cart_value: number;
+        currency: string;
+        line_items: number;
+    };
+    'gengage:context:update': Partial<PageContext>;
+};
+declare global {
+    interface Window {
+        /**
+         * Set this before loading widget scripts for SSR / static pages.
+         * CSR/SPA: call widget.update() instead.
+         */
+        gengage?: {
+            pageContext?: PageContext;
+            /** Shared session ID — set once at page bootstrap. */
+            sessionId?: string;
+            /** Chat widget public API, available after chat widget init(). */
+            chat?: import('./widget-base').ChatPublicAPI;
+            /** Overlay orchestration API, available after initOverlayWidgets(). */
+            overlay?: import('./overlay.js').OverlayWidgetsController;
+        };
+        /** @internal Legacy compat — do not use in new integrations. */
+        __gengageSessionId?: string;
+    }
+}
+export {};

package/dist/common/ui-theme.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetTheme } from './types.js';
+/**
+ * Shared SDK-wide visual tokens.
+ *
+ * Applied to every widget root by default so account customizations only
+ * override what they need.
+ */
+export declare const DEFAULT_WIDGET_THEME_TOKENS: WidgetTheme;
+export declare function withDefaultWidgetTheme(theme?: WidgetTheme): WidgetTheme;

package/dist/common/uuidv7.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zero-dependency UUIDv7 generator.
+ *
+ * 48-bit Unix-ms timestamp + random bits, version nibble 0x7, variant 0b10.
+ * Lexicographically sortable — critical for thread ordering (threadA < threadB).
+ */
+export declare function uuidv7(): string;

package/dist/common/voice-input.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Browser-native Web Speech API voice input.
+ *
+ * Uses the SpeechRecognition API for real-time speech-to-text.
+ * The frontend sends transcribed text directly — no audio blobs
+ * are sent to the backend. This replaces server-side Groq Whisper.
+ *
+ * Supports:
+ *   - Real-time transcription with interim results
+ *   - Turkish (`tr-TR`) and English (`en-US`) language support
+ *   - Auto-submit on silence (configurable timeout)
+ *   - Microphone permission handling with descriptive errors
+ *
+ * Browser support:
+ *   - Chrome 33+, Edge 79+, Safari 14.1+ (via webkitSpeechRecognition)
+ *   - Firefox: NOT SUPPORTED (no SpeechRecognition API)
+ */
+export type VoiceInputState = 'idle' | 'listening' | 'error';
+export type VoiceInputErrorCode = 'not-supported' | 'not-allowed' | 'no-microphone' | 'no-speech' | 'network' | 'aborted' | 'unknown';
+export interface VoiceInputCallbacks {
+    /** Called with interim transcript while the user speaks. */
+    onInterim?: (text: string) => void;
+    /** Called with final transcript when a phrase is recognized. */
+    onFinal?: (text: string) => void;
+    /** Called when auto-submit fires (silence timeout reached with final text). */
+    onAutoSubmit?: (text: string) => void;
+    /** Called when voice input state changes. */
+    onStateChange?: (state: VoiceInputState) => void;
+    /** Called on recognition error. */
+    onError?: (code: VoiceInputErrorCode, message: string) => void;
+}
+export interface VoiceInputOptions {
+    /** BCP 47 language tag. Default: 'tr-TR'. */
+    lang?: string;
+    /** Silence duration in ms before auto-submit. Default: 1500. */
+    silenceTimeoutMs?: number;
+    /** Whether to auto-submit on silence. Default: true. */
+    autoSubmit?: boolean;
+}
+/**
+ * Check whether the browser supports the Web Speech API.
+ */
+export declare function isVoiceInputSupported(): boolean;
+export declare class VoiceInput {
+    private recognition;
+    private _state;
+    private silenceTimer;
+    private accumulatedTranscript;
+    private readonly callbacks;
+    private readonly lang;
+    private readonly silenceTimeoutMs;
+    private readonly autoSubmit;
+    private intentionalStop;
+    private _lastRestartAt;
+    constructor(callbacks: VoiceInputCallbacks, options?: VoiceInputOptions);
+    get state(): VoiceInputState;
+    /**
+     * Start listening. Requests microphone permission on first call.
+     */
+    start(): void;
+    /**
+     * Stop listening. Returns the accumulated transcript.
+     */
+    stop(): string;
+    /**
+     * Abort listening. Discards any accumulated transcript.
+     */
+    abort(): void;
+    /** Destroy the instance and release resources. */
+    destroy(): void;
+    private setState;
+    private startSilenceTimer;
+    private clearSilenceTimer;
+}

package/dist/common/widget-base.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Abstract base class for all Gengage widgets.
+ *
+ * Provides:
+ *   - Lifecycle management (init → update → show/hide → destroy)
+ *   - Typed event emitter
+ *   - Theme application via CSS custom properties
+ *   - SPA context-update listener (gengage:context:update)
+ *   - Mount target resolution (selector string or HTMLElement)
+ *
+ * Subclasses must implement:
+ *   - protected onInit(config): Promise<void>
+ *   - protected onUpdate(context): void
+ *   - protected onShow(): void
+ *   - protected onHide(): void
+ *   - protected onDestroy(): void
+ */
+import type { BaseWidgetConfig, GengageWidget, PageContext } from './types.js';
+type AnyHandler = (...args: unknown[]) => void;
+export declare abstract class BaseWidget<TConfig extends BaseWidgetConfig = BaseWidgetConfig> implements GengageWidget<TConfig> {
+    protected config: TConfig;
+    protected root: HTMLElement;
+    protected isVisible: boolean;
+    protected isInitialised: boolean;
+    private readonly _handlers;
+    private readonly _cleanups;
+    private _ownsRoot;
+    private _destroying;
+    init(config: TConfig): Promise<void>;
+    update(context: Partial<PageContext>): void;
+    show(): void;
+    hide(): void;
+    destroy(): void;
+    /**
+     * Called at the end of destroy() to remove or clear the root node.
+     * Subclasses that mount into a merchant-owned element (e.g. SimBut) should
+     * override this to a no-op so the host page's DOM is never mutated.
+     */
+    protected _cleanupRoot(): void;
+    on(event: string, handler: AnyHandler): () => void;
+    protected abstract onInit(config: TConfig): Promise<void>;
+    protected abstract onUpdate(context: Partial<PageContext>): void;
+    protected abstract onShow(): void;
+    protected abstract onHide(): void;
+    protected abstract onDestroy(): void;
+    /** Emit a widget event to all registered handlers. */
+    protected emit(event: string, ...args: unknown[]): void;
+    /** Register a cleanup function to run on destroy(). */
+    protected addCleanup(fn: () => void): void;
+    private _resolveMount;
+    private _applyTheme;
+}
+export interface ChatPublicAPI {
+    open(options?: {
+        state?: 'full' | 'half';
+        initialMessage?: string;
+    }): void;
+    openWithAction(action: import('./types.js').ActionPayload, options?: {
+        sku?: string;
+        state?: 'full' | 'half';
+    }): void;
+    /** Send a user message programmatically (same as typing + submit). */
+    sendMessage(text: string): void;
+    /** Send a backend action programmatically. */
+    sendAction(action: import('./types.js').ActionPayload, options?: {
+        silent?: boolean;
+    }): void;
+    close(): void;
+    saveSession(sessionId: string, sku: string): void;
+    readonly isOpen: boolean;
+    on(event: 'open' | 'close' | 'ready' | 'message' | 'error' | 'context-update' | 'destroy', handler: (...args: unknown[]) => void): () => void;
+    /**
+     * Register a callback for a GA4 event name.
+     * When the widget fires that event, the callback is invoked with the event detail.
+     * Callbacks that return `false` or throw signal failure — the widget reacts accordingly
+     * (e.g. showing an error message for add-to-cart failures).
+     *
+     * @returns unsubscribe function
+     */
+    addCallback(eventName: string, callback: (detail: Record<string, unknown>) => boolean | Promise<boolean>): () => void;
+}
+export {};