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

package/dist/types.d.ts

@@ -0,0 +1,849 @@
+import type { CsatFeedbackOption, CsatSurveySettings, FileUploadErrorData } from "./shared-utils/index.js";
+/**
+ * Bridge type definitions describing the state and events that flow between
+ * the messaging core frame and the display layer (app or native WebView).
+ *
+ * These types are the source of truth for the `@ada-cx/messaging-bridge`
+ * package and must stay in sync with the AsyncAPI spec at asyncapi.yml.
+ */
+export interface FallbackUiLink {
+    label: string;
+    url: string;
+}
+export type LocalizedFallbackUiMessage = string | Record<string, string>;
+export type LocalizedFallbackUiLinks = FallbackUiLink[] | Record<string, FallbackUiLink[]>;
+export interface FallbackUiConfig {
+    icon: {
+        isDefault: boolean;
+        image: string | null;
+    };
+    message: LocalizedFallbackUiMessage;
+    links: LocalizedFallbackUiLinks;
+}
+export interface SamlLoginButtonConfig {
+    backgroundColor: string | null;
+    fontFamily: string | null;
+    header: string | null;
+    headerMessage: string | null;
+    title: string | null;
+    text: string | null;
+}
+export type { CsatFeedbackOption, CsatSurveySettings };
+export interface CsatSubmitData {
+    score?: number;
+    style?: string;
+    feedback?: string[];
+    resolved?: boolean;
+    comment?: string;
+    customerEffortScore?: number;
+    netPromoterScore?: number;
+}
+export interface CaptureData {
+    placeholder: string;
+    validationErrorMessage: string;
+    isOptional: boolean;
+    cancelCaptureResponseId: string;
+    cancelCaptureLabel: string;
+    dataId: string;
+    /** True while a submit for this capture is in flight. Owned by core, so a
+     *  replayed or reordered capture-state event can never re-enable a field whose
+     *  submit has not resolved. Optional because a native host may hydrate a snapshot
+     *  cached before this field existed; absent reads as "not submitting". */
+    isSubmitting?: boolean;
+    /**
+     * The latest submit for this capture that core failed or dropped WITHOUT a
+     * server validation verdict: no session to round-trip, an over-length
+     * value, a transport failure, a duplicate submit while one is in flight,
+     * or a host-driven reset/engagement gate. `submitId` echoes the key the
+     * submitter sent with `capture.submit` (null when it sent none), so
+     * `operations.submitCapture` handles settle only on their OWN submit's
+     * failure. Server validation rejections ride `validationErrorMessage`
+     * instead. Optional: absent on a core document that predates it — those
+     * cores report these failures nowhere capture-scoped, so pass `timeoutMs`.
+     */
+    lastSubmitFailure?: {
+        submitId: string | null;
+        message: string;
+    } | null;
+}
+export interface ListSelectionData {
+    cancelCaptureResponseId: string;
+    cancelCaptureLabel: string;
+    isOptional: boolean;
+    showExitListOptionBlock: boolean;
+    dataId: string;
+}
+/**
+ * `waiting_for_data`: the bot is blocked on an external system and api asked the
+ * client to say so. Mirrors core's `conversation.stateData.liveChat` payload.
+ */
+export interface LiveChatStateData {
+    notificationMessage: string;
+    notificationMessageSubtext: string;
+    showBanner: boolean;
+    timeoutAfterMs: string;
+}
+interface BaseMessage {
+    id: string;
+    sender: "user" | "bot" | "agent";
+    timestamp: number;
+    body: string;
+    /** The conversation this message belongs to. Stamped on creation/ingest, and
+     * backfilled once the id exists. Core no longer reads it directly — End Chat
+     * availability moved to the `chat.userHasSentInCurrentConversation` flag (EXP-380).
+     * Mirrors core's `BaseMessage` (kept in sync by hand). */
+    conversationId?: string;
+    reviewable?: boolean;
+    /** Persisted response-review vote restored from the conversation log. */
+    reaction?: 1 | -1;
+    /** The message's durable `_id` cursor (ObjectId string): the loss-tolerant
+     * read watermark key. Absent on optimistic bubbles / non-durable frames. */
+    cursor?: string;
+    streamId?: string;
+    isStreaming?: boolean;
+    /** Stable render key that survives the optimistic→durable id swap, so a
+     * reconciled user message's bubble does not replay its entrance animation. */
+    clientKey?: string;
+    /** The live agent who authored this message, stamped by `toBotMessage` on both the
+     * live and history-restore paths. Preferred over `agent.activeAgent` when naming a
+     * sender — restored history outlives an agent's session.
+     * Mirrors core's `BaseMessage` (kept in sync by hand). */
+    agentInfo?: AgentInfo;
+    /** A client-side send failed; retry eligibility is reported separately. */
+    deliveryStatus?: "failed";
+    /** Core still owns the trusted send envelope needed to retry this failure. */
+    isRetryable?: boolean;
+}
+export interface TextMessage extends BaseMessage {
+    type: "text";
+    attachments?: Array<{
+        url: string;
+        filename: string;
+        mimeType: string;
+    }>;
+}
+export interface QuickReply {
+    label: string;
+    /** Empty on an `accepted_value` chip — there is no Response behind it. */
+    target: string;
+    /** `accepted_value` sends the visible label as a plain user utterance instead
+     *  of triggering a Response; the Ask step resolves it to the accepted value. */
+    buttonType: "suggestion" | "switch" | "accepted_value";
+    /** Raw accepted value, used as the utterance only when the label is absent. */
+    value?: string;
+}
+export interface QuickRepliesMessage extends BaseMessage {
+    type: "quick_replies";
+    quickReplies: QuickReply[];
+    isForced: boolean;
+    /** Chip layout authored on the playbook Ask step. Overrides the bot-wide
+     *  `config.buttonLayout*` on both viewports when present. */
+    buttonLayout?: "stacked" | "carousel";
+    /** Authored on the Ask step: true shows every chip, false collapses past
+     *  `MAX_COLLAPSED_QUICK_REPLIES`. Undefined inherits the bot-wide setting. */
+    showAll?: boolean;
+}
+export interface LinkMessage extends BaseMessage {
+    type: "link";
+    url: string;
+    linkText: string;
+    title: string;
+    linkDescription: string;
+    linkIcon: string;
+    altText: string;
+    newWindow: boolean;
+    articleId: string | null;
+    /** True when this normalized link originated as legacy's sized-popup block. */
+    isWebWindow?: boolean;
+    windowHeight?: number;
+    windowWidth?: number;
+}
+export interface PictureMessage extends BaseMessage {
+    type: "picture";
+    picUrl: string;
+    altText: string;
+}
+export interface VideoMessage extends BaseMessage {
+    type: "video";
+    vidUrl: string;
+    altText: string;
+}
+export interface DownloadableMessage extends BaseMessage {
+    type: "downloadable";
+    url: string;
+    name: string;
+    mimeType: string | null;
+}
+export interface AgentInfo {
+    name: string;
+    imageUrl: string | null;
+    internalId: string | null;
+    defaultImage: boolean;
+}
+export interface PresenceMessage extends BaseMessage {
+    type: "presence";
+    event: string;
+    agentInfo?: AgentInfo;
+}
+export interface OptionItem {
+    id: string;
+    label: string;
+    description?: string;
+    datetime?: string;
+}
+export interface OptionsMessage extends BaseMessage {
+    type: "options_message";
+    options: OptionItem[];
+}
+export interface SelectableListItem {
+    id: string;
+    text: string;
+}
+export interface SelectableListMessage extends BaseMessage {
+    type: "surfaceable_list_selection";
+    variableId: string;
+    selectables: SelectableListItem[];
+    multiple: boolean;
+    prompt: string;
+}
+export interface QueueBotBlockMessage extends BaseMessage {
+    type: "queue_bot_block";
+    queuePosition?: number | null;
+    waitMessage?: string;
+    platform?: string;
+}
+export interface WidgetMessage extends BaseMessage {
+    type: "widget";
+    widgetName: string;
+    ariaLabel: string;
+    widgetUrl: string;
+    linkText: string;
+    linkSubtext: string;
+    inlineInChat: boolean;
+}
+export interface SignInMessage extends BaseMessage {
+    type: "sign_in";
+    authButtonLabel: string;
+    authLink: string;
+    authProvider: string;
+    authLinkExpired: boolean;
+    messageLead: string;
+}
+/**
+ * Silent OAuth. api emits this when a Sign In block resolves to a provider the
+ * chatter is already authenticated with in this browser.
+ *
+ * There is no visible UI — the row loads `authLink` in a hidden iframe so the
+ * provider's existing session cookie completes the flow and api resumes the
+ * conversation on its own.
+ */
+export interface SeamlessOAuthMessage extends BaseMessage {
+    type: "seamless_oauth";
+    authLink: string;
+    authProvider: string;
+    authLinkExpired: boolean;
+    /** Response the bot falls back to if the silent flow fails. */
+    errorResponseId: string;
+}
+/**
+ * Web Push opt-in prompt, emitted from a Notification block during a live-agent
+ * handoff so the chatter can be told when an agent replies after tabbing away.
+ */
+export interface NotificationPermissionMessage extends BaseMessage {
+    type: "local_notification_permission";
+    /** Prompt text authored in the Notification block. */
+    body: string;
+}
+export type CsatScaleType = "thumbs" | "emoji" | "1-5" | "1-7" | "0-10" | "1-10";
+export interface CsatMessage extends BaseMessage {
+    type: "csat";
+    surveyType: string;
+    scaleType: CsatScaleType;
+    score: number | null;
+    submitted: boolean;
+    feedback?: string[];
+    resolved?: boolean | null;
+    comment?: string | null;
+    customerEffortScore?: number | null;
+    netPromoterScore?: number | null;
+    isPositive?: boolean | null;
+}
+export type Message = TextMessage | QuickRepliesMessage | LinkMessage | PictureMessage | VideoMessage | DownloadableMessage | PresenceMessage | QueueBotBlockMessage | SelectableListMessage | OptionsMessage | NotificationPermissionMessage | SeamlessOAuthMessage | SignInMessage | WidgetMessage | CsatMessage;
+/** Native SDK wrapper hosting the widget; null on the web. */
+export type SdkPlatform = "IOS" | "ANDROID" | "REACTNATIVE" | null;
+/**
+ * The derived display state core publishes to the app frame on every
+ * `core.state.update`. Keys are dotted strings grouped by prefix:
+ *
+ * - `app.*` — frame lifecycle: loading, initialized, session id.
+ * - `config.*` — bot configuration and theming resolved from client config.
+ * - `appearance.*` — user-chosen in-widget theme/text-size overrides.
+ * - `saml.*` — SAML sign-in gate state and login-button styling.
+ * - `transcript.*` — email/download transcript request status.
+ * - `connection.*` — realtime transport connectivity.
+ * - `chat.*` — the conversation: messages, cursors, composer, send status.
+ * - `conversation.*` — server conversation-state blocks (capture, list
+ *   selection, live-chat wait states).
+ * - `liveAgent.*` / `agent.*` — handoff lifecycle, queue position, and the
+ *   agents present in the conversation.
+ * - `zendesk.*` / `zendeskMessaging.*` — Zendesk handoff SDK status.
+ * - `file.*` — handoff file-upload availability, progress, and errors.
+ * - `outage.*` — response-delay and connectivity-loss banners.
+ * - `error.*` — fatal error surface.
+ * - `chatter.*` — end-user preferences: language, notifications, translations.
+ * - `ui.*` — transient UI signals (typing indicators, dialogs, toasts).
+ * - `voice.*` — Web Speech voice input/TTS state.
+ * - `csat.*` / `endChat.*` — survey settings, eligibility, and End Chat gates.
+ * - `security.*` — Turnstile challenge state.
+ *
+ * Read values by key, or use the `STATE` constants for typo-safe access. This
+ * contract is shared with `packages/core` and must stay in sync with it.
+ *
+ * Update cadence: core coalesces to at most ONE `core.state.update` per
+ * microtask, and skips the post entirely when the derived state is unchanged.
+ * Unchanged keys keep their reference identity across updates, so `Object.is`
+ * per key is a sound change detector (see `BridgeClient.subscribeKey`) — the
+ * exception is `chat.messages`, whose array identity changes on every
+ * streaming delta.
+ */
+export interface AppDisplayState {
+    "app.loading": boolean;
+    "app.initialized": boolean;
+    "app.testModeBannerLabel"?: string | null;
+    "app.sessionId": string;
+    "config.handle": string;
+    "config.features": Record<string, boolean>;
+    "config.clientDefaultLanguage": string;
+    "config.translatedLanguages": string[];
+    "config.emailTranscriptEnabled": boolean;
+    "config.downloadTranscriptEnabled": boolean;
+    "config.sdkPlatform": SdkPlatform;
+    "config.sdkSupportsDownloadLink": boolean;
+    "config.showBranding": boolean;
+    /** Reseller/partner name appended after the Ada logomark in the footer. */
+    "config.adaPartnerName": string | null;
+    "config.botName": string | null;
+    "config.botDescription": string | null;
+    "config.botDescriptionEnabled": boolean;
+    "config.botAvatarUrl": string | null;
+    "config.tintColor": string | null;
+    "config.style": "round" | "rectangular";
+    "config.textSize": "small" | "default" | "large";
+    "config.headerColorEnabled": boolean;
+    "config.headerColor": string | null;
+    "config.headerTextColor": string | null;
+    "config.chatEnabled": boolean;
+    "config.privacyLink": string | null;
+    "config.privacy": boolean;
+    "config.theme": "light" | "dark" | "auto";
+    "config.advancedColorsEnabled": boolean;
+    "config.textOverAccentColor": string | null;
+    "config.buttonLayoutMobile": "carousel" | "stacked";
+    "config.buttonLayoutDesktop": "carousel" | "stacked";
+    "config.showAllQuickReplies": boolean;
+    "config.isMobileViewport": boolean;
+    "appearance.userTheme": "light" | "dark" | "auto" | null;
+    "appearance.userTextSize": "small" | "default" | "large" | null;
+    "config.fallbackUi": FallbackUiConfig | null;
+    "config.buttonSize": number;
+    "config.buttonBackgroundColor": string | null;
+    "config.avatar": {
+        letter: string;
+        image: string | null;
+        useLetter: boolean;
+    };
+    "config.agentAvatar": {
+        isDefault: boolean;
+        image: string | null;
+    };
+    "config.allowedProtocols": string[];
+    "config.customRedactions": Array<{
+        pattern: string;
+        replacement?: string;
+    }>;
+    "saml.locked": boolean;
+    "saml.url": string | null;
+    "saml.loginButton": SamlLoginButtonConfig;
+    /** `idle -> pending` on `settings.transcript.email.send`, then
+     * `-> success | error` when the request resolves. Act on the
+     * `pending -> terminal` transition, not on the standing value. */
+    "transcript.email.status": "idle" | "pending" | "success" | "error";
+    /** Advances on EVERY `transcript.email.status` write. A request core drops
+     * before it goes `pending` (a host-driven reset in progress) writes its
+     * terminal status inside one broadcast batch, so the `pending -> terminal`
+     * edge never appears — correlate on this advancing to a terminal status
+     * instead. Optional: absent on a core document that predates it. */
+    "transcript.email.status.seq"?: number;
+    /** Same lifecycle as `transcript.email.status`, for
+     * `settings.transcript.download.request`. */
+    "transcript.download.status": "idle" | "pending" | "success" | "error";
+    /** Same contract as `transcript.email.status.seq`, for downloads. */
+    "transcript.download.status.seq"?: number;
+    "connection.socket.connected": boolean;
+    "connection.pusher.channelConnected": boolean;
+    "chat.responseLoading": boolean;
+    /** True from the moment a user message lands until the bot's reply arrives
+     * (or the send fails). This — not `chat.isSending` — is the "a reply is
+     * coming" signal to key composure/typing UI on. */
+    "chat.isGenerating": boolean;
+    /** Optional while core/app assets roll independently. */
+    "chat.isUnifiedReasonerGenerating"?: boolean;
+    "chat.isConversationActive"?: boolean;
+    "chat.canLoadMore": boolean;
+    "chat.loadingPreviousMessages": boolean;
+    /** Bumped each time restored/baseline history is (re)loaded; drives the
+     * app's one-shot "land at the bottom of restored history" scroll on reload. */
+    "chat.recentMessagesLoadSeq": number;
+    /** Highest message `_id` cursor the user has read in the current conversation
+     * (persisted across reloads); seeds the unread divider + restore scroll. */
+    "chat.lastReadCursor": string;
+    /** Active conversation id; lets read-tracking reset its per-conversation
+     * watermark accumulator (cursor spaces are per conversation). Arrives
+     * asynchronously via the realtime channel, NOT with the send response —
+     * null until the conversation is established server-side. */
+    "chat.conversationId"?: string | null;
+    /** Monotonic conversation/reset boundary from core. Optional for compatibility
+     * with an older core asset during rollout. */
+    "chat.conversationGeneration"?: number;
+    "chat.messages.reactions": Record<string, number>;
+    /**
+     * True while api reports any active conversation state. Optional for rolling
+     * compatibility with an older core document; the app defaults it to false.
+     */
+    "conversation.inState"?: boolean;
+    "conversation.stateData.capture": CaptureData | null;
+    "conversation.stateData.listSelection": ListSelectionData | null;
+    /** `waiting_for_data`: null unless the bot is blocked on an external system. */
+    "conversation.stateData.liveChat": LiveChatStateData | null;
+    /** The transcript. Updates on any append/upsert/stream delta/reaction/
+     * history load; array identity changes on EVERY streaming delta, so
+     * derive a signature (or use a custom `equals`) before diffing. An
+     * optimistic user row appears here immediately on send; its durable
+     * server echo later reconciles IN PLACE, swapping `id` while carrying
+     * `clientKey` forward — key on `clientKey ?? id` (see `messageKey`). */
+    "chat.messages": Message[];
+    /** Rarely observable as `true` on the bot path: it is set and cleared
+     * within one synchronous dispatch batch, and only one state update per
+     * batch is posted. It stays true only across a genuine failure gap.
+     * Watch `chat.isGenerating` for "in flight" UI instead. */
+    "chat.isSending": boolean;
+    /** Set when a send fails (also clears the sending/generating flags).
+     * Cleared ONLY by the `chat.error.dismiss` event — clear it in core
+     * rather than hiding it locally, or the session's second error renders
+     * nothing. */
+    "chat.error": string | null;
+    /** Monotonic counter that advances every time core SETS `chat.error` —
+     * including when the new text is identical to the current one (the same
+     * over-length send repeated back-to-back), which `chat.error` alone cannot
+     * surface. Correlate send failures on this advancing and read the text
+     * from `chat.error`; `operations.sendMessage` handles do exactly that.
+     * Optional: absent on a core document that predates it — fall back to
+     * watching `chat.error` transitions. */
+    "chat.error.seq"?: number;
+    /** The `tempMessageUuid` of the `operations.sendMessage` send that raised
+     * `chat.error`, or null when the error is not attributable to one keyed
+     * send (capture failures, transcript failures, non-bridge sends). Send
+     * handles reject only when the key matches their own, so an unrelated
+     * failure in flight never falsely rejects a delivered send. Optional:
+     * absent on a core document that predates it — fall back to
+     * `chat.error.seq`. */
+    "chat.error.clientKey"?: string | null;
+    "chat.composerText"?: {
+        text: string;
+        revision: number;
+    } | null;
+    /** Interactive blocks (quick replies, options) the chatter has already
+     * answered. Includes blocks a later same-conversation user message
+     * superseded, so the set survives a reload. Filter interactive rows on
+     * it before enabling them. */
+    "chat.answeredInteractiveIds": string[];
+    /** A playbook step is running, so the composer must refuse to send. */
+    "chat.playbookStepExecuting": boolean;
+    "liveAgent.inLiveChat"?: boolean;
+    "liveAgent.inPending"?: boolean;
+    "liveAgent.isActive"?: boolean;
+    "liveAgent.hasConversationEnded"?: boolean;
+    "liveAgent.conversationEndedByChatter"?: boolean;
+    "liveAgent.platform.name"?: string | null;
+    "liveAgent.platform.departmentId"?: number | null;
+    "liveAgent.queuePosition"?: number | null;
+    /** A queue-cancel POST is in flight; the banner's Cancel is disabled while true. */
+    "liveAgent.queueCancelPending"?: boolean;
+    "liveAgent.handoff.lastEvent"?: {
+        userQuestion: string | null;
+        transcriptUrl: string | null;
+        queueName: string | null;
+        lang: string | null;
+        variables: Record<string, unknown> | null;
+    } | null;
+    "liveAgent.handoff.retryRequestedCount"?: number;
+    "agent.list"?: Array<{
+        id: string;
+        name: string;
+        imageUrl: string | null;
+        defaultImage: boolean;
+        isActive: boolean;
+        isTyping: boolean;
+    }>;
+    /** The agent currently active in the conversation, or null. Prefer a
+     * message's own `agentInfo` when naming its sender — restored history
+     * outlives an agent's session. */
+    "agent.activeAgent"?: {
+        id: string;
+        name: string;
+        imageUrl: string | null;
+        defaultImage: boolean;
+        isActive: boolean;
+        isTyping: boolean;
+    } | null;
+    "zendesk.sdk.initialized"?: boolean;
+    "zendesk.sdk.disconnected"?: boolean;
+    "zendesk.sdk.reconnecting"?: boolean;
+    "zendesk.sessionId"?: string | null;
+    "zendesk.department.status"?: "ONLINE" | "OFFLINE" | null;
+    "zendesk.department.id"?: number | null;
+    "zendesk.tags"?: string[] | null;
+    "zendesk.fatalRequestErrorReached"?: boolean;
+    "ui.fatalHandoffDialog.pending"?: boolean;
+    "ui.fatalHandoffDialog.cancelFailed"?: boolean;
+    "zendeskMessaging.sdk.initializationStatus"?: 0 | 1 | 2;
+    "zendeskMessaging.sdk.initialized"?: boolean;
+    "zendeskMessaging.sdk.disconnected"?: boolean;
+    "zendeskMessaging.sdk.reconnecting"?: boolean;
+    "zendeskMessaging.conversationId"?: string | null;
+    "file.uploadVisible"?: boolean;
+    "file.uploadEnabled"?: boolean;
+    /** A live-agent upload is in flight. Core can reject a selection and go
+     * straight to `file.uploadError` WITHOUT ever setting this true, so an
+     * upload observer must watch both keys. */
+    "file.isUploading"?: boolean;
+    "file.uploadError"?: {
+        errorKey: "FILE_UPLOAD_UNSUPPORTED_TYPE" | "FILE_UPLOAD_UNKNOWN_ERROR" | "FILE_UPLOAD_EXCEED_SIZE_LIMIT" | "FILE_UPLOAD_ERROR" | "FILE_UPLOAD_MULTIPLE_FILES";
+        errorData: FileUploadErrorData;
+    } | null;
+    "file.transfer"?: {
+        progress?: number;
+        fileName?: string;
+        fileSize?: number;
+    } | null;
+    "outage.responseDelayed"?: boolean;
+    "outage.showServiceRestoredToast"?: boolean;
+    "outage.networkConnectivityToast"?: "offline" | "online" | null;
+    /** Connectivity is lost per core's verdict — unaffected by the toast being dismissed. */
+    "outage.connectivityLost"?: boolean;
+    "error.hasErrors": boolean;
+    "error.type": string | null;
+    "chatter.language": string;
+    "chatter.alertSoundEnabled": boolean;
+    "chatter.deviceNotificationsEnabled": boolean;
+    /** Host-origin Web Notification permission, as reported by the SDK. Permission
+     * is per-origin, so the widget frame's own value is not the one that governs
+     * the prompt. */
+    "chatter.notificationPermission": "default" | "granted" | "denied";
+    /** False when the host browser exposes no Notification API. */
+    "chatter.notificationsSupported": boolean;
+    "chatter.smsNotificationsEnabled": boolean;
+    "chatter.translations": Record<string, string | null>;
+    "ui.typingIndicator.visible": boolean;
+    /** api's bot `typing_indicator`; separate from the above because the UI gates
+     * that one on live chat. */
+    "ui.botTyping.visible": boolean;
+    "ui.showRetryDialog"?: boolean;
+    "ui.retryDialog.pending"?: boolean;
+    "voice.enabled"?: boolean;
+    "voice.isRecording"?: boolean;
+    "voice.mode"?: "toggle" | "push-to-talk";
+    "voice.currentTranscript"?: string;
+    "voice.isFinal"?: boolean;
+    "voice.audioLevel"?: number;
+    "voice.error"?: string | null;
+    "voice.ttsEnabled"?: boolean;
+    "csat.autoTrigger"?: boolean;
+    "csat.showAfterEndChat"?: boolean;
+    "csat.botSettings"?: CsatSurveySettings | null;
+    "csat.agentSettings"?: CsatSurveySettings | null;
+    "csat.settings"?: CsatSurveySettings | null;
+    /** Set on a failed (or invalid-for-scale) survey submit; cleared to null
+     * at the start of every non-partial submit. Match it together with the
+     * two error scope keys below — the same two-part guard the success triple
+     * needs. */
+    "csat.submitError"?: string | null;
+    "csat.submitErrorConversationId"?: string | null;
+    "csat.submitErrorSurveyType"?: string | null;
+    /** Advances every time `csat.submitError` is set to a message — including
+     * a repeat of the identical text (the same submit dropped twice), which
+     * the text alone cannot surface. Correlate error verdicts on its advance
+     * plus the surveyType/conversation match. Optional: absent on a core
+     * document that predates it — fall back to text transitions. */
+    "csat.submitError.seq"?: number;
+    /** Monotonic counter bumped on each TERMINAL survey submit success (a
+     * `partial` stage-1 submit does not bump it). Correlate by latching the
+     * seq before submitting and matching surveyType AND conversationId when
+     * it advances — type alone is insufficient: a late response from a dead
+     * conversation would close the new conversation's survey of the same
+     * type. `operations.submitCsat().settled()` implements this. */
+    "csat.submitSuccess.seq"?: number;
+    "csat.submitSuccess.surveyType"?: string | null;
+    "csat.submitSuccess.conversationId"?: string | null;
+    /** Request->response with no request id: `csat.checkEndChatEligibility`
+     * sets status `loading`, and the answer sets `ready` and bumps the seq.
+     * Latch the seq when asking and treat yourself as pending until it
+     * advances — a `ready -> ready` re-check changes no other observable
+     * state. `operations.checkEndChatEligibility()` implements this. */
+    "csat.endChatEligibility.seq"?: number;
+    "csat.endChatEligibility.status"?: "idle" | "loading" | "ready";
+    "csat.endChatEligible"?: boolean | null;
+    "csat.endChatSurveyTarget"?: "bot" | "agent" | null;
+    /** Whether End Chat is offered: the conversation has not ended, the user
+     * has sent in it, and a conversation id exists. Gates the header close
+     * affordance. */
+    "endChat.canEnd"?: boolean;
+    "config.isParentElementMode"?: boolean;
+    "config.hideDefaultHeader"?: boolean;
+    "ui.secretMessage.isOpen"?: boolean;
+    "ui.secretMessage.buttonEnabled"?: boolean;
+    "security.turnstileSiteKey"?: string | null;
+    "security.challengeEnabled"?: boolean;
+    "security.challengeError"?: string | null;
+}
+/**
+ * Events the display layer sends to core through `sendEvent`. Each key maps to
+ * its payload type (`undefined` = no payload). Grouped by prefix:
+ *
+ * - `app.*` — lifecycle: `app.initialize` is the REQUIRED mount handshake
+ *   (send it within 15 seconds of the frame loading, or core unmounts the app
+ *   frame), plus reset, new-conversation, and error reporting.
+ * - `chat.*` — conversation actions: send/retry messages, select quick
+ *   replies/options/lists, report read cursors, react, load history.
+ * - `capture.*` / `listSelection.*` — answer or cancel conversation-state
+ *   data blocks.
+ * - `liveAgent.*` — request/cancel/end a handoff, agent-directed messages,
+ *   typing edges, visitor info.
+ * - `zendesk.*` / `zendeskMessaging.*` — Zendesk handoff SDK control.
+ * - `file.*` — handoff file-upload start/cancel/retry/error-dismiss.
+ * - `voice.*` — voice recording, mode, transcript, and TTS control.
+ * - `ui.*` — widget chrome interactions (close, minimize, dialogs, toasts,
+ *   viewport, composer-changed edge).
+ * - `settings.*` / `appearance.*` — end-user preference changes.
+ * - `csat.*` / `endChat.*` — survey submission, shown-tracking, eligibility.
+ * - `outage.*` — retry after a response outage.
+ * - `security.*` — Turnstile verify/error/expire.
+ *
+ * This contract is shared with `packages/core` and must stay in sync with it.
+ */
+export interface AppEvents {
+    /** Send a chat message. When `tempMessageUuid` is a RFC 4122 uuid, core
+     * seeds the optimistic message's `clientKey` from it, so the sender can
+     * find its own send in `chat.messages` (the durable echo keeps the key
+     * across the id swap). `messageType: "secret"` masks the send: the raw
+     * body never enters the transcript, so no correlatable row exists.
+     * Prefer `operations.sendMessage`, which handles all of this. */
+    "chat.message.send": {
+        body: string;
+        messageType: string;
+        tempMessageUuid: string;
+    };
+    "chat.message.retry": {
+        message: {
+            id?: string;
+            body?: string;
+            type: string;
+            tempMessageUuid?: string;
+        };
+    };
+    "chat.quickReply.select": {
+        label: string;
+        target: string;
+        buttonType: string;
+        /** Raw accepted value. Set only on target-less `accepted_value` chips and
+         *  used as the utterance only when the visible label is absent. */
+        value?: string;
+        messageId: string;
+    };
+    /** Highest message `_id` cursor the user has scrolled into view; advances the
+     * persisted read watermark for the conversation it was observed in. */
+    "chat.messages.read": {
+        cursor: string;
+        conversationId?: string;
+    };
+    /** The user activated a `link` message's preview card. Core resolves the stored
+     * message for tracking and, for a validated same-tab link, host navigation. */
+    "chat.link.click": {
+        messageId: string;
+        navigateInHost?: boolean;
+    };
+    /** Ask the unsandboxed web host to print a validated transcript image. */
+    "image.print.request": {
+        url: string;
+    };
+    /** Ask the SDK host to expand or restore the app's viewport surface. */
+    "ui.hostViewport.set": {
+        expanded: boolean;
+    };
+    "liveAgent.handoff.request": {
+        platformData: {
+            platform: string;
+            departmentId?: number;
+            tags?: string[];
+        };
+    };
+    "liveAgent.handoff.cancel": undefined;
+    "liveAgent.chat.end": undefined;
+    "liveAgent.message.send": {
+        message: string;
+    };
+    "liveAgent.typing.start": undefined;
+    "liveAgent.typing.stop": undefined;
+    "liveAgent.visitor.setInfo": {
+        displayName?: string;
+        email?: string;
+        phone?: string;
+    };
+    "zendesk.sdk.initialize": {
+        accountKey: string;
+        options?: Record<string, unknown>;
+    };
+    "zendesk.sdk.teardown": undefined;
+    "zendesk.department.set": {
+        departmentId: number;
+    };
+    "zendesk.transcript.send": {
+        transcript: string[];
+        externalChatId: string;
+    };
+    "zendesk.transcript.clear": undefined;
+    "zendeskMessaging.sdk.initialize": undefined;
+    "zendeskMessaging.sdk.destroy": undefined;
+    "zendeskMessaging.conversation.load": undefined;
+    "file.upload.start": {
+        file: File;
+        uploadId?: string;
+        platform?: string;
+    };
+    "file.upload.cancel": undefined;
+    "file.upload.errorDismiss": undefined;
+    "file.upload.retry": {
+        file: File;
+        uploadId?: string;
+    };
+    "voice.recording.start": undefined;
+    "voice.recording.stop": undefined;
+    "voice.mode.set": {
+        mode: "toggle" | "push-to-talk";
+    };
+    "voice.transcript.apply": {
+        transcript: string;
+    };
+    "voice.tts.toggle": {
+        enabled: boolean;
+    };
+    "ui.closeButton.click": undefined;
+    "ui.minimizeButton.click": undefined;
+    "ui.toast.dismiss": undefined;
+    "ui.retryDialog.confirm": undefined;
+    "ui.retryDialog.dismiss": undefined;
+    /** Close a retry/fatal recovery sheet without posting a handoff control request. */
+    "ui.handoffDialog.dismiss": undefined;
+    "ui.fatalHandoffDialog.cancel": undefined;
+    /** Leave a live-chat queue from the queue banner, outside the retry prompt. */
+    "ui.queueCancel.request": undefined;
+    "outage.retry": undefined;
+    "settings.language.change": {
+        language: string;
+    };
+    "settings.alertSound.toggle": {
+        enabled: boolean;
+    };
+    "settings.notifications.toggle": {
+        enabled: boolean;
+    };
+    "settings.smsNotifications.toggle": {
+        enabled: boolean;
+    };
+    "settings.transcript.email.send": {
+        email: string;
+    };
+    "settings.transcript.download.request": undefined;
+    "settings.notifications.requestPermission": undefined;
+    "appearance.setTheme": {
+        theme: "light" | "dark" | "auto";
+    };
+    "appearance.setTextSize": {
+        textSize: "small" | "default" | "large";
+    };
+    "app.initialize": undefined;
+    "app.reset": undefined;
+    "app.startNewConversation": undefined;
+    "app.error.report": {
+        message: string;
+        stack: string;
+        componentStack: string;
+    };
+    "chat.message.reaction.add": {
+        messageId: string;
+        reaction: number;
+    };
+    "capture.submit": {
+        value: string;
+        dataId: string;
+        /** Optional uuid-shaped key for this submit. Core echoes it on
+         * `conversation.stateData.capture.lastSubmitFailure.submitId` when it
+         * fails or drops the submit without a server validation verdict, so
+         * the submitter can settle on its own submit's failure.
+         * `operations.submitCapture` mints one per call. */
+        submitId?: string;
+    };
+    "capture.cancel": {
+        cancelResponseId: string;
+        cancelLabel: string;
+        dataId: string;
+    };
+    "listSelection.cancel": {
+        cancelResponseId: string;
+        cancelLabel: string;
+        dataId: string;
+    };
+    "chat.logs.loadMore": undefined;
+    /** The chatter dismissed the error toast. Clears `chat.error`. */
+    "chat.error.dismiss": undefined;
+    "csat.submit": {
+        data: CsatSubmitData;
+        surveyType: string;
+        partial?: boolean;
+        /**
+         * The conversation this survey rates. Sent for a survey rendered IN the
+         * transcript, whose row can outlive its conversation — the transcript is
+         * preserved across a conversation change, so the held id is not a safe proxy.
+         * Optional: omitted by the End Chat / proactive flows, where core resolves it.
+         */
+        conversationId?: string | null;
+    };
+    "csat.shown": {
+        surveyType: string;
+        conversationId?: string | null;
+    };
+    "csat.checkEndChatEligibility": undefined;
+    "endChat.skipCsat": undefined;
+    "ui.secretMessage.toggle": {
+        open: boolean;
+    };
+    /** Composer text changed — drives the content-free handoff typing edge. The
+     * event is deliberately payload-free: core never reads the text, so the
+     * composer contents must not cross the frame boundary (secret mode exists to
+     * keep exactly that content out of this channel). */
+    "ui.composer.textChanged": undefined;
+    "chat.option.select": {
+        optionId: string;
+        optionLabel?: string;
+        messageId: string;
+    };
+    "chat.selectableList.submit": {
+        selectedIds: string[];
+        dataId: string;
+    };
+    "security.turnstile.verify": {
+        token: string;
+    };
+    "security.turnstile.error": undefined;
+    "security.turnstile.expire": undefined;
+}