@findlane/server 0.15.0 → 0.17.0

package/README.md

@@ -48,6 +48,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. `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). |
+| `querySuggestions({ q, limit? })`, `popularSearches({ limit? })` | Whole searches to offer as a visitor types, `[{ q, typed }]`, and the index's popular searches for an empty box. Not counted as searches. |
 | `upsert(records)` | Add or update up to 1,000 records by `objectID`. |
 | `replaceAll(records)` | Replace the whole catalog in one request (up to 100,000 records). |
 | `replaceAllStaged(records, options)` | Replace a larger catalog in batches under one stage ID, switched in one commit. Retrying with the same `stageId` resumes. `abortReplacement(stageId)` drops a stage. |

package/dist/index.cjs

@@ -253,10 +253,31 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(options);
         return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
       },
+      querySuggestions: async (query, options) => {
+        const { signal } = requestOptions(options);
+        return (await request("/query-suggestions", "POST", query, signal)).suggestions;
+      },
+      popularSearches: async (options = {}, requestOptionsOrSignal) => {
+        const { signal } = requestOptions(requestOptionsOrSignal);
+        return (await request("/query-suggestions", "POST", { q: "", limit: options.limit ?? 6 }, signal)).suggestions;
+      },
       recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
         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

@@ -63,6 +63,9 @@ export type IndexSettings = {
      * Exact matches rank first. Searches use it once the index's word list is built, a minute or so after it's
      * turned on. Off by default. */
     compoundWords?: boolean;
+    /** 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;
     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;
@@ -71,6 +74,33 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** An index's query suggestion settings. When saving, give only those to change. */
+export type QuerySuggestionSettings = {
+    /** false: no suggestions. */
+    enabled?: boolean;
+    /** false: no popular searches for an empty box; typed suggestions still use them. */
+    popularSearches?: boolean;
+    /** Popular searches an empty box shows, 1 to 10; 6 by default. */
+    popularCount?: number;
+    /** A shoppers' search becomes a suggestion once searched this many times (3 by default), on this many
+     * different days (2 by default). */
+    minSearches?: number;
+    minDays?: number;
+    /** The facet and searchable fields whose values are suggested, up to 20; null (the default) chooses
+     * readable ones from the records, leaving out slugs, sizes and long text. */
+    fields?: string[] | null;
+    /** Searches to suggest, up to 1,000; to show first, in the empty box too, up to 20; and never to show,
+     * nor anything with their words in a row, up to 1,000. One to six words each. */
+    added?: string[];
+    pinned?: string[];
+    hidden?: string[];
+};
+/** A whole search to offer as a shopper types, or in an empty box. `typed`: where what was typed is in
+ * `q`, as UTF-16 offsets (end exclusive); popular searches have none. */
+export type QuerySuggestion = {
+    q: string;
+    typed?: [number, number];
+};
 /** 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". */
@@ -391,6 +421,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, {
@@ -410,6 +443,75 @@ export type SearchResponse<T> = {
     rewrittenQuery?: string;
 };
 /** 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;
@@ -619,13 +721,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;
@@ -758,9 +862,51 @@ export declare class SearchServerClient {
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
         suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<DidYouMean | null>;
+        /** Query suggestions: whole searches to offer as a shopper types `q`, the best first; with `q` empty, the
+         * index's popular searches. The API key needs the `search` scope; not counted as searches. `limit`: 1 to
+         * 10, 5 by default. */
+        querySuggestions: (query: {
+            q: string;
+            limit?: number;
+        }, options?: AbortSignal | RequestOptions) => Promise<QuerySuggestion[]>;
+        /** The index's popular searches, for an empty search box, with the owner's pinned searches first;
+         * empty until the index has enough searches. The list changes daily. */
+        popularSearches: (options?: {
+            limit?: number;
+        }, requestOptionsOrSignal?: AbortSignal | RequestOptions) => Promise<QuerySuggestion[]>;
         /** 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

@@ -63,6 +63,9 @@ export type IndexSettings = {
      * Exact matches rank first. Searches use it once the index's word list is built, a minute or so after it's
      * turned on. Off by default. */
     compoundWords?: boolean;
+    /** 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;
     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;
@@ -71,6 +74,33 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** An index's query suggestion settings. When saving, give only those to change. */
+export type QuerySuggestionSettings = {
+    /** false: no suggestions. */
+    enabled?: boolean;
+    /** false: no popular searches for an empty box; typed suggestions still use them. */
+    popularSearches?: boolean;
+    /** Popular searches an empty box shows, 1 to 10; 6 by default. */
+    popularCount?: number;
+    /** A shoppers' search becomes a suggestion once searched this many times (3 by default), on this many
+     * different days (2 by default). */
+    minSearches?: number;
+    minDays?: number;
+    /** The facet and searchable fields whose values are suggested, up to 20; null (the default) chooses
+     * readable ones from the records, leaving out slugs, sizes and long text. */
+    fields?: string[] | null;
+    /** Searches to suggest, up to 1,000; to show first, in the empty box too, up to 20; and never to show,
+     * nor anything with their words in a row, up to 1,000. One to six words each. */
+    added?: string[];
+    pinned?: string[];
+    hidden?: string[];
+};
+/** A whole search to offer as a shopper types, or in an empty box. `typed`: where what was typed is in
+ * `q`, as UTF-16 offsets (end exclusive); popular searches have none. */
+export type QuerySuggestion = {
+    q: string;
+    typed?: [number, number];
+};
 /** 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". */
@@ -391,6 +421,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, {
@@ -410,6 +443,75 @@ export type SearchResponse<T> = {
     rewrittenQuery?: string;
 };
 /** 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;
@@ -619,13 +721,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;
@@ -758,9 +862,51 @@ export declare class SearchServerClient {
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
         suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<DidYouMean | null>;
+        /** Query suggestions: whole searches to offer as a shopper types `q`, the best first; with `q` empty, the
+         * index's popular searches. The API key needs the `search` scope; not counted as searches. `limit`: 1 to
+         * 10, 5 by default. */
+        querySuggestions: (query: {
+            q: string;
+            limit?: number;
+        }, options?: AbortSignal | RequestOptions) => Promise<QuerySuggestion[]>;
+        /** The index's popular searches, for an empty search box, with the owner's pinned searches first;
+         * empty until the index has enough searches. The list changes daily. */
+        popularSearches: (options?: {
+            limit?: number;
+        }, requestOptionsOrSignal?: AbortSignal | RequestOptions) => Promise<QuerySuggestion[]>;
         /** 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

@@ -207,10 +207,31 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(options);
         return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
       },
+      querySuggestions: async (query, options) => {
+        const { signal } = requestOptions(options);
+        return (await request("/query-suggestions", "POST", query, signal)).suggestions;
+      },
+      popularSearches: async (options = {}, requestOptionsOrSignal) => {
+        const { signal } = requestOptions(requestOptionsOrSignal);
+        return (await request("/query-suggestions", "POST", { q: "", limit: options.limit ?? 6 }, signal)).suggestions;
+      },
       recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
         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.15.0",
+  "version": "0.17.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",