@askdialog/dialog-sdk 2.11.0 → 2.12.0

package/README.md

@@ -51,7 +51,8 @@ import { Dialog } from '@askdialog/dialog-sdk';
 
 const client = new Dialog({
   apiKey: 'YOUR_API_KEY', // required
-  locale: 'TARGETED_LOCALE', // required
+  locale: 'fr-FR', currency: 'EUR', // ISO 639-1 language
+  currency: 'EUR', // required ISO 4217 currency
   countryCode: 'FR', // optional, ISO 3166 alpha-2
   callbacks: {
     addToCart: async ({
@@ -100,7 +101,7 @@ Declare it at construction on product pages:
 ```ts
 new Dialog({
   apiKey: 'YOUR_API_KEY',
-  locale: 'fr',
+  locale: 'fr-FR', currency: 'EUR',
   product: { id: 'PRODUCT_ID', variantId: 'VARIANT_ID' }, // variantId optional
 });
 ```
@@ -130,7 +131,7 @@ Some sessions must hide purchasing actions — for example a B2B storefront that
 ```ts
 new Dialog({
   apiKey: 'YOUR_API_KEY',
-  locale: 'fr',
+  locale: 'fr-FR', currency: 'EUR',
   disableAddToCart: true, // hide the add-to-cart CTA for this session
 });
 ```
@@ -219,18 +220,20 @@ Example of expected result:
 
 - Search products
 
-`client.search()` performs a typed, Algolia-shaped search through Dialog's public API, with no framework and no commerce callbacks required. Each entry targets an index named `<index>_<locale>` (index ∈ `products | collections | articles | pages`, locale ISO 639-1) — build the name with `searchIndexName(index, locale)`, which reduces any BCP-47 tag to its bare language.
+`client.search()` sends a multi-index request to the public search API. Build names with `searchIndexName(index, language, currency)`: `<index>_<lang>_<currency>`, e.g. `products_fr_eur`. Supported indices: `products`, `collections`, `articles`, `pages`. Language must be a lowercase ISO 639-1 code (`fr`, `en`). Regional locales such as `fr-FR` are rejected. The ISO 4217 currency is lowercased in the index name.
+
+Currency is required and independent of language: `fr` with `USD` produces `products_fr_usd`. Names without a currency suffix return 404.
 
 ```typescript
 import { Dialog, DialogSearchError, searchIndexName } from '@askdialog/dialog-sdk';
 import type { SearchResponse } from '@askdialog/dialog-sdk';
 
-const client = new Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr' });
+const client = new Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr-FR', currency: 'EUR' });
 
 const response: SearchResponse = await client.search({
   requests: [
     {
-      indexName: searchIndexName('products', client.locale), // "products_fr"
+      indexName: searchIndexName('products', 'fr', client.currency), // "products_fr_eur"
       query: 'shampoo',
       page: 0, // optional, zero-indexed (default 0)
       hitsPerPage: 20, // optional, 1-100 (default 20)
@@ -248,29 +251,32 @@ With the IIFE bundle the results are plain runtime JSON (same shape, no types):
 ```html
 <script src="https://d2m6yt8rnm4dos.cloudfront.net/dialog-sdk.X.Y.Z.min.js"></script>
 <script>
-  const client = new window.DialogSDK.Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr' });
+  const client = new window.DialogSDK.Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr-FR', currency: 'EUR' });
   client
-    .search({ requests: [{ indexName: 'products_fr', query: 'shampoo' }] })
+    .search({ requests: [{ indexName: 'products_fr_eur', query: 'shampoo' }] })
     .then((response) => console.log(response.results[0].hits));
 </script>
 ```
 
 A non-2xx answer rejects with `DialogSearchError` — stable `name`, HTTP `status` and `message` (e.g. `404 Index products_xx does not exist`, `400 Unknown parameter: foo`). Aborting rejects with the native `AbortError`, and network failures keep their native errors.
 
-`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.
+`client.search()` sends requests unchanged, without debounce, caching or automatic cancellation. Use `createSearchController()` for interactive search.
 
 - 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 attribution events (`view_search_results` viewport impressions, `select_search_result` clicks). It searches the products index (`products_<locale>`) and exposes the products result entry as `state.response`; optional `sections` add other indices (`collections`, …) to the same request, exposed under `state.sections`. It has no framework or rendering dependency: raw JavaScript, React, Vue and Shopify integrations are rendering-and-routing adapters around it.
+`createSearchController()` handles debounce, cancellation, stale responses, pagination, retries and search analytics. New queries reset pagination. State is `idle`, `loading`, `success`, `empty` or `error`.
+
+Products are available in `state.response`. Optional `sections` query additional indexes in the same request and expose results in `state.sections`.
 
 ```typescript
 import { createSearchController, Dialog, SearchStatus } from '@askdialog/dialog-sdk';
 
-const client = new Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr' });
+const client = new Dialog({ apiKey: 'YOUR_API_KEY', locale: 'fr-FR', currency: 'EUR' });
 
 const controller = createSearchController({
   search: (request, options) => client.search(request, options),
-  locale: client.locale, // names the searched index ("products_fr")
+  language: 'fr',
+  currency: client.currency,
   analytics: {
     surface: 'search_page', // where results are displayed
     trackViewSearchResults: (params) => client.trackViewSearchResults(params),
@@ -283,7 +289,7 @@ const controller = createSearchController({
 });
 
 const unsubscribe = controller.subscribe((state) => {
-  // state: { status, query, page, response?, error? }
+  // state: { status, query, page, response?, sections?, error? }
   if (state.status === SearchStatus.SUCCESS) {
     renderCards(state.response.hits).forEach((element, index) => {
       controller.observeResult(element, index); // viewport impression
@@ -296,16 +302,20 @@ 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.
+// Cancel requests and remove observers on unmount.
 controller.dispose();
 ```
 
-The adapter contract for a framework binding (React, Vue, Shopify):
+The client uses a BCP-47 `locale` such as `fr-FR` for assistant localization. Search controllers and React/Vue hooks require explicit `language` (ISO 639-1) and `currency` (ISO 4217), independently of the client locale. Pass `client.currency` to reuse its configured currency.
+
+For Shopify, use `window.Shopify.currency.active` as the currency. Controller options are fixed at creation; recreate the controller to change language or currency.
+
+Framework integrations:
 
-- **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.
+- Subscribe to state changes and render results.
+- Call `observeResult(element, index)` for each result and `selectResult(index)` on selection. Use `{ navigate: false }` for middle-clicks and modified clicks. Call `preventDefault()` only when `selectResult` returns true.
+- Pass `navigate` for router navigation. The integration owns URL synchronization.
+- Create one controller per search surface and call `dispose()` on unmount.
 
 The raw JavaScript reference adapter lives in [`packages/search-example`](../search-example).
 
@@ -531,7 +541,8 @@ interface AssistantEvent {
   payload: {
     // Common fields (included in all events)
     date: string;        // ISO timestamp
-    locale: string;      // Current locale
+    locale: string;      // BCP-47 locale
+    currency: string;    // Current currency
     url: string;         // Current page URL
     userId?: string;     // User ID if available
     

package/dist/Dialog.d.ts

@@ -12,6 +12,7 @@ export declare class Dialog {
     static readonly VERSION: string;
     private _apiKey;
     private _locale;
+    private _currency;
     private _countryCode?;
     private _callbacks?;
     private _theme;
@@ -20,37 +21,31 @@ export declare class Dialog {
     private _ignoreOneTrustAutoBlock;
     private _disableAddToCart;
     private _currentProduct?;
-    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, disableAddToCart, product, }: DialogConstructor);
+    constructor({ apiKey, locale, currency, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, disableAddToCart, product, }: DialogConstructor);
     get apiKey(): string;
     get theme(): Theme;
     get userId(): string;
     get locale(): string;
+    get currency(): string;
     get eventsHandler(): EventsHandler;
     getLocalizationInformations(): DetailedLocaleInfo | null;
     private _createOrRetrieveUserId;
     getSuggestions(productId: string): Promise<Suggestion>;
     /**
-     * Typed multi-index search through the Nest public endpoint (Algolia-shaped,
-     * DAT-412). The locale travels in each entry's `indexName` (`products_fr`) —
-     * build it with `searchIndexName(index, locale)`. Stateless: one request per
-     * call, cancellation belongs to the caller via `options.signal` (previous
-     * searches are never cancelled automatically). Rejects with
-     * `DialogSearchError` on a non-2xx answer, and with the native AbortError /
-     * network error otherwise.
+     * Send one search request with names built by `searchIndexName`.
+     * Cancel through `options.signal`. HTTP errors reject with `DialogSearchError`;
+     * network and cancellation errors propagate unchanged.
      */
     search(request: SearchRequest, options?: SearchOptions): Promise<SearchResponse>;
     openAssistant(params: OpenAssistantPayload): void;
     closeAssistant(): void;
     /**
-     * Declare the product of the current page. The assistant reads it as the
-     * conversation's product context whenever a question carries no product of
-     * its own (floating bookmark, resume surface, free-text input). Call it on
-     * every PDP navigation on single-page storefronts; ids must match the
-     * Dialog product feed.
+     * Set the default product context for assistant questions.
+     * Call on each product-page navigation; IDs must match the Dialog product feed.
      */
     setCurrentProduct(productId: string, variantId?: string): void;
     private static _isValidProductId;
-    /** Declare that the current page is not a product page. */
+    /** Clear the product context on non-product pages. */
     clearCurrentProduct(): void;
     private _applyCurrentProductDataset;
     sendProductMessage(params: ProductQuestionPayload): void;
@@ -63,15 +58,11 @@ export declare class Dialog {
     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.
+     * Emit impressions batched by `createSearchImpressionTracker`.
+     * Use `items: []` for an empty result set.
      */
     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.
-     */
+    /** Emit a selection after its impression, including middle-clicks and modified clicks. */
     trackSelectSearchResult(params: SelectSearchResultParams): void;
     private _loadAssistant;
 }

package/dist/Dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../src/Dialog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../src/Dialog.ts"],"names":[],"mappings":"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"}

package/dist/Dialog.js

@@ -14,6 +14,7 @@ export class Dialog {
     static VERSION = packageJson.version;
     _apiKey;
     _locale;
+    _currency;
     _countryCode;
     _callbacks;
     _theme;
@@ -22,9 +23,10 @@ export class Dialog {
     _ignoreOneTrustAutoBlock;
     _disableAddToCart;
     _currentProduct;
-    constructor({ apiKey, locale, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, disableAddToCart, product, }) {
+    constructor({ apiKey, locale, currency, countryCode, callbacks, theme, userId, ignoreOneTrustAutoBlock, disableAddToCart, product, }) {
         this._apiKey = apiKey;
         this._locale = locale;
+        this._currency = currency;
         this._countryCode = countryCode;
         this._callbacks = callbacks;
         this._ignoreOneTrustAutoBlock = ignoreOneTrustAutoBlock ?? false;
@@ -54,6 +56,9 @@ export class Dialog {
     get locale() {
         return this._locale;
     }
+    get currency() {
+        return this._currency;
+    }
     get eventsHandler() {
         return this._eventsHandler;
     }
@@ -77,13 +82,9 @@ export class Dialog {
         return loadSuggestions(this._apiKey, this._locale, productId);
     }
     /**
-     * Typed multi-index search through the Nest public endpoint (Algolia-shaped,
-     * DAT-412). The locale travels in each entry's `indexName` (`products_fr`) —
-     * build it with `searchIndexName(index, locale)`. Stateless: one request per
-     * call, cancellation belongs to the caller via `options.signal` (previous
-     * searches are never cancelled automatically). Rejects with
-     * `DialogSearchError` on a non-2xx answer, and with the native AbortError /
-     * network error otherwise.
+     * Send one search request with names built by `searchIndexName`.
+     * Cancel through `options.signal`. HTTP errors reject with `DialogSearchError`;
+     * network and cancellation errors propagate unchanged.
      */
     search(request, options) {
         return searchLexical(this._apiKey, request, options);
@@ -97,11 +98,8 @@ export class Dialog {
         this._eventsHandler.emitExternalEvent(DialogEvents.CLOSE_ASSISTANT);
     }
     /**
-     * Declare the product of the current page. The assistant reads it as the
-     * conversation's product context whenever a question carries no product of
-     * its own (floating bookmark, resume surface, free-text input). Call it on
-     * every PDP navigation on single-page storefronts; ids must match the
-     * Dialog product feed.
+     * Set the default product context for assistant questions.
+     * Call on each product-page navigation; IDs must match the Dialog product feed.
      */
     setCurrentProduct(productId, variantId) {
         if (!Dialog._isValidProductId(productId)) {
@@ -114,23 +112,17 @@ export class Dialog {
     static _isValidProductId(productId) {
         return typeof productId === "string" && productId.trim() !== "";
     }
-    /** Declare that the current page is not a product page. */
+    /** Clear the product context on non-product pages. */
     clearCurrentProduct() {
         this._currentProduct = undefined;
         this._applyCurrentProductDataset();
     }
-    // The dataset on the assistant mount node is the SDK⇄runtime contract for
-    // the page product: the runtime observes data-product-id / data-variant-id
-    // and needs no event plumbing, so SDK and runtime versions can drift.
+    // The runtime reads product context from the mount node dataset.
     _applyCurrentProductDataset() {
-        // Resolved via getElementById on purpose, NOT an instance reference: the
-        // assistant runtime reads the dataset the same way, so on a page where
-        // another integration already rendered #dialog-shopify-ai (duplicate-id
-        // case) writer and reader must land on the same — first — node.
+        // Match the runtime lookup: duplicate IDs must resolve to the same first node.
         const mountNode = document.getElementById("dialog-shopify-ai");
         if (mountNode === null) {
-            // Assistant mount node absent (locale error at load, or the host page
-            // removed it) — the declaration is kept but cannot reach the runtime.
+            // Keep the context until a mount node is available.
             console.warn("Dialog: assistant mount node not found; the current product declaration has no effect.");
             return;
         }
@@ -162,12 +154,9 @@ export class Dialog {
     getProduct(productId, variantId) {
         return this._getCallbacksOrThrow("getProduct").getProduct(productId, variantId);
     }
-    // The full input (including the optional enriched product fields) is
-    // forwarded to the merchant callback and to the tracking event, so
-    // integrations can consume the added-product data wherever they hook in.
+    // Forward all product fields to the commerce callback and analytics.
     async addToCart(input) {
-        // No-op when disabled, so a stale UI that still surfaced the CTA cannot
-        // add to the cart or emit analytics.
+        // Disabled instances must neither modify the cart nor emit analytics.
         if (this._disableAddToCart) {
             console.warn("Dialog: addToCart is disabled on this instance (disableAddToCart); ignoring the call.");
             return;
@@ -176,8 +165,7 @@ export class Dialog {
         this.registerAddToCartEvent(input);
         return;
     }
-    // Callbacks are optional at construction; the two commerce methods assert
-    // theirs at call time with an integration-facing configuration error.
+    // Validate optional commerce callbacks when invoked.
     _getCallbacksOrThrow(name) {
         if (this._callbacks?.[name] === undefined) {
             throw new Error(`Dialog: \`callbacks.${name}\` was not provided to the constructor; ${name}() is unavailable on this instance.`);
@@ -190,13 +178,8 @@ export class Dialog {
             ...input,
         });
     }
-    // Order-level: call ONCE per completed order with the order total.
-    // `orderValue` is what the dashboard's "Revenue generated" reads — do not
-    // call this per line item (that has no total and revenue resolves to 0).
-    //
-    // The legacy per-line signature (`{ productId, quantity, price }`) is still
-    // accepted for backward compatibility so existing installs keep working
-    // after an upgrade, but it is deprecated: it carries no order total.
+    // Call once per completed order; `orderValue` supplies the revenue total.
+    // The deprecated per-item payload remains accepted but has no order total.
     registerSubmitCheckoutEvent(params) {
         if ("orderValue" in params) {
             this._eventsHandler.emitExternalEvent(DialogEvents.TRACK_SUBMIT_CHECKOUT, {
@@ -218,9 +201,8 @@ export class Dialog {
         });
     }
     /**
-     * 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.
+     * Emit impressions batched by `createSearchImpressionTracker`.
+     * Use `items: []` for an empty result set.
      */
     trackViewSearchResults(params) {
         this._eventsHandler.emitExternalEvent(DialogEvents.TRACK_VIEW_SEARCH_RESULTS, {
@@ -228,10 +210,7 @@ export class Dialog {
             ...params,
         });
     }
-    /**
-     * Emit on a result click — including auxclick / cmd+click, not only before
-     * a same-tab navigation. Force the clicked item's impression first.
-     */
+    /** Emit a selection after its impression, including middle-clicks and modified clicks. */
     trackSelectSearchResult(params) {
         this._eventsHandler.emitExternalEvent(DialogEvents.TRACK_SELECT_SEARCH_RESULT, {
             userId: this._userId,
@@ -252,7 +231,7 @@ export class Dialog {
         div.dataset.countryCode = localeInfo.countryCode;
         div.dataset.language = localeInfo.language;
         if (this._disableAddToCart) {
-            // Read by the assistant runtime to hide the add-to-cart CTA.
+            // Hide the add-to-cart button in the assistant.
             div.dataset.disableAddToCart = "true";
         }
         document.body.appendChild(div);
@@ -262,12 +241,7 @@ export class Dialog {
         setTimeout(() => {
             const script = document.createElement("script");
             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. OneTrust's trap fires
-                // synchronously inside the `src` setter, so the attribute must be in
-                // place BEFORE src is assigned or the script is rewritten to
-                // type="text/plain" despite carrying the attribute.
+                // Set the bypass attribute before src: OneTrust intercepts the src setter.
                 script.setAttribute("data-ot-ignore", "");
             }
             script.defer = true;

package/dist/__tests__/dialogSearchAnalytics.spec.js

@@ -2,9 +2,7 @@ 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.
+// Bypass constructor DOM setup; provide only the fields used by analytics.
 const buildDialog = () => {
     const eventsHandler = new EventsHandler("fr", "user-1");
     const emitExternalEvent = vi.fn();
@@ -19,7 +17,7 @@ const buildDialog = () => {
 };
 const envelope = {
     query_id: "query-1",
-    index: "products_fr",
+    index: "products_fr_eur",
     surface: "search_page",
     search_type: "lexical",
     page: 2,

package/dist/__tests__/publicTypes.spec.js

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

package/dist/__tests__/searchController.spec.js

@@ -1,4 +1,4 @@
-/* eslint max-lines: ["error", 460] */
+/* eslint max-lines: ["error", 490] */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createSearchController } from "../searchController";
 import { SearchStatus } from "../types/searchController";
@@ -15,7 +15,7 @@ const DEBOUNCE_MS = 250;
 const response = (overrides = {}) => ({
     results: [
         {
-            index: "products_fr",
+            index: "products_fr_eur",
             hits: [{ objectID: "p1" }, { objectID: "p2" }],
             nbHits: 2,
             page: 0,
@@ -37,7 +37,7 @@ const deferred = () => {
     });
     return { promise, resolve, reject };
 };
-// Lets the controller's `await search(...)` continuation run.
+// Flush the search promise continuation.
 const settle = async () => {
     await Promise.resolve();
     await Promise.resolve();
@@ -49,12 +49,13 @@ const states = [];
 const createController = () => {
     const controller = createSearchController({
         search,
+        language: "fr",
+        currency: "EUR",
         analytics: {
             surface: "search_page",
             trackViewSearchResults,
             trackSelectSearchResult,
         },
-        locale: "fr",
     });
     controller.subscribe((state) => states.push(state));
     return controller;
@@ -93,22 +94,28 @@ describe("createSearchController", () => {
         });
         expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
     });
-    it("sends one products entry named after the bare-language locale", async () => {
+    it("sends one products entry with independent language and currency", async () => {
         const controller = createSearchController({
             search,
+            language: "fr",
+            currency: "USD",
             analytics: {
                 surface: "search_page",
                 trackViewSearchResults,
                 trackSelectSearchResult,
             },
-            locale: "fr-FR",
         });
-        search.mockResolvedValue(response({ query: "shoes" }));
+        search.mockResolvedValue(response({ query: "shoes", index: "products_fr_usd" }));
         controller.submit("shoes");
         await settle();
         expect(search.mock.calls[0][0]).toEqual({
             requests: [
-                { indexName: "products_fr", query: "shoes", page: 0, hitsPerPage: 12 },
+                {
+                    indexName: "products_fr_usd",
+                    query: "shoes",
+                    page: 0,
+                    hitsPerPage: 12,
+                },
             ],
         });
         controller.dispose();
@@ -125,7 +132,7 @@ describe("createSearchController", () => {
         });
         expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
     });
-    it("aborts the previous in-flight request when a new one starts", async () => {
+    it("invalidates the previous request as soon as new input is queued", async () => {
         const controller = createController();
         const first = deferred();
         const second = deferred();
@@ -134,8 +141,14 @@ describe("createSearchController", () => {
             .mockReturnValueOnce(second.promise);
         controller.submit("shoes");
         const firstSignal = search.mock.calls[0][1]?.signal;
-        controller.submit("boots");
+        controller.setQuery("boots");
+        first.resolve(response({ query: "shoes" }));
+        await settle();
         expect(firstSignal?.aborted).toBe(true);
+        expect(search).toHaveBeenCalledTimes(1);
+        expect(controller.getState().response).toBeUndefined();
+        expect(controller.getState().status).toBe(SearchStatus.LOADING);
+        vi.advanceTimersByTime(DEBOUNCE_MS);
         second.resolve(response({ query: "boots", queryID: "qid-2" }));
         await settle();
         expect(controller.getState().response?.query).toBe("boots");
@@ -151,7 +164,7 @@ describe("createSearchController", () => {
         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.
+        // Simulate a late response from a transport that ignores cancellation.
         stale.resolve(response({ query: "shoes", queryID: "qid-1" }));
         await settle();
         expect(controller.getState().status).toBe(SearchStatus.SUCCESS);
@@ -291,42 +304,54 @@ describe("createSearchController", () => {
     it("requests the sections on their first page with the products and exposes their entries", async () => {
         const controller = createSearchController({
             search,
+            language: "fr",
+            currency: "USD",
             analytics: {
                 surface: "search_page",
                 trackViewSearchResults,
                 trackSelectSearchResult,
             },
-            locale: "fr",
             sections: [{ index: "collections", hitsPerPage: 5 }],
         });
         const collections = {
             ...response().results[0],
-            index: "collections_fr",
+            index: "collections_fr_usd",
             hits: [{ objectID: "c1" }],
             nbHits: 1,
         };
         search.mockResolvedValueOnce({
-            results: [...response().results, collections],
+            results: [...response({ index: "products_fr_usd" }).results, collections],
         });
         controller.submit("shoes");
         await settle();
         expect(search.mock.calls[0][0].requests).toEqual([
-            { indexName: "products_fr", query: "shoes", page: 0, hitsPerPage: 12 },
-            { indexName: "collections_fr", query: "shoes", page: 0, hitsPerPage: 5 },
+            {
+                indexName: "products_fr_usd",
+                query: "shoes",
+                page: 0,
+                hitsPerPage: 12,
+            },
+            {
+                indexName: "collections_fr_usd",
+                query: "shoes",
+                page: 0,
+                hitsPerPage: 5,
+            },
         ]);
-        expect(controller.getState().response?.index).toBe("products_fr");
+        expect(controller.getState().response?.index).toBe("products_fr_usd");
         expect(controller.getState().sections).toEqual({ collections });
     });
     it("resolves a sections function per request and leaves a missing entry out", async () => {
         let enabled = false;
         const controller = createSearchController({
             search,
+            language: "fr",
+            currency: "EUR",
             analytics: {
                 surface: "search_page",
                 trackViewSearchResults,
                 trackSelectSearchResult,
             },
-            locale: "fr",
             sections: () => (enabled ? [{ index: "collections" }] : []),
         });
         search.mockResolvedValue(response());
@@ -338,7 +363,7 @@ describe("createSearchController", () => {
         expect(search.mock.calls[0][0].requests).toHaveLength(1);
         expect(search.mock.calls[1][0].requests).toHaveLength(2);
         expect(search.mock.calls[1][0].requests[1]).toMatchObject({
-            indexName: "collections_fr",
+            indexName: "collections_fr_eur",
             hitsPerPage: 12,
         });
         expect(controller.getState().sections).toEqual({});
@@ -347,12 +372,13 @@ describe("createSearchController", () => {
         const failure = new Error("entitlement lookup failed");
         const controller = createSearchController({
             search,
+            language: "fr",
+            currency: "EUR",
             analytics: {
                 surface: "search_page",
                 trackViewSearchResults,
                 trackSelectSearchResult,
             },
-            locale: "fr",
             sections: () => {
                 throw failure;
             },