@ada-support/embed2 1.13.6 → 1.14.4

package/README.md

@@ -1,6 +1,6 @@
 # Embed 2
 
-Embed 2 allows clients to setup Ada Web Chat in their web application. For further information on how to use Embed, check out our [documentation](https://developers.ada.cx/reference/add-chat-to-website).
+Embed 2 allows clients to setup Ada Web Chat in their web application. For further information on how to use Embed, check out our [documentation](https://docs.ada.cx/chat/web/getting-started).
 
 ## 1. Installation
 
@@ -34,4 +34,4 @@ adaEmbed.start({
 });
 ```
 
-In the example above the `handle` key is a part of `AdaSettings`. To learn more about other settings, consult the [API reference](https://developers.ada.cx/reference/embed2-reference).
+In the example above the `handle` key is a part of `AdaSettings`. To learn more about other settings, consult the [API reference](https://docs.ada.cx/chat/web/sdk-api-reference).

package/dist/npm-entry/client/components/ChatFrame/chatFrameEvents/chatterEvent/index.d.ts

@@ -1,3 +1,8 @@
 import type { Client } from "common/models/client";
+import type { AdaCluster } from "common/types";
 import type { MessagePayload } from "common/types/events";
-export declare function storeChatterEventDataInBrowser(client: Client, payload: MessagePayload): void;
+export declare function storeChatterEventDataInBrowser(client: Client, payload: MessagePayload, { cluster, domain, privateMode, }?: {
+    cluster?: AdaCluster;
+    domain?: string;
+    privateMode?: boolean;
+}): void;

package/dist/npm-entry/client/components/Container/host-facing-meta-fields.d.ts

@@ -0,0 +1,5 @@
+import type { PayloadByEvent } from "common/lib/channel";
+/** Strips the internal `proactive_conversation` tracker for getMetaFields(). */
+export declare function toHostFacingMetaFields(metaFields: Record<string, unknown> | undefined): PayloadByEvent["GET_META_FIELDS_RESPONSE"];
+/** Merges a proactive_conversation key onto existing metaFields. */
+export declare function withProactiveKey(metaFields: Record<string, unknown> | undefined, key: string): Record<string, unknown>;

package/dist/npm-entry/client/embed.d.ts

@@ -10,6 +10,7 @@ export declare function createEmbed(adaSettings: StartOptions): {
     readonly adaSettings: StartOptions;
     readonly getInfo: () => Promise<WindowInfo>;
     readonly setMetaFields: (options: MetaFieldPayload) => Promise<void>;
+    readonly getMetaFields: () => Promise<MetaFieldPayload>;
     readonly setSensitiveMetaFields: (options: MetaFieldPayload) => Promise<void>;
     readonly stop: () => Promise<void>;
     readonly deleteHistory: () => Promise<void>;

package/dist/npm-entry/common/constants/events.d.ts

@@ -59,6 +59,8 @@ export declare const GET_INFO = "GET_INFO";
 export declare const GET_INFO_RESPONSE = "GET_INFO_RESPONSE";
 export declare const SET_META_FIELDS = "SET_META_FIELDS";
 export declare const SET_META_FIELDS_RESPONSE = "SET_META_FIELDS_RESPONSE";
+export declare const GET_META_FIELDS = "GET_META_FIELDS";
+export declare const GET_META_FIELDS_RESPONSE = "GET_META_FIELDS_RESPONSE";
 export declare const STOP = "STOP";
 export declare const STOP_RESPONSE = "STOP_RESPONSE";
 export declare const DELETE_HISTORY = "DELETE_HISTORY";

package/dist/npm-entry/common/helpers/host-telemetry.d.ts

@@ -3,6 +3,7 @@ export type HostTelemetrySurface = "mobile" | "browser";
 export type HostTelemetryPlatform = "ios" | "android" | "react-native" | "web" | "unknown";
 export type HostTelemetryWebSdkOrigin = "legacy" | "messaging";
 export type HostTelemetryMobileShell = "messaging-sdk" | "legacy-sdk";
+export type HostTelemetryMode = "headless" | "visible";
 export interface HostTelemetryContext {
     surface: HostTelemetrySurface;
     hostPlatform: HostTelemetryPlatform;
@@ -10,6 +11,13 @@ export interface HostTelemetryContext {
     mobileShell?: HostTelemetryMobileShell;
     mobilePackage?: string;
     mobileVersion?: string;
+    /**
+     * MES-981 P1 #10: distinguishes SDK-driven headless sessions from
+     * sessions with a visible chat surface. Tagged on every log/RUM line
+     * emitted through `setGlobalLogContext(toMonitoringContext(...))` so
+     * dashboards can filter by mode without a separate event.
+     */
+    mode?: HostTelemetryMode;
 }
 export declare const HOST_TELEMETRY_QUERY_PARAM = "ada_host_telemetry";
 type StartOptionsWithHostTelemetry = StartOptions & {

package/dist/npm-entry/common/helpers/messaging-auth-state.d.ts

@@ -0,0 +1,34 @@
+import type { AdaCluster } from "common/types";
+export interface MessagingAuthState {
+    messagingToken: string;
+    messagingTokenExpiresAt: number;
+    sessionRefreshToken: string;
+    refreshGeneration: number;
+}
+type MessagingAuthStatePersistence = "normal" | "session" | "private" | string | null | undefined;
+declare const MESSAGING_AUTH_STATE_STORAGE_KEY: "messagingAuthState";
+export declare function buildMessagingAuthStateStorageKey({ handle, cluster, domain, }: {
+    handle: string | null | undefined;
+    cluster?: AdaCluster;
+    domain?: string;
+}): typeof MESSAGING_AUTH_STATE_STORAGE_KEY | null;
+export declare function parseMessagingAuthState(value: unknown): MessagingAuthState | null;
+export declare function readMessagingAuthStateFromStorage({ handle, cluster, domain, }: {
+    handle: string | null | undefined;
+    cluster?: AdaCluster;
+    domain?: string;
+}): MessagingAuthState | undefined;
+export declare function writeMessagingAuthStateToStorage({ handle, cluster, domain, persistence, state, }: {
+    handle: string | null | undefined;
+    cluster?: AdaCluster;
+    domain?: string;
+    persistence: MessagingAuthStatePersistence;
+    state: MessagingAuthState | null | undefined;
+}): boolean;
+export declare function clearAllMessagingAuthStatesFromStorage(): void;
+export declare function clearMessagingAuthStateFromStorage({ handle, cluster, domain, }: {
+    handle: string | null | undefined;
+    cluster?: AdaCluster;
+    domain?: string;
+}): void;
+export {};

package/dist/npm-entry/common/helpers/programmatic-control.d.ts

@@ -0,0 +1,5 @@
+import { AdaEmbedError } from "common/helpers/errors";
+export declare const PROGRAMMATIC_CONTROL_DISABLED_ERROR: AdaEmbedError;
+export declare function isProgrammaticControlEnabled(adaSettings: object | undefined | null): boolean;
+export declare function requireProgrammaticControl(adaSettings: object | undefined | null): void;
+export declare function shouldDeliverTranscriptEvent(eventKey: string, adaSettings: object | undefined | null): boolean;

package/dist/npm-entry/common/helpers/with-timeout.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Race `promise` against a timeout. If the timeout fires first, reject
+ * with an AdaEmbedError carrying `errorMessage`. If the promise settles
+ * first (resolve or reject), clear the pending timer so it doesn't
+ * keep the event loop alive past resolution.
+ *
+ * MES-981 P1 #7: used to cap host-supplied beforeSend hooks so a
+ * never-resolving delegate can't hang sendMessage forever.
+ */
+export declare function withTimeout<T>(promise: PromiseLike<T> | T, ms: number, errorMessage: string): Promise<T>;

package/dist/npm-entry/common/lib/channel.d.ts

@@ -15,7 +15,10 @@ export interface EmbedRequestPayloadByEvent {
     DISPATCH: StoreDispatchPayload;
     EVAL_CAMPAIGN_CONDITIONS: CampaignParams;
     GET: StoreGetPayload;
+    GET_CONVERSATION: unknown;
     GET_INFO: unknown;
+    GET_MESSAGES: unknown;
+    GET_META_FIELDS: unknown;
     GET_STATE: unknown;
     RESET: ResetParams;
     SET_META_FIELDS: MetaFieldPayload;
@@ -34,6 +37,12 @@ export interface EmbedRequestPayloadByEvent {
     SET_LANGUAGE: {
         language: string;
     };
+    SET_COMPOSER_TEXT: {
+        text: string;
+    };
+    SEND_MESSAGE: {
+        text: string;
+    };
     TRIGGER_PROACTIVE: TriggerProactiveParams;
     INJECT_PROACTIVE_CONVERSATION: {
         key: string;
@@ -51,8 +60,42 @@ export interface EmbedResponsePayloadByEvent {
     "DISPATCH_RESPONSE": StoreState;
     "EVAL_CAMPAIGN_CONDITIONS_RESPONSE": unknown;
     "GET_RESPONSE": StoreState[keyof StoreState];
+    "GET_CONVERSATION_RESPONSE": {
+        id: string | null;
+        handoff: {
+            inLiveChat: boolean;
+            agent?: {
+                id: string;
+                name: string;
+                avatarUrl?: string;
+            };
+        };
+    };
     "GET_INFO_RESPONSE": unknown;
+    "GET_MESSAGES_RESPONSE": Array<{
+        id: string;
+        role: "user" | "bot" | "agent";
+        type: string;
+        body?: string;
+        createdAt: number;
+        agent?: {
+            id: string;
+            name: string;
+            avatarUrl?: string;
+        };
+    }>;
+    "GET_META_FIELDS_RESPONSE": MetaFieldPayload;
     "GET_STATE_RESPONSE": StoreState;
+    "SEND_MESSAGE_RESPONSE": {
+        id: string;
+    } | {
+        error: string;
+    };
+    "SET_COMPOSER_TEXT_RESPONSE": {
+        ok: true;
+    } | {
+        error: string;
+    };
     "GREETING": unknown;
     "JWT_AUTH_RESPONSE": unknown;
     "RESET_RESPONSE": unknown;

package/dist/npm-entry/common/types/extended-api.d.ts

@@ -0,0 +1,191 @@
+import type { AdaEmbedAPI, AdaEventContext, AdaEventKey, AdaEventSubscriptionCallback, StartOptions } from "@ada-support/embed-types";
+import type { MetaFieldPayload } from "common/types/store";
+/**
+ * MES-981: new ada:* event keys + their payload shapes, added alongside
+ * the existing `@ada-support/embed-types` `AdaEventDataKeyedByEvent` union.
+ * Once the upstream package is updated these are folded back in and this
+ * file goes away.
+ */
+export interface ExtendedAdaEventDataKeyedByEvent {
+    /**
+     * MES-981 P1 #10: tagged with `mode` so downstream consumers can
+     * distinguish between visible-drawer sessions and SDK-driven headless
+     * sessions.
+     */
+    "ada:ready": {
+        mode: "headless" | "visible";
+    };
+    "ada:message:sent": {
+        message: Message;
+    };
+    "ada:message:received": {
+        message: Message;
+    };
+    "ada:typing:start": {
+        agentId: string;
+    };
+    "ada:typing:stop": {
+        agentId: string;
+    };
+    "ada:connection:change": {
+        state: "connected" | "reconnecting" | "disconnected";
+    };
+    "ada:conversation:change": {
+        id: string;
+    };
+}
+export type ExtendedAdaEventKey = AdaEventKey | keyof ExtendedAdaEventDataKeyedByEvent;
+/**
+ * MES-981: forward-compatible start options that include the new
+ * MES-981 flags. The flags are consumed at runtime by `embed-2`; the
+ * type augmentation here lets host pages set them without a type error
+ * while the upstream `@ada-support/embed-types` package is being updated.
+ */
+export type ExtendedStartOptions = StartOptions & {
+    /** Loads chat without rendering the default button/drawer. */
+    headless?: boolean;
+    /**
+     * Opt-in to the programmatic transcript-bearing surface introduced by
+     * MES-981: `sendMessage`, `setComposerText`, `getMessages`, `setDelegate`,
+     * and the `ada:message:sent` / `ada:message:received` events.
+     *
+     * Defaults to `false`. While the flag is off the methods reject with an
+     * explicit error and the events are not delivered to host subscribers,
+     * because every script that lives in the host page (analytics, GTM, ad
+     * pixels, session replay tools, supply-chain XSS) inherits the host's
+     * trust — and the host site's product/security team should explicitly
+     * accept the transcript-exposure risk before that capability is reachable.
+     */
+    enableProgrammaticControl?: boolean;
+};
+/**
+ * Local augmentation of the public AdaEmbedAPI surface for methods that are
+ * being rolled out via MES-981 ahead of a matching release of
+ * @ada-support/embed-types. Once those types are published, the methods below
+ * should be moved into the upstream interface and this file can be removed.
+ */
+export interface ExtendedAdaEmbedAPI extends AdaEmbedAPI {
+    /**
+     * MES-981: widened start() overload that accepts the new ExtendedStartOptions
+     * (`headless`, `enableProgrammaticControl`) without requiring an `as`
+     * cast at the call site. Returns void to match the upstream signature.
+     */
+    start(adaSettings: ExtendedStartOptions): Promise<void>;
+    /**
+     * Convenience accessor for whether the chat drawer is currently open.
+     * Equivalent to `(await getInfo()).isChatOpen`.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`.
+     *
+     * @example
+     * if (await adaEmbed.isOpen()) {
+     *   // chat is visible
+     * }
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Returns the metaFields currently held in embed-2's state. Reflects the
+     * value initially passed to `start({ metaFields })` plus any subsequent
+     * `setMetaFields` updates. Sensitive metaFields are deliberately not
+     * exposed.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`.
+     */
+    getMetaFields(): Promise<MetaFieldPayload>;
+    /**
+     * Pre-fills the chat composer input with `text` without sending it.
+     * The value can still be edited or cleared by the end user.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`,
+     * or with an `AdaEmbedError` if the chat frame is not yet ready.
+     */
+    setComposerText(text: string): Promise<void>;
+    /**
+     * Returns metadata about the current conversation: its id (or `null`
+     * if there is no active conversation), and the handoff state — whether
+     * the conversation is in live chat and, if so, basic info about the
+     * connected agent.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`,
+     * or with an `AdaEmbedError` if the chat frame is not yet ready.
+     */
+    getConversation(): Promise<ConversationInfo>;
+    /**
+     * Returns the full in-memory message list for the current session.
+     * Generative has no server-side history endpoint, so this returns
+     * what the client has rendered (user, bot, and any handoff messages).
+     * Returns an empty array if no messages have been exchanged yet.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`,
+     * or with an `AdaEmbedError` if the chat frame is not yet ready.
+     */
+    getMessages(): Promise<Message[]>;
+    /**
+     * Sends a free-text user message through the same path as the visible
+     * composer (POSTs to `/message/chat/`). Resolves with the generated
+     * message id so the caller can correlate it with later `getMessages()`
+     * reads.
+     *
+     * Generative does not support per-message metadata; user-level metadata
+     * is set via `setMetaFields`.
+     *
+     * Rejects with `EMBED_NOT_INITIALIZED_ERROR` if called before `start()`,
+     * an `AdaEmbedError` if the chat frame is not yet ready, or an
+     * `AdaEmbedError` if `text` is empty.
+     */
+    sendMessage(text: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Registers a host-side interceptor that runs in embed-2 before
+     * outgoing messages are forwarded to chat. Use `beforeSend` to
+     * modify, cancel, or pass through the user message. Set `beforeSend`
+     * to `undefined` to clear an existing delegate.
+     *
+     * The delegate may be synchronous or async. Returning `false` (or a
+     * Promise of `false`) cancels the send and causes `sendMessage` to
+     * reject with `DelegateRejected`.
+     */
+    setDelegate(delegate: Delegate): void;
+    /**
+     * MES-981: widened subscribeEvent overload to accept the new ada:* event
+     * keys until @ada-support/embed-types is republished. The upstream signature
+     * is preserved for the original key set via the union return type.
+     */
+    subscribeEvent<K extends ExtendedAdaEventKey>(eventKey: K, callback: K extends AdaEventKey ? AdaEventSubscriptionCallback<K> : K extends keyof ExtendedAdaEventDataKeyedByEvent ? (data: ExtendedAdaEventDataKeyedByEvent[K], context: AdaEventContext) => void : never): Promise<number>;
+}
+export type BeforeSend = (message: {
+    text: string;
+}) => {
+    text: string;
+} | false | Promise<{
+    text: string;
+} | false>;
+export interface Delegate {
+    beforeSend?: BeforeSend;
+}
+export interface ConversationInfo {
+    id: string | null;
+    handoff: {
+        inLiveChat: boolean;
+        agent?: {
+            id: string;
+            name: string;
+            avatarUrl?: string;
+        };
+    };
+}
+export type MessageRole = "user" | "bot" | "agent";
+export interface Message {
+    id: string;
+    role: MessageRole;
+    type: string;
+    body?: string;
+    /** Unix epoch seconds (subsecond precision), as stored by the chat session. */
+    createdAt: number;
+    agent?: {
+        id: string;
+        name: string;
+        avatarUrl?: string;
+    };
+}

package/dist/npm-entry/common/types/index.d.ts

@@ -1,5 +1,5 @@
-import type { AdaEmbedAPI } from "@ada-support/embed-types";
 import type { ActionTypes } from "common/constants/actions";
+import type { ExtendedAdaEmbedAPI } from "./extended-api";
 import type { StoreState } from "./store-state";
 export * from "./interface";
 export interface StoreAction {
@@ -30,7 +30,7 @@ export interface TriggerCampaignParams {
     ignoreFrequency?: boolean;
 }
 export interface CustomWindow extends Window {
-    adaEmbed: AdaEmbedAPI;
+    adaEmbed: ExtendedAdaEmbedAPI;
     navigator: Navigator;
     adaEmbedLoadedCallback?: () => void;
 }

package/dist/npm-entry/common/types/store-state.d.ts

@@ -1,11 +1,13 @@
 import type { Modality, StartOptions } from "@ada-support/embed-types";
 import type { ConnectionState } from "common/constants/events";
+import type { MessagingAuthState } from "common/helpers/messaging-auth-state";
 import type { Client } from "common/models/client";
 import type { AdaCluster } from "common/types";
 export interface StoreState extends StartOptionsNoFunction {
     chatterCreated: string | undefined;
     chatterToken: string | undefined;
     sessionToken: string | undefined;
+    messagingAuthState?: MessagingAuthState;
     client?: Client;
     enabledLanguages: string[];
     isDrawerOpen: boolean;
@@ -65,4 +67,8 @@ export interface StartOptionsNoFunction {
     testMode?: boolean;
     preload?: boolean;
     showFallbackOnTimeout?: boolean;
+    /** MES-981: programmatic-only mode — entry UI is hidden, host renders its own surface */
+    headless?: boolean;
+    /** MES-981 P0 #4: opt-in for the transcript-bearing programmatic surface. */
+    enableProgrammaticControl?: boolean;
 }

package/dist/npm-entry/index-npm.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("@ada-support/embed-types").AdaEmbedAPI;
+declare const _default: import("./common/types/extended-api").ExtendedAdaEmbedAPI;
 export default _default;