@findlane/browser 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -123,17 +123,57 @@ 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 +191,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/package.json

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