@findlane/browser 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -93,21 +93,87 @@ export type DidYouMean = {
         to: string;
     }[];
 };
+/** How a product's recommendations are served (the recommendations add-on). */
+export type RecommendationsRequest = {
+    /** Up to this many products in each list, 1 to 20; 8 by default. */
+    limit?: number;
+    /** Only picks matching these filters, as in a search, such as `{ inStock: true }`. The index's browser
+     * access decides which fields may be filtered by. */
+    filters?: SearchRequest["filters"];
+    /** The record fields to return; by default, those the index's browser access returns. */
+    attributesToRetrieve?: string[];
+    /** Goes with picks cost at most this many times the product; null for no limit. By default, the index's setting. */
+    maxPriceRatio?: number | null;
+};
+export type RecommendationHit<T> = {
+    id: string;
+    score: number | null;
+    record: T;
+};
+export type RecommendationsResponse<T> = {
+    objectID: string;
+    /** false until the product's lists are built; both lists are empty meanwhile. */
+    ready: boolean;
+    /** Products a shopper would want with this one, the likeliest first; `score` is the decision model's probability. */
+    goesWith: RecommendationHit<T>[];
+    /** Products a shopper could choose instead, then (unless the index hides them) variants of this one. */
+    similar: RecommendationHit<T>[];
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+/** A product in a cart or an order. */
+export type EventItem = {
+    objectID: string;
+    quantity?: number;
+    price?: number;
+};
+/** Where a clicked product was: its place in the results (from 1), and the search's query or the
+ * recommendation list (and the product whose list it was). */
+export type ClickDetails = {
+    position?: number;
+    query?: string;
+    list?: "goesWith" | "similar" | "together";
+    from?: string;
+};
+/** Events from the page, sent in the background: a batch a second, and what's left when the page is
+ * hidden or closed. They carry no cookie or ID. */
+export type BrowserEvents = {
+    view(objectID: string): void;
+    click(objectID: string, details?: ClickDetails): void;
+    addToCart(items: EventItem[], options?: {
+        currency?: string;
+    }): void;
+    /** Counts for Bought together only when the index allows orders from browsers (usually a server
+     * sends them); always counts on the index's Events page. */
+    purchase(order: {
+        orderID: string;
+        items: EventItem[];
+        currency?: string;
+    }): void;
+    /** With `events: "afterConsent"`: true sends the events held so far and those after; false drops them. */
+    consent(granted: boolean): void;
+    /** Sends the events waiting now. */
+    flush(): void;
+};
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /** The hosted Findlane API, used unless `baseUrl` says otherwise. */
 export declare const defaultBaseUrl = "https://api.findlane.dev";
 export type BrowserClientOptions = {
     /** The API to call; defaults to the hosted Findlane API. */
     baseUrl?: string;
     publicId: string;
-    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    fetch?: Fetch;
+    /** Whether `events` sends anything: true (the default), false, or "afterConsent" to hold events until
+     * `events.consent(true)`. */
+    events?: boolean | "afterConsent";
 };
 export declare class SearchBrowserClient {
     private readonly url;
     private readonly fetcher;
+    /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
+    readonly events: BrowserEvents;
     constructor(options: BrowserClientOptions);
     private post;
     search<T = Record<string, unknown>>(request: SearchRequest, options?: {
@@ -119,4 +185,10 @@ export declare class SearchBrowserClient {
     suggest(request: SearchRequest, options?: {
         signal?: AbortSignal;
     }): Promise<DidYouMean | null>;
+    /** A product's recommendations (the recommendations add-on): products that go with it, and similar
+     * products, for a product page or a cart. Not counted as a search. */
+    recommendations<T = Record<string, unknown>>(objectID: string, request?: RecommendationsRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<RecommendationsResponse<T>>;
 }
+export {};

package/dist/index.js

@@ -8,14 +8,60 @@ export class FindlaneError extends Error {
 }
 /** The hosted Findlane API, used unless `baseUrl` says otherwise. */
 export const defaultBaseUrl = "https://api.findlane.dev";
+function eventSender(url, fetcher, mode) {
+    let queue = [];
+    let allowed = mode === "afterConsent" ? undefined : mode;
+    let timer;
+    let listening = false;
+    const flush = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        while (allowed && queue.length) {
+            const body = JSON.stringify({ events: queue.splice(0, 100) });
+            // A beacon outlives the page; text/plain needs no CORS preflight.
+            if (fetcher || !(typeof navigator == "object" && navigator.sendBeacon?.(url, new Blob([body], { type: "text/plain" }))))
+                (fetcher ?? fetch)(url, { method: "POST", headers: { "content-type": "text/plain" }, body, keepalive: true })
+                    .catch(() => undefined);
+        }
+    };
+    const add = (event) => {
+        if (allowed === false)
+            return;
+        if (queue.push(event) > 500)
+            queue.shift();
+        if (!listening && typeof document == "object") {
+            listening = true;
+            addEventListener("pagehide", flush);
+            document.addEventListener("visibilitychange", () => document.hidden && flush());
+        }
+        timer ??= setTimeout(flush, 1000);
+    };
+    return {
+        view: (objectID) => add({ type: "view", objectID }),
+        click: (objectID, details) => add({ type: "click", objectID, ...details }),
+        addToCart: (items, options) => add({ type: "addToCart", items, ...options }),
+        purchase: (order) => add({ type: "purchase", ...order }),
+        consent(granted) {
+            allowed = granted;
+            if (granted)
+                flush();
+            else
+                queue = [];
+        },
+        flush,
+    };
+}
 export class SearchBrowserClient {
     url;
     fetcher;
+    /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
+    events;
     constructor(options) {
         if (!/^pub_[a-f0-9]{32}$/.test(options.publicId))
             throw new Error("A valid public index ID (pub_…) is required");
         this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}`;
         this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.events = eventSender(`${this.url}/events`, options.fetch, options.events ?? true);
     }
     async post(operation, request, signal) {
         const response = await this.fetcher(`${this.url}/${operation}`, {
@@ -40,4 +86,9 @@ export class SearchBrowserClient {
     async suggest(request, options = {}) {
         return (await this.post("suggest", request, options.signal)).didYouMean;
     }
+    /** A product's recommendations (the recommendations add-on): products that go with it, and similar
+     * products, for a product page or a cart. Not counted as a search. */
+    recommendations(objectID, request = {}, options = {}) {
+        return this.post("recommendations", { objectID, ...request }, options.signal);
+    }
 }

package/dist/react/cache.d.ts

@@ -1,9 +1,14 @@
-import type { SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
+import type { RecommendationsRequest, RecommendationsResponse, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
  * the query's first eight lowercase words, defaults left out, and list order ignored. */
 export declare function searchKey(request: SearchRequest): string;
+/** A product's recommendations share a key when only defaults differ: the limit of 8 and empty filters. */
+export declare function recommendationsKey(objectID: string, request?: RecommendationsRequest): string;
 /** A cached response, if there's a recent one. */
 export declare function peek<T>(client: SearchBrowserClient, request: SearchRequest): SearchResponse<T> | null;
+export declare function peekRecommendations<T>(client: SearchBrowserClient, objectID: string, request?: RecommendationsRequest): RecommendationsResponse<T> | null;
 /** The search's response: from memory, from the same search in flight, or a new request. A caller's
  * signal stops its own wait; the request stops once every caller waiting for it has. */
 export declare function cachedSearch<T>(client: SearchBrowserClient, request: SearchRequest, signal?: AbortSignal): Promise<SearchResponse<T>>;
+/** A product's recommendations, kept and shared the same way. */
+export declare function cachedRecommendations<T>(client: SearchBrowserClient, objectID: string, request?: RecommendationsRequest, signal?: AbortSignal): Promise<RecommendationsResponse<T>>;

package/dist/react/cache.js

@@ -1,8 +1,9 @@
 import { canonical } from "./state.js";
 const size = 50;
 const maxAge = 5 * 60_000;
-const caches = new WeakMap();
-const flights = new WeakMap();
+const store = () => ({ responses: new WeakMap(), flights: new WeakMap() });
+const searches = store();
+const recommendations = store();
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
  * the query's first eight lowercase words, defaults left out, and list order ignored. */
 export function searchKey(request) {
@@ -20,58 +21,77 @@ export function searchKey(request) {
     }
     return canonical(normal);
 }
+/** A product's recommendations share a key when only defaults differ: the limit of 8 and empty filters. */
+export function recommendationsKey(objectID, request = {}) {
+    const { limit, filters, ...rest } = request;
+    return canonical({ objectID, ...rest, ...(limit !== undefined && limit !== 8 ? { limit } : {}),
+        ...(filters && Object.keys(filters).length ? { filters } : {}) });
+}
+function lookup(from, client, key) {
+    const entry = from.responses.get(client)?.get(key);
+    return entry && Date.now() - entry.at < maxAge ? entry.response : null;
+}
 /** A cached response, if there's a recent one. */
 export function peek(client, request) {
-    const entry = caches.get(client)?.get(searchKey(request));
-    return entry && Date.now() - entry.at < maxAge ? entry.response : null;
+    return lookup(searches, client, searchKey(request));
+}
+export function peekRecommendations(client, objectID, request) {
+    return lookup(recommendations, client, recommendationsKey(objectID, request));
 }
 /** The search's response: from memory, from the same search in flight, or a new request. A caller's
  * signal stops its own wait; the request stops once every caller waiting for it has. */
 export function cachedSearch(client, request, signal) {
-    const found = peek(client, request);
+    return shared(searches, client, searchKey(request), (stop) => client.search(request, { signal: stop }), signal);
+}
+/** A product's recommendations, kept and shared the same way. */
+export function cachedRecommendations(client, objectID, request = {}, signal) {
+    return shared(recommendations, client, recommendationsKey(objectID, request), (stop) => client.recommendations(objectID, request, { signal: stop }), signal);
+}
+function shared(from, client, key, load, signal) {
+    const found = lookup(from, client, key);
     if (found)
         return Promise.resolve(found);
     if (signal?.aborted)
         return Promise.reject(signal.reason);
-    const key = searchKey(request);
-    let inFlight = flights.get(client);
+    let inFlight = from.flights.get(client);
     if (!inFlight)
-        flights.set(client, (inFlight = new Map()));
-    let flight = inFlight.get(key);
+        from.flights.set(client, (inFlight = new Map()));
+    const flights = inFlight;
+    let flight = flights.get(key);
     if (!flight) {
         const controller = new AbortController();
         const started = {
             controller,
             waiting: 0,
-            response: client.search(request, { signal: controller.signal }).then((response) => {
-                remember(client, key, response);
+            response: load(controller.signal).then((response) => {
+                remember(from, client, key, response);
                 return response;
-            }).finally(() => { if (inFlight.get(key) === started)
-                inFlight.delete(key); }),
+            }).finally(() => { if (flights.get(key) === started)
+                flights.delete(key); }),
         };
-        inFlight.set(key, (flight = started));
+        flights.set(key, (flight = started));
     }
-    const shared = flight;
-    shared.waiting++;
+    const current = flight;
+    current.waiting++;
     return new Promise((resolve, reject) => {
         const leave = () => {
             reject(signal.reason);
-            if (--shared.waiting > 0)
+            if (--current.waiting > 0)
                 return;
             // A later caller starts a new request rather than joining a stopped one.
-            if (inFlight.get(key) === shared)
-                inFlight.delete(key);
-            shared.controller.abort();
+            if (flights.get(key) === current)
+                flights.delete(key);
+            current.controller.abort();
         };
         signal?.addEventListener("abort", leave, { once: true });
-        shared.response.then((response) => resolve(response), reject)
+        current.response.then((response) => resolve(response), reject)
             .finally(() => signal?.removeEventListener("abort", leave));
     });
 }
-function remember(client, key, response) {
-    let cache = caches.get(client);
+function remember(from, client, key, response) {
+    let cache = from.responses.get(client);
     if (!cache)
-        caches.set(client, (cache = new Map()));
+        from.responses.set(client, (cache = new Map()));
     cache.delete(key);
     cache.set(key, { at: Date.now(), response });
     // A Map keeps insertion order, so the first key is the oldest.

package/dist/react/index.d.ts

@@ -1,6 +1,8 @@
 export { FindlaneProvider, useClient, type ClientOptions } from "./client.js";
 export { useSearch, type UseSearchOptions, type UseSearchResult } from "./use-search.js";
 export { useAutocomplete, type AutocompleteOptions } from "./use-autocomplete.js";
+export { useRecommendations, type UseRecommendationsOptions, type UseRecommendationsResult } from "./use-recommendations.js";
+export { Recommendations, type RecommendationsProps } from "./recommendations.js";
 export { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.js";
 export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, type HitsProps, type RefinementListProps, type SearchBoxProps, } from "./components.js";
 export { SearchDialog, type SearchDialogProps } from "./dialog.js";

package/dist/react/index.js

@@ -1,8 +1,10 @@
 "use client";
-// @findlane/browser/react: hooks that keep searches current, and components built on them.
+// @findlane/browser/react: hooks that keep searches (and recommendations) current, and components built on them.
 export { FindlaneProvider, useClient } from "./client.js";
 export { useSearch } from "./use-search.js";
 export { useAutocomplete } from "./use-autocomplete.js";
+export { useRecommendations } from "./use-recommendations.js";
+export { Recommendations } from "./recommendations.js";
 export { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, } from "./search-provider.js";
 export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
 export { SearchDialog } from "./dialog.js";

package/dist/react/recommendations.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { RecommendationsRequest } from "../index.js";
+import type { ClientOptions } from "./client.js";
+import type { Hit } from "./state.js";
+export type RecommendationsProps<T> = ClientOptions & RecommendationsRequest & {
+    /** The product whose recommendations to show. */
+    objectID: string;
+    /** Products that go with it (the default), or similar products. */
+    list?: "goesWith" | "similar";
+    /** The heading (default "Goes well with" or "Similar products"); null for none. */
+    title?: ReactNode;
+    /** A product's content; DefaultHit shows an image and a title. */
+    render?: (hit: Hit<T>, index: number) => ReactNode;
+    /** Shown while the lists load. */
+    loading?: ReactNode;
+    className?: string;
+};
+/** One of a product's recommendation lists (the recommendations add-on). It renders nothing while the
+ * product has none, so a product page can always include it. A Goes with and a Similar list for the
+ * same product share one request. */
+export declare function Recommendations<T = Record<string, unknown>>({ objectID, list, title, render, loading, className, ...options }: RecommendationsProps<T>): import("react").JSX.Element | null;

package/dist/react/recommendations.js

@@ -0,0 +1,17 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DefaultHit } from "./components.js";
+import { useRecommendations } from "./use-recommendations.js";
+/** One of a product's recommendation lists (the recommendations add-on). It renders nothing while the
+ * product has none, so a product page can always include it. A Goes with and a Similar list for the
+ * same product share one request. */
+export function Recommendations({ objectID, list = "goesWith", title, render, loading = null, className, ...options }) {
+    const { data, isPending } = useRecommendations(objectID, options);
+    if (!data)
+        return isPending ? _jsx(_Fragment, { children: loading }) : null;
+    const hits = data[list];
+    if (!hits.length)
+        return null;
+    const heading = title === undefined ? (list === "goesWith" ? "Goes well with" : "Similar products") : title;
+    return (_jsxs("section", { className: className, "data-findlane-recommendations": list, children: [heading !== null && _jsx("h2", { "data-findlane-recommendations-title": "", children: heading }), _jsx("ol", { "data-findlane-hits": "", children: hits.map((hit, index) => _jsx("li", { children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id)) })] }));
+}

package/dist/react/styles.css

@@ -152,6 +152,28 @@
   transition: opacity 0.15s 0.1s;
 }
 
+:where([data-findlane-recommendations]) {
+  margin: 24px 0;
+}
+:where([data-findlane-recommendations-title]) {
+  margin: 0 0 12px;
+  font-size: 1.1em;
+  font-weight: 600;
+}
+:where([data-findlane-recommendations] [data-findlane-hits]) {
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+}
+:where([data-findlane-recommendations] [data-findlane-hits] > li) {
+  display: grid;
+  gap: 6px;
+  align-content: start;
+}
+:where([data-findlane-recommendations] [data-findlane-image]) {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 1;
+}
+
 :where([data-findlane-refinement-list]) {
   min-width: 0;
   margin: 0 0 18px;

package/dist/react/use-recommendations.d.ts

@@ -0,0 +1,14 @@
+import type { RecommendationsRequest, RecommendationsResponse } from "../index.js";
+import { type ClientOptions } from "./client.js";
+export type UseRecommendationsOptions<T> = ClientOptions & RecommendationsRequest & {
+    /** Lists for the first product, such as ones from the server. */
+    initialData?: RecommendationsResponse<T>;
+};
+export type UseRecommendationsResult<T> = {
+    data: RecommendationsResponse<T> | null;
+    error: unknown;
+    isPending: boolean;
+};
+/** A product's recommendations (the recommendations add-on): products that go with it, and similar
+ * products. Components asking for the same product at once share one request. Pass `null` for none. */
+export declare function useRecommendations<T = Record<string, unknown>>(objectID: string | null, { initialData, client: given, publicId, baseUrl, ...request }?: UseRecommendationsOptions<T>): UseRecommendationsResult<T>;

package/dist/react/use-recommendations.js

@@ -0,0 +1,41 @@
+"use client";
+import { useEffect, useState } from "react";
+import { cachedRecommendations, peekRecommendations, recommendationsKey } from "./cache.js";
+import { useClient } from "./client.js";
+/** A product's recommendations (the recommendations add-on): products that go with it, and similar
+ * products. Components asking for the same product at once share one request. Pass `null` for none. */
+export function useRecommendations(objectID, { initialData, client: given, publicId, baseUrl, ...request } = {}) {
+    const client = useClient({ client: given, publicId, baseUrl });
+    const key = objectID === null ? null : recommendationsKey(objectID, request);
+    const [result, setResult] = useState(() => ({
+        data: initialData && initialData.objectID === objectID ? initialData : null,
+        error: null,
+        isPending: objectID !== null && !(initialData && initialData.objectID === objectID),
+    }));
+    useEffect(() => {
+        if (objectID === null) {
+            setResult((current) => (current.data || current.error || current.isPending ? { data: null, error: null, isPending: false } : current));
+            return;
+        }
+        if (initialData && initialData.objectID === objectID)
+            return;
+        const cached = peekRecommendations(client, objectID, request);
+        if (cached) {
+            setResult({ data: cached, error: null, isPending: false });
+            return;
+        }
+        setResult((current) => (current.isPending ? current : { ...current, isPending: true }));
+        let active = true;
+        const controller = new AbortController();
+        cachedRecommendations(client, objectID, request, controller.signal).then((data) => { if (active)
+            setResult({ data, error: null, isPending: false }); }, (error) => { if (active)
+            setResult((current) => ({ ...current, error, isPending: false })); });
+        return () => {
+            active = false;
+            controller.abort();
+        };
+        // The key stands for the product and options, so a new options object asking the same doesn't fetch again.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, key]);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Findlane browser SDK: fast, typo-tolerant public search from the browser with an index's public ID, plus React hooks and components.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "instant search", "ecommerce search", "browser", "react", "autocomplete"],
   "license": "MIT",