@blotoutio/providers-evo-search-sdk 1.64.1 → 1.64.2

package/README.md

@@ -54,6 +54,36 @@ function HeaderSearch() {
 }
 ```
 
+## Tracking interactions
+
+EvoSearch needs three interaction signals to power the dashboard: searches, result clicks, and cart/purchase events. **In a headless integration, only `trackClick` requires code on your side.**
+
+### Searches — handled server-side
+
+Search volume, top queries, and zero-result queries are measured automatically from the search API. No client code needed.
+
+### Result clicks — `trackClick`
+
+Call `trackClick(productId)` when a user clicks a result, passing the `id` field from the search result:
+
+```tsx
+{
+  results.map((p) => (
+    <li key={p.id}>
+      <button type='button' onClick={() => trackClick(p.id)}>
+        {p.title}
+      </button>
+    </li>
+  ))
+}
+```
+
+### Add-to-cart / purchase — use your existing EdgeTag tags
+
+If you already send EdgeTag `AddToCart` and `Purchase` events via the EdgeTag SDK, you're done — EvoSearch receives them server-side and attributes them to searches automatically.
+
+**Important:** The product id in `trackClick` must match the product id in your EdgeTag commerce tags. If your commerce tags use SKUs or variant ids, normalize them to product id on both sides, or search-to-cart attribution will report zero.
+
 For full API reference, see the design spec in the Blotout solutions repo or the docs site.
 
 ## Disabling the default UI (headless mode)

package/core.cjs.js

@@ -662,10 +662,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         throw new Error('sendTag missing');
     }
     const getHeaders = () => {
+        var _a;
         const headers = new Headers({ EdgeTagUserId: userId });
         if (sessionId) {
             headers.set('EdgeTagSessionId', sessionId);
         }
+        headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
         return headers;
     };
     // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -699,7 +701,9 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if (!response.ok) {
             const errorText = await response.text().catch(() => '');
             logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-            throw new Error(`${label} failed - ${response.status}`);
+            const error = new Error(`${label} failed - ${response.status}`);
+            error.status = response.status;
+            throw error;
         }
         return (await response.json());
     };

package/core.js

@@ -663,10 +663,12 @@ var ProvidersEvoSearchSdk = (function () {
             throw new Error('sendTag missing');
         }
         const getHeaders = () => {
+            var _a;
             const headers = new Headers({ EdgeTagUserId: userId });
             if (sessionId) {
                 headers.set('EdgeTagSessionId', sessionId);
             }
+            headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
             return headers;
         };
         // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -700,7 +702,9 @@ var ProvidersEvoSearchSdk = (function () {
             if (!response.ok) {
                 const errorText = await response.text().catch(() => '');
                 logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-                throw new Error(`${label} failed - ${response.status}`);
+                const error = new Error(`${label} failed - ${response.status}`);
+                error.status = response.status;
+                throw error;
             }
             return (await response.json());
         };

package/core.mjs

@@ -660,10 +660,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         throw new Error('sendTag missing');
     }
     const getHeaders = () => {
+        var _a;
         const headers = new Headers({ EdgeTagUserId: userId });
         if (sessionId) {
             headers.set('EdgeTagSessionId', sessionId);
         }
+        headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
         return headers;
     };
     // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -697,7 +699,9 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if (!response.ok) {
             const errorText = await response.text().catch(() => '');
             logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-            throw new Error(`${label} failed - ${response.status}`);
+            const error = new Error(`${label} failed - ${response.status}`);
+            error.status = response.status;
+            throw error;
         }
         return (await response.json());
     };

package/hooks.cjs.js

@@ -632,6 +632,11 @@ const uiActions = new Set([
 new Set([...uiActions]);
 
 const DEBOUNCE_MS = 200;
+// How long a typed query must sit unchanged after its results render before
+// the widget counts it as one real search (recents + server-side query
+// metrics). Search fires per keystroke, so anything shorter than a genuine
+// reading pause would count prefixes (`a`, `ap`, `app`) as searches.
+const SEARCH_SETTLE_MS = 3000;
 
 // Intentionally duplicated from @blotoutio/providers/evo-search/config to keep the hooks bundle lean — importing from the config barrel pulls the shared/universal geo data into dist/hooks.mjs (~4KB gzipped). Drift between the two values is caught by utils.test.ts.
 const isHttpURL = (value) => {
@@ -690,6 +695,87 @@ const processAutocompleteResponse = (response) => {
     };
 };
 
+// Resilience wrapper for /search requests. A transient network failure or a
+// hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
+// a rejection), retry transient failures with backoff, and never retry a
+// caller-superseded (aborted) request. Shared by the widget and the headless
+// hook. See callers: search-widget.ts (performAutocomplete) and
+// hooks/use-evo-search.ts.
+const DEFAULTS = {
+    timeoutMs: 7000,
+    retries: 2,
+    backoffMs: [400, 1200],
+};
+// Deterministic HTTP errors (4xx other than 429) will never succeed on
+// retry — only retry timeouts, network errors, 429, and 5xx. Errors without
+// an attached `status` (network/timeout failures) are always retryable.
+const isRetryable = (error) => {
+    const status = error === null || error === void 0 ? void 0 : error.status;
+    return status == null || status === 429 || status >= 500;
+};
+const delay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new DOMException('Aborted', 'AbortError'));
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+});
+/**
+ * Run `attempt` with a timeout, retrying transient failures. `callerSignal`
+ * supersedes everything: if it aborts, we stop immediately without retrying
+ * (the query changed / the widget cleaned up). A timeout or network error is
+ * retried up to `retries` times; anything left over is rethrown.
+ */
+async function withSearchResilience(attempt, callerSignal, options = {}) {
+    var _a, _b;
+    const { timeoutMs, retries, backoffMs } = { ...DEFAULTS, ...options };
+    let lastError;
+    for (let i = 0; i <= retries; i++) {
+        if (callerSignal.aborted)
+            throw new DOMException('Aborted', 'AbortError');
+        const local = new AbortController();
+        const onCallerAbort = () => local.abort();
+        callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        // Race the attempt against an explicit timeout that REJECTS. Aborting the
+        // signal alone isn't enough — an attempt that ignores its signal would
+        // otherwise hang forever and never retry. Reject with a TimeoutError (not
+        // an AbortError) so callers surface it instead of treating it as a
+        // caller-cancellation.
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                local.abort(); // still cancel the in-flight request to free the socket
+                reject(new DOMException('Search request timed out', 'TimeoutError'));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([attempt(local.signal), timeout]);
+        }
+        catch (error) {
+            lastError = error;
+            // The caller superseded this request — do not retry, propagate the abort.
+            if (callerSignal.aborted)
+                throw error;
+            // Otherwise it was a timeout or a transient network error: retry if budget remains.
+            if (i < retries && isRetryable(error)) {
+                const wait = (_b = (_a = backoffMs[i]) !== null && _a !== void 0 ? _a : backoffMs[backoffMs.length - 1]) !== null && _b !== void 0 ? _b : 0;
+                // Rejects with an AbortError if the caller aborts mid-backoff —
+                // propagate that cancellation instead of the transient `error` above.
+                await delay(wait, callerSignal);
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            callerSignal.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    throw lastError;
+}
+
 const isDevEnv$1 = () => typeof process != 'undefined' && process.env['NODE_ENV'] != 'production';
 const emptyReturn = (query, setQuery, trackClick) => ({
     query,
@@ -710,6 +796,9 @@ const useEvoSearch = (options = {}) => {
     const [suggestions, setSuggestions] = react.useState([]);
     const [loading, setLoading] = react.useState(false);
     const [error, setError] = react.useState(null);
+    // Bumped when the browser regains connectivity, to re-run the search effect
+    // and self-heal a query that failed while offline.
+    const [retryNonce, setRetryNonce] = react.useState(0);
     const ready = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.ready) !== null && _a !== void 0 ? _a : false;
     const api = (_b = ctx === null || ctx === void 0 ? void 0 : ctx.api) !== null && _b !== void 0 ? _b : null;
     react.useEffect(() => {
@@ -717,6 +806,25 @@ const useEvoSearch = (options = {}) => {
             console.error('[EvoSearch] useEvoSearch called outside <EvoSearchProvider>. Wrap your app in <EvoSearchProvider> at the root.');
         }
     }, [ctx]);
+    // Re-running a successful search on every reconnect would refetch (and
+    // re-bill) work that already completed; only self-heal a query that's
+    // currently in an error state, mirroring the widget's `hasError` gate.
+    const hasErrorRef = react.useRef(false);
+    react.useEffect(() => {
+        hasErrorRef.current = error != null;
+    }, [error]);
+    react.useEffect(() => {
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const onOnline = () => {
+            if (hasErrorRef.current) {
+                setRetryNonce((n) => n + 1);
+            }
+        };
+        window.addEventListener('online', onOnline);
+        return () => window.removeEventListener('online', onOnline);
+    }, []);
     react.useEffect(() => {
         if (!ready || !api) {
             return;
@@ -739,7 +847,7 @@ const useEvoSearch = (options = {}) => {
         const controller = new AbortController();
         const timer = setTimeout(async () => {
             try {
-                const res = await api.search(query, undefined, controller.signal);
+                const res = await withSearchResilience((signal) => api.search(query, undefined, signal), controller.signal);
                 setResults(processAutocompleteResponse(res).products);
                 if (wantsSuggestions) {
                     setSuggestions((prev) => {
@@ -768,7 +876,32 @@ const useEvoSearch = (options = {}) => {
             clearTimeout(timer);
             controller.abort();
         };
-    }, [query, ready, api, mode]);
+    }, [query, ready, api, mode, retryNonce]);
+    // Widget parity: report a settled query as one real search after SEARCH_SETTLE_MS.
+    const lastFinalizedRef = react.useRef('');
+    react.useEffect(() => {
+        if (!api || mode === 'autocomplete' || loading || error) {
+            return;
+        }
+        const cleaned = query.trim();
+        if (!cleaned) {
+            // Clearing the query lets the same term finalize again on re-entry.
+            lastFinalizedRef.current = '';
+            return;
+        }
+        if (cleaned.toLowerCase() === lastFinalizedRef.current) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            lastFinalizedRef.current = cleaned.toLowerCase();
+            const actionData = {
+                query: cleaned,
+                resultCount: results.length,
+            };
+            api.sendEvent('evoSearchSearchIssued', undefined, actionData);
+        }, SEARCH_SETTLE_MS);
+        return () => clearTimeout(timer);
+    }, [api, mode, query, results, loading, error]);
     const trackClick = react.useCallback((productId, extra) => {
         if (!api) {
             return;

package/hooks.mjs

@@ -1,5 +1,5 @@
 import { jsx } from 'react/jsx-runtime';
-import { createContext, useSyncExternalStore, useEffect, useContext, useState, useCallback, useMemo } from 'react';
+import { createContext, useSyncExternalStore, useEffect, useContext, useState, useRef, useCallback, useMemo } from 'react';
 
 const EvoSearchContext = createContext(null);
 
@@ -630,6 +630,11 @@ const uiActions = new Set([
 new Set([...uiActions]);
 
 const DEBOUNCE_MS = 200;
+// How long a typed query must sit unchanged after its results render before
+// the widget counts it as one real search (recents + server-side query
+// metrics). Search fires per keystroke, so anything shorter than a genuine
+// reading pause would count prefixes (`a`, `ap`, `app`) as searches.
+const SEARCH_SETTLE_MS = 3000;
 
 // Intentionally duplicated from @blotoutio/providers/evo-search/config to keep the hooks bundle lean — importing from the config barrel pulls the shared/universal geo data into dist/hooks.mjs (~4KB gzipped). Drift between the two values is caught by utils.test.ts.
 const isHttpURL = (value) => {
@@ -688,6 +693,87 @@ const processAutocompleteResponse = (response) => {
     };
 };
 
+// Resilience wrapper for /search requests. A transient network failure or a
+// hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
+// a rejection), retry transient failures with backoff, and never retry a
+// caller-superseded (aborted) request. Shared by the widget and the headless
+// hook. See callers: search-widget.ts (performAutocomplete) and
+// hooks/use-evo-search.ts.
+const DEFAULTS = {
+    timeoutMs: 7000,
+    retries: 2,
+    backoffMs: [400, 1200],
+};
+// Deterministic HTTP errors (4xx other than 429) will never succeed on
+// retry — only retry timeouts, network errors, 429, and 5xx. Errors without
+// an attached `status` (network/timeout failures) are always retryable.
+const isRetryable = (error) => {
+    const status = error === null || error === void 0 ? void 0 : error.status;
+    return status == null || status === 429 || status >= 500;
+};
+const delay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new DOMException('Aborted', 'AbortError'));
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+});
+/**
+ * Run `attempt` with a timeout, retrying transient failures. `callerSignal`
+ * supersedes everything: if it aborts, we stop immediately without retrying
+ * (the query changed / the widget cleaned up). A timeout or network error is
+ * retried up to `retries` times; anything left over is rethrown.
+ */
+async function withSearchResilience(attempt, callerSignal, options = {}) {
+    var _a, _b;
+    const { timeoutMs, retries, backoffMs } = { ...DEFAULTS, ...options };
+    let lastError;
+    for (let i = 0; i <= retries; i++) {
+        if (callerSignal.aborted)
+            throw new DOMException('Aborted', 'AbortError');
+        const local = new AbortController();
+        const onCallerAbort = () => local.abort();
+        callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        // Race the attempt against an explicit timeout that REJECTS. Aborting the
+        // signal alone isn't enough — an attempt that ignores its signal would
+        // otherwise hang forever and never retry. Reject with a TimeoutError (not
+        // an AbortError) so callers surface it instead of treating it as a
+        // caller-cancellation.
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                local.abort(); // still cancel the in-flight request to free the socket
+                reject(new DOMException('Search request timed out', 'TimeoutError'));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([attempt(local.signal), timeout]);
+        }
+        catch (error) {
+            lastError = error;
+            // The caller superseded this request — do not retry, propagate the abort.
+            if (callerSignal.aborted)
+                throw error;
+            // Otherwise it was a timeout or a transient network error: retry if budget remains.
+            if (i < retries && isRetryable(error)) {
+                const wait = (_b = (_a = backoffMs[i]) !== null && _a !== void 0 ? _a : backoffMs[backoffMs.length - 1]) !== null && _b !== void 0 ? _b : 0;
+                // Rejects with an AbortError if the caller aborts mid-backoff —
+                // propagate that cancellation instead of the transient `error` above.
+                await delay(wait, callerSignal);
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            callerSignal.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    throw lastError;
+}
+
 const isDevEnv$1 = () => typeof process != 'undefined' && process.env['NODE_ENV'] != 'production';
 const emptyReturn = (query, setQuery, trackClick) => ({
     query,
@@ -708,6 +794,9 @@ const useEvoSearch = (options = {}) => {
     const [suggestions, setSuggestions] = useState([]);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
+    // Bumped when the browser regains connectivity, to re-run the search effect
+    // and self-heal a query that failed while offline.
+    const [retryNonce, setRetryNonce] = useState(0);
     const ready = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.ready) !== null && _a !== void 0 ? _a : false;
     const api = (_b = ctx === null || ctx === void 0 ? void 0 : ctx.api) !== null && _b !== void 0 ? _b : null;
     useEffect(() => {
@@ -715,6 +804,25 @@ const useEvoSearch = (options = {}) => {
             console.error('[EvoSearch] useEvoSearch called outside <EvoSearchProvider>. Wrap your app in <EvoSearchProvider> at the root.');
         }
     }, [ctx]);
+    // Re-running a successful search on every reconnect would refetch (and
+    // re-bill) work that already completed; only self-heal a query that's
+    // currently in an error state, mirroring the widget's `hasError` gate.
+    const hasErrorRef = useRef(false);
+    useEffect(() => {
+        hasErrorRef.current = error != null;
+    }, [error]);
+    useEffect(() => {
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const onOnline = () => {
+            if (hasErrorRef.current) {
+                setRetryNonce((n) => n + 1);
+            }
+        };
+        window.addEventListener('online', onOnline);
+        return () => window.removeEventListener('online', onOnline);
+    }, []);
     useEffect(() => {
         if (!ready || !api) {
             return;
@@ -737,7 +845,7 @@ const useEvoSearch = (options = {}) => {
         const controller = new AbortController();
         const timer = setTimeout(async () => {
             try {
-                const res = await api.search(query, undefined, controller.signal);
+                const res = await withSearchResilience((signal) => api.search(query, undefined, signal), controller.signal);
                 setResults(processAutocompleteResponse(res).products);
                 if (wantsSuggestions) {
                     setSuggestions((prev) => {
@@ -766,7 +874,32 @@ const useEvoSearch = (options = {}) => {
             clearTimeout(timer);
             controller.abort();
         };
-    }, [query, ready, api, mode]);
+    }, [query, ready, api, mode, retryNonce]);
+    // Widget parity: report a settled query as one real search after SEARCH_SETTLE_MS.
+    const lastFinalizedRef = useRef('');
+    useEffect(() => {
+        if (!api || mode === 'autocomplete' || loading || error) {
+            return;
+        }
+        const cleaned = query.trim();
+        if (!cleaned) {
+            // Clearing the query lets the same term finalize again on re-entry.
+            lastFinalizedRef.current = '';
+            return;
+        }
+        if (cleaned.toLowerCase() === lastFinalizedRef.current) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            lastFinalizedRef.current = cleaned.toLowerCase();
+            const actionData = {
+                query: cleaned,
+                resultCount: results.length,
+            };
+            api.sendEvent('evoSearchSearchIssued', undefined, actionData);
+        }, SEARCH_SETTLE_MS);
+        return () => clearTimeout(timer);
+    }, [api, mode, query, results, loading, error]);
     const trackClick = useCallback((productId, extra) => {
         if (!api) {
             return;

package/index.cjs.js

@@ -847,10 +847,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         throw new Error('sendTag missing');
     }
     const getHeaders = () => {
+        var _a;
         const headers = new Headers({ EdgeTagUserId: userId });
         if (sessionId) {
             headers.set('EdgeTagSessionId', sessionId);
         }
+        headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
         return headers;
     };
     // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -884,7 +886,9 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if (!response.ok) {
             const errorText = await response.text().catch(() => '');
             logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-            throw new Error(`${label} failed - ${response.status}`);
+            const error = new Error(`${label} failed - ${response.status}`);
+            error.status = response.status;
+            throw error;
         }
         return (await response.json());
     };
@@ -8305,6 +8309,87 @@ const searchWidgetStyles = i$6 `
   }
 `;
 
+// Resilience wrapper for /search requests. A transient network failure or a
+// hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
+// a rejection), retry transient failures with backoff, and never retry a
+// caller-superseded (aborted) request. Shared by the widget and the headless
+// hook. See callers: search-widget.ts (performAutocomplete) and
+// hooks/use-evo-search.ts.
+const DEFAULTS = {
+    timeoutMs: 7000,
+    retries: 2,
+    backoffMs: [400, 1200],
+};
+// Deterministic HTTP errors (4xx other than 429) will never succeed on
+// retry — only retry timeouts, network errors, 429, and 5xx. Errors without
+// an attached `status` (network/timeout failures) are always retryable.
+const isRetryable = (error) => {
+    const status = error === null || error === void 0 ? void 0 : error.status;
+    return status == null || status === 429 || status >= 500;
+};
+const delay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new DOMException('Aborted', 'AbortError'));
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+});
+/**
+ * Run `attempt` with a timeout, retrying transient failures. `callerSignal`
+ * supersedes everything: if it aborts, we stop immediately without retrying
+ * (the query changed / the widget cleaned up). A timeout or network error is
+ * retried up to `retries` times; anything left over is rethrown.
+ */
+async function withSearchResilience(attempt, callerSignal, options = {}) {
+    var _a, _b;
+    const { timeoutMs, retries, backoffMs } = { ...DEFAULTS, ...options };
+    let lastError;
+    for (let i = 0; i <= retries; i++) {
+        if (callerSignal.aborted)
+            throw new DOMException('Aborted', 'AbortError');
+        const local = new AbortController();
+        const onCallerAbort = () => local.abort();
+        callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        // Race the attempt against an explicit timeout that REJECTS. Aborting the
+        // signal alone isn't enough — an attempt that ignores its signal would
+        // otherwise hang forever and never retry. Reject with a TimeoutError (not
+        // an AbortError) so callers surface it instead of treating it as a
+        // caller-cancellation.
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                local.abort(); // still cancel the in-flight request to free the socket
+                reject(new DOMException('Search request timed out', 'TimeoutError'));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([attempt(local.signal), timeout]);
+        }
+        catch (error) {
+            lastError = error;
+            // The caller superseded this request — do not retry, propagate the abort.
+            if (callerSignal.aborted)
+                throw error;
+            // Otherwise it was a timeout or a transient network error: retry if budget remains.
+            if (i < retries && isRetryable(error)) {
+                const wait = (_b = (_a = backoffMs[i]) !== null && _a !== void 0 ? _a : backoffMs[backoffMs.length - 1]) !== null && _b !== void 0 ? _b : 0;
+                // Rejects with an AbortError if the caller aborts mid-backoff —
+                // propagate that cancellation instead of the transient `error` above.
+                await delay(wait, callerSignal);
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            callerSignal.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    throw lastError;
+}
+
 const MIN_QUERY_LENGTH = 3;
 // @state fields whose change should be persisted to the session snapshot.
 const SESSION_PERSIST_KEYS = [
@@ -8395,6 +8480,7 @@ class SearchWidget extends ElementWithStylesheet {
         // autocomplete can't overwrite a fresh search's results.
         this.requestGeneration = 0;
         this.keydownListener = (event) => this.handleKeydown(event);
+        this.onlineListener = () => this.handleReconnect();
         // Streaming tokens are coalesced into one per-frame state update rather than
         // reassigning `askAnswer` on every token — a ~220-token answer would
         // otherwise trigger ~220 full widget renders.
@@ -8439,6 +8525,20 @@ class SearchWidget extends ElementWithStylesheet {
         var _a, _b;
         (_b = (_a = this.api) === null || _a === void 0 ? void 0 : _a.warm) === null || _b === void 0 ? void 0 : _b.call(_a);
     }
+    // A transient network failure leaves the results in an error state; when
+    // connectivity returns, re-issue the current query so it self-heals without
+    // the shopper having to retype.
+    handleReconnect() {
+        if (!this.hasError) {
+            return;
+        }
+        const trimmed = this.searchQuery.trim();
+        if (trimmed.length < MIN_QUERY_LENGTH) {
+            return;
+        }
+        this.loading = true;
+        void this.performAutocomplete(trimmed);
+    }
     connectedCallback() {
         super.connectedCallback();
         // The widget always opens in Search view; Ask AI is entered only by
@@ -8455,6 +8555,7 @@ class SearchWidget extends ElementWithStylesheet {
         this.mobileMediaQuery = window.matchMedia('(max-width: 768px)');
         this.isMobile = this.mobileMediaQuery.matches;
         this.mobileMediaQuery.addEventListener('change', this.mobileMediaListener);
+        window.addEventListener('online', this.onlineListener);
     }
     firstUpdated() {
         this.focusSearchBox();
@@ -8470,6 +8571,7 @@ class SearchWidget extends ElementWithStylesheet {
         this.resetAnswerBuffer();
         this.removeEventListener('keydown', this.keydownListener);
         (_c = this.mobileMediaQuery) === null || _c === void 0 ? void 0 : _c.removeEventListener('change', this.mobileMediaListener);
+        window.removeEventListener('online', this.onlineListener);
         super.disconnectedCallback();
     }
     willUpdate(changed) {
@@ -8888,7 +8990,8 @@ class SearchWidget extends ElementWithStylesheet {
                 this.loading = false;
                 return;
             }
-            const response = await this.api.search(query, undefined, this.newResultsSignal());
+            const api = this.api;
+            const response = await withSearchResilience((signal) => api.search(query, undefined, signal), this.newResultsSignal());
             if (generation !== this.requestGeneration) {
                 return;
             }

package/index.js

@@ -848,10 +848,12 @@ var ProvidersEvoSearchSdk = (function () {
             throw new Error('sendTag missing');
         }
         const getHeaders = () => {
+            var _a;
             const headers = new Headers({ EdgeTagUserId: userId });
             if (sessionId) {
                 headers.set('EdgeTagSessionId', sessionId);
             }
+            headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
             return headers;
         };
         // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -885,7 +887,9 @@ var ProvidersEvoSearchSdk = (function () {
             if (!response.ok) {
                 const errorText = await response.text().catch(() => '');
                 logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-                throw new Error(`${label} failed - ${response.status}`);
+                const error = new Error(`${label} failed - ${response.status}`);
+                error.status = response.status;
+                throw error;
             }
             return (await response.json());
         };
@@ -8306,6 +8310,87 @@ var ProvidersEvoSearchSdk = (function () {
   }
 `;
 
+    // Resilience wrapper for /search requests. A transient network failure or a
+    // hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
+    // a rejection), retry transient failures with backoff, and never retry a
+    // caller-superseded (aborted) request. Shared by the widget and the headless
+    // hook. See callers: search-widget.ts (performAutocomplete) and
+    // hooks/use-evo-search.ts.
+    const DEFAULTS = {
+        timeoutMs: 7000,
+        retries: 2,
+        backoffMs: [400, 1200],
+    };
+    // Deterministic HTTP errors (4xx other than 429) will never succeed on
+    // retry — only retry timeouts, network errors, 429, and 5xx. Errors without
+    // an attached `status` (network/timeout failures) are always retryable.
+    const isRetryable = (error) => {
+        const status = error === null || error === void 0 ? void 0 : error.status;
+        return status == null || status === 429 || status >= 500;
+    };
+    const delay = (ms, signal) => new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new DOMException('Aborted', 'AbortError'));
+        const t = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(t);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+    /**
+     * Run `attempt` with a timeout, retrying transient failures. `callerSignal`
+     * supersedes everything: if it aborts, we stop immediately without retrying
+     * (the query changed / the widget cleaned up). A timeout or network error is
+     * retried up to `retries` times; anything left over is rethrown.
+     */
+    async function withSearchResilience(attempt, callerSignal, options = {}) {
+        var _a, _b;
+        const { timeoutMs, retries, backoffMs } = { ...DEFAULTS, ...options };
+        let lastError;
+        for (let i = 0; i <= retries; i++) {
+            if (callerSignal.aborted)
+                throw new DOMException('Aborted', 'AbortError');
+            const local = new AbortController();
+            const onCallerAbort = () => local.abort();
+            callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+            // Race the attempt against an explicit timeout that REJECTS. Aborting the
+            // signal alone isn't enough — an attempt that ignores its signal would
+            // otherwise hang forever and never retry. Reject with a TimeoutError (not
+            // an AbortError) so callers surface it instead of treating it as a
+            // caller-cancellation.
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    local.abort(); // still cancel the in-flight request to free the socket
+                    reject(new DOMException('Search request timed out', 'TimeoutError'));
+                }, timeoutMs);
+            });
+            try {
+                return await Promise.race([attempt(local.signal), timeout]);
+            }
+            catch (error) {
+                lastError = error;
+                // The caller superseded this request — do not retry, propagate the abort.
+                if (callerSignal.aborted)
+                    throw error;
+                // Otherwise it was a timeout or a transient network error: retry if budget remains.
+                if (i < retries && isRetryable(error)) {
+                    const wait = (_b = (_a = backoffMs[i]) !== null && _a !== void 0 ? _a : backoffMs[backoffMs.length - 1]) !== null && _b !== void 0 ? _b : 0;
+                    // Rejects with an AbortError if the caller aborts mid-backoff —
+                    // propagate that cancellation instead of the transient `error` above.
+                    await delay(wait, callerSignal);
+                    continue;
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                callerSignal.removeEventListener('abort', onCallerAbort);
+            }
+        }
+        throw lastError;
+    }
+
     const MIN_QUERY_LENGTH = 3;
     // @state fields whose change should be persisted to the session snapshot.
     const SESSION_PERSIST_KEYS = [
@@ -8396,6 +8481,7 @@ var ProvidersEvoSearchSdk = (function () {
             // autocomplete can't overwrite a fresh search's results.
             this.requestGeneration = 0;
             this.keydownListener = (event) => this.handleKeydown(event);
+            this.onlineListener = () => this.handleReconnect();
             // Streaming tokens are coalesced into one per-frame state update rather than
             // reassigning `askAnswer` on every token — a ~220-token answer would
             // otherwise trigger ~220 full widget renders.
@@ -8440,6 +8526,20 @@ var ProvidersEvoSearchSdk = (function () {
             var _a, _b;
             (_b = (_a = this.api) === null || _a === void 0 ? void 0 : _a.warm) === null || _b === void 0 ? void 0 : _b.call(_a);
         }
+        // A transient network failure leaves the results in an error state; when
+        // connectivity returns, re-issue the current query so it self-heals without
+        // the shopper having to retype.
+        handleReconnect() {
+            if (!this.hasError) {
+                return;
+            }
+            const trimmed = this.searchQuery.trim();
+            if (trimmed.length < MIN_QUERY_LENGTH) {
+                return;
+            }
+            this.loading = true;
+            void this.performAutocomplete(trimmed);
+        }
         connectedCallback() {
             super.connectedCallback();
             // The widget always opens in Search view; Ask AI is entered only by
@@ -8456,6 +8556,7 @@ var ProvidersEvoSearchSdk = (function () {
             this.mobileMediaQuery = window.matchMedia('(max-width: 768px)');
             this.isMobile = this.mobileMediaQuery.matches;
             this.mobileMediaQuery.addEventListener('change', this.mobileMediaListener);
+            window.addEventListener('online', this.onlineListener);
         }
         firstUpdated() {
             this.focusSearchBox();
@@ -8471,6 +8572,7 @@ var ProvidersEvoSearchSdk = (function () {
             this.resetAnswerBuffer();
             this.removeEventListener('keydown', this.keydownListener);
             (_c = this.mobileMediaQuery) === null || _c === void 0 ? void 0 : _c.removeEventListener('change', this.mobileMediaListener);
+            window.removeEventListener('online', this.onlineListener);
             super.disconnectedCallback();
         }
         willUpdate(changed) {
@@ -8889,7 +8991,8 @@ var ProvidersEvoSearchSdk = (function () {
                     this.loading = false;
                     return;
                 }
-                const response = await this.api.search(query, undefined, this.newResultsSignal());
+                const api = this.api;
+                const response = await withSearchResilience((signal) => api.search(query, undefined, signal), this.newResultsSignal());
                 if (generation !== this.requestGeneration) {
                     return;
                 }

package/index.mjs

@@ -845,10 +845,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         throw new Error('sendTag missing');
     }
     const getHeaders = () => {
+        var _a;
         const headers = new Headers({ EdgeTagUserId: userId });
         if (sessionId) {
             headers.set('EdgeTagSessionId', sessionId);
         }
+        headers.set('X-EvoSearch-Channel', ((_a = window[registryKey]) === null || _a === void 0 ? void 0 : _a.ui) ? 'widget' : 'headless');
         return headers;
     };
     // Parsing `baseURL` once at API construction avoids re-parsing the host on
@@ -882,7 +884,9 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if (!response.ok) {
             const errorText = await response.text().catch(() => '');
             logger.error(`EvoSearch API: ${label} failed - ${response.status}: ${errorText}`);
-            throw new Error(`${label} failed - ${response.status}`);
+            const error = new Error(`${label} failed - ${response.status}`);
+            error.status = response.status;
+            throw error;
         }
         return (await response.json());
     };
@@ -8303,6 +8307,87 @@ const searchWidgetStyles = i$6 `
   }
 `;
 
+// Resilience wrapper for /search requests. A transient network failure or a
+// hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
+// a rejection), retry transient failures with backoff, and never retry a
+// caller-superseded (aborted) request. Shared by the widget and the headless
+// hook. See callers: search-widget.ts (performAutocomplete) and
+// hooks/use-evo-search.ts.
+const DEFAULTS = {
+    timeoutMs: 7000,
+    retries: 2,
+    backoffMs: [400, 1200],
+};
+// Deterministic HTTP errors (4xx other than 429) will never succeed on
+// retry — only retry timeouts, network errors, 429, and 5xx. Errors without
+// an attached `status` (network/timeout failures) are always retryable.
+const isRetryable = (error) => {
+    const status = error === null || error === void 0 ? void 0 : error.status;
+    return status == null || status === 429 || status >= 500;
+};
+const delay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new DOMException('Aborted', 'AbortError'));
+    const t = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+});
+/**
+ * Run `attempt` with a timeout, retrying transient failures. `callerSignal`
+ * supersedes everything: if it aborts, we stop immediately without retrying
+ * (the query changed / the widget cleaned up). A timeout or network error is
+ * retried up to `retries` times; anything left over is rethrown.
+ */
+async function withSearchResilience(attempt, callerSignal, options = {}) {
+    var _a, _b;
+    const { timeoutMs, retries, backoffMs } = { ...DEFAULTS, ...options };
+    let lastError;
+    for (let i = 0; i <= retries; i++) {
+        if (callerSignal.aborted)
+            throw new DOMException('Aborted', 'AbortError');
+        const local = new AbortController();
+        const onCallerAbort = () => local.abort();
+        callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        // Race the attempt against an explicit timeout that REJECTS. Aborting the
+        // signal alone isn't enough — an attempt that ignores its signal would
+        // otherwise hang forever and never retry. Reject with a TimeoutError (not
+        // an AbortError) so callers surface it instead of treating it as a
+        // caller-cancellation.
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                local.abort(); // still cancel the in-flight request to free the socket
+                reject(new DOMException('Search request timed out', 'TimeoutError'));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([attempt(local.signal), timeout]);
+        }
+        catch (error) {
+            lastError = error;
+            // The caller superseded this request — do not retry, propagate the abort.
+            if (callerSignal.aborted)
+                throw error;
+            // Otherwise it was a timeout or a transient network error: retry if budget remains.
+            if (i < retries && isRetryable(error)) {
+                const wait = (_b = (_a = backoffMs[i]) !== null && _a !== void 0 ? _a : backoffMs[backoffMs.length - 1]) !== null && _b !== void 0 ? _b : 0;
+                // Rejects with an AbortError if the caller aborts mid-backoff —
+                // propagate that cancellation instead of the transient `error` above.
+                await delay(wait, callerSignal);
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            callerSignal.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    throw lastError;
+}
+
 const MIN_QUERY_LENGTH = 3;
 // @state fields whose change should be persisted to the session snapshot.
 const SESSION_PERSIST_KEYS = [
@@ -8393,6 +8478,7 @@ class SearchWidget extends ElementWithStylesheet {
         // autocomplete can't overwrite a fresh search's results.
         this.requestGeneration = 0;
         this.keydownListener = (event) => this.handleKeydown(event);
+        this.onlineListener = () => this.handleReconnect();
         // Streaming tokens are coalesced into one per-frame state update rather than
         // reassigning `askAnswer` on every token — a ~220-token answer would
         // otherwise trigger ~220 full widget renders.
@@ -8437,6 +8523,20 @@ class SearchWidget extends ElementWithStylesheet {
         var _a, _b;
         (_b = (_a = this.api) === null || _a === void 0 ? void 0 : _a.warm) === null || _b === void 0 ? void 0 : _b.call(_a);
     }
+    // A transient network failure leaves the results in an error state; when
+    // connectivity returns, re-issue the current query so it self-heals without
+    // the shopper having to retype.
+    handleReconnect() {
+        if (!this.hasError) {
+            return;
+        }
+        const trimmed = this.searchQuery.trim();
+        if (trimmed.length < MIN_QUERY_LENGTH) {
+            return;
+        }
+        this.loading = true;
+        void this.performAutocomplete(trimmed);
+    }
     connectedCallback() {
         super.connectedCallback();
         // The widget always opens in Search view; Ask AI is entered only by
@@ -8453,6 +8553,7 @@ class SearchWidget extends ElementWithStylesheet {
         this.mobileMediaQuery = window.matchMedia('(max-width: 768px)');
         this.isMobile = this.mobileMediaQuery.matches;
         this.mobileMediaQuery.addEventListener('change', this.mobileMediaListener);
+        window.addEventListener('online', this.onlineListener);
     }
     firstUpdated() {
         this.focusSearchBox();
@@ -8468,6 +8569,7 @@ class SearchWidget extends ElementWithStylesheet {
         this.resetAnswerBuffer();
         this.removeEventListener('keydown', this.keydownListener);
         (_c = this.mobileMediaQuery) === null || _c === void 0 ? void 0 : _c.removeEventListener('change', this.mobileMediaListener);
+        window.removeEventListener('online', this.onlineListener);
         super.disconnectedCallback();
     }
     willUpdate(changed) {
@@ -8886,7 +8988,8 @@ class SearchWidget extends ElementWithStylesheet {
                 this.loading = false;
                 return;
             }
-            const response = await this.api.search(query, undefined, this.newResultsSignal());
+            const api = this.api;
+            const response = await withSearchResilience((signal) => api.search(query, undefined, signal), this.newResultsSignal());
             if (generation !== this.requestGeneration) {
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotoutio/providers-evo-search-sdk",
-  "version": "1.64.1",
+  "version": "1.64.2",
   "description": "Evo Search SDK for EdgeTag",
   "author": "Blotout",
   "license": "MIT",