@ada-support/embed2 1.13.5 → 1.14.3

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/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/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

@@ -65,4 +65,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;

package/dist/npm-entry/index.js

@@ -15919,7 +15919,7 @@ const client = new BrowserClient({
     return event;
   },
   environment: "production",
-  release: "1.13.5-7576a55",
+  release: "1.14.3-00422f5",
   sampleRate: 0.25,
   autoSessionTracking: false,
   // Integrations don't seem to work with Sentry: https://github.com/getsentry/sentry-javascript/issues/2541
@@ -16019,6 +16019,8 @@ const GET_INFO = "GET_INFO";
 const GET_INFO_RESPONSE = "GET_INFO_RESPONSE";
 const SET_META_FIELDS = "SET_META_FIELDS";
 const SET_META_FIELDS_RESPONSE = "SET_META_FIELDS_RESPONSE";
+const GET_META_FIELDS = "GET_META_FIELDS";
+const GET_META_FIELDS_RESPONSE = "GET_META_FIELDS_RESPONSE";
 const STOP = "STOP";
 const STOP_RESPONSE = "STOP_RESPONSE";
 const DELETE_HISTORY = "DELETE_HISTORY";
@@ -16058,6 +16060,12 @@ let FetchEventStatus = /*#__PURE__*/function (FetchEventStatus) {
 
 
 
+// MES-981 P1 #6 follow-up: request events whose responses are surfaced
+// directly to host-page callers. For these, channel.fetch() differentiates
+// timeouts (resolves to undefined) from other failures (re-throws with a
+// descriptive message) so the caller's "response === undefined" check
+// always means "timeout" specifically, not "something else went wrong".
+const PRIVILEGED_FETCH_EVENTS = new Set(["SEND_MESSAGE", "SET_COMPOSER_TEXT", "GET_MESSAGES", "GET_CONVERSATION"]);
 class Channel {
   constructor() {
     _defineProperty(this, "trackedListeners", void 0);
@@ -16111,6 +16119,21 @@ class Channel {
         throw new AdaEmbedError(`Failed to respond to "GET_STATE" request. Reason: "${e.message}".`);
       }
 
+      // MES-981 P1 #6 follow-up: privileged transcript-bearing request/
+      // response pairs must distinguish timeouts from other failures.
+      // Without this, the "if (response === undefined)" check in
+      // interface.ts throws a misleading "… timed out" error even when
+      // the real failure was a payload-shape rejection or a handler
+      // exception. Re-throw on any non-timeout error so the caller sees
+      // the actual reason.
+      if (PRIVILEGED_FETCH_EVENTS.has(requestEvent)) {
+        if (e instanceof Error && e.message === "Could not connect frame channel.") {
+          // genuine timeout — fall through, resolves to undefined
+        } else {
+          throw new AdaEmbedError(`"${requestEvent}" failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+      }
+
       // handling promise
       if (e.message !== "Could not connect frame channel.") {
         error_tracker.trackException(e);
@@ -16395,14 +16418,25 @@ function subscribeEvent(eventKey, callback) {
   });
   return id;
 }
+
+// MES-981 P2 #11: events that carry transcript bodies (or other
+// sensitive payloads) must match exactly, never via prefix. Prefix
+// subscriptions to `ada:` would otherwise leak `ada:message:sent` and
+// `ada:message:received` to anyone broadly subscribed to the `ada:`
+// namespace.
+const EXACT_MATCH_EVENT_KEYS = new Set(["ada:message:sent", "ada:message:received"]);
 function publishEvent(eventKey, data) {
   subscriptions.forEach(subscription => {
-    // Using startsWith instead of === allows subscribing to a specific event OR a namespace,
-    // e.g. ada:campaigns subscribes to ada:campaigns:opened, ada:campaigns:engaged, and
-    // ada:campaigns:shown. Broadcasting this way simultaneously reaches subscriptions
-    // that have subscribed to a specific event, and those that have subscribed to a namespace
-    if (eventKey.startsWith(subscription.eventKey)) {
-      // try/catch to guard against missing or bad callbacks
+    const matches = EXACT_MATCH_EVENT_KEYS.has(eventKey) ?
+    // Sensitive events require an exact subscription key match —
+    // never deliver via a prefix subscription to e.g. "ada:" or
+    // "ada:message".
+    subscription.eventKey === eventKey :
+    // Prefix match remains the default so subscribers can listen to
+    // a namespace like `ada:campaigns` and catch
+    // `ada:campaigns:opened` / `:engaged` / `:shown`.
+    eventKey.startsWith(subscription.eventKey);
+    if (matches) {
       try {
         subscription.callback(data, {
           eventKey
@@ -16509,7 +16543,7 @@ function getEmbedURL(_ref) {
   } else {
     host = `http://${handle}.localhost:${ports.localhost.default}`;
   }
-  return `${host}/embed/${frameName}/${"7576a55"}/index.html`;
+  return `${host}/embed/${frameName}/${"00422f5"}/index.html`;
 }
 function constructQueryString(query) {
   return Object.keys(query).map(key => {
@@ -16720,6 +16754,15 @@ const mutations = (state, action) => {
   switch (action.type) {
     case ActionTypes.TOGGLE_CHAT_TYPE:
       {
+        // MES-981 P1 #9 follow-up: defensive guard against future accidental
+        // TOGGLE_CHAT_ACTION dispatches in headless mode. The host page has
+        // no drawer to toggle, so flipping isDrawerOpen / drawerHasBeenOpened
+        // and persisting `ada-embed_is-drawer-open: true` to localStorage
+        // would leak across reloads with no visible effect. start() doesn't
+        // dispatch this in headless any more, but the mutation stays robust.
+        if (state.adaSettings.headless) {
+          return state;
+        }
         let {
           hasChatOpenedAfterProactiveMessagesShown
         } = state;
@@ -17011,6 +17054,8 @@ const getInitialState = adaSettings => ({
   language: undefined,
   greeting: undefined,
   crossWindowPersistence: true,
+  headless: false,
+  enableProgrammaticControl: false,
   hideMask: true,
   metaFields: {},
   sensitiveMetaFields: {},
@@ -17052,6 +17097,58 @@ const getInitialState = adaSettings => ({
   deviceToken: null,
   showFallbackOnTimeout: true
 });
+// EXTERNAL MODULE: ./node_modules/lodash.memoize/index.js
+var lodash_memoize = __webpack_require__(7654);
+var lodash_memoize_default = /*#__PURE__*/__webpack_require__.n(lodash_memoize);
+;// CONCATENATED MODULE: ./src/services/logger/index.ts
+
+function logger_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function logger_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? logger_ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : logger_ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+
+
+const DEFAULT_LOG_SAMPLE_RATE = 0.01;
+const DD_BASE_URL = "https://browser-http-intake.logs.datadoghq.com/v1/input/";
+const DD_TOKEN = "pubfe23baedd2ea322bebb5ed2020fa2fa1";
+let globalLogContext = {};
+function setGlobalLogContext(context) {
+  globalLogContext = logger_objectSpread({}, context);
+}
+function clearGlobalLogContext() {
+  globalLogContext = {};
+}
+
+// We need memoization to ensure consistency of logs
+const shouldLog = lodash_memoize_default()(sampleRate => {
+  if (!DD_TOKEN || sampleRate === 0) {
+    return false;
+  }
+  return Math.random() < (sampleRate || DEFAULT_LOG_SAMPLE_RATE);
+});
+
+/**
+ * Sends log to Datadog
+ */
+async function log(message, extra, options) {
+  if (!shouldLog(options === null || options === void 0 ? void 0 : options.sampleRate)) {
+    return;
+  }
+  await httpRequest({
+    url: `${DD_BASE_URL}${DD_TOKEN}?ddsource=browser&ddtags=version:1.5.0,env:${"production"}`,
+    method: "POST",
+    body: JSON.stringify(logger_objectSpread(logger_objectSpread(logger_objectSpread({
+      message
+    }, extra), globalLogContext), {}, {
+      level: (options === null || options === void 0 ? void 0 : options.level) || "info",
+      sampleRate: (options === null || options === void 0 ? void 0 : options.sampleRate) || DEFAULT_LOG_SAMPLE_RATE,
+      service: "embed",
+      env: "production",
+      embedVersion: 2,
+      version: "1.14.3",
+      isNpm: true,
+      commitHash: "00422f5"
+    }))
+  });
+}
 ;// CONCATENATED MODULE: ./src/common/helpers/get-intro-for-url.ts
 function getProcessedPath(path) {
   const regex = /^http(s)?:\/\/(www.)?/;
@@ -17651,58 +17748,6 @@ function getButtonText(client) {
   }
   return buttonTextMap[languageKey];
 }
-// EXTERNAL MODULE: ./node_modules/lodash.memoize/index.js
-var lodash_memoize = __webpack_require__(7654);
-var lodash_memoize_default = /*#__PURE__*/__webpack_require__.n(lodash_memoize);
-;// CONCATENATED MODULE: ./src/services/logger/index.ts
-
-function logger_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
-function logger_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? logger_ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : logger_ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
-
-
-const DEFAULT_LOG_SAMPLE_RATE = 0.01;
-const DD_BASE_URL = "https://browser-http-intake.logs.datadoghq.com/v1/input/";
-const DD_TOKEN = "pubfe23baedd2ea322bebb5ed2020fa2fa1";
-let globalLogContext = {};
-function setGlobalLogContext(context) {
-  globalLogContext = logger_objectSpread({}, context);
-}
-function clearGlobalLogContext() {
-  globalLogContext = {};
-}
-
-// We need memoization to ensure consistency of logs
-const shouldLog = lodash_memoize_default()(sampleRate => {
-  if (!DD_TOKEN || sampleRate === 0) {
-    return false;
-  }
-  return Math.random() < (sampleRate || DEFAULT_LOG_SAMPLE_RATE);
-});
-
-/**
- * Sends log to Datadog
- */
-async function log(message, extra, options) {
-  if (!shouldLog(options === null || options === void 0 ? void 0 : options.sampleRate)) {
-    return;
-  }
-  await httpRequest({
-    url: `${DD_BASE_URL}${DD_TOKEN}?ddsource=browser&ddtags=version:1.5.0,env:${"production"}`,
-    method: "POST",
-    body: JSON.stringify(logger_objectSpread(logger_objectSpread(logger_objectSpread({
-      message
-    }, extra), globalLogContext), {}, {
-      level: (options === null || options === void 0 ? void 0 : options.level) || "info",
-      sampleRate: (options === null || options === void 0 ? void 0 : options.sampleRate) || DEFAULT_LOG_SAMPLE_RATE,
-      service: "embed",
-      env: "production",
-      embedVersion: 2,
-      version: "1.13.5",
-      isNpm: true,
-      commitHash: "7576a55"
-    }))
-  });
-}
 ;// CONCATENATED MODULE: ./src/client/helpers/alternative-bot-rollout/index.ts
 
 function alternative_bot_rollout_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
@@ -19263,6 +19308,12 @@ function deriveMessagingMobileShell(mobilePackage) {
 function deriveLegacyMobileShell(surface, hostPlatform) {
   return surface === "mobile" && hostPlatform !== "web" ? "legacy-sdk" : undefined;
 }
+
+// MES-981 P1 #10: extracted to keep resolveHostTelemetryFromStartOptions
+// under the sonarjs cognitive-complexity threshold.
+function deriveMode(adaSettings) {
+  return adaSettings.headless ? "headless" : undefined;
+}
 function normalizeHostTelemetry(value) {
   const record = asRecord(value);
   if (!record) {
@@ -19345,11 +19396,14 @@ function resolveHostTelemetryFromStartOptions(adaSettings) {
   const mobilePackage = explicit === null || explicit === void 0 ? void 0 : explicit.mobilePackage;
   const mobileVersion = explicit === null || explicit === void 0 ? void 0 : explicit.mobileVersion;
   const mobileShell = deriveMessagingMobileShell(mobilePackage) ?? (explicit === null || explicit === void 0 ? void 0 : explicit.mobileShell) ?? (legacyFingerprint === null || legacyFingerprint === void 0 ? void 0 : legacyFingerprint.mobileShell) ?? (!hasExplicitHostTelemetry ? deriveLegacyMobileShell(surface, hostPlatform) : undefined);
-  return host_telemetry_objectSpread(host_telemetry_objectSpread(host_telemetry_objectSpread({
+  const mode = deriveMode(adaSettings);
+  return host_telemetry_objectSpread(host_telemetry_objectSpread(host_telemetry_objectSpread(host_telemetry_objectSpread({
     surface,
     hostPlatform,
     webSdkOrigin
-  }, mobileShell ? {
+  }, mode ? {
+    mode
+  } : {}), mobileShell ? {
     mobileShell
   } : {}), mobilePackage ? {
     mobilePackage
@@ -19367,7 +19421,11 @@ function toMonitoringContext(hostTelemetry) {
   return host_telemetry_objectSpread(host_telemetry_objectSpread(host_telemetry_objectSpread({
     surface: hostTelemetry.surface,
     host_platform: hostTelemetry.hostPlatform,
-    web_sdk_origin: hostTelemetry.webSdkOrigin
+    web_sdk_origin: hostTelemetry.webSdkOrigin,
+    // MES-981 P1 #10: every log/RUM line carries `mode`; default to
+    // "visible" when not set on the context so dashboards can filter
+    // by mode without a separate query.
+    mode: hostTelemetry.mode ?? "visible"
   }, hostTelemetry.mobileShell ? {
     mobile_shell: hostTelemetry.mobileShell
   } : {}), hostTelemetry.mobilePackage ? {
@@ -19378,6 +19436,32 @@ function toMonitoringContext(hostTelemetry) {
 }
 ;// CONCATENATED MODULE: ./src/common/helpers/is-mobile.ts
 const isMobile = /(iPhone)|(iPod)|(android)|(webOS)/i.exec(navigator.userAgent) !== null;
+;// CONCATENATED MODULE: ./src/common/helpers/programmatic-control.ts
+
+
+// MES-981: privileged transcript-bearing surface is opt-in. Host pages
+// must explicitly accept the exposure risk via
+// `start({ enableProgrammaticControl: true })`, because every third-party
+// script in the host page (analytics, GTM, ad pixels, session replay,
+// supply-chain XSS) inherits the host's trust.
+const PROGRAMMATIC_CONTROL_DISABLED_ERROR = new AdaEmbedError("ProgrammaticControlNotEnabled: this API requires `start({ enableProgrammaticControl: true })`.");
+function isProgrammaticControlEnabled(adaSettings) {
+  return Boolean(adaSettings === null || adaSettings === void 0 ? void 0 : adaSettings.enableProgrammaticControl);
+}
+function requireProgrammaticControl(adaSettings) {
+  if (!isProgrammaticControlEnabled(adaSettings)) {
+    throw PROGRAMMATIC_CONTROL_DISABLED_ERROR;
+  }
+}
+
+// ada:message:sent and ada:message:received carry user/agent transcript
+// bodies. Other ada:* events (ready, connection, conversation, typing)
+// only carry id/state/timing data and are not subject to this gate.
+const TRANSCRIPT_EVENT_KEYS = new Set(["ada:message:sent", "ada:message:received"]);
+function shouldDeliverTranscriptEvent(eventKey, adaSettings) {
+  if (!TRANSCRIPT_EVENT_KEYS.has(eventKey)) return true;
+  return isProgrammaticControlEnabled(adaSettings);
+}
 ;// CONCATENATED MODULE: ./src/client/components/ChatFrame/chatFrameEvents/chatterEvent/index.ts
 
 
@@ -19548,6 +19632,31 @@ function getFallbackDataURI() {
 
 
 
+
+// MES-981: route an inbound PUBLISH_EVENT from the chat iframe to the host's
+// event-subscription registry. Pulled out of handleChatEvent so its switch
+// stays under the sonarjs cognitive-complexity threshold.
+//
+// Two host-facing transforms happen here:
+//   - shouldDeliverTranscriptEvent drops ada:message:* unless the host
+//     opted in via enableProgrammaticControl (P0 #4).
+//   - ada:ready is re-emitted with `{ mode: "headless" | "visible" }` so
+//     subscribers can branch without inspecting adaSettings (P1 #10).
+function forwardPublishEvent(publishPayload, adaSettings) {
+  const {
+    eventKey,
+    data
+  } = publishPayload;
+  if (!shouldDeliverTranscriptEvent(eventKey, adaSettings)) return;
+  if (eventKey === "ada:ready") {
+    const mode = adaSettings.headless ? "headless" : "visible";
+    publishEvent(eventKey, {
+      mode
+    });
+    return;
+  }
+  publishEvent(eventKey, data);
+}
 class ChatFrame extends preact_module_d {
   constructor() {
     super(...arguments);
@@ -19597,7 +19706,7 @@ class ChatFrame extends preact_module_d {
     log("Chat frame mount", {
       handle,
       chatUrl: this.url,
-      embedVersion: "7576a55".slice(0, 7),
+      embedVersion: "00422f5".slice(0, 7),
       embedSettings: adaSettings
     });
 
@@ -19685,7 +19794,7 @@ class ChatFrame extends preact_module_d {
     const hostPageUrlParams = new URL(window.location.href).searchParams;
     const smsToken = hostPageUrlParams.get("adaSMSToken");
     const queryParams = {
-      embedVersion: "7576a55".slice(0, 7),
+      embedVersion: "00422f5".slice(0, 7),
       greeting,
       language,
       skipGreeting,
@@ -20004,11 +20113,7 @@ class ChatFrame extends preact_module_d {
         }
       case PUBLISH_EVENT:
         {
-          const {
-            eventKey,
-            data
-          } = payload;
-          publishEvent(eventKey, data);
+          forwardPublishEvent(payload, adaSettings);
           break;
         }
       case ANALYTICS_EVENT:
@@ -20658,10 +20763,36 @@ class XStorageFrame extends preact_module_d {
   }
 }
 /* harmony default export */ var components_XStorageFrame = (connect()(XStorageFrame));
+;// CONCATENATED MODULE: ./src/client/components/Container/host-facing-meta-fields.ts
+
+function host_facing_meta_fields_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function host_facing_meta_fields_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? host_facing_meta_fields_ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : host_facing_meta_fields_ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+// MES-981 metaFields helpers. Extracted from Container/index.tsx so the
+// transforms don't push that already-large module over its max-lines budget.
+
+/** Strips the internal `proactive_conversation` tracker for getMetaFields(). */
+function toHostFacingMetaFields(metaFields) {
+  const hostFacing = host_facing_meta_fields_objectSpread({}, metaFields);
+  delete hostFacing.proactive_conversation;
+  return hostFacing;
+}
+
+/** Merges a proactive_conversation key onto existing metaFields. */
+function withProactiveKey(metaFields, key) {
+  return host_facing_meta_fields_objectSpread(host_facing_meta_fields_objectSpread({}, metaFields), {}, {
+    proactive_conversation: key
+  });
+}
 ;// CONCATENATED MODULE: ./src/client/components/Container/index.tsx
 
 function Container_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function Container_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? Container_ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : Container_ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+/* eslint-disable max-lines -- MES-981: file was already at the 1000-line
+   max-lines cap on main; the additive programmatic-control work pushes it
+   just over. A targeted refactor of this Container is being tracked
+   separately and is out of scope for this PR. */
+
+
 
 
 
@@ -20740,11 +20871,11 @@ class Container extends preact_module_d {
       adaSettings
     });
 
-    // Nullify any previous conversation's proactive_conversation metavariable value
+    // MES-981: seed state.metaFields with host-supplied values + reset tracker.
     setGlobalState({
-      metaFields: {
+      metaFields: Container_objectSpread(Container_objectSpread({}, adaSettings.metaFields ?? {}), {}, {
         proactive_conversation: null
-      }
+      })
     });
 
     // We want to make sure this happens before any publishEvent calls
@@ -20853,7 +20984,9 @@ class Container extends preact_module_d {
     // campaigns, we don't need this for engage (response_id) campaigns
     campaignToTrigger.response_id || appConnectionState === ConnectionState.Done) && !isDrawerOpen && !chatterInLiveChat) {
       triggerCampaignImpl({
-        adaSettings,
+        adaSettings: Container_objectSpread(Container_objectSpread({}, adaSettings), {}, {
+          handle: (client === null || client === void 0 ? void 0 : client.handle) || adaSettings.handle
+        }),
         chatterToken,
         campaign: campaignToTrigger,
         ignoreStatus: Boolean(campaignTriggerOptions.ignoreStatus),
@@ -20901,12 +21034,11 @@ class Container extends preact_module_d {
     if (isChatWebsocketConnected && isDrawerOpen && recentProactiveConversationConfig) {
       const chatChannel = messageService.getChannel(CHAT_IFRAME);
       if (chatChannel) {
-        // Set meta field to indicate that a proactive conversation has been injected
-        // This can be used by the AI manager to customize the greeting
+        const {
+          metaFields
+        } = this.props;
         setGlobalState({
-          metaFields: {
-            proactive_conversation: recentProactiveConversationConfig.key
-          }
+          metaFields: withProactiveKey(metaFields, recentProactiveConversationConfig.key)
         });
         chatChannel.postMessage(INJECT_PROACTIVE_CONVERSATION, {
           key: recentProactiveConversationConfig.key,
@@ -20961,6 +21093,13 @@ class Container extends preact_module_d {
     if (hideChatOverride) {
       return false;
     }
+
+    // MES-981: in headless mode the host page never opens the drawer, so
+    // treat headless as an implicit preload to ensure the chat iframe loads
+    // and registers its frame-channel handler.
+    if (adaSettings.headless) {
+      return true;
+    }
     if (preload) {
       return true;
     }
@@ -21101,7 +21240,9 @@ class Container extends preact_module_d {
     if (!client) {
       throw new AdaEmbedError("`client` is not defined");
     }
-    const campaignToTrigger = getCampaignToTrigger(adaSettings, client.marketing_campaigns, params, !client.features.afm_proactive_messaging);
+    const campaignToTrigger = getCampaignToTrigger(Container_objectSpread(Container_objectSpread({}, adaSettings), {}, {
+      handle: client.handle
+    }), client.marketing_campaigns, params, !client.features.afm_proactive_messaging);
     if (campaignToTrigger) {
       if (useDelay) {
         setTimeout(() => {
@@ -21238,9 +21379,13 @@ class Container extends preact_module_d {
             drawerHasBeenOpened,
             chatterToken
           } = this.props;
+          // MES-981 P1 #9: in headless mode the UI is intentionally hidden,
+          // so `isChatOpen` always returns false regardless of any drawer
+          // state. Matches the contract that isOpen() returns in headless.
+          const isHeadless = Boolean(adaSettings.headless);
           const contentToReturn = {
-            isDrawerOpen,
-            isChatOpen: isDrawerOpen || Boolean(parentElement),
+            isDrawerOpen: isHeadless ? false : isDrawerOpen,
+            isChatOpen: isHeadless ? false : isDrawerOpen || Boolean(parentElement),
             hasActiveChatter: Boolean(chatterToken),
             hasClosedChat: drawerHasBeenOpened && !isDrawerOpen
           };
@@ -21261,6 +21406,14 @@ class Container extends preact_module_d {
           localChannel.postMessage(SET_META_FIELDS_RESPONSE, null, id);
           break;
         }
+      case GET_META_FIELDS:
+        {
+          const {
+            metaFields
+          } = this.props;
+          localChannel.postMessage(GET_META_FIELDS_RESPONSE, toHostFacingMetaFields(metaFields), id);
+          break;
+        }
       case "SET_SENSITIVE_META_FIELDS":
         {
           const {
@@ -21826,6 +21979,7 @@ function embed_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { va
 
 
 
+
 function renderApp(_ref) {
   let {
     adaSettings,
@@ -21850,6 +22004,25 @@ function renderApp(_ref) {
   if (!parentContainer) {
     throw new AdaEmbedError("`parentContainer` is null");
   }
+
+  // MES-981: in headless mode the React tree still mounts (so the websocket,
+  // Redux, and FC handlers run) but the entry container is moved off-screen
+  // — the host page controls its own UI on top of the programmatic surface.
+  // We use absolute positioning + 0x0 + clip instead of `display: none`
+  // because Chrome (and Safari) defer iframe loads for elements that are
+  // display:none, which would block the chat iframe from ever registering
+  // its frame-channel handlers.
+  if (adaSettings.headless) {
+    entryContainer.style.position = "absolute";
+    entryContainer.style.left = "0";
+    entryContainer.style.top = "0";
+    entryContainer.style.width = "0";
+    entryContainer.style.height = "0";
+    entryContainer.style.overflow = "hidden";
+    entryContainer.style.clip = "rect(0, 0, 0, 0)";
+    entryContainer.style.pointerEvents = "none";
+    entryContainer.setAttribute("aria-hidden", "true");
+  }
   parentContainer.appendChild(entryContainer);
   M(v(StoreContext.Provider, {
     value: store
@@ -21899,6 +22072,31 @@ function createEmbed(adaSettings) {
       initializationReject: reject
     });
   });
+
+  // MES-981 P1 #10: emit a high-priority log entry on every headless
+  // session start so ops can spot abuse patterns (compromised host site
+  // silently running chatter sessions under the visiting user's token).
+  // Sampled at 1.0 so we never miss one; the volume is bounded by the
+  // host explicitly opting in.
+  if (adaSettings.headless) {
+    log("headless_session_initialized", {
+      handle: adaSettings.handle,
+      parent_origin: window.location.origin
+    }, {
+      sampleRate: 1,
+      level: "info"
+    });
+  }
+
+  // MES-981 P1 #9: headless boot no longer reuses TOGGLE_CHAT_ACTION.
+  // The old dispatch persisted drawer-open state to localStorage and set
+  // `drawerHasBeenOpened` / `focusIsOnAda` even though there is no
+  // visible drawer — which then leaked across reloads. The chat iframe
+  // mounts directly via `shouldRenderChatFrame` returning true for
+  // headless (Container/index.tsx), and the iframe's own init drives
+  // chatter creation, pusher subscription, and greeting fire. No drawer
+  // state needs to flip.
+
   const debounceCampaignTrigger = lodash_debounce_default()(async function (campaignKey) {
     let triggerCampaignParams = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     await initialized;
@@ -21921,6 +22119,10 @@ function createEmbed(adaSettings) {
       await initialized;
       await localChannel.fetch(SET_META_FIELDS, SET_META_FIELDS_RESPONSE, options);
     },
+    async getMetaFields() {
+      await initialized;
+      return await localChannel.fetch(GET_META_FIELDS, GET_META_FIELDS_RESPONSE);
+    },
     async setSensitiveMetaFields(options) {
       await initialized;
       await localChannel.fetch("SET_SENSITIVE_META_FIELDS", "SET_SENSITIVE_META_FIELDS_RESPONSE", options);
@@ -21990,6 +22192,30 @@ function createEmbed(adaSettings) {
     }
   };
 }
+;// CONCATENATED MODULE: ./src/common/helpers/with-timeout.ts
+
+
+/**
+ * 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.
+ */
+function withTimeout(promise, ms, errorMessage) {
+  return new Promise((resolve, reject) => {
+    const handle = setTimeout(() => reject(new AdaEmbedError(errorMessage)), ms);
+    Promise.resolve(promise).then(value => {
+      clearTimeout(handle);
+      resolve(value);
+    }, err => {
+      clearTimeout(handle);
+      reject(err);
+    });
+  });
+}
 ;// CONCATENATED MODULE: ./src/interface.ts
 
 
@@ -21998,13 +22224,56 @@ function createEmbed(adaSettings) {
 
 
 
+
+
 const EMBED_NOT_INITIALIZED_ERROR = new AdaEmbedError("Actions cannot be called until Embed has been instantiated. Try running `adaEmbed.start({...})`.");
 
+// MES-981 P1 #7: run the host's beforeSend hook with a 5s timeout, validate
+// its return value, and surface DelegateRejected / DelegateTimeout / shape
+// errors with the same wording as before. Extracted from sendMessage to
+// keep that method below the sonarjs cognitive-complexity threshold.
+async function applyBeforeSend(beforeSend, originalText) {
+  let result;
+  try {
+    result = await withTimeout(beforeSend({
+      text: originalText
+    }), 5000, "DelegateTimeout");
+  } catch (err) {
+    if (err instanceof AdaEmbedError && err.message === "DelegateTimeout") {
+      log("Delegate beforeSend timed out", {
+        timeoutMs: 5000
+      });
+    } else {
+      log("Delegate beforeSend threw", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+    throw err;
+  }
+  if (result === false) {
+    log("Delegate beforeSend canceled the send", {});
+    throw new AdaEmbedError("DelegateRejected");
+  }
+  const candidate = result;
+  if (!candidate || typeof candidate !== "object" || typeof candidate.text !== "string") {
+    throw new AdaEmbedError("Delegate beforeSend must return `{ text: string }`, `false`, or a Promise resolving to one of these.");
+  }
+  const transformed = candidate.text;
+  if (transformed.trim().length === 0) {
+    throw new AdaEmbedError("sendMessage requires non-empty text after delegate transform");
+  }
+  log("Delegate beforeSend completed", {
+    transformed: transformed !== originalText
+  });
+  return transformed;
+}
+
 /**
  * Returns the public Embed methods to be bound to the window object.
  */
 function createEmbedInterface() {
   let embed = null;
+  let delegate = {};
   const toggle = async () => {
     if (!embed) {
       throw EMBED_NOT_INITIALIZED_ERROR;
@@ -22048,6 +22317,9 @@ function createEmbedInterface() {
       }
       const stopPromise = embed.stop();
       embed = null;
+      // MES-981: clear the registered delegate so a subsequent start() begins
+      // with a clean interception state.
+      delegate = {};
       try {
         await stopPromise;
       } finally {
@@ -22067,6 +22339,12 @@ function createEmbedInterface() {
       }
       return embed.setMetaFields(options);
     },
+    getMetaFields: async () => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+      return embed.getMetaFields();
+    },
     setSensitiveMetaFields: async options => {
       if (!embed) {
         throw EMBED_NOT_INITIALIZED_ERROR;
@@ -22079,6 +22357,20 @@ function createEmbedInterface() {
       }
       return embed.getInfo();
     },
+    isOpen: async () => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+
+      // MES-981: in headless mode the entry container is display:none, so
+      // even a parentElement-mounted embed isn't visible to the user. Treat
+      // it as "not open" regardless of the underlying isDrawerOpen flag.
+      if (embed.adaSettings.headless) {
+        return false;
+      }
+      const info = await embed.getInfo();
+      return info.isChatOpen;
+    },
     reset: async resetParams => {
       if (!embed) {
         throw EMBED_NOT_INITIALIZED_ERROR;
@@ -22120,6 +22412,12 @@ function createEmbedInterface() {
       }
       return embed.evaluateCampaignConditions(options);
     },
+    // MES-981: the public surface accepts both the upstream AdaEventKey set
+    // and the new ada:* keys (ExtendedAdaEventKey). The underlying event
+    // subscription registry is a string-keyed map at runtime, so casting
+    // through any is safe and lets the implementation reuse the existing
+    // subscribeEvent helper.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     subscribeEvent: async (eventKey, callback) => subscribeEvent(eventKey, callback),
     unsubscribeEvent: async id => unsubscribeEvent(id),
     closeCampaign: async () => {
@@ -22146,6 +22444,126 @@ function createEmbedInterface() {
         language
       });
     },
+    setComposerText: async text => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+      requireProgrammaticControl(embed.adaSettings);
+      if (embed.adaSettings.headless) {
+        throw new AdaEmbedError("HeadlessModeError: setComposerText is not available in headless mode");
+      }
+
+      // MES-981: wait for chat to finish init before forwarding the
+      // postMessage, matching the existing behaviour of setMetaFields etc.
+      await embed.initialized;
+      const channel = embed.messageService.getChannel("chat");
+      if (!channel) {
+        throw new AdaEmbedError("Chat is not ready yet to have composer text set.");
+      }
+
+      // MES-981 P0 #3: SET_COMPOSER_TEXT is request/response so chat-side
+      // validation failures (INVALID_PAYLOAD, TOO_LONG) reach the caller.
+      const response = await channel.fetch("SET_COMPOSER_TEXT", "SET_COMPOSER_TEXT_RESPONSE", {
+        text
+      });
+      if (!response) {
+        throw new AdaEmbedError("setComposerText timed out — chat frame did not respond in time.");
+      }
+      if ("error" in response) {
+        throw new AdaEmbedError(`setComposerText rejected by chat: ${response.error}`);
+      }
+    },
+    getConversation: async () => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+
+      // MES-981 P0 #4: getConversation returns the live-agent handoff
+      // identity (id / name / avatarUrl) alongside the conversation id.
+      // Same host-page exposure surface as ada:message:* and getMessages,
+      // so the same opt-in gate applies.
+      requireProgrammaticControl(embed.adaSettings);
+      await embed.initialized;
+      const channel = embed.messageService.getChannel("chat");
+      if (!channel) {
+        throw new AdaEmbedError("Chat is not ready yet to read conversation.");
+      }
+      const response = await channel.fetch("GET_CONVERSATION", "GET_CONVERSATION_RESPONSE");
+      if (!response) {
+        throw new AdaEmbedError("getConversation timed out — chat frame did not respond in time.");
+      }
+      return response;
+    },
+    getMessages: async () => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+      requireProgrammaticControl(embed.adaSettings);
+      await embed.initialized;
+      const channel = embed.messageService.getChannel("chat");
+      if (!channel) {
+        throw new AdaEmbedError("Chat is not ready yet to read messages.");
+      }
+      const response = await channel.fetch("GET_MESSAGES", "GET_MESSAGES_RESPONSE");
+
+      // MES-981 P1 #6: channel.fetch resolves to undefined on timeout.
+      // The previous behavior normalized that to [], which made a real
+      // chat-frame failure indistinguishable from an empty transcript.
+      // Fail loudly instead so hosts can branch on the error.
+      if (response === undefined) {
+        throw new AdaEmbedError("getMessages timed out — chat frame did not respond in time.");
+      }
+      return response;
+    },
+    sendMessage: async text => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+      requireProgrammaticControl(embed.adaSettings);
+
+      // MES-981: reject empty AND whitespace-only text so we never POST a
+      // meaningless body to /message/chat/.
+      if (typeof text !== "string" || text.trim().length === 0) {
+        throw new AdaEmbedError("sendMessage requires non-empty text");
+      }
+
+      // MES-981: gate on init BEFORE running the host's beforeSend hook.
+      // Otherwise an init failure (or a missing chat channel) leaves the
+      // host with delegate side-effects — analytics logs, UI optimism — for
+      // a message that can never be sent. Match the gating order used by
+      // every other public method on this surface.
+      await embed.initialized;
+      const channel = embed.messageService.getChannel("chat");
+      if (!channel) {
+        throw new AdaEmbedError("Chat is not ready yet to send a message.");
+      }
+      const {
+        beforeSend
+      } = delegate;
+      const finalText = beforeSend ? await applyBeforeSend(beforeSend, text) : text;
+      const response = await channel.fetch("SEND_MESSAGE", "SEND_MESSAGE_RESPONSE", {
+        text: finalText
+      });
+      if (!response) {
+        throw new AdaEmbedError("sendMessage timed out — chat frame did not respond in time.");
+      }
+
+      // MES-981 P0 #2: chat-side validation/rate-limit/dispatch failures
+      // come back as `{ error: <code> }`. Surface the code to the caller
+      // so they can branch on machine-readable reasons (TOO_LONG,
+      // RATE_LIMITED, EMPTY_TEXT, INVALID_PAYLOAD, DISPATCH_FAILED).
+      if ("error" in response) {
+        throw new AdaEmbedError(`sendMessage rejected by chat: ${response.error}`);
+      }
+      return response;
+    },
+    setDelegate: newDelegate => {
+      if (!embed) {
+        throw EMBED_NOT_INITIALIZED_ERROR;
+      }
+      requireProgrammaticControl(embed.adaSettings);
+      delegate = newDelegate ?? {};
+    },
     handleNotification: async () => {
       if (!embed) {
         throw EMBED_NOT_INITIALIZED_ERROR;

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

@@ -1,7 +1,7 @@
-import type { AdaEmbedAPI } from "@ada-support/embed-types";
 import { AdaEmbedError } from "common/helpers/errors";
+import type { ExtendedAdaEmbedAPI } from "common/types/extended-api";
 export declare const EMBED_NOT_INITIALIZED_ERROR: AdaEmbedError;
 /**
  * Returns the public Embed methods to be bound to the window object.
  */
-export declare function createEmbedInterface(): AdaEmbedAPI;
+export declare function createEmbedInterface(): ExtendedAdaEmbedAPI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ada-support/embed2",
-  "version": "1.13.5",
+  "version": "1.14.3",
   "description": "",
   "main": "dist/npm-entry",
   "typings": "dist/npm-entry/index-npm.d.ts",