@findlane/server 0.11.0 → 0.12.0

package/README.md

@@ -57,7 +57,8 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 | `getSettings()`, `replaceSettings(settings)`, `waitForSettings()` | Read and change searchable fields, facets, filters, sorts, custom ranking, synonyms, languages, typo tolerance, and text normalization. |
 | `getIndexingStatus()`, `waitUntilIndexed(revision)` | Writes return an accepted revision and are searchable when accepted, so `waitUntilIndexed` returns at once. |
 | `getPublicSearchAccess()`, `setPublicSearchPolicy(policy)`, `usePublicIndexDefaults()` | Restrict what browser search may read and query. |
-| `events.send(events)`, `events.importOrders(orders)`, `events.cancelOrder(orderID)` | Orders and other events for the index's Events page and Bought together; the key needs the `events` or `write` scope. |
+| `events.send(events, { visitorId, visitId }?)`, `events.importOrders(orders)`, `events.cancelOrder(orderID)` | Orders and other events for the index's Events page and Bought together; the key needs the `events` or `write` scope. Your own anonymous visitor IDs link a shopper's events, when the index takes them. |
+| `events.forget(ids)` | Deletes the events sent with these visitor or visit IDs, within a week. |
 | `events.proxy(request)`, `events.relay(body, visitor)` | A route on your own site for the browser SDK's events (its `eventsUrl`), which ad blockers let through. See [Events](https://findlane.dev/docs/events#through-your-own-domain). |
 
 ### Settings

package/dist/index.cjs

@@ -149,7 +149,7 @@ class SearchServerClient {
         }
       }
     };
-    const postEvents = async (events, signal) => {
+    const postEvents = async (payload, signal) => {
       for (let attempt = 0;; attempt++) {
         signal?.throwIfAborted();
         let wait = 250 * 2 ** attempt;
@@ -158,11 +158,11 @@ class SearchServerClient {
             method: "POST",
             signal,
             headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
-            body: JSON.stringify({ events })
+            body: JSON.stringify(payload)
           });
           const data = await response.json().catch(() => ({}));
           if (response.ok)
-            return { accepted: data.accepted ?? 0, rejected: data.rejected ?? [] };
+            return data;
           const error = new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
           if (attempt >= 5 || ![408, 429, 502, 503, 504].includes(response.status))
             throw error;
@@ -194,16 +194,23 @@ class SearchServerClient {
       const retryAfter = response.headers.get("retry-after");
       return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
     };
-    const sendEvents = async (events, signal) => {
+    const sendEvents = async (events, options = {}) => {
+      const { signal, visitorId, visitId } = options;
       const result = { accepted: 0, rejected: [] };
       let batch = [];
       let sent = 0;
       const flush = async () => {
         if (!batch.length)
           return;
-        const answer = await postEvents(batch, signal);
-        result.accepted += answer.accepted;
-        result.rejected.push(...answer.rejected.map((item) => ({ ...item, index: item.index + sent })));
+        const answer = await postEvents({
+          ...visitorId === undefined ? {} : { visitorId },
+          ...visitId === undefined ? {} : { visitId },
+          events: batch
+        }, signal);
+        result.accepted += answer.accepted ?? 0;
+        result.rejected.push(...(answer.rejected ?? []).map((item) => ({ ...item, index: item.index + sent })));
+        if (answer.visitorIds === "off")
+          result.visitorIds = "off";
         sent += batch.length;
         batch = [];
       };
@@ -240,7 +247,7 @@ class SearchServerClient {
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
       events: {
-        send: (events, signal) => sendEvents(events, signal),
+        send: (events, options) => sendEvents(events, options === undefined ? {} : ("aborted" in options) ? { signal: options } : options),
         importOrders: (orders, signal) => sendEvents(async function* () {
           for await (const { timestamp, ...order } of orders)
             yield {
@@ -248,8 +255,14 @@ class SearchServerClient {
               ...order,
               ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
             };
-        }(), signal),
-        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal),
+        }(), { signal }),
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], { signal }),
+        forget: async (ids, signal) => {
+          let forgotten = 0;
+          for (let start = 0;start < ids.length; start += 1000)
+            forgotten += (await postEvents({ forget: ids.slice(start, start + 1000) }, signal)).forgotten ?? 0;
+          return { forgotten };
+        },
         proxy: async (request2, visitor = {}) => {
           if (request2.method !== "POST")
             return jsonResponse(JSON.stringify({ error: "Only POST is allowed" }), 405, { allow: "POST" });

package/dist/index.d.cts

@@ -314,13 +314,23 @@ export type Order = {
     currency?: string;
     timestamp?: number | Date | string;
 };
-/** How many events were accepted, and which were refused and why; `index` counts from the first event sent. */
+/** How many events were accepted, and which were refused and why; `index` counts from the first event
+ * sent. `visitorIds: "off"` when IDs were sent and dropped: the index doesn't take them. */
 export type EventsResult = {
     accepted: number;
     rejected: {
         index: number;
         reason: string;
     }[];
+    visitorIds?: "off";
+};
+/** Options for `events.send`. `visitorId` and `visitId` are your own anonymous IDs for the shopper and
+ * the visit, for all the events sent: 16 to 64 letters, digits, - or _, never an email address, a
+ * phone number or a customer number. They're kept only when the index takes visitor IDs. */
+export type EventOptions = {
+    signal?: AbortSignal;
+    visitorId?: string;
+    visitId?: string;
 };
 export declare class FindlaneError extends Error {
     status: number;
@@ -357,13 +367,19 @@ export declare class SearchServerClient {
         /** Events for the index's Events page and Bought together; the API key needs the `events` or `write`
          * scope. Orders count once each, however often they're sent. */
         events: {
-            /** Sends events, 200 a request. One bad event doesn't refuse the rest: they're in `rejected`. */
-            send: (events: ServerEvent[], signal?: AbortSignal) => Promise<EventsResult>;
+            /** Sends events, 200 a request. One bad event doesn't refuse the rest: they're in `rejected`. Pass
+             * `{ visitorId, visitId }` to link a shopper's events (see EventOptions). */
+            send: (events: ServerEvent[], options?: AbortSignal | EventOptions) => Promise<EventsResult>;
             /** Sends past orders, up to 400 days old, from a list or an async iterable (such as a database
              * cursor), 200 a request. */
             importOrders: (orders: Iterable<Order> | AsyncIterable<Order>, signal?: AbortSignal) => Promise<EventsResult>;
             /** Takes a cancelled or refunded order out of Bought together. */
             cancelOrder: (orderID: string, signal?: AbortSignal) => Promise<EventsResult>;
+            /** Deletes the events sent with these visitor or visit IDs, for shoppers who asked: Findlane does it
+             * within a week. 1,000 IDs a request. */
+            forget: (ids: string[], signal?: AbortSignal) => Promise<{
+                forgotten: number;
+            }>;
             /** A route on your own domain for the browser SDK's events (its `eventsUrl` option): ad blockers
              * block beacons to other sites, not to the page's own. Give it the browser's POST request (Next.js
              * route handlers, Workers, Hono, Bun, Deno); it finds the visitor's address in the headers

package/dist/index.d.ts

@@ -314,13 +314,23 @@ export type Order = {
     currency?: string;
     timestamp?: number | Date | string;
 };
-/** How many events were accepted, and which were refused and why; `index` counts from the first event sent. */
+/** How many events were accepted, and which were refused and why; `index` counts from the first event
+ * sent. `visitorIds: "off"` when IDs were sent and dropped: the index doesn't take them. */
 export type EventsResult = {
     accepted: number;
     rejected: {
         index: number;
         reason: string;
     }[];
+    visitorIds?: "off";
+};
+/** Options for `events.send`. `visitorId` and `visitId` are your own anonymous IDs for the shopper and
+ * the visit, for all the events sent: 16 to 64 letters, digits, - or _, never an email address, a
+ * phone number or a customer number. They're kept only when the index takes visitor IDs. */
+export type EventOptions = {
+    signal?: AbortSignal;
+    visitorId?: string;
+    visitId?: string;
 };
 export declare class FindlaneError extends Error {
     status: number;
@@ -357,13 +367,19 @@ export declare class SearchServerClient {
         /** Events for the index's Events page and Bought together; the API key needs the `events` or `write`
          * scope. Orders count once each, however often they're sent. */
         events: {
-            /** Sends events, 200 a request. One bad event doesn't refuse the rest: they're in `rejected`. */
-            send: (events: ServerEvent[], signal?: AbortSignal) => Promise<EventsResult>;
+            /** Sends events, 200 a request. One bad event doesn't refuse the rest: they're in `rejected`. Pass
+             * `{ visitorId, visitId }` to link a shopper's events (see EventOptions). */
+            send: (events: ServerEvent[], options?: AbortSignal | EventOptions) => Promise<EventsResult>;
             /** Sends past orders, up to 400 days old, from a list or an async iterable (such as a database
              * cursor), 200 a request. */
             importOrders: (orders: Iterable<Order> | AsyncIterable<Order>, signal?: AbortSignal) => Promise<EventsResult>;
             /** Takes a cancelled or refunded order out of Bought together. */
             cancelOrder: (orderID: string, signal?: AbortSignal) => Promise<EventsResult>;
+            /** Deletes the events sent with these visitor or visit IDs, for shoppers who asked: Findlane does it
+             * within a week. 1,000 IDs a request. */
+            forget: (ids: string[], signal?: AbortSignal) => Promise<{
+                forgotten: number;
+            }>;
             /** A route on your own domain for the browser SDK's events (its `eventsUrl` option): ad blockers
              * block beacons to other sites, not to the page's own. Give it the browser's POST request (Next.js
              * route handlers, Workers, Hono, Bun, Deno); it finds the visitor's address in the headers

package/dist/index.js

@@ -103,7 +103,7 @@ class SearchServerClient {
         }
       }
     };
-    const postEvents = async (events, signal) => {
+    const postEvents = async (payload, signal) => {
       for (let attempt = 0;; attempt++) {
         signal?.throwIfAborted();
         let wait = 250 * 2 ** attempt;
@@ -112,11 +112,11 @@ class SearchServerClient {
             method: "POST",
             signal,
             headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
-            body: JSON.stringify({ events })
+            body: JSON.stringify(payload)
           });
           const data = await response.json().catch(() => ({}));
           if (response.ok)
-            return { accepted: data.accepted ?? 0, rejected: data.rejected ?? [] };
+            return data;
           const error = new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
           if (attempt >= 5 || ![408, 429, 502, 503, 504].includes(response.status))
             throw error;
@@ -148,16 +148,23 @@ class SearchServerClient {
       const retryAfter = response.headers.get("retry-after");
       return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
     };
-    const sendEvents = async (events, signal) => {
+    const sendEvents = async (events, options = {}) => {
+      const { signal, visitorId, visitId } = options;
       const result = { accepted: 0, rejected: [] };
       let batch = [];
       let sent = 0;
       const flush = async () => {
         if (!batch.length)
           return;
-        const answer = await postEvents(batch, signal);
-        result.accepted += answer.accepted;
-        result.rejected.push(...answer.rejected.map((item) => ({ ...item, index: item.index + sent })));
+        const answer = await postEvents({
+          ...visitorId === undefined ? {} : { visitorId },
+          ...visitId === undefined ? {} : { visitId },
+          events: batch
+        }, signal);
+        result.accepted += answer.accepted ?? 0;
+        result.rejected.push(...(answer.rejected ?? []).map((item) => ({ ...item, index: item.index + sent })));
+        if (answer.visitorIds === "off")
+          result.visitorIds = "off";
         sent += batch.length;
         batch = [];
       };
@@ -194,7 +201,7 @@ class SearchServerClient {
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
       events: {
-        send: (events, signal) => sendEvents(events, signal),
+        send: (events, options) => sendEvents(events, options === undefined ? {} : ("aborted" in options) ? { signal: options } : options),
         importOrders: (orders, signal) => sendEvents(async function* () {
           for await (const { timestamp, ...order } of orders)
             yield {
@@ -202,8 +209,14 @@ class SearchServerClient {
               ...order,
               ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
             };
-        }(), signal),
-        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal),
+        }(), { signal }),
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], { signal }),
+        forget: async (ids, signal) => {
+          let forgotten = 0;
+          for (let start = 0;start < ids.length; start += 1000)
+            forgotten += (await postEvents({ forget: ids.slice(start, start + 1000) }, signal)).forgotten ?? 0;
+          return { forgotten };
+        },
         proxy: async (request2, visitor = {}) => {
           if (request2.method !== "POST")
             return jsonResponse(JSON.stringify({ error: "Only POST is allowed" }), 405, { allow: "POST" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Findlane server SDK: upload catalogs, manage index settings, and search with a secret workspace API key.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "ecommerce search", "search api", "sdk"],
   "license": "MIT",