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

package/dist/client/client.d.ts

@@ -0,0 +1,843 @@
+import type { AdaMessagingClientConfig, AdaMessagingStartOptions, AdaSdkEventCallback, ConversationInfo, Delegate, MetaFieldValue, PublicMessage, ResetParams, SendMessageResult, WindowInfo } from "./client-types.js";
+/**
+ * Ada Messaging Client — thin coordinator
+ *
+ * This class is intentionally a coordinator, not a monolith. It owns the
+ * top-level lifecycle (init, open, close, destroy) and delegates all
+ * domain-specific logic to purpose-built modules:
+ *
+ *   - FrameManager              — iframe registry, channels, and load timers
+ *   - SdkEventBus               — pub/sub subscriber registry and getInfo() promise tracking
+ *   - client-channel-handlers.ts — per-frame postMessage handler wiring
+ *   - client-host-runtime.ts    — config delivery, location-history patching, event routing
+ *   - proactive/               — intro popup scheduling, URL-trigger evaluation, channel handlers
+ *   - config-helpers.ts         — pure config parsing and validation functions
+ *   - frame-styles.ts           — CSS string generators for each frame
+ *   - integration-manager.ts    — integration iframe lifecycle and command bus
+ *   - voice/voice-manager.ts    — WebSpeech recording and TTS
+ *
+ * Keep this class as a coordinator: new feature logic belongs in one of the
+ * modules above, not in additional private methods here.
+ *
+ * Frame hierarchy (hybrid model):
+ *   Host Page
+ *   ├── button.html      (chat trigger)
+ *   ├── intro.html       (proactive messages)
+ *   └── core.html        (headless business logic → mounts app iframe;
+ *                          persists session/auth via the bot-domain
+ *                          /api/messaging/storage frame it mounts internally)
+ */
+declare class AdaMessagingClient {
+    private _config;
+    private _assetRolloutCluster;
+    private _frameManager;
+    private readonly MAX_PENDING_MESSAGES;
+    private _pendingCoreMessages;
+    private _eventBus;
+    private _isInitialized;
+    private _integrationManager;
+    private _voiceManager;
+    private _startupConfig;
+    /** Latest host trigger waiting for the first startup config. */
+    private _pendingHostProactive;
+    private _lastOpenedViaKeyboard;
+    private _introTimer;
+    private readonly _proactiveTimers;
+    private _programmaticProactiveTimer;
+    private _activeProactiveSurfaceId;
+    private _proactiveClearRequestSeq;
+    private _pendingProactiveClearRequestId;
+    /** Latest intro display waiting for the intro frame channel. */
+    private _pendingIntroDisplay;
+    /** The channel exists at iframe load, before the intro runtime can receive. */
+    private _introChannelReady;
+    private _introChannelSetupStarted;
+    private _introChannelFailed;
+    private _introChannelUnlockAttempts;
+    private _introChannelHandshakeTimer;
+    private _introChannelDisplayTimer;
+    /** Latest emoji greeting waiting for the launcher channel. */
+    private _pendingEmojiDisplay;
+    /** Monotonic ordering for SDK-owned proactive intents. */
+    private _proactiveIntentSeq;
+    private _currentProactiveIntentId;
+    private _introShowing;
+    /** Page-local greeting dedupe; legacy resets this on a full-page reload. */
+    private _hasIntroShown;
+    /** Sticky client-lifetime parity with Embed2's card-greeting `wasIntroShown`. */
+    private _wasIntroShown;
+    /** Effective value for the current chatter; proactive removal sets only this bit. */
+    private _introShown;
+    private _runtimeMetaSyncScheduled;
+    private _runtimeMetaGeneration;
+    private _locationHistoryState;
+    private _lastEvaluatedUrl;
+    private _cachedEndpoint;
+    private _unreadCount;
+    /**
+     * Server-reported unread count for the current chatter, held apart from
+     * `_unreadCount` so a live message never renders as `seed + 1`.
+     */
+    private _seededUnread;
+    private _seededUnreadToken;
+    private _chatterToken;
+    /** Exact accepted chatter whose credentials live in tab-scoped identity storage. */
+    private _identitySessionChatterToken;
+    /** Consumption is emitted immediately before the matching chatter announcement. */
+    private _identityTokenConsumedAwaitingChatter;
+    /** One post-reset announcement from the just-abandoned identity lifecycle. */
+    private _ignoredChatterAnnouncementToken;
+    /** A storage credential that has not yet been restored into runtime state. */
+    private _persistedChatterCandidate;
+    /** Candidate discovery is SDK-triggered only after final startup config is known. */
+    private _coreReadyForCandidateDiscovery;
+    private _candidateDiscoveryBlockedForCore;
+    private _candidateDiscoveryRequestedForCore;
+    private _candidateDiscoveryGeneration;
+    private _scheduledCandidateDiscoveryGeneration;
+    private _candidateDiscoveryRequestSeq;
+    private _pendingCandidateDiscoveryRequestId;
+    private _candidateGeneration;
+    private _notificationStatusAbortController;
+    private _notificationStatusTimeout;
+    private _notificationStatusRequestSeq;
+    private _notificationStatusRequest;
+    private _notificationStatusCache;
+    private _sessionResumeRequestSeq;
+    private _pendingSessionResume;
+    private _pendingSessionResumeVisibility;
+    /** Resume succeeded, but only core.chatter.created may promote this token. */
+    private _resumedChatterAwaitingAnnouncement;
+    /** A prior tab's open marker is only actionable after live restore succeeds. */
+    private _pendingCrossWindowDrawerRestore;
+    /** Host-provided push token, retained independently of chatter-sensitive metadata. */
+    private _deviceToken;
+    /**
+     * Chatter whose unread count the user has already acknowledged by opening the
+     * chat. An in-flight seed carries a pre-clear count, so it has to lose to this
+     * rather than to chat visibility — the chat may already be closed again by the
+     * time the response lands.
+     */
+    private _acknowledgedUnreadToken;
+    /** An acknowledgement that landed before the chatter token existed to send it. */
+    private _pendingUnreadAcknowledgement;
+    private _isChatOpen;
+    /** Legacy keeps the chat frame mounted after its first open, replacing pre-chat surfaces. */
+    private _hasChatOpened;
+    /** Explicit host/user engagement, distinct from a hidden background resume. */
+    private _hasExplicitlyEngaged;
+    /** Resolved HTMLElement when parentElement config is active, null otherwise */
+    private _parentElement;
+    /** Whether init has made the configured host-layout mode authoritative. */
+    private _parentElementResolved;
+    private _maskElement;
+    private _hasActiveChatter;
+    private _hasPublishedEmbedLoaded;
+    private readonly _registeredInternalEventCallbacks;
+    private _crossWindowLiveChatActive;
+    private _cleanupErrorReporter;
+    private _cleanupCoreChannelHandlers;
+    private _cleanupServiceWorkerNotificationClick;
+    private _chatActivationEventTimer;
+    private _chatFallbackTimer;
+    /** First visible arm of the current activation's absolute fallback ceiling. */
+    private _chatFallbackArmedAt;
+    private _coreFrameReloadTimer;
+    private _chatHideTimer;
+    private _chatViewportCleanup;
+    private _pageScrollLocked;
+    /** App-requested host viewport lease, honored only by floating browser widgets. */
+    private _hostViewportRequested;
+    private _hasCompletedActivation;
+    /** Core has begun or advanced session activation, possibly while hidden. */
+    private _activationWorkObserved;
+    private _showingTimeoutFallback;
+    private readonly _handleFallbackMessage;
+    /**
+     * Durable clear intent replayed to every replacement Core until the exact
+     * correlated acknowledgement arrives. Config delivery is not completion: Core
+     * can crash after receiving these fields but before confirming the write barrier.
+     */
+    private _clearPersistenceOnNextCoreConfig;
+    /**
+     * A soft reset made from the timeout document. Its replacement core must first
+     * restore the existing chatter, then sync the supplied fields and reactivate.
+     */
+    private _historyPreservingResetAfterCoreReload;
+    private _pendingClearAckRequestId;
+    private _pendingClearAckResponseType;
+    private _pendingClearPersistenceScope;
+    private _resolvedPersistenceMode;
+    /** The current Core document has installed its router and completed public bootstrap. */
+    private _coreReadyForResetDelivery;
+    private _pendingClearPersistenceModes;
+    private _pendingDestructiveOps;
+    private _greetingResponseIdOnNextCoreConfig;
+    private _configuredGreetingResponseId;
+    private _campaignShowSeq;
+    private _shownCampaign;
+    private _openedCampaignSeq;
+    private _introSurfaceSeq;
+    private _currentIntroSurface;
+    private _internalHostTelemetry?;
+    private _onIdentityTokenConsumed?;
+    private _isEmbedLoadedPublicationActive?;
+    private _zdChatterAuthCallback;
+    private _delegate;
+    private _urlBusinessEvents;
+    private _urlBusinessEventsEnabled;
+    private _urlBusinessEventsLoaded;
+    private _urlBusinessEventsFailureReported;
+    private _urlBusinessEventsEndpoint;
+    private _urlBusinessEventsLoad;
+    private _urlBusinessEventsRefreshPending;
+    private _urlBusinessEventsAbortController;
+    /** Expose zdChatterAuthCallback to channel handlers for Zendesk Chat auth flow */
+    get zdChatterAuthCallback(): ((callback: (token: string) => void) => void) | null;
+    /**
+     * Proxy getters so that callers inside this class (channel setup, proactive
+     * runtime dependencies, open/close) can continue to use `this._channels` and
+     * `this._frames` without modification. They resolve through the FrameManager
+     * when one exists, or return empty collections before init.
+     */
+    private get _channels();
+    private get _frames();
+    constructor(config: AdaMessagingClientConfig);
+    private _initializeClient;
+    /**
+     * Open the chat drawer UI.
+     * When the chat is already open this is a no-op.
+     * When {@link AdaMessagingClientConfig.lazy} is true and the client has not
+     * been initialized yet, calling open() triggers initialization.
+     *
+     * @example
+     * window.adaEmbed.open();
+     */
+    open(): void;
+    /** Open after a proactive click without clearing the engagement attribution
+     * that core and the SDK have just armed for that exact displayed surface. */
+    private _openFromProactiveEngagement;
+    private _openChat;
+    /**
+     * Close the chat drawer UI and restore the launcher button.
+     * When the chat is already closed this is a no-op.
+     *
+     * @example
+     * window.adaEmbed.close();
+     */
+    close(reason?: "close" | "minimize"): void;
+    /**
+     * Reset the active conversation and optionally apply new configuration.
+     * Use this when the authenticated user changes or to start a fresh session.
+     *
+     * The promise resolves on core's correlated confirmation. Full resets wait for
+     * the persisted conversation clear to be durable, including when core reloads;
+     * history-preserving resets wait for reconfiguration/reactivation and do not
+     * clear the chatter or transcript. For compatibility with existing
+     * fire-and-forget call sites, a core that never confirms settles this promise
+     * after a bounded wait instead of rejecting; that settlement is not a claim
+     * that core completed the operation.
+     *
+     * @param resetParams - Optional reset options (e.g., new metaFields or greeting).
+     *
+     * @example
+     * window.adaEmbed.reset({ metaFields: { userId: "new-user" } });
+     */
+    reset(resetParams?: ResetParams): Promise<void>;
+    private _registerDestructiveAck;
+    private _registerDurableClearAck;
+    private _acknowledgeDurableClearIntent;
+    private _clearDurableClearIntent;
+    private _abandonDurableClearIntent;
+    private _persistenceScopeKey;
+    private _outgoingPersistenceMode;
+    /**
+     * A reset/delete request belongs to the bot whose storage it snapshotted.
+     * Rebinding this SDK instance to another bot cannot truthfully finish that
+     * request and must never replay it into the new bot's storage.
+     */
+    private _abandonDestructiveWorkForPersistenceScopeChange;
+    private _hasNoFrameToAck;
+    private _hasReadyCoreChannel;
+    /**
+     * Mount only the public Core frame so a never-started lazy client can perform
+     * and acknowledge a durable persistence clear. Core's page-load phase mounts
+     * storage but never restores, identifies, creates, greets, or connects a
+     * chatter; a later start() reuses this pre-mounted frame via the same
+     * reuse path in _initializeFrames().
+     */
+    private _ensurePublicCoreFrameForDestructiveClear;
+    private _pruneDestructiveOp;
+    /**
+     * A later durable-clear acknowledgement confirms older clears it superseded:
+     * its required-mode coverage must subsume each older request. Soft
+     * reconfiguration payloads are not cumulative, so only their exact correlated
+     * acknowledgement may settle them.
+     */
+    private _settleDestructiveOpFamily;
+    /**
+     * Toggle the chat drawer — open if closed, close if open.
+     *
+     * @example
+     * window.adaEmbed.toggle();
+     */
+    toggle(): void;
+    /**
+     * Retrieve current client state asynchronously.
+     *
+     * @returns A promise that resolves to a {@link WindowInfo} object containing
+     *   `isChatOpen`, `hasActiveChatter`, and `hasClosedChat`.
+     *   The promise resolves immediately with local state values if the core
+     *   frame has not yet responded, or if the SDK is being destroyed.
+     *
+     * @example
+     * const info = await window.adaEmbed.getInfo();
+     * if (info.isChatOpen) { ... }
+     */
+    getInfo(): Promise<WindowInfo>;
+    /**
+     * Whether the chat is currently visible to the user. Derived from getInfo().
+     *
+     * @example
+     * if (await window.adaEmbed.isOpen()) { ... }
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Returns the non-sensitive metaFields currently set on the session.
+     * Sensitive metaFields are never returned. Resolves to an empty object if
+     * the core frame does not respond.
+     *
+     * @example
+     * const fields = await window.adaEmbed.getMetaFields();
+     */
+    getMetaFields(): Promise<Record<string, MetaFieldValue>>;
+    /**
+     * Returns the active conversation id and live-agent handoff state. Requires
+     * `enableProgrammaticControl`; rejects when the gate is off or core does not
+     * respond.
+     *
+     * @example
+     * const { id, handoff } = await window.adaEmbed.getConversation();
+     */
+    getConversation(): Promise<ConversationInfo>;
+    /**
+     * Returns the in-memory message transcript. Requires
+     * `enableProgrammaticControl`; rejects when the gate is off or core does not
+     * respond.
+     *
+     * @example
+     * const messages = await window.adaEmbed.getMessages();
+     */
+    getMessages(): Promise<PublicMessage[]>;
+    setComposerText(text: string): Promise<void>;
+    setDelegate(delegate: Delegate | null | undefined): void;
+    private _applyBeforeSend;
+    /**
+     * Delete chatter history and reset the session.
+     *
+     * Resolves after core confirms the persisted clear is durable, including
+     * across a replacement core frame. A missing confirmation uses the same
+     * bounded compatibility settlement as {@link reset}; it does not represent a
+     * false success acknowledgement from core.
+     */
+    deleteHistory(): Promise<void>;
+    /**
+     * Set the display language for the chat interface.
+     *
+     * @param language - A BCP-47 language tag (e.g. `"en"`, `"fr"`, `"es-MX"`).
+     *
+     * @example
+     * window.adaEmbed.setLanguage("fr");
+     */
+    setLanguage(language: string): void;
+    /**
+     * Change the chat widget's color scheme at runtime.
+     * Takes effect immediately without reset or reload.
+     *
+     * @param theme - `"light"`, `"dark"`, or `"auto"` (follows OS preference).
+     *
+     * @example
+     * window.adaEmbed.setTheme("dark");
+     */
+    setTheme(theme: "light" | "dark" | "auto"): void;
+    /**
+     * Update the active chatter's metafields.
+     * Values are validated and sanitized before being forwarded to the core frame.
+     *
+     * @param fields - A key/value map of metadata to attach to the chatter session.
+     *
+     * @example
+     * window.adaEmbed.setMetaFields({ userId: "u123", plan: "pro" });
+     */
+    setMetaFields(fields: Record<string, unknown>): void;
+    /**
+     * Show or hide the Ada dashboard test-mode banner ("Testing Process: X").
+     * `null` (or empty) hides it. Dashboard-only — only the Ada dashboard calls this.
+     */
+    setTestModeBanner(label: string | null): void;
+    /**
+     * Pass sensitive metafields securely via chatter sensitive metadata storage.
+     * Unlike {@link setMetaFields}, these values are not logged or exposed in plain text.
+     *
+     * @param fields - A key/value map of sensitive metadata to send.
+     *
+     * @example
+     * window.adaEmbed.setSensitiveMetaFields({ authToken: "secret" });
+     */
+    setSensitiveMetaFields(fields: Record<string, unknown>): void;
+    /**
+     * Register a device push-notification token for the active chatter.
+     *
+     * @param token - The device token string from APNs or FCM.
+     *
+     * @example
+     * window.adaEmbed.setDeviceToken("fcm-device-token-here");
+     */
+    setDeviceToken(token: string): void;
+    private _replayDeviceToken;
+    /**
+     * Programmatically send a message as the user in the active conversation.
+     * Opens the chat drawer if not already visible. If the chat has not started,
+     * the auto-greeting is skipped and the message starts the conversation.
+     *
+     * @param body - The message text to send.
+     *
+     * @example
+     * window.adaEmbed.sendMessage("I need help with my order");
+     */
+    sendMessage(body: string): Promise<SendMessageResult>;
+    /**
+     * Handle an incoming push notification by opening the chat drawer.
+     * Typically called from your notification service worker or app delegate.
+     *
+     * @example
+     * window.adaEmbed.handleNotification();
+     */
+    handleNotification(): void;
+    /**
+     * Request browser web-notification permission. Must be called in response to
+     * a user gesture (e.g. a button click) per browser policy. Once granted, the
+     * widget shows a browser notification for new live-agent messages while the
+     * page is hidden or the chat is closed (legacy chat parity); clicking it
+     * focuses the window, opens the chat, and emits `ada:web_notification:click`.
+     *
+     * @returns The resulting permission, or null if the browser has no support.
+     *
+     * @example
+     * myEnableNotificationsButton.onclick = () => window.adaEmbed.requestNotifications();
+     */
+    requestNotifications(): Promise<NotificationPermission> | null;
+    /**
+     * Track a custom analytics event.
+     *
+     * @param key  - The event name/key.
+     * @param value - Optional numeric value associated with the event.
+     * @param meta  - Optional freeform metadata payload.
+     *
+     * @example
+     * window.adaEmbed.trackEvent("page_view", 1, { page: "/pricing" });
+     */
+    trackEvent(key: string, value?: number, meta?: Record<string, unknown>): void;
+    /**
+     * Subscribe to a named SDK lifecycle event.
+     * Namespace matching applies: subscribing to `"ada:campaigns"` also
+     * receives `"ada:campaigns:shown"`, `"ada:campaigns:engaged"`, etc.
+     *
+     * @param key      - The event name or prefix to subscribe to (e.g. `"ada:start"`).
+     * @param callback - Called with the event payload whenever the event fires.
+     * @returns A numeric subscription ID. Pass to {@link unsubscribeEvent} to cancel.
+     *
+     * @example
+     * const id = window.adaEmbed.subscribeEvent("ada:start", (data) => {
+     *   console.log("Chat started", data);
+     * });
+     */
+    subscribeEvent(key: string, callback: AdaSdkEventCallback): number;
+    /**
+     * Cancel a subscription previously registered with {@link subscribeEvent}.
+     *
+     * @param id - The subscription ID returned by {@link subscribeEvent}.
+     *
+     * @example
+     * const id = window.adaEmbed.subscribeEvent("ada:start", handler);
+     * // later…
+     * window.adaEmbed.unsubscribeEvent(id);
+     */
+    unsubscribeEvent(id: number): void;
+    /**
+     * Subscribe to published events. Transcript-bearing events
+     * (`ada:message:sent` and `ada:message:received`) require exact
+     * `subscribeEvent()` listeners and are not delivered to broad subscribers.
+     * Designed for bridge adapters (React Native, iOS, Android) that need to
+     * forward SDK events to native code.
+     *
+     * @returns A numeric subscription ID. Pass to {@link unsubscribeEvent} to cancel.
+     *
+     * @example
+     * const id = window.adaEmbed.subscribeAll((key, data) => {
+     *   nativeBridge.postMessage(JSON.stringify({ type: "sdk.event", key, data }));
+     * });
+     */
+    subscribeAll(callback: (key: string, data: unknown) => void): number;
+    /**
+     * Trigger a proactive (scripted) conversation by its message key.
+     * `triggerProactiveConversation` is the deprecated alias for this method.
+     *
+     * @param messageKey - The proactive message key configured in the Ada dashboard.
+     * @param params     - Optional placeholder substitution values.
+     *
+     * @example
+     * window.adaEmbed.triggerProactive("welcome_returning_user", { name: "Alex" });
+     */
+    triggerProactive(messageKeyOrOptions: string | {
+        messageKey: string;
+        params?: Record<string, string>;
+    }, params?: Record<string, string>): void;
+    /** @deprecated Use triggerProactive() instead */
+    triggerProactiveConversation(key: string, params?: Record<string, string>): void;
+    /**
+     * @deprecated Messaging supports only generative features; scripted/declarative proactive messages are ignored.
+     */
+    createProactive(..._args: unknown[]): void;
+    /**
+     * @deprecated Messaging supports only generative features; scripted/declarative campaigns are ignored.
+     */
+    triggerCampaign(..._args: unknown[]): void;
+    /**
+     * @deprecated Messaging supports only generative features; scripted/declarative campaigns are ignored.
+     */
+    evaluateCampaignConditions(..._args: unknown[]): void;
+    /** Close the currently displayed proactive or campaign bubble. */
+    closeCampaign(): void;
+    /**
+     * Trigger a specific Answer by id. Sends a greeting carrying `response_id` —
+     * the same greeting path as {@link triggerGreeting}, whose `handle` argument is
+     * the other arm of the same union.
+     *
+     * @param answerId - Answer id, as shown in the dashboard URL for that Answer.
+     *
+     * @example
+     * window.adaEmbed.triggerAnswer("627d28a9bd9ca9e5337b9763");
+     */
+    triggerAnswer(answerId: string): void;
+    /**
+     * Mount all frames and start the SDK client.
+     * Use with {@link AdaMessagingClientConfig.lazy} = `true` to defer initialization
+     * until an explicit user action, then call `start()` to mount.
+     * Optional settings overrides are applied before first initialization.
+     * Floating mode activates only when the drawer is explicitly opened. Headless
+     * and parentElement modes have no launcher gesture, so start activates them.
+     *
+     * @example
+     * // Defer loading until consent granted:
+     * window.adaEmbed.start({ language: "fr" });
+     */
+    start(options?: AdaMessagingStartOptions): void;
+    /**
+     * Tear down all SDK frames and listeners, removing Ada from the page.
+     * Equivalent to {@link destroy}. The client can be re-mounted with {@link start}.
+     *
+     * @example
+     * window.adaEmbed.stop();
+     */
+    stop(): void;
+    /**
+     * Programmatically trigger the bot greeting in an active conversation.
+     *
+     * @param handle - Optional bot handle override. Defaults to the configured handle.
+     *
+     * @example
+     * window.adaEmbed.triggerGreeting();
+     */
+    triggerGreeting(handle?: string): void;
+    private _triggerGreeting;
+    /**
+     * Tear down all SDK frames, channels, and event listeners.
+     * The SDK cannot be reused after destroy without creating a new instance.
+     * Prefer {@link stop} for removable-and-restartable teardown.
+     *
+     * @example
+     * window.adaEmbed.destroy();
+     */
+    destroy(): void;
+    private _destroyRuntime;
+    /**
+     * Initialize the client: create the container div,
+     * mount all frames, and establish channels.
+     */
+    private _init;
+    private _initializeFrames;
+    /** Wire all message handlers for the core (headless business logic) frame. */
+    private _setupCoreChannel;
+    /** Wire all message handlers for the button (chat trigger) frame. */
+    private _setupButtonChannel;
+    private _clearIntroChannelHandshakeTimer;
+    private _clearIntroChannelDisplayTimer;
+    private _stopIntroChannelReadiness;
+    /** Bound one queued display without treating an unready frame as delivered. */
+    private _armIntroChannelDisplayTimeout;
+    /**
+     * A stripped Referrer-Policy leaves the child unable to send its queued
+     * origin/ready reports until it receives one trusted parent message. Retry a
+     * harmless command to the origin derived from the iframe src; FrameChannel
+     * still authenticates the eventual ready by source, origin, and frame name.
+     */
+    private _attemptIntroChannelUnlock;
+    /** Wire handlers, but wait for the runtime's authenticated ready to deliver. */
+    private _setupIntroChannel;
+    private _openProactiveCtaUrl;
+    /** Send the client configuration to a frame. */
+    private _deliverConfig;
+    /** Safely invoke a window-level callback if it exists and is a function */
+    private _invokeWindowCallback;
+    /**
+     * Headless has no visible drawer, but start() is still an activation boundary
+     * and a stalled activation otherwise has no host-facing signal at all. Track it
+     * with the same diagnostic budget as an embedded client while retaining the
+     * visible-drawer requirement for fallback UI.
+     */
+    private _isEligibleForActivationTimeouts;
+    /** Route a published event key to all matching subscribeEvent subscribers */
+    private _routePublishedEvent;
+    private _beginProactiveDisplay;
+    private _acknowledgeProactiveShown;
+    private _beginGreetingDisplay;
+    /** Publish the acknowledged bubble lifecycle event once, without inventing the
+     * declarative-only `ada:message_opened:*` business goal for Generative Chat. */
+    private _publishShownCampaignOpened;
+    private _warnDeclarativeOnlyMethod;
+    private _queuePendingCoreMessage;
+    private _flushPendingCoreMessages;
+    private _acceptStartupConfig;
+    /**
+     * Deliver the latest core-owned launcher appearance when a button channel is
+     * available. `_startupConfig` is the durable snapshot: if core wins the sibling
+     * iframe load race, `_setupButtonChannel()` replays the same snapshot later.
+     */
+    private _syncButtonStartupConfig;
+    /**
+     * Render the badge from its canonical state. A live message deliberately wins
+     * over a server seed rather than adding to it: the seed includes live-chat
+     * lifecycle notices, while `_unreadCount` counts messages received this page.
+     */
+    private _syncButtonUnreadCount;
+    private _showOrQueueIntroDisplay;
+    private _ensureIntroFrame;
+    private _showOrQueueEmojiDisplay;
+    private _drainPendingEmojiDisplay;
+    private _drainPendingIntroDisplay;
+    private _clearPendingIntroDisplay;
+    private _dropPendingIntroDisplay;
+    private _clearProgrammaticProactiveTimer;
+    private _clearProactive;
+    /** Apply a core-owned conversation reset to proactive state without touching
+     * an independent greeting that may already occupy the shared intro frame. */
+    private _clearProactiveFromCore;
+    private _beginProactiveIntent;
+    /** Retire only the core surface represented by a dropped queued callback. */
+    private _retireDroppedProactiveSurface;
+    private _nextProactiveIntentId;
+    /** Hide and invalidate the single legacy pre-chat surface. */
+    private _retirePreChatSurface;
+    private _showProactive;
+    /**
+     * @param keepChatter - the reset preserves the chatter core-side, so keep the
+     *   identity we already hold. Core announces a chatter only when its token
+     *   changes, so a preserved one is never re-announced and dropping it here
+     *   would strand us with no token for the unread routes.
+     */
+    private _prepareForSessionReset;
+    private _clearChatActivationTimeouts;
+    /**
+     * Holds the drawer's open geometry while it slides and fades out, then
+     * collapses it to 0×0.
+     *
+     * The collapse runs on a timer rather than `transitionend`: that event never
+     * fires when the transition is interrupted or the frame is not being
+     * rendered, and a missed collapse would strand a full-viewport `position:
+     * fixed` iframe over the customer's page (legacy embed-2 records this as
+     * breaking scrolling on iOS). The closing styles are already inert, so a lost
+     * timer degrades to a wasted paint region, not a blocked page.
+     */
+    private _startChatCloseAnimation;
+    private _clearChatHideTimer;
+    private _syncChatViewportHeight;
+    private _stopChatViewportHeightSync;
+    /**
+     * Lease the browser viewport to the core iframe while an in-chat surface is
+     * open. Only the SDK-owned floating drawer can make this promise: an inline
+     * embed may sit under a clipped/transformed ancestor, while headless/native
+     * clients own their own window geometry.
+     *
+     * The request remains recorded across a public close so reopening cannot show
+     * the in-app modal inside a card. The closed frame is 0x0 and inert; lifecycle
+     * replacement paths explicitly release the lease.
+     */
+    private _setHostViewportExpanded;
+    /** Mobile drawers and host-viewport surfaces share one composable lock. */
+    private _syncPageScrollLock;
+    /**
+     * Keeps the host page from scrolling behind an edge-to-edge SDK surface.
+     * The drags that escape are the ones starting on the drawer's non-scrollable
+     * chrome; the message list's own `overscroll-behavior-y: contain` covers
+     * end-of-list chaining, but only on iOS 16+ — iOS 15 is still the floor.
+     *
+     * Locks both `<html>` and `<body>`: the viewport's scroll is governed by
+     * whichever computes non-`visible` overflow (CSS Overflow L3 §3.3) — a host
+     * page with `html { overflow-x: hidden }` (a common horizontal-overflow fix)
+     * would make a body-only lock silently ineffective. No-op if already in the
+     * requested state, so a redundant unlock on close/destroy can't clobber a
+     * value that was never saved.
+     *
+     * Snapshots/restores the `overflow-x`/`overflow-y` longhands rather than the
+     * `overflow` shorthand: if a host set only one axis inline (e.g.
+     * `overflow-x: hidden`, a common way to suppress an unwanted horizontal
+     * scrollbar), reading the shorthand back returns `""` since it doesn't
+     * serialize from a single longhand — saving and restoring that would drop
+     * the host's original value entirely instead of preserving it.
+     */
+    private _setPageScrollLocked;
+    /**
+     * Whether the SDK draws its own floating-widget chrome — the launcher, the
+     * intro popup and the drawer scrim. `parentElement` hands window
+     * management to the host; `headless` mounts core alone.
+     */
+    private get _hasFloatingWidgetChrome();
+    private _startChatActivationTimeouts;
+    /** Re-arm only the inactivity fallback; the public diagnostic remains one-shot. */
+    private _rearmChatFallbackTimeout;
+    private _maybeShowChatTimeoutFallback;
+    private _disconnectCoreChannel;
+    private _showChatTimeoutFallback;
+    private _reloadCoreFrame;
+    private _invalidateStartupConfigForCoreReplacement;
+    private _requestActivationAfterCoreReload;
+    private _handleFrameTimeout;
+    private _setConfig;
+    private _clearIdentityToken;
+    private _clearGlobalIdentityToken;
+    private _applyResetOverridesToConfig;
+    private _sendPendingHistoryPreservingReset;
+    private _markCoreProtocolReady;
+    private _applyStartOverrides;
+    private _subscribeInternalEvent;
+    private _registerInternalEventCallbacks;
+    private _publishEmbedLoaded;
+    private _setupServiceWorkerNotificationClickHandler;
+    private _crossWindowDrawerStorageKey;
+    private _crossWindowLiveChatStorageKey;
+    private _safeSessionStorageGet;
+    private _safeSessionStorageSet;
+    private _safeSessionStorageRemove;
+    private _persistCrossWindowDrawerState;
+    private _setCrossWindowLiveChatActive;
+    private _clearCrossWindowPersistenceState;
+    private _armCrossWindowDrawerRestore;
+    private _clearUnreadCount;
+    private _chatterApiUrl;
+    /**
+     * Clear the chatter's server-side unread count.
+     *
+     * Deliberately not gated on the local count. api resets `unread_count` only
+     * from this route, and never on a new conversation, so it outlives both the
+     * page and the conversation. A clear that skipped the DELETE would leave a
+     * non-zero count for the next load to seed from — the badge would come back
+     * on every reload and never clear.
+     */
+    private _resetServerUnreadCount;
+    private _setChatterToken;
+    private _scheduleCandidateDiscovery;
+    private _setPersistedChatterCandidate;
+    private _beginExplicitEngagement;
+    private _inspectPersistedChatterCandidate;
+    private _handleSessionResumeResult;
+    private _handleSessionResumeVisibilityResult;
+    private _nextSessionResumeRequestId;
+    private _nextPositiveSafeInteger;
+    private _discardPersistedChatterCandidate;
+    private _cancelCandidateDiscoveryRequest;
+    private _resetCandidateDiscoveryForCoreReplacement;
+    private _invalidateNotificationStatusLookup;
+    private _getNotificationStatus;
+    /**
+     * Seed the launcher badge from the chatter's server-side unread count.
+     *
+     * api owns the scope of `unread_amount`; legacy applies a positive value without
+     * consulting `is_live_state`, including a count left by a handoff that has since
+     * ended. Keep the dot presentation because the value includes lifecycle notices as
+     * well as agent messages, and legacy also renders it as a dot.
+     */
+    private _seedUnreadCountFromServer;
+    private _applyUnreadStatus;
+    private _showEmbeddedChat;
+    private _isChatVisible;
+    private _getWindowInfo;
+    private _getProactiveRuntimeDependencies;
+    /**
+     * Schedule the intro greeting popup to display after the configured delay.
+     * Skipped when chat has opened, this client already showed it, or paths do not match.
+     */
+    private _scheduleIntro;
+    /**
+     * Patch history.pushState / replaceState and listen to popstate so that
+     * single-page-app navigation fires a synthetic "locationchange" event.
+     * Called once during `_init()`.
+     */
+    private _patchLocationHistory;
+    /** Restore original history methods and remove the locationchange listener. */
+    private _unpatchLocationHistory;
+    /** Record a delivered Text/card greeting in both legacy intro lifetimes. */
+    private _markGreetingIntroShown;
+    /** Patch only the current chatter when an accepted proactive is removed. */
+    private _markProactiveIntroShown;
+    private _currentRuntimeMeta;
+    /** Invalidate a queued microtask once the same latest snapshot is staged/sent. */
+    private _cancelScheduledRuntimeMetaSync;
+    /**
+     * Consume any staged snapshot and send current page truth on the supplied Core
+     * lifecycle. Callers place this immediately after a destructive protocol edge.
+     */
+    private _sendAuthoritativeRuntimeMeta;
+    /**
+     * Collapse synchronous history writes and intro commits into one latest-state
+     * update. A generation pin prevents a microtask queued by a destroyed client
+     * from reaching a later stop()/start() lifecycle.
+     */
+    private _scheduleRuntimeMetaSync;
+    /** Called on every SPA navigation. Re-evaluates intro and proactive conditions. */
+    private _onLocationChange;
+    /**
+     * Record URL-goal eligibility, then load definitions only for an active chatter.
+     * A dormant or provisional persisted token cannot post a business event and must
+     * not turn an ordinary launcher page load into another API request.
+     */
+    private _configureUrlBusinessEvents;
+    private _evaluateUrlBusinessEvents;
+    /**
+     * Evaluate URL-triggered proactive conversations for the current page,
+     * without the intro-greeting scheduling that `_onLocationChange` also does.
+     * Runs once on initial startup config (SPA navigation covers the rest).
+     */
+    private _evaluateProactiveConditions;
+    /** Normalize config align to a concrete "left" | "right" value. */
+    private get _align();
+    /** Whether the button is in text-label mode (affects frame sizing). */
+    private get _isTextButton();
+    private get _isHeadless();
+    private _requireProgrammaticControl;
+    /**
+     * Send a message to the core frame channel.
+     * Kept as a thin proxy for test spy compatibility (`vi.spyOn(client, "_sendToCore")`).
+     *
+     * Messages can be issued before the core channel exists: in lazy mode before
+     * `_init()`, during the initial core-frame bootstrap, or while retrying after
+     * a timeout fallback. A live router may receive ordinary activation before
+     * public config succeeds (that activation is the retry path). Only a pending
+     * history-preserving reset must hold later work until core.ready delivers the
+     * exact reset first.
+     */
+    private _sendToCore;
+    /** Create a FrameManager for the given container element. */
+    private _createFrameManager;
+}
+export { AdaMessagingClient };