@askdialog/dialog-sdk 2.4.0 → 2.6.0

package/README.md

@@ -91,6 +91,15 @@ The getProduct function is used to display product information in the assistant.
 
 When the client is instantiated, it will automatically insert into the DOM the Dialog Assistant script, so you can interact with the assistant using `sendProductMessage` or `sendGenericMessage`. This assistant runtime always loads — it owns the shopper identity, consent handling and analytics bridge — while the heavy assistant UI stays lazy-loaded and is not fetched eagerly.
 
+### OneTrust auto-blocking
+
+If your site uses OneTrust auto-blocking, it may neutralize the assistant script injected by the SDK (`type` rewritten to `text/plain`) for visitors who declined cookies — a `data-ot-ignore` on your own SDK `<script>` tag does not cover dynamically injected scripts. Two remedies, both merchant-side decisions:
+
+- categorize the assistant CDN domain as strictly necessary in your OneTrust console, or
+- pass the optional `ignoreOneTrustAutoBlock: true` constructor flag so the SDK adds `data-ot-ignore` on the script it injects.
+
+Either is compliance-safe with regard to analytics: the assistant gates all analytics on consent internally and sends nothing without an explicit opt-in (inspect `window.dialog.audit.consent`).
+
 ### Getters
 
 - apiKey
@@ -179,6 +188,7 @@ const response: SearchResponse = await client.search({
   query: 'shampoo',
   page: 0, // optional, zero-indexed (default 0)
   hitsPerPage: 20, // optional, 1-100 (default 20)
+  queryId: previousResponse?.queryId, // optional, resend while the query is unchanged
 });
 // response.hits[n].product: { id, title?, url?, imageUrl?, priceRange?, inStock? }
 ```
@@ -195,32 +205,56 @@ With the IIFE bundle the results are plain runtime JSON (same shape, no types):
 
 A non-2xx answer rejects with `DialogSearchError` — stable `name`, HTTP `status`, optional machine-readable `code` (e.g. `SEARCH_INDEX_NOT_FOUND`) and `message`. Aborting rejects with the native `AbortError`, and network failures keep their native errors.
 
-The SDK is stateless: no debounce, no cache, no automatic cancellation of previous searches. For search-as-you-type, own those in the integration:
+`client.search()` itself is stateless: no debounce, no cache, no automatic cancellation of previous searches. For search-as-you-type, use the search controller below instead of hand-rolling those.
+
+- Search controller
+
+`createSearchController()` wraps the stateless transport with the stateful behavior every search UI needs — debounce (immediate on explicit submission), cancellation of the in-flight request, stale-response protection (a late response never replaces newer results, even if the transport ignores the abort), pagination that resets on a new query, `idle` / `loading` / `success` / `empty` / `error` states, retry, and the DEC-2448 attribution events (`view_search_results` viewport impressions, `select_search_result` clicks) with a consistent `query_id`. It has no framework or rendering dependency: raw JavaScript, React, Vue and Shopify integrations are rendering-and-routing adapters around it.
 
 ```typescript
-let controller: AbortController | undefined;
-let latestRequestId = 0;
-let debounceTimer: number | undefined;
-
-const onInput = (query: string) => {
-  window.clearTimeout(debounceTimer);
-  debounceTimer = window.setTimeout(async () => {
-    controller?.abort(); // cancel the in-flight request
-    controller = new AbortController();
-    const requestId = ++latestRequestId;
-    try {
-      const response = await client.search({ query }, { signal: controller.signal });
-      if (requestId !== latestRequestId) return; // stale response, ignore
-      render(response.hits);
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'AbortError') return;
-      if (error instanceof DialogSearchError) renderError(error.message);
-      else throw error;
-    }
-  }, 200);
-};
+import { createSearchController, Dialog, SearchStatus } from '@askdialog/dialog-sdk';
+
+const client = new Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr' });
+
+const controller = createSearchController({
+  search: (request, options) => client.search(request, options),
+  analytics: {
+    surface: 'search_page', // where results are displayed
+    trackViewSearchResults: (params) => client.trackViewSearchResults(params),
+    trackSelectSearchResult: (params) => client.trackSelectSearchResult(params),
+  },
+  navigate: (url) => router.push(url), // optional platform routing adapter
+  debounceMs: 250, // optional (default 250)
+  hitsPerPage: 12, // optional (default 12)
+});
+
+const unsubscribe = controller.subscribe((state) => {
+  // state: { status, query, page, response?, error? }
+  if (state.status === SearchStatus.SUCCESS) {
+    renderCards(state.response.hits).forEach((element, index) => {
+      controller.observeResult(element, index); // viewport impression
+      element.onclick = () => controller.selectResult(index); // attribution, then `navigate`
+    });
+  }
+});
+
+input.oninput = () => controller.setQuery(input.value); // debounced
+form.onsubmit = () => controller.submit(input.value); // immediate
+nextButton.onclick = () => controller.setPage(controller.getState().page + 1);
+retryButton.onclick = () => controller.retry();
+// On teardown (SPA unmount): cancel in-flight work and detach observers.
+controller.dispose();
 ```
 
+The adapter contract for a framework binding (React, Vue, Shopify):
+
+- **Rendering** — subscribe to the controller (`subscribe`/`getState` fit React's `useSyncExternalStore` and a Vue `shallowRef` updated by the listener) and render the five states; never re-implement debounce, `AbortController` or race protection locally.
+- **Attribution** — call `observeResult(element, index)` for every rendered result and `selectResult(index)` on every result click (including middle-click/cmd+click). Do not `preventDefault` a same-tab navigation: attribution is recorded first and the events survive it.
+- **Routing** — platform navigation and URL synchronization (query params, history) stay in the adapter: pass `navigate` for router-driven platforms, or let plain `<a href>` links navigate natively.
+- **Lifecycle** — create one controller per search surface and `dispose()` it on unmount.
+
+The raw JavaScript reference adapter lives in [`packages/search-example`](../search-example).
+
 - Handler for fetch product
 
 The `getProduct` callback is called by the assistant to display product information. You must return an object matching the `SimplifiedProduct` interface.

package/dist/Dialog.d.ts

@@ -4,6 +4,7 @@ import { DetailedLocaleInfo } from "./utils/localization";
 import { Suggestion } from "./types/suggestion";
 import { AddToCartInput, GenericQuestionPayload, LegacyCheckoutParams, OpenAssistantPayload, ProductQuestionPayload, SubmitCheckoutParams } from "./types/events";
 import { SimplifiedProduct } from "./types/product";
+import { SelectSearchResultParams, ViewSearchResultsParams } from "./types/searchAnalytics";
 import { EventsHandler } from "./EventsHandler";
 import { SearchOptions, SearchRequest, SearchResponse } from "./types/search";
 import { AssistantEvent } from "./types/assistantEvent";
@@ -16,7 +17,8 @@ export declare class Dialog {
     private _theme;
     private _userId;
     private _eventsHandler;
-    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, }: DialogConstructor);
+    private _ignoreOneTrustAutoBlock;
+    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, }: DialogConstructor);
     get apiKey(): string;
     get theme(): Theme;
     get userId(): string;
@@ -44,6 +46,17 @@ export declare class Dialog {
     private _getCallbacksOrThrow;
     registerAddToCartEvent(input: AddToCartInput): void;
     registerSubmitCheckoutEvent(params: SubmitCheckoutParams | LegacyCheckoutParams): void;
+    /**
+     * Emit a batch of viewport impressions. The batching/dedup semantics live
+     * in `createSearchImpressionTracker` — wire its `emit` here, or call
+     * directly with `items: []` for a rendered no-results state.
+     */
+    trackViewSearchResults(params: ViewSearchResultsParams): void;
+    /**
+     * Emit on a result click — including auxclick / cmd+click, not only before
+     * a same-tab navigation. Force the clicked item's impression first.
+     */
+    trackSelectSearchResult(params: SelectSearchResultParams): void;
     private _loadAssistant;
 }
 //# sourceMappingURL=Dialog.d.ts.map

package/dist/Dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../src/Dialog.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,kBAAkB,EAEnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,cAAc,EAEd,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,qBAAa,MAAM;IACjB,gBAAuB,OAAO,SAAuB;IAErD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAE9B,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAgB;gBAE1B,EACV,MAAM,EACN,MAAM,EACN,WAAW,EACX,SAAS,EACT,KAAK,EACL,MAAM,GACP,EAAE,iBAAiB;IAYpB,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,KAAK,IAAI,KAAK,CAExB;IACD,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,aAAa,IAAI,aAAa,CAExC;IAEM,2BAA2B,IAAI,kBAAkB,GAAG,IAAI;IAI/D,OAAO,CAAC,uBAAuB;IAkBlB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAInE;;;;;;OAMG;IACI,MAAM,CACX,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,cAAc,CAAC;IAKnB,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAKjD,cAAc,IAAI,IAAI;IAItB,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAIxD,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAOxD,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAIjE,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAInD,UAAU,CACf,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAUhB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5D,OAAO,CAAC,oBAAoB;IAUrB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAcnD,2BAA2B,CAChC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,GAClD,IAAI;IA0BP,OAAO,CAAC,cAAc;CA4BvB"}
+{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../src/Dialog.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,kBAAkB,EAEnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,cAAc,EAEd,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,qBAAa,MAAM;IACjB,gBAAuB,OAAO,SAAuB;IAErD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAE9B,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,wBAAwB,CAAU;gBAE9B,EACV,MAAM,EACN,MAAM,EACN,WAAW,EACX,SAAS,EACT,KAAK,EACL,MAAM,EACN,uBAAuB,GACxB,EAAE,iBAAiB;IAapB,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,KAAK,IAAI,KAAK,CAExB;IACD,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,MAAM,IAAI,MAAM,CAE1B;IACD,IAAW,aAAa,IAAI,aAAa,CAExC;IAEM,2BAA2B,IAAI,kBAAkB,GAAG,IAAI;IAI/D,OAAO,CAAC,uBAAuB;IAkBlB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAInE;;;;;;OAMG;IACI,MAAM,CACX,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,cAAc,CAAC;IAKnB,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAKjD,cAAc,IAAI,IAAI;IAItB,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAIxD,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAOxD,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAIjE,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAInD,UAAU,CACf,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAUhB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5D,OAAO,CAAC,oBAAoB;IAUrB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAcnD,2BAA2B,CAChC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,GAClD,IAAI;IA0BP;;;;OAIG;IACI,sBAAsB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAUpE;;;OAGG;IACI,uBAAuB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI;IAUtE,OAAO,CAAC,cAAc;CAkCvB"}

package/dist/Dialog.js

@@ -19,11 +19,13 @@ export class Dialog {
     _theme;
     _userId;
     _eventsHandler;
-    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, }) {
+    _ignoreOneTrustAutoBlock;
+    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, }) {
         this._apiKey = apiKey;
         this._locale = locale;
         this._countryCode = countryCode;
         this._callbacks = callbacks;
+        this._ignoreOneTrustAutoBlock = ignoreOneTrustAutoBlock ?? false;
         this._theme = { ...defaultTheme, ...theme };
         this._userId = this._createOrRetrieveUserId(userId);
         this._eventsHandler = new EventsHandler(locale, userId);
@@ -146,6 +148,27 @@ export class Dialog {
             currency: params.currency,
         });
     }
+    /**
+     * Emit a batch of viewport impressions. The batching/dedup semantics live
+     * in `createSearchImpressionTracker` — wire its `emit` here, or call
+     * directly with `items: []` for a rendered no-results state.
+     */
+    trackViewSearchResults(params) {
+        this._eventsHandler.emitExternalEvent(DialogEvents.TRACK_VIEW_SEARCH_RESULTS, {
+            userId: this._userId,
+            ...params,
+        });
+    }
+    /**
+     * Emit on a result click — including auxclick / cmd+click, not only before
+     * a same-tab navigation. Force the clicked item's impression first.
+     */
+    trackSelectSearchResult(params) {
+        this._eventsHandler.emitExternalEvent(DialogEvents.TRACK_SELECT_SEARCH_RESULT, {
+            userId: this._userId,
+            ...params,
+        });
+    }
     _loadAssistant() {
         const localeInfo = getDetailedLocaleInfo(this._locale, this._countryCode);
         if (localeInfo === null) {
@@ -167,6 +190,12 @@ export class Dialog {
             script.async = true;
             script.type = "module";
             script.src = config.assistantUrl;
+            if (this._ignoreOneTrustAutoBlock) {
+                // OneTrust auto-blocking also intercepts dynamically injected scripts
+                // (by domain), so the merchant's data-ot-ignore on their own SDK tag
+                // cannot cover this one — it has to be set here.
+                script.setAttribute("data-ot-ignore", "");
+            }
             document.head.insertBefore(script, document.head.firstChild);
         }, 50);
     }

package/dist/EventsHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EventsHandler.d.ts","sourceRoot":"","sources":["../src/EventsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,EAEb,4BAA4B,EAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAuB,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAehF,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAuB;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAKpC,iBAAiB,CACtB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,GAC/B,IAAI;IAYA,mBAAmB,IAAI,IAAI;IAU3B,kBAAkB,IAAI,IAAI;IAIjC,OAAO,CAAC,sBAAsB;IAWvB,kBAAkB,CACvB,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAC5B,OAAO,CAAC,EAAE,4BAA4B,GACrC,IAAI;IAQA,gBAAgB,CACrB,QAAQ,EAAE,CACR,KAAK,EAAE,cAAc,CAAC,aAAa,GAAG,qBAAqB,CAAC,KACzD,IAAI,GACR,MAAM,IAAI;CA0Bd"}
+{"version":3,"file":"EventsHandler.d.ts","sourceRoot":"","sources":["../src/EventsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,EAEb,4BAA4B,EAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAuB,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAiBhF,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAuB;gBAElC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAKpC,iBAAiB,CACtB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,GAC/B,IAAI;IAYA,mBAAmB,IAAI,IAAI;IAU3B,kBAAkB,IAAI,IAAI;IAIjC,OAAO,CAAC,sBAAsB;IAWvB,kBAAkB,CACvB,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAC5B,OAAO,CAAC,EAAE,4BAA4B,GACrC,IAAI;IAQA,gBAAgB,CACrB,QAAQ,EAAE,CACR,KAAK,EAAE,cAAc,CAAC,aAAa,GAAG,qBAAqB,CAAC,KACzD,IAAI,GACR,MAAM,IAAI;CA0Bd"}

package/dist/EventsHandler.js

@@ -6,6 +6,8 @@ import { DIALOG_CUSTOM_EVENT, DialogEvents } from "./types/events";
 const BUFFERED_EVENT_TYPES = new Set([
     DialogEvents.TRACK_ADD_TO_CART,
     DialogEvents.TRACK_SUBMIT_CHECKOUT,
+    DialogEvents.TRACK_VIEW_SEARCH_RESULTS,
+    DialogEvents.TRACK_SELECT_SEARCH_RESULT,
 ]);
 export class EventsHandler {
     _locale;

package/dist/__tests__/dialogLoadAssistant.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dialogLoadAssistant.spec.d.ts.map

package/dist/__tests__/dialogLoadAssistant.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogLoadAssistant.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/dialogLoadAssistant.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/dialogLoadAssistant.spec.js

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Dialog } from "../Dialog";
+// The full Dialog constructor touches window/localStorage; these tests only
+// exercise the assistant script injection, so the instance is built from the
+// prototype with just the fields _loadAssistant reads.
+const buildDialog = (ignoreOneTrustAutoBlock) => {
+    const dialog = Object.create(Dialog.prototype);
+    Object.assign(dialog, {
+        _apiKey: "api-key-1",
+        _userId: "user-1",
+        _locale: "fr-FR",
+        _ignoreOneTrustAutoBlock: ignoreOneTrustAutoBlock,
+    });
+    return dialog;
+};
+const stubDocument = () => {
+    const script = { setAttribute: vi.fn() };
+    const insertBefore = vi.fn();
+    vi.stubGlobal("document", {
+        createElement: (tag) => tag === "script" ? script : { dataset: {} },
+        body: { appendChild: vi.fn() },
+        head: { insertBefore, firstChild: null },
+    });
+    return { script, insertBefore };
+};
+const loadAssistant = (dialog) => {
+    dialog._loadAssistant();
+    vi.advanceTimersByTime(50);
+};
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+    vi.clearAllMocks();
+});
+describe("Dialog._loadAssistant OneTrust exemption", () => {
+    it("sets data-ot-ignore on the injected script when opted in", () => {
+        vi.useFakeTimers();
+        const { script, insertBefore } = stubDocument();
+        loadAssistant(buildDialog(true));
+        expect(script.setAttribute).toHaveBeenCalledWith("data-ot-ignore", "");
+        expect(insertBefore).toHaveBeenCalledWith(script, null);
+    });
+    it("leaves the injected script untouched by default", () => {
+        vi.useFakeTimers();
+        const { script, insertBefore } = stubDocument();
+        loadAssistant(buildDialog(false));
+        expect(script.setAttribute).not.toHaveBeenCalled();
+        expect(insertBefore).toHaveBeenCalledWith(script, null);
+    });
+});

package/dist/__tests__/dialogSearchAnalytics.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dialogSearchAnalytics.spec.d.ts.map

package/dist/__tests__/dialogSearchAnalytics.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogSearchAnalytics.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/dialogSearchAnalytics.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/dialogSearchAnalytics.spec.js

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Dialog } from "../Dialog";
+import { EventsHandler } from "../EventsHandler";
+import { DIALOG_CUSTOM_EVENT, DialogEvents } from "../types/events";
+// The Dialog constructor loads the assistant into the DOM; these tests only
+// exercise the search tracking methods, so the instance is built from the
+// prototype with just the fields those methods read.
+const buildDialog = () => {
+    const eventsHandler = new EventsHandler("fr", "user-1");
+    const emitExternalEvent = vi.fn();
+    eventsHandler.emitExternalEvent =
+        emitExternalEvent;
+    const dialog = Object.create(Dialog.prototype);
+    Object.assign(dialog, {
+        _eventsHandler: eventsHandler,
+        _userId: "user-1",
+    });
+    return { dialog, emitExternalEvent };
+};
+const envelope = {
+    query_id: "query-1",
+    surface: "search_page",
+    page: 2,
+    total_hits: 1247,
+    query_length: 14,
+};
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+});
+describe("Dialog search analytics", () => {
+    it("emits TRACK_VIEW_SEARCH_RESULTS with the snake_case envelope, items and userId", () => {
+        const { dialog, emitExternalEvent } = buildDialog();
+        const items = [
+            { product_id: "product-1", position: 21 },
+            { product_id: "product-2", position: 22 },
+        ];
+        dialog.trackViewSearchResults({ ...envelope, items });
+        expect(emitExternalEvent).toHaveBeenCalledWith(DialogEvents.TRACK_VIEW_SEARCH_RESULTS, { userId: "user-1", ...envelope, items });
+    });
+    it("represents a rendered no-results state as empty items with total_hits 0", () => {
+        const { dialog, emitExternalEvent } = buildDialog();
+        dialog.trackViewSearchResults({ ...envelope, total_hits: 0, items: [] });
+        expect(emitExternalEvent).toHaveBeenCalledWith(DialogEvents.TRACK_VIEW_SEARCH_RESULTS, { userId: "user-1", ...envelope, total_hits: 0, items: [] });
+    });
+    it("emits TRACK_SELECT_SEARCH_RESULT with a single-item array", () => {
+        const { dialog, emitExternalEvent } = buildDialog();
+        const item = { product_id: "product-1", position: 22 };
+        dialog.trackSelectSearchResult({ ...envelope, items: [item] });
+        expect(emitExternalEvent).toHaveBeenCalledWith(DialogEvents.TRACK_SELECT_SEARCH_RESULT, { userId: "user-1", ...envelope, items: [item] });
+    });
+});
+describe("EventsHandler search event buffering", () => {
+    it("buffers both search events until consumer-ready, then flushes them intact and in order", () => {
+        const dispatchEvent = vi.fn();
+        vi.stubGlobal("window", { dispatchEvent });
+        const eventsHandler = new EventsHandler("fr", "user-1");
+        const item = { product_id: "product-1", position: 22 };
+        eventsHandler.emitExternalEvent(DialogEvents.TRACK_VIEW_SEARCH_RESULTS, {
+            ...envelope,
+            items: [],
+        });
+        eventsHandler.emitExternalEvent(DialogEvents.TRACK_SELECT_SEARCH_RESULT, {
+            ...envelope,
+            items: [item],
+        });
+        expect(dispatchEvent).not.toHaveBeenCalled();
+        eventsHandler.notifyConsumerReady();
+        const dispatched = dispatchEvent.mock.calls.map(([event]) => ({
+            name: event.type,
+            detail: event.detail,
+        }));
+        expect(dispatched).toEqual([
+            {
+                name: DIALOG_CUSTOM_EVENT,
+                detail: {
+                    type: DialogEvents.TRACK_VIEW_SEARCH_RESULTS,
+                    payload: { ...envelope, items: [] },
+                },
+            },
+            {
+                name: DIALOG_CUSTOM_EVENT,
+                detail: {
+                    type: DialogEvents.TRACK_SELECT_SEARCH_RESULT,
+                    payload: { ...envelope, items: [item] },
+                },
+            },
+        ]);
+    });
+});

package/dist/__tests__/publicTypes.spec.js

@@ -9,6 +9,9 @@ describe("public API types", () => {
         // Invalid callback values must be rejected.
         expectTypeOf().not.toMatchTypeOf();
         expectTypeOf().parameters.toMatchTypeOf();
+        expectTypeOf().toMatchTypeOf();
+        expectTypeOf().toMatchTypeOf();
+        expectTypeOf().toEqualTypeOf();
         expectTypeOf().returns.resolves.toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();

package/dist/__tests__/searchController.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=searchController.spec.d.ts.map

package/dist/__tests__/searchController.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchController.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/searchController.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/searchController.spec.js

@@ -0,0 +1,254 @@
+/* eslint max-lines: ["error", 400] */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSearchController } from "../searchController";
+import { SearchStatus } from "../types/searchController";
+vi.mock("../utils/searchImpressions", () => ({
+    createSearchImpressionTracker: () => ({
+        setContext: vi.fn(),
+        observe: vi.fn(),
+        forceImpression: vi.fn(),
+        flush: vi.fn(),
+        disconnect: vi.fn(),
+    }),
+}));
+const DEBOUNCE_MS = 250;
+const response = (overrides = {}) => ({
+    queryId: "qid-1",
+    hits: [
+        { id: "h1", score: 1, product: { id: "p1" } },
+        { id: "h2", score: 0.9, product: { id: "p2" } },
+    ],
+    nbHits: 2,
+    page: 0,
+    nbPages: 3,
+    hitsPerPage: 12,
+    processingTimeMs: 5,
+    query: "shoes",
+    ...overrides,
+});
+const deferred = () => {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+};
+// Lets the controller's `await search(...)` continuation run.
+const settle = async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+};
+const search = vi.fn();
+const trackViewSearchResults = vi.fn();
+const trackSelectSearchResult = vi.fn();
+const states = [];
+const createController = () => {
+    const controller = createSearchController({
+        search,
+        analytics: {
+            surface: "search_page",
+            trackViewSearchResults,
+            trackSelectSearchResult,
+        },
+    });
+    controller.subscribe((state) => states.push(state));
+    return controller;
+};
+beforeEach(() => {
+    vi.useFakeTimers();
+});
+afterEach(() => {
+    vi.useRealTimers();
+    vi.clearAllMocks();
+    states.length = 0;
+});
+describe("createSearchController", () => {
+    it("starts idle", () => {
+        const controller = createController();
+        expect(controller.getState()).toMatchObject({
+            status: SearchStatus.IDLE,
+            query: "",
+            page: 0,
+        });
+    });
+    it("debounces rapid input into a single request for the last query", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response({ query: "shoes" }));
+        controller.setQuery("sh");
+        vi.advanceTimersByTime(DEBOUNCE_MS - 1);
+        controller.setQuery("sho");
+        vi.advanceTimersByTime(DEBOUNCE_MS - 1);
+        controller.setQuery("shoes");
+        vi.advanceTimersByTime(DEBOUNCE_MS);
+        await settle();
+        expect(search).toHaveBeenCalledTimes(1);
+        expect(search.mock.calls[0][0]).toMatchObject({ query: "shoes", page: 0 });
+        expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
+    });
+    it("submits immediately without waiting for the debounce", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response());
+        controller.setQuery("sho");
+        controller.submit("shoes");
+        await settle();
+        expect(search).toHaveBeenCalledTimes(1);
+        expect(search.mock.calls[0][0]).toMatchObject({ query: "shoes" });
+        expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
+    });
+    it("aborts the previous in-flight request when a new one starts", async () => {
+        const controller = createController();
+        const first = deferred();
+        const second = deferred();
+        search
+            .mockReturnValueOnce(first.promise)
+            .mockReturnValueOnce(second.promise);
+        controller.submit("shoes");
+        const firstSignal = search.mock.calls[0][1]?.signal;
+        controller.submit("boots");
+        expect(firstSignal?.aborted).toBe(true);
+        second.resolve(response({ query: "boots", queryId: "qid-2" }));
+        await settle();
+        expect(controller.getState().response?.query).toBe("boots");
+    });
+    it("never lets a late stale response replace newer results, even without transport cancellation", async () => {
+        const controller = createController();
+        const stale = deferred();
+        const fresh = deferred();
+        search
+            .mockReturnValueOnce(stale.promise)
+            .mockReturnValueOnce(fresh.promise);
+        controller.submit("shoes");
+        controller.submit("boots");
+        fresh.resolve(response({ query: "boots", queryId: "qid-2" }));
+        await settle();
+        // The stale transport ignored the abort and answers after the fresh one.
+        stale.resolve(response({ query: "shoes", queryId: "qid-1" }));
+        await settle();
+        expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
+        expect(controller.getState().response?.query).toBe("boots");
+    });
+    it("swallows the AbortError of a superseded request", async () => {
+        const controller = createController();
+        const first = deferred();
+        search
+            .mockReturnValueOnce(first.promise)
+            .mockResolvedValueOnce(response({ query: "boots", queryId: "qid-2" }));
+        controller.submit("shoes");
+        controller.submit("boots");
+        first.reject(new DOMException("The operation was aborted.", "AbortError"));
+        await settle();
+        expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
+        expect(controller.getState().error).toBeUndefined();
+    });
+    it("surfaces errors and retries the same query and page", async () => {
+        const controller = createController();
+        const failure = new TypeError("Failed to fetch");
+        search
+            .mockResolvedValueOnce(response())
+            .mockRejectedValueOnce(failure)
+            .mockResolvedValueOnce(response({ page: 2 }));
+        controller.submit("shoes");
+        await settle();
+        controller.setPage(2);
+        await settle();
+        expect(controller.getState()).toMatchObject({
+            status: SearchStatus.ERROR,
+            error: failure,
+            response: undefined,
+        });
+        controller.retry();
+        await settle();
+        expect(search).toHaveBeenCalledTimes(3);
+        expect(search.mock.calls[2][0]).toMatchObject({ query: "shoes", page: 2 });
+        expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
+    });
+    it("ignores retry outside the error state", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response());
+        controller.submit("shoes");
+        await settle();
+        controller.retry();
+        await settle();
+        expect(search).toHaveBeenCalledTimes(1);
+    });
+    it("reports the empty status on zero hits", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response({ hits: [], nbHits: 0, nbPages: 0 }));
+        controller.submit("shoes");
+        await settle();
+        expect(controller.getState().status).toBe(SearchStatus.EMPTY);
+    });
+    it("resets to idle and invalidates in-flight work when the query gets too short", async () => {
+        const controller = createController();
+        const inFlight = deferred();
+        search.mockReturnValueOnce(inFlight.promise);
+        controller.submit("shoes");
+        controller.setQuery("s");
+        inFlight.resolve(response());
+        await settle();
+        expect(search).toHaveBeenCalledTimes(1);
+        expect(controller.getState().status).toBe(SearchStatus.IDLE);
+    });
+    it("resets pagination when a new query is submitted", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response());
+        controller.submit("shoes");
+        await settle();
+        controller.setPage(2);
+        await settle();
+        controller.submit("boots");
+        await settle();
+        expect(search.mock.calls[2][0]).toMatchObject({ query: "boots", page: 0 });
+    });
+    it("flushes a pending debounced query instead of paginating stale results", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response());
+        controller.submit("shoes");
+        await settle();
+        controller.setQuery("boots");
+        controller.setPage(1);
+        await settle();
+        expect(search).toHaveBeenCalledTimes(2);
+        expect(search.mock.calls[1][0]).toMatchObject({ query: "boots", page: 0 });
+    });
+    it("ignores pagination without a committed query", () => {
+        const controller = createController();
+        controller.setPage(1);
+        expect(search).not.toHaveBeenCalled();
+    });
+    it("notifies subscribers and stops after unsubscribe", async () => {
+        const controller = createController();
+        search.mockResolvedValue(response());
+        const listener = vi.fn();
+        const unsubscribe = controller.subscribe(listener);
+        controller.submit("shoes");
+        await settle();
+        const notified = listener.mock.calls.length;
+        unsubscribe();
+        controller.submit("boots");
+        await settle();
+        expect(notified).toBeGreaterThan(0);
+        expect(listener).toHaveBeenCalledTimes(notified);
+    });
+    it("stops all work after dispose", async () => {
+        const controller = createController();
+        const inFlight = deferred();
+        search.mockReturnValueOnce(inFlight.promise);
+        controller.submit("shoes");
+        const signal = search.mock.calls[0][1]?.signal;
+        controller.dispose();
+        expect(signal?.aborted).toBe(true);
+        inFlight.resolve(response());
+        await settle();
+        controller.setQuery("boots");
+        controller.submit("boots");
+        controller.setPage(1);
+        controller.retry();
+        vi.advanceTimersByTime(DEBOUNCE_MS);
+        await settle();
+        expect(search).toHaveBeenCalledTimes(1);
+        expect(controller.getState().status).toBe(SearchStatus.LOADING);
+    });
+});

package/dist/__tests__/searchControllerAttribution.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=searchControllerAttribution.spec.d.ts.map

package/dist/__tests__/searchControllerAttribution.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchControllerAttribution.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/searchControllerAttribution.spec.ts"],"names":[],"mappings":""}