@findlane/server 0.9.0 → 0.11.0

package/README.md

@@ -57,6 +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.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) } : {}
@@ -164,6 +176,24 @@ class SearchServerClient {
         await pause(wait, 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, signal) => {
       const result = { accepted: 0, rejected: [] };
       let batch = [];
@@ -219,7 +249,22 @@ class SearchServerClient {
               ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
             };
         }(), signal),
-        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal)
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal),
+        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

@@ -189,14 +189,23 @@ 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 sent with
+     * `index.events`. Empty without orders. */
+    together?: TogetherHit<T>[];
+    /** What `together`'s counts are of. */
+    togetherBasis?: "orders";
 };
 /** 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
@@ -254,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;
@@ -348,6 +364,15 @@ export declare class SearchServerClient {
             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>;
+            /** 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

@@ -189,14 +189,23 @@ 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 sent with
+     * `index.events`. Empty without orders. */
+    together?: TogetherHit<T>[];
+    /** What `together`'s counts are of. */
+    togetherBasis?: "orders";
 };
 /** 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
@@ -254,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;
@@ -348,6 +364,15 @@ export declare class SearchServerClient {
             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>;
+            /** 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) } : {}
@@ -118,6 +130,24 @@ class SearchServerClient {
         await pause(wait, 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, signal) => {
       const result = { accepted: 0, rejected: [] };
       let batch = [];
@@ -173,7 +203,22 @@ class SearchServerClient {
               ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
             };
         }(), signal),
-        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal)
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal),
+        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.9.0",
+  "version": "0.11.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",