@findlane/server 0.11.0 → 0.13.0

package/README.md

@@ -47,7 +47,7 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 
 | Method | What it does |
 | --- | --- |
-| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `options` takes `signal` and `visitor` (below). |
+| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `explain: true` says why each hit matched and what ordered it, and `appliedRules` lists the index's query rules the query fired. `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. |
@@ -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

@@ -12,20 +12,46 @@ export type SortOption = SortRule & {
     thenBy: SortRule[];
 };
 export type IndexSettings = {
-    /** One to five fields, matched with their weight. */
+    /** One to five fields, matched with their weight. `typos: false` matches a field's words exactly or as
+     * prefixes, never with typos, for codes, SKUs, and brands. */
     searchableAttributes: {
         field: string;
         weight: number;
+        typos?: false;
     }[];
     facetFields: string[];
     filterFields?: string[];
     typoTolerance: boolean;
+    /** Words of at least `oneTypo` letters match with one typo, and of at least `twoTypos` with two.
+     * `{ oneTypo: 4, twoTypos: 7 }` by default; oneTypo is 3 to 20, twoTypos from oneTypo to 50. */
+    typoWordLengths?: {
+        oneTypo: number;
+        twoTypos: number;
+    };
+    /** Up to 1,000 single words that never match with typos, though prefixes still do, such as brand names. */
+    exactWords?: string[];
     sorts: SortOption[];
     defaultSort: string;
-    /** Orders equally relevant results (within 10% of the best score) by up to three sort fields. */
+    /** Orders every result by up to two sort fields before relevance, in relevance and named sorts (not
+     * distance), such as `[{ field: "soldOut", direction: "asc" }]` for in stock first. Relevance and
+     * custom ranking order each group. Records without the field come last. */
+    rankFirst?: SortRule[];
+    /** Orders equally relevant results (within `relevanceTolerance` of the best score) by up to three sort fields. */
     customRanking?: SortRule[];
+    /** How close to the best match's score, in percent (1 to 50), results count as equally relevant for
+     * custom ranking, and for distance in searches with a query and `near`. 10 by default. */
+    relevanceTolerance?: number;
     /** Groups of interchangeable words or phrases (up to four words each). */
     synonyms?: string[][];
+    /** A query for an input also matches its 1 to 20 synonyms, but not the other way round. Up to 1,000,
+     * each term up to four words. */
+    oneWaySynonyms?: {
+        input: string;
+        synonyms: string[];
+    }[];
+    /** Up to 1,000 query rules, applied at query time, so a change takes effect at once. Up to 10 fire per
+     * search, in this order, and an earlier rule's filter on a field wins over a later one's. */
+    rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
@@ -39,6 +65,40 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** When a query is, starts with, or contains one of a rule's phrases, the rule's `then` applies to that
+ * search. Phrases are compared as synonyms are: without case, accents, or the index languages' stop words,
+ * and with their plurals and other spellings, so a rule for "balloon" also fires for "balloons". */
+export type QueryRule = {
+    /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
+    id: string;
+    /** Up to 200 characters, for the people reading the settings. */
+    description?: string;
+    /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
+    enabled?: boolean;
+    if: {
+        /** 1 to 20 phrases of one to four words. */
+        phrases: string[];
+        /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
+        match?: "is" | "startsWith" | "contains";
+    };
+    /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
+    then: {
+        /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
+         * Records without the field drop out, so `boost` is usually the better choice. */
+        filters?: SearchRequest["filters"];
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
+         * sorted by relevance. Several rules' boosts add up. */
+        boost?: SearchRequest["filters"];
+        /** Records matching these come after the others, in the same searches as `boost`. */
+        bury?: SearchRequest["filters"];
+        /** Up to 100 objectIDs left out of the results. */
+        hide?: string[];
+        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        replace?: string;
+        /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
+        userData?: unknown;
+    };
+};
 /** A settings change running in the background (with the settings it applies), or the last one's
  * failure. `kind` is "searchable" (new searchable fields filled in) or "rebuild" (a full copy). */
 export type SettingsRebuild = {
@@ -100,7 +160,13 @@ export type SearchRequest = {
     q?: string;
     /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
-    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    /** Field values to keep. Each field takes a value (a list field contains it), or an object of
+     * conditions that all apply: `in` (any of up to 100 values), `all` (a list field has every one),
+     * `not` and `notIn` (records without the field stay in), and `gte`/`lte` for numbers and dates, such
+     * as `{ tags: { in: ["kids", "adult"], notIn: ["party"] }, price: { lte: 50 } }`. `"$or"` takes one to
+     * four groups of field filters and keeps records that match any group:
+     * `{ inStock: true, $or: [{ brand: "Acme" }, { price: { lte: 20 } }] }`. Up to 20 field filters,
+     * counting those in groups. */
     filters?: Record<string, unknown>;
     facets?: string[];
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
@@ -122,6 +188,13 @@ export type SearchRequest = {
         preTag?: string;
         postTag?: string;
     };
+    /** Say why each hit matched and what ordered it, in each hit's `explain`: each query word's best match in
+     * each searchable field, the relevance band, and the ranking fields' values. For understanding and tuning
+     * ranking; browser search doesn't explain results. */
+    explain?: boolean;
+    /** false searches without the index's query rules, such as to compare results with and without them. On by
+     * default; browser search doesn't take it. */
+    enableRules?: boolean;
     /** Nearest first from a point, with each hit's `distance` in meters; `radius` (meters) keeps only what's
      * within it. With a query, the best matches come first and distance orders them. Needs the index's
      * location field. Records without a location are left out. */
@@ -144,6 +217,60 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym, or
+ * as another form of the word in the index's languages (a plural or another spelling). */
+export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form";
+/** A query word's best match in one searchable field. `word` is the matched word (or a synonym's phrase) as
+ * the record writes it. `weight` is what that kind of match weighs in the search: the field's weight times 1
+ * for exact, 0.8 for a synonym or word form, 0.2 for a prefix, and 0.1 for a typo. A typo has `edits`, or
+ * `firstLetter` when the first letter differs (tried only when nothing matched without); a synonym has the
+ * `synonym` that matched. */
+export type FieldMatch = {
+    field: string;
+    word: string;
+    how: MatchKind;
+    weight: number;
+    edits?: number;
+    firstLetter?: true;
+    synonym?: string;
+};
+/** A ranking field and the hit's value for it; null when the record has none (it comes last). */
+export type RankingValue = SortRule & {
+    value: unknown;
+};
+/** Why a hit matched and what ordered it, with `explain`. Scores are for the whole record, so matches carry
+ * weights rather than points that add up to `score`. */
+export type HitExplanation = {
+    /** Each query word (after the languages' stop words, up to eight) with its best match in each searchable
+     * field, strongest first. Every word matches somewhere. Empty without a query. */
+    words: {
+        query: string;
+        matches: FieldMatch[];
+    }[];
+    /** With custom ranking (or `near`) and a query: 0 for results within `relevanceTolerance` of `bestScore`,
+     * 1 for the next band down, and so on. Distance (with `near`), then custom ranking, orders the results
+     * within a band. */
+    band?: number | null;
+    /** The best score in the hit's rank first group, among results as boosted by the search's rules (the whole
+     * search without either). */
+    bestScore?: number | null;
+    /** The index's rank first fields. */
+    rankFirst?: RankingValue[];
+    /** The index's custom ranking fields, when sorting by relevance. */
+    customRanking?: RankingValue[];
+    /** The named sort's fields, when sorting by one. */
+    sort?: RankingValue[];
+    /** When the query's rules boosted or buried results: those whose filters the hit matched, if any. */
+    rules?: {
+        id: string;
+        effect: "boost" | "bury";
+    }[];
+};
+/** A query rule the search fired, with its `userData`, if it has any. */
+export type AppliedRule = {
+    id: string;
+    userData?: unknown;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -153,6 +280,8 @@ export type SearchResponse<T> = {
         distance?: number;
         /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
         highlights?: Record<string, string | string[]>;
+        /** With `explain`: why the hit matched and what ordered it. */
+        explain?: HitExplanation;
     }[];
     total: number;
     /** "gte" when `total` is a lower bound (page count mode). */
@@ -172,12 +301,17 @@ export type SearchResponse<T> = {
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
+    /** The index's query rules the query fired, in the index's order. Left out when none fired. */
+    appliedRules?: AppliedRule[];
+    /** When a rule replaced words: the query that was searched. */
+    rewrittenQuery?: string;
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
-    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`.
+     * Each field's filter takes the same shapes; `$or` is for searches only. */
     filters?: SearchRequest["filters"];
     /** The record fields to return; all of them by default. */
     attributesToRetrieve?: string[];
@@ -314,13 +448,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 +501,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

@@ -12,20 +12,46 @@ export type SortOption = SortRule & {
     thenBy: SortRule[];
 };
 export type IndexSettings = {
-    /** One to five fields, matched with their weight. */
+    /** One to five fields, matched with their weight. `typos: false` matches a field's words exactly or as
+     * prefixes, never with typos, for codes, SKUs, and brands. */
     searchableAttributes: {
         field: string;
         weight: number;
+        typos?: false;
     }[];
     facetFields: string[];
     filterFields?: string[];
     typoTolerance: boolean;
+    /** Words of at least `oneTypo` letters match with one typo, and of at least `twoTypos` with two.
+     * `{ oneTypo: 4, twoTypos: 7 }` by default; oneTypo is 3 to 20, twoTypos from oneTypo to 50. */
+    typoWordLengths?: {
+        oneTypo: number;
+        twoTypos: number;
+    };
+    /** Up to 1,000 single words that never match with typos, though prefixes still do, such as brand names. */
+    exactWords?: string[];
     sorts: SortOption[];
     defaultSort: string;
-    /** Orders equally relevant results (within 10% of the best score) by up to three sort fields. */
+    /** Orders every result by up to two sort fields before relevance, in relevance and named sorts (not
+     * distance), such as `[{ field: "soldOut", direction: "asc" }]` for in stock first. Relevance and
+     * custom ranking order each group. Records without the field come last. */
+    rankFirst?: SortRule[];
+    /** Orders equally relevant results (within `relevanceTolerance` of the best score) by up to three sort fields. */
     customRanking?: SortRule[];
+    /** How close to the best match's score, in percent (1 to 50), results count as equally relevant for
+     * custom ranking, and for distance in searches with a query and `near`. 10 by default. */
+    relevanceTolerance?: number;
     /** Groups of interchangeable words or phrases (up to four words each). */
     synonyms?: string[][];
+    /** A query for an input also matches its 1 to 20 synonyms, but not the other way round. Up to 1,000,
+     * each term up to four words. */
+    oneWaySynonyms?: {
+        input: string;
+        synonyms: string[];
+    }[];
+    /** Up to 1,000 query rules, applied at query time, so a change takes effect at once. Up to 10 fire per
+     * search, in this order, and an earlier rule's filter on a field wins over a later one's. */
+    rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
@@ -39,6 +65,40 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** When a query is, starts with, or contains one of a rule's phrases, the rule's `then` applies to that
+ * search. Phrases are compared as synonyms are: without case, accents, or the index languages' stop words,
+ * and with their plurals and other spellings, so a rule for "balloon" also fires for "balloons". */
+export type QueryRule = {
+    /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
+    id: string;
+    /** Up to 200 characters, for the people reading the settings. */
+    description?: string;
+    /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
+    enabled?: boolean;
+    if: {
+        /** 1 to 20 phrases of one to four words. */
+        phrases: string[];
+        /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
+        match?: "is" | "startsWith" | "contains";
+    };
+    /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
+    then: {
+        /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
+         * Records without the field drop out, so `boost` is usually the better choice. */
+        filters?: SearchRequest["filters"];
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
+         * sorted by relevance. Several rules' boosts add up. */
+        boost?: SearchRequest["filters"];
+        /** Records matching these come after the others, in the same searches as `boost`. */
+        bury?: SearchRequest["filters"];
+        /** Up to 100 objectIDs left out of the results. */
+        hide?: string[];
+        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        replace?: string;
+        /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
+        userData?: unknown;
+    };
+};
 /** A settings change running in the background (with the settings it applies), or the last one's
  * failure. `kind` is "searchable" (new searchable fields filled in) or "rebuild" (a full copy). */
 export type SettingsRebuild = {
@@ -100,7 +160,13 @@ export type SearchRequest = {
     q?: string;
     /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
-    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    /** Field values to keep. Each field takes a value (a list field contains it), or an object of
+     * conditions that all apply: `in` (any of up to 100 values), `all` (a list field has every one),
+     * `not` and `notIn` (records without the field stay in), and `gte`/`lte` for numbers and dates, such
+     * as `{ tags: { in: ["kids", "adult"], notIn: ["party"] }, price: { lte: 50 } }`. `"$or"` takes one to
+     * four groups of field filters and keeps records that match any group:
+     * `{ inStock: true, $or: [{ brand: "Acme" }, { price: { lte: 20 } }] }`. Up to 20 field filters,
+     * counting those in groups. */
     filters?: Record<string, unknown>;
     facets?: string[];
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
@@ -122,6 +188,13 @@ export type SearchRequest = {
         preTag?: string;
         postTag?: string;
     };
+    /** Say why each hit matched and what ordered it, in each hit's `explain`: each query word's best match in
+     * each searchable field, the relevance band, and the ranking fields' values. For understanding and tuning
+     * ranking; browser search doesn't explain results. */
+    explain?: boolean;
+    /** false searches without the index's query rules, such as to compare results with and without them. On by
+     * default; browser search doesn't take it. */
+    enableRules?: boolean;
     /** Nearest first from a point, with each hit's `distance` in meters; `radius` (meters) keeps only what's
      * within it. With a query, the best matches come first and distance orders them. Needs the index's
      * location field. Records without a location are left out. */
@@ -144,6 +217,60 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym, or
+ * as another form of the word in the index's languages (a plural or another spelling). */
+export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form";
+/** A query word's best match in one searchable field. `word` is the matched word (or a synonym's phrase) as
+ * the record writes it. `weight` is what that kind of match weighs in the search: the field's weight times 1
+ * for exact, 0.8 for a synonym or word form, 0.2 for a prefix, and 0.1 for a typo. A typo has `edits`, or
+ * `firstLetter` when the first letter differs (tried only when nothing matched without); a synonym has the
+ * `synonym` that matched. */
+export type FieldMatch = {
+    field: string;
+    word: string;
+    how: MatchKind;
+    weight: number;
+    edits?: number;
+    firstLetter?: true;
+    synonym?: string;
+};
+/** A ranking field and the hit's value for it; null when the record has none (it comes last). */
+export type RankingValue = SortRule & {
+    value: unknown;
+};
+/** Why a hit matched and what ordered it, with `explain`. Scores are for the whole record, so matches carry
+ * weights rather than points that add up to `score`. */
+export type HitExplanation = {
+    /** Each query word (after the languages' stop words, up to eight) with its best match in each searchable
+     * field, strongest first. Every word matches somewhere. Empty without a query. */
+    words: {
+        query: string;
+        matches: FieldMatch[];
+    }[];
+    /** With custom ranking (or `near`) and a query: 0 for results within `relevanceTolerance` of `bestScore`,
+     * 1 for the next band down, and so on. Distance (with `near`), then custom ranking, orders the results
+     * within a band. */
+    band?: number | null;
+    /** The best score in the hit's rank first group, among results as boosted by the search's rules (the whole
+     * search without either). */
+    bestScore?: number | null;
+    /** The index's rank first fields. */
+    rankFirst?: RankingValue[];
+    /** The index's custom ranking fields, when sorting by relevance. */
+    customRanking?: RankingValue[];
+    /** The named sort's fields, when sorting by one. */
+    sort?: RankingValue[];
+    /** When the query's rules boosted or buried results: those whose filters the hit matched, if any. */
+    rules?: {
+        id: string;
+        effect: "boost" | "bury";
+    }[];
+};
+/** A query rule the search fired, with its `userData`, if it has any. */
+export type AppliedRule = {
+    id: string;
+    userData?: unknown;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -153,6 +280,8 @@ export type SearchResponse<T> = {
         distance?: number;
         /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
         highlights?: Record<string, string | string[]>;
+        /** With `explain`: why the hit matched and what ordered it. */
+        explain?: HitExplanation;
     }[];
     total: number;
     /** "gte" when `total` is a lower bound (page count mode). */
@@ -172,12 +301,17 @@ export type SearchResponse<T> = {
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
+    /** The index's query rules the query fired, in the index's order. Left out when none fired. */
+    appliedRules?: AppliedRule[];
+    /** When a rule replaced words: the query that was searched. */
+    rewrittenQuery?: string;
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
-    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`.
+     * Each field's filter takes the same shapes; `$or` is for searches only. */
     filters?: SearchRequest["filters"];
     /** The record fields to return; all of them by default. */
     attributesToRetrieve?: string[];
@@ -314,13 +448,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 +501,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.13.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",