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

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

@@ -0,0 +1,164 @@
+/** CSS styles for hidden utility iframes (collapsed intro, etc.) */
+export declare const HIDDEN_FRAME_STYLES = "position:absolute;width:0;height:0;border:0;overflow:hidden;";
+/**
+ * Transparent halo (px) the button iframe reserves on every side so the unread
+ * badge, which overhangs the button's top-right corner, isn't clipped by the
+ * iframe bounds. Must match `BADGE_HALO` in `public/button.html`: button.html
+ * adds it to the reported frame size, and `getButtonFrameStyles` pulls the
+ * anchor in by the same amount so the 24px visual edge gap is unchanged.
+ */
+export declare const BUTTON_BADGE_HALO = 8;
+/**
+ * Transparent band (px) the proactive iframe reserves on every side so the
+ * bubble's drop shadow isn't clipped by the iframe bounds. `0 8px 24px` reaches
+ * 12px sideways and 20px below the box, and an iframe clips its own document
+ * regardless of the element's `overflow`, so anything short of that leaves the
+ * shadow ending on a hard line.
+ *
+ * Must match `.ada-intro-container`'s padding in
+ * `packages/integrations/src/intro-page.tsx`: the container paints the band, and
+ * {@link getProactiveFrameStyles} pulls the anchors out by the same amount so the
+ * content's visual position is unchanged. Same arrangement as
+ * {@link BUTTON_BADGE_HALO} and `public/button.html`.
+ */
+export declare const PROACTIVE_SHADOW_HALO = 24;
+/**
+ * The gap every floating surface keeps from the viewport edge. Shared so the
+ * launcher, the drawer and the proactive bubble cannot drift apart — the bubble
+ * lining up with the launcher is the whole point of threading it through.
+ */
+export declare const EDGE_GAP = 24;
+/** Default launcher diameter — `--btn-size` in `public/button.html`. */
+export declare const DEFAULT_LAUNCHER_SIZE = 64;
+/**
+ * The launcher frame's height before `button.resize` reports the measured one:
+ * the default button plus the badge halo it reserves on each side.
+ */
+export declare const DEFAULT_LAUNCHER_FRAME_HEIGHT: number;
+/**
+ * Read the launcher frame's current height off the element the `button.resize`
+ * handler sizes. Falls back to the default when the frame hasn't reported yet —
+ * a proactive can be shown before the launcher measures itself.
+ */
+export declare function getLauncherFrameHeight(launcher: HTMLElement | null | undefined): number;
+export declare const VIEWPORT_HEIGHT_CSS_VAR = "--ada-messaging-viewport-height";
+/** Legacy embed-2's drawer durations (`ChatFrame/index.tsx` `:389` and `:178`). */
+export declare const CHAT_OPEN_TRANSITION_MS = 300;
+export declare const CHAT_CLOSE_TRANSITION_MS = 200;
+/**
+ * The closed drawer's resting styles — used both to mount the core frame and to
+ * park it after a close. Collapsed to 0×0 *and* carrying the animation's start
+ * values: a transition needs a committed start value to interpolate from, so a
+ * frame resting at plain {@link HIDDEN_FRAME_STYLES} (`opacity` 1, no
+ * `transform`) would snap open however the open styles are written.
+ */
+export declare const CHAT_FRAME_COLLAPSED_STYLES = "position:absolute;width:0;height:0;border:0;overflow:hidden;opacity:0;transform:translateY(100px);";
+/**
+ * Ada's own stacking scale, named so the scrim's position is declared alongside
+ * the frames it has to sit under rather than inferred from them. The invariant
+ * has two halves — the scrim must stay below every frame, and above the band
+ * host chrome occupies — so it is pinned by `frame-styles.test.ts` rather than
+ * derived: a `Math.min` over the frames would satisfy the first half while a
+ * future low-stacked frame silently dragged the scrim under host content.
+ *
+ * `scrim` is embed-2's `.drawer-mask` value.
+ *
+ * `proactive` sits one below `launcher` deliberately. The proactive frame reserves
+ * a transparent shadow halo that reaches down over the launcher, and an iframe is
+ * atomic for hit-testing — a click anywhere in its box is consumed by its own
+ * document and never falls through to what is underneath, whatever
+ * `pointer-events` that document sets. At an equal z-index the winner would be DOM
+ * order, including a lazily mounted `intro` frame appended after `button`,
+ * so the halo would paint over the launcher and swallow clicks on its top edge
+ * while a bubble is showing — exactly when the user is most likely to reach for it.
+ */
+export declare const FRAME_Z_INDEX: {
+    readonly scrim: 9998;
+    readonly proactive: 9999;
+    readonly launcher: 10000;
+    readonly chat: 10001;
+    readonly chatMobile: 10010;
+    readonly hostViewport: 10020;
+};
+/** Legacy Embed2's mobile signal: fixed for the page lifetime and UA-based. */
+export declare function isMobileViewport(): boolean;
+/**
+ * Legacy Generative Chat's content-layout signal. Unlike Embed2's outer drawer
+ * geometry above, Chat included iPad when choosing mobile quick-reply layouts.
+ */
+export declare function isMobileContentLayout(): boolean;
+/**
+ * A media query can't be expressed in an inline `style` attribute, and injecting
+ * a `<style>` element is not reliable on a host page whose CSP omits
+ * `'unsafe-inline'` — so the drawer's reduced-motion branch is resolved in JS.
+ * Degrades to "animate" when `matchMedia` is unavailable, matching
+ * {@link isMobileViewport}.
+ */
+export declare function prefersReducedMotion(): boolean;
+export declare function syncFrameViewportHeight(element: HTMLElement): () => void;
+/**
+ * CSS styles for the button launcher iframe.
+ *
+ * The iframe starts invisible (opacity:0) and at 0×0 size. Once the
+ * button.html content renders and measures itself, it sends a
+ * "button.resize" postMessage with its dimensions. The SDK then
+ * resizes the iframe to fit and fades it in.
+ *
+ * The reported size is intentionally oversized by `BUTTON_BADGE_HALO` on each
+ * side so the overhanging unread badge isn't clipped by the iframe bounds, and
+ * the anchor is pulled in by the same amount to preserve the 24px visual edge
+ * gap. The halo is an inert band around the launcher (matching legacy chat,
+ * which reserves an even larger buffer) — it is not click-through.
+ */
+export declare function getButtonFrameStyles(align: "left" | "right", _isText: boolean, isParentElement: boolean): string;
+/**
+ * CSS styles for the open chat widget iframe.
+ *
+ * @param align           - "left" | "right" (from client config)
+ * @param isParentElement - true when the SDK is mounted inside a host element
+ * @param isMobile        - true for legacy's UA-detected mobile form factor;
+ *                          renders the drawer edge-to-edge full screen instead of the
+ *                          floating desktop card.
+ * @param animate         - false reproduces the pre-animation styles exactly (reduced motion,
+ *                          and any restyle that must land instantly). Geometry is never
+ *                          transitioned — only `opacity`/`transform` — so the drawer's box
+ *                          still snaps to full size while the content slides and fades in.
+ */
+export declare function getChatFrameStyles(align: "left" | "right", isParentElement: boolean, isMobile?: boolean, animate?: boolean): string;
+/**
+ * Temporary host-viewport geometry for content that needs more room than the
+ * floating drawer (for example, an image lightbox). This is deliberately an
+ * SDK-owned iframe style, not a host-DOM portal: old SDKs ignore the request,
+ * and parent-element/headless clients never apply it.
+ *
+ * `100%` and the synchronized viewport-height custom property avoid the mobile
+ * browser chrome traps of `100vw`/`100vh`. Every declaration needed to restore
+ * an interactive frame is explicit because `applyFrameStyle` replaces the
+ * complete inline style block.
+ */
+export declare function getHostViewportFrameStyles(): string;
+/**
+ * The drawer's styles for the duration of the close animation: the *open*
+ * geometry, so there is a box to animate, plus the hidden end state.
+ *
+ * `visibility` flips only after the transition completes (`0ms linear` with a
+ * matching delay, legacy embed-2's shape) and `pointer-events:none` applies at
+ * once, so a frame still holding open geometry is inert over the customer's page
+ * even if the caller's collapse never lands.
+ */
+export declare function getChatFrameClosingStyles(align: "left" | "right", isMobile?: boolean): string;
+/**
+ * CSS styles for the proactive message intro iframe.
+ *
+ * Returns `HIDDEN_FRAME_STYLES` in parentElement mode because proactive
+ * popups are suppressed when the SDK is embedded in a host element.
+ *
+ * The anchors are the *visual* gaps minus {@link PROACTIVE_SHADOW_HALO}, since
+ * the container inside the frame insets the content by the halo. `EDGE_GAP`
+ * matches `getButtonFrameStyles` so the bubble and the launcher share a right
+ * edge.
+ *
+ * @param align           - "left" | "right" (from client config)
+ * @param isParentElement - true when the SDK is mounted inside a host element
+ */
+export declare function getProactiveFrameStyles(align: "left" | "right", isParentElement: boolean, launcherFrameHeight?: number): string;

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

@@ -0,0 +1,53 @@
+/**
+ * Whether a frame carrying this style block is invisible to a sighted user. The SDK
+ * expresses that three ways and only three — collapsing to 0×0, fading to
+ * `opacity: 0`, and the closing drawer's `visibility: hidden` — so the style block
+ * is the whole answer.
+ *
+ * Read from the declaration string rather than the element's parsed
+ * `style.width`/`style.opacity`, because jsdom drops every declaration after an
+ * `overflow` shorthand: the launcher's own mount style parses to an empty
+ * `CSSStyleDeclaration` there, so an element-based reading would be right in a
+ * browser and silently wrong in every unit test.
+ *
+ * A block that declares the *end* of a transition rather than the frame's current
+ * appearance is not something the string can distinguish — those callers write the
+ * style and set exposure themselves.
+ */
+export declare function isHiddenFrameStyle(style: string): boolean;
+/**
+ * Whether the frame has been sized by something other than its collapsed mount
+ * style. The launcher mounts at 0×0 and only becomes a real control once
+ * `button.resize` reports a measurement, so exposing it before that publishes an
+ * empty node the chatter cannot reach.
+ */
+export declare function hasMeasuredSize(frame: HTMLElement | null | undefined): boolean;
+/**
+ * Add or drop a frame's `aria-hidden`, keeping its focusability in step.
+ *
+ * `aria-hidden` alone leaves the frame's own controls in the tab order, so a
+ * keyboard user lands on something their screen reader has been told to ignore
+ * (axe `aria-hidden-focus`) — `inert` is what takes the subtree out of sequential
+ * focus, and it crosses into a frame's nested document where `tabindex` cannot.
+ *
+ * Where `inert` is unimplemented, `visibility: hidden` is the fallback: a 0×0 or
+ * faded frame still offers its nested controls to Tab, and `visibility` is the one
+ * property that removes a whole subtree — nested browsing context included — from
+ * both the tree and sequential focus. It costs the fade/slide on those browsers,
+ * which is the right trade against a reader-invisible control being reachable.
+ *
+ * Exposure drops the attribute rather than setting `aria-hidden="false"`, which
+ * cannot override a hidden ancestor and so reads as an opt-back-in it can never be.
+ */
+export declare function setFrameHidden(frame: HTMLElement | null | undefined, hidden: boolean): void;
+/**
+ * Write a frame's style block and bring its accessibility exposure with it.
+ *
+ * Derived from the style rather than passed alongside it because the two must not
+ * be able to disagree: a collapsed frame left in the tree offers a reader a control
+ * that cannot be operated, and a visible frame kept out of it is invisible to
+ * assistive technology while the chatter can see it. Frames whose visibility changes
+ * without a new style block — the launcher, which is faded by property writes —
+ * call {@link setFrameHidden} directly.
+ */
+export declare function applyFrameStyle(frame: HTMLElement | null | undefined, style: string): void;

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

@@ -0,0 +1,73 @@
+import { FrameChannel } from "../frame-channel/index.js";
+import type { IntegrationCommand, IntegrationFrameId, TrackedIntegrationCommand } from "./config-helpers.js";
+export interface IntegrationManagerDeps {
+    /** Build a URL pointing to an asset file within a given package directory. */
+    buildAssetUrl: (dir: "integrations", file: string) => string;
+    /** Container element into which integration iframes are appended. */
+    container: HTMLElement;
+    /** Forward a message to the core frame channel. */
+    sendToCore: (type: string, payload: unknown) => void;
+    /** Publish a named SDK event to host-page subscribers. */
+    routePublishedEvent: (key: string, data: unknown) => void;
+    /** Deliver the current SDK config to a newly-connected integration channel. */
+    deliverConfig: (channel: FrameChannel) => void;
+    /** Resolve the absolute origin for a mounted iframe (null if unavailable). */
+    getFrameOrigin: (iframe: HTMLIFrameElement) => string | null;
+}
+/**
+ * Manages the lifecycle of integration iframes (zendesk, zendeskMessaging,
+ * oauth, csat) and the command bus that routes commands to them.
+ *
+ * Designed with constructor dependency injection so it can be tested in
+ * isolation without requiring a full `AdaMessagingClient` instance.
+ */
+export declare class IntegrationManager {
+    private readonly _deps;
+    private readonly _frames;
+    private readonly _channels;
+    private readonly _ready;
+    private readonly _loadTimers;
+    private readonly _pendingCommands;
+    private readonly _trackedCommands;
+    private readonly _trackedCommandTimers;
+    /** Terminal command ids whose eventual late receipts should be ignored. */
+    private readonly _settledCommandIds;
+    private _commandCounter;
+    private _activePlatform;
+    private _destroyed;
+    private readonly _loadHandlers;
+    constructor(deps: IntegrationManagerDeps);
+    /**
+     * Dispatch a raw integration command payload (as received from the core
+     * frame via `sdk.integration.command`). Validates, normalizes, routes to
+     * the appropriate iframe, and emits `ada:integration:command` for public
+     * integration work.
+     */
+    dispatch(rawPayload: unknown): void;
+    /**
+     * Wire the frame channel for a freshly-loaded integration iframe.
+     * Called by the SDK after the iframe's `load` event fires.
+     */
+    onFrameLoaded(frameId: IntegrationFrameId, iframe: HTMLIFrameElement): void;
+    /** Disconnect all channels, cancel all timers, and clear all state. */
+    teardown(): void;
+    /** Clear identity-bound integration state while keeping the manager reusable. */
+    resetForIdentityChange(): void;
+    private _clearRuntimeState;
+    private _ensureFrame;
+    private _mountFrame;
+    private _failPendingCommandsForFrame;
+    private _queueCommand;
+    private _removePending;
+    private _clearTracked;
+    private _rememberSettledCommandId;
+    private _trackCommand;
+    private _flush;
+    private _handleResult;
+    private _emitResult;
+    private _handleEvent;
+    /** @internal — used by client.test.ts integration buffering tests */
+    get _integrationPendingCommands(): Map<IntegrationFrameId, IntegrationCommand[]>;
+    /** @internal — used by client.test.ts integration buffering tests */
+    get _trackedIntegrationCommands(): Map<string, TrackedIntegrationCommand>;
+}

package/dist/client/legacy-callback-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { AdaSdkEventCallback } from "./client-types.js";
+export interface AdaptLegacyCallbacksOptions {
+    /** Raw `window.adaSettings` object (may contain any shape). */
+    adaSettings: Record<string, unknown>;
+    /** The `eventCallbacks` map from the constructor config (if any). */
+    constructorEventCallbacks: Record<string, AdaSdkEventCallback> | undefined;
+    /** Bound reference to `AdaMessagingClient.subscribeEvent`. */
+    subscribeEvent: (key: string, callback: AdaSdkEventCallback) => number;
+}
+export interface AdaptLegacyCallbacksResult {
+    /**
+     * The `zdChatterAuthCallback` function extracted from adaSettings, or
+     * `null` if not present / not a function.  The caller stores it separately
+     * and invokes it on demand (request-response pattern, not an event).
+     */
+    zdChatterAuthCallback: ((callback: (token: string) => void) => void) | null;
+}
+/**
+ * Registers applicable adaSettings callbacks as `subscribeEvent` subscribers
+ * and returns the extracted `zdChatterAuthCallback`.
+ */
+export declare function adaptLegacyCallbacks(options: AdaptLegacyCallbacksOptions): AdaptLegacyCallbacksResult;

package/dist/client/mask-element.d.ts

@@ -0,0 +1,19 @@
+export interface MaskElementHandle {
+    /** Drawer open/closed. The scrim renders only while open and off mobile. */
+    setOpen(isOpen: boolean): void;
+    destroy(): void;
+}
+export interface CreateMaskElementOptions {
+    /** The SDK's frame container, which also scopes teardown. */
+    container: HTMLElement;
+    /** Invoked on a scrim click or an Escape press while the scrim is showing. */
+    onDismiss: () => void;
+}
+/**
+ * The host-page scrim behind an open chat drawer, for hosts that opt in with
+ * `hideMask: false`.
+ *
+ * Mobile form factor uses legacy's page-lifetime UA signal, so `setOpen()` can
+ * render synchronously without a resize/breakpoint subscription.
+ */
+export declare function createMaskElement(options: CreateMaskElementOptions): MaskElementHandle;

package/dist/client/proactive/index.d.ts

@@ -0,0 +1,5 @@
+export type { IntroChannelDependencies } from "./proactive-channel.js";
+export { setupIntroChannelHandlers } from "./proactive-channel.js";
+export type { IntroDisplayKind, IntroShowingState, ProactiveRuntimeDependencies, } from "./proactive-runtime.js";
+export { evaluateProactiveConditionsRuntime, matchesIntroPathRuntime, onLocationChangeRuntime, openCtaUrlRuntime, scheduleIntroRuntime, } from "./proactive-runtime.js";
+export { findMatchingProactives, isProactiveShown, markProactiveShown, markProactiveShownForUser, } from "./proactive-utils.js";

package/dist/client/proactive/proactive-channel.d.ts

@@ -0,0 +1,33 @@
+import type { FrameChannel, FrameRegistry, StartupConfig } from "../../frame-channel/index.js";
+export interface IntroChannelDependencies {
+    channel: FrameChannel;
+    frames: FrameRegistry;
+    getStartupConfig: () => StartupConfig | null;
+    sendToCore: (type: string, payload: unknown) => void;
+    routePublishedEvent: (key: string, data: unknown) => void;
+    open: () => void;
+    /** Open after an exact proactive click without clearing its armed attribution. */
+    openFromProactiveEngagement?: () => void;
+    setIntroShowing: (state: "greeting" | "proactive" | null) => void;
+    getCurrentIntroSurface?: () => {
+        kind: "greeting";
+        displayId: number;
+    } | {
+        kind: "proactive";
+        campaignKey: string;
+        surfaceId: number;
+        intentId?: number;
+    } | null;
+    acknowledgeProactiveShown?: (campaignKey: string, surfaceId: number) => boolean;
+    /** Mark current-session intro metadata when an accepted proactive is removed. */
+    markIntroShown?: () => void;
+    clearCurrentIntroSurface?: () => void;
+    /** Retire an acknowledged bubble so a later open cannot publish it as opened. */
+    clearShownCampaign?: () => void;
+    /** Open a proactive bubble's branded CTA URL from the host-page context. The
+     *  intro frame is sandboxed without allow-popups, so it cannot navigate itself;
+     *  it delegates the open to the SDK running on the host page. */
+    openCtaUrl?: (url: string, openInNewTab: boolean) => void;
+}
+/** Wire all message handlers for the intro (proactive messages + greeting) frame. */
+export declare function setupIntroChannelHandlers(deps: IntroChannelDependencies): void;

package/dist/client/proactive/proactive-runtime.d.ts

@@ -0,0 +1,65 @@
+import type { FrameChannel, FrameName, FrameRegistry, StartupConfig } from "../../frame-channel/index.js";
+export type IntroShowingState = "greeting" | "proactive" | null;
+export type IntroDisplayKind = "greeting" | "proactive";
+export interface ProactiveRuntimeDependencies {
+    handle: string;
+    language?: string;
+    parentElement: HTMLElement | null;
+    /** Whether the resolved host layout currently permits launcher/intro chrome. */
+    hasFloatingWidgetChrome: boolean;
+    channels: Map<FrameName, FrameChannel>;
+    frames: FrameRegistry;
+    getAlign: () => "left" | "right";
+    getIsChatOpen: () => boolean;
+    getHasChatOpened: () => boolean;
+    getHasIntroShown: () => boolean;
+    setHasIntroShown: (shown: boolean) => void;
+    /** Mark legacy's sticky `wasIntroShown` chatter metadata fact. */
+    markIntroShown: () => void;
+    resetIntroShownForNavigation: () => void;
+    sendToCore: (type: string, payload: unknown) => void;
+    routePublishedEvent: (key: string, data: unknown) => void;
+    getStartupConfig: () => StartupConfig | null;
+    getIntroTimer: () => ReturnType<typeof setTimeout> | null;
+    setIntroTimer: (timer: ReturnType<typeof setTimeout> | null) => void;
+    getProactiveTimers: () => Set<ReturnType<typeof setTimeout>>;
+    /** Retire all pre-chat content on a real navigation. */
+    retirePreChatSurface: () => void;
+    /** Allocate the ordering token carried through SDK -> core -> SDK. */
+    beginProactiveIntent: () => number;
+    /** True while no later SDK intent or navigation has superseded this one. */
+    isCurrentProactiveIntent: (intentId: number) => boolean;
+    setIntroShowing: (state: IntroShowingState) => void;
+    getLastEvaluatedUrl: () => string;
+    setLastEvaluatedUrl: (url: string) => void;
+    /** Deliver now when intro is ready, otherwise retain only the latest display. */
+    showOrQueueIntroDisplay: (kind: IntroDisplayKind, display: () => void, onDropped?: () => void) => void;
+    /** Deliver an emoji after the button channel is ready, retaining only latest. */
+    showOrQueueEmojiDisplay: (display: () => void) => void;
+    /** Mount the card-based intro runtime once a real surface has passed its gates. */
+    ensureIntroFrame: () => void;
+    beginGreetingDisplay: () => number;
+}
+/**
+ * Open a proactive bubble's branded CTA URL. The URL round-trips through the
+ * sandboxed intro frame before reaching the host page, so re-validate the
+ * destination with the shared credential-free navigation policy before opening —
+ * never open a `javascript:`/`data:`/relative URL. `open` is
+ * injected (`window.open`) so this stays pure and unit-testable.
+ */
+export declare function openCtaUrlRuntime(url: string, openInNewTab: boolean, open: (url: string, target: string, features: string) => unknown): void;
+/** Match an intro path pattern against the current pathname. Supports trailing `*` wildcard. */
+export declare function matchesIntroPathRuntime(pattern: string, pathname: string): boolean;
+/**
+ * Schedule the intro greeting popup to display after the configured delay.
+ * Skipped when: chat has already opened, this client instance already showed it,
+ * or paths don't match.
+ */
+export declare function scheduleIntroRuntime(deps: ProactiveRuntimeDependencies, intro: NonNullable<StartupConfig["intro"]>): void;
+/** Called on every SPA navigation. Re-evaluates intro and proactive conditions. */
+export declare function onLocationChangeRuntime(deps: ProactiveRuntimeDependencies): void;
+/**
+ * Evaluate URL-triggered proactive conversation conditions.
+ * Called on every SPA location change.
+ */
+export declare function evaluateProactiveConditionsRuntime(deps: ProactiveRuntimeDependencies, ignoreFrequency?: boolean, surfaceAlreadyRetired?: boolean): boolean;

package/dist/client/proactive/proactive-utils.d.ts

@@ -0,0 +1,51 @@
+import type { StartupConfigProactiveConversation } from "../../frame-channel/types.js";
+/**
+ * Compile an admin-authored URL regex within the existing defensive length ceiling.
+ * Successful and rejected compiles share a bounded cache across SPA evaluations.
+ * Native matching remains the legacy JavaScript contract for ordinary patterns.
+ * A conservative nested-repetition family is rejected because it can freeze the
+ * host page with only a few dozen URL characters (for example, `(a+)+`). Repeated
+ * alternation fails closed for the same reason. A small fixed repeat around
+ * flat, non-alternating optional tokens remains accepted because its optional-decision
+ * count is statically capped above. This heuristic is not a complete ReDoS proof.
+ */
+export declare function compileCachedUrlRegex(source: string): RegExp | null;
+/**
+ * Match one URL trigger condition, per-type, against the host page URL — mirroring
+ * legacy's `evalUrlMatchTriggerCondition`: `ends-with` and `equals` ignore query params,
+ * while `contains` and `regex` deliberately see the full URL including query params.
+ *
+ * The two differ on trailing slashes, and NOT symmetrically:
+ * - `equals` treats one as insignificant on either side (EXP-462 — docs.ada.cx documents
+ *   `.../checkout` matching `.../checkout/`, so the matcher conforms to the docs).
+ * - `ends-with` tolerates one only on the PAGE url. A condition authored as `/checkout/`
+ *   still will not match a page ending `/checkout`. That asymmetry is legacy's and is
+ *   left alone deliberately: the docs promise nothing about slashes for `Ends With`, so
+ *   there is no documented behaviour to conform to, and stripping the condition side
+ *   needs a root guard (`"/"` would strip to `""`, which every URL ends with).
+ *
+ * An unknown type never matches, so a condition legacy cannot express (e.g.
+ * `starts-with`) cannot fire a proactive here either.
+ */
+export declare function matchesUrlTriggerCondition(type: string, condValue: string, href: string): boolean;
+interface ProactiveMatch {
+    key: string;
+    entry: StartupConfigProactiveConversation;
+}
+/** Select the final eligible unranked match, or the next ranked match. */
+export declare function findMatchingProactives(proactives: Record<string, StartupConfigProactiveConversation> | null, href: string, handle: string): ProactiveMatch[];
+/** Returns true if the proactive conversation has already been shown this session. */
+export declare function isProactiveShown(key: string, handle: string): boolean;
+/** Record that a proactive conversation has been shown this session. */
+export declare function markProactiveShown(key: string, handle: string): void;
+/**
+ * Returns true if the proactive conversation has already been shown to this user.
+ * Backed by localStorage so suppression survives tab close (once-per-user), under
+ * a key distinct from the once-per-session sessionStorage key.
+ */
+export declare function isProactiveShownForUser(key: string, handle: string): boolean;
+/** Record that a proactive conversation has been shown to this user (persists across sessions). */
+export declare function markProactiveShownForUser(key: string, handle: string): void;
+/** Record a ranked URL-triggered proactive so the next visit advances. */
+export declare function markRankedProactiveShown(key: string, handle: string): void;
+export {};

package/dist/client/sdk-error-reporter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SDK error reporter.
+ *
+ * Captures errors that originate from Ada Messaging scripts running on the
+ * host page and forwards them to the core iframe via sendToCore so that core
+ * can route them to Sentry.
+ *
+ * Filtering strategy (host-page safety):
+ *   - `error` events: when `event.filename` is non-empty, check it against our
+ *     assets origin and skip errors from customer scripts. When filename is
+ *     empty (cross-origin scripts or browser-sanitised events), we forward
+ *     unconditionally as "opaque SDK context" — we can't attribute it but it
+ *     may still reflect a crash in our code triggered by a 3rd-party call.
+ *     Note: inline scripts on the host page also produce an empty filename;
+ *     those will be forwarded but will not contain Ada stack frames and will
+ *     appear as attributionless errors in Sentry.
+ *   - `unhandledrejection` events: check the rejection's stack trace for our
+ *     assets origin; skip rejections with no stack or a stack that doesn't
+ *     reference our origin (can't attribute them to our code).
+ *   - `ada:error` CustomEvents: always ours — forwarded with full detail.
+ */
+export declare function setupSdkErrorReporter(sendToCore: (type: string, payload: unknown) => void): () => void;

package/dist/client/sdk-event-bus.d.ts

@@ -0,0 +1,116 @@
+import type { AdaSdkEventCallback, WindowInfo } from "./client-types.js";
+/**
+ * SdkEventBus — owns the pub/sub subscriber registry and getInfo() promise tracking.
+ *
+ * Responsibilities:
+ *  - subscribeEvent / unsubscribeEvent: namespace-matched event routing
+ *  - routePublishedEvent: distribute published events to matching subscribers
+ *  - requestInfo: issue sdk.info.get requests and resolve them asynchronously
+ *  - teardown: flush pending info promises and clear all state
+ */
+export declare class SdkEventBus {
+    private readonly _eventSubscribers;
+    private _nextSubscriberId;
+    private readonly _infoRequestCallbacks;
+    private readonly _infoRequestTimers;
+    private _infoRequestCounter;
+    private readonly _dataRequests;
+    /** Subscribe to an event key. Returns a stable subscription ID. */
+    subscribe(key: string, callback: AdaSdkEventCallback): number;
+    /**
+     * Subscribe to broad published events. Transcript-bearing events
+     * (`ada:message:sent` and `ada:message:received`) require exact
+     * subscribeEvent listeners and are not delivered to wildcard subscribers.
+     * Designed for bridge adapters (e.g. React Native, iOS, Android) that need to
+     * forward SDK events to native code.
+     *
+     * Returns a stable subscription ID that can be passed to unsubscribe().
+     */
+    subscribeAll(callback: (key: string, data: unknown) => void): number;
+    /** Cancel a subscription registered via subscribe() or subscribeAll(). */
+    unsubscribe(id: number): void;
+    /** Route a published event key to all matching subscribers. */
+    routePublishedEvent(key: string, data: unknown): void;
+    /** Whether a published event key would currently be observed by any subscriber. */
+    hasSubscribersFor(key: string): boolean;
+    /**
+     * Whether the exact event key has a direct subscribeEvent listener.
+     *
+     * Wildcard (`subscribeAll`) subscribers are intentionally excluded: the
+     * transcript-bearing events (`ada:message:sent`/`ada:message:received`)
+     * require an explicit per-key opt-in so conversation content is never
+     * delivered to generic event loggers that subscribe to everything.
+     */
+    hasExactSubscriberFor(key: string): boolean;
+    /**
+     * Request current window info from the core frame.
+     *
+     * `sendFn` dispatches the sdk.info.get message to core.
+     * `getFallbackInfo` provides local state if core does not respond within 5 s.
+     *
+     * The Maps exposed by `infoRequestCallbacks` and `infoRequestTimers` are
+     * passed directly to `setupCoreChannelHandlers` so the channel handler can
+     * resolve the promise without going through an additional layer.
+     */
+    requestInfo(sendFn: (type: string, payload: unknown) => void, getFallbackInfo: () => WindowInfo): Promise<WindowInfo>;
+    /**
+     * Exposed so CoreChannelDependencies can resolve and cancel info requests
+     * directly without additional indirection.
+     */
+    get infoRequestCallbacks(): Map<string, (info: WindowInfo) => void>;
+    get infoRequestTimers(): Map<string, ReturnType<typeof setTimeout>>;
+    /**
+     * Generic request/response round-trip to the core frame, modelled on
+     * {@link requestInfo}. Backs the read-only programmatic getters
+     * (getMetaFields/getConversation/getMessages). `sendFn` dispatches
+     * `messageType` with a `{ requestId }` payload; the matching `core.*.response`
+     * handler calls {@link resolveDataRequest}. If core does not respond within
+     * the timeout, the promise resolves with `fallback()` unless
+     * `timeoutErrorMessage` is set, in which case it rejects.
+     */
+    requestData<T>(sendFn: (type: string, payload: unknown) => void, messageType: string, fallback: () => T, options?: {
+        timeoutErrorMessage?: string;
+        payload?: Record<string, unknown>;
+        timeoutMs?: number;
+        reArmOnProgress?: boolean;
+        maxTotalMs?: number;
+        preserveForCoreReplacement?: boolean;
+    }): Promise<T>;
+    /** Register a bounded correlated response without sending the request. */
+    registerAckRequest<T>(fallback: () => T, options?: {
+        timeoutErrorMessage?: string;
+        timeoutMs?: number;
+        reArmOnProgress?: boolean;
+        maxTotalMs?: number;
+        preserveForCoreReplacement?: boolean;
+    }): {
+        requestId: string;
+        promise: Promise<T>;
+    };
+    /** Settle an abandoned acknowledgement through its compatibility fallback. */
+    settleUnconfirmed(requestId: string): void;
+    private _settleOnTimeout;
+    /**
+     * Re-arm requests whose response waits behind a multi-step activation. The
+     * absolute ceiling is measured from registration, so progress from another
+     * operation cannot keep a stale request alive indefinitely.
+     */
+    reArmPendingRequests(): void;
+    /** Resolve a pending requestData() promise with the core response payload. */
+    resolveDataRequest(requestId: string, data: unknown): void;
+    /** Reject a pending requestData() promise with a core-supplied error. */
+    rejectDataRequest(requestId: string, message: string): void;
+    /**
+     * Settle every pending requestData() promise. Ungated reads resolve with their
+     * fallback value; gated/programmatic reads reject with their timeout error.
+     * Used on core-frame crash (frame.error) and teardown.
+     */
+    flushDataRequests(options?: {
+        preserveForCoreReplacement?: boolean;
+    }): void;
+    /**
+     * Tear down: cancel pending info timers, resolve all pending getInfo()
+     * promises with `finalInfo` so callers don't hang, then clear all state.
+     */
+    teardown(finalInfo: WindowInfo): void;
+}

package/dist/client/service-worker-notifications.d.ts

@@ -0,0 +1 @@
+export declare function setupServiceWorkerNotificationClickHandler(onNotificationClick: () => void): (() => void) | null;

package/dist/client/url-business-events.d.ts

@@ -0,0 +1,19 @@
+interface UrlMatchCondition {
+    type: string;
+    value: string;
+}
+interface UrlTriggerCondition {
+    type: "url-match";
+    conditionsAny: UrlMatchCondition[];
+}
+export interface UrlBusinessEvent {
+    key: string;
+    value: number;
+    triggerConditions: UrlTriggerCondition[];
+}
+/** Parse the public `GET business_events/` response without trusting its shape. */
+export declare function parseUrlBusinessEvents(payload: unknown): UrlBusinessEvent[];
+/** Return every event with ANY matching URL trigger, matching legacy Embed2. */
+export declare function getMatchingUrlBusinessEvents(events: UrlBusinessEvent[], href: string): UrlBusinessEvent[];
+export declare function fetchUrlBusinessEvents(endpoint: string, fetcher?: typeof globalThis.fetch, signal?: AbortSignal): Promise<UrlBusinessEvent[]>;
+export {};