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

package/README.md

@@ -0,0 +1,211 @@
+# @ada-cx/messaging-sdk
+
+TypeScript types, test mocks, and a thin loader for the Ada Messaging SDK.
+
+This package never contains the SDK runtime. The loader imports the runtime
+from Ada's CDN at page load. Ada ships runtime fixes to the CDN, and every
+page receives them on the next load. This is the same model as
+`@stripe/stripe-js`.
+
+## Install
+
+```sh
+npm install @ada-cx/messaging-sdk
+```
+
+## Quick start
+
+Call `loadAdaMessaging` with your bot handle. It loads the runtime, creates
+the messaging interface, starts the widget, and returns the interface.
+
+```ts
+import { loadAdaMessaging } from "@ada-cx/messaging-sdk";
+
+// Module scope: your code holds the only reference.
+const ada = await loadAdaMessaging({ handle: "my-bot" });
+```
+
+`loadAdaMessaging` never assigns the interface to `window` or any other
+global. Keep the returned reference in module scope, where only your own code
+can reach it. A global is reachable by every script on the page. The
+`createAdaEmbedInterface` export exists only as the legacy `window.adaEmbed`
+compat facade for pages migrating from the script-tag setup.
+
+Use `loadMessagingSdk` when you want the runtime module without starting a
+widget, for example to preload it before the widget is needed:
+
+```ts
+import { loadMessagingSdk } from "@ada-cx/messaging-sdk";
+
+const sdkModule = await loadMessagingSdk();
+```
+
+`loadMessagingSdk` memoizes the in-flight import. Concurrent calls share one
+load. Both loaders reject a failed load with a `MessagingSdkLoadError` and
+permit a retry:
+
+```ts
+import { MessagingSdkLoadError } from "@ada-cx/messaging-sdk";
+
+try {
+	await loadAdaMessaging({ handle: "my-bot" });
+} catch (error) {
+	if (error instanceof MessagingSdkLoadError) {
+		console.error(error.code); // "invalid_cdn_base" | "invalid_build_sha" | "unstamped_build_sha" | "sdk_import_failed" | "sdk_module_invalid"
+	}
+}
+```
+
+## One widget per page
+
+Only one messaging interface can run on a page, and `loadAdaMessaging`
+enforces this for you. Repeated calls return the same memoized promise and
+resolve to the same started interface. The first call's settings win, and
+later calls never start a second widget. When a later call passes different
+settings, the loader logs a console warning and ignores the new settings.
+The call is therefore safe in code that runs more than once, such as React
+Strict Mode development effects. You do not need to cache the promise
+yourself.
+
+A failed load or start clears the memo, so a later call can retry.
+
+Control the widget lifecycle through the returned interface. `ada.stop()`
+tears the widget down, and a later `ada.start(settings)` on the same
+interface starts it again. A `loadAdaMessaging` call after `stop()` returns
+the same stopped interface. It does not restart the widget. The loader logs
+a console warning when it returns a stopped interface, so call
+`start(settings)` on that interface to run the widget again.
+
+## Module formats
+
+The package ships ESM and CommonJS builds of both entries. Bundlers and
+ESM runtimes use the `import` condition. Jest and other CommonJS runners
+use the `require` condition. TypeScript resolves both entries under
+`moduleResolution` `bundler`, `node16`, and the legacy `node10` setting.
+
+## Types
+
+Import any public type directly. Type imports add zero runtime code.
+
+```ts
+import type {
+	AdaMessagingInterface,
+	AdaMessagingSettings,
+	AdaMessagingStartOptions,
+	PublicMessage,
+	ResetParams,
+} from "@ada-cx/messaging-sdk";
+```
+
+`AdaMessagingInterface` is the interface `loadAdaMessaging` resolves. The
+`AdaEmbedInterface` name remains available as its legacy alias.
+
+Runtime symbols such as `AdaMessagingClient` and `createAdaEmbedInterface`
+are exported as types only. Get their implementations from
+`loadMessagingSdk()`. `createAdaEmbedInterface` exists for migrations from
+the legacy `window.adaEmbed` contract; new integrations use
+`loadAdaMessaging`.
+
+## Testing your integration
+
+The `./testing` entry provides an in-memory mock of the messaging interface.
+Your unit tests never touch the CDN.
+
+```ts
+import { createMockAdaMessaging } from "@ada-cx/messaging-sdk/testing";
+
+const ada = createMockAdaMessaging();
+
+await ada.sendMessage("hello");
+expect(ada.calls).toContainEqual({
+	method: "sendMessage",
+	args: ["hello"],
+});
+
+// Simulate an SDK event for your subscribers.
+await ada.subscribeEvent("ada:conversation:message", onMessage);
+ada.$emit("ada:conversation:message", { message_id: "m1" });
+```
+
+The mock records every call in `calls`. It keeps light state: sent messages
+appear in `getMessages()`, and `open`/`close` drive `isOpen()`. Pass
+overrides to replace any method with your own spy:
+
+```ts
+const ada = createMockAdaMessaging({ getMessages: vi.fn(async () => []) });
+```
+
+## Bundler note
+
+The loader imports the runtime with a fully dynamic URL. The import is
+pre-annotated with `/* webpackIgnore: true */` and `/* @vite-ignore */`, so
+webpack and Vite leave it for the browser to resolve. Do not copy the import
+into your own code without those annotations. If your bundler still rewrites
+dynamic imports, configure it to ignore imports of `https:` URLs.
+
+## Versioning and staging validation
+
+The npm version covers only the loader, the types, and the mocks. It never
+pins the runtime. The runtime always resolves from Ada's CDN rollout at page
+load.
+
+To validate a specific runtime build on any page, add the
+`?ada-messaging-version=<version>` query parameter to the page URL. The value
+accepts a `pr-<N>` preview build or a git SHA from a main build. An invalid
+or unavailable value falls back to the stable rollout.
+
+To validate against a different asset host, pass its root to the loader. Ada
+gives you the host value when you arrange a preproduction validation:
+
+```ts
+await loadAdaMessaging(
+	{ handle: "my-bot" },
+	{ cdnBase: "<ada-provided-asset-host>" },
+);
+```
+
+Use `cdnBase` for staging validation only. Production pages must keep the
+default.
+
+### Pin the CDN build
+
+The package exports `CDN_BUILD_SHA`. The value is the git commit SHA of the
+monorepo commit this npm version was published from. Ada deploys each
+commit's runtime under an immutable SHA root on the CDN. The value therefore
+names the CDN build associated with this npm version.
+
+Pass the SHA as the `pinBuildSha` loader option. The loader then skips the
+rollout bootstrap and imports that build's immutable entry,
+`<cdnBase>/<sha>/sdk/index.js`, directly:
+
+```ts
+import {
+	CDN_BUILD_SHA,
+	isCdnBuildShaStamped,
+	loadAdaMessaging,
+} from "@ada-cx/messaging-sdk";
+
+if (isCdnBuildShaStamped()) {
+	await loadAdaMessaging({ handle: "my-bot" }, { pinBuildSha: CDN_BUILD_SHA });
+}
+```
+
+**Pinning is not recommended for production.** A pinned runtime misses Ada's
+fixes and rollouts. A pinned runtime can also predate later server contract
+changes and stop working. Use a pin only to debug an issue, to validate a
+staged build, or to reproduce a report against a known runtime.
+
+The option accepts any full 40-character hex git SHA of a deployed main
+build. The loader rejects any other value with the `invalid_build_sha` error
+code. Only published packages carry a real SHA. In the repository, and in a
+locally built copy, `CDN_BUILD_SHA` is a 40-zero placeholder and
+`isCdnBuildShaStamped()` returns `false`. The loader rejects the placeholder
+with the `unstamped_build_sha` error code.
+
+The npm publish and the CDN deploy of the same commit run in parallel. In
+the first minutes after a release, a pin can fail with `sdk_import_failed`
+until the deploy completes. If the deploy of that commit failed, the pinned
+build never exists. The unpinned default is unaffected in both cases.
+
+`pinBuildSha` composes with `cdnBase`. The pinned entry resolves under the
+asset host you pass.

package/dist/client/ada-settings-reader.d.ts

@@ -0,0 +1,10 @@
+import type { AdaMessagingClientConfig } from "./client-types.js";
+/**
+ * Reads `window.adaSettings` and maps recognised fields to
+ * `AdaMessagingClientConfig`.  All field access is defensive — unknown types
+ * are silently ignored so that a mal-formed host page cannot crash the SDK.
+ *
+ * Priority rule: the constructor config always wins.  This module only
+ * supplies fallback values that the constructor has not explicitly set.
+ */
+export declare function readAdaSettings(): Partial<AdaMessagingClientConfig>;

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

@@ -0,0 +1,92 @@
+import type { FrameChannel, FrameName, FrameRegistry, FrameToSdkEvents, StartupConfig } from "../frame-channel/index.js";
+import type { AdaSdkEventCallback, WindowInfo } from "./client-types.js";
+interface BaseChannelDependencies {
+    channels: Map<FrameName, FrameChannel>;
+    frames: FrameRegistry;
+    parentElement: HTMLElement | null;
+    getAlign: () => "left" | "right";
+    open: () => void;
+}
+export interface ProactiveDisplayRequest {
+    campaignKey: string | null;
+    surfaceId: number;
+    triggerMethod?: "url" | "programmatic";
+    displayDelay?: number;
+    frequency?: "always" | "session" | "user";
+    intentId?: number;
+}
+export interface CoreChannelDependencies extends BaseChannelDependencies {
+    channel: FrameChannel;
+    config: {
+        handle: string;
+        language?: string;
+        headless?: boolean;
+        rolloutOverride?: number;
+        sensitiveMetaFields?: Record<string, unknown>;
+        styles?: Record<string, string>;
+        eventCallbacks?: Record<string, AdaSdkEventCallback>;
+    };
+    deliverConfig: (channel: FrameChannel) => void;
+    close: (reason?: "close" | "minimize") => void;
+    destroy: () => void;
+    routePublishedEvent: (key: string, data: unknown) => void;
+    invokeWindowCallback: (name: string, ...args: unknown[]) => void;
+    dispatchIntegrationCommand: (payload: unknown) => void;
+    startVoiceRecording: () => void;
+    stopVoiceRecording: () => void;
+    setVoiceLanguage: (language: string) => void;
+    setVoiceMode: (mode: "push-to-talk" | "toggle") => void;
+    setStartupConfig: (config: StartupConfig) => void;
+    getStartupConfig: () => StartupConfig | null;
+    getIsChatOpen: () => boolean;
+    getWindowInfo: () => WindowInfo;
+    scheduleIntro: (intro: NonNullable<StartupConfig["intro"]>) => void;
+    /** Evaluate URL-triggered proactive conversations for the current page. */
+    evaluateProactive: () => void;
+    /** Schedule or immediately deliver one resolved proactive display. */
+    showProactive: (request: ProactiveDisplayRequest, display: () => void) => void;
+    beginProactiveDisplay: (campaignKey: string, surfaceId: number, intentId?: number) => void;
+    isProactiveClearPending: () => boolean;
+    acknowledgeProactiveClear: (requestId: number) => void;
+    clearProactiveFromCore: () => void;
+    incrementUnreadCount: () => number;
+    setHasActiveChatter: (value: boolean) => void;
+    setChatterToken: (chatterToken: string) => boolean | undefined;
+    setChatterCandidate: (candidate: FrameToSdkEvents["core.chatter.candidate"]) => void;
+    handleSessionResumeResult: (result: FrameToSdkEvents["core.session.resume.result"]) => void;
+    handleSessionResumeVisibilityResult: (result: FrameToSdkEvents["core.session.resume.visibility.result"]) => void;
+    clearIdentityToken: () => void;
+    markIdentityTokenConsumed?: (chatterToken?: string) => void;
+    markIdentityTokenFailed?: () => void;
+    setPersistenceMode?: (mode: "normal" | "session" | "private") => void;
+    setCrossWindowLiveChatActive: (value: boolean) => void;
+    setSensitiveMetaFields: (fields: Record<string, unknown>) => void;
+    setHostViewportExpanded: (expanded: boolean) => void;
+    /** Run host-side work that must wait until the replacement core has prepared. */
+    onCoreReady?: () => void;
+    /** Claim reset ordering as soon as Core's SDK router is installed. */
+    onCoreProtocolReady?: () => void;
+    infoRequestCallbacks: Map<string, (info: WindowInfo) => void>;
+    infoRequestTimers: Map<string, ReturnType<typeof setTimeout>>;
+    resolveDataRequest: (requestId: string, data: unknown) => void;
+    rejectDataRequest: (requestId: string, message: string) => void;
+    flushDataRequests: (options?: {
+        preserveForCoreReplacement?: boolean;
+    }) => void;
+    getZdChatterAuthCallback: () => ((callback: (token: string) => void) => void) | null;
+}
+export interface ButtonChannelDependencies {
+    channel: FrameChannel;
+    frames: FrameRegistry;
+    deliverConfig: (channel: FrameChannel) => void;
+    open: () => void;
+    setLastOpenedViaKeyboard: (value: boolean) => void;
+    /** Needed to re-anchor a showing proactive bubble when the launcher resizes. */
+    getAlign: () => "left" | "right";
+    getIsChatOpen: () => boolean;
+}
+/** Wire all message handlers for the core (headless business logic) frame. */
+export declare function setupCoreChannelHandlers(deps: CoreChannelDependencies): () => void;
+/** Wire all message handlers for the button (chat trigger) frame. */
+export declare function setupButtonChannelHandlers(deps: ButtonChannelDependencies): void;
+export {};

package/dist/client/client-errors.d.ts

@@ -0,0 +1,7 @@
+type AdaEmbedErrorCode = "start_already_active" | "start_interrupted" | "start_owner_conflict";
+/** Legacy-compatible public error shape for host SDK lifecycle failures. */
+export declare class AdaEmbedError extends Error {
+    readonly code?: AdaEmbedErrorCode;
+    constructor(message: string, code?: AdaEmbedErrorCode);
+}
+export {};

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

@@ -0,0 +1,41 @@
+import type { FrameName } from "../frame-channel/index.js";
+/** Default frame HTML files relative to their package asset path */
+export declare const FRAME_SOURCES: Record<FrameName, string>;
+/**
+ * Which built package each frame's HTML ships from. `core`/`button` are plain
+ * vanilla-JS frames in `packages/sdk/public`. `intro` renders the Lovelace
+ * `ProactiveMessage` design-system component, so it lives in `packages/integrations`
+ * (React is banned in `sdk` — see `.claude/rules/architecture.md`).
+ */
+export declare const FRAME_PACKAGES: Record<FrameName, "sdk" | "integrations">;
+/**
+ * The accessible name a screen reader reads when it reaches each frame from the
+ * host page (axe `frame-title`, WCAG 4.1.2). Applied on mount for every frame, so
+ * a new frame cannot ship unnamed.
+ *
+ * Untranslated, like the launcher's name has always been: the SDK mounts frames
+ * before any locale is resolved, and these read on the host page rather than
+ * inside the chat.
+ */
+export declare const FRAME_TITLES: Record<FrameName, string>;
+/**
+ * One name for every integration runtime. They are headless and permanently 0×0, so
+ * a reader never lands in one and there is nothing to tell them apart by.
+ */
+export declare const INTEGRATION_FRAME_TITLE = "Ada Chat Integration";
+/**
+ * Least-privilege sandbox policies per top-level frame.
+ *
+ * - core must permit forms/popups/downloads because it hosts the nested app
+ *   iframe, which supports transcript downloads and outbound legal/support links.
+ *   `allow-popups-to-escape-sandbox` is required so those popups load as normal,
+ *   unsandboxed tabs — without it, a popup opened from a sandboxed frame stays
+ *   sandboxed, and Chrome blocks the navigation outright when the target site
+ *   sets a Cross-Origin-Opener-Policy header (EXP-268).
+ * - button/intro are utility frames and do not require forms/popups.
+ */
+export declare const FRAME_SANDBOX_POLICIES: Record<FrameName, string>;
+export declare const ASSET_QUERY_HANDLE_KEY = "ada_handle";
+export declare const ASSET_QUERY_CLUSTER_KEY = "ada_cluster";
+/** Frame load timeout in milliseconds — see constants.ts for the canonical value */
+export { FRAME_LOAD_TIMEOUT_MS } from "./constants.js";

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

@@ -0,0 +1,54 @@
+import type { FrameName, FrameRegistry } from "../frame-channel/index.js";
+import { FrameChannel } from "../frame-channel/index.js";
+export interface BuildAssetUrlRuntimeOptions {
+    packageName: "sdk" | "integrations";
+    path: string;
+    handle: string;
+    cluster: string;
+    assetsOrigin: string;
+    commitSha?: string;
+}
+export declare function buildAssetUrlRuntime(options: BuildAssetUrlRuntimeOptions): string;
+/**
+ * Recover the CDN base that buildAssetUrlRuntime expects (origin + any path
+ * prefix such as "/messaging" for the static.ada.support root) from the running
+ * SDK module's own URL. Deployed assets live at `<base>/<sha>/sdk/index.js`, so
+ * the base is the path up to (and including the slash before) the `<sha>`
+ * segment. Using `new URL(metaUrl).origin` would drop a path prefix and break the
+ * static.ada.support/messaging/ root for frame URLs. Falls back to the baked
+ * origin in dev (or any case where the `<sha>` segment isn't in the path, or
+ * metaUrl can't be parsed as http(s) — e.g. an opaque blob origin).
+ */
+export declare function resolveAssetsOriginRuntime(metaUrl: string, commitSha: string | undefined, fallbackOrigin: string): string;
+export interface MountFrameRuntimeOptions {
+    name: FrameName;
+    options: {
+        style: string;
+    };
+    container: HTMLElement | null;
+    frames: FrameRegistry;
+    loadTimers: Map<string, ReturnType<typeof setTimeout>>;
+    buildAssetUrl: (packageName: "sdk" | "integrations", path: string) => string;
+    onFrameTimeout: (name: FrameName, message: string) => void;
+    onFrameLoaded: (name: FrameName, iframe: HTMLIFrameElement) => void;
+}
+/**
+ * Create an iframe, append it to the container, and set up
+ * a FrameChannel once it loads.
+ */
+export declare function mountFrameRuntime(options: MountFrameRuntimeOptions): void;
+export interface OnFrameLoadedRuntimeOptions {
+    name: FrameName;
+    iframe: HTMLIFrameElement;
+    channels: Map<FrameName, FrameChannel>;
+    getFrameOrigin: (frame: HTMLIFrameElement) => string | null;
+    setupCoreChannel: (channel: FrameChannel) => void;
+    setupButtonChannel: (channel: FrameChannel) => void;
+    setupIntroChannel: (channel: FrameChannel) => void;
+}
+/**
+ * Called when an iframe has loaded. Creates a FrameChannel, wires origin
+ * locking and error reporting (shared for all frames), then delegates
+ * per-frame channel setup.
+ */
+export declare function onFrameLoadedRuntime(options: OnFrameLoadedRuntimeOptions): void;

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

@@ -0,0 +1,73 @@
+import type { FrameChannel } from "../frame-channel/index.js";
+import type { ClearPersistenceAckResponseType } from "../frame-channel/types.js";
+import type { HostTelemetryContext } from "../host-telemetry.js";
+import type { AdaSdkEventCallback } from "./client-types.js";
+export interface DeliverConfigRuntimeOptions {
+    handle: string;
+    cluster: string | null;
+    endpoint: string;
+    language?: string;
+    greeting?: string;
+    configuredGreetingResponseId?: string;
+    identityToken?: string;
+    greetingResponseId?: string | null;
+    metaFields?: Record<string, unknown>;
+    sensitiveMetaFields?: Record<string, unknown>;
+    allowMetaFieldsInReset?: boolean;
+    enableProgrammaticControl?: boolean;
+    /** Customer-hosted app frame URL (already normalized to https). */
+    appUrl?: string;
+    appUrlFallback?: boolean;
+    hostTelemetry?: HostTelemetryContext;
+    styles?: Record<string, string>;
+    theme?: "light" | "dark" | "auto";
+    testMode?: boolean;
+    privateMode?: boolean;
+    isParentElementMode?: boolean;
+    isMobileViewport?: boolean;
+    hideDefaultHeader?: boolean;
+    clearPersistenceOnPrepare?: boolean;
+    clearPersistenceAckRequestId?: string;
+    clearPersistenceAckResponseType?: ClearPersistenceAckResponseType;
+    clearPersistenceStorageModes?: Array<"normal" | "session" | "private">;
+    /** Sticky SDK-owned fact matching legacy Embed2 `wasIntroShown`. */
+    introShown?: boolean;
+}
+/** Send the client configuration to a frame. */
+export declare function deliverConfigRuntime(channel: FrameChannel, config: DeliverConfigRuntimeOptions): void;
+/** Safely invoke a window-level callback if it exists and is a function. */
+export declare function invokeWindowCallbackRuntime(name: string, ...args: unknown[]): void;
+export type EventSubscriber = {
+    key: string;
+    wildcard?: false;
+    callback: AdaSdkEventCallback;
+} | {
+    key: "*";
+    wildcard: true;
+    callback: (key: string, data: unknown) => void;
+};
+export declare function subscriberMatchesEventKeyRuntime(subscriber: EventSubscriber, key: string): boolean;
+/** Route a published event key to all matching subscribeEvent subscribers. */
+export declare function routePublishedEventRuntime(subscribers: Map<number, EventSubscriber>, key: string, data: unknown): void;
+export interface LocationHistoryRuntimeState {
+    origPushState: typeof history.pushState | null;
+    origReplaceState: typeof history.replaceState | null;
+    locationChangeHandler: (() => void) | null;
+    popstateHandler: (() => void) | null;
+}
+export declare const EMPTY_LOCATION_HISTORY_STATE: LocationHistoryRuntimeState;
+/** Share the page-owned scroll lock across defensive or nested callers. */
+export declare function acquireDocumentScrollLockRuntime(): void;
+/** Release one caller's ownership and restore only after the final owner. */
+export declare function releaseDocumentScrollLockRuntime(): void;
+/**
+ * Patch history.pushState / replaceState and listen to popstate so that
+ * single-page-app navigation fires a synthetic "ada:locationchange" event.
+ *
+ * Uses module-level ref counting so defensive concurrent callers share one
+ * patch and one native popstate listener; the originals are only restored when
+ * the last caller unpatches.
+ */
+export declare function patchLocationHistoryRuntime(state: LocationHistoryRuntimeState, onLocationChange: () => void): LocationHistoryRuntimeState;
+/** Restore original history methods and remove location listeners. */
+export declare function unpatchLocationHistoryRuntime(state: LocationHistoryRuntimeState): LocationHistoryRuntimeState;