@findlane/browser 0.11.0 → 0.13.0

package/README.md

@@ -60,6 +60,10 @@ import "@findlane/browser/react/styles.css" // optional
 
 A response has `hits` (each with its `record` and any `highlights`), `total`, `facets`, and `tookMs`. Pass `{ signal }` as a second argument to cancel a request, as search-as-you-type should.
 
+## Events
+
+`client.events` sends views, clicks, add-to-carts and orders in the background, for the index's Events page and Bought together. With `visitorIds: true`, they also carry random IDs for the browser and the visit, when the index takes them, and `client.events.forget()` deletes the IDs and asks for their events to be deleted. Docs: https://findlane.dev/docs/events
+
 ## Security
 
 The public ID grants search access only to its index, and it is visible in browser source. By default the API returns every uploaded record field. `attributesToRetrieve` requests fewer fields for speed, but it does not make the others private. Origin checks constrain browsers; they do not authenticate other callers. Keep public catalog fields safe to expose. The dashboard can remove origins, add server-enforced restrictions, or rotate the ID.

package/dist/index.d.ts

@@ -2,7 +2,13 @@ export type SearchRequest = {
     q?: string;
     /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
-    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    /** Field values to keep. Each field takes a value (a list field contains it), or an object of
+     * conditions that all apply: `in` (any of up to 100 values), `all` (a list field has every one),
+     * `not` and `notIn` (records without the field stay in), and `gte`/`lte` for numbers and dates, such
+     * as `{ tags: { in: ["kids", "adult"], notIn: ["party"] }, price: { lte: 50 } }`. `"$or"` takes one to
+     * four groups of field filters and keeps records that match any group:
+     * `{ inStock: true, $or: [{ brand: "Acme" }, { price: { lte: 20 } }] }`. Up to 20 field filters,
+     * counting those in groups. */
     filters?: Record<string, unknown>;
     facets?: string[];
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
@@ -81,6 +87,16 @@ export type SearchResponse<T> = {
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
+    /** The index's query rules the query fired, in the index's order, with their `userData`, such as a banner
+     * to show or a page to go to. Left out when none fired. */
+    appliedRules?: AppliedRule[];
+    /** When a rule replaced words: the query that was searched. */
+    rewrittenQuery?: string;
+};
+/** A query rule a search fired, with its `userData`, if it has any. */
+export type AppliedRule = {
+    id: string;
+    userData?: unknown;
 };
 /** A corrected query. `applied`: the results are already for `q` (a search's "Showing results for");
  * otherwise searching `q` finds results that the query didn't ("Did you mean"). `changes` lists each
@@ -97,8 +113,9 @@ export type DidYouMean = {
 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. */
+    /** Only picks matching these filters, as in a search, such as `{ inStock: true }`. Each field's filter
+     * takes the same shapes; `$or` is for searches only. 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[];
@@ -147,7 +164,7 @@ export type ClickDetails = {
     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. */
+ * hidden or closed. They carry no cookie, and no ID unless `visitorIds` is on. */
 export type BrowserEvents = {
     /** A product's page was viewed. A repeat of the last view within 5 seconds is the same page view
      * (React's double mount in development, a re-render), so it isn't sent. */
@@ -163,8 +180,12 @@ export type BrowserEvents = {
         items: EventItem[];
         currency?: string;
     }): void;
-    /** With `events: "afterConsent"`: true sends the events held so far and those after; false drops them. */
+    /** With `events: "afterConsent"`: true sends the events held so far and those after; false drops them,
+     * and with `visitorIds` deletes the IDs from this device. */
     consent(granted: boolean): void;
+    /** With `visitorIds`: deletes this browser's visitor and visit IDs from the device, and asks Findlane
+     * to delete the events sent with them, which it does within a week. Later events get new IDs. */
+    forget(): void;
     /** Sends the events waiting now. */
     flush(): void;
 };
@@ -183,6 +204,11 @@ export type BrowserClientOptions = {
      * `events.proxy`), such as "/findlane/events". Ad blockers block beacons to other sites, not to the
      * page's own. */
     eventsUrl?: string;
+    /** Whether events carry random IDs for this browser and this visit, which link one shopper's views,
+     * carts and orders. The index must take them too (its Events page). Turn it on only if your consent
+     * banner covers analytics, or your shoppers don't need one; with `events: "afterConsent"` the IDs
+     * wait for consent as events do. */
+    visitorIds?: boolean;
 };
 export declare class SearchBrowserClient {
     private readonly url;

package/dist/index.js

@@ -8,22 +8,66 @@ 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) {
+const day = 86_400_000;
+/** The visitor and visit IDs of a public ID, kept on the device: the visitor's in localStorage, made
+ * anew 13 months after it was made (use doesn't extend it); the visit's in sessionStorage, made anew
+ * after 30 minutes without events. Storage that can't be used (a sandboxed frame's) means no IDs. */
+function deviceIds(publicId) {
+    const keys = { visitor: `findlane:visitor:${publicId}`, visit: `findlane:visit:${publicId}` };
+    // 16 random bytes in base64url: letters, digits, - and _, as the API takes IDs.
+    const random = () => btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(16))))
+        .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    const read = (storage, key) => {
+        const value = JSON.parse(storage.getItem(key) ?? "null");
+        return typeof value?.id == "string" && typeof value.at == "number" ? value : null;
+    };
+    return {
+        /** The IDs for a request now, made when there are none or they're old. */
+        use(now = Date.now()) {
+            try {
+                let visitor = read(localStorage, keys.visitor);
+                if (!visitor || now - visitor.at > 395 * day)
+                    localStorage.setItem(keys.visitor, JSON.stringify(visitor = { id: random(), at: now }));
+                const visit = read(sessionStorage, keys.visit);
+                const visitId = visit && now - visit.at <= 30 * 60_000 ? visit.id : random();
+                sessionStorage.setItem(keys.visit, JSON.stringify({ id: visitId, at: now }));
+                return { visitorId: visitor.id, visitId };
+            }
+            catch {
+                return null;
+            }
+        },
+        /** Deletes them from the device, and returns those there were. */
+        clear() {
+            try {
+                const ids = [read(localStorage, keys.visitor)?.id, read(sessionStorage, keys.visit)?.id].filter((id) => !!id);
+                localStorage.removeItem(keys.visitor);
+                sessionStorage.removeItem(keys.visit);
+                return ids;
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+function eventSender(url, fetcher, mode, ids) {
     let queue = [];
     let allowed = mode === "afterConsent" ? undefined : mode;
     let timer;
     let listening = false;
     let lastView = { objectID: "", at: 0 };
+    const send = (body) => {
+        // 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 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);
-        }
+        while (allowed && queue.length)
+            send(JSON.stringify({ ...ids?.use(), events: queue.splice(0, 100) }));
     };
     const add = (event) => {
         if (allowed === false)
@@ -52,8 +96,15 @@ function eventSender(url, fetcher, mode) {
             allowed = granted;
             if (granted)
                 flush();
-            else
+            else {
                 queue = [];
+                ids?.clear();
+            }
+        },
+        forget() {
+            const forgotten = ids?.clear() ?? [];
+            if (forgotten.length)
+                send(JSON.stringify({ forget: forgotten }));
         },
         flush,
     };
@@ -68,7 +119,7 @@ export class SearchBrowserClient {
             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(options.eventsUrl ?? `${this.url}/events`, options.fetch, options.events ?? true);
+        this.events = eventSender(options.eventsUrl ?? `${this.url}/events`, options.fetch, options.events ?? true, options.visitorIds ? deviceIds(options.publicId) : null);
     }
     async post(operation, request, signal) {
         const response = await this.fetcher(`${this.url}/${operation}`, {

package/package.json

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