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

package/dist/npm/testing.cjs

@@ -0,0 +1,155 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/npm/testing.ts
+var EXACT_MATCH_EVENT_KEYS = new Set(["ada:message:sent", "ada:message:received"]);
+function keyedSubscriptionMatches(subscriptionKey, eventKey) {
+	if (EXACT_MATCH_EVENT_KEYS.has(eventKey)) return subscriptionKey === eventKey;
+	return subscriptionKey === eventKey || eventKey.startsWith(subscriptionKey);
+}
+function toMetaFieldRecord(fields) {
+	const record = {};
+	for (const [key, value] of Object.entries(fields)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) record[key] = value;
+	return record;
+}
+/**
+* Create an in-memory messaging-interface stand-in for unit-testing an
+* integration without loading the SDK from the CDN.
+*
+* Every method resolves, records itself in `calls`, and keeps just enough
+* state to behave like the real interface: `sendMessage` appends a
+* programmatic user message that `getMessages` returns, `open`/`close`/
+* `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds
+* `getMetaFields` (sensitive fields are never returned, matching the real
+* SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.
+*
+* Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden
+* methods are still recorded in `calls`.
+*/
+function createMockAdaMessaging(overrides = {}) {
+	const calls = [];
+	let nextSubscriptionId = 1;
+	let nextMessageId = 1;
+	let chatOpen = false;
+	let conversationId = null;
+	const metaFields = {};
+	const messages = [];
+	const keyedSubscriptions = /* @__PURE__ */ new Map();
+	const wildcardSubscriptions = /* @__PURE__ */ new Map();
+	const emit = (key, data) => {
+		for (const subscription of keyedSubscriptions.values()) if (keyedSubscriptionMatches(subscription.key, key)) subscription.callback(data, { eventKey: key });
+		if (EXACT_MATCH_EVENT_KEYS.has(key)) return;
+		for (const callback of wildcardSubscriptions.values()) callback(key, data);
+	};
+	const clearTranscript = () => {
+		messages.length = 0;
+		conversationId = null;
+	};
+	const base = {
+		start: async () => void 0,
+		stop: async () => void 0,
+		toggle: async () => {
+			chatOpen = !chatOpen;
+		},
+		deleteHistory: async () => {
+			clearTranscript();
+		},
+		reset: async () => {
+			clearTranscript();
+		},
+		setMetaFields: async (fields) => {
+			Object.assign(metaFields, toMetaFieldRecord(fields));
+		},
+		setSensitiveMetaFields: async () => void 0,
+		setTestModeBanner: async () => void 0,
+		getInfo: async () => ({
+			isChatOpen: chatOpen,
+			isDrawerOpen: chatOpen,
+			hasActiveChatter: messages.length > 0,
+			hasClosedChat: false
+		}),
+		getMetaFields: async () => ({ ...metaFields }),
+		isOpen: async () => chatOpen,
+		getConversation: async () => ({
+			id: conversationId,
+			handoff: { inLiveChat: false }
+		}),
+		getMessages: async () => [...messages],
+		setComposerText: async () => void 0,
+		setDelegate: () => void 0,
+		trackEvent: async () => void 0,
+		subscribeEvent: async (key, callback) => {
+			const id = nextSubscriptionId++;
+			keyedSubscriptions.set(id, {
+				key,
+				callback
+			});
+			return id;
+		},
+		unsubscribeEvent: async (id) => {
+			keyedSubscriptions.delete(id);
+			wildcardSubscriptions.delete(id);
+		},
+		subscribeAll: async (callback) => {
+			const id = nextSubscriptionId++;
+			wildcardSubscriptions.set(id, callback);
+			return id;
+		},
+		open: async () => {
+			chatOpen = true;
+		},
+		close: async () => {
+			chatOpen = false;
+		},
+		setLanguage: async () => void 0,
+		setTheme: async () => void 0,
+		setDeviceToken: async () => void 0,
+		sendMessage: async (body) => {
+			const id = `mock-message-${nextMessageId++}`;
+			conversationId = conversationId ?? "mock-conversation";
+			messages.push({
+				id,
+				role: "user",
+				type: "text",
+				body,
+				createdAt: Math.floor(Date.now() / 1e3),
+				origin: "programmatic"
+			});
+			return { id };
+		},
+		handleNotification: async () => {
+			chatOpen = true;
+		},
+		requestNotifications: async () => "granted",
+		createProactive: async () => void 0,
+		triggerCampaign: async () => void 0,
+		evaluateCampaignConditions: async () => void 0,
+		closeCampaign: async () => void 0,
+		triggerAnswer: async () => void 0,
+		triggerProactive: async () => void 0,
+		triggerGreeting: async () => void 0,
+		destroy: async () => {
+			keyedSubscriptions.clear();
+			wildcardSubscriptions.clear();
+			chatOpen = false;
+		}
+	};
+	const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0));
+	const implementation = {
+		...base,
+		...definedOverrides
+	};
+	return {
+		...Object.fromEntries(Object.entries(implementation).map(([method, fn]) => [method, (...args) => {
+			calls.push({
+				method,
+				args
+			});
+			return fn(...args);
+		}])),
+		calls,
+		$emit: emit
+	};
+}
+//#endregion
+exports.createMockAdaMessaging = createMockAdaMessaging;
+
+//# sourceMappingURL=testing.cjs.map

package/dist/npm/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.cjs","names":[],"sources":["../../src/npm/testing.ts"],"sourcesContent":["import type {\n\tAdaSdkEventCallback,\n\tMetaFieldValue,\n\tPublicMessage,\n} from \"../client/client-types\";\nimport type { AdaMessagingInterface } from \"./loader\";\n\n/** One recorded method invocation on a {@link MockAdaMessaging}. */\nexport interface RecordedAdaMessagingCall {\n\tmethod: string;\n\targs: unknown[];\n}\n\n/**\n * The mock returned by {@link createMockAdaMessaging}: the full\n * {@link AdaMessagingInterface} plus test hooks for inspecting calls and\n * simulating SDK events.\n */\nexport interface MockAdaMessaging extends AdaMessagingInterface {\n\t/** Every method invocation, in call order. */\n\tcalls: RecordedAdaMessagingCall[];\n\t/**\n\t * Deliver an event to `subscribeEvent` and `subscribeAll` callbacks, as if\n\t * the SDK emitted it (e.g. `$emit(\"ada:ready\", { isRolledOut: true })`).\n\t * Routing matches the real SDK: keyed subscriptions match by prefix\n\t * (`\"ada:campaigns\"` catches `\"ada:campaigns:shown\"`), except the\n\t * transcript events `ada:message:sent`/`ada:message:received`, which reach\n\t * exact-key subscribers only and never `subscribeAll`.\n\t */\n\t$emit: (key: string, data?: unknown) => void;\n}\n\ninterface KeyedSubscription {\n\tkey: string;\n\tcallback: AdaSdkEventCallback;\n}\n\n// Mirrors EXACT_MATCH_EVENT_KEYS in client/client-host-runtime.ts: transcript\n// events reach exact-key subscribers only, never prefix or subscribeAll\n// subscribers. Duplicated (not imported) so the published testing entry stays\n// free of runtime modules; a drift test pins the mock against the real matcher.\nconst EXACT_MATCH_EVENT_KEYS = new Set([\n\t\"ada:message:sent\",\n\t\"ada:message:received\",\n]);\n\nfunction keyedSubscriptionMatches(\n\tsubscriptionKey: string,\n\teventKey: string,\n): boolean {\n\tif (EXACT_MATCH_EVENT_KEYS.has(eventKey)) {\n\t\treturn subscriptionKey === eventKey;\n\t}\n\t// Raw prefix match, same as the real SDK: \"ada:campaigns\" also catches\n\t// \"ada:campaigns:shown\" and underscore-suffixed keys.\n\treturn subscriptionKey === eventKey || eventKey.startsWith(subscriptionKey);\n}\n\nfunction toMetaFieldRecord(\n\tfields: Record<string, unknown>,\n): Record<string, MetaFieldValue> {\n\tconst record: Record<string, MetaFieldValue> = {};\n\tfor (const [key, value] of Object.entries(fields)) {\n\t\tif (\n\t\t\ttypeof value === \"string\" ||\n\t\t\ttypeof value === \"number\" ||\n\t\t\ttypeof value === \"boolean\" ||\n\t\t\tvalue === null\n\t\t) {\n\t\t\trecord[key] = value;\n\t\t}\n\t}\n\treturn record;\n}\n\n/**\n * Create an in-memory messaging-interface stand-in for unit-testing an\n * integration without loading the SDK from the CDN.\n *\n * Every method resolves, records itself in `calls`, and keeps just enough\n * state to behave like the real interface: `sendMessage` appends a\n * programmatic user message that `getMessages` returns, `open`/`close`/\n * `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds\n * `getMetaFields` (sensitive fields are never returned, matching the real\n * SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.\n *\n * Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden\n * methods are still recorded in `calls`.\n */\nexport function createMockAdaMessaging(\n\toverrides: Partial<AdaMessagingInterface> = {},\n): MockAdaMessaging {\n\tconst calls: RecordedAdaMessagingCall[] = [];\n\tlet nextSubscriptionId = 1;\n\tlet nextMessageId = 1;\n\tlet chatOpen = false;\n\tlet conversationId: string | null = null;\n\tconst metaFields: Record<string, MetaFieldValue> = {};\n\tconst messages: PublicMessage[] = [];\n\tconst keyedSubscriptions = new Map<number, KeyedSubscription>();\n\tconst wildcardSubscriptions = new Map<\n\t\tnumber,\n\t\t(key: string, data: unknown) => void\n\t>();\n\n\tconst emit = (key: string, data?: unknown): void => {\n\t\tfor (const subscription of keyedSubscriptions.values()) {\n\t\t\tif (keyedSubscriptionMatches(subscription.key, key)) {\n\t\t\t\tsubscription.callback(data, { eventKey: key });\n\t\t\t}\n\t\t}\n\t\tif (EXACT_MATCH_EVENT_KEYS.has(key)) {\n\t\t\treturn;\n\t\t}\n\t\tfor (const callback of wildcardSubscriptions.values()) {\n\t\t\tcallback(key, data);\n\t\t}\n\t};\n\n\tconst clearTranscript = (): void => {\n\t\tmessages.length = 0;\n\t\tconversationId = null;\n\t};\n\n\tconst base: AdaMessagingInterface = {\n\t\tstart: async () => undefined,\n\t\tstop: async () => undefined,\n\t\ttoggle: async () => {\n\t\t\tchatOpen = !chatOpen;\n\t\t},\n\t\tdeleteHistory: async () => {\n\t\t\tclearTranscript();\n\t\t},\n\t\treset: async () => {\n\t\t\tclearTranscript();\n\t\t},\n\t\tsetMetaFields: async (fields) => {\n\t\t\tObject.assign(metaFields, toMetaFieldRecord(fields));\n\t\t},\n\t\t// Sensitive fields are accepted but never readable back, matching the\n\t\t// real SDK's getMetaFields contract.\n\t\tsetSensitiveMetaFields: async () => undefined,\n\t\tsetTestModeBanner: async () => undefined,\n\t\tgetInfo: async () => ({\n\t\t\tisChatOpen: chatOpen,\n\t\t\tisDrawerOpen: chatOpen,\n\t\t\thasActiveChatter: messages.length > 0,\n\t\t\thasClosedChat: false,\n\t\t}),\n\t\tgetMetaFields: async () => ({ ...metaFields }),\n\t\tisOpen: async () => chatOpen,\n\t\tgetConversation: async () => ({\n\t\t\tid: conversationId,\n\t\t\thandoff: { inLiveChat: false },\n\t\t}),\n\t\tgetMessages: async () => [...messages],\n\t\tsetComposerText: async () => undefined,\n\t\tsetDelegate: () => undefined,\n\t\ttrackEvent: async () => undefined,\n\t\tsubscribeEvent: async (key, callback) => {\n\t\t\tconst id = nextSubscriptionId++;\n\t\t\tkeyedSubscriptions.set(id, { key, callback });\n\t\t\treturn id;\n\t\t},\n\t\tunsubscribeEvent: async (id) => {\n\t\t\tkeyedSubscriptions.delete(id);\n\t\t\twildcardSubscriptions.delete(id);\n\t\t},\n\t\tsubscribeAll: async (callback) => {\n\t\t\tconst id = nextSubscriptionId++;\n\t\t\twildcardSubscriptions.set(id, callback);\n\t\t\treturn id;\n\t\t},\n\t\topen: async () => {\n\t\t\tchatOpen = true;\n\t\t},\n\t\tclose: async () => {\n\t\t\tchatOpen = false;\n\t\t},\n\t\tsetLanguage: async () => undefined,\n\t\tsetTheme: async () => undefined,\n\t\tsetDeviceToken: async () => undefined,\n\t\tsendMessage: async (body) => {\n\t\t\tconst id = `mock-message-${nextMessageId++}`;\n\t\t\tconversationId = conversationId ?? \"mock-conversation\";\n\t\t\tmessages.push({\n\t\t\t\tid,\n\t\t\t\trole: \"user\",\n\t\t\t\ttype: \"text\",\n\t\t\t\tbody,\n\t\t\t\tcreatedAt: Math.floor(Date.now() / 1000),\n\t\t\t\torigin: \"programmatic\",\n\t\t\t});\n\t\t\treturn { id };\n\t\t},\n\t\thandleNotification: async () => {\n\t\t\tchatOpen = true;\n\t\t},\n\t\trequestNotifications: async () => \"granted\",\n\t\tcreateProactive: async () => undefined,\n\t\ttriggerCampaign: async () => undefined,\n\t\tevaluateCampaignConditions: async () => undefined,\n\t\tcloseCampaign: async () => undefined,\n\t\ttriggerAnswer: async () => undefined,\n\t\ttriggerProactive: async () => undefined,\n\t\ttriggerGreeting: async () => undefined,\n\t\tdestroy: async () => {\n\t\t\tkeyedSubscriptions.clear();\n\t\t\twildcardSubscriptions.clear();\n\t\t\tchatOpen = false;\n\t\t},\n\t};\n\n\tconst definedOverrides = Object.fromEntries(\n\t\tObject.entries(overrides).filter(([, value]) => value !== undefined),\n\t);\n\tconst implementation = { ...base, ...definedOverrides };\n\tconst recorded = Object.fromEntries(\n\t\tObject.entries(implementation).map(([method, fn]) => [\n\t\t\tmethod,\n\t\t\t(...args: unknown[]) => {\n\t\t\t\tcalls.push({ method, args });\n\t\t\t\treturn (fn as (...callArgs: unknown[]) => unknown)(...args);\n\t\t\t},\n\t\t]),\n\t) as unknown as AdaMessagingInterface;\n\n\treturn { ...recorded, calls, $emit: emit };\n}\n"],"mappings":"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"}

package/dist/npm/testing.d.cts

@@ -0,0 +1,39 @@
+import type { AdaMessagingInterface } from "./loader.js" with { "resolution-mode": "import" };
+/** One recorded method invocation on a {@link MockAdaMessaging}. */
+export interface RecordedAdaMessagingCall {
+    method: string;
+    args: unknown[];
+}
+/**
+ * The mock returned by {@link createMockAdaMessaging}: the full
+ * {@link AdaMessagingInterface} plus test hooks for inspecting calls and
+ * simulating SDK events.
+ */
+export interface MockAdaMessaging extends AdaMessagingInterface {
+    /** Every method invocation, in call order. */
+    calls: RecordedAdaMessagingCall[];
+    /**
+     * Deliver an event to `subscribeEvent` and `subscribeAll` callbacks, as if
+     * the SDK emitted it (e.g. `$emit("ada:ready", { isRolledOut: true })`).
+     * Routing matches the real SDK: keyed subscriptions match by prefix
+     * (`"ada:campaigns"` catches `"ada:campaigns:shown"`), except the
+     * transcript events `ada:message:sent`/`ada:message:received`, which reach
+     * exact-key subscribers only and never `subscribeAll`.
+     */
+    $emit: (key: string, data?: unknown) => void;
+}
+/**
+ * Create an in-memory messaging-interface stand-in for unit-testing an
+ * integration without loading the SDK from the CDN.
+ *
+ * Every method resolves, records itself in `calls`, and keeps just enough
+ * state to behave like the real interface: `sendMessage` appends a
+ * programmatic user message that `getMessages` returns, `open`/`close`/
+ * `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds
+ * `getMetaFields` (sensitive fields are never returned, matching the real
+ * SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.
+ *
+ * Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden
+ * methods are still recorded in `calls`.
+ */
+export declare function createMockAdaMessaging(overrides?: Partial<AdaMessagingInterface>): MockAdaMessaging;

package/dist/npm/testing.d.ts

@@ -0,0 +1,39 @@
+import type { AdaMessagingInterface } from "./loader.js";
+/** One recorded method invocation on a {@link MockAdaMessaging}. */
+export interface RecordedAdaMessagingCall {
+    method: string;
+    args: unknown[];
+}
+/**
+ * The mock returned by {@link createMockAdaMessaging}: the full
+ * {@link AdaMessagingInterface} plus test hooks for inspecting calls and
+ * simulating SDK events.
+ */
+export interface MockAdaMessaging extends AdaMessagingInterface {
+    /** Every method invocation, in call order. */
+    calls: RecordedAdaMessagingCall[];
+    /**
+     * Deliver an event to `subscribeEvent` and `subscribeAll` callbacks, as if
+     * the SDK emitted it (e.g. `$emit("ada:ready", { isRolledOut: true })`).
+     * Routing matches the real SDK: keyed subscriptions match by prefix
+     * (`"ada:campaigns"` catches `"ada:campaigns:shown"`), except the
+     * transcript events `ada:message:sent`/`ada:message:received`, which reach
+     * exact-key subscribers only and never `subscribeAll`.
+     */
+    $emit: (key: string, data?: unknown) => void;
+}
+/**
+ * Create an in-memory messaging-interface stand-in for unit-testing an
+ * integration without loading the SDK from the CDN.
+ *
+ * Every method resolves, records itself in `calls`, and keeps just enough
+ * state to behave like the real interface: `sendMessage` appends a
+ * programmatic user message that `getMessages` returns, `open`/`close`/
+ * `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds
+ * `getMetaFields` (sensitive fields are never returned, matching the real
+ * SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.
+ *
+ * Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden
+ * methods are still recorded in `calls`.
+ */
+export declare function createMockAdaMessaging(overrides?: Partial<AdaMessagingInterface>): MockAdaMessaging;

package/dist/npm/testing.js

@@ -0,0 +1,154 @@
+//#region src/npm/testing.ts
+var EXACT_MATCH_EVENT_KEYS = new Set(["ada:message:sent", "ada:message:received"]);
+function keyedSubscriptionMatches(subscriptionKey, eventKey) {
+	if (EXACT_MATCH_EVENT_KEYS.has(eventKey)) return subscriptionKey === eventKey;
+	return subscriptionKey === eventKey || eventKey.startsWith(subscriptionKey);
+}
+function toMetaFieldRecord(fields) {
+	const record = {};
+	for (const [key, value] of Object.entries(fields)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) record[key] = value;
+	return record;
+}
+/**
+* Create an in-memory messaging-interface stand-in for unit-testing an
+* integration without loading the SDK from the CDN.
+*
+* Every method resolves, records itself in `calls`, and keeps just enough
+* state to behave like the real interface: `sendMessage` appends a
+* programmatic user message that `getMessages` returns, `open`/`close`/
+* `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds
+* `getMetaFields` (sensitive fields are never returned, matching the real
+* SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.
+*
+* Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden
+* methods are still recorded in `calls`.
+*/
+function createMockAdaMessaging(overrides = {}) {
+	const calls = [];
+	let nextSubscriptionId = 1;
+	let nextMessageId = 1;
+	let chatOpen = false;
+	let conversationId = null;
+	const metaFields = {};
+	const messages = [];
+	const keyedSubscriptions = /* @__PURE__ */ new Map();
+	const wildcardSubscriptions = /* @__PURE__ */ new Map();
+	const emit = (key, data) => {
+		for (const subscription of keyedSubscriptions.values()) if (keyedSubscriptionMatches(subscription.key, key)) subscription.callback(data, { eventKey: key });
+		if (EXACT_MATCH_EVENT_KEYS.has(key)) return;
+		for (const callback of wildcardSubscriptions.values()) callback(key, data);
+	};
+	const clearTranscript = () => {
+		messages.length = 0;
+		conversationId = null;
+	};
+	const base = {
+		start: async () => void 0,
+		stop: async () => void 0,
+		toggle: async () => {
+			chatOpen = !chatOpen;
+		},
+		deleteHistory: async () => {
+			clearTranscript();
+		},
+		reset: async () => {
+			clearTranscript();
+		},
+		setMetaFields: async (fields) => {
+			Object.assign(metaFields, toMetaFieldRecord(fields));
+		},
+		setSensitiveMetaFields: async () => void 0,
+		setTestModeBanner: async () => void 0,
+		getInfo: async () => ({
+			isChatOpen: chatOpen,
+			isDrawerOpen: chatOpen,
+			hasActiveChatter: messages.length > 0,
+			hasClosedChat: false
+		}),
+		getMetaFields: async () => ({ ...metaFields }),
+		isOpen: async () => chatOpen,
+		getConversation: async () => ({
+			id: conversationId,
+			handoff: { inLiveChat: false }
+		}),
+		getMessages: async () => [...messages],
+		setComposerText: async () => void 0,
+		setDelegate: () => void 0,
+		trackEvent: async () => void 0,
+		subscribeEvent: async (key, callback) => {
+			const id = nextSubscriptionId++;
+			keyedSubscriptions.set(id, {
+				key,
+				callback
+			});
+			return id;
+		},
+		unsubscribeEvent: async (id) => {
+			keyedSubscriptions.delete(id);
+			wildcardSubscriptions.delete(id);
+		},
+		subscribeAll: async (callback) => {
+			const id = nextSubscriptionId++;
+			wildcardSubscriptions.set(id, callback);
+			return id;
+		},
+		open: async () => {
+			chatOpen = true;
+		},
+		close: async () => {
+			chatOpen = false;
+		},
+		setLanguage: async () => void 0,
+		setTheme: async () => void 0,
+		setDeviceToken: async () => void 0,
+		sendMessage: async (body) => {
+			const id = `mock-message-${nextMessageId++}`;
+			conversationId = conversationId ?? "mock-conversation";
+			messages.push({
+				id,
+				role: "user",
+				type: "text",
+				body,
+				createdAt: Math.floor(Date.now() / 1e3),
+				origin: "programmatic"
+			});
+			return { id };
+		},
+		handleNotification: async () => {
+			chatOpen = true;
+		},
+		requestNotifications: async () => "granted",
+		createProactive: async () => void 0,
+		triggerCampaign: async () => void 0,
+		evaluateCampaignConditions: async () => void 0,
+		closeCampaign: async () => void 0,
+		triggerAnswer: async () => void 0,
+		triggerProactive: async () => void 0,
+		triggerGreeting: async () => void 0,
+		destroy: async () => {
+			keyedSubscriptions.clear();
+			wildcardSubscriptions.clear();
+			chatOpen = false;
+		}
+	};
+	const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0));
+	const implementation = {
+		...base,
+		...definedOverrides
+	};
+	return {
+		...Object.fromEntries(Object.entries(implementation).map(([method, fn]) => [method, (...args) => {
+			calls.push({
+				method,
+				args
+			});
+			return fn(...args);
+		}])),
+		calls,
+		$emit: emit
+	};
+}
+//#endregion
+export { createMockAdaMessaging };
+
+//# sourceMappingURL=testing.js.map

package/dist/npm/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":[],"sources":["../../src/npm/testing.ts"],"sourcesContent":["import type {\n\tAdaSdkEventCallback,\n\tMetaFieldValue,\n\tPublicMessage,\n} from \"../client/client-types\";\nimport type { AdaMessagingInterface } from \"./loader\";\n\n/** One recorded method invocation on a {@link MockAdaMessaging}. */\nexport interface RecordedAdaMessagingCall {\n\tmethod: string;\n\targs: unknown[];\n}\n\n/**\n * The mock returned by {@link createMockAdaMessaging}: the full\n * {@link AdaMessagingInterface} plus test hooks for inspecting calls and\n * simulating SDK events.\n */\nexport interface MockAdaMessaging extends AdaMessagingInterface {\n\t/** Every method invocation, in call order. */\n\tcalls: RecordedAdaMessagingCall[];\n\t/**\n\t * Deliver an event to `subscribeEvent` and `subscribeAll` callbacks, as if\n\t * the SDK emitted it (e.g. `$emit(\"ada:ready\", { isRolledOut: true })`).\n\t * Routing matches the real SDK: keyed subscriptions match by prefix\n\t * (`\"ada:campaigns\"` catches `\"ada:campaigns:shown\"`), except the\n\t * transcript events `ada:message:sent`/`ada:message:received`, which reach\n\t * exact-key subscribers only and never `subscribeAll`.\n\t */\n\t$emit: (key: string, data?: unknown) => void;\n}\n\ninterface KeyedSubscription {\n\tkey: string;\n\tcallback: AdaSdkEventCallback;\n}\n\n// Mirrors EXACT_MATCH_EVENT_KEYS in client/client-host-runtime.ts: transcript\n// events reach exact-key subscribers only, never prefix or subscribeAll\n// subscribers. Duplicated (not imported) so the published testing entry stays\n// free of runtime modules; a drift test pins the mock against the real matcher.\nconst EXACT_MATCH_EVENT_KEYS = new Set([\n\t\"ada:message:sent\",\n\t\"ada:message:received\",\n]);\n\nfunction keyedSubscriptionMatches(\n\tsubscriptionKey: string,\n\teventKey: string,\n): boolean {\n\tif (EXACT_MATCH_EVENT_KEYS.has(eventKey)) {\n\t\treturn subscriptionKey === eventKey;\n\t}\n\t// Raw prefix match, same as the real SDK: \"ada:campaigns\" also catches\n\t// \"ada:campaigns:shown\" and underscore-suffixed keys.\n\treturn subscriptionKey === eventKey || eventKey.startsWith(subscriptionKey);\n}\n\nfunction toMetaFieldRecord(\n\tfields: Record<string, unknown>,\n): Record<string, MetaFieldValue> {\n\tconst record: Record<string, MetaFieldValue> = {};\n\tfor (const [key, value] of Object.entries(fields)) {\n\t\tif (\n\t\t\ttypeof value === \"string\" ||\n\t\t\ttypeof value === \"number\" ||\n\t\t\ttypeof value === \"boolean\" ||\n\t\t\tvalue === null\n\t\t) {\n\t\t\trecord[key] = value;\n\t\t}\n\t}\n\treturn record;\n}\n\n/**\n * Create an in-memory messaging-interface stand-in for unit-testing an\n * integration without loading the SDK from the CDN.\n *\n * Every method resolves, records itself in `calls`, and keeps just enough\n * state to behave like the real interface: `sendMessage` appends a\n * programmatic user message that `getMessages` returns, `open`/`close`/\n * `toggle` drive `isOpen` and `getInfo`, `setMetaFields` feeds\n * `getMetaFields` (sensitive fields are never returned, matching the real\n * SDK), and `$emit` fans out to `subscribeEvent`/`subscribeAll` callbacks.\n *\n * Pass `overrides` to replace any method (e.g. with `vi.fn()`); overridden\n * methods are still recorded in `calls`.\n */\nexport function createMockAdaMessaging(\n\toverrides: Partial<AdaMessagingInterface> = {},\n): MockAdaMessaging {\n\tconst calls: RecordedAdaMessagingCall[] = [];\n\tlet nextSubscriptionId = 1;\n\tlet nextMessageId = 1;\n\tlet chatOpen = false;\n\tlet conversationId: string | null = null;\n\tconst metaFields: Record<string, MetaFieldValue> = {};\n\tconst messages: PublicMessage[] = [];\n\tconst keyedSubscriptions = new Map<number, KeyedSubscription>();\n\tconst wildcardSubscriptions = new Map<\n\t\tnumber,\n\t\t(key: string, data: unknown) => void\n\t>();\n\n\tconst emit = (key: string, data?: unknown): void => {\n\t\tfor (const subscription of keyedSubscriptions.values()) {\n\t\t\tif (keyedSubscriptionMatches(subscription.key, key)) {\n\t\t\t\tsubscription.callback(data, { eventKey: key });\n\t\t\t}\n\t\t}\n\t\tif (EXACT_MATCH_EVENT_KEYS.has(key)) {\n\t\t\treturn;\n\t\t}\n\t\tfor (const callback of wildcardSubscriptions.values()) {\n\t\t\tcallback(key, data);\n\t\t}\n\t};\n\n\tconst clearTranscript = (): void => {\n\t\tmessages.length = 0;\n\t\tconversationId = null;\n\t};\n\n\tconst base: AdaMessagingInterface = {\n\t\tstart: async () => undefined,\n\t\tstop: async () => undefined,\n\t\ttoggle: async () => {\n\t\t\tchatOpen = !chatOpen;\n\t\t},\n\t\tdeleteHistory: async () => {\n\t\t\tclearTranscript();\n\t\t},\n\t\treset: async () => {\n\t\t\tclearTranscript();\n\t\t},\n\t\tsetMetaFields: async (fields) => {\n\t\t\tObject.assign(metaFields, toMetaFieldRecord(fields));\n\t\t},\n\t\t// Sensitive fields are accepted but never readable back, matching the\n\t\t// real SDK's getMetaFields contract.\n\t\tsetSensitiveMetaFields: async () => undefined,\n\t\tsetTestModeBanner: async () => undefined,\n\t\tgetInfo: async () => ({\n\t\t\tisChatOpen: chatOpen,\n\t\t\tisDrawerOpen: chatOpen,\n\t\t\thasActiveChatter: messages.length > 0,\n\t\t\thasClosedChat: false,\n\t\t}),\n\t\tgetMetaFields: async () => ({ ...metaFields }),\n\t\tisOpen: async () => chatOpen,\n\t\tgetConversation: async () => ({\n\t\t\tid: conversationId,\n\t\t\thandoff: { inLiveChat: false },\n\t\t}),\n\t\tgetMessages: async () => [...messages],\n\t\tsetComposerText: async () => undefined,\n\t\tsetDelegate: () => undefined,\n\t\ttrackEvent: async () => undefined,\n\t\tsubscribeEvent: async (key, callback) => {\n\t\t\tconst id = nextSubscriptionId++;\n\t\t\tkeyedSubscriptions.set(id, { key, callback });\n\t\t\treturn id;\n\t\t},\n\t\tunsubscribeEvent: async (id) => {\n\t\t\tkeyedSubscriptions.delete(id);\n\t\t\twildcardSubscriptions.delete(id);\n\t\t},\n\t\tsubscribeAll: async (callback) => {\n\t\t\tconst id = nextSubscriptionId++;\n\t\t\twildcardSubscriptions.set(id, callback);\n\t\t\treturn id;\n\t\t},\n\t\topen: async () => {\n\t\t\tchatOpen = true;\n\t\t},\n\t\tclose: async () => {\n\t\t\tchatOpen = false;\n\t\t},\n\t\tsetLanguage: async () => undefined,\n\t\tsetTheme: async () => undefined,\n\t\tsetDeviceToken: async () => undefined,\n\t\tsendMessage: async (body) => {\n\t\t\tconst id = `mock-message-${nextMessageId++}`;\n\t\t\tconversationId = conversationId ?? \"mock-conversation\";\n\t\t\tmessages.push({\n\t\t\t\tid,\n\t\t\t\trole: \"user\",\n\t\t\t\ttype: \"text\",\n\t\t\t\tbody,\n\t\t\t\tcreatedAt: Math.floor(Date.now() / 1000),\n\t\t\t\torigin: \"programmatic\",\n\t\t\t});\n\t\t\treturn { id };\n\t\t},\n\t\thandleNotification: async () => {\n\t\t\tchatOpen = true;\n\t\t},\n\t\trequestNotifications: async () => \"granted\",\n\t\tcreateProactive: async () => undefined,\n\t\ttriggerCampaign: async () => undefined,\n\t\tevaluateCampaignConditions: async () => undefined,\n\t\tcloseCampaign: async () => undefined,\n\t\ttriggerAnswer: async () => undefined,\n\t\ttriggerProactive: async () => undefined,\n\t\ttriggerGreeting: async () => undefined,\n\t\tdestroy: async () => {\n\t\t\tkeyedSubscriptions.clear();\n\t\t\twildcardSubscriptions.clear();\n\t\t\tchatOpen = false;\n\t\t},\n\t};\n\n\tconst definedOverrides = Object.fromEntries(\n\t\tObject.entries(overrides).filter(([, value]) => value !== undefined),\n\t);\n\tconst implementation = { ...base, ...definedOverrides };\n\tconst recorded = Object.fromEntries(\n\t\tObject.entries(implementation).map(([method, fn]) => [\n\t\t\tmethod,\n\t\t\t(...args: unknown[]) => {\n\t\t\t\tcalls.push({ method, args });\n\t\t\t\treturn (fn as (...callArgs: unknown[]) => unknown)(...args);\n\t\t\t},\n\t\t]),\n\t) as unknown as AdaMessagingInterface;\n\n\treturn { ...recorded, calls, $emit: emit };\n}\n"],"mappings":";AAyCA,IAAM,yBAAyB,IAAI,IAAI,CACtC,oBACA,uBACA,CAAC;AAEF,SAAS,yBACR,iBACA,UACU;AACV,KAAI,uBAAuB,IAAI,SAAS,CACvC,QAAO,oBAAoB;AAI5B,QAAO,oBAAoB,YAAY,SAAS,WAAW,gBAAgB;;AAG5E,SAAS,kBACR,QACiC;CACjC,MAAM,SAAyC,EAAE;AACjD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAChD,KACC,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,aACjB,UAAU,KAEV,QAAO,OAAO;AAGhB,QAAO;;;;;;;;;;;;;;;;AAiBR,SAAgB,uBACf,YAA4C,EAAE,EAC3B;CACnB,MAAM,QAAoC,EAAE;CAC5C,IAAI,qBAAqB;CACzB,IAAI,gBAAgB;CACpB,IAAI,WAAW;CACf,IAAI,iBAAgC;CACpC,MAAM,aAA6C,EAAE;CACrD,MAAM,WAA4B,EAAE;CACpC,MAAM,qCAAqB,IAAI,KAAgC;CAC/D,MAAM,wCAAwB,IAAI,KAG/B;CAEH,MAAM,QAAQ,KAAa,SAAyB;AACnD,OAAK,MAAM,gBAAgB,mBAAmB,QAAQ,CACrD,KAAI,yBAAyB,aAAa,KAAK,IAAI,CAClD,cAAa,SAAS,MAAM,EAAE,UAAU,KAAK,CAAC;AAGhD,MAAI,uBAAuB,IAAI,IAAI,CAClC;AAED,OAAK,MAAM,YAAY,sBAAsB,QAAQ,CACpD,UAAS,KAAK,KAAK;;CAIrB,MAAM,wBAA8B;AACnC,WAAS,SAAS;AAClB,mBAAiB;;CAGlB,MAAM,OAA8B;EACnC,OAAO,YAAY,KAAA;EACnB,MAAM,YAAY,KAAA;EAClB,QAAQ,YAAY;AACnB,cAAW,CAAC;;EAEb,eAAe,YAAY;AAC1B,oBAAiB;;EAElB,OAAO,YAAY;AAClB,oBAAiB;;EAElB,eAAe,OAAO,WAAW;AAChC,UAAO,OAAO,YAAY,kBAAkB,OAAO,CAAC;;EAIrD,wBAAwB,YAAY,KAAA;EACpC,mBAAmB,YAAY,KAAA;EAC/B,SAAS,aAAa;GACrB,YAAY;GACZ,cAAc;GACd,kBAAkB,SAAS,SAAS;GACpC,eAAe;GACf;EACD,eAAe,aAAa,EAAE,GAAG,YAAY;EAC7C,QAAQ,YAAY;EACpB,iBAAiB,aAAa;GAC7B,IAAI;GACJ,SAAS,EAAE,YAAY,OAAO;GAC9B;EACD,aAAa,YAAY,CAAC,GAAG,SAAS;EACtC,iBAAiB,YAAY,KAAA;EAC7B,mBAAmB,KAAA;EACnB,YAAY,YAAY,KAAA;EACxB,gBAAgB,OAAO,KAAK,aAAa;GACxC,MAAM,KAAK;AACX,sBAAmB,IAAI,IAAI;IAAE;IAAK;IAAU,CAAC;AAC7C,UAAO;;EAER,kBAAkB,OAAO,OAAO;AAC/B,sBAAmB,OAAO,GAAG;AAC7B,yBAAsB,OAAO,GAAG;;EAEjC,cAAc,OAAO,aAAa;GACjC,MAAM,KAAK;AACX,yBAAsB,IAAI,IAAI,SAAS;AACvC,UAAO;;EAER,MAAM,YAAY;AACjB,cAAW;;EAEZ,OAAO,YAAY;AAClB,cAAW;;EAEZ,aAAa,YAAY,KAAA;EACzB,UAAU,YAAY,KAAA;EACtB,gBAAgB,YAAY,KAAA;EAC5B,aAAa,OAAO,SAAS;GAC5B,MAAM,KAAK,gBAAgB;AAC3B,oBAAiB,kBAAkB;AACnC,YAAS,KAAK;IACb;IACA,MAAM;IACN,MAAM;IACN;IACA,WAAW,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;IACxC,QAAQ;IACR,CAAC;AACF,UAAO,EAAE,IAAI;;EAEd,oBAAoB,YAAY;AAC/B,cAAW;;EAEZ,sBAAsB,YAAY;EAClC,iBAAiB,YAAY,KAAA;EAC7B,iBAAiB,YAAY,KAAA;EAC7B,4BAA4B,YAAY,KAAA;EACxC,eAAe,YAAY,KAAA;EAC3B,eAAe,YAAY,KAAA;EAC3B,kBAAkB,YAAY,KAAA;EAC9B,iBAAiB,YAAY,KAAA;EAC7B,SAAS,YAAY;AACpB,sBAAmB,OAAO;AAC1B,yBAAsB,OAAO;AAC7B,cAAW;;EAEZ;CAED,MAAM,mBAAmB,OAAO,YAC/B,OAAO,QAAQ,UAAU,CAAC,QAAQ,GAAG,WAAW,UAAU,KAAA,EAAU,CACpE;CACD,MAAM,iBAAiB;EAAE,GAAG;EAAM,GAAG;EAAkB;AAWvD,QAAO;EAAE,GAVQ,OAAO,YACvB,OAAO,QAAQ,eAAe,CAAC,KAAK,CAAC,QAAQ,QAAQ,CACpD,SACC,GAAG,SAAoB;AACvB,SAAM,KAAK;IAAE;IAAQ;IAAM,CAAC;AAC5B,UAAQ,GAA2C,GAAG,KAAK;IAE5D,CAAC,CACF;EAEqB;EAAO,OAAO;EAAM"}

package/dist/sdk-module-loader.d.ts

@@ -0,0 +1 @@
+export declare function loadMessagingSdkModule(scriptUrl: string): Promise<unknown>;

package/dist/shared-utils/clusters.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canonical set of supported Ada rollout clusters.
+ * Both sdk and core reference this set for cluster validation.
+ */
+export declare const VALID_ADA_CLUSTERS: Set<string>;

package/dist/shared-utils/csat.d.ts

@@ -0,0 +1,116 @@
+export declare const CSAT_INTEGRATION_ID: "csat";
+export declare const CSAT_SUBMIT_ACTION: "survey.submit";
+export declare const CSAT_SUBMITTED_ACTION_ALIAS: "survey.submitted";
+export declare const CSAT_CHANNEL_NAME: "integration.csat";
+export declare const CSAT_CONFIG_SET_TYPE: "integration.config.set";
+export declare const CSAT_RESULT_TYPE: "integration.result";
+export declare const CSAT_SURVEY_TYPES: readonly [
+	"answer_flow",
+	"proactive",
+	"end_chat",
+	"live_chat",
+];
+export type CsatSurveyType = (typeof CSAT_SURVEY_TYPES)[number];
+export declare function isCsatSurveyType(
+	value: unknown,
+): value is CsatSurveyType;
+export declare const POST_AGENT_CSAT_SURVEY_TYPES: ReadonlySet<CsatSurveyType>;
+export declare function isPostAgentCsatSurveyType(value: string): boolean;
+export declare function isCsatSubmitAction(action: string): boolean;
+export declare function normalizeCsatSubmitAction(action: string): string;
+/**
+ * The four `csat_style` values accepted by the Ada API on
+ * `/surveys/submit_survey` (see `api/internal_apis/surveys/spec.yml` and
+ * `api/core/feedback/surveys/models/csat_styles.py`).
+ */
+export declare const CSAT_STYLE_API_VALUES: readonly [
+	"NUMERIC",
+	"NUMERIC_TEN",
+	"THUMBS",
+	"EMOJI",
+];
+export type CsatStyleApiValue = (typeof CSAT_STYLE_API_VALUES)[number];
+export interface CsatApiScoreAndStyle {
+	score: number;
+	style: CsatStyleApiValue;
+}
+/**
+ * Translates a messaging UI scale string (`"1-5"`, `"1-10"`, `"emoji"`) to the
+ * corresponding API enum value accepted by `/surveys/submit_survey`
+ * (`NUMERIC`, `NUMERIC_TEN`, `EMOJI`).
+ *
+ * Returns `null` when the scale cannot be represented by the API enum without
+ * also transforming the score. Use `toCsatApiScoreAndStyle` for outbound
+ * `/surveys/submit_survey` payloads.
+ *
+ * Intentionally NOT mapped (returns `null`):
+ *
+ *  - `"1-7"` — API has no `NUMERIC_SEVEN`; collapsing to `NUMERIC` would let
+ *    the UI emit `csat_score=7`, which the API rejects when `csat_style="NUMERIC"`
+ *    (NUMERIC range is 1–5, see `api/internal_apis/surveys/spec.yml`).
+ *  - `"0-10"` — API has no `NUMERIC_TEN_WITH_ZERO`; collapsing to `NUMERIC_TEN`
+ *    would let `csat_score=0` slip through, which `NUMERIC_TEN` (range 1–10)
+ *    rejects.
+ *  - `"thumbs"` — messaging's UI emits `csat_score=1` / `csat_score=5` for
+ *    thumbs-down/thumbs-up, but API `THUMBS` expects `0/1`. This is handled by
+ *    `toCsatApiScoreAndStyle`.
+ *
+ * Pass-through: callers that already supply one of the four canonical API
+ * values get them back unchanged.
+ */
+export declare function toCsatStyleApiValue(
+	uiStyle: string | null | undefined,
+): CsatStyleApiValue | null;
+/**
+ * Converts the score/style pair emitted by messaging UI into the raw integer
+ * pair accepted by the current `/surveys/submit_survey` API.
+ *
+ * The API validates scores as native values for the provided `csat_style`:
+ * `NUMERIC`/`EMOJI` 1-5, `NUMERIC_TEN` 1-10, `THUMBS` 0-1. Messaging's thumbs
+ * UI still emits legacy 5-point values (1 = down, 5 = up), so this helper maps
+ * them to API-native 0/1 before the request.
+ *
+ * Missing, unknown, and unsupported legacy satisfaction scales (`1-7`, `0-10`)
+ * return `null` because the current API requires `csat_style` when
+ * `csat_score` is provided and has no matching style for those legacy scales.
+ */
+export declare function toCsatApiScoreAndStyle(
+	score: number,
+	uiStyle: string | null | undefined,
+): CsatApiScoreAndStyle | null;
+/**
+ * The inverse of {@link toCsatApiScoreAndStyle}: turns a stored `csat_score` /
+ * `csat_style` pair back into the score and scale string the UI renders on.
+ *
+ * Only `THUMBS` needs the score itself moved — messaging's thumbs UI selects on
+ * the legacy 5-point values (1 = down, 5 = up) while the API stores 0/1, so a
+ * restored thumbs answer would otherwise select no chip at all.
+ *
+ * Returns `null` when the pair cannot be rendered, which callers read as "start
+ * with no satisfaction answer" rather than as an error.
+ */
+export declare function fromCsatApiScoreAndStyle(
+	score: unknown,
+	apiStyle: unknown,
+): {
+	score: number;
+	style: string;
+} | null;
+/**
+ * The inverse of {@link toCsatStyleApiValue}: maps an API enum value back to
+ * the lowercase UI scale string that messaging's UI renderers (`CsatSurveyForm`,
+ * `CsatPromptSheet`, `CsatInlineBlock`) branch on. The `/csat_settings`
+ * response and the `csat` log message both serialize `satisfaction_style` /
+ * `scale_type` as the API's uppercase enum (`THUMBS`, `EMOJI`, `NUMERIC`,
+ * `NUMERIC_TEN`), so without this translation the UI silently falls through
+ * to the `"1-5"` default and renders the wrong scale.
+ *
+ * Strings that are already in the UI's lowercase format (e.g. `"1-7"`,
+ * `"0-10"`, `"thumbs"`, `"emoji"`) are returned unchanged so legacy payloads
+ * keep working.
+ *
+ * Returns `null` only when given a non-string or empty input.
+ */
+export declare function fromCsatStyleApiValue(
+	apiStyle: string | null | undefined,
+): string | null;

package/dist/shared-utils/host-telemetry.d.ts

@@ -0,0 +1,35 @@
+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 interface HostTelemetryContext {
+	surface: HostTelemetrySurface;
+	hostPlatform: HostTelemetryPlatform;
+	webSdkOrigin: HostTelemetryWebSdkOrigin;
+	mobileShell?: HostTelemetryMobileShell;
+	mobilePackage?: string;
+	mobileVersion?: string;
+}
+export declare function sanitizeHostTelemetryContext(
+	value: unknown,
+): HostTelemetryContext | undefined;
+export declare function resolveHostTelemetryContext(
+	hostTelemetry: HostTelemetryContext | undefined,
+	{
+		defaultOrigin,
+		defaultSurface,
+		defaultPlatform,
+	}: {
+		defaultOrigin: HostTelemetryWebSdkOrigin;
+		defaultSurface: HostTelemetrySurface;
+		defaultPlatform?: HostTelemetryPlatform;
+	},
+): HostTelemetryContext;
+export declare function toHostTelemetryMonitoringContext(
+	hostTelemetry: HostTelemetryContext,
+): Record<string, string>;

package/dist/shared-utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./clusters.js";
+export * from "./csat.js";
+export * from "./host-telemetry.js";