@ada-support/embed2 1.13.6 → 1.14.4

package/dist/npm-entry/index.js

@@ -15919,7 +15919,7 @@ const client = new BrowserClient({
     return event;
   },
   environment: "production",
-  release: "1.13.6-406ab08",
+  release: "1.14.4-57d2690",
   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}/${"406ab08"}/index.html`;
+  return `${host}/embed/${frameName}/${"57d2690"}/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;
@@ -16994,11 +17037,192 @@ const ZD_MESSAGING_CHATTER_CREATED_STORAGE_KEY = "ada-embed_zd-messaging-chatter
 
 /** @deprecated - Use CHATTER_TOKEN_STORAGE_KEY */
 const CHATTER_STORAGE_KEY = (/* unused pure expression or super */ null && (CHATTER_TOKEN_STORAGE_KEY));
+;// CONCATENATED MODULE: ./src/common/helpers/messaging-auth-state.ts
+
+
+// Single static key, shared verbatim with messaging + chat and disclosed by
+// @ada-support/web-storage. Per-bot scoping is implicit in the bot-subdomain
+// storage origin this runs on, so no apiOrigin/handle-scoped key is needed.
+const MESSAGING_AUTH_STATE_STORAGE_KEY = "messagingAuthState";
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// Typed @ada-support/web-storage wrapper for the chosen persistence provider, or
+// null when persistence is disabled / there is no window. The wrapper is what
+// puts `messagingAuthState` on the published web-storage disclosure list and
+// serializes the value, so callers pass/get a typed object rather than a string.
+function getMessagingAuthStorage(persistence) {
+  if (persistence === "private" || typeof window === "undefined") {
+    return null;
+  }
+  return persistence === "session" ? dist/* adaSessionStorage */.ad : dist/* adaLocalStorage */.BB;
+}
+function getApiOrigin(_ref) {
+  let {
+    handle,
+    cluster,
+    domain
+  } = _ref;
+  try {
+    return new window.URL(getURL({
+      name: "api",
+      handle,
+      cluster,
+      domain
+    }), window.location.origin).origin;
+  } catch (error) {
+    return null;
+  }
+}
+function buildMessagingAuthStateStorageKey(_ref2) {
+  let {
+    handle,
+    cluster,
+    domain
+  } = _ref2;
+  // The key itself is static; the handle/origin now only gate whether there is a
+  // resolvable session to read/write (preserving the previous no-op behavior
+  // before a handle/origin is known) rather than scoping the key.
+  if (!handle || !getApiOrigin({
+    handle,
+    cluster,
+    domain
+  })) {
+    return null;
+  }
+  return MESSAGING_AUTH_STATE_STORAGE_KEY;
+}
+function parseMessagingAuthState(value) {
+  let parsedValue = value;
+  if (typeof value === "string") {
+    try {
+      parsedValue = JSON.parse(value);
+    } catch (error) {
+      return null;
+    }
+  }
+  if (!isRecord(parsedValue)) {
+    return null;
+  }
+  const {
+    messagingToken,
+    messagingTokenExpiresAt,
+    sessionRefreshToken,
+    refreshGeneration
+  } = parsedValue;
+  if (typeof messagingToken !== "string" || !messagingToken || typeof messagingTokenExpiresAt !== "number" || !Number.isFinite(messagingTokenExpiresAt) || messagingTokenExpiresAt <= 0 || typeof sessionRefreshToken !== "string" || !sessionRefreshToken || typeof refreshGeneration !== "number" || !Number.isFinite(refreshGeneration)) {
+    return null;
+  }
+  return {
+    messagingToken,
+    messagingTokenExpiresAt,
+    sessionRefreshToken,
+    refreshGeneration
+  };
+}
+
+// Storage-blocked browsers can throw on the storage methods, so each access is
+// wrapped to fall back gracefully rather than throw into callers.
+function safeReadMessagingAuthState(persistence) {
+  try {
+    var _getMessagingAuthStor;
+    return parseMessagingAuthState(((_getMessagingAuthStor = getMessagingAuthStorage(persistence)) === null || _getMessagingAuthStor === void 0 ? void 0 : _getMessagingAuthStor.getItem(MESSAGING_AUTH_STATE_STORAGE_KEY)) ?? null);
+  } catch (error) {
+    return null;
+  }
+}
+function readMessagingAuthStateFromStorage(_ref3) {
+  let {
+    handle,
+    cluster,
+    domain
+  } = _ref3;
+  if (!buildMessagingAuthStateStorageKey({
+    handle,
+    cluster,
+    domain
+  })) {
+    return undefined;
+  }
+  const persistedAuthStates = ["normal", "session"].map(persistence => safeReadMessagingAuthState(persistence)).filter(authState => authState !== null);
+  return persistedAuthStates.reduce((highestState, authState) => !highestState || authState.refreshGeneration > highestState.refreshGeneration ? authState : highestState, undefined);
+}
+function writeMessagingAuthStateToStorage(_ref4) {
+  let {
+    handle,
+    cluster,
+    domain,
+    persistence,
+    state
+  } = _ref4;
+  const storageKey = buildMessagingAuthStateStorageKey({
+    handle,
+    cluster,
+    domain
+  });
+  const storage = getMessagingAuthStorage(persistence);
+  if (!storageKey || !storage || !state) {
+    return false;
+  }
+  try {
+    const existing = readMessagingAuthStateFromStorage({
+      handle,
+      cluster,
+      domain
+    });
+    if (existing && existing.refreshGeneration >= state.refreshGeneration) {
+      return false;
+    }
+    storage.setItem(storageKey, state);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+function clearAllMessagingAuthStatesFromStorage() {
+  ["normal", "session"].forEach(persistence => {
+    try {
+      var _getMessagingAuthStor2;
+      (_getMessagingAuthStor2 = getMessagingAuthStorage(persistence)) === null || _getMessagingAuthStor2 === void 0 ? void 0 : _getMessagingAuthStor2.removeItem(MESSAGING_AUTH_STATE_STORAGE_KEY);
+    } catch (error) {
+      // Storage blocked; nothing to clear.
+    }
+  });
+}
+
+// Removes the messaging auth state (across both persistence providers). Used when
+// a bot rotates to a new chatter. With the bot-subdomain storage origin there is a
+// single auth state per origin, so this and `clearAllMessagingAuthStatesFromStorage`
+// now clear the same key.
+function clearMessagingAuthStateFromStorage(_ref5) {
+  let {
+    handle,
+    cluster,
+    domain
+  } = _ref5;
+  if (!buildMessagingAuthStateStorageKey({
+    handle,
+    cluster,
+    domain
+  })) {
+    return;
+  }
+  ["normal", "session"].forEach(persistence => {
+    try {
+      var _getMessagingAuthStor3;
+      (_getMessagingAuthStor3 = getMessagingAuthStorage(persistence)) === null || _getMessagingAuthStor3 === void 0 ? void 0 : _getMessagingAuthStor3.removeItem(MESSAGING_AUTH_STATE_STORAGE_KEY);
+    } catch (error) {
+      // Storage blocked; nothing to clear.
+    }
+  });
+}
 ;// CONCATENATED MODULE: ./src/client/store/state.ts
 
 
 
 
+
 function getValueFromStorage(key) {
   return dist/* adaLocalStorage */.BB.getItem(key) || dist/* adaSessionStorage */.ad.getItem(key);
 }
@@ -17011,6 +17235,8 @@ const getInitialState = adaSettings => ({
   language: undefined,
   greeting: undefined,
   crossWindowPersistence: true,
+  headless: false,
+  enableProgrammaticControl: false,
   hideMask: true,
   metaFields: {},
   sensitiveMetaFields: {},
@@ -17031,6 +17257,11 @@ const getInitialState = adaSettings => ({
   chatterToken: getValueFromStorage(CHATTER_TOKEN_STORAGE_KEY) || undefined,
   chatterCreated: getValueFromStorage(CHATTER_CREATED_STORAGE_KEY) || undefined,
   sessionToken: getValueFromStorage(SESSION_AUTH_TOKEN_STORAGE_KEY) || undefined,
+  messagingAuthState: readMessagingAuthStateFromStorage({
+    handle: adaSettings.handle,
+    cluster: adaSettings.cluster,
+    domain: adaSettings.domain
+  }),
   zdSessionId: getValueFromStorage(ZD_SESSION_STORAGE_KEY) || undefined,
   zdPreviousTags: getValueFromStorage(ZD_PREVIOUS_TAGS_STORAGE_KEY) || undefined,
   zdMessagingExternalUserId: getValueFromStorage(ZD_MESSAGING_EXTERNAL_USER_ID_STORAGE_KEY) || null,
@@ -17052,6 +17283,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.4",
+      isNpm: true,
+      commitHash: "57d2690"
+    }))
+  });
+}
 ;// CONCATENATED MODULE: ./src/common/helpers/get-intro-for-url.ts
 function getProcessedPath(path) {
   const regex = /^http(s)?:\/\/(www.)?/;
@@ -17651,58 +17934,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.6",
-      isNpm: true,
-      commitHash: "406ab08"
-    }))
-  });
-}
 ;// 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 +19494,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 +19582,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 +19607,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,23 +19622,101 @@ 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
 
 
+
 function storeChatterEventDataInBrowser(client, payload) {
-  const {
-    persistence
-  } = client;
+  let {
+    cluster,
+    domain,
+    privateMode
+  } = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
   const {
     chatter,
     created,
-    sessionToken
+    sessionToken,
+    messagingAuthState
   } = payload;
+  if (privateMode) {
+    return;
+  }
+  const {
+    persistence
+  } = client;
+
+  // A new chatter resets refreshGeneration back to 1, so the generation guard in
+  // writeMessagingAuthStateToStorage would otherwise refuse to overwrite a previous
+  // chatter's higher-generation (now-dead) auth state — leaving the host-page copy
+  // stuck on a refresh token the backend has rotated away. Whenever the persisted
+  // chatter token does not match the incoming one — including when it is absent or in
+  // the other persistence provider, leaving the auth state orphaned — drop the stale
+  // auth state first so the new chatter's credentials persist.
+  const previousChatter = retrieveStorage(CHATTER_TOKEN_STORAGE_KEY, client, privateMode);
+  if (previousChatter !== chatter) {
+    clearMessagingAuthStateFromStorage({
+      handle: client.handle,
+      cluster,
+      domain
+    });
+  }
   setBrowserStorageItem(CHATTER_TOKEN_STORAGE_KEY, chatter, persistence);
   setBrowserStorageItem(CHATTER_CREATED_STORAGE_KEY, created, persistence);
   if (sessionToken) {
     setBrowserStorageItem(SESSION_AUTH_TOKEN_STORAGE_KEY, sessionToken, persistence);
   }
+
+  // embed-2 only PERSISTS / mirrors the chat auth state here; it is the relay that
+  // lets the chat iframe restore the JWT (e.g. across reloads). embed-2 deliberately
+  // never attaches `Authorization` to its own XHR requests — adding headers to
+  // embed-2's cross-origin XHR trips CORS preflight (see common/helpers/http.ts) — so
+  // the chat iframe, not embed-2, is what sends `Bearer <messagingToken>`.
+  const parsedAuthState = parseMessagingAuthState(messagingAuthState);
+  if (parsedAuthState) {
+    writeMessagingAuthStateToStorage({
+      handle: client.handle,
+      cluster,
+      domain,
+      persistence,
+      state: parsedAuthState
+    });
+  } else {
+    // chat published no usable auth state for this chatter (e.g. it cleared a dead
+    // refresh token on unrecoverable invalid_refresh_token). Drop the host-side copy so
+    // a stale token can't be resurrected on reload — a null write would otherwise no-op
+    // and leave it in place.
+    clearMessagingAuthStateFromStorage({
+      handle: client.handle,
+      cluster,
+      domain
+    });
+  }
 }
 ;// CONCATENATED MODULE: ./src/client/components/ChatFrame/chatFrameEvents/index.ts
 
@@ -19548,6 +19870,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 +19944,7 @@ class ChatFrame extends preact_module_d {
     log("Chat frame mount", {
       handle,
       chatUrl: this.url,
-      embedVersion: "406ab08".slice(0, 7),
+      embedVersion: "57d2690".slice(0, 7),
       embedSettings: adaSettings
     });
 
@@ -19685,7 +20032,7 @@ class ChatFrame extends preact_module_d {
     const hostPageUrlParams = new URL(window.location.href).searchParams;
     const smsToken = hostPageUrlParams.get("adaSMSToken");
     const queryParams = {
-      embedVersion: "406ab08".slice(0, 7),
+      embedVersion: "57d2690".slice(0, 7),
       greeting,
       language,
       skipGreeting,
@@ -20004,11 +20351,7 @@ class ChatFrame extends preact_module_d {
         }
       case PUBLISH_EVENT:
         {
-          const {
-            eventKey,
-            data
-          } = payload;
-          publishEvent(eventKey, data);
+          forwardPublishEvent(payload, adaSettings);
           break;
         }
       case ANALYTICS_EVENT:
@@ -20027,12 +20370,16 @@ class ChatFrame extends preact_module_d {
       case CHATTER_EVENT:
         {
           const {
-            client
+            client,
+            cluster,
+            domain,
+            privateMode
           } = this.props;
           const {
             chatter,
             created,
-            sessionToken
+            sessionToken,
+            messagingAuthState
           } = payload;
           const {
             chatterTokenCallback
@@ -20040,14 +20387,19 @@ class ChatFrame extends preact_module_d {
           if (!client) {
             throw new AdaEmbedError("`client` is undefined");
           }
-          storeChatterEventDataInBrowser(client, payload);
+          storeChatterEventDataInBrowser(client, payload, {
+            cluster,
+            domain,
+            privateMode
+          });
           if (chatterTokenCallback) {
             chatterTokenCallback(chatter);
           }
           await setGlobalState({
             chatterToken: chatter,
             chatterCreated: created,
-            sessionToken
+            sessionToken,
+            messagingAuthState
           });
           break;
         }
@@ -20658,10 +21010,37 @@ 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 +21119,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 +21232,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 +21282,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 +21341,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 +21488,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 +21627,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 +21654,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 {
@@ -21325,11 +21726,20 @@ class Container extends preact_module_d {
             dist/* adaSessionStorage */.ad.removeItem(CHATTER_TOKEN_STORAGE_KEY);
             dist/* adaLocalStorage */.BB.removeItem(CHATTER_CREATED_STORAGE_KEY);
             dist/* adaSessionStorage */.ad.removeItem(CHATTER_CREATED_STORAGE_KEY);
+            // Scope the clear to this bot so a sibling Ada bot on the same origin keeps its
+            // own messaging auth state. adaSettings.{handle,cluster,domain} matches the key
+            // storeChatterEventDataInBrowser wrote under.
+            clearMessagingAuthStateFromStorage({
+              handle: adaSettings.handle,
+              cluster: adaSettings.cluster,
+              domain: adaSettings.domain
+            });
 
             // And from state
             newState = Container_objectSpread(Container_objectSpread({}, newState), {}, {
               chatterToken: undefined,
-              chatterCreated: undefined
+              chatterCreated: undefined,
+              messagingAuthState: undefined
             });
           }
           await setGlobalState(newState);
@@ -21359,11 +21769,19 @@ class Container extends preact_module_d {
           dist/* adaSessionStorage */.ad.removeItem(CHATTER_TOKEN_STORAGE_KEY);
           dist/* adaLocalStorage */.BB.removeItem(CHATTER_CREATED_STORAGE_KEY);
           dist/* adaSessionStorage */.ad.removeItem(CHATTER_CREATED_STORAGE_KEY);
+          // Scope the clear to this bot so a sibling Ada bot on the same origin keeps its
+          // own messaging auth state (see RESET above).
+          clearMessagingAuthStateFromStorage({
+            handle: adaSettings.handle,
+            cluster: adaSettings.cluster,
+            domain: adaSettings.domain
+          });
 
           // And from state
           await setGlobalState({
             chatterToken: undefined,
-            chatterCreated: undefined
+            chatterCreated: undefined,
+            messagingAuthState: undefined
           });
           xStorageChannel.postMessage(DELETE_HISTORY_EVENT, undefined);
           localChannel.postMessage(DELETE_HISTORY_RESPONSE, null, id);
@@ -21594,6 +22012,15 @@ class Container extends preact_module_d {
         adaSettings: Container_objectSpread(Container_objectSpread({}, adaSettings), {}, {
           handle: assignedClient.handle
         }),
+        // Re-read the handle-scoped messaging auth blob under the assigned bot handle.
+        // getInitialState read it under the original adaSettings.handle, which differs
+        // from assignedClient.handle under alternative-bot rollout, so without this the
+        // host-side JWT fallback would miss the assigned bot's persisted token on reload.
+        messagingAuthState: readMessagingAuthStateFromStorage({
+          handle: assignedClient.handle,
+          cluster: cluster,
+          domain
+        }),
         chatterInLiveChat
       }));
     } catch (e) {
@@ -21826,6 +22253,7 @@ function embed_objectSpread(e) { for (var r = 1; r < arguments.length; r++) { va
 
 
 
+
 function renderApp(_ref) {
   let {
     adaSettings,
@@ -21850,6 +22278,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 +22346,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 +22393,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 +22466,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 +22498,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 +22591,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 +22613,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 +22631,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 +22686,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 +22718,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;