@blotoutio/providers-evo-search-sdk 1.66.2 → 1.68.0

package/README.md

@@ -54,6 +54,122 @@ function HeaderSearch() {
 }
 ```
 
+## Image search
+
+Shoppers can search with a photo instead of words. The hook exposes it as one extra action that writes the same `results` / `loading` / `error` state as the text path, so you render one result list:
+
+```tsx
+import { useEvoSearch } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+function ImageSearch() {
+  const { query, searchByImage, results, loading, error } = useEvoSearch()
+  return (
+    <>
+      <input
+        type='file'
+        accept='image/*'
+        onChange={(e) => {
+          const file = e.target.files?.[0]
+          if (file) {
+            // Second argument is an optional text refinement ("in blue").
+            void searchByImage(file, query)
+          }
+        }}
+      />
+      {loading && <span>Searching…</span>}
+      {error && <span>Image search failed. Try again.</span>}
+      <ul>
+        {results.map((p) => (
+          <li key={p.id}>{p.title}</li>
+        ))}
+      </ul>
+    </>
+  )
+}
+```
+
+Pass a `File` or `Blob` straight from the file input (or a drop / paste handler) — it is downscaled and JPEG-encoded for you. A `string` is taken as an already-prepared `data:` URI and sent as-is.
+
+### Check the merchant gate first
+
+Image search is off unless the merchant enabled it, exactly like Ask AI. Read it from the API config and hide the affordance when it is not enabled:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { useEvoSearchAPI } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+function useVisualSearchEnabled() {
+  const { api, ready } = useEvoSearchAPI()
+  const [enabled, setEnabled] = useState(false)
+  useEffect(() => {
+    if (!ready || !api) {
+      return
+    }
+    void api
+      // Older workers omit the field, so compare strictly — a missing value
+      // means off, never on.
+      .config()
+      .then((config) => setEnabled(config.visualSearchEnabled === true))
+      .catch(() => setEnabled(false))
+  }, [api, ready])
+  return enabled
+}
+```
+
+If the merchant turns it off between that check and a search, the request fails with `403` and the rejection carries `disabled: true`. Treat that as "hide the entry point", not as an error to show:
+
+```tsx
+import type { EvoSearchAPIError } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+if ((error as EvoSearchAPIError | null)?.disabled) {
+  // Hide the camera button — nothing the shopper can retry.
+}
+```
+
+### The raw API (non-React, or your own state)
+
+In React, `useEvoSearchAPI()` hands you the API object:
+
+```tsx
+const { api } = useEvoSearchAPI()
+const { mode, products } = await api.searchImage(file, 'in blue')
+```
+
+It is the same object the registry holds, so a vanilla storefront can reach it without the hook:
+
+```js
+const api = window[Symbol.for('evo-search')]?.api
+const { mode, products } = await api.searchImage(file, 'in blue')
+```
+
+`searchImage` returns the API product shape, not the normalized one `useEvoSearch().results` yields. Map it if you want both paths to render through the same components:
+
+```js
+import { mapAPIProductToSDKProduct } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+const normalized = products.map(mapAPIProductToSDKProduct)
+```
+
+### Timeouts are your responsibility on the raw API
+
+`searchImage` has no built-in deadline: pass an `AbortSignal` so a stalled embedding can't hang your UI forever. Do not retry — every attempt costs a multimodal embedding, and there is no response cache on this route. `useEvoSearch().searchByImage` already applies this policy (no retries, 15s budget):
+
+```js
+const controller = new AbortController()
+const timer = setTimeout(() => controller.abort(), 15_000)
+try {
+  await api.searchImage(file, undefined, undefined, controller.signal)
+} finally {
+  clearTimeout(timer)
+}
+```
+
+Debounce and abort rather than firing per keystroke when a text refinement is attached to an image.
+
+### Why 768px
+
+Uploads are downscaled to a 768px long edge before they leave the browser: retrieval quality was tuned at that rendition, and the endpoint caps the decoded payload (~1.5MB), which a phone photo blows past. If you want to prepare or preview the data URI yourself, `downscaleImage(file)` and `MAX_IMAGE_EDGE` are exported from the same entry point — it rejects anything that isn't an image.
+
 ## 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.**

package/core.cjs.js

@@ -598,6 +598,19 @@ const hasPreviewKey = () => {
         return false;
     }
 };
+// Session-sticky opt-out for internal QA: ?evs=off suppresses the widget even
+// when the manifest has it enabled, so the merchant's default site can be
+// previewed. Takes precedence over both `enabled` and the preview flag.
+const disableKeyName = 'disableEvoSearch';
+const hasDisableKey = () => {
+    var _a;
+    try {
+        return ((_a = sessionStorage.getItem(disableKeyName)) !== null && _a !== void 0 ? _a : '0') === '1';
+    }
+    catch {
+        return false;
+    }
+};
 
 var _a;
 const registryKey = Symbol.for('evo-search');
@@ -640,6 +653,10 @@ const notifyReady = () => {
 // caller-superseded (aborted) request. Shared by the widget and the headless
 // hook. See callers: search-widget.ts (performAutocomplete) and
 // hooks/use-evo-search.ts.
+// Per-attempt budget for /search/image, shared by the widget and the headless
+// hook so the two can't drift. Wider than the text search's 7s: the request
+// carries an upload and waits on a multimodal embedding.
+const IMAGE_SEARCH_TIMEOUT_MS = 15000;
 const DEFAULTS = {
     timeoutMs: 7000,
     retries: 2,
@@ -743,6 +760,126 @@ async function withSearchResilience(attempt, callerSignal, options = {}) {
     throw lastError;
 }
 
+// Client-side downscale for image search. The worker caps the decoded upload at
+// ~1.5MB and every request costs a multimodal embed, so shrinking a phone photo
+// here (a 12MP JPEG is ~4MB) is what keeps the request inside the cap and the
+// upload quick on mobile data. Matches the sync-time `imageEmbedWidth` (see
+// search-tuning.ts) so query and index renditions land in the same Gemini
+// tiling bracket — a JPEG at this edge is still two orders of magnitude below
+// the worker's decoded-size cap.
+const MAX_IMAGE_EDGE = 768;
+const JPEG_QUALITY = 0.85;
+// Fallback decode for engines without createImageBitmap. Orientation here is
+// whatever the UA's `image-orientation` default is — see decodeImage.
+const loadImage = (source) => new Promise((resolve, reject) => {
+    const objectUrl = URL.createObjectURL(source);
+    const image = new Image();
+    image.onload = () => {
+        URL.revokeObjectURL(objectUrl);
+        resolve(image);
+    };
+    image.onerror = () => {
+        URL.revokeObjectURL(objectUrl);
+        reject(new Error('Image could not be decoded'));
+    };
+    image.src = objectUrl;
+});
+// createImageBitmap pins EXIF orientation explicitly, so a portrait phone photo
+// is embedded upright even on engines that predate the
+// `image-orientation: from-image` default (older iOS Safari, the embedded
+// Android WebViews storefront traffic includes) — a sideways embed degrades
+// retrieval with no error to show for it. It also skips the full-size <img>
+// decode. So it goes first, and the <img> path catches everything it can't do:
+// engines that lack the API, and the sources it rejects outright but <img>
+// renders (an SVG with no intrinsic size is the one that shows up).
+// A very large source can still yield a blank canvas on old iOS; if blank
+// embeds are ever observed, add a source pixel-count ceiling here.
+const decodeImage = async (source) => {
+    if (typeof createImageBitmap === 'function') {
+        try {
+            const bitmap = await createImageBitmap(source, {
+                imageOrientation: 'from-image',
+            });
+            return {
+                image: bitmap,
+                width: bitmap.width,
+                height: bitmap.height,
+                // Phone memory doesn't wait for GC to reclaim a decoded bitmap.
+                release: () => bitmap.close(),
+            };
+        }
+        catch {
+            // Fall through: a rejection here means "this decoder can't", not "this
+            // isn't an image". The legacy path decides, and only its failure is the
+            // shopper's error.
+        }
+    }
+    const image = await loadImage(source);
+    return {
+        image,
+        width: image.naturalWidth,
+        height: image.naturalHeight,
+        release: () => undefined,
+    };
+};
+// Draw `image` — or just `region` of it — into a fresh canvas whose longest
+// edge is at most `maxEdge`, on a white ground. A cropped region is scaled to
+// the same edge cap as the whole frame, so a selection is embedded at the
+// resolution the index renditions were built at rather than at whatever
+// fraction of the frame it happened to occupy.
+const renderToCanvas = (image, sourceWidth, sourceHeight, maxEdge, region) => {
+    const sx = region ? Math.round(region.x * sourceWidth) : 0;
+    const sy = region ? Math.round(region.y * sourceHeight) : 0;
+    const sw = region
+        ? Math.max(1, Math.round(region.w * sourceWidth))
+        : sourceWidth;
+    const sh = region
+        ? Math.max(1, Math.round(region.h * sourceHeight))
+        : sourceHeight;
+    const longestEdge = Math.max(sw, sh);
+    const scale = longestEdge > maxEdge ? maxEdge / longestEdge : 1;
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.max(1, Math.round(sw * scale));
+    canvas.height = Math.max(1, Math.round(sh * scale));
+    const context = canvas.getContext('2d');
+    if (!context) {
+        throw new Error('Canvas is unavailable');
+    }
+    // JPEG has no alpha, so a transparent source (a PNG/WebP cutout, the common
+    // paste case) would otherwise composite onto the canvas's transparent-black
+    // default and be embedded as a black-backed product. Catalog shots are
+    // typically white-background, so white is the closer prior.
+    context.fillStyle = '#ffffff';
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    if (region) {
+        context.drawImage(image, sx, sy, sw, sh, 0, 0, canvas.width, canvas.height);
+    }
+    else {
+        context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    }
+    return canvas;
+};
+/**
+ * Downscale `source` to a JPEG data URI whose longest edge is at most
+ * `MAX_IMAGE_EDGE`, upright regardless of the source's EXIF orientation.
+ * Rejects anything that isn't an image, and anything the browser can't decode
+ * (HEIC off iOS, corrupt files) — every input path (file picker, drop, paste) is
+ * shopper-controlled, so this is the trust boundary that keeps a stray PDF or
+ * text drop off the wire.
+ */
+const downscaleImage = async (source) => {
+    if (!source.type.startsWith('image/')) {
+        throw new Error('Only image files can be searched');
+    }
+    const { image, width, height, release } = await decodeImage(source);
+    try {
+        return renderToCanvas(image, width, height, MAX_IMAGE_EDGE).toDataURL('image/jpeg', JPEG_QUALITY);
+    }
+    finally {
+        release();
+    }
+};
+
 // Ask can't reuse withSearchResilience: a half-consumed stream isn't retryable.
 // Idle timeout resets per chunk; both reject with TimeoutError so submitAsk
 // routes them to the search fallback rather than treating them as cancellation.
@@ -792,6 +929,11 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
             headers.set('EdgeTagSessionId', sessionId);
         }
         headers.set('X-EvoSearch-Channel', getChannel());
+        // Only sent when the merchant is actually previewing; these routes preflight
+        // anyway, so the extra header costs no round-trip.
+        if (hasPreviewKey()) {
+            headers.set('X-EvoSearch-Preview', '1');
+        }
         return headers;
     };
     // Identity for the public read endpoints travels as query params instead of
@@ -806,6 +948,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
             url.searchParams.set('sid', sessionId);
         }
         url.searchParams.set('channel', getChannel());
+        // Emitted only when previewing: a live-traffic search URL has to stay
+        // byte-identical to today's or the edge cache fragments and the hit rate
+        // regresses on the per-keystroke hot path.
+        if (hasPreviewKey()) {
+            url.searchParams.set('preview', '1');
+        }
     };
     // Parsing `baseURL` once at API construction avoids re-parsing the host on
     // every keystroke when `getURL` runs inside the autocomplete hot path.
@@ -918,7 +1066,7 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
     const clearRecents = () => sendMutation('/user/recents', 'ClearRecents', 'DELETE');
     // Resilience lives here, not at each call site, so no consumer can opt out —
     // the headless channel previously had no deadline and no retry.
-    const search = async (query, limit = 8, signal) => {
+    const search = async (query, limit = 24, signal) => {
         logger.info(`EvoSearch API: Search request - query length: ${query.length}, limit: ${limit}`);
         const data = await withSearchResilience((attemptSignal) => getJSON('/search', 'Search', { q: query, limit: String(limit) }, attemptSignal), 
         // Shared stand-in is safe: the wrapper removes its abort listener per attempt.
@@ -926,6 +1074,62 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         logger.info(`EvoSearch API: Search success - ${data.llmSuggestions.length} suggestions, ${data.products.length} products`);
         return data;
     };
+    // Image search. Unlike `/search` there is no response cache on the worker
+    // side and every call costs a multimodal embedding, so callers must debounce
+    // and abort rather than fire per keystroke. A 403 `{disabled:true}` means the
+    // merchant turned visual search off — surfaced as `disabled` on the thrown
+    // error so the widget can hide the affordance instead of showing an error.
+    //
+    // A File/Blob (the common case headlessly: straight off an `<input
+    // type="file">`) is downscaled and JPEG-encoded here, which is both the size
+    // cap the worker enforces and the trust boundary that keeps a non-image off
+    // the wire. A string is assumed to be a prepared data URI and passes through.
+    const searchImage = async (image, text, limit, signal) => {
+        var _a;
+        const dataUri = typeof image === 'string' ? image : await downscaleImage(image);
+        logger.info(`EvoSearch API: Image search request - text length: ${(_a = text === null || text === void 0 ? void 0 : text.length) !== null && _a !== void 0 ? _a : 0}`);
+        const headers = getHeaders();
+        headers.set('Content-Type', 'application/json');
+        // The widget and the hook wrap this in a no-retry resilience budget; a raw
+        // consumer that passes no signal gets the same deadline here rather than a
+        // request that can hang indefinitely.
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort();
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onCallerAbort);
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            controller.abort();
+        }
+        const timer = setTimeout(() => controller.abort(), IMAGE_SEARCH_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetchImpl(getURL('/search/image'), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    image: dataUri,
+                    ...(text ? { text } : {}),
+                    ...(limit === undefined ? {} : { limit }),
+                }),
+                credentials: 'omit',
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onCallerAbort);
+        }
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => '');
+            logger.error(`EvoSearch API: ImageSearch failed - ${response.status}: ${errorText}`);
+            const error = new Error(`ImageSearch failed - ${response.status}`);
+            error.status = response.status;
+            if (response.status === 403 && isDisabledBody(errorText)) {
+                error.disabled = true;
+            }
+            throw error;
+        }
+        return (await response.json());
+    };
     // SSE consumer for Ask AI. Decodes `event: <type>\ndata: <json>` frames
     // from the worker stream and yields typed events as they arrive. Caller
     // aborts via the AbortSignal — fetch teardown closes the underlying
@@ -1091,10 +1295,19 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
             clearRecents,
         },
         search,
+        searchImage,
         askStream,
         sendEvent,
     };
 };
+const isDisabledBody = (body) => {
+    try {
+        return JSON.parse(body).disabled === true;
+    }
+    catch {
+        return false;
+    }
+};
 const parseSseFrame = (frame) => {
     let eventType = '';
     const dataLines = [];
@@ -1161,8 +1374,10 @@ const init = (params) => {
         // A re-init can land on a different channel, or bail out entirely, so drop
         // any previous cadence before deciding which one this run owns.
         disposeKeepWarm === null || disposeKeepWarm === void 0 ? void 0 : disposeKeepWarm();
-        if (new URLSearchParams(window.location.search).get('evs') === 'preview') {
+        const evsParam = new URLSearchParams(window.location.search).get('evs');
+        if (evsParam === 'preview') {
             try {
+                sessionStorage.removeItem(disableKeyName);
                 sessionStorage.setItem(previewKeyName, '1');
                 logger.info('EvoSearch SDK: Preview mode enabled via ?evs=preview URL param');
             }
@@ -1170,11 +1385,32 @@ const init = (params) => {
                 error('EvoSearch SDK: Failed to set previewEvoSearch sessionStorage');
             }
         }
+        else if (evsParam === 'off') {
+            try {
+                sessionStorage.removeItem(previewKeyName);
+                sessionStorage.setItem(disableKeyName, '1');
+                logger.info('EvoSearch SDK: Disabled via ?evs=off URL param');
+            }
+            catch {
+                error('EvoSearch SDK: Failed to set disableEvoSearch sessionStorage');
+            }
+        }
+        else if (evsParam === 'reset') {
+            try {
+                sessionStorage.removeItem(previewKeyName);
+                sessionStorage.removeItem(disableKeyName);
+                logger.info('EvoSearch SDK: Reset to configured state via ?evs=reset URL param');
+            }
+            catch {
+                error('EvoSearch SDK: Failed to clear evoSearch sessionStorage');
+            }
+        }
         const { enabled, uiPreferences, askAi } = (_c = (_b = params.manifest) === null || _b === void 0 ? void 0 : _b.variables) !== null && _c !== void 0 ? _c : {};
         const mode = uiPreferences === null || uiPreferences === void 0 ? void 0 : uiPreferences.mode;
         const askAiEnabled = (askAi === null || askAi === void 0 ? void 0 : askAi.enabled) === true;
+        const visualSearchEnabled = (uiPreferences === null || uiPreferences === void 0 ? void 0 : uiPreferences.visualSearch) === true;
         const hasPreview = hasPreviewKey();
-        const shouldEnable = enabled || hasPreview;
+        const shouldEnable = !hasDisableKey() && (enabled || hasPreview);
         if (!shouldEnable) {
             logger.info('EvoSearch SDK: Mode is disabled, skipping initialization');
             return;
@@ -1222,6 +1458,7 @@ const init = (params) => {
             api: evoSearchAPI,
             uiPreferences,
             askAiEnabled,
+            visualSearchEnabled,
         });
         params.sendTag({
             eventId: crypto.randomUUID(),
@@ -1244,7 +1481,7 @@ const init = (params) => {
 const tag = ({ data }) => {
     try {
         return {
-            sdkVersion: "1.66.2" || '',
+            sdkVersion: "1.68.0" || '',
             searchQuery: data['searchQuery'],
             searchResults: data['searchResults'],
             timestamp: Date.now(),
@@ -1253,7 +1490,7 @@ const tag = ({ data }) => {
     catch (err) {
         console.error(`EvoSearch SDK: Tagging failed - ${err}`);
         return {
-            sdkVersion: "1.66.2" ,
+            sdkVersion: "1.68.0" ,
             timestamp: Date.now(),
         };
     }