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

package/dist/client/config-helpers.d.ts

@@ -0,0 +1,157 @@
+import { CSAT_INTEGRATION_ID, CSAT_SUBMIT_ACTION, normalizeCsatSubmitAction, VALID_ADA_CLUSTERS } from "../shared-utils/index.js";
+import type { MetaFieldValue } from "./client-types.js";
+export declare const LOCALHOST_CLUSTER = "localhost";
+export declare const DEFAULT_ADA_DOMAIN = "ada";
+export { VALID_ADA_CLUSTERS };
+export declare const KNOWN_ADA_BASE_DOMAINS: Set<string>;
+export declare const HANDLE_PATTERN: RegExp;
+export declare const LOCALHOST_API_PROXY_BASE = "https://messaging-demo.net:5040/api";
+export declare const LOOPBACK_API_PROXY_PORT = 5040;
+/** Hostname of the local messaging asset server (the /etc/hosts alias serving the SDK
+ * on :4900). When the SDK loads from here the demo-server proxy (:5040) is running
+ * too, so the bot API is reached through it — not the direct-bot fallback. */
+export declare const LOCAL_ASSETS_HOSTNAME = "messaging-assets.net";
+/** The api's default local `APP_PORT`. A `<handle>.localhost` host page (e.g. the
+ * app dashboard's Test Chat) talks to its bot api directly on this port. */
+export declare const LOCAL_BOT_API_PORT = 8000;
+export declare function deriveLocalhostApiProxyBase(sdkUrl: string, pageHost?: string): string;
+/**
+ * The `adaSettings.styles` keys that reach a token. `tintColor` is the only one:
+ * `surfaceColor`/`surfaceColorDark` have no token target in either design system, and
+ * a per-mode brand color does not exist at all (server config carries one mode-agnostic
+ * `tint_color`). Accepting the other three only made the surface look wider than it was.
+ */
+export declare const SUPPORTED_THEME_STYLE_KEYS: readonly ["tintColor"];
+export declare function normalizeIdentityToken(value: unknown): string | undefined;
+/**
+ * Normalize the custom app frame URL (`appUrl`), warning when a
+ * supplied value is dropped. Core re-validates through the same shared helper
+ * — a host page can post `sdk.config.set` straight at the core frame, so this
+ * is a convenience gate, not the security boundary.
+ *
+ * The drop logs through `logger.dataLoss` — host config the SDK accepted and
+ * then discarded is exactly the ungated channel's contract, and the GA docs
+ * promise a console warning here without a debug opt-in.
+ */
+export declare function normalizeAppUrlOverride(value: unknown): string | undefined;
+export declare const INTEGRATION_FRAME_IDS: readonly ["zendesk", "zendeskMessaging", "oauth", "csat"];
+export type IntegrationFrameId = (typeof INTEGRATION_FRAME_IDS)[number];
+export interface IntegrationCommand {
+    integration: string;
+    action: string;
+    payload?: Record<string, unknown>;
+    commandId?: string;
+}
+export interface IntegrationResultPayload {
+    commandId?: string;
+    integration: string;
+    action: string;
+    status: "success" | "error";
+    data?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export interface TrackedIntegrationCommand {
+    frameId: IntegrationFrameId;
+    integration: string;
+    action: string;
+    /** True only after the command crossed the ready frame channel. */
+    dispatched: boolean;
+    /** Correlation needed to fail the exact optimistic message if the frame hangs. */
+    messageId?: string;
+    requestId?: string;
+    zendeskOperationSeq?: number;
+}
+/**
+ * Normalize and validate a customer-provided endpoint override.
+ * Throws on invalid input so the constructor surfaces config errors early.
+ */
+export declare function validateEndpointOverride(endpoint: string): string;
+/** Append `/api/` to a base URL, avoiding double-appending if already present. */
+export declare function buildApiEndpoint(apiBase: string): string;
+export declare function normalizeClusterInput(value: string | null | undefined): string | null;
+export declare function validateCluster(cluster: string, label: string): string;
+/**
+ * Parse and validate the `handle`, `cluster`, and `domain` config values into a
+ * handle plus a canonical base-domain `cluster`. `domain` is the embed-2 base
+ * segment (e.g. "ada-dev2"); a full URL override belongs in `endpoint`, not here.
+ */
+export declare function parseClientIdentity(rawHandle: string, rawCluster?: string | null, rawDomain?: string | null): {
+    handle: string;
+    cluster: string | null;
+};
+/**
+ * Attempt to detect an Ada base domain from the SDK asset URL.
+ * Returns the longest matching suffix from KNOWN_ADA_BASE_DOMAINS, or null.
+ */
+export declare function resolveAdaBaseDomainFromSdkUrl(sdkUrl: string): string | null;
+/**
+ * Derive the default API base URL from the handle, SDK URL, and optional cluster.
+ * Used when no explicit `endpoint` override is provided in config.
+ */
+export declare function deriveDefaultApiBase(handle: string, sdkUrl: string, cluster?: string | null): string;
+/** Strip non-primitive values and empty keys from a metafield record.
+ * Also enforces key/value length limits and a maximum entry count to
+ * prevent oversized payloads from reaching the API (which would 413).
+ * Sensitive records still report data loss, but never name their keys. */
+export declare function sanitizeMetaFieldRecord(fields: Record<string, unknown>, options?: {
+    sensitive?: boolean;
+}): Record<string, MetaFieldValue>;
+/** Query-param prefix that the standalone `chat.html` forwards as conversation
+ * metaFields: `?mf_email=…&mf_bot_handle=…` → `metaFields: { email, bot_handle }`.
+ * Lets a host (e.g. the dashboard "Ask for Help" popup) pass context to the bot
+ * without baking business keys into the entry point. */
+export declare const CHAT_HTML_META_FIELD_PREFIX = "mf_";
+export interface ChatHtmlConfig {
+    handle: string;
+    cluster?: string;
+    language?: string;
+    greeting?: string;
+    metaFields: Record<string, MetaFieldValue>;
+}
+/**
+ * Build the standalone `chat.html` SDK config (sans `parentElement`) from its
+ * query string. Reads `ada_handle` (required) / `ada_cluster` / `language` /
+ * `greeting`, and forwards every `mf_<key>` param as a sanitized `metaFields`
+ * entry. Returns `null` when `ada_handle` is absent.
+ */
+export declare function resolveChatHtmlConfig(search: string | URLSearchParams): ChatHtmlConfig | null;
+/**
+ * Return only the host overrides that are both supported and safe to paint.
+ *
+ * Carries no defaults. Core treats every key it receives here as "the host asked for
+ * this", so seeding a default would hand every bot the same hardcoded tint in place of
+ * the one configured in its dashboard.
+ */
+export declare function sanitizeThemeStyles(styles: Record<string, string> | undefined): Record<string, string>;
+/**
+ * Determine which live-agent platform is active based on the command.
+ * `handoff.request` and `fileUpload` commands carry platform hints.
+ */
+export declare function normalizeLiveAgentPlatform(command: IntegrationCommand, activePlatform: string | null): string | null;
+/** Normalize CSAT action strings; pass all other actions through unchanged. */
+export declare function normalizeIntegrationAction(integration: string, action: string): string;
+/**
+ * Resolve which integration iframe should handle the given command,
+ * also returning the updated active live-agent platform.
+ */
+export declare function resolveIntegrationTarget(command: IntegrationCommand, activePlatform: string | null): {
+    frameId: IntegrationFrameId | null;
+    nextActivePlatform: string | null;
+};
+export { CSAT_INTEGRATION_ID, CSAT_SUBMIT_ACTION, normalizeCsatSubmitAction };
+/**
+ * Check whether the embedding page URL contains a private-mode override.
+ *
+ * Detects:
+ *   - ?private=true
+ *   - ?private=1
+ *   - #private  (hash must be exactly "#private")
+ *
+ * When any of these is present, storage is forced to "private" mode
+ * regardless of the client config's persistence setting.
+ */
+export declare function detectPrivateUrlOverride(location?: Pick<Location, "search" | "hash">): boolean;

package/dist/client/constants.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Central source of truth for all numeric limits and timeouts used across SDK modules.
+ * Import from here instead of defining local constants to avoid drift.
+ */
+/** Milliseconds to wait for a top-level frame to fire its load event */
+export declare const FRAME_LOAD_TIMEOUT_MS = 10000;
+/**
+ * Milliseconds to wait after the host opens chat before publishing the legacy
+ * timeout event when activation has not completed.
+ */
+export declare const CHAT_ACTIVATION_TIMEOUT_EVENT_MS = 5000;
+/**
+ * Parent-element embeds are visible while their public and engaged config are
+ * still loading, and headless starts without the launcher's config-fetch head
+ * start, so the floating widget's 5-second diagnostic is too eager for those
+ * paths. This remains an early signal, well before the fallback UI budget.
+ */
+export declare const CHAT_ACTIVATION_TIMEOUT_EVENT_PARENT_ELEMENT_MS = 15000;
+/**
+ * Milliseconds to wait after the host opens chat before auto-showing the
+ * self-contained fallback document when one bounded activation step has made
+ * no progress. Core completion checkpoints re-arm this inactivity budget.
+ *
+ * Every startup request is bounded to at most 20 seconds and bot-domain
+ * storage hydration is bounded to 6 seconds. Thirty seconds therefore leaves
+ * margin for a healthy chatter create/identify POST without navigating its
+ * owning core frame away while the server commit may still be in flight.
+ */
+export declare const CHAT_FALLBACK_DELAY_MS = 30000;
+/**
+ * Absolute visible-activation ceiling. Progress from an unrelated recovery or
+ * reset may share the same internal channel, so re-arming cannot be unbounded.
+ */
+export declare const CHAT_FALLBACK_MAX_TOTAL_MS = 120000;
+/**
+ * Milliseconds to wait for a frame to send its `frame.origin.report` message.
+ * After this window, the SDK falls back to the expected origin (if known) or
+ * logs a warning, so queued messages are not held indefinitely.
+ */
+export declare const ORIGIN_REPORT_TIMEOUT_MS = 3000;
+/**
+ * Bound the parent-to-intro handshake used when a host strips the iframe's
+ * referrer. The child cannot flush its queued origin/ready reports until it
+ * receives one trusted parent message, while a broken child must not be pinged
+ * for the rest of the page's lifetime.
+ */
+export declare const INTRO_CHANNEL_UNLOCK_MAX_ATTEMPTS = 20;
+/** Maximum number of integration commands that can be buffered per frame */
+export declare const MAX_PENDING_COMMANDS = 64;
+/** Maximum number of integration commands tracked for result callbacks */
+export declare const MAX_TRACKED_COMMANDS = 256;
+/** Milliseconds before an integration command result callback times out */
+export declare const COMMAND_RESULT_TIMEOUT_MS = 20000;
+/** Per-step inactivity budget for reset/deleteHistory durable acknowledgements. */
+export declare const RESET_ACK_TIMEOUT_MS = 30000;
+/** Absolute ceiling for progress-rearmed destructive-operation acknowledgements. */
+export declare const RESET_ACK_MAX_TOTAL_MS: number;
+/** Per-step inactivity budget for a cold programmatic send. */
+export declare const SEND_MESSAGE_TIMEOUT_MS = 30000;
+/** Absolute ceiling for a progress-rearmed cold programmatic send. */
+export declare const SEND_MESSAGE_MAX_TOTAL_MS = 120000;

package/dist/client/core-channel-test-harness.d.ts

@@ -0,0 +1,47 @@
+import type { AdaMessagingClient } from "./client.js";
+export type CoreHandler = (message: {
+    payload: unknown;
+}) => void;
+/** Install a connected core channel without mounting a real iframe. */
+export declare function installCoreChannel(client: AdaMessagingClient): {
+    channel: {
+        send: import("vitest").Mock<import("@vitest/spy").Procedure>;
+        on: import("vitest").Mock<(type: string, handler: CoreHandler) => void>;
+    };
+    handlers: Map<string, CoreHandler>;
+};
+/** Wire the production core handlers onto the stub channel. */
+export declare function installRealCoreHandlers(client: AdaMessagingClient, options?: {
+    ready?: boolean;
+}): {
+    channel: {
+        send: import("vitest").Mock<import("@vitest/spy").Procedure>;
+        on: import("vitest").Mock<(type: string, handler: CoreHandler) => void>;
+    };
+    handlers: Map<string, CoreHandler>;
+};
+/** Wire production handlers onto the Core frame manager already mounted by the client. */
+export declare function attachRealCoreHandlers(client: AdaMessagingClient, options?: {
+    ready?: boolean;
+}): {
+    channel: {
+        send: import("vitest").Mock<import("@vitest/spy").Procedure>;
+        on: import("vitest").Mock<(type: string, handler: CoreHandler) => void>;
+        disconnect: import("vitest").Mock<import("@vitest/spy").Procedure>;
+    };
+    handlers: Map<string, CoreHandler>;
+};
+export declare function requestIdsFor(channel: {
+    send: {
+        mock: {
+            calls: unknown[][];
+        };
+    };
+}, type: string): string[];
+export declare function requestIdFor(channel: {
+    send: {
+        mock: {
+            calls: unknown[][];
+        };
+    };
+}, type: string): string;

package/dist/client/embed-interface.d.ts

@@ -0,0 +1,172 @@
+import type { AdaMessagingStartOptions, AdaSdkEventCallback, ConversationInfo, Delegate, MetaFieldValue, PublicMessage, ResetParams, SendMessageResult, WindowInfo } from "./client-types.js";
+/** One queued call captured by the embed loader before the SDK was ready. */
+export interface LoaderQueueAction {
+    method: string;
+    arguments: unknown[];
+}
+/** Whether a replayed loader-queue action resolved or rejected. */
+export type LoaderQueueActionOutcome = "resolve" | "reject";
+/** Reports the raw object identity from the host-writable loader queue. */
+export type LoaderQueueActionOutcomeHandler = (action: object, outcome: LoaderQueueActionOutcome, detail: unknown) => void;
+/**
+ * The public host-page facade, exposed as `window.adaEmbed`. Create it with
+ * {@link createAdaEmbedInterface}; every method resolves once the underlying
+ * client has accepted the action. Methods other than `start`, `subscribe*`,
+ * and `setDelegate` reject until `start()` has instantiated a client.
+ */
+export interface AdaEmbedInterface {
+    /**
+     * Instantiate and start the Messaging client with the merged settings
+     * (`window.adaSettings`, then earlier settings, then this call's).
+     * Rejects with `AdaEmbedError("start_already_active")` when already
+     * started and `"start_interrupted"` when a callback stops it mid-start.
+     * `settings.handle` is required unless it was already provided.
+     */
+    start: (settings?: AdaMessagingStartOptions) => Promise<void>;
+    /** Stop and tear down the running client. A later start() may run again. */
+    stop: () => Promise<void>;
+    /** Open the chat drawer when closed, or close it when open. */
+    toggle: () => Promise<void>;
+    /**
+     * Permanently clear the chatter's conversation history and persisted
+     * state. Resolves on durable confirmation from the runtime.
+     */
+    deleteHistory: () => Promise<void>;
+    /**
+     * Reset the session. By default this clears history and creates a new
+     * chatter; pass `resetChatHistory: false` to update config while keeping
+     * history. Caller-supplied `metaFields` apply on a full reset only when
+     * the host opted in via `allowMetaFieldsInReset`.
+     */
+    reset: (params?: ResetParams) => Promise<void>;
+    /** Merge non-sensitive metafield key/value pairs onto the chatter. */
+    setMetaFields: (fields: Record<string, unknown>) => Promise<void>;
+    /**
+     * Merge sensitive metafield key/value pairs, delivered over the secure
+     * storage transport and never readable back via getMetaFields().
+     */
+    setSensitiveMetaFields: (fields: Record<string, unknown>) => Promise<void>;
+    /** Show a test-mode banner with the given label, or remove it with null. */
+    setTestModeBanner: (label: string | null) => Promise<void>;
+    /** Read the current window state (open/drawer/chatter flags). */
+    getInfo: () => Promise<WindowInfo>;
+    /** Read the chatter's non-sensitive metafields. Sensitive fields are never returned. */
+    getMetaFields: () => Promise<Record<string, MetaFieldValue>>;
+    /** Whether the chat is currently visible to the user. */
+    isOpen: () => Promise<boolean>;
+    /**
+     * Read the active conversation id and live-agent handoff state.
+     * Requires `enableProgrammaticControl`; rejects when the gate is off.
+     */
+    getConversation: () => Promise<ConversationInfo>;
+    /**
+     * Read the conversation transcript as public message shapes.
+     * Requires `enableProgrammaticControl`; rejects when the gate is off.
+     */
+    getMessages: () => Promise<PublicMessage[]>;
+    /**
+     * Replace the composer input text. Requires `enableProgrammaticControl`;
+     * throws `HeadlessModeError` in headless mode (there is no composer).
+     */
+    setComposerText: (text: string) => Promise<void>;
+    /**
+     * Register a delegate whose `beforeSend` hook may rewrite or veto outgoing
+     * text. Callable before start(); requires `enableProgrammaticControl`
+     * once a client is running. Pass null/undefined to clear.
+     */
+    setDelegate: (delegate: Delegate | null | undefined) => void;
+    /** Send a custom analytics event for conversation tracking. */
+    trackEvent: (key: string, value?: number, meta?: Record<string, unknown>) => Promise<void>;
+    /**
+     * Subscribe to a public `ada:*` event key. Resolves a subscription id for
+     * unsubscribeEvent(). Callable before start(); subscriptions replay onto
+     * each started client.
+     */
+    subscribeEvent: (key: string, callback: AdaSdkEventCallback) => Promise<number>;
+    /** Remove a subscription created by subscribeEvent() or subscribeAll(). */
+    unsubscribeEvent: (id: number) => Promise<void>;
+    /**
+     * Subscribe to every broadcast event. The gated transcript events
+     * (`ada:message:sent` / `ada:message:received`) are exact-subscription
+     * only and never delivered to wildcard subscribers.
+     */
+    subscribeAll: (callback: (key: string, data: unknown) => void) => Promise<number>;
+    /** Open the chat drawer. No-op in headless mode. */
+    open: () => Promise<void>;
+    /** Close the chat drawer. */
+    close: () => Promise<void>;
+    /** Switch the conversation language (e.g. "en", "fr"). */
+    setLanguage: (language: string) => Promise<void>;
+    /** Set the color scheme; "auto" follows the OS preference. */
+    setTheme: (theme: "light" | "dark" | "auto") => Promise<void>;
+    /** Register a push-notification device token for this chatter. */
+    setDeviceToken: (token: string) => Promise<void>;
+    /**
+     * Send a message into the conversation as the user. Requires
+     * `enableProgrammaticControl`; resolves the accepted message id.
+     */
+    sendMessage: (body: string) => Promise<SendMessageResult>;
+    /** Open the chat in response to a host-handled push notification tap. */
+    handleNotification: () => Promise<void>;
+    /**
+     * Prompt for web-notification permission via the browser. Call it from a
+     * user gesture; resolves the resulting permission, or null when the
+     * Notification API is unavailable.
+     */
+    requestNotifications: () => Promise<NotificationPermission | null>;
+    /** @deprecated Messaging supports only generative features; scripted/declarative proactive messages are ignored. */
+    createProactive: (body: string, duration?: number, responseId?: string) => Promise<void>;
+    /** @deprecated Messaging supports only generative features; scripted/declarative campaigns are ignored. */
+    triggerCampaign: (campaignKey: string, options?: Record<string, unknown>) => Promise<void>;
+    /** @deprecated Messaging supports only generative features; scripted/declarative campaigns are ignored. */
+    evaluateCampaignConditions: (options?: Record<string, unknown>) => Promise<void>;
+    /** Close the currently displayed proactive or campaign bubble. */
+    closeCampaign: () => Promise<void>;
+    /** Trigger a generative Answer by its response id. */
+    triggerAnswer: (answerId: string) => Promise<void>;
+    /** Trigger a proactive message by key, with optional template params. */
+    triggerProactive: (messageKeyOrOptions: string | {
+        messageKey: string;
+        params?: Record<string, string>;
+    }, params?: Record<string, string>) => Promise<void>;
+    /** Re-evaluate and show the configured greeting for the bot. */
+    triggerGreeting: (handle?: string) => Promise<void>;
+    /** Tear down all frames, channels, and subscriptions permanently. */
+    destroy: () => Promise<void>;
+}
+declare global {
+    interface Window {
+        __AdaEmbedLoaderInitialActionQueue?: LoaderQueueAction[];
+        /**
+         * @deprecated Subscribe to `ada:embed_loaded` or use
+         * `window.adaSettings.onAdaEmbedLoaded` instead.
+         */
+        adaEmbedLoadedCallback?: () => void;
+    }
+}
+/**
+ * Create the public `adaEmbed` facade around a lazily-created
+ * {@link AdaMessagingClient}. Settings merge in priority order: this call's
+ * `initialSettings` over `window.adaSettings`, then `start(settings)` over
+ * both. Subscriptions and a delegate registered before `start()` are queued
+ * and replayed onto each started client.
+ */
+export declare function createAdaEmbedInterface(initialSettings?: AdaMessagingStartOptions): AdaEmbedInterface;
+/**
+ * Backward-compatible method-event replay for already-released loaders.
+ *
+ * Keep this frozen-queue Promise chain separate from atomic replay. Existing
+ * loaders observe synchronous validation and one Promise reaction per API call.
+ */
+export declare function dispatchEmbedLoaderInitialActionQueue(api: object): void;
+/**
+ * Replays for a loader that can restore legacy after genuine startup failure.
+ * Terminal validation and invocation outcomes use exact action identity. The
+ * returned promise is only the startup decision, while `onQueueDrained` closes
+ * retained-facade routing synchronously.
+ * An already-empty queue can invoke `onQueueDrained` before this function returns,
+ * so the loader must finish its handoff state changes before calling this function.
+ * If the frozen queue has no `start`, startup is accepted immediately; a `start`
+ * appended later is still replayed and exact-settled but cannot reopen rollback.
+ */
+export declare function dispatchEmbedLoaderInitialActionQueueForAtomicHandoff(api: object, onOutcome: LoaderQueueActionOutcomeHandler, onQueueDrained: () => void): Promise<void>;

package/dist/client/embed-lifecycle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lifecycle channel between `createAdaEmbedInterface` and the npm loader's
+ * memo: a non-enumerable getter over closure state, so the loader never
+ * mutates the public surface and `Object.freeze` on the facade still works.
+ * `Symbol.for` because the loader and the CDN runtime are separate builds;
+ * a runtime that predates the getter yields `undefined` — degrade gracefully.
+ */
+export declare const EMBED_LIFECYCLE_STOPPED: unique symbol;
+/** Read the facade's stopped flag; `undefined` when the runtime predates it. */
+export declare function readEmbedStoppedFlag(ada: object): boolean | undefined;
+/** Define the getter at facade creation time, before any host freeze. */
+export declare function defineEmbedStoppedFlag(ada: object, readStopped: () => boolean): void;

package/dist/client/fallback-html.d.ts

@@ -0,0 +1 @@
+export declare function getFallbackDataURI(): string;

package/dist/client/frame-manager.d.ts

@@ -0,0 +1,64 @@
+import type { FrameChannel, FrameName, FrameRegistry } from "../frame-channel/index.js";
+export interface FrameManagerOptions {
+    handle: string;
+    /** Resolved asset rollout cluster (e.g. "ada.support") */
+    cluster: string;
+    /** Value of import.meta.env.VITE_ASSETS_ORIGIN */
+    assetsOrigin: string;
+    /** Value of import.meta.env.VITE_COMMIT_SHA — omit for un-versioned assets */
+    commitSha?: string;
+    container: HTMLElement;
+    onFrameTimeout: (name: FrameName, message: string) => void;
+    setupCoreChannel: (channel: FrameChannel) => void;
+    setupButtonChannel: (channel: FrameChannel) => void;
+    setupIntroChannel: (channel: FrameChannel) => void;
+}
+/**
+ * FrameManager — owns the iframe registry, postMessage channels, and frame
+ * load lifecycle.
+ *
+ * All low-level DOM operations delegate to the pure-function helpers in
+ * `client-frame-runtime.ts`. This class provides the stateful wrapper that
+ * wires those functions together and holds the shared state they need.
+ *
+ * Responsibilities:
+ *  - buildAssetUrl: construct versioned asset URLs with ada_handle/cluster params
+ *  - mountFrame: create an iframe, append it to the container, start load timeout
+ *  - sendToCore: send a typed postMessage to the core frame channel
+ *  - getFrameOrigin: derive the expected origin from a frame's src
+ *  - teardown: cancel timers, disconnect channels, remove container from DOM
+ */
+export declare class FrameManager {
+    private readonly _frames;
+    private readonly _channels;
+    private readonly _loadTimers;
+    private readonly _options;
+    constructor(options: FrameManagerOptions);
+    /** The container element that holds all managed iframes. */
+    get container(): HTMLElement;
+    /** Read-only view of the iframe registry — used by channel-setup and proactive helpers. */
+    get frames(): FrameRegistry;
+    /** Read-only view of the channel map — used by channel-setup and proactive helpers. */
+    get channels(): Map<FrameName, FrameChannel>;
+    /** Construct a versioned asset URL for the given package and path. */
+    buildAssetUrl(packageName: "sdk" | "integrations", path: string): string;
+    /** Create an iframe, append it to the container, and register a load timeout. */
+    mountFrame(name: FrameName, options: {
+        style: string;
+    }): void;
+    /** Send a typed postMessage to the core frame. No-op if the channel is not yet open. */
+    sendToCore<T>(type: string, payload: T): void;
+    /**
+     * Resolve a frame's absolute origin from its src attribute.
+     * Returns null for invalid or non-http(s) URLs.
+     */
+    getFrameOrigin(frame: HTMLIFrameElement): string | null;
+    /**
+     * Tear down all managed state:
+     *  - disconnect all frame channels
+     *  - clear load timers
+     *  - remove the container from the DOM
+     */
+    teardown(): void;
+    private _onFrameLoaded;
+}