@ada-cx/messaging-sdk 1.0.0-setup.0

package/dist/frame-channel/types.d.ts

@@ -0,0 +1,736 @@
+import type { HostTelemetryContext } from "../host-telemetry.js";
+/**
+ * Frame channel message format.
+ *
+ * All postMessage payloads between the SDK and its child iframes
+ * are serialized as JSON using this shape.
+ */
+export interface FrameMessage<T = unknown> {
+    /** Identifies the sender (e.g. "sdk", "core", "button") */
+    name: string;
+    /** Event type key */
+    type: string;
+    /** Event-specific data */
+    payload: T;
+    /** UUID for request/response correlation */
+    id?: string;
+}
+export type MetaFieldValue = string | number | boolean | null;
+/** Reload-path response types allowed to acknowledge a durable persistence clear. */
+export type ClearPersistenceAckResponseType = "core.reset.response" | "core.history.delete.response";
+/** Button configuration from server-side client config */
+export interface StartupConfigButton {
+    iconType: string;
+    iconPath: string;
+    textEnabled: boolean;
+    text: string;
+    /**
+     * BCP-47 tag of the language `text` is written in, which the launcher document
+     * declares so a reader pronounces it correctly. Absent on a snapshot cached by
+     * a native host before this field existed.
+     */
+    textLanguage?: string;
+    size: number;
+    backgroundColor: string | null;
+}
+/** Intro popup configuration from server-side client config */
+export interface StartupConfigIntro {
+    responseId: string;
+    body: string;
+    delay: number;
+    duration: number | null;
+    style: "Text" | "Emoji";
+    paths: string[];
+    image?: {
+        url: string;
+        alt: string;
+    };
+    cta?: {
+        label: string;
+        url: string;
+        openInNewTab: boolean;
+    };
+}
+/** Fallback UI shown on outage-style full-page fallback states */
+export interface StartupConfigFallbackUi {
+    icon: {
+        isDefault: boolean;
+        image: string | null;
+    };
+    message: string | Record<string, string>;
+    links: Array<{
+        label: string;
+        url: string;
+    }> | Record<string, Array<{
+        label: string;
+        url: string;
+    }>>;
+}
+/** Proactive conversation entry (URL-triggered, template or direct) */
+export interface StartupConfigProactiveConversation {
+    key?: string;
+    /** Lowest value wins when several URL-triggered proactives match. */
+    order?: number | null;
+    messages: Record<string, string[]>;
+    is_template: boolean;
+    params?: Record<string, string>;
+    modality_config?: {
+        chat?: {
+            active: boolean;
+            url_trigger_conditions?: Array<{
+                type: string;
+                value: string;
+            }>;
+            delay?: number;
+            duration?: number;
+            frequency?: "always" | "session" | "user";
+            schedule_start?: string | null;
+            schedule_end?: string | null;
+        };
+    };
+    /** Per-language branded images for the pre-chat proactive bubble. */
+    images?: Record<string, Array<{
+        url: string;
+        alt: string;
+    }>>;
+    /** Branded call-to-action buttons for the pre-chat proactive bubble. */
+    ctas?: Array<{
+        label: string;
+        url: string;
+        openInNewTab: boolean;
+    }>;
+}
+/**
+ * Serializable snapshot of client config broadcast from core to SDK
+ * immediately after prepare(). Used by the SDK to drive button/intro/proactive
+ * behavior without additional API calls.
+ */
+export interface StartupConfig {
+    chatEnabled: boolean;
+    tintColor: string;
+    button: StartupConfigButton | null;
+    intro: StartupConfigIntro | null;
+    fallbackUi: StartupConfigFallbackUi | null;
+    advancedColorsEnabled: boolean;
+    textOverAccentColor: string | null;
+    proactiveConversations: Record<string, StartupConfigProactiveConversation> | null;
+    features: Record<string, boolean>;
+    /** Server-provided custom schemes the host SDK may authorize for navigation. */
+    allowedProtocols: string[];
+}
+/**
+ * The **only** keys a native host may write to device storage — the canonical
+ * allowlist the iOS and Android persistence hooks enforce.
+ *
+ * An allowlist, not a denylist: a denylist re-opens the hole the first time a new
+ * sensitive key appears upstream, whereas an unrecognized key here simply is not
+ * persisted. Today the cached payload is the `core.startup.config` snapshot (branding
+ * and feature config, no tokens), so nothing is actually stripped — the point is that
+ * widening what gets cached cannot silently start persisting chatter content.
+ *
+ * `__ada_cached_at__` is load-bearing, not incidental: it is what bounds the hydration
+ * snapshot to a 10-minute TTL. Dropping it does not disable rehydration — `bridge-client`
+ * accepts an undated snapshot for back-compat — it removes the bound, so stale state
+ * hydrates indefinitely. iOS and Android keep their own `cachedAt` timestamp as well, so
+ * the real exposure is where the host owns persistence (React Native).
+ *
+ * The native implementations and React Native host-persistence documentation mirror
+ * this list and are pinned to it by `native-persistence-allowlist.test.ts`. Swift and
+ * Kotlin cannot import it, while React Native delegates persistence to the host app;
+ * silently diverging at any of those boundaries is the failure this prevents.
+ */
+export declare const PERSISTABLE_NATIVE_STATE_KEYS: readonly ["advancedColorsEnabled", "allowedProtocols", "button", "chatEnabled", "fallbackUi", "features", "intro", "proactiveConversations", "textOverAccentColor", "tintColor", "__ada_cached_at__"];
+/** Names of the frames the SDK can mount */
+export type FrameName = "core" | "button" | "intro";
+/** Map of frame names to their iframe elements (once mounted) */
+export type FrameRegistry = Partial<Record<FrameName, HTMLIFrameElement>>;
+/**
+ * SDK → Frame events.
+ * Events sent from the SDK to child iframes.
+ */
+export interface SdkToFrameEvents {
+    /** Deliver client config to the core frame after mount */
+    "sdk.config.set": {
+        endpoint: string;
+        handle: string;
+        cluster?: string | null;
+        language?: string;
+        greeting?: string;
+        /** Legacy adaSettings.greeting Answer id, higher priority than an Intro. */
+        configuredGreetingResponseId?: string;
+        identityToken?: string;
+        greetingResponseId?: string | null;
+        /** Customer-hosted app frame URL; core enforces https-only and the per-handle origin allowlist. */
+        appUrl?: string;
+        /** When false, a failing custom appUrl does not fall back to the default app. */
+        appUrlFallback?: boolean;
+        metaFields?: Record<string, MetaFieldValue>;
+        hostTelemetry?: HostTelemetryContext;
+        styles?: Record<string, string>;
+        /** Build/runtime mode; customer testMode never changes infrastructure. */
+        mode?: "test" | "dev" | "prod";
+        /** Prevent cross-session history from being loaded */
+        privateMode?: boolean;
+        /**
+         * Legacy-compatible UA form factor at config-delivery time — the same fixed
+         * signal that decides whether the drawer opens full screen. Only the host
+         * page can measure this; a desktop widget frame is capped at 375px.
+         */
+        isMobileViewport?: boolean;
+        /** One-shot bootstrap flag to clear persisted chatter state before prepare(). */
+        clearPersistenceOnPrepare?: boolean;
+        /** Correlate a reset/deleteHistory clear across a replacement core frame. */
+        clearPersistenceAckRequestId?: string;
+        clearPersistenceAckResponseType?: ClearPersistenceAckResponseType;
+        /** Outgoing conversation buckets that the correlated clear must remove. */
+        clearPersistenceStorageModes?: Array<"normal" | "session" | "private">;
+    };
+    /** Request the frame to identify its trusted origin */
+    "sdk.origin.request": undefined;
+    /** Toggle visibility of the chat UI */
+    "sdk.visibility.set": {
+        isVisible: boolean;
+        /** Why the chat was hidden — drives ada:close_chat vs ada:minimize_chat. */
+        reason?: "close" | "minimize";
+        /**
+         * Internal soft-reset replay. Visibility is restored without granting the
+         * ordinary create-capable activation path; sdk.reset owns exact reactivation.
+         */
+        historyPreservingReset?: true;
+    };
+    /** Activate chat startup without changing UI visibility */
+    "sdk.activate": undefined;
+    /** Ask core to discover persisted chatter state after final SDK config is ready. */
+    "sdk.session.candidate.request": {
+        requestId: number;
+    };
+    /**
+     * Ask core to restore one server-confirmed live persisted chatter without
+     * creating or identifying a replacement session.
+     */
+    "sdk.session.resume": {
+        chatterToken: string;
+        requestId: number;
+    };
+    /** Reveal a drawer only for the exact existing-only resume that succeeded. */
+    "sdk.session.resume.visibility": {
+        chatterToken: string;
+        requestId: number;
+        isVisible: true;
+    };
+    /**
+     * Web Notification permission as seen from the HOST page origin.
+     *
+     * The widget runs in its own iframe origin, so `Notification.permission` read
+     * inside it is a different value from the one that actually governs the prompt.
+     * Only the SDK can report this truthfully.
+     */
+    "sdk.notifications.permission": {
+        permission: "default" | "granted" | "denied";
+        supported: boolean;
+    };
+    /** Reset the client session, optionally with new config */
+    "sdk.reset": {
+        greeting?: string | null;
+        greetingResponseId?: string | null;
+        language?: string;
+        identityToken?: string;
+        metaFields?: Record<string, MetaFieldValue>;
+        sensitiveMetaFields?: Record<string, MetaFieldValue>;
+        resetChatHistory?: boolean;
+        requestId?: string;
+        /** Internal reload recovery hint; the SDK always owns this field. */
+        reactivate?: boolean;
+        /**
+         * Internal history-preservation proof; the SDK always owns this field.
+         * Core may restore only this exact chatter and must never fall through to
+         * create/identify when completing a soft reset.
+         */
+        expectedChatterToken?: string;
+        /**
+         * Internal storage-scope proof paired with expectedChatterToken. An
+         * identified chatter persists in tab-scoped storage after its one-shot
+         * identity token is consumed; replacement Core must reopen that scope
+         * without replaying the token or clearing anonymous storage.
+         */
+        expectedIdentitySession?: boolean;
+    } | undefined;
+    /** Inject a proactive conversation (SDK → core); URL matches are prevalidated before delay. */
+    "sdk.proactive.inject": {
+        key: string;
+        params?: Record<string, string>;
+        triggerMethod: "url" | "programmatic";
+        intentId: number;
+    };
+    /** Confirm that the intro frame actually rendered a proactive display. */
+    "sdk.proactive.shown": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Retire only the old display while a replacement remains pending. */
+    "sdk.proactive.replaced": {
+        surfaceId: number;
+    };
+    /** Clear all selected/displayed proactives and establish an ordering barrier. */
+    "sdk.proactive.clear": {
+        requestId: number;
+    };
+    /** Notify core that user engaged with proactive message (SDK → core) */
+    "sdk.proactive.engaged": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Notify core that user dismissed proactive messages (SDK → core) */
+    "sdk.proactive.dismissed": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Programmatically trigger a greeting (SDK → core).
+     *  `responseId` is the `triggerAnswer(answerId)` arm of legacy's
+     *  `{ response_id } | { handle }` greeting union; it sends unconditionally. */
+    "sdk.greeting.trigger": {
+        handle?: string;
+        responseId?: string;
+    };
+    /** Deliberately inert ping that unlocks a referrer-stripped intro child. */
+    "intro.handshake": undefined;
+    /** Display proactive messages in intro frame (SDK → intro).
+     *  Mirrors the `core.proactive.show` payload, plus `align` — core has no notion of
+     *  the widget's side, so the SDK stamps it on while forwarding. Without it the
+     *  frame cannot hug the launcher's edge on a left-aligned bot. */
+    "intro.proactive.display": {
+        messages: Array<{
+            id: string;
+            body: string;
+            campaignKey: string;
+            timestamp: number;
+            imageUrl?: string;
+            imageAlt?: string;
+            cta?: {
+                label: string;
+                url: string;
+                openInNewTab: boolean;
+            };
+        }>;
+        duration: number | null;
+        surfaceId: number;
+        align?: "left" | "right";
+    };
+    /** Clear proactive messages in intro frame (SDK → intro) */
+    "intro.proactive.clear": undefined;
+    /** Voice transcript update from SDK (SDK → Core) */
+    "sdk.voice.transcript": {
+        transcript: string;
+        isFinal: boolean;
+    };
+    /** Voice error from SDK (SDK → Core) */
+    "sdk.voice.error": {
+        error: string;
+    };
+    /** Audio level update for waveform (SDK → Core) */
+    "sdk.voice.audioLevel": {
+        level: number;
+    };
+    /** Set the display language (SDK → core) */
+    "sdk.language.set": {
+        language: string;
+    };
+    /** Update metafield key/value pairs (SDK → core) */
+    "sdk.metaFields.set": {
+        metaFields: Record<string, MetaFieldValue>;
+    };
+    /**
+     * Refresh metadata derived from host-page runtime state. These keys are owned
+     * by the SDK and are deliberately separate from the public metadata setter.
+     */
+    "sdk.runtimeMeta.set": {
+        initialURL?: string;
+        introShown?: boolean;
+    };
+    /** Show/hide the dashboard test-mode banner (SDK → core); null hides it */
+    "sdk.testModeBanner.set": {
+        label: string | null;
+    };
+    "sdk.sensitiveMetaFields.set": {
+        sensitiveMetaFields: Record<string, MetaFieldValue>;
+    };
+    /** Delete chatter history and reset the session (SDK → core). */
+    "sdk.history.delete": {
+        requestId?: string;
+    } | undefined;
+    /** Register a device push notification token (SDK → core) */
+    "sdk.notifications.deviceToken.set": {
+        token: string;
+    };
+    /** Track an analytics event (SDK → core) */
+    "sdk.analytics.trackEvent": {
+        key: string;
+        value?: number;
+        meta?: Record<string, unknown>;
+    };
+    /** Request current client state info (SDK → core) */
+    "sdk.info.get": {
+        requestId: string;
+    };
+    /** Request the current non-sensitive metaFields (SDK → core) */
+    "sdk.metaFields.get": {
+        requestId: string;
+    };
+    /** Request conversation + live-agent handoff state (SDK → core) */
+    "sdk.conversation.get": {
+        requestId: string;
+    };
+    /** Request the in-memory message transcript (SDK → core) */
+    "sdk.messages.get": {
+        requestId: string;
+    };
+    /** Set the visible chat composer text (SDK → core) */
+    "sdk.composerText.set": {
+        requestId: string;
+        text: string;
+    };
+    /** Create a manually-constructed proactive message in the intro frame */
+    "sdk.proactive.custom": {
+        id: string;
+        body: string;
+        duration?: number;
+        responseId?: string;
+    };
+    /**
+     * Forward startup config to the button frame so it can render the
+     * correct icon/text/size/fallback UI (SDK → button).
+     */
+    "sdk.button.config": StartupConfig & {
+        align: "left" | "right";
+    };
+    /** Show the button frame with a CSS transition (SDK → button) */
+    "sdk.button.show": undefined;
+    /** Hide the button frame with a CSS transition (SDK → button) */
+    "sdk.button.hide": undefined;
+    /** Show an emoji overlay above the button (SDK → button) */
+    "sdk.button.emoji.show": {
+        emojiUrl: string;
+    };
+    /** Remove the emoji overlay from the button (SDK → button) */
+    "sdk.button.emoji.hide": undefined;
+    /** Focus the button element for keyboard accessibility (SDK → button) */
+    "sdk.button.focus": undefined;
+    /**
+     * Update the unread message count badge on the button (SDK → button).
+     *
+     * `display: "dot"` renders the badge without its digit. It is for a count the
+     * SDK cannot vouch for as a message count — see `_seedUnreadCountFromServer`
+     * in `client/client.ts`. Omitted means the digit is shown.
+     */
+    "sdk.unread.count": {
+        count: number;
+        display?: "count" | "dot";
+    };
+    /** Show a bot greeting popup in the intro frame (SDK → intro) */
+    "intro.greeting.show": {
+        body: string;
+        duration: number | null;
+        style: "Text" | "Emoji";
+        displayId: number;
+        align?: "left" | "right";
+        image?: {
+            url: string;
+            alt: string;
+        };
+        cta?: {
+            label: string;
+            url: string;
+            openInNewTab: boolean;
+        };
+    };
+    /** Hide the bot greeting popup in the intro frame (SDK → intro) */
+    "intro.greeting.hide": undefined;
+    /** Send a user message into the conversation (SDK → core) */
+    "sdk.message.send": {
+        requestId?: string;
+        body: string;
+    };
+    /** Respond to a Zendesk Chat auth token request (SDK → core) */
+    "sdk.zd.auth.response": {
+        token: string | null;
+        error?: string;
+    };
+}
+/**
+ * Frame → SDK events.
+ * Events sent from child iframes back to the SDK.
+ */
+export interface FrameToSdkEvents {
+    /** Frame reports its origin for secure targeting */
+    "frame.origin.report": {
+        origin: string;
+    };
+    /** Core frame signals it has finished initializing */
+    "frame.ready": {
+        name: FrameName;
+    };
+    /** Core requests the SDK to create a browser web notification */
+    "frame.notification.create": {
+        title: string;
+        body?: string;
+        icon?: string;
+        conversationId?: string;
+        messageId?: string;
+    };
+    /** Core asks the host page to follow a validated same-tab link. */
+    "core.host.navigate": {
+        url: string;
+        /**
+         * Compatibility echo for older SDK assets. Current SDKs authorize against the
+         * previously accepted StartupConfig and never against this command payload.
+         */
+        allowedProtocols: string[];
+    };
+    /** Core asks the unsandboxed web host to print a validated image. */
+    "core.host.printImage": {
+        url: string;
+    };
+    /** Core asks the SDK host to expand or restore its viewport surface. */
+    "core.host.viewport.set": {
+        expanded: boolean;
+    };
+    /** A frame encountered an error */
+    "frame.error": {
+        name: FrameName;
+        error: string;
+    };
+    /** Button frame reports its rendered content size so the SDK can resize the iframe to fit */
+    "button.resize": {
+        width: number;
+        height: number;
+    };
+    /** Core sends proactive messages to show in intro frame (core → SDK) */
+    "core.proactive.show": {
+        messages: Array<{
+            id: string;
+            body: string;
+            campaignKey: string;
+            timestamp: number;
+            imageUrl?: string;
+            imageAlt?: string;
+            cta?: {
+                label: string;
+                url: string;
+                openInNewTab: boolean;
+            };
+        }>;
+        duration: number | null;
+        /** Core-owned identity for this selected campaign. */
+        surfaceId: number;
+        /** SDK-originated display metadata; absent for API-driven campaigns. */
+        triggerMethod?: "url" | "programmatic";
+        /** Seconds still to wait in the SDK. URL triggers always carry zero. */
+        displayDelay?: number;
+        frequency?: "always" | "session" | "user";
+        /** Echo of the SDK trigger that produced this display. */
+        intentId?: number;
+    };
+    /** Acknowledge an SDK clear barrier. */
+    "core.proactive.cleared": {
+        requestId: number;
+    };
+    /** Core-origin lifecycle reset for proactive work only (never a greeting). */
+    "core.proactive.clear": undefined;
+    /** Core sends rollout fraction after client config is loaded (core → SDK) */
+    "core.rollout": {
+        value: number | null;
+    };
+    /** Core reports the storage scope selected for the current session lifecycle. */
+    "core.storage.persistence": {
+        mode: "normal" | "session" | "private";
+    };
+    /** Intro frame reports user clicked a proactive message (intro → SDK) */
+    "intro.proactive.clicked": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Intro confirms React committed the requested proactive surface. */
+    "intro.proactive.shown": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Intro frame reports user dismissed proactive messages (intro → SDK) */
+    "intro.proactive.dismissed": {
+        campaignKey: string;
+        surfaceId: number;
+    };
+    /** Intro frame reports its rendered content height so the SDK can size the
+     *  iframe to fit (avoids cropping tall proactive cards with images) (intro → SDK) */
+    "intro.resize": {
+        height: number;
+    };
+    /** Intro frame reports user clicked a proactive bubble's branded CTA (intro → SDK).
+     *  Fire-and-forget navigation — no campaignKey, matching legacy link-click semantics. */
+    "intro.proactive.cta.clicked": {
+        url: string;
+        openInNewTab: boolean;
+        kind: "greeting";
+        displayId: number;
+    } | {
+        url: string;
+        openInNewTab: boolean;
+        kind: "proactive";
+        surfaceId: number;
+        campaignKey: string;
+    };
+    /** Core requests SDK to start voice recording (Core → SDK) */
+    "core.voice.start": undefined;
+    /** Core requests SDK to stop voice recording (Core → SDK) */
+    "core.voice.stop": undefined;
+    /** Core sets voice language for recognition (Core → SDK) */
+    "core.voice.setLanguage": {
+        language: string;
+    };
+    /** Core sets voice recording mode (Core → SDK) */
+    "core.voice.setMode": {
+        mode: "toggle" | "push-to-talk";
+    };
+    /** Core requests SDK to speak text via TTS (Core → SDK) */
+    "core.tts.speak": {
+        text: string;
+    };
+    /** Core publishes a named event for SDK subscribeEvent routing (core → SDK) */
+    "core.event.publish": {
+        key: string;
+        data: unknown;
+    };
+    /** Core notifies SDK that a chatter was created — for chatterTokenCallback (core → SDK) */
+    "core.chatter.created": {
+        chatterId: string;
+        chatterToken: string;
+    };
+    /**
+     * Core found a persisted chatter credential. It remains provisional until the
+     * SDK confirms a live server state and core reports a successful restore.
+     */
+    "core.chatter.candidate": {
+        chatterToken: string;
+        requestId: number;
+    };
+    /** Result of an existing-only sdk.session.resume request. */
+    "core.session.resume.result": {
+        chatterToken: string;
+        requestId: number;
+        resumed: boolean;
+        reason?: string;
+    };
+    /** Result of an exact restore-only drawer visibility request. */
+    "core.session.resume.visibility.result": {
+        chatterToken: string;
+        requestId: number;
+        visible: boolean;
+    };
+    /** Core notifies SDK that a one-shot identity token was successfully exchanged. */
+    "core.identityToken.consumed": {
+        chatterToken: string;
+    };
+    /** Core notifies SDK that a one-shot identity token exchange failed. */
+    "core.identityToken.failed": {
+        reason: string;
+    };
+    /** Core sends an analytics event (core → SDK) */
+    "core.analytics.event": {
+        event: string;
+        data: Record<string, unknown>;
+    };
+    /** Core forwards a custom JavaScript event — for legacy eventCallbacks (core → SDK) */
+    "core.customJavascript": {
+        payload: unknown;
+    };
+    /** Core completed public-only startup config and can accept deferred commands. */
+    "core.ready": undefined;
+    /** Core installed its SDK message router and can accept reset-bound commands. */
+    "core.protocol.ready": undefined;
+    /** Core responds to a programmatic sendMessage request (core → SDK) */
+    "core.message.response": {
+        requestId: string;
+        id?: string;
+        error?: string;
+    };
+    /** Core confirmed an sdk.reset durable clear/reconfiguration barrier. */
+    "core.reset.response": {
+        requestId: string;
+    };
+    /** Core confirmed an sdk.history.delete durable clear barrier. */
+    "core.history.delete.response": {
+        requestId: string;
+    };
+    /** Core broadcasts its public launcher config snapshot before engaged prepare(). */
+    "core.startup.config": StartupConfig;
+    /** Button frame notifies SDK that the user opened chat via keyboard (button → SDK) */
+    "button.click.keyboard": undefined;
+    /** Intro frame notifies SDK that the user clicked a bot greeting (intro → SDK) */
+    "intro.greeting.clicked": {
+        displayId: number;
+    };
+    /** Intro frame notifies SDK that the user dismissed the bot greeting (intro → SDK) */
+    "intro.greeting.dismissed": {
+        displayId: number;
+    };
+    /** Core notifies SDK of the current unread message count (core → SDK) */
+    "core.unread.count": {
+        count: number;
+    };
+    /** Core requests a Zendesk Chat auth token from the host page (core → SDK) */
+    "core.zd.auth.request": {
+        chatterToken: string;
+    };
+    /** Core responds to an sdk.info.get request (core → SDK) */
+    "core.info.response": {
+        requestId: string;
+        isChatOpen: boolean;
+        isDrawerOpen: boolean;
+        hasActiveChatter: boolean;
+        hasClosedChat: boolean;
+    };
+    /** Core responds to an sdk.metaFields.get request (core → SDK) */
+    "core.metaFields.response": {
+        requestId: string;
+        metaFields: Record<string, string | number | boolean | null>;
+    };
+    /** Core responds to an sdk.conversation.get request (core → SDK) */
+    "core.conversation.response": {
+        requestId: string;
+        error?: string;
+        id?: string | null;
+        handoff?: {
+            inLiveChat: boolean;
+            agent?: {
+                id: string;
+                name: string;
+                avatarUrl?: string;
+            };
+        };
+    };
+    /** Core responds to an sdk.messages.get request (core → SDK) */
+    "core.messages.response": {
+        requestId: string;
+        error?: string;
+        messages?: Array<{
+            id: string;
+            role: "user" | "bot" | "agent";
+            type: string;
+            body?: string;
+            createdAt: number;
+            /** Present whenever the transport message carries agent identity. */
+            agent?: {
+                id: string;
+                name: string;
+                avatarUrl?: string;
+            };
+            data?: Record<string, unknown>;
+            origin?: "programmatic";
+        }>;
+    };
+    /** Core responds to an sdk.composerText.set request (core → SDK) */
+    "core.composerText.response": {
+        requestId: string;
+        ok?: true;
+        error?: string;
+    };
+}