@findlane/server 0.31.0 → 0.33.0

package/README.md

@@ -60,7 +60,8 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 | `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.send(events, { visitorId, visitId, abTest }?)`, `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. `abTest`, from the shopper's search answer, puts them in their A/B test group. |
+| `abTests.get()`, `abTests.estimate({ share })`, `analytics.abTest()` | The index's A/B tests of its settings, with their results, and what a test would take. Owners start and end them in the dashboard. |
 | `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). |

package/dist/index.cjs

@@ -241,7 +241,8 @@ class SearchServerClient {
       return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
     };
     const sendEvents = async (events, options = {}) => {
-      const { signal, visitorId, visitId } = options;
+      const { signal, visitorId, visitId, abTest } = options;
+      const label = abTest === undefined || typeof abTest === "string" ? abTest : `${abTest.id}:${abTest.variant}`;
       const result = { accepted: 0, rejected: [] };
       let batch = [];
       let sent = 0;
@@ -251,6 +252,7 @@ class SearchServerClient {
         const answer = await postEvents({
           ...visitorId === undefined ? {} : { visitorId },
           ...visitId === undefined ? {} : { visitId },
+          ...label === undefined ? {} : { abTest: label },
           events: batch
         }, signal);
         result.accepted += answer.accepted ?? 0;
@@ -394,7 +396,12 @@ class SearchServerClient {
         product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
         revenue: (options = {}) => report("revenue", options),
         filterSales: (options = {}) => report("filter-sales", options),
-        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "GET", undefined, options.signal)
+        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "GET", undefined, options.signal),
+        abTest: (options = {}) => request("/analytics/ab-test", "GET", undefined, options.signal)
+      },
+      abTests: {
+        get: (signal) => request("/ab-tests", "GET", undefined, signal),
+        estimate: (options = {}) => request(`/ab-tests/estimate${options.share === undefined ? "" : `?share=${options.share}`}`, "GET", undefined, options.signal)
       },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),

package/dist/index.d.cts

@@ -539,6 +539,9 @@ export type SearchResponse<T> = {
         };
         /** A rule pinned it at its place (0.20.0). */
         pinned?: true;
+        /** With optimized images on (0.33.0): its image's placeholder, a ThumbHash in base64, for the browser SDK's
+         * `Image` (its `placeholder` prop) to show while the image loads. */
+        placeholder?: string;
     }[];
     /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
@@ -974,6 +977,80 @@ export type EventOptions = {
     signal?: AbortSignal;
     visitorId?: string;
     visitId?: string;
+    /** The shopper's group in the index's running A/B test (0.32.0): the `abTest` of the search answer their browser got,
+     * as `{ id, variant }` or `"<id>:<variant>"`, which the browser SDK sends with its own events. Your server's events
+     * count toward a group only with it, so send one shopper's events a call. A label for a test that ended is ignored. */
+    abTest?: AbTestLabel | string;
+};
+/** A shopper's group in an A/B test, as a browser search answer's `abTest` gives it: `a` searched with today's
+ * settings, `b` with the change (0.32.0). */
+export type AbTestLabel = {
+    id: string;
+    variant: "a" | "b";
+};
+/** One measure in an A/B test's results: each group's value per search (a share for `noResults` and `topThree`), and
+ * B's change over A (0.1 is 10% more) with its 95% interval. Null where there aren't the searches or days yet. */
+export type AbFigure = {
+    a: number | null;
+    b: number | null;
+    change: number | null;
+    low: number | null;
+    high: number | null;
+};
+/** An A/B test's results. `decided` once the test has run its days with 1,000 searches in each group; `verdict` is then
+ * `b` (the change did better), `a` (worse) or `none` (no clear difference), judged on clicks per search, then carts. */
+export type AbTestResults = {
+    days: number;
+    decided: boolean;
+    verdict: "a" | "b" | "none" | null;
+    searches: {
+        a: number;
+        b: number;
+    };
+    currency: string | null;
+    figures: Record<"noResults" | "clicks" | "topThree" | "carts" | "orders" | "revenue", AbFigure>;
+    perDay: {
+        day: string;
+        searches: {
+            a: number;
+            b: number;
+        };
+        clicks: {
+            a: number;
+            b: number;
+        };
+    }[];
+    computedAt: string;
+};
+/** An A/B test of an index's settings (0.32.0): group B's `share` of shoppers, the settings it `changes` and their values
+ * in `patch` (null where B goes without one), an A/A test (`aa`) changes none. `outcome` once ended: `a` kept today's
+ * settings, `b` applied the change, `guard` ended early because the change found nothing far more often. */
+export type AbTest = {
+    id: string;
+    name: string;
+    share: number;
+    changes: string[];
+    aa: boolean;
+    patch: Record<string, unknown>;
+    startedAt: string;
+    endsAt: string;
+    endedAt: string | null;
+    outcome: "a" | "b" | "guard" | null;
+    results: AbTestResults | null;
+};
+/** An index's A/B tests: the running one with its results so far, or null, and up to 10 that ended, newest first. */
+export type AbTests = {
+    running: AbTest | null;
+    ended: AbTest[];
+};
+/** What a test at a share would take: the days to find a 10% change in clicks per search (null with too few
+ * searches), from the index's searches and clicks per search over the last 14 days, and the share of searches more
+ * that would miss the cache. */
+export type AbTestEstimate = {
+    searchesPerDay: number;
+    clicksPerSearch: number;
+    days: number | null;
+    extraMisses: number;
 };
 /** 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
@@ -1464,6 +1541,29 @@ export declare class SearchServerClient {
                 range?: "7d" | "30d" | "90d";
                 signal?: AbortSignal;
             }) => Promise<BannerStatsReport>;
+            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+            abTest: (options?: {
+                signal?: AbortSignal;
+            }) => Promise<AbTests & {
+                index: string;
+            }>;
+        };
+        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+        abTests: {
+            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+            get: (signal?: AbortSignal) => Promise<AbTests & {
+                shares: number[];
+                days: {
+                    min: number;
+                    default: number;
+                    max: number;
+                };
+            }>;
+            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+            estimate: (options?: {
+                share?: number;
+                signal?: AbortSignal;
+            }) => Promise<AbTestEstimate>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
@@ -1672,6 +1772,29 @@ export declare class SearchServerClient {
                     range?: "7d" | "30d" | "90d";
                     signal?: AbortSignal;
                 }) => Promise<BannerStatsReport>;
+                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                abTest: (options?: {
+                    signal?: AbortSignal;
+                }) => Promise<AbTests & {
+                    index: string;
+                }>;
+            };
+            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+            abTests: {
+                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                get: (signal?: AbortSignal) => Promise<AbTests & {
+                    shares: number[];
+                    days: {
+                        min: number;
+                        default: number;
+                        max: number;
+                    };
+                }>;
+                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                estimate: (options?: {
+                    share?: number;
+                    signal?: AbortSignal;
+                }) => Promise<AbTestEstimate>;
             };
             upsert: (records: S[], signal?: AbortSignal) => Promise<WriteReceipt>;
             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S>>;
@@ -1878,6 +2001,29 @@ export declare class SearchServerClient {
                         range?: "7d" | "30d" | "90d";
                         signal?: AbortSignal;
                     }) => Promise<BannerStatsReport>;
+                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                    abTest: (options?: {
+                        signal?: AbortSignal;
+                    }) => Promise<AbTests & {
+                        index: string;
+                    }>;
+                };
+                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                abTests: {
+                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                        shares: number[];
+                        days: {
+                            min: number;
+                            default: number;
+                            max: number;
+                        };
+                    }>;
+                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                    estimate: (options?: {
+                        share?: number;
+                        signal?: AbortSignal;
+                    }) => Promise<AbTestEstimate>;
                 };
                 upsert: (records: S_1[], signal?: AbortSignal) => Promise<WriteReceipt>;
                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_1>>;
@@ -2084,6 +2230,29 @@ export declare class SearchServerClient {
                             range?: "7d" | "30d" | "90d";
                             signal?: AbortSignal;
                         }) => Promise<BannerStatsReport>;
+                        /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                        abTest: (options?: {
+                            signal?: AbortSignal;
+                        }) => Promise<AbTests & {
+                            index: string;
+                        }>;
+                    };
+                    /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                    abTests: {
+                        /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                        get: (signal?: AbortSignal) => Promise<AbTests & {
+                            shares: number[];
+                            days: {
+                                min: number;
+                                default: number;
+                                max: number;
+                            };
+                        }>;
+                        /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                        estimate: (options?: {
+                            share?: number;
+                            signal?: AbortSignal;
+                        }) => Promise<AbTestEstimate>;
                     };
                     upsert: (records: S_2[], signal?: AbortSignal) => Promise<WriteReceipt>;
                     getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_2>>;
@@ -2290,6 +2459,29 @@ export declare class SearchServerClient {
                                 range?: "7d" | "30d" | "90d";
                                 signal?: AbortSignal;
                             }) => Promise<BannerStatsReport>;
+                            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                            abTest: (options?: {
+                                signal?: AbortSignal;
+                            }) => Promise<AbTests & {
+                                index: string;
+                            }>;
+                        };
+                        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                        abTests: {
+                            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                            get: (signal?: AbortSignal) => Promise<AbTests & {
+                                shares: number[];
+                                days: {
+                                    min: number;
+                                    default: number;
+                                    max: number;
+                                };
+                            }>;
+                            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                            estimate: (options?: {
+                                share?: number;
+                                signal?: AbortSignal;
+                            }) => Promise<AbTestEstimate>;
                         };
                         upsert: (records: S_3[], signal?: AbortSignal) => Promise<WriteReceipt>;
                         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_3>>;
@@ -2496,6 +2688,29 @@ export declare class SearchServerClient {
                                     range?: "7d" | "30d" | "90d";
                                     signal?: AbortSignal;
                                 }) => Promise<BannerStatsReport>;
+                                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                abTest: (options?: {
+                                    signal?: AbortSignal;
+                                }) => Promise<AbTests & {
+                                    index: string;
+                                }>;
+                            };
+                            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                            abTests: {
+                                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                get: (signal?: AbortSignal) => Promise<AbTests & {
+                                    shares: number[];
+                                    days: {
+                                        min: number;
+                                        default: number;
+                                        max: number;
+                                    };
+                                }>;
+                                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                estimate: (options?: {
+                                    share?: number;
+                                    signal?: AbortSignal;
+                                }) => Promise<AbTestEstimate>;
                             };
                             upsert: (records: S_4[], signal?: AbortSignal) => Promise<WriteReceipt>;
                             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_4>>;
@@ -2702,6 +2917,29 @@ export declare class SearchServerClient {
                                         range?: "7d" | "30d" | "90d";
                                         signal?: AbortSignal;
                                     }) => Promise<BannerStatsReport>;
+                                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                    abTest: (options?: {
+                                        signal?: AbortSignal;
+                                    }) => Promise<AbTests & {
+                                        index: string;
+                                    }>;
+                                };
+                                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                abTests: {
+                                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                                        shares: number[];
+                                        days: {
+                                            min: number;
+                                            default: number;
+                                            max: number;
+                                        };
+                                    }>;
+                                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                    estimate: (options?: {
+                                        share?: number;
+                                        signal?: AbortSignal;
+                                    }) => Promise<AbTestEstimate>;
                                 };
                                 upsert: (records: S_5[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_5>>;
@@ -2908,6 +3146,29 @@ export declare class SearchServerClient {
                                             range?: "7d" | "30d" | "90d";
                                             signal?: AbortSignal;
                                         }) => Promise<BannerStatsReport>;
+                                        /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                        abTest: (options?: {
+                                            signal?: AbortSignal;
+                                        }) => Promise<AbTests & {
+                                            index: string;
+                                        }>;
+                                    };
+                                    /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                    abTests: {
+                                        /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                        get: (signal?: AbortSignal) => Promise<AbTests & {
+                                            shares: number[];
+                                            days: {
+                                                min: number;
+                                                default: number;
+                                                max: number;
+                                            };
+                                        }>;
+                                        /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                        estimate: (options?: {
+                                            share?: number;
+                                            signal?: AbortSignal;
+                                        }) => Promise<AbTestEstimate>;
                                     };
                                     upsert: (records: S_6[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                     getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_6>>;
@@ -3114,6 +3375,29 @@ export declare class SearchServerClient {
                                                 range?: "7d" | "30d" | "90d";
                                                 signal?: AbortSignal;
                                             }) => Promise<BannerStatsReport>;
+                                            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                            abTest: (options?: {
+                                                signal?: AbortSignal;
+                                            }) => Promise<AbTests & {
+                                                index: string;
+                                            }>;
+                                        };
+                                        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                        abTests: {
+                                            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                            get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                shares: number[];
+                                                days: {
+                                                    min: number;
+                                                    default: number;
+                                                    max: number;
+                                                };
+                                            }>;
+                                            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                            estimate: (options?: {
+                                                share?: number;
+                                                signal?: AbortSignal;
+                                            }) => Promise<AbTestEstimate>;
                                         };
                                         upsert: (records: S_7[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_7>>;
@@ -3320,6 +3604,29 @@ export declare class SearchServerClient {
                                                     range?: "7d" | "30d" | "90d";
                                                     signal?: AbortSignal;
                                                 }) => Promise<BannerStatsReport>;
+                                                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                                abTest: (options?: {
+                                                    signal?: AbortSignal;
+                                                }) => Promise<AbTests & {
+                                                    index: string;
+                                                }>;
+                                            };
+                                            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                            abTests: {
+                                                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                                get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                    shares: number[];
+                                                    days: {
+                                                        min: number;
+                                                        default: number;
+                                                        max: number;
+                                                    };
+                                                }>;
+                                                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                                estimate: (options?: {
+                                                    share?: number;
+                                                    signal?: AbortSignal;
+                                                }) => Promise<AbTestEstimate>;
                                             };
                                             upsert: (records: S_8[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_8>>;
@@ -3526,6 +3833,29 @@ export declare class SearchServerClient {
                                                         range?: "7d" | "30d" | "90d";
                                                         signal?: AbortSignal;
                                                     }) => Promise<BannerStatsReport>;
+                                                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                                    abTest: (options?: {
+                                                        signal?: AbortSignal;
+                                                    }) => Promise<AbTests & {
+                                                        index: string;
+                                                    }>;
+                                                };
+                                                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                                abTests: {
+                                                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                        shares: number[];
+                                                        days: {
+                                                            min: number;
+                                                            default: number;
+                                                            max: number;
+                                                        };
+                                                    }>;
+                                                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                                    estimate: (options?: {
+                                                        share?: number;
+                                                        signal?: AbortSignal;
+                                                    }) => Promise<AbTestEstimate>;
                                                 };
                                                 upsert: (records: S_9[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_9>>;

package/dist/index.d.ts

@@ -539,6 +539,9 @@ export type SearchResponse<T> = {
         };
         /** A rule pinned it at its place (0.20.0). */
         pinned?: true;
+        /** With optimized images on (0.33.0): its image's placeholder, a ThumbHash in base64, for the browser SDK's
+         * `Image` (its `placeholder` prop) to show while the image loads. */
+        placeholder?: string;
     }[];
     /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
@@ -974,6 +977,80 @@ export type EventOptions = {
     signal?: AbortSignal;
     visitorId?: string;
     visitId?: string;
+    /** The shopper's group in the index's running A/B test (0.32.0): the `abTest` of the search answer their browser got,
+     * as `{ id, variant }` or `"<id>:<variant>"`, which the browser SDK sends with its own events. Your server's events
+     * count toward a group only with it, so send one shopper's events a call. A label for a test that ended is ignored. */
+    abTest?: AbTestLabel | string;
+};
+/** A shopper's group in an A/B test, as a browser search answer's `abTest` gives it: `a` searched with today's
+ * settings, `b` with the change (0.32.0). */
+export type AbTestLabel = {
+    id: string;
+    variant: "a" | "b";
+};
+/** One measure in an A/B test's results: each group's value per search (a share for `noResults` and `topThree`), and
+ * B's change over A (0.1 is 10% more) with its 95% interval. Null where there aren't the searches or days yet. */
+export type AbFigure = {
+    a: number | null;
+    b: number | null;
+    change: number | null;
+    low: number | null;
+    high: number | null;
+};
+/** An A/B test's results. `decided` once the test has run its days with 1,000 searches in each group; `verdict` is then
+ * `b` (the change did better), `a` (worse) or `none` (no clear difference), judged on clicks per search, then carts. */
+export type AbTestResults = {
+    days: number;
+    decided: boolean;
+    verdict: "a" | "b" | "none" | null;
+    searches: {
+        a: number;
+        b: number;
+    };
+    currency: string | null;
+    figures: Record<"noResults" | "clicks" | "topThree" | "carts" | "orders" | "revenue", AbFigure>;
+    perDay: {
+        day: string;
+        searches: {
+            a: number;
+            b: number;
+        };
+        clicks: {
+            a: number;
+            b: number;
+        };
+    }[];
+    computedAt: string;
+};
+/** An A/B test of an index's settings (0.32.0): group B's `share` of shoppers, the settings it `changes` and their values
+ * in `patch` (null where B goes without one), an A/A test (`aa`) changes none. `outcome` once ended: `a` kept today's
+ * settings, `b` applied the change, `guard` ended early because the change found nothing far more often. */
+export type AbTest = {
+    id: string;
+    name: string;
+    share: number;
+    changes: string[];
+    aa: boolean;
+    patch: Record<string, unknown>;
+    startedAt: string;
+    endsAt: string;
+    endedAt: string | null;
+    outcome: "a" | "b" | "guard" | null;
+    results: AbTestResults | null;
+};
+/** An index's A/B tests: the running one with its results so far, or null, and up to 10 that ended, newest first. */
+export type AbTests = {
+    running: AbTest | null;
+    ended: AbTest[];
+};
+/** What a test at a share would take: the days to find a 10% change in clicks per search (null with too few
+ * searches), from the index's searches and clicks per search over the last 14 days, and the share of searches more
+ * that would miss the cache. */
+export type AbTestEstimate = {
+    searchesPerDay: number;
+    clicksPerSearch: number;
+    days: number | null;
+    extraMisses: number;
 };
 /** 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
@@ -1464,6 +1541,29 @@ export declare class SearchServerClient {
                 range?: "7d" | "30d" | "90d";
                 signal?: AbortSignal;
             }) => Promise<BannerStatsReport>;
+            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+            abTest: (options?: {
+                signal?: AbortSignal;
+            }) => Promise<AbTests & {
+                index: string;
+            }>;
+        };
+        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+        abTests: {
+            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+            get: (signal?: AbortSignal) => Promise<AbTests & {
+                shares: number[];
+                days: {
+                    min: number;
+                    default: number;
+                    max: number;
+                };
+            }>;
+            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+            estimate: (options?: {
+                share?: number;
+                signal?: AbortSignal;
+            }) => Promise<AbTestEstimate>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
@@ -1672,6 +1772,29 @@ export declare class SearchServerClient {
                     range?: "7d" | "30d" | "90d";
                     signal?: AbortSignal;
                 }) => Promise<BannerStatsReport>;
+                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                abTest: (options?: {
+                    signal?: AbortSignal;
+                }) => Promise<AbTests & {
+                    index: string;
+                }>;
+            };
+            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+            abTests: {
+                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                get: (signal?: AbortSignal) => Promise<AbTests & {
+                    shares: number[];
+                    days: {
+                        min: number;
+                        default: number;
+                        max: number;
+                    };
+                }>;
+                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                estimate: (options?: {
+                    share?: number;
+                    signal?: AbortSignal;
+                }) => Promise<AbTestEstimate>;
             };
             upsert: (records: S[], signal?: AbortSignal) => Promise<WriteReceipt>;
             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S>>;
@@ -1878,6 +2001,29 @@ export declare class SearchServerClient {
                         range?: "7d" | "30d" | "90d";
                         signal?: AbortSignal;
                     }) => Promise<BannerStatsReport>;
+                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                    abTest: (options?: {
+                        signal?: AbortSignal;
+                    }) => Promise<AbTests & {
+                        index: string;
+                    }>;
+                };
+                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                abTests: {
+                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                        shares: number[];
+                        days: {
+                            min: number;
+                            default: number;
+                            max: number;
+                        };
+                    }>;
+                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                    estimate: (options?: {
+                        share?: number;
+                        signal?: AbortSignal;
+                    }) => Promise<AbTestEstimate>;
                 };
                 upsert: (records: S_1[], signal?: AbortSignal) => Promise<WriteReceipt>;
                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_1>>;
@@ -2084,6 +2230,29 @@ export declare class SearchServerClient {
                             range?: "7d" | "30d" | "90d";
                             signal?: AbortSignal;
                         }) => Promise<BannerStatsReport>;
+                        /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                        abTest: (options?: {
+                            signal?: AbortSignal;
+                        }) => Promise<AbTests & {
+                            index: string;
+                        }>;
+                    };
+                    /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                    abTests: {
+                        /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                        get: (signal?: AbortSignal) => Promise<AbTests & {
+                            shares: number[];
+                            days: {
+                                min: number;
+                                default: number;
+                                max: number;
+                            };
+                        }>;
+                        /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                        estimate: (options?: {
+                            share?: number;
+                            signal?: AbortSignal;
+                        }) => Promise<AbTestEstimate>;
                     };
                     upsert: (records: S_2[], signal?: AbortSignal) => Promise<WriteReceipt>;
                     getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_2>>;
@@ -2290,6 +2459,29 @@ export declare class SearchServerClient {
                                 range?: "7d" | "30d" | "90d";
                                 signal?: AbortSignal;
                             }) => Promise<BannerStatsReport>;
+                            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                            abTest: (options?: {
+                                signal?: AbortSignal;
+                            }) => Promise<AbTests & {
+                                index: string;
+                            }>;
+                        };
+                        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                        abTests: {
+                            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                            get: (signal?: AbortSignal) => Promise<AbTests & {
+                                shares: number[];
+                                days: {
+                                    min: number;
+                                    default: number;
+                                    max: number;
+                                };
+                            }>;
+                            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                            estimate: (options?: {
+                                share?: number;
+                                signal?: AbortSignal;
+                            }) => Promise<AbTestEstimate>;
                         };
                         upsert: (records: S_3[], signal?: AbortSignal) => Promise<WriteReceipt>;
                         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_3>>;
@@ -2496,6 +2688,29 @@ export declare class SearchServerClient {
                                     range?: "7d" | "30d" | "90d";
                                     signal?: AbortSignal;
                                 }) => Promise<BannerStatsReport>;
+                                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                abTest: (options?: {
+                                    signal?: AbortSignal;
+                                }) => Promise<AbTests & {
+                                    index: string;
+                                }>;
+                            };
+                            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                            abTests: {
+                                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                get: (signal?: AbortSignal) => Promise<AbTests & {
+                                    shares: number[];
+                                    days: {
+                                        min: number;
+                                        default: number;
+                                        max: number;
+                                    };
+                                }>;
+                                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                estimate: (options?: {
+                                    share?: number;
+                                    signal?: AbortSignal;
+                                }) => Promise<AbTestEstimate>;
                             };
                             upsert: (records: S_4[], signal?: AbortSignal) => Promise<WriteReceipt>;
                             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_4>>;
@@ -2702,6 +2917,29 @@ export declare class SearchServerClient {
                                         range?: "7d" | "30d" | "90d";
                                         signal?: AbortSignal;
                                     }) => Promise<BannerStatsReport>;
+                                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                    abTest: (options?: {
+                                        signal?: AbortSignal;
+                                    }) => Promise<AbTests & {
+                                        index: string;
+                                    }>;
+                                };
+                                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                abTests: {
+                                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                                        shares: number[];
+                                        days: {
+                                            min: number;
+                                            default: number;
+                                            max: number;
+                                        };
+                                    }>;
+                                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                    estimate: (options?: {
+                                        share?: number;
+                                        signal?: AbortSignal;
+                                    }) => Promise<AbTestEstimate>;
                                 };
                                 upsert: (records: S_5[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_5>>;
@@ -2908,6 +3146,29 @@ export declare class SearchServerClient {
                                             range?: "7d" | "30d" | "90d";
                                             signal?: AbortSignal;
                                         }) => Promise<BannerStatsReport>;
+                                        /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                        abTest: (options?: {
+                                            signal?: AbortSignal;
+                                        }) => Promise<AbTests & {
+                                            index: string;
+                                        }>;
+                                    };
+                                    /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                    abTests: {
+                                        /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                        get: (signal?: AbortSignal) => Promise<AbTests & {
+                                            shares: number[];
+                                            days: {
+                                                min: number;
+                                                default: number;
+                                                max: number;
+                                            };
+                                        }>;
+                                        /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                        estimate: (options?: {
+                                            share?: number;
+                                            signal?: AbortSignal;
+                                        }) => Promise<AbTestEstimate>;
                                     };
                                     upsert: (records: S_6[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                     getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_6>>;
@@ -3114,6 +3375,29 @@ export declare class SearchServerClient {
                                                 range?: "7d" | "30d" | "90d";
                                                 signal?: AbortSignal;
                                             }) => Promise<BannerStatsReport>;
+                                            /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                            abTest: (options?: {
+                                                signal?: AbortSignal;
+                                            }) => Promise<AbTests & {
+                                                index: string;
+                                            }>;
+                                        };
+                                        /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                        abTests: {
+                                            /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                            get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                shares: number[];
+                                                days: {
+                                                    min: number;
+                                                    default: number;
+                                                    max: number;
+                                                };
+                                            }>;
+                                            /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                            estimate: (options?: {
+                                                share?: number;
+                                                signal?: AbortSignal;
+                                            }) => Promise<AbTestEstimate>;
                                         };
                                         upsert: (records: S_7[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_7>>;
@@ -3320,6 +3604,29 @@ export declare class SearchServerClient {
                                                     range?: "7d" | "30d" | "90d";
                                                     signal?: AbortSignal;
                                                 }) => Promise<BannerStatsReport>;
+                                                /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                                abTest: (options?: {
+                                                    signal?: AbortSignal;
+                                                }) => Promise<AbTests & {
+                                                    index: string;
+                                                }>;
+                                            };
+                                            /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                            abTests: {
+                                                /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                                get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                    shares: number[];
+                                                    days: {
+                                                        min: number;
+                                                        default: number;
+                                                        max: number;
+                                                    };
+                                                }>;
+                                                /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                                estimate: (options?: {
+                                                    share?: number;
+                                                    signal?: AbortSignal;
+                                                }) => Promise<AbTestEstimate>;
                                             };
                                             upsert: (records: S_8[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                             getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_8>>;
@@ -3526,6 +3833,29 @@ export declare class SearchServerClient {
                                                         range?: "7d" | "30d" | "90d";
                                                         signal?: AbortSignal;
                                                     }) => Promise<BannerStatsReport>;
+                                                    /** The index's A/B tests, as `abTests.get()` reads them with a search or write key (0.32.0). */
+                                                    abTest: (options?: {
+                                                        signal?: AbortSignal;
+                                                    }) => Promise<AbTests & {
+                                                        index: string;
+                                                    }>;
+                                                };
+                                                /** The index's A/B tests of its settings (0.32.0); owners start and end them in the dashboard, or through an agent. */
+                                                abTests: {
+                                                    /** The running test with its results so far, and those that ended; with the shares and days a test may take. */
+                                                    get: (signal?: AbortSignal) => Promise<AbTests & {
+                                                        shares: number[];
+                                                        days: {
+                                                            min: number;
+                                                            default: number;
+                                                            max: number;
+                                                        };
+                                                    }>;
+                                                    /** What a test would take at a `share` of shoppers in group B: 0.1 to 0.5, 0.5 by default. */
+                                                    estimate: (options?: {
+                                                        share?: number;
+                                                        signal?: AbortSignal;
+                                                    }) => Promise<AbTestEstimate>;
                                                 };
                                                 upsert: (records: S_9[], signal?: AbortSignal) => Promise<WriteReceipt>;
                                                 getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<S_9>>;

package/dist/index.js

@@ -194,7 +194,8 @@ class SearchServerClient {
       return jsonResponse(await response.text(), response.status, retryAfter ? { "retry-after": retryAfter } : {});
     };
     const sendEvents = async (events, options = {}) => {
-      const { signal, visitorId, visitId } = options;
+      const { signal, visitorId, visitId, abTest } = options;
+      const label = abTest === undefined || typeof abTest === "string" ? abTest : `${abTest.id}:${abTest.variant}`;
       const result = { accepted: 0, rejected: [] };
       let batch = [];
       let sent = 0;
@@ -204,6 +205,7 @@ class SearchServerClient {
         const answer = await postEvents({
           ...visitorId === undefined ? {} : { visitorId },
           ...visitId === undefined ? {} : { visitId },
+          ...label === undefined ? {} : { abTest: label },
           events: batch
         }, signal);
         result.accepted += answer.accepted ?? 0;
@@ -347,7 +349,12 @@ class SearchServerClient {
         product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
         revenue: (options = {}) => report("revenue", options),
         filterSales: (options = {}) => report("filter-sales", options),
-        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "GET", undefined, options.signal)
+        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "GET", undefined, options.signal),
+        abTest: (options = {}) => request("/analytics/ab-test", "GET", undefined, options.signal)
+      },
+      abTests: {
+        get: (signal) => request("/ab-tests", "GET", undefined, signal),
+        estimate: (options = {}) => request(`/ab-tests/estimate${options.share === undefined ? "" : `?share=${options.share}`}`, "GET", undefined, options.signal)
       },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),

package/package.json

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