@findlane/server 0.16.0 → 0.18.0

package/dist/index.cjs

@@ -265,6 +265,19 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(requestOptionsOrSignal);
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
+      lists: {
+        get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
+        getMany: async (ids, options = {}) => {
+          const query = new URLSearchParams({ ...ids ? { ids: ids.join(",") } : {}, ...options.limit ? { limit: String(options.limit) } : {} }).toString();
+          return (await request(`/lists${query ? `?${query}` : ""}`, "GET", undefined, options.signal)).lists;
+        },
+        settings: (signal) => request("/lists/settings", "GET", undefined, signal),
+        save: (id, list, signal) => request(`/lists/${encodeURIComponent(id)}`, "PUT", list, signal),
+        delete: (id, signal) => request(`/lists/${encodeURIComponent(id)}`, "DELETE", undefined, signal),
+        order: (ids, signal) => request("/lists/order", "PUT", { lists: ids }, signal),
+        refresh: (signal) => request("/lists/refresh", "POST", undefined, signal),
+        preview: (list, signal) => request("/lists/preview", "POST", list, signal)
+      },
       events: {
         send: (events, options) => sendEvents(events, options === undefined ? {} : ("aborted" in options) ? { signal: options } : options),
         importOrders: (orders, signal) => sendEvents(async function* () {

package/dist/index.d.cts

@@ -66,6 +66,14 @@ 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;
@@ -335,6 +343,8 @@ 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;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -421,6 +431,9 @@ export type SearchResponse<T> = {
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
     facets: Record<string, Record<string, number>>;
+    /** True when the facet counts are estimates: on an index of 100,000 records or more, a search with more
+     * than 2,000 matches counts its facets on a sample of them, scaled to the total. */
+    facetsEstimated?: boolean;
     /** With `facetStats`: each field's smallest and largest value across the matches, without the field's
      * own filter. A field no match has is left out. */
     facetStats?: Record<string, {
@@ -438,8 +451,88 @@ 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
+ * a sort, with products pinned first and others hidden; or a facet field's values with how many products each
+ * has, for a menu. `updatedAt` is when what the index's lists hold last changed. */
+export type ProductList<T = JsonRecord> = {
+    id: string;
+    title: string;
+    kind: "products";
+    hits: {
+        id: string;
+        record: T;
+    }[];
+    /** The list's filters and sort, for a "See all" link to the same products as a search. */
+    browse: {
+        sort: string;
+        filters: Record<string, unknown>;
+    };
+    updatedAt: string;
+};
+export type ValueList = {
+    id: string;
+    title: string;
+    kind: "values";
+    field: string;
+    values: {
+        value: string;
+        count: number;
+    }[];
+    browse: {
+        filters: Record<string, unknown>;
+    };
+    updatedAt: string;
+};
+export type List<T = JsonRecord> = ProductList<T> | ValueList;
+/** A list as it's set up. Products (`source` "sort", the default): `sort` is one of the index's sorts (its
+ * default without one), `limit` 1 to 50 (10 by default), `pinned` and `hidden` objectIDs, and
+ * `attributesToRetrieve` the fields each product has. Values (`source` "values"): `field` is a facet field,
+ * `sort` "count" (the default) or "name", `limit` 1 to 1,000, and `pinned` and `hidden` values. `filters` are
+ * a search's, for either. */
+export type ListDefinition = {
+    title?: string;
+    source?: "sort" | "values";
+    sort?: string;
+    filters?: SearchRequest["filters"];
+    limit?: number;
+    pinned?: string[];
+    hidden?: string[];
+    attributesToRetrieve?: string[];
+    field?: string;
+};
+/** An index's lists as set up, each with how many products or values it held at its last build and why that
+ * failed, if it did; the last build; and how many lists the plan allows per index. */
+export type ListSettings = {
+    lists: Array<ListDefinition & {
+        id: string;
+        title: string;
+        source: "sort" | "values";
+        updatedAt: string;
+        items: number | null;
+        error: string | null;
+    }>;
+    build: {
+        version: number;
+        builtAt: string | null;
+        buildMs: number | null;
+        updatedAt: string | null;
+        refreshAvailableAt: string | null;
+    } | null;
+    cap: number;
+};
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
@@ -554,7 +647,7 @@ export type ServerEvent = {
     objectID: string;
     position?: number;
     query?: string;
-    list?: "goesWith" | "similar" | "together";
+    list?: "goesWith" | "similar" | "together" | "related";
     from?: string;
     timestamp?: number;
 } | {
@@ -649,13 +742,15 @@ export type SearchesReport = AnalyticsReport & {
         noResults: number;
     }[];
 };
-/** A top query: its clicks on results and their average place (from 1), or null when clicks aren't available. */
+/** A top query: its clicks on results, or null when clicks aren't available; their average place, and the
+ * middle click's, which a few clicks far down don't pull up (from 1, or null without clicks that say their place). */
 export type TopQuery = {
     query: string;
     searches: number;
     noResults: number;
     clicks: number | null;
     averagePosition: number | null;
+    middlePosition: number | null;
 };
 export type QueryCount = {
     query: string;
@@ -803,6 +898,36 @@ 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>>;
+        /** The index's lists: rows of products, such as Popular, and facet fields' values for menus, built ahead
+         * and served from a cache, so reading them isn't counted as searches. Reading needs the `search` scope;
+         * setting them up needs `write`. */
+        lists: {
+            /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
+            get: <R = T>(id: string, options?: {
+                limit?: number;
+                signal?: AbortSignal;
+            }) => Promise<List<R>>;
+            /** Several lists (up to 10) in the order asked, leaving out IDs without a list; without IDs, all of them. */
+            getMany: <R = T>(ids?: string[], options?: {
+                limit?: number;
+                signal?: AbortSignal;
+            }) => Promise<List<R>[]>;
+            /** How the index's lists are set up, and their last build. */
+            settings: (signal?: AbortSignal) => Promise<ListSettings>;
+            /** Creates or changes a list and builds it; one whose filters, sort or field don't work on the index is
+             * refused with why (400), and a new list past the plan's lists per index too (402). */
+            save: (id: string, list: ListDefinition, signal?: AbortSignal) => Promise<ListSettings>;
+            delete: (id: string, signal?: AbortSignal) => Promise<ListSettings>;
+            /** Puts the lists in this order: every list's ID once. */
+            order: (ids: string[], signal?: AbortSignal) => Promise<ListSettings>;
+            /** Builds the lists again now, rather than within the minute they take to follow the index; once a minute. */
+            refresh: (signal?: AbortSignal) => Promise<ListSettings>;
+            /** What a list would hold, built without saving it. */
+            preview: <R = T>(list: ListDefinition, signal?: AbortSignal) => Promise<{
+                list: List<R>;
+                tookMs: number;
+            }>;
+        };
         /** 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: {

package/dist/index.d.ts

@@ -66,6 +66,14 @@ 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;
@@ -335,6 +343,8 @@ 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;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -421,6 +431,9 @@ export type SearchResponse<T> = {
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
     facets: Record<string, Record<string, number>>;
+    /** True when the facet counts are estimates: on an index of 100,000 records or more, a search with more
+     * than 2,000 matches counts its facets on a sample of them, scaled to the total. */
+    facetsEstimated?: boolean;
     /** With `facetStats`: each field's smallest and largest value across the matches, without the field's
      * own filter. A field no match has is left out. */
     facetStats?: Record<string, {
@@ -438,8 +451,88 @@ 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
+ * a sort, with products pinned first and others hidden; or a facet field's values with how many products each
+ * has, for a menu. `updatedAt` is when what the index's lists hold last changed. */
+export type ProductList<T = JsonRecord> = {
+    id: string;
+    title: string;
+    kind: "products";
+    hits: {
+        id: string;
+        record: T;
+    }[];
+    /** The list's filters and sort, for a "See all" link to the same products as a search. */
+    browse: {
+        sort: string;
+        filters: Record<string, unknown>;
+    };
+    updatedAt: string;
+};
+export type ValueList = {
+    id: string;
+    title: string;
+    kind: "values";
+    field: string;
+    values: {
+        value: string;
+        count: number;
+    }[];
+    browse: {
+        filters: Record<string, unknown>;
+    };
+    updatedAt: string;
+};
+export type List<T = JsonRecord> = ProductList<T> | ValueList;
+/** A list as it's set up. Products (`source` "sort", the default): `sort` is one of the index's sorts (its
+ * default without one), `limit` 1 to 50 (10 by default), `pinned` and `hidden` objectIDs, and
+ * `attributesToRetrieve` the fields each product has. Values (`source` "values"): `field` is a facet field,
+ * `sort` "count" (the default) or "name", `limit` 1 to 1,000, and `pinned` and `hidden` values. `filters` are
+ * a search's, for either. */
+export type ListDefinition = {
+    title?: string;
+    source?: "sort" | "values";
+    sort?: string;
+    filters?: SearchRequest["filters"];
+    limit?: number;
+    pinned?: string[];
+    hidden?: string[];
+    attributesToRetrieve?: string[];
+    field?: string;
+};
+/** An index's lists as set up, each with how many products or values it held at its last build and why that
+ * failed, if it did; the last build; and how many lists the plan allows per index. */
+export type ListSettings = {
+    lists: Array<ListDefinition & {
+        id: string;
+        title: string;
+        source: "sort" | "values";
+        updatedAt: string;
+        items: number | null;
+        error: string | null;
+    }>;
+    build: {
+        version: number;
+        builtAt: string | null;
+        buildMs: number | null;
+        updatedAt: string | null;
+        refreshAvailableAt: string | null;
+    } | null;
+    cap: number;
+};
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
@@ -554,7 +647,7 @@ export type ServerEvent = {
     objectID: string;
     position?: number;
     query?: string;
-    list?: "goesWith" | "similar" | "together";
+    list?: "goesWith" | "similar" | "together" | "related";
     from?: string;
     timestamp?: number;
 } | {
@@ -649,13 +742,15 @@ export type SearchesReport = AnalyticsReport & {
         noResults: number;
     }[];
 };
-/** A top query: its clicks on results and their average place (from 1), or null when clicks aren't available. */
+/** A top query: its clicks on results, or null when clicks aren't available; their average place, and the
+ * middle click's, which a few clicks far down don't pull up (from 1, or null without clicks that say their place). */
 export type TopQuery = {
     query: string;
     searches: number;
     noResults: number;
     clicks: number | null;
     averagePosition: number | null;
+    middlePosition: number | null;
 };
 export type QueryCount = {
     query: string;
@@ -803,6 +898,36 @@ 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>>;
+        /** The index's lists: rows of products, such as Popular, and facet fields' values for menus, built ahead
+         * and served from a cache, so reading them isn't counted as searches. Reading needs the `search` scope;
+         * setting them up needs `write`. */
+        lists: {
+            /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
+            get: <R = T>(id: string, options?: {
+                limit?: number;
+                signal?: AbortSignal;
+            }) => Promise<List<R>>;
+            /** Several lists (up to 10) in the order asked, leaving out IDs without a list; without IDs, all of them. */
+            getMany: <R = T>(ids?: string[], options?: {
+                limit?: number;
+                signal?: AbortSignal;
+            }) => Promise<List<R>[]>;
+            /** How the index's lists are set up, and their last build. */
+            settings: (signal?: AbortSignal) => Promise<ListSettings>;
+            /** Creates or changes a list and builds it; one whose filters, sort or field don't work on the index is
+             * refused with why (400), and a new list past the plan's lists per index too (402). */
+            save: (id: string, list: ListDefinition, signal?: AbortSignal) => Promise<ListSettings>;
+            delete: (id: string, signal?: AbortSignal) => Promise<ListSettings>;
+            /** Puts the lists in this order: every list's ID once. */
+            order: (ids: string[], signal?: AbortSignal) => Promise<ListSettings>;
+            /** Builds the lists again now, rather than within the minute they take to follow the index; once a minute. */
+            refresh: (signal?: AbortSignal) => Promise<ListSettings>;
+            /** What a list would hold, built without saving it. */
+            preview: <R = T>(list: ListDefinition, signal?: AbortSignal) => Promise<{
+                list: List<R>;
+                tookMs: number;
+            }>;
+        };
         /** 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: {

package/dist/index.js

@@ -219,6 +219,19 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(requestOptionsOrSignal);
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
+      lists: {
+        get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
+        getMany: async (ids, options = {}) => {
+          const query = new URLSearchParams({ ...ids ? { ids: ids.join(",") } : {}, ...options.limit ? { limit: String(options.limit) } : {} }).toString();
+          return (await request(`/lists${query ? `?${query}` : ""}`, "GET", undefined, options.signal)).lists;
+        },
+        settings: (signal) => request("/lists/settings", "GET", undefined, signal),
+        save: (id, list, signal) => request(`/lists/${encodeURIComponent(id)}`, "PUT", list, signal),
+        delete: (id, signal) => request(`/lists/${encodeURIComponent(id)}`, "DELETE", undefined, signal),
+        order: (ids, signal) => request("/lists/order", "PUT", { lists: ids }, signal),
+        refresh: (signal) => request("/lists/refresh", "POST", undefined, signal),
+        preview: (list, signal) => request("/lists/preview", "POST", list, signal)
+      },
       events: {
         send: (events, options) => sendEvents(events, options === undefined ? {} : ("aborted" in options) ? { signal: options } : options),
         importOrders: (orders, signal) => sendEvents(async function* () {

package/package.json

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