@findlane/browser 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -110,30 +110,79 @@ export type RecommendationHit<T> = {
     score: number | null;
     record: T;
 };
+/** A Bought together pick: `count` is the orders in the last year that had both products. */
+export type TogetherHit<T> = RecommendationHit<T> & {
+    count: number;
+};
 export type RecommendationsResponse<T> = {
     objectID: string;
-    /** false until the product's lists are built; both lists are empty meanwhile. */
+    /** false until the product's lists are built; the 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>[];
+    /** Products bought in the same orders as this one, the most orders first, from the orders the store
+     * sends as events. Empty without orders. */
+    together?: TogetherHit<T>[];
+    /** What `together`'s counts are of. */
+    togetherBasis?: "orders";
 };
 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?: {
@@ -151,3 +200,4 @@ export declare class SearchBrowserClient {
         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}`, {

package/dist/react/components.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type MouseEvent, type ReactNode } from "react";
 import type { DidYouMean as Correction } from "../index.js";
 import { type Refinement } from "./search-provider.js";
 import type { Hit } from "./state.js";
@@ -48,6 +48,9 @@ export type HitsProps<T> = {
     loading?: ReactNode;
     className?: string;
 };
+/** Whether a click was on a link inside the element that handled it, such as a hit's link. */
+export declare function onLink(event: MouseEvent<HTMLElement>): boolean;
+/** The results. Following a link in a hit sends a click event, with its place and the query. */
 export declare function Hits<T = Record<string, unknown>>({ render, empty, loading, className }: HitsProps<T>): import("react").JSX.Element;
 export type RefinementListProps = {
     field: string;

package/dist/react/components.js

@@ -38,8 +38,14 @@ export function SearchInput({ placeholder, label = "Search", className, autoFocu
     const { query, setQuery } = useSearchBox();
     return (_jsx("form", { role: "search", className: className, "data-findlane-search-input": "", onSubmit: (event) => event.preventDefault(), children: _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, autoComplete: "off", spellCheck: false, maxLength: 200 }) }));
 }
+/** Whether a click was on a link inside the element that handled it, such as a hit's link. */
+export function onLink(event) {
+    const link = event.target.closest?.("a[href]");
+    return Boolean(link && event.currentTarget.contains(link));
+}
+/** The results. Following a link in a hit sends a click event, with its place and the query. */
 export function Hits({ render, empty, loading = null, className }) {
-    const { hits, isLoaded, isPending, error } = useHits();
+    const { hits, isLoaded, isPending, error, click } = useHits();
     const { query } = useSearchBox();
     if (error && !isLoaded)
         return _jsx("p", { "data-findlane-note": "", children: messageFor(error) });
@@ -47,7 +53,13 @@ export function Hits({ render, empty, loading = null, className }) {
         return _jsx(_Fragment, { children: loading });
     if (!hits.length)
         return _jsx("p", { "data-findlane-empty": "", children: empty ? empty(query) : query ? _jsxs(_Fragment, { children: ["No results for \u201C", query, "\u201D"] }) : "No results" });
-    return (_jsx("ol", { className: className, "data-findlane-hits": "", "data-pending": isPending || undefined, children: hits.map((hit, index) => (_jsx("li", { children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id))) }));
+    return (_jsx("ol", { className: className, "data-findlane-hits": "", "data-pending": isPending || undefined, children: hits.map((hit, index) => {
+            // A click, and a middle click that opens the link in a new tab.
+            const clicked = (event) => { if (!event.defaultPrevented && onLink(event))
+                click(hit); };
+            return (_jsx("li", { onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
+                    clicked(event); }, children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id));
+        }) }));
 }
 /** Checkboxes for a facet's values, with counts. */
 export function RefinementList({ field, label, limit = 8, format, className }) {

package/dist/react/recommendations.d.ts

@@ -1,21 +1,36 @@
 import type { ReactNode } from "react";
 import type { RecommendationsRequest } from "../index.js";
-import type { ClientOptions } from "./client.js";
+import { type ClientOptions } from "./client.js";
 import type { Hit } from "./state.js";
+type List = "goesWith" | "similar" | "together";
 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. */
+    /** Products that go with it (the default), similar products, or products bought in the same orders
+     * ("together", from the orders the store sends as events). */
+    list?: List;
+    /** Another list that fills a short one, from the same response: `list="together" fill="goesWith"`
+     * gives a product with few orders a full list too. */
+    fill?: "goesWith" | "similar";
+    /** The heading; null for none. By default the list's: "Goes well with", "Similar products", or
+     * "Frequently bought together" when most products shown come from orders (otherwise the fill list's). */
     title?: ReactNode;
     /** A product's content; DefaultHit shows an image and a title. */
     render?: (hit: Hit<T>, index: number) => ReactNode;
+    /** A product's page: each product (DefaultHit, or what `render` gives) becomes a link to it. Leave it
+     * out when `render` has its own link. */
+    getHref?: (hit: Hit<T>) => string | undefined;
+    /** A product's page as a template, for server components, which can't pass `getHref`:
+     * "/products/{handle}" puts in the record's `handle`, URL-encoded, and `{objectID}` the product's ID. */
+    hrefTemplate?: string;
     /** 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;
+ * product has none, so a product page can always include it. Lists for the same product share one
+ * request. Each product says which list it came from, in data-findlane-source. Following a link in a
+ * product sends a click event with its list, place, and the product the list is for (the client's
+ * `events` option turns them off, or holds them until consent). */
+export declare function Recommendations<T = Record<string, unknown>>({ objectID, list, fill, title, render, getHref, hrefTemplate, loading, className, ...options }: RecommendationsProps<T>): import("react").JSX.Element | null;
+export {};

package/dist/react/recommendations.js

@@ -1,17 +1,39 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DefaultHit } from "./components.js";
+import { useClient } from "./client.js";
+import { DefaultHit, onLink } from "./components.js";
+import { fillTemplate } from "./use-autocomplete.js";
 import { useRecommendations } from "./use-recommendations.js";
+const headings = { goesWith: "Goes well with", similar: "Similar products", together: "Frequently bought together" };
 /** 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 }) {
+ * product has none, so a product page can always include it. Lists for the same product share one
+ * request. Each product says which list it came from, in data-findlane-source. Following a link in a
+ * product sends a click event with its list, place, and the product the list is for (the client's
+ * `events` option turns them off, or holds them until consent). */
+export function Recommendations({ objectID, list = "goesWith", fill, title, render, getHref, hrefTemplate, loading = null, className, ...options }) {
     const { data, isPending } = useRecommendations(objectID, options);
+    const client = useClient({ client: options.client, publicId: options.publicId, baseUrl: options.baseUrl });
     if (!data)
         return isPending ? _jsx(_Fragment, { children: loading }) : null;
-    const hits = data[list];
-    if (!hits.length)
+    const limit = options.limit ?? 8;
+    const own = (data[list] ?? []).slice(0, limit).map((hit) => ({ hit, source: list }));
+    const taken = new Set([objectID, ...own.map((item) => item.hit.id)]);
+    const extra = fill && fill !== list ? (data[fill] ?? []).filter((hit) => !taken.has(hit.id))
+        .slice(0, limit - own.length).map((hit) => ({ hit, source: fill })) : [];
+    const items = [...own, ...extra];
+    if (!items.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)) })] }));
+    // A heading that says what most of the list is.
+    const heading = title === undefined ? headings[fill && own.length * 2 < items.length ? fill : list] : 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: items.map(({ hit, source }, index) => {
+                    const href = getHref ? getHref(hit) : hrefTemplate ? fillTemplate(hrefTemplate, hit) : undefined;
+                    const content = render ? render(hit, index) : _jsx(DefaultHit, { hit: hit });
+                    // A click, and a middle click that opens the link in a new tab.
+                    const clicked = (event) => {
+                        if (!event.defaultPrevented && onLink(event))
+                            client.events.click(hit.id, { list: source, from: objectID, position: index + 1 });
+                    };
+                    return (_jsx("li", { "data-findlane-source": source, onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
+                            clicked(event); }, children: href ? _jsx("a", { href: href, "data-findlane-link": "", children: content }) : content }, hit.id));
+                }) })] }));
 }

package/dist/react/search-provider.d.ts

@@ -45,6 +45,11 @@ export declare function useHits<T = Record<string, unknown>>(): {
     isLoaded: boolean;
     isPending: boolean;
     error: unknown;
+    /** Sends a click event for a hit, with its place and the query, for click-through in Analytics.
+     * Hits does it for links in a hit; call it from a hit rendered without a link. */
+    click: (hit: {
+        id: string;
+    }) => void;
 };
 /** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance
  * corrected some words (`applied`, "Showing results for"), or, when nothing matched, a query that

package/dist/react/search-provider.js

@@ -76,7 +76,7 @@ export function useSearchBox() {
     return { query: state.q, setQuery, clear: () => setQuery(""), isPending: pending };
 }
 export function useHits() {
-    const [{ results, pending, error }] = useSnapshot();
+    const [{ results, pending, error }, store] = useSnapshot();
     return {
         hits: results?.hits ?? [],
         total: results?.response.total ?? 0,
@@ -92,6 +92,9 @@ export function useHits() {
         isLoaded: results !== null,
         isPending: pending,
         error,
+        /** Sends a click event for a hit, with its place and the query, for click-through in Analytics.
+         * Hits does it for links in a hit; call it from a hit rendered without a link. */
+        click: (hit) => store.click(hit.id),
     };
 }
 /** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance

package/dist/react/store.d.ts

@@ -55,6 +55,8 @@ export declare class SearchStore<T = unknown> {
     /** A new client or config, from changed props. */
     configure(client: SearchBrowserClient, config: SearchConfig): void;
     get settings(): SearchConfig;
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    click(objectID: string): void;
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state?: SearchState): void;

package/dist/react/store.js

@@ -58,6 +58,13 @@ export class SearchStore {
         this.search(false);
     }
     get settings() { return this.config; }
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    click(objectID) {
+        const results = this.snapshot.results;
+        const index = results ? results.hits.findIndex((hit) => hit.id === objectID) : -1;
+        this.client.events.click(objectID, { query: results?.request.q ?? "",
+            ...(index >= 0 ? { position: (results.request.offset ?? 0) + index + 1 } : {}) });
+    }
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state) {

package/dist/react/styles.css

@@ -163,11 +163,19 @@
 :where([data-findlane-recommendations] [data-findlane-hits]) {
   grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
 }
-:where([data-findlane-recommendations] [data-findlane-hits] > li) {
+:where([data-findlane-recommendations] [data-findlane-hits] > li),
+:where([data-findlane-recommendations] [data-findlane-link]) {
   display: grid;
   gap: 6px;
   align-content: start;
 }
+:where([data-findlane-recommendations] [data-findlane-link]) {
+  color: inherit;
+  text-decoration: none;
+}
+:where([data-findlane-recommendations] [data-findlane-link]:hover [data-findlane-title]) {
+  text-decoration: underline;
+}
 :where([data-findlane-recommendations] [data-findlane-image]) {
   width: 100%;
   height: auto;

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

@@ -1,6 +1,6 @@
 import { type HTMLAttributes, type InputHTMLAttributes } from "react";
 import type { Hit } from "./state.js";
-import type { ClientOptions } from "./client.js";
+import { type ClientOptions } from "./client.js";
 export type AutocompleteOptions<T> = ClientOptions & {
     /** Suggestions to show: 1–50 (default 6). */
     limit?: number;
@@ -28,7 +28,9 @@ export type AutocompleteOptions<T> = ClientOptions & {
 /** A hit's address from a template; links to other schemes, such as javascript:, are refused. */
 export declare function fillTemplate<T>(template: string, hit: Hit<T>): string | undefined;
 /** A search box with suggestions, as the WAI-ARIA combobox pattern: the hook keeps the state and
- * the prop getters give the input, list, and options their attributes and events. */
+ * the prop getters give the input, list, and options their attributes and events. Choosing a
+ * suggestion sends a click event with its place and the query, for click-through in Analytics (the
+ * client's `events` option turns them off, or holds them until consent). */
 export declare function useAutocomplete<T = Record<string, unknown>>(options?: AutocompleteOptions<T>): {
     query: string;
     setQuery: (value: string) => void;

package/dist/react/use-autocomplete.js

@@ -2,6 +2,7 @@
 import { useEffect, useId, useState, } from "react";
 import { valuesAt } from "./highlight.js";
 import { useSearch } from "./use-search.js";
+import { useClient } from "./client.js";
 /** A hit's address from a template; links to other schemes, such as javascript:, are refused. */
 export function fillTemplate(template, hit) {
     const value = (field) => (field === "objectID" ? hit.id : valuesAt(hit.record, field)[0] ?? "");
@@ -10,7 +11,9 @@ export function fillTemplate(template, hit) {
     return /^[a-z][a-z\d+.-]*:/i.test(href.trim()) && !/^https?:/i.test(href.trim()) ? undefined : href || undefined;
 }
 /** A search box with suggestions, as the WAI-ARIA combobox pattern: the hook keeps the state and
- * the prop getters give the input, list, and options their attributes and events. */
+ * the prop getters give the input, list, and options their attributes and events. Choosing a
+ * suggestion sends a click event with its place and the query, for click-through in Analytics (the
+ * client's `events` option turns them off, or holds them until consent). */
 export function useAutocomplete(options = {}) {
     const { limit = 6, fields, filters, sort, minLength = 1, debounceMs, hrefTemplate, onSelect, onSubmit } = options;
     const getHref = options.getHref ?? (hrefTemplate ? (hit) => fillTemplate(hrefTemplate, hit) : undefined);
@@ -33,6 +36,7 @@ export function useAutocomplete(options = {}) {
     const search = useSearch(request, {
         publicId: options.publicId, baseUrl: options.baseUrl, client: options.client, debounceMs,
     });
+    const client = useClient({ publicId: options.publicId, baseUrl: options.baseUrl, client: options.client });
     const hits = search.data?.hits ?? [];
     // Open once there's something to show: suggestions, "no results", or an error.
     const isOpen = focused && !dismissed && request !== null && (search.data !== null || search.error !== null);
@@ -49,7 +53,12 @@ export function useAutocomplete(options = {}) {
         setDismissed(true);
         setActiveIndex(-1);
     };
+    const clicked = (hit) => {
+        const index = hits.indexOf(hit);
+        client.events.click(hit.id, { query, ...(index >= 0 ? { position: index + 1 } : {}) });
+    };
     const select = (hit) => {
+        clicked(hit);
         close();
         if (onSelect)
             return onSelect(hit);
@@ -158,16 +167,20 @@ export function useAutocomplete(options = {}) {
             onClick: (event) => {
                 props.onClick?.(event);
                 const hit = hits[index];
-                // A link opened in a new tab or window is left to the browser.
-                if (event.defaultPrevented || !hit || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                if (event.defaultPrevented || !hit)
                     return;
+                // A link opened in a new tab or window is left to the browser.
+                if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                    return clicked(hit);
                 // A link without onSelect is followed as usual.
                 if (onSelect || !event.currentTarget.href) {
                     event.preventDefault();
                     select(hit);
                 }
-                else
+                else {
+                    clicked(hit);
                     close();
+                }
             },
         }),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.7.0",
+  "version": "0.9.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",