@findlane/server 0.10.0 → 0.12.0

package/README.md

@@ -57,6 +57,9 @@ 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, { 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

@@ -69,6 +69,18 @@ class StagedReplacementError extends Error {
 }
 var eventsPerRequest = 200;
 var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+var relayedBytes = 256 * 1024;
+function requestVisitor(request) {
+  const headers = request.headers;
+  const cf = request.cf;
+  return {
+    ip: headers.get("cf-connecting-ip") ?? headers.get("x-real-ip") ?? headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
+    userAgent: headers.get("user-agent") ?? undefined,
+    origin: headers.get("origin") ?? new URL(request.url).origin,
+    country: (typeof cf?.country == "string" ? cf.country : null) ?? headers.get("cf-ipcountry") ?? headers.get("x-vercel-ip-country") ?? undefined
+  };
+}
+var jsonResponse = (body, status, headers = {}) => new Response(body, { status, headers: { "content-type": "application/json", "cache-control": "no-store", ...headers } });
 var visitorHeaders = (visitor) => visitor?.ip ? {
   "findlane-visitor-ip": visitor.ip.trim(),
   ...visitor.userAgent ? { "findlane-visitor-agent": visitor.userAgent.replace(/[^\x20-\x7e]/g, "").slice(0, 512) } : {}
@@ -137,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;
@@ -146,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;
@@ -164,16 +176,41 @@ class SearchServerClient {
         await pause(wait, signal);
       }
     };
-    const sendEvents = async (events, signal) => {
+    const relayEvents = async (body, visitor, signal) => {
+      if (!visitor.ip?.trim())
+        throw new Error("Relaying events needs the visitor's IP address");
+      const response = await this.fetcher(this.baseUrl + path + "/events", {
+        method: "POST",
+        signal,
+        body,
+        headers: {
+          authorization: `Bearer ${this.key}`,
+          "content-type": "application/json",
+          ...visitorHeaders(visitor),
+          ...visitor.origin ? { "findlane-visitor-origin": visitor.origin } : {},
+          ...visitor.country ? { "findlane-visitor-country": visitor.country } : {}
+        }
+      });
+      const retryAfter = response.headers.get("retry-after");
+      return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
+    };
+    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 = [];
       };
@@ -210,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 {
@@ -218,8 +255,29 @@ 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" });
+          const tooLarge = () => jsonResponse(JSON.stringify({ error: "The request is too large" }), 413);
+          if (Number(request2.headers.get("content-length") ?? 0) > relayedBytes)
+            return tooLarge();
+          const body = await request2.text();
+          if (new TextEncoder().encode(body).length > relayedBytes)
+            return tooLarge();
+          const found = { ...requestVisitor(request2), ...visitor };
+          if (!found.ip)
+            throw new Error("No visitor IP address in the request's headers; pass it: events.proxy(request, { ip })");
+          return relayEvents(body, { ...found, ip: found.ip });
+        },
+        relay: (body, visitor, signal) => relayEvents(body, visitor, signal)
       },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),

package/dist/index.d.cts

@@ -263,6 +263,13 @@ export type RequestOptions = {
     signal?: AbortSignal;
     visitor?: Visitor;
 };
+/** A visitor whose events a server relays from its own domain (`events.relay`). */
+export type RelayedVisitor = Visitor & {
+    /** The page's origin, such as `https://shop.example`: the site the Events page shows. */
+    origin?: string;
+    /** The visitor's country as two letters, such as `IS`, when the host knows it. */
+    country?: string;
+};
 /** A product in a cart or an order. */
 export type EventItem = {
     objectID: string;
@@ -307,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;
@@ -350,13 +367,28 @@ 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
+             * Cloudflare, Vercel and most proxies set. Where a visitor reaches your server directly, they can
+             * set those too, so pass `{ ip }`. The API key needs the `events` or `write` scope. */
+            proxy: (request: Request, visitor?: Partial<RelayedVisitor>) => Promise<Response>;
+            /** `proxy` for servers without Fetch API requests, such as Express: the request's body as text,
+             * and its visitor. Answers with the API's response. */
+            relay: (body: string, visitor: RelayedVisitor, signal?: AbortSignal) => Promise<Response>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.d.ts

@@ -263,6 +263,13 @@ export type RequestOptions = {
     signal?: AbortSignal;
     visitor?: Visitor;
 };
+/** A visitor whose events a server relays from its own domain (`events.relay`). */
+export type RelayedVisitor = Visitor & {
+    /** The page's origin, such as `https://shop.example`: the site the Events page shows. */
+    origin?: string;
+    /** The visitor's country as two letters, such as `IS`, when the host knows it. */
+    country?: string;
+};
 /** A product in a cart or an order. */
 export type EventItem = {
     objectID: string;
@@ -307,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;
@@ -350,13 +367,28 @@ 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
+             * Cloudflare, Vercel and most proxies set. Where a visitor reaches your server directly, they can
+             * set those too, so pass `{ ip }`. The API key needs the `events` or `write` scope. */
+            proxy: (request: Request, visitor?: Partial<RelayedVisitor>) => Promise<Response>;
+            /** `proxy` for servers without Fetch API requests, such as Express: the request's body as text,
+             * and its visitor. Answers with the API's response. */
+            relay: (body: string, visitor: RelayedVisitor, signal?: AbortSignal) => Promise<Response>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.js

@@ -23,6 +23,18 @@ class StagedReplacementError extends Error {
 }
 var eventsPerRequest = 200;
 var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+var relayedBytes = 256 * 1024;
+function requestVisitor(request) {
+  const headers = request.headers;
+  const cf = request.cf;
+  return {
+    ip: headers.get("cf-connecting-ip") ?? headers.get("x-real-ip") ?? headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
+    userAgent: headers.get("user-agent") ?? undefined,
+    origin: headers.get("origin") ?? new URL(request.url).origin,
+    country: (typeof cf?.country == "string" ? cf.country : null) ?? headers.get("cf-ipcountry") ?? headers.get("x-vercel-ip-country") ?? undefined
+  };
+}
+var jsonResponse = (body, status, headers = {}) => new Response(body, { status, headers: { "content-type": "application/json", "cache-control": "no-store", ...headers } });
 var visitorHeaders = (visitor) => visitor?.ip ? {
   "findlane-visitor-ip": visitor.ip.trim(),
   ...visitor.userAgent ? { "findlane-visitor-agent": visitor.userAgent.replace(/[^\x20-\x7e]/g, "").slice(0, 512) } : {}
@@ -91,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;
@@ -100,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;
@@ -118,16 +130,41 @@ class SearchServerClient {
         await pause(wait, signal);
       }
     };
-    const sendEvents = async (events, signal) => {
+    const relayEvents = async (body, visitor, signal) => {
+      if (!visitor.ip?.trim())
+        throw new Error("Relaying events needs the visitor's IP address");
+      const response = await this.fetcher(this.baseUrl + path + "/events", {
+        method: "POST",
+        signal,
+        body,
+        headers: {
+          authorization: `Bearer ${this.key}`,
+          "content-type": "application/json",
+          ...visitorHeaders(visitor),
+          ...visitor.origin ? { "findlane-visitor-origin": visitor.origin } : {},
+          ...visitor.country ? { "findlane-visitor-country": visitor.country } : {}
+        }
+      });
+      const retryAfter = response.headers.get("retry-after");
+      return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
+    };
+    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 = [];
       };
@@ -164,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 {
@@ -172,8 +209,29 @@ 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" });
+          const tooLarge = () => jsonResponse(JSON.stringify({ error: "The request is too large" }), 413);
+          if (Number(request2.headers.get("content-length") ?? 0) > relayedBytes)
+            return tooLarge();
+          const body = await request2.text();
+          if (new TextEncoder().encode(body).length > relayedBytes)
+            return tooLarge();
+          const found = { ...requestVisitor(request2), ...visitor };
+          if (!found.ip)
+            throw new Error("No visitor IP address in the request's headers; pass it: events.proxy(request, { ip })");
+          return relayEvents(body, { ...found, ip: found.ip });
+        },
+        relay: (body, visitor, signal) => relayEvents(body, visitor, signal)
       },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),

package/package.json

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