@findlane/server 0.7.0 → 0.9.0

package/README.md

@@ -31,13 +31,23 @@ The workspace ID is under Settings in the dashboard, and keys are under API keys
 - `search`: `search()`.
 - `write`: record writes, settings, public search restrictions, and indexing status.
 
+## Searching for a visitor
+
+When your server searches for someone, such as a shopper loading a server-rendered search page, pass the visitor. The index's limits and bot rules then apply to them as they do to browser search, and searches from verified crawlers like Googlebot are free:
+
+```ts
+const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent: req.get("user-agent") } })
+```
+
+`suggest()` and `recommendations()` take the same option. Without it, a search counts as your server's own.
+
 ## An index's methods
 
 `client.index<T>(name)` returns these; `T` types your records, which each need a string `objectID`.
 
 | Method | What it does |
 | --- | --- |
-| `search(request)` | Search with a query, filters, facets, a sort, paging, and highlighting. |
+| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `options` takes `signal` and `visitor` (below). |
 | `upsert(records)` | Add or update up to 1,000 records by `objectID`. |
 | `replaceAll(records)` | Replace the whole catalog in one request (up to 100,000 records). |
 | `replaceAllStaged(records, options)` | Replace a larger catalog in batches under one stage ID, switched in one commit. Retrying with the same `stageId` resumes. `abortReplacement(stageId)` drops a stage. |

package/dist/index.cjs

@@ -67,6 +67,12 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+var eventsPerRequest = 200;
+var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+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) } : {}
+} : {};
 
 class FindlaneError extends Error {
   status;
@@ -93,12 +99,13 @@ class SearchServerClient {
   }
   index(name) {
     const path = `/api/teams/${encodeURIComponent(this.workspaceId)}/indexes/${encodeURIComponent(name)}`;
-    const request = async (suffix, method = "GET", payload, signal) => {
+    const request = async (suffix, method = "GET", payload, signal, extra = {}) => {
       const response = await this.fetcher(this.baseUrl + path + suffix, {
         method,
         headers: {
           authorization: `Bearer ${this.key}`,
-          ...payload === undefined ? {} : { "content-type": "application/json" }
+          ...payload === undefined ? {} : { "content-type": "application/json" },
+          ...extra
         },
         body: payload === undefined ? undefined : JSON.stringify(payload),
         signal
@@ -130,6 +137,54 @@ class SearchServerClient {
         }
       }
     };
+    const postEvents = async (events, signal) => {
+      for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
+        let wait = 250 * 2 ** attempt;
+        try {
+          const response = await this.fetcher(this.baseUrl + path + "/events", {
+            method: "POST",
+            signal,
+            headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
+            body: JSON.stringify({ events })
+          });
+          const data = await response.json().catch(() => ({}));
+          if (response.ok)
+            return { accepted: data.accepted ?? 0, rejected: data.rejected ?? [] };
+          const error = new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+          if (attempt >= 5 || ![408, 429, 502, 503, 504].includes(response.status))
+            throw error;
+          const after = Number(response.headers.get("retry-after"));
+          if (after > 0)
+            wait = Math.min(after * 1000, 60000);
+        } catch (error) {
+          if (error instanceof FindlaneError || attempt >= 5 || signal?.aborted)
+            throw error;
+        }
+        await pause(wait, signal);
+      }
+    };
+    const sendEvents = async (events, signal) => {
+      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 })));
+        sent += batch.length;
+        batch = [];
+      };
+      for await (const event of events) {
+        batch.push(event);
+        if (batch.length >= eventsPerRequest)
+          await flush();
+      }
+      await flush();
+      return result;
+    };
     const stagePath = (stageId) => `/staged-replacements/${encodeURIComponent(stageId)}`;
     const beginReplacement = (stageId, signal) => retry(() => request(stagePath(stageId), "POST", undefined, signal), signal);
     const uploadReplacementBatch = (stageId, batchId, records, signal) => retry(() => request(`${stagePath(stageId)}/batches/${encodeURIComponent(batchId)}`, "POST", { records }, signal), signal);
@@ -142,9 +197,30 @@ class SearchServerClient {
       return retry(() => request("/record-writes", "POST", payload, options.signal), options.signal);
     };
     return {
-      search: (query = {}, signal) => request("/search", "POST", query, signal),
-      suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
-      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
+      search: (query = {}, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return request("/search", "POST", query, signal, visitorHeaders(visitor));
+      },
+      suggest: async (query, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
+      },
+      recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
+        const { signal, visitor } = requestOptions(requestOptionsOrSignal);
+        return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
+      },
+      events: {
+        send: (events, signal) => sendEvents(events, signal),
+        importOrders: (orders, signal) => sendEvents(async function* () {
+          for await (const { timestamp, ...order } of orders)
+            yield {
+              type: "purchase",
+              ...order,
+              ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
+            };
+        }(), signal),
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal)
+      },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),

package/dist/index.d.cts

@@ -240,6 +240,72 @@ export declare class StagedReplacementError extends Error {
     stageId: string;
     constructor(stageId: string, cause: unknown);
 }
+/** The visitor a server searches for, such as a shopper loading a server-rendered search page. With it,
+ * the index's limits and bot rules apply to that visitor, as they do to browser search, and searches
+ * from verified crawlers like Googlebot are free. */
+export type Visitor = {
+    /** The visitor's IP address: on Express `req.ip`, on Next.js the first address in `x-forwarded-for`. */
+    ip: string;
+    /** The visitor's User-Agent header. */
+    userAgent?: string;
+};
+/** Options for a search, a suggestion, or recommendations. */
+export type RequestOptions = {
+    signal?: AbortSignal;
+    visitor?: Visitor;
+};
+/** A product in a cart or an order. */
+export type EventItem = {
+    objectID: string;
+    quantity?: number;
+    price?: number;
+};
+/** An event from a server; the API key needs the `events` or `write` scope. `timestamp` (ms since 1970)
+ * may be up to 400 days back, for history. Events don't name the shopper. */
+export type ServerEvent = {
+    type: "view";
+    objectID: string;
+    timestamp?: number;
+} | {
+    type: "click";
+    objectID: string;
+    position?: number;
+    query?: string;
+    list?: "goesWith" | "similar" | "together";
+    from?: string;
+    timestamp?: number;
+} | {
+    type: "addToCart";
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number;
+} | {
+    type: "purchase";
+    orderID: string;
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number;
+}
+/** Takes a cancelled or refunded order out of Bought together. */
+ | {
+    type: "cancel";
+    orderID: string;
+};
+/** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
+export type Order = {
+    orderID: string;
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number | Date | string;
+};
+/** How many events were accepted, and which were refused and why; `index` counts from the first event sent. */
+export type EventsResult = {
+    accepted: number;
+    rejected: {
+        index: number;
+        reason: string;
+    }[];
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -262,15 +328,27 @@ export declare class SearchServerClient {
     index<T extends {
         objectID: string;
     } = JsonRecord>(name: string): {
-        /** Searches the index; the API key needs the `search` scope. */
-        search: <R = T>(query?: SearchRequest, signal?: AbortSignal) => Promise<SearchResponse<R>>;
+        /** Searches the index; the API key needs the `search` scope. Pass `{ visitor }` when searching for
+         * someone, such as a shopper loading a server-rendered page (see Visitor). */
+        search: <R = T>(query?: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<SearchResponse<R>>;
         /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
-        suggest: (query: SearchRequest, signal?: AbortSignal) => Promise<DidYouMean | null>;
+        suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<DidYouMean | null>;
         /** A product's recommendations (the recommendations add-on): products that go with it, and similar products.
          * The API key needs the `search` scope; not counted as a search. */
-        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
+        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, requestOptionsOrSignal?: AbortSignal | RequestOptions) => Promise<RecommendationsResponse<R>>;
+        /** 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 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>;
+        };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;

package/dist/index.d.ts

@@ -240,6 +240,72 @@ export declare class StagedReplacementError extends Error {
     stageId: string;
     constructor(stageId: string, cause: unknown);
 }
+/** The visitor a server searches for, such as a shopper loading a server-rendered search page. With it,
+ * the index's limits and bot rules apply to that visitor, as they do to browser search, and searches
+ * from verified crawlers like Googlebot are free. */
+export type Visitor = {
+    /** The visitor's IP address: on Express `req.ip`, on Next.js the first address in `x-forwarded-for`. */
+    ip: string;
+    /** The visitor's User-Agent header. */
+    userAgent?: string;
+};
+/** Options for a search, a suggestion, or recommendations. */
+export type RequestOptions = {
+    signal?: AbortSignal;
+    visitor?: Visitor;
+};
+/** A product in a cart or an order. */
+export type EventItem = {
+    objectID: string;
+    quantity?: number;
+    price?: number;
+};
+/** An event from a server; the API key needs the `events` or `write` scope. `timestamp` (ms since 1970)
+ * may be up to 400 days back, for history. Events don't name the shopper. */
+export type ServerEvent = {
+    type: "view";
+    objectID: string;
+    timestamp?: number;
+} | {
+    type: "click";
+    objectID: string;
+    position?: number;
+    query?: string;
+    list?: "goesWith" | "similar" | "together";
+    from?: string;
+    timestamp?: number;
+} | {
+    type: "addToCart";
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number;
+} | {
+    type: "purchase";
+    orderID: string;
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number;
+}
+/** Takes a cancelled or refunded order out of Bought together. */
+ | {
+    type: "cancel";
+    orderID: string;
+};
+/** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
+export type Order = {
+    orderID: string;
+    items: EventItem[];
+    currency?: string;
+    timestamp?: number | Date | string;
+};
+/** How many events were accepted, and which were refused and why; `index` counts from the first event sent. */
+export type EventsResult = {
+    accepted: number;
+    rejected: {
+        index: number;
+        reason: string;
+    }[];
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -262,15 +328,27 @@ export declare class SearchServerClient {
     index<T extends {
         objectID: string;
     } = JsonRecord>(name: string): {
-        /** Searches the index; the API key needs the `search` scope. */
-        search: <R = T>(query?: SearchRequest, signal?: AbortSignal) => Promise<SearchResponse<R>>;
+        /** Searches the index; the API key needs the `search` scope. Pass `{ visitor }` when searching for
+         * someone, such as a shopper loading a server-rendered page (see Visitor). */
+        search: <R = T>(query?: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<SearchResponse<R>>;
         /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
-        suggest: (query: SearchRequest, signal?: AbortSignal) => Promise<DidYouMean | null>;
+        suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<DidYouMean | null>;
         /** A product's recommendations (the recommendations add-on): products that go with it, and similar products.
          * The API key needs the `search` scope; not counted as a search. */
-        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
+        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, requestOptionsOrSignal?: AbortSignal | RequestOptions) => Promise<RecommendationsResponse<R>>;
+        /** 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 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>;
+        };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;

package/dist/index.js

@@ -21,6 +21,12 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+var eventsPerRequest = 200;
+var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+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) } : {}
+} : {};
 
 class FindlaneError extends Error {
   status;
@@ -47,12 +53,13 @@ class SearchServerClient {
   }
   index(name) {
     const path = `/api/teams/${encodeURIComponent(this.workspaceId)}/indexes/${encodeURIComponent(name)}`;
-    const request = async (suffix, method = "GET", payload, signal) => {
+    const request = async (suffix, method = "GET", payload, signal, extra = {}) => {
       const response = await this.fetcher(this.baseUrl + path + suffix, {
         method,
         headers: {
           authorization: `Bearer ${this.key}`,
-          ...payload === undefined ? {} : { "content-type": "application/json" }
+          ...payload === undefined ? {} : { "content-type": "application/json" },
+          ...extra
         },
         body: payload === undefined ? undefined : JSON.stringify(payload),
         signal
@@ -84,6 +91,54 @@ class SearchServerClient {
         }
       }
     };
+    const postEvents = async (events, signal) => {
+      for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
+        let wait = 250 * 2 ** attempt;
+        try {
+          const response = await this.fetcher(this.baseUrl + path + "/events", {
+            method: "POST",
+            signal,
+            headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
+            body: JSON.stringify({ events })
+          });
+          const data = await response.json().catch(() => ({}));
+          if (response.ok)
+            return { accepted: data.accepted ?? 0, rejected: data.rejected ?? [] };
+          const error = new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+          if (attempt >= 5 || ![408, 429, 502, 503, 504].includes(response.status))
+            throw error;
+          const after = Number(response.headers.get("retry-after"));
+          if (after > 0)
+            wait = Math.min(after * 1000, 60000);
+        } catch (error) {
+          if (error instanceof FindlaneError || attempt >= 5 || signal?.aborted)
+            throw error;
+        }
+        await pause(wait, signal);
+      }
+    };
+    const sendEvents = async (events, signal) => {
+      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 })));
+        sent += batch.length;
+        batch = [];
+      };
+      for await (const event of events) {
+        batch.push(event);
+        if (batch.length >= eventsPerRequest)
+          await flush();
+      }
+      await flush();
+      return result;
+    };
     const stagePath = (stageId) => `/staged-replacements/${encodeURIComponent(stageId)}`;
     const beginReplacement = (stageId, signal) => retry(() => request(stagePath(stageId), "POST", undefined, signal), signal);
     const uploadReplacementBatch = (stageId, batchId, records, signal) => retry(() => request(`${stagePath(stageId)}/batches/${encodeURIComponent(batchId)}`, "POST", { records }, signal), signal);
@@ -96,9 +151,30 @@ class SearchServerClient {
       return retry(() => request("/record-writes", "POST", payload, options.signal), options.signal);
     };
     return {
-      search: (query = {}, signal) => request("/search", "POST", query, signal),
-      suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
-      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
+      search: (query = {}, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return request("/search", "POST", query, signal, visitorHeaders(visitor));
+      },
+      suggest: async (query, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
+      },
+      recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
+        const { signal, visitor } = requestOptions(requestOptionsOrSignal);
+        return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
+      },
+      events: {
+        send: (events, signal) => sendEvents(events, signal),
+        importOrders: (orders, signal) => sendEvents(async function* () {
+          for await (const { timestamp, ...order } of orders)
+            yield {
+              type: "purchase",
+              ...order,
+              ...timestamp === undefined ? {} : { timestamp: typeof timestamp === "number" ? timestamp : new Date(timestamp).getTime() }
+            };
+        }(), signal),
+        cancelOrder: (orderID, signal) => sendEvents([{ type: "cancel", orderID }], signal)
+      },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),

package/package.json

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