@findlane/server 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -232,7 +232,7 @@ class SearchServerClient {
       await flush();
       return result;
     };
-    const report = (name2, options) => retry(() => request(`/analytics/${name2}${analyticsQuery(options)}`, "GET", undefined, options.signal), options.signal);
+    const report = (name, options) => retry(() => request(`/analytics/${name}${analyticsQuery(options)}`, "GET", undefined, options.signal), options.signal);
     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);
@@ -295,16 +295,16 @@ class SearchServerClient {
             forgotten += (await postEvents({ forget: ids.slice(start, start + 1000) }, signal)).forgotten ?? 0;
           return { forgotten };
         },
-        proxy: async (request2, visitor = {}) => {
-          if (request2.method !== "POST")
+        proxy: async (request, visitor = {}) => {
+          if (request.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)
+          if (Number(request.headers.get("content-length") ?? 0) > relayedBytes)
             return tooLarge();
-          const body = await request2.text();
+          const body = await request.text();
           if (new TextEncoder().encode(body).length > relayedBytes)
             return tooLarge();
-          const found = { ...requestVisitor(request2), ...visitor };
+          const found = { ...requestVisitor(request), ...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 });

package/dist/index.d.cts

@@ -66,9 +66,29 @@ export type IndexSettings = {
     /** Query suggestions: whole searches offered as shoppers type, and popular searches for an empty box,
      * from what shoppers search and the catalog. On by default. Changes apply within a few minutes. */
     querySuggestions?: QuerySuggestionSettings;
+    /** Related results (0.18.0): when a search's words find nothing, the products closest to it in meaning, in
+     * the response's `related`. Paid plans, indexes of up to 200,000 records. Turned on, every record is
+     * embedded within minutes, and `minScore`, the floor, is calibrated from the index's own searches that
+     * found nothing; none show until it is. Off by default. */
+    relatedResults?: {
+        enabled?: boolean;
+        minScore?: number | null;
+    };
     normalizationProfile?: "default-v2" | "default-v1" | "icelandic-ascii-v1";
     /** An object field of lat and lng numbers, such as `_geoloc`, that `near` and `within` search; null for none. */
     locationField?: string | null;
+    /** Shows each value of a field once, such as a product whose colours or sizes are records sharing its ID:
+     * the record (or up to `limit`, 1 to 4) that best matches the search. A text or number field with one value;
+     * `total` then counts groups. Null for none. */
+    distinct?: {
+        field: string;
+        limit?: number;
+    } | null;
+    /** Variants listed inside each record, such as a product's flavours: a list of objects at `field`. Each hit
+     * then says which one the search matched (`variant`). Null for none. */
+    variants?: {
+        field: string;
+    } | null;
     /** When saving: types for fields no record has yet, so settings can come before the records. Records'
      * types win once they have the field. Not returned when reading settings. */
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
@@ -335,6 +355,11 @@ export type SearchRequest = {
     /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
      * antimeridian. */
     within?: GeoBox;
+    /** With the index's `relatedResults` on: false asks for no related results (0.18.0). */
+    related?: boolean;
+    /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
+     * records. */
+    distinct?: boolean | number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -415,8 +440,23 @@ export type SearchResponse<T> = {
         highlights?: Record<string, string | string[]>;
         /** With `explain`: why the hit matched and what ordered it. */
         explain?: HitExplanation;
+        /** With the index's `distinct` setting: the hit's group (its value of the group field, null for a record
+         * without one) and how many of the group's records matched. */
+        group?: {
+            value: string | number | null;
+            matched: number;
+        };
+        /** With the index's `variants` setting: which item of the record's variants list the search matched, by
+         * its words or by filters on the variants' fields, such as the flavour a shopper typed. Absent when none
+         * stands out. */
+        variant?: {
+            index: number;
+        };
     }[];
+    /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
+    /** With `distinct`: the matching records, which `total` counts as groups. */
+    totalRecords?: number;
     /** "gte" when `total` is a lower bound (page count mode). */
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
@@ -441,6 +481,17 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** With the index's `relatedResults` on (0.18.0): when the query's words found nothing (`hits` empty,
+     * `total` 0), the products closest to it in meaning, best first, with their similarity as `score`. Show
+     * them under a heading of their own, such as "No exact matches. Related products". */
+    related?: {
+        hits: Array<{
+            id: string;
+            score: number | null;
+            record: T;
+        }>;
+        total: number;
+    };
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 /** One of an index's lists (docs: Lists): a row of products, such as Popular or New arrivals, from a filter and
@@ -626,7 +677,7 @@ export type ServerEvent = {
     objectID: string;
     position?: number;
     query?: string;
-    list?: "goesWith" | "similar" | "together";
+    list?: "goesWith" | "similar" | "together" | "related";
     from?: string;
     timestamp?: number;
 } | {

package/dist/index.d.ts

@@ -66,9 +66,29 @@ export type IndexSettings = {
     /** Query suggestions: whole searches offered as shoppers type, and popular searches for an empty box,
      * from what shoppers search and the catalog. On by default. Changes apply within a few minutes. */
     querySuggestions?: QuerySuggestionSettings;
+    /** Related results (0.18.0): when a search's words find nothing, the products closest to it in meaning, in
+     * the response's `related`. Paid plans, indexes of up to 200,000 records. Turned on, every record is
+     * embedded within minutes, and `minScore`, the floor, is calibrated from the index's own searches that
+     * found nothing; none show until it is. Off by default. */
+    relatedResults?: {
+        enabled?: boolean;
+        minScore?: number | null;
+    };
     normalizationProfile?: "default-v2" | "default-v1" | "icelandic-ascii-v1";
     /** An object field of lat and lng numbers, such as `_geoloc`, that `near` and `within` search; null for none. */
     locationField?: string | null;
+    /** Shows each value of a field once, such as a product whose colours or sizes are records sharing its ID:
+     * the record (or up to `limit`, 1 to 4) that best matches the search. A text or number field with one value;
+     * `total` then counts groups. Null for none. */
+    distinct?: {
+        field: string;
+        limit?: number;
+    } | null;
+    /** Variants listed inside each record, such as a product's flavours: a list of objects at `field`. Each hit
+     * then says which one the search matched (`variant`). Null for none. */
+    variants?: {
+        field: string;
+    } | null;
     /** When saving: types for fields no record has yet, so settings can come before the records. Records'
      * types win once they have the field. Not returned when reading settings. */
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
@@ -335,6 +355,11 @@ export type SearchRequest = {
     /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
      * antimeridian. */
     within?: GeoBox;
+    /** With the index's `relatedResults` on: false asks for no related results (0.18.0). */
+    related?: boolean;
+    /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
+     * records. */
+    distinct?: boolean | number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -415,8 +440,23 @@ export type SearchResponse<T> = {
         highlights?: Record<string, string | string[]>;
         /** With `explain`: why the hit matched and what ordered it. */
         explain?: HitExplanation;
+        /** With the index's `distinct` setting: the hit's group (its value of the group field, null for a record
+         * without one) and how many of the group's records matched. */
+        group?: {
+            value: string | number | null;
+            matched: number;
+        };
+        /** With the index's `variants` setting: which item of the record's variants list the search matched, by
+         * its words or by filters on the variants' fields, such as the flavour a shopper typed. Absent when none
+         * stands out. */
+        variant?: {
+            index: number;
+        };
     }[];
+    /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
+    /** With `distinct`: the matching records, which `total` counts as groups. */
+    totalRecords?: number;
     /** "gte" when `total` is a lower bound (page count mode). */
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
@@ -441,6 +481,17 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** With the index's `relatedResults` on (0.18.0): when the query's words found nothing (`hits` empty,
+     * `total` 0), the products closest to it in meaning, best first, with their similarity as `score`. Show
+     * them under a heading of their own, such as "No exact matches. Related products". */
+    related?: {
+        hits: Array<{
+            id: string;
+            score: number | null;
+            record: T;
+        }>;
+        total: number;
+    };
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 /** One of an index's lists (docs: Lists): a row of products, such as Popular or New arrivals, from a filter and
@@ -626,7 +677,7 @@ export type ServerEvent = {
     objectID: string;
     position?: number;
     query?: string;
-    list?: "goesWith" | "similar" | "together";
+    list?: "goesWith" | "similar" | "together" | "related";
     from?: string;
     timestamp?: number;
 } | {

package/dist/index.js

@@ -186,7 +186,7 @@ class SearchServerClient {
       await flush();
       return result;
     };
-    const report = (name2, options) => retry(() => request(`/analytics/${name2}${analyticsQuery(options)}`, "GET", undefined, options.signal), options.signal);
+    const report = (name, options) => retry(() => request(`/analytics/${name}${analyticsQuery(options)}`, "GET", undefined, options.signal), options.signal);
     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);
@@ -249,16 +249,16 @@ class SearchServerClient {
             forgotten += (await postEvents({ forget: ids.slice(start, start + 1000) }, signal)).forgotten ?? 0;
           return { forgotten };
         },
-        proxy: async (request2, visitor = {}) => {
-          if (request2.method !== "POST")
+        proxy: async (request, visitor = {}) => {
+          if (request.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)
+          if (Number(request.headers.get("content-length") ?? 0) > relayedBytes)
             return tooLarge();
-          const body = await request2.text();
+          const body = await request.text();
           if (new TextEncoder().encode(body).length > relayedBytes)
             return tooLarge();
-          const found = { ...requestVisitor(request2), ...visitor };
+          const found = { ...requestVisitor(request), ...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 });

package/package.json

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