@askdialog/dialog-sdk 2.5.0 → 2.6.0

package/README.md

@@ -205,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";
@@ -45,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;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,OAAO,CAAC,cAAc;CAkCvB"}
+{"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

@@ -148,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) {

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__/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__/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":""}