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

package/dist/operations.d.ts

@@ -0,0 +1,323 @@
+import type { AppDisplayState, AppEvents, CsatSubmitData, Message, OptionItem, QuickReply } from "./types.js";
+/**
+ * The minimal client surface the operations layer builds on. Satisfied by the
+ * real `BridgeClient` and by the npm test mock.
+ */
+export interface BridgeOperationsHost {
+    getState(): AppDisplayState | null;
+    subscribe(callback: () => void): () => void;
+    sendEvent<K extends keyof AppEvents>(event: K, ...args: AppEvents[K] extends undefined ? [] : [payload: AppEvents[K]]): void;
+}
+/** Outcome of a correlated submit: accepted, or rejected with a message. */
+export type OperationResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export interface SettleOptions {
+    /** Reject with an `Error` if the operation has not settled in time. */
+    timeoutMs?: number;
+}
+/**
+ * Rejection every in-flight `settled()` promise receives when the client is
+ * destroyed, so teardown is the layer's bound of last resort even without a
+ * `timeoutMs`. The class identity does not survive the npm/CDN module split,
+ * so detect it by `error.name === "BridgeClientDestroyedError"` (or via
+ * {@link BridgeClientDestroyedError.is}), never by `instanceof` alone.
+ */
+export declare class BridgeClientDestroyedError extends Error {
+    constructor(message?: string);
+    static is(error: unknown): error is BridgeClientDestroyedError;
+}
+export interface SendHandle {
+    /**
+     * The uuid put on the wire as `tempMessageUuid`. Core seeds the optimistic
+     * message's `clientKey` from it, so the sent message is findable in
+     * `chat.messages` by `clientKey === tempMessageUuid`.
+     */
+    readonly tempMessageUuid: string;
+    /**
+     * Resolves with the message once it appears in `chat.messages` (the
+     * optimistic row; the durable server echo keeps the same `clientKey`).
+     * Rejects when core reports THIS send's error before the row appears —
+     * rate limit, over-length, session not ready, dispatch failure —
+     * correlated exactly on `chat.error.clientKey` matching the minted
+     * `tempMessageUuid`, so an unrelated failure in the same window never
+     * falsely rejects a delivered send. On a core document that predates
+     * `chat.error.clientKey`, falls back to the positional
+     * `chat.error.seq`-advance detection, and before that to `chat.error`
+     * text transitions. A secret send NEVER resolves — core deliberately
+     * writes no transcript row for it — so pass `timeoutMs` or skip
+     * `settled()` for secret sends. Destroying the client rejects every
+     * pending `settled()` with a {@link BridgeClientDestroyedError}.
+     */
+    settled(opts?: SettleOptions): Promise<Message>;
+}
+export interface CaptureHandle {
+    /**
+     * Resolves on the verdict for THIS capture submit: `{ ok: true }` when the
+     * value was accepted (core removes the capture block), or
+     * `{ ok: false, message }` when it was rejected — a server validation
+     * rejection (observed on the `isSubmitting` falling edge, with the
+     * validation error text), or a failure/drop core stamps on the capture's
+     * `lastSubmitFailure` keyed to this submit's own minted `submitId` (no
+     * session to round-trip, value over the length cap, transport failure, a
+     * duplicate submit while one is in flight, a host-driven reset). The
+     * correlation is exact: the handle never reads the global `chat.error`,
+     * so an unrelated failure in the same window can never masquerade as this
+     * capture's verdict. On a core document that predates `lastSubmitFailure`,
+     * those failures are not capture-attributable at all and the handle stays
+     * pending — pass `timeoutMs` when targeting older cores.
+     */
+    settled(opts?: SettleOptions): Promise<OperationResult>;
+}
+export interface CsatSubmitHandle {
+    /**
+     * Resolves when core reports this survey's outcome, correlated on the
+     * success seq advance x surveyType x conversationId triple (and the
+     * mirror-image error triple). A `partial` submit reports no terminal
+     * outcome, so `settled()` on one only settles via `timeoutMs`.
+     */
+    settled(opts?: SettleOptions): Promise<OperationResult>;
+}
+export interface FileUploadHandle {
+    /** The minted upload id sent with `file.upload.start`. */
+    readonly uploadId: string;
+    /**
+     * Re-send the EXACT same `{ file, uploadId }` pair. Core correlates the
+     * retry to the failed attempt by that pair, so a fresh pair would orphan
+     * the original error state.
+     */
+    retry(): void;
+    /** Dismiss a reported upload error (`file.uploadError`). */
+    dismissError(): void;
+}
+export interface EndChatEligibilityResult {
+    /** `csat.endChatEligible` at the moment the answer arrived. */
+    eligible: boolean | null;
+    /** Which survey End Chat should present, when eligible. */
+    surveyTarget: "bot" | "agent" | null;
+}
+export interface ObserveOptions<T> {
+    /** Change detector; defaults to `Object.is`. */
+    equals?: (a: T, b: T) => boolean;
+    /** Also invoke the callback immediately with the current value. */
+    emitInitial?: boolean;
+}
+/**
+ * Typed helpers over the bridge event/state contract. Obtain via
+ * `client.operations`. Fire-and-forget helpers return `void`; correlated
+ * helpers return a handle or Promise that settles from state transitions
+ * (there is no request/response channel — core answers through state).
+ */
+export interface BridgeOperations {
+    /**
+     * Send a chat message. The body is trimmed; an empty result sends nothing
+     * (the returned handle then rejects). `secret: true` sends a masked
+     * message: the raw body never enters the transcript and the handle never
+     * resolves. While `ui.secretMessage.isOpen` is true you likely want
+     * `secret: true` to match the composer's mode.
+     */
+    sendMessage(body: string, opts?: {
+        secret?: boolean;
+    }): SendHandle;
+    /** Retry a failed send by message id (see {@link canRetryMessage}). */
+    retryMessage(messageId: string): void;
+    /**
+     * Whether the retry affordance should show for a message: a `text`
+     * message core marked `isRetryable`, no disconnected Zendesk SDK, and the
+     * message belongs to the current conversation (or predates stamping).
+     */
+    canRetryMessage(message: Message): boolean;
+    /** Answer a quick-reply chip. Pass the chip and its message id verbatim. */
+    selectQuickReply(reply: QuickReply, messageId: string): void;
+    /** Answer an options block. The label falls back to the option id. */
+    selectOption(option: OptionItem, messageId: string): void;
+    /**
+     * Submit the active selectable list (`conversation.stateData.listSelection`
+     * supplies the `dataId`). No-op when no list selection is active.
+     */
+    submitListSelection(selectedIds: string[]): void;
+    /**
+     * Cancel the active selectable list. Uses the block's own cancel response
+     * and label (`label` overrides the visible label). No-op when no list
+     * selection is active or it has no cancel response.
+     */
+    cancelListSelection(label?: string): void;
+    /**
+     * Submit the active capture field (`conversation.stateData.capture`
+     * supplies the `dataId`). Each call mints its own `submitId`, so the
+     * handle settles only on ITS OWN submit's verdict or failure — a second
+     * submit sent while one is in flight is dropped by core and its handle
+     * resolves `{ ok: false }` on its own terms rather than inheriting the
+     * in-flight submit's verdict.
+     */
+    submitCapture(value: string): CaptureHandle;
+    /**
+     * Cancel the active capture field. `label` overrides the block's own
+     * cancel label. No-op when no capture is active or it has no cancel
+     * response.
+     */
+    cancelCapture(label?: string): void;
+    /** React to a bot message with a thumbs vote. */
+    addReaction(messageId: string, reaction: 1 | -1): void;
+    /**
+     * Report that the user activated a `link` message. Core resolves the
+     * stored message for tracking and, with `navigateInHost`, validated
+     * same-tab host navigation.
+     */
+    reportLinkClick(messageId: string, opts?: {
+        navigateInHost?: boolean;
+    }): void;
+    /**
+     * Advance the persisted read watermark. Reports are debounced 400 ms, the
+     * watermark is a monotonic lexical max over `_id` cursor strings (calling
+     * with an older cursor never lowers it), and the accumulator resets when
+     * `chat.conversationId` changes so a pending cursor from conversation A
+     * can never commit against B. Call with `message.cursor` for each message
+     * that scrolls into view; messages stamped with a DIFFERENT
+     * `conversationId` must be excluded by the caller (the transcript
+     * preserves the previous conversation's rows).
+     */
+    markRead(cursor: string, opts?: {
+        conversationId?: string;
+    }): void;
+    /**
+     * Request an older page of history. No-op unless `chat.canLoadMore` is
+     * true and no load is already in flight.
+     */
+    loadOlderMessages(): void;
+    /**
+     * Invoke `callback` each time restored/baseline history (re)loads
+     * (`chat.recentMessagesLoadSeq` advances) — the one-shot trigger for
+     * "scroll to the bottom of restored history" and for seeding an unread
+     * divider. Returns an unsubscribe function.
+     */
+    onHistoryLoaded(callback: (seq: number) => void): () => void;
+    /**
+     * Submit a CSAT survey. Pass `conversationId: message.conversationId` for
+     * a survey rendered IN the transcript (the row can outlive its
+     * conversation); omit it — or pass `null`, which is treated as omitted on
+     * the wire and in correlation — for End Chat / proactive flows, where
+     * core resolves the conversation itself.
+     */
+    submitCsat(data: CsatSubmitData, opts: {
+        surveyType: string;
+        partial?: boolean;
+        conversationId?: string | null;
+    }): CsatSubmitHandle;
+    /** Analytics: report that a survey was displayed. Fire-and-forget. */
+    trackCsatShown(surveyType: string, conversationId?: string | null): void;
+    /**
+     * Ask core whether End Chat should present a survey. Correlated by
+     * latching `csat.endChatEligibility.seq` and resolving when it advances
+     * (there is no request id; a `ready -> ready` re-check changes no other
+     * observable state).
+     */
+    checkEndChatEligibility(opts?: SettleOptions): Promise<EndChatEligibilityResult>;
+    /** End the chat without presenting a survey. */
+    skipCsatAndEndChat(): void;
+    /**
+     * Start a new conversation. Applies a local cooldown (default 5 s) that
+     * swallows rapid re-clicks; returns `false` while cooling down.
+     */
+    startNewConversation(opts?: {
+        cooldownMs?: number;
+    }): boolean;
+    /** Reset the app frame's conversation state. */
+    resetApp(): void;
+    /**
+     * Report a content-free composer-changed edge (drives live-agent typing
+     * indicators). The event is payload-free by contract — composer text must
+     * never cross the frame boundary — and this helper suppresses it entirely
+     * in secret mode (pass `secret: true`, or leave it to the
+     * `ui.secretMessage.isOpen` state check): even a content-free typing edge
+     * is a signal about the secret being typed.
+     */
+    notifyComposerChanged(opts?: {
+        secret?: boolean;
+    }): void;
+    /** Open or close the masked (secret) composer mode. */
+    toggleSecretMessage(open: boolean): void;
+    /**
+     * Start a live-agent file upload. Mints and retains the `{ file,
+     * uploadId }` pair so `retry()` replays exactly it. Progress and errors
+     * land on `file.isUploading`, `file.transfer`, and `file.uploadError`
+     * (core can report an error without ever setting `isUploading`).
+     */
+    startFileUpload(file: File): FileUploadHandle;
+    /** Change the conversation language (BCP 47 tag the bot offers). */
+    setLanguage(language: string): void;
+    /**
+     * Email the transcript. Resolves/rejects when `transcript.email.status`
+     * reaches `success | error` with its `.seq` advanced past this call's
+     * baseline — a request core drops without ever broadcasting `pending`
+     * (a host-driven reset in progress) still rejects. On a core document
+     * that predates the seq, falls back to the `pending -> terminal` edge.
+     * The email is trimmed; an empty result rejects immediately without
+     * sending (core drops an empty email silently, so nothing would ever
+     * settle it).
+     */
+    emailTranscript(email: string, opts?: SettleOptions): Promise<void>;
+    /**
+     * Download the transcript. Same settle contract as
+     * {@link BridgeOperations.emailTranscript}, on
+     * `transcript.download.status`.
+     */
+    downloadTranscript(opts?: SettleOptions): Promise<void>;
+    /** Toggle the new-message alert sound. */
+    setAlertSound(enabled: boolean): void;
+    /**
+     * Ask the HOST page to request Web Notification permission (permission is
+     * per-origin, so the widget frame's own value is not the governing one).
+     * Result lands on `chatter.notificationPermission`.
+     */
+    requestNotificationPermission(): void;
+    /** Set the user's in-widget theme override. */
+    setTheme(theme: "light" | "dark" | "auto"): void;
+    /** Set the user's in-widget text-size override. */
+    setTextSize(size: "small" | "default" | "large"): void;
+    /** The header close affordance (ends the chat when `endChat.canEnd`). */
+    close(): void;
+    /** Minimize the widget. */
+    minimize(): void;
+    /** Dismiss the visible toast. */
+    dismissToast(): void;
+    /**
+     * Clear `chat.error` in core. Clear core state rather than hiding the
+     * error locally, or the session's second error renders nothing.
+     */
+    dismissError(): void;
+    /** Ask the SDK host to expand or restore the app's viewport surface. */
+    setHostViewportExpanded(expanded: boolean): void;
+    /** Retry after a response outage banner. */
+    retryAfterOutage(): void;
+    /**
+     * Report a fatal app error to core (renders the fallback UI and reports
+     * telemetry). Callable from anywhere with a client reference — including
+     * a class error boundary outside any React provider.
+     */
+    reportAppError(error: unknown, componentStack?: string): void;
+}
+interface StateObservation {
+    subscribeKey<K extends keyof AppDisplayState>(key: K, callback: (value: AppDisplayState[K] | undefined, previous: AppDisplayState[K] | undefined) => void, opts?: ObserveOptions<AppDisplayState[K] | undefined>): () => void;
+    select<T>(selector: (state: AppDisplayState | null) => T, callback: (value: T, previous: T | undefined) => void, opts?: ObserveOptions<T>): () => void;
+}
+/**
+ * Build the `subscribeKey`/`select` observation primitives over a host.
+ * `Object.is` is a sound default equality for `subscribeKey`: state crosses
+ * the frame boundary by structured clone, so the real client restores each
+ * structurally unchanged key's previous reference before notifying (the test
+ * mock shares references in memory to begin with). For `select`, whose
+ * selector typically MINTS a new object per call, pass a custom `equals`
+ * (or select a primitive/signature string) when projecting objects.
+ */
+export declare function createStateObservation(host: BridgeOperationsHost): StateObservation;
+export interface BridgeOperationsBundle {
+    operations: BridgeOperations;
+    /** Release the layer's own subscriptions and timers (client teardown). */
+    dispose(): void;
+}
+export declare function createBridgeOperations(rawHost: BridgeOperationsHost): BridgeOperationsBundle;
+export {};

package/dist/shared-utils/csat-settings.d.ts

@@ -0,0 +1,61 @@
+export interface CsatFeedbackOption {
+	id: string;
+	label: string;
+}
+export interface CsatSurveySettings {
+	satisfactionIsEnabled: boolean;
+	satisfactionLabel: string;
+	satisfactionRange: number;
+	satisfactionStyle: string;
+	followUpFeedbackIsEnabled: boolean;
+	followUpFeedbackPositiveLabel: string;
+	followUpFeedbackNegativeLabel: string;
+	followUpFeedbackPositiveOptions: CsatFeedbackOption[];
+	followUpFeedbackNegativeOptions: CsatFeedbackOption[];
+	resolutionIsEnabled: boolean;
+	resolutionLabel: string;
+	openFeedbackIsEnabled: boolean;
+	openFeedbackLabel: string;
+	openFeedbackHint?: string;
+	customerEffortScoreIsEnabled: boolean;
+	customerEffortScoreRange: number;
+	customerEffortScoreLabel?: string;
+	netPromoterScoreIsEnabled: boolean;
+	netPromoterScoreLabel?: string;
+	order: string[];
+	required?: string[];
+	respondToNegativeFeedback?: boolean;
+	respondToPositiveFeedback?: boolean;
+	anytimeSurveyIsEnabled?: boolean;
+	postChatSurveyIsEnabled?: boolean;
+}
+export declare const DEFAULT_CSAT_ORDER: string[];
+export type TranslationMap = Record<string, string>;
+export interface StoredCsatFeedbackOption extends CsatFeedbackOption {
+	translations?: TranslationMap;
+}
+export interface CsatLabelTranslations {
+	satisfactionLabel?: TranslationMap;
+	followUpFeedbackPositiveLabel?: TranslationMap;
+	followUpFeedbackNegativeLabel?: TranslationMap;
+	resolutionLabel?: TranslationMap;
+	openFeedbackLabel?: TranslationMap;
+	openFeedbackHint?: TranslationMap;
+	customerEffortScoreLabel?: TranslationMap;
+	netPromoterScoreLabel?: TranslationMap;
+}
+export interface StoredCsatSurveySettings extends CsatSurveySettings {
+	followUpFeedbackPositiveOptions: StoredCsatFeedbackOption[];
+	followUpFeedbackNegativeOptions: StoredCsatFeedbackOption[];
+	labelTranslations?: CsatLabelTranslations;
+}
+/** Preserve API translation maps so already-fetched surveys follow language changes. */
+export declare function parseCsatSettings(
+	data: unknown,
+	language?: string,
+): StoredCsatSurveySettings | null;
+/** Strip internal maps while resolving the public app contract for this render. */
+export declare function localizeCsatSettings(
+	settings: StoredCsatSurveySettings | null,
+	language: string,
+): CsatSurveySettings | null;

package/dist/shared-utils/file-upload.d.ts

@@ -0,0 +1,36 @@
+export type FileUploadErrorReason =
+	| "delivery_unknown"
+	| "durability_failed"
+	| "durability_unknown"
+	| "handoff_ended"
+	| "http_400"
+	| "http_413"
+	| "http_415"
+	| "http_error"
+	| "integration_error"
+	| "integration_frame_error"
+	| "integration_frame_load_error"
+	| "integration_result_timeout"
+	| "invalid_context"
+	| "invalid_response"
+	| "message_send_failed"
+	| "missing_platform"
+	| "missing_transfer_data"
+	| "network_error"
+	| "provider_rejected"
+	| "timeout"
+	| "unsupported_platform"
+	| "upload_not_enabled";
+/** Typed bridge contract for file-upload failures shown to the chatter. */
+export interface FileUploadErrorData {
+	reason?: FileUploadErrorReason;
+	deliveryConfirmed?: boolean;
+	indeterminate?: boolean;
+	/** Core owns whether replaying the retained operation is safe and meaningful. */
+	retryable?: boolean;
+	maxFileSizeInMB?: number;
+	status?: number | string;
+	integrationErrorCode?: string;
+	platform?: string;
+	details?: Record<string, unknown>;
+}

package/dist/shared-utils/index.d.ts

@@ -0,0 +1,2 @@
+export type * from "./csat-settings.js";
+export type * from "./file-upload.js";

package/dist/state-keys.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Typed constants for all bridge state keys.
+ *
+ * Using these constants prevents silent typos — a misspelled string literal
+ * compiles without error but returns `undefined` at runtime.
+ *
+ * This is a catalogue for consumers of the package, not a list of keys this
+ * repo happens to use: most entries have no in-repo reader, and a new one
+ * having none is expected rather than dead code.
+ *
+ * The `satisfies` clause is what makes that true. This map is a third
+ * hand-maintained mirror of the state contract, and an unused constant never
+ * typechecks on its own — without the clause a value that no longer names a
+ * real `AppDisplayState` key would compile clean and only fail at the first
+ * read. It also keeps the literal types, so `StateKey` stays a union of the
+ * exact strings rather than widening to `string`.
+ *
+ * @example
+ * import { STATE } from "@ada-cx/messaging-bridge";
+ * const botName = state?.[STATE.CONFIG_BOT_NAME] ?? "Ada";
+ */
+export declare const STATE: {
+    readonly AGENT_ACTIVE_AGENT: "agent.activeAgent";
+    readonly APP_LOADING: "app.loading";
+    readonly CHAT_CAN_LOAD_MORE: "chat.canLoadMore";
+    readonly CHAT_ERROR: "chat.error";
+    readonly CHAT_ERROR_SEQ: "chat.error.seq";
+    readonly CHAT_ERROR_CLIENT_KEY: "chat.error.clientKey";
+    readonly CHAT_IS_GENERATING: "chat.isGenerating";
+    readonly CHAT_IS_UNIFIED_REASONER_GENERATING: "chat.isUnifiedReasonerGenerating";
+    readonly CHAT_IS_SENDING: "chat.isSending";
+    readonly CHAT_MESSAGES: "chat.messages";
+    readonly CHAT_COMPOSER_TEXT: "chat.composerText";
+    readonly CHAT_ANSWERED_INTERACTIVE_IDS: "chat.answeredInteractiveIds";
+    readonly CHAT_PLAYBOOK_STEP_EXECUTING: "chat.playbookStepExecuting";
+    readonly CHATTER_ALERT_SOUND_ENABLED: "chatter.alertSoundEnabled";
+    readonly CHATTER_DEVICE_NOTIFICATIONS_ENABLED: "chatter.deviceNotificationsEnabled";
+    readonly CHATTER_LANGUAGE: "chatter.language";
+    readonly CHATTER_SMS_NOTIFICATIONS_ENABLED: "chatter.smsNotificationsEnabled";
+    readonly CHATTER_TRANSLATIONS: "chatter.translations";
+    readonly CONFIG_ADVANCED_COLORS_ENABLED: "config.advancedColorsEnabled";
+    readonly CONFIG_ALLOWED_PROTOCOLS: "config.allowedProtocols";
+    readonly CONFIG_BOT_AVATAR_URL: "config.botAvatarUrl";
+    readonly CONFIG_BOT_DESCRIPTION: "config.botDescription";
+    readonly CONFIG_BOT_DESCRIPTION_ENABLED: "config.botDescriptionEnabled";
+    readonly CONFIG_BOT_NAME: "config.botName";
+    readonly CONFIG_BUTTON_LAYOUT_DESKTOP: "config.buttonLayoutDesktop";
+    readonly CONFIG_BUTTON_LAYOUT_MOBILE: "config.buttonLayoutMobile";
+    readonly CONFIG_CHAT_ENABLED: "config.chatEnabled";
+    readonly CONFIG_CUSTOM_REDACTIONS: "config.customRedactions";
+    readonly CONFIG_DOWNLOAD_TRANSCRIPT_ENABLED: "config.downloadTranscriptEnabled";
+    readonly CONFIG_EMAIL_TRANSCRIPT_ENABLED: "config.emailTranscriptEnabled";
+    readonly CONFIG_FALLBACK_UI: "config.fallbackUi";
+    readonly CONFIG_FEATURES: "config.features";
+    readonly CONFIG_HANDLE: "config.handle";
+    readonly CONFIG_HEADER_COLOR: "config.headerColor";
+    readonly CONFIG_HEADER_COLOR_ENABLED: "config.headerColorEnabled";
+    readonly CONFIG_HEADER_TEXT_COLOR: "config.headerTextColor";
+    readonly CONFIG_IS_MOBILE_VIEWPORT: "config.isMobileViewport";
+    readonly CONFIG_PRIVACY_LINK: "config.privacyLink";
+    readonly CONFIG_PRIVACY: "config.privacy";
+    readonly CONFIG_SDK_PLATFORM: "config.sdkPlatform";
+    readonly CONFIG_SDK_SUPPORTS_DOWNLOAD_LINK: "config.sdkSupportsDownloadLink";
+    readonly CONFIG_SHOW_ALL_QUICK_REPLIES: "config.showAllQuickReplies";
+    readonly CONFIG_SHOW_BRANDING: "config.showBranding";
+    readonly CONFIG_ADA_PARTNER_NAME: "config.adaPartnerName";
+    readonly CONFIG_STYLE: "config.style";
+    readonly CONFIG_TEXT_OVER_ACCENT_COLOR: "config.textOverAccentColor";
+    readonly CONFIG_TEXT_SIZE: "config.textSize";
+    readonly CONFIG_THEME: "config.theme";
+    readonly CONFIG_TINT_COLOR: "config.tintColor";
+    readonly CONFIG_TRANSLATED_LANGUAGES: "config.translatedLanguages";
+    readonly CONFIG_CLIENT_DEFAULT_LANGUAGE: "config.clientDefaultLanguage";
+    readonly CONVERSATION_IN_STATE: "conversation.inState";
+    readonly CONVERSATION_STATE_DATA_CAPTURE: "conversation.stateData.capture";
+    readonly CONVERSATION_STATE_DATA_LIST_SELECTION: "conversation.stateData.listSelection";
+    readonly CSAT_AUTO_TRIGGER: "csat.autoTrigger";
+    readonly FILE_TRANSFER: "file.transfer";
+    readonly FILE_UPLOAD_ERROR: "file.uploadError";
+    readonly LIVE_AGENT_IN_LIVE_CHAT: "liveAgent.inLiveChat";
+    readonly TRANSCRIPT_DOWNLOAD_STATUS: "transcript.download.status";
+    readonly TRANSCRIPT_EMAIL_STATUS: "transcript.email.status";
+    readonly UI_FATAL_HANDOFF_DIALOG_CANCEL_FAILED: "ui.fatalHandoffDialog.cancelFailed";
+    readonly UI_FATAL_HANDOFF_DIALOG_PENDING: "ui.fatalHandoffDialog.pending";
+    readonly UI_RETRY_DIALOG_PENDING: "ui.retryDialog.pending";
+    readonly UI_SECRET_MESSAGE_BUTTON_ENABLED: "ui.secretMessage.buttonEnabled";
+    readonly UI_SECRET_MESSAGE_IS_OPEN: "ui.secretMessage.isOpen";
+    readonly UI_SHOW_RETRY_DIALOG: "ui.showRetryDialog";
+    readonly UI_TYPING_INDICATOR_VISIBLE: "ui.typingIndicator.visible";
+    readonly SECURITY_CHALLENGE_ENABLED: "security.challengeEnabled";
+    readonly SECURITY_CHALLENGE_ERROR: "security.challengeError";
+    readonly SECURITY_TURNSTILE_SITE_KEY: "security.turnstileSiteKey";
+    readonly SAML_LOCKED: "saml.locked";
+    readonly SAML_URL: "saml.url";
+    readonly SAML_LOGIN_BUTTON: "saml.loginButton";
+    readonly VOICE_AUDIO_LEVEL: "voice.audioLevel";
+    readonly VOICE_CURRENT_TRANSCRIPT: "voice.currentTranscript";
+    readonly VOICE_ENABLED: "voice.enabled";
+    readonly VOICE_ERROR: "voice.error";
+    readonly VOICE_IS_FINAL: "voice.isFinal";
+    readonly VOICE_IS_RECORDING: "voice.isRecording";
+    readonly VOICE_MODE: "voice.mode";
+    readonly VOICE_TTS_ENABLED: "voice.ttsEnabled";
+};
+export type StateKey = (typeof STATE)[keyof typeof STATE];

package/dist/testing.d.ts

@@ -0,0 +1,53 @@
+import type { BridgeClient } from "./bridge-client.js";
+import type { AppDisplayState, AppEvents } from "./types.js";
+/** One recorded `sendEvent` call. */
+export interface SentBridgeEvent<K extends keyof AppEvents = keyof AppEvents> {
+    event: K;
+    payload: AppEvents[K] | undefined;
+}
+/**
+ * A scriptable, in-memory {@link BridgeClient} for unit tests.
+ *
+ * No postMessage, no origin checks, no network: tests drive state through
+ * `setState`/`updateState` and assert on the events the component under test
+ * sent through `sentEvents`. The `operations`, `subscribeKey`, and `select`
+ * surfaces are the REAL implementations running over this in-memory state:
+ * every operation records its events in `sentEvents`, and a correlated
+ * handle (`sendMessage().settled()`, `submitCsat().settled()`, ...) resolves
+ * when the test scripts the answering state transition via `updateState`.
+ */
+export interface MockBridgeClient extends BridgeClient {
+    /** Replace the state snapshot and notify subscribers. */
+    setState(state: AppDisplayState | null): void;
+    /**
+     * Shallow-merge a partial snapshot over the current state (or over an empty
+     * object when no state is set) and notify subscribers. Seeds
+     * `"chat.error.clientKey": null` when the key is absent — production core
+     * always publishes it (null when no keyed send owns the error), and
+     * `operations` send handles take the keyed correlation path only when it is
+     * present. Script a `chat.error` fixture with the send's `tempMessageUuid`
+     * as `chat.error.clientKey` to reject that handle; use `setState` to script
+     * an older core document without the key.
+     */
+    updateState(partial: Partial<AppDisplayState>): void;
+    /**
+     * Every event sent through the client, in order. Each read returns a fresh
+     * copy, so a captured array survives `clearSentEvents()`.
+     */
+    readonly sentEvents: readonly SentBridgeEvent[];
+    /** Forget recorded events without touching state or subscribers. */
+    clearSentEvents(): void;
+    /** Number of active subscribers. */
+    readonly subscriberCount: number;
+    /** True once `destroy()` has been called. */
+    readonly destroyed: boolean;
+}
+/**
+ * Create a {@link MockBridgeClient}, optionally seeded with an initial state
+ * snapshot. Mirrors the real client's teardown semantics: after `destroy()`,
+ * state is `null`, subscribers are cleared, `sendEvent` is a no-op, and every
+ * in-flight `operations` `settled()` promise rejects with a
+ * `BridgeClientDestroyedError`. Notification also mirrors the real client:
+ * a throwing subscriber is caught and logged, never aborting the pass.
+ */
+export declare function createMockBridgeClient(initialState?: AppDisplayState | null): MockBridgeClient;