@findlane/server 0.14.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. |
@@ -55,11 +56,14 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 | `getRecord(objectID)` | A record and its version. |
 | `upsertOne(record, { expectedVersion })`, `deleteOne(objectID, { expectedVersion })` | Write only if the record is still at `expectedVersion` (0 for one that never existed); retried with one idempotency key. |
 | `getSettings()`, `replaceSettings(settings)`, `waitForSettings()` | Read and change searchable fields, facets, filters, sorts, custom ranking, synonyms, languages, typo tolerance, and text normalization. |
+| `compareSettings(settings, { queries, searched }?)` | Compare settings with the index's own without saving them: its search tests and most searched queries, each searched with both. Says which tests would fail and whose results change. |
+| `getSearchTests()`, `setSearchTests(tests)` | Searches that must keep working, saved apart from the settings, such as a record in the top 3 or at least 100 results. `compareSettings` checks them. |
 | `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, { 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). |
+| `analytics.searches()`, `.queries({ list, limit })`, `.filters()`, `.events()`, `.products()`, `.productCounts()`, `.product(objectID)` | The index's analytics, for your own admin: searches over time, top queries with their clicks, queries without results or clicks, the filters used, events, and each product's views, add-to-carts and orders. The key needs the `analytics` scope, and works only from a server. See [Analytics](https://findlane.dev/docs/api#analytics). |
 
 ### Settings
 
@@ -72,6 +76,14 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 
 A large `searchable` or `rebuild` change continues in the background, with its progress in `rebuild` (also returned by `getSettings`). Searches use the previous settings until it finishes, and `waitForSettings()` waits for it.
 
+Before saving a change to rules, synonyms, typo tolerance, or ranking, `compareSettings` shows what it does, and `{}` runs the search tests with the current settings:
+
+```ts
+const comparison = await products.compareSettings({ rules: nextRules })
+const failing = comparison.tests.filter((test) => test.before && !test.after)
+if (!failing.length) await products.replaceSettings({ ...(await products.getSettings()), rules: nextRules })
+```
+
 ### Browser search
 
 Only upload fields you intend to make public if browser search is enabled. `getPublicSearchAccess()` shows the current mode. `setPublicSearchPolicy({ returnFields, searchFields, filterFields, facetFields, sortIds, defaultSort })` restricts the index at the API, and `usePublicIndexDefaults()` removes the restrictions. Only a workspace owner can change allowed browser origins, in the dashboard.

package/dist/index.cjs

@@ -67,6 +67,16 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+function analyticsQuery(options) {
+  const params = new URLSearchParams;
+  for (const name of ["range", "from", "to", "interval", "source", "list", "limit"]) {
+    const value = options[name];
+    if (value !== undefined)
+      params.set(name, value instanceof Date ? value.toISOString() : String(value));
+  }
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
 var eventsPerRequest = 200;
 var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
 var relayedBytes = 256 * 1024;
@@ -222,6 +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 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);
@@ -242,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));
@@ -279,6 +298,15 @@ class SearchServerClient {
         },
         relay: (body, visitor, signal) => relayEvents(body, visitor, signal)
       },
+      analytics: {
+        searches: (options = {}) => report("searches", options),
+        queries: (options = {}) => report("queries", options),
+        filters: (options = {}) => report("filters", options),
+        events: (options = {}) => report("events", options),
+        products: (options = {}) => report("products", options),
+        productCounts: (options = {}) => report("product-counts", options),
+        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options)
+      },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),
@@ -337,6 +365,16 @@ class SearchServerClient {
         const { rebuild: _rebuild, rebuilt: _rebuilt, applied: _applied, ...body } = settings;
         return request("/config", "PUT", body, signal);
       },
+      compareSettings: (settings, options = {}) => {
+        const { rebuild: _rebuild, rebuilt: _rebuilt, applied: _applied, ...body } = settings;
+        return request("/compare", "POST", {
+          settings: body,
+          ...options.queries ? { queries: options.queries } : {},
+          ...options.searched === false ? { searched: false } : {}
+        }, options.signal);
+      },
+      getSearchTests: async (signal) => (await request("/tests", "GET", undefined, signal)).tests,
+      setSearchTests: async (tests, signal) => (await request("/tests", "PUT", { tests }, signal)).tests,
       waitForSettings: async (options = {}) => {
         const deadline = Date.now() + (options.timeoutMs ?? 30 * 60000);
         while (true) {

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". */
@@ -136,6 +166,101 @@ export type SavedSettings = IndexSettings & {
     rebuilt: boolean;
     rebuild: SettingsRebuild | null;
 };
+/** What a search test expects of its query's results: a record among the first `inTop` results (1 to
+ * 20), a record not among the first `notInTop`, or at least `minResults` results (1 to 10,000). */
+export type TestExpectation = {
+    objectID: string;
+    inTop: number;
+} | {
+    objectID: string;
+    notInTop: number;
+} | {
+    minResults: number;
+};
+/** A search that must keep working, saved apart from the settings, which `compareSettings` checks: a query
+ * (empty browses), its filters on facet, filter or sort fields, and what its results should hold. IDs are
+ * 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index; notes up to 200 characters. */
+export type SearchTest = {
+    id: string;
+    q: string;
+    filters?: SearchRequest["filters"];
+    expect: TestExpectation;
+    note?: string;
+};
+/** How many compared queries changed in a way, and their searches in the last 30 days. */
+export type CompareCount = {
+    queries: number;
+    searches: number;
+};
+export type ComparedHit = {
+    objectID: string;
+    title: string;
+};
+/** Proposed settings compared with the index's own, without saving them (`compareSettings`). */
+export type SettingsComparison = {
+    /** The queries compared, and their searches in the last 30 days. */
+    compared: number;
+    searches: number;
+    /** Time (20 seconds) ran out before every query was compared. */
+    truncated: boolean;
+    summary: {
+        topChanged: CompareCount;
+        moreResults: CompareCount;
+        fewerResults: CompareCount;
+        nowNothing: CompareCount;
+        nowSomething: CompareCount;
+    };
+    /** Every search test: whether it passes with the current settings (`before`) and the proposed ones
+     * (`after`), or `skipped` when time ran out first, or the search's `error`. */
+    tests: (Omit<SearchTest, "note"> & {
+        before?: boolean;
+        after?: boolean;
+        skipped?: true;
+        error?: string;
+    })[];
+    /** Up to 50 queries whose top 10 or total changed, the tests' queries first, then the most searched: the
+     * totals and first 5 results with each, and the results that left, joined, and moved within the top 10.
+     * Places are in the first 20 results; null is outside them. */
+    changes: {
+        q: string;
+        filters?: SearchRequest["filters"];
+        searches: number;
+        before: {
+            total: number;
+            top: ComparedHit[];
+        };
+        after: {
+            total: number;
+            top: ComparedHit[];
+        };
+        gone: (ComparedHit & {
+            from: number;
+            to: number | null;
+        })[];
+        added: (ComparedHit & {
+            from: number | null;
+            to: number;
+        })[];
+        moved: (ComparedHit & {
+            from: number;
+            to: number;
+        })[];
+    }[];
+    errors: {
+        q: string;
+        error: string;
+    }[];
+};
+export type CompareOptions = {
+    /** More queries to compare, such as those a change is for: text, or `{ q, filters }`. Up to 200. */
+    queries?: (string | {
+        q: string;
+        filters?: SearchRequest["filters"];
+    })[];
+    /** false leaves out the index's 100 most searched queries of the last 30 days. */
+    searched?: boolean;
+    signal?: AbortSignal;
+};
 export type PublicSearchPolicy = {
     returnFields: string[];
     searchFields: string[];
@@ -474,6 +599,166 @@ export type EventOptions = {
     visitorId?: string;
     visitId?: string;
 };
+/** An analytics window, in UTC: `range` (7d by default), or `from` and `to`. A date as `from` is the start of
+ * that day, and as `to` includes the whole day; `to` is now by default. Analytics go back 90 days: a window
+ * starting earlier starts then, and the report's `from` says so. */
+export type AnalyticsOptions = {
+    range?: "24h" | "7d" | "30d" | "90d";
+    from?: string | Date;
+    to?: string | Date;
+    /** Searches from browsers (browser search), from servers (API keys), or both, by default. */
+    source?: "all" | "browser" | "server";
+    signal?: AbortSignal;
+};
+/** What every analytics report starts with. `sampled`: the counts are estimates, because Analytics Engine,
+ * which keeps them, sampled some of them; totals and lists stay close, small counts less so. */
+export type AnalyticsReport = {
+    index: string;
+    from: string;
+    to: string;
+    source: "all" | "browser" | "server";
+    sampled: boolean;
+};
+export type SearchTotals = {
+    searches: number;
+    /** Searches whose query and result count were recorded: the base for `noResultRate`. */
+    tracked: number;
+    noResults: number;
+    /** `noResults` of `tracked`, 0 to 1; null without tracked searches. */
+    noResultRate: number | null;
+    browser: number;
+    server: number;
+    uniqueQueries: number;
+    /** Response times at the API, in ms. */
+    medianMs: number;
+    p95Ms: number;
+};
+export type SearchesReport = AnalyticsReport & {
+    interval: "hour" | "day";
+    totals: SearchTotals;
+    /** The same span just before `from`. */
+    previous: SearchTotals & {
+        from: string;
+        to: string;
+    };
+    /** Every hour or day of the window, the first one starting at or before `from`. */
+    series: {
+        t: string;
+        searches: number;
+        tracked: number;
+        noResults: number;
+    }[];
+};
+/** A top query: its clicks on results and their average place (from 1), or null when clicks aren't available. */
+export type TopQuery = {
+    query: string;
+    searches: number;
+    noResults: number;
+    clicks: number | null;
+    averagePosition: number | null;
+};
+export type QueryCount = {
+    query: string;
+    searches: number;
+};
+export type QueryLists = {
+    top: TopQuery;
+    noResults: QueryCount;
+    noClicks: QueryCount;
+};
+export type QueriesReport<L extends keyof QueryLists = "top"> = AnalyticsReport & {
+    list: L;
+    queries: QueryLists[L][];
+};
+export type FiltersReport = AnalyticsReport & {
+    /** Searches whose filters and sort were recorded. */
+    searches: number;
+    /** Each filter field with the searches that filtered on it, up to 100. */
+    filters: {
+        field: string;
+        searches: number;
+    }[];
+    /** Each sort with its searches; `sort` is null for searches that named none, which use the index's default. */
+    sorts: {
+        sort: string | null;
+        searches: number;
+    }[];
+};
+export type EventType = "view" | "click" | "addToCart" | "purchase" | "cancel";
+export type EventsReport = AnalyticsReport & {
+    interval: "hour" | "day";
+    /** Accepted events of each type, by source. */
+    types: {
+        type: EventType;
+        browser: number;
+        server: number;
+    }[];
+    /** Orders accepted, and of them those stored, which Bought together and the order counts use. */
+    orders: {
+        accepted: number;
+        stored: number;
+    };
+    /** Events from crawlers and scripts, which are dropped. */
+    bots: number;
+    /** Refused events, by why. */
+    refused: {
+        reason: string;
+        events: number;
+    }[];
+    series: ({
+        t: string;
+    } & Record<EventType, number>)[];
+};
+/** A product's counts. `viewers` is how many visitor IDs viewed it, or null when the index's views carry
+ * none. `searchClicks` is clicks on it outside recommendations: in search results and product lists. */
+export type ProductCount = {
+    objectID: string;
+    views: number;
+    viewers: number | null;
+    searchClicks: number;
+    carts: number;
+    orders: number;
+};
+export type ListedProduct = ProductCount & {
+    title: string;
+    image: string | null;
+};
+/** Product reports are exact and about 2 minutes behind; `computedAt` is when they were counted, up to 5
+ * minutes ago. `orders` is the orders stored in the window. */
+export type ProductListsReport = AnalyticsReport & {
+    computedAt: string;
+    orders: number;
+    /** The most viewed, most added to carts, and most ordered products, by views. */
+    products: ListedProduct[];
+    /** Products with 50 or more views, the fewest orders per view first; null without orders. */
+    viewedNotBought: ListedProduct[] | null;
+};
+export type ProductCountsReport = AnalyticsReport & {
+    computedAt: string;
+    orders: number;
+    /** false when more than 50,000 products had events, and only the most viewed are listed. */
+    complete: boolean;
+    products: ProductCount[];
+};
+export type ProductReport = AnalyticsReport & {
+    objectID: string;
+    interval: "hour" | "day";
+    totals: Omit<ProductCount, "objectID">;
+    series: ({
+        t: string;
+    } & Omit<ProductCount, "objectID">)[];
+    /** The queries whose results it was clicked in, the most clicks first, up to 20. */
+    searchedFor: {
+        query: string;
+        clicks: number;
+    }[];
+    /** Clicks on it in each recommendation list. */
+    recommendationClicks: {
+        goesWith: number;
+        similar: number;
+        together: number;
+    };
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -503,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>>;
@@ -532,6 +829,39 @@ export declare class SearchServerClient {
              * and its visitor. Answers with the API's response. */
             relay: (body: string, visitor: RelayedVisitor, signal?: AbortSignal) => Promise<Response>;
         };
+        /** The index's search analytics. The API key needs the `analytics` scope, and works only from a server:
+         * requests from web pages are refused. */
+        analytics: {
+            /** Searches, searches without results and response times, beside the same span before, and a series per
+             * hour (up to 7 days, by default) or day. */
+            searches: (options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<SearchesReport>;
+            /** Queries, the most searched first: `top` (by default) with their clicks, `noResults`, or `noClicks`, which
+             * found something nobody clicked. `limit` is 1 to 1,000, 100 by default. */
+            queries: <L extends keyof QueryLists = "top">(options?: AnalyticsOptions & {
+                list?: L;
+                limit?: number;
+            }) => Promise<QueriesReport<L>>;
+            /** The filter fields and sorts searches used. */
+            filters: (options?: AnalyticsOptions) => Promise<FiltersReport>;
+            /** Events of each type over time and by source, orders stored, and refused and bot events. */
+            events: (options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<EventsReport>;
+            /** The most viewed, most added to carts and most ordered products, with titles and images, and those
+             * viewed but rarely bought. Exact, from every event kept (13 months, from 9 October 2026). */
+            products: (options?: AnalyticsOptions) => Promise<ProductListsReport>;
+            /** Every product with events or orders in the window, the most viewed first, up to 50,000: views,
+             * viewers, clicks, add-to-carts and orders. Exact, like `products`. */
+            productCounts: (options?: AnalyticsOptions) => Promise<ProductCountsReport>;
+            /** One product's views, viewers, clicks, add-to-carts and orders per hour or day, the queries it was
+             * clicked from, and its clicks in recommendations. Fast, for a product page in an admin: views and
+             * clicks are estimates when `sampled`, and an add-to-cart of several products counts toward the first. */
+            product: (objectID: string, options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<ProductReport>;
+        };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;
@@ -545,6 +875,16 @@ export declare class SearchServerClient {
         delete: (objectID: string, signal?: AbortSignal) => Promise<WriteReceipt>;
         getSettings: (signal?: AbortSignal) => Promise<CurrentSettings>;
         replaceSettings: (settings: IndexSettings, signal?: AbortSignal) => Promise<SavedSettings>;
+        /** Compares settings with the index's own without saving them: its search tests, `queries`, and its 100
+         * most searched queries of the last 30 days, each searched with both, for up to 20 seconds. Takes the
+         * settings `replaceSettings` does, or only those that change; `{}` runs the tests with the current
+         * settings. A change to what the index stores (new searchable, facet, filter, sort or location fields,
+         * or normalization) throws a 409: save it first. Not counted as searches. */
+        compareSettings: (settings: Partial<IndexSettings>, options?: CompareOptions) => Promise<SettingsComparison>;
+        /** The index's search tests. */
+        getSearchTests: (signal?: AbortSignal) => Promise<SearchTest[]>;
+        /** Replaces the index's search tests, up to 200; `[]` deletes them. */
+        setSearchTests: (tests: SearchTest[], signal?: AbortSignal) => Promise<SearchTest[]>;
         /** Waits until no settings rebuild is running; throws if it failed. */
         waitForSettings: (options?: {
             timeoutMs?: number;

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". */
@@ -136,6 +166,101 @@ export type SavedSettings = IndexSettings & {
     rebuilt: boolean;
     rebuild: SettingsRebuild | null;
 };
+/** What a search test expects of its query's results: a record among the first `inTop` results (1 to
+ * 20), a record not among the first `notInTop`, or at least `minResults` results (1 to 10,000). */
+export type TestExpectation = {
+    objectID: string;
+    inTop: number;
+} | {
+    objectID: string;
+    notInTop: number;
+} | {
+    minResults: number;
+};
+/** A search that must keep working, saved apart from the settings, which `compareSettings` checks: a query
+ * (empty browses), its filters on facet, filter or sort fields, and what its results should hold. IDs are
+ * 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index; notes up to 200 characters. */
+export type SearchTest = {
+    id: string;
+    q: string;
+    filters?: SearchRequest["filters"];
+    expect: TestExpectation;
+    note?: string;
+};
+/** How many compared queries changed in a way, and their searches in the last 30 days. */
+export type CompareCount = {
+    queries: number;
+    searches: number;
+};
+export type ComparedHit = {
+    objectID: string;
+    title: string;
+};
+/** Proposed settings compared with the index's own, without saving them (`compareSettings`). */
+export type SettingsComparison = {
+    /** The queries compared, and their searches in the last 30 days. */
+    compared: number;
+    searches: number;
+    /** Time (20 seconds) ran out before every query was compared. */
+    truncated: boolean;
+    summary: {
+        topChanged: CompareCount;
+        moreResults: CompareCount;
+        fewerResults: CompareCount;
+        nowNothing: CompareCount;
+        nowSomething: CompareCount;
+    };
+    /** Every search test: whether it passes with the current settings (`before`) and the proposed ones
+     * (`after`), or `skipped` when time ran out first, or the search's `error`. */
+    tests: (Omit<SearchTest, "note"> & {
+        before?: boolean;
+        after?: boolean;
+        skipped?: true;
+        error?: string;
+    })[];
+    /** Up to 50 queries whose top 10 or total changed, the tests' queries first, then the most searched: the
+     * totals and first 5 results with each, and the results that left, joined, and moved within the top 10.
+     * Places are in the first 20 results; null is outside them. */
+    changes: {
+        q: string;
+        filters?: SearchRequest["filters"];
+        searches: number;
+        before: {
+            total: number;
+            top: ComparedHit[];
+        };
+        after: {
+            total: number;
+            top: ComparedHit[];
+        };
+        gone: (ComparedHit & {
+            from: number;
+            to: number | null;
+        })[];
+        added: (ComparedHit & {
+            from: number | null;
+            to: number;
+        })[];
+        moved: (ComparedHit & {
+            from: number;
+            to: number;
+        })[];
+    }[];
+    errors: {
+        q: string;
+        error: string;
+    }[];
+};
+export type CompareOptions = {
+    /** More queries to compare, such as those a change is for: text, or `{ q, filters }`. Up to 200. */
+    queries?: (string | {
+        q: string;
+        filters?: SearchRequest["filters"];
+    })[];
+    /** false leaves out the index's 100 most searched queries of the last 30 days. */
+    searched?: boolean;
+    signal?: AbortSignal;
+};
 export type PublicSearchPolicy = {
     returnFields: string[];
     searchFields: string[];
@@ -474,6 +599,166 @@ export type EventOptions = {
     visitorId?: string;
     visitId?: string;
 };
+/** An analytics window, in UTC: `range` (7d by default), or `from` and `to`. A date as `from` is the start of
+ * that day, and as `to` includes the whole day; `to` is now by default. Analytics go back 90 days: a window
+ * starting earlier starts then, and the report's `from` says so. */
+export type AnalyticsOptions = {
+    range?: "24h" | "7d" | "30d" | "90d";
+    from?: string | Date;
+    to?: string | Date;
+    /** Searches from browsers (browser search), from servers (API keys), or both, by default. */
+    source?: "all" | "browser" | "server";
+    signal?: AbortSignal;
+};
+/** What every analytics report starts with. `sampled`: the counts are estimates, because Analytics Engine,
+ * which keeps them, sampled some of them; totals and lists stay close, small counts less so. */
+export type AnalyticsReport = {
+    index: string;
+    from: string;
+    to: string;
+    source: "all" | "browser" | "server";
+    sampled: boolean;
+};
+export type SearchTotals = {
+    searches: number;
+    /** Searches whose query and result count were recorded: the base for `noResultRate`. */
+    tracked: number;
+    noResults: number;
+    /** `noResults` of `tracked`, 0 to 1; null without tracked searches. */
+    noResultRate: number | null;
+    browser: number;
+    server: number;
+    uniqueQueries: number;
+    /** Response times at the API, in ms. */
+    medianMs: number;
+    p95Ms: number;
+};
+export type SearchesReport = AnalyticsReport & {
+    interval: "hour" | "day";
+    totals: SearchTotals;
+    /** The same span just before `from`. */
+    previous: SearchTotals & {
+        from: string;
+        to: string;
+    };
+    /** Every hour or day of the window, the first one starting at or before `from`. */
+    series: {
+        t: string;
+        searches: number;
+        tracked: number;
+        noResults: number;
+    }[];
+};
+/** A top query: its clicks on results and their average place (from 1), or null when clicks aren't available. */
+export type TopQuery = {
+    query: string;
+    searches: number;
+    noResults: number;
+    clicks: number | null;
+    averagePosition: number | null;
+};
+export type QueryCount = {
+    query: string;
+    searches: number;
+};
+export type QueryLists = {
+    top: TopQuery;
+    noResults: QueryCount;
+    noClicks: QueryCount;
+};
+export type QueriesReport<L extends keyof QueryLists = "top"> = AnalyticsReport & {
+    list: L;
+    queries: QueryLists[L][];
+};
+export type FiltersReport = AnalyticsReport & {
+    /** Searches whose filters and sort were recorded. */
+    searches: number;
+    /** Each filter field with the searches that filtered on it, up to 100. */
+    filters: {
+        field: string;
+        searches: number;
+    }[];
+    /** Each sort with its searches; `sort` is null for searches that named none, which use the index's default. */
+    sorts: {
+        sort: string | null;
+        searches: number;
+    }[];
+};
+export type EventType = "view" | "click" | "addToCart" | "purchase" | "cancel";
+export type EventsReport = AnalyticsReport & {
+    interval: "hour" | "day";
+    /** Accepted events of each type, by source. */
+    types: {
+        type: EventType;
+        browser: number;
+        server: number;
+    }[];
+    /** Orders accepted, and of them those stored, which Bought together and the order counts use. */
+    orders: {
+        accepted: number;
+        stored: number;
+    };
+    /** Events from crawlers and scripts, which are dropped. */
+    bots: number;
+    /** Refused events, by why. */
+    refused: {
+        reason: string;
+        events: number;
+    }[];
+    series: ({
+        t: string;
+    } & Record<EventType, number>)[];
+};
+/** A product's counts. `viewers` is how many visitor IDs viewed it, or null when the index's views carry
+ * none. `searchClicks` is clicks on it outside recommendations: in search results and product lists. */
+export type ProductCount = {
+    objectID: string;
+    views: number;
+    viewers: number | null;
+    searchClicks: number;
+    carts: number;
+    orders: number;
+};
+export type ListedProduct = ProductCount & {
+    title: string;
+    image: string | null;
+};
+/** Product reports are exact and about 2 minutes behind; `computedAt` is when they were counted, up to 5
+ * minutes ago. `orders` is the orders stored in the window. */
+export type ProductListsReport = AnalyticsReport & {
+    computedAt: string;
+    orders: number;
+    /** The most viewed, most added to carts, and most ordered products, by views. */
+    products: ListedProduct[];
+    /** Products with 50 or more views, the fewest orders per view first; null without orders. */
+    viewedNotBought: ListedProduct[] | null;
+};
+export type ProductCountsReport = AnalyticsReport & {
+    computedAt: string;
+    orders: number;
+    /** false when more than 50,000 products had events, and only the most viewed are listed. */
+    complete: boolean;
+    products: ProductCount[];
+};
+export type ProductReport = AnalyticsReport & {
+    objectID: string;
+    interval: "hour" | "day";
+    totals: Omit<ProductCount, "objectID">;
+    series: ({
+        t: string;
+    } & Omit<ProductCount, "objectID">)[];
+    /** The queries whose results it was clicked in, the most clicks first, up to 20. */
+    searchedFor: {
+        query: string;
+        clicks: number;
+    }[];
+    /** Clicks on it in each recommendation list. */
+    recommendationClicks: {
+        goesWith: number;
+        similar: number;
+        together: number;
+    };
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -503,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>>;
@@ -532,6 +829,39 @@ export declare class SearchServerClient {
              * and its visitor. Answers with the API's response. */
             relay: (body: string, visitor: RelayedVisitor, signal?: AbortSignal) => Promise<Response>;
         };
+        /** The index's search analytics. The API key needs the `analytics` scope, and works only from a server:
+         * requests from web pages are refused. */
+        analytics: {
+            /** Searches, searches without results and response times, beside the same span before, and a series per
+             * hour (up to 7 days, by default) or day. */
+            searches: (options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<SearchesReport>;
+            /** Queries, the most searched first: `top` (by default) with their clicks, `noResults`, or `noClicks`, which
+             * found something nobody clicked. `limit` is 1 to 1,000, 100 by default. */
+            queries: <L extends keyof QueryLists = "top">(options?: AnalyticsOptions & {
+                list?: L;
+                limit?: number;
+            }) => Promise<QueriesReport<L>>;
+            /** The filter fields and sorts searches used. */
+            filters: (options?: AnalyticsOptions) => Promise<FiltersReport>;
+            /** Events of each type over time and by source, orders stored, and refused and bot events. */
+            events: (options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<EventsReport>;
+            /** The most viewed, most added to carts and most ordered products, with titles and images, and those
+             * viewed but rarely bought. Exact, from every event kept (13 months, from 9 October 2026). */
+            products: (options?: AnalyticsOptions) => Promise<ProductListsReport>;
+            /** Every product with events or orders in the window, the most viewed first, up to 50,000: views,
+             * viewers, clicks, add-to-carts and orders. Exact, like `products`. */
+            productCounts: (options?: AnalyticsOptions) => Promise<ProductCountsReport>;
+            /** One product's views, viewers, clicks, add-to-carts and orders per hour or day, the queries it was
+             * clicked from, and its clicks in recommendations. Fast, for a product page in an admin: views and
+             * clicks are estimates when `sampled`, and an add-to-cart of several products counts toward the first. */
+            product: (objectID: string, options?: AnalyticsOptions & {
+                interval?: "hour" | "day";
+            }) => Promise<ProductReport>;
+        };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;
@@ -545,6 +875,16 @@ export declare class SearchServerClient {
         delete: (objectID: string, signal?: AbortSignal) => Promise<WriteReceipt>;
         getSettings: (signal?: AbortSignal) => Promise<CurrentSettings>;
         replaceSettings: (settings: IndexSettings, signal?: AbortSignal) => Promise<SavedSettings>;
+        /** Compares settings with the index's own without saving them: its search tests, `queries`, and its 100
+         * most searched queries of the last 30 days, each searched with both, for up to 20 seconds. Takes the
+         * settings `replaceSettings` does, or only those that change; `{}` runs the tests with the current
+         * settings. A change to what the index stores (new searchable, facet, filter, sort or location fields,
+         * or normalization) throws a 409: save it first. Not counted as searches. */
+        compareSettings: (settings: Partial<IndexSettings>, options?: CompareOptions) => Promise<SettingsComparison>;
+        /** The index's search tests. */
+        getSearchTests: (signal?: AbortSignal) => Promise<SearchTest[]>;
+        /** Replaces the index's search tests, up to 200; `[]` deletes them. */
+        setSearchTests: (tests: SearchTest[], signal?: AbortSignal) => Promise<SearchTest[]>;
         /** Waits until no settings rebuild is running; throws if it failed. */
         waitForSettings: (options?: {
             timeoutMs?: number;

package/dist/index.js

@@ -21,6 +21,16 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+function analyticsQuery(options) {
+  const params = new URLSearchParams;
+  for (const name of ["range", "from", "to", "interval", "source", "list", "limit"]) {
+    const value = options[name];
+    if (value !== undefined)
+      params.set(name, value instanceof Date ? value.toISOString() : String(value));
+  }
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
 var eventsPerRequest = 200;
 var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
 var relayedBytes = 256 * 1024;
@@ -176,6 +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 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);
@@ -196,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));
@@ -233,6 +252,15 @@ class SearchServerClient {
         },
         relay: (body, visitor, signal) => relayEvents(body, visitor, signal)
       },
+      analytics: {
+        searches: (options = {}) => report("searches", options),
+        queries: (options = {}) => report("queries", options),
+        filters: (options = {}) => report("filters", options),
+        events: (options = {}) => report("events", options),
+        products: (options = {}) => report("products", options),
+        productCounts: (options = {}) => report("product-counts", options),
+        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options)
+      },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),
@@ -291,6 +319,16 @@ class SearchServerClient {
         const { rebuild: _rebuild, rebuilt: _rebuilt, applied: _applied, ...body } = settings;
         return request("/config", "PUT", body, signal);
       },
+      compareSettings: (settings, options = {}) => {
+        const { rebuild: _rebuild, rebuilt: _rebuilt, applied: _applied, ...body } = settings;
+        return request("/compare", "POST", {
+          settings: body,
+          ...options.queries ? { queries: options.queries } : {},
+          ...options.searched === false ? { searched: false } : {}
+        }, options.signal);
+      },
+      getSearchTests: async (signal) => (await request("/tests", "GET", undefined, signal)).tests,
+      setSearchTests: async (tests, signal) => (await request("/tests", "PUT", { tests }, signal)).tests,
       waitForSettings: async (options = {}) => {
         const deadline = Date.now() + (options.timeoutMs ?? 30 * 60000);
         while (true) {

package/package.json

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