@findlane/server 0.15.0 → 0.16.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,6 +253,14 @@ 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));

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". */
@@ -758,6 +788,18 @@ 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>>;

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". */
@@ -758,6 +788,18 @@ 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>>;

package/dist/index.js

@@ -207,6 +207,14 @@ 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));

package/package.json

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