@findlane/server 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -67,6 +67,7 @@ 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(),
@@ -136,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);
@@ -160,6 +209,18 @@ class SearchServerClient {
         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

@@ -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,58 @@ 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);
@@ -286,6 +347,17 @@ export declare class SearchServerClient {
         /** 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, 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

@@ -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,58 @@ 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);
@@ -286,6 +347,17 @@ export declare class SearchServerClient {
         /** 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, 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,7 @@ 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(),
@@ -90,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);
@@ -114,6 +163,18 @@ class SearchServerClient {
         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.8.0",
+  "version": "0.10.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",