@findlane/server 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -318,7 +318,8 @@ class SearchServerClient {
         events: (options = {}) => report("events", options),
         products: (options = {}) => report("products", options),
         productCounts: (options = {}) => report("product-counts", options),
-        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options)
+        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
+        revenue: (options = {}) => report("revenue", options)
       },
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),

package/dist/index.d.cts

@@ -121,9 +121,11 @@ 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". */
+/** When a search meets a rule's `if`, the rule's `then` applies to that search: its words (one of the
+ * phrases), its filters (such as a category page's), the contexts it sends, and whether it has words; only
+ * between the rule's `active` times when it has them. 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". */
 export type QueryRule = {
     /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
     id: string;
@@ -131,25 +133,46 @@ export type QueryRule = {
     description?: string;
     /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
     enabled?: boolean;
+    /** Fires only from `from` and before `until`, ISO 8601 times with their zone, such as
+     * "2026-11-27T00:00:00Z"; either may be left out (0.20.0). */
+    active?: {
+        from?: string;
+        until?: string;
+    };
+    /** Every condition given must hold; with none, the rule fires on every search. */
     if: {
-        /** 1 to 20 phrases of one to four words. */
-        phrases: string[];
+        /** 1 to 20 phrases of one to four words. Reading settings returns [] for a rule without phrases. */
+        phrases?: string[];
         /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
         match?: "is" | "startsWith" | "contains";
+        /** The search filters each field (1 to 10 filter fields) to one of these values, alone or in an `in`
+         * list, as a category page filters its category (0.20.0). */
+        filters?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+        /** The search sends one of these contexts (its `context`), 1 to 10 names (0.20.0). */
+        context?: string[];
+        /** For a rule without phrases: only searches without words, such as a category page ("none"), or only
+         * with them ("some") (0.20.0). */
+        words?: "none" | "some";
     };
     /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
     then: {
         /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
          * Records without the field drop out, so `boost` is usually the better choice. */
         filters?: SearchRequest["filters"];
-        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
-         * sorted by relevance. Several rules' boosts add up. */
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches sorted by
+         * relevance, with words or without (0.20.0), but not named sorts or distance. Several rules' boosts add up. */
         boost?: SearchRequest["filters"];
         /** Records matching these come after the others, in the same searches as `boost`. */
         bury?: SearchRequest["filters"];
         /** Up to 100 objectIDs left out of the results. */
         hide?: string[];
-        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        /** 1 to 20 records at places from 1, on every sort, when they pass the search's filters (not necessarily its
+         * words); a later rule's pin at a taken place moves down (0.20.0). */
+        pin?: {
+            objectID: string;
+            position: number;
+        }[];
+        /** With phrases: words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
         replace?: string;
         /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
         userData?: unknown;
@@ -360,6 +383,17 @@ export type SearchRequest = {
     /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
      * records. */
     distinct?: boolean | number;
+    /** Contexts the page sends, which rules with a `context` condition fire on, such as "category-page": a
+     * name or up to 10, each 1 to 64 letters, digits, `_`, `:` or `-` (0.20.0). */
+    context?: string | string[];
+    /** Records matching these filters come first, after the index's rank first, in searches by relevance: filters as
+     * `filters` takes them, or a list of up to 10, each counting once, so records matching more come first (0.21.0). */
+    boost?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** Records matching these come last, the same way (0.21.0). */
+    bury?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** Checks rules as at this time, in milliseconds since 1970, such as a campaign's start, instead of now
+     * (0.20.0). Browser search doesn't take it. */
+    rulesAt?: number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -429,6 +463,14 @@ export type AppliedRule = {
     id: string;
     userData?: unknown;
 };
+/** A rule's banner: an image, where it links, its text, its place among the hits from 1, and the rule's ID. */
+export type Banner = {
+    image: string;
+    link?: string;
+    title?: string;
+    position?: number;
+    rule: string;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -452,6 +494,8 @@ export type SearchResponse<T> = {
         variant?: {
             index: number;
         };
+        /** A rule pinned it at its place (0.20.0). */
+        pinned?: true;
     }[];
     /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
@@ -481,6 +525,11 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** Banners of the rules that fired, in their order (0.21.0): show each at its `position` among the hits (from
+     * 1; the top when left out), linking to `link`. */
+    banners?: Banner[];
+    /** A page a rule sends this search to, such as "/pages/returns" (0.21.0): go there instead of showing results. */
+    redirect?: string;
     /** With the index's `relatedResults` on (0.18.0): when the query's words found nothing (`hits` empty,
      * `total` 0), the products closest to it in meaning, best first, with their similarity as `score`. Show
      * them under a heading of their own, such as "No exact matches. Related products". */
@@ -884,6 +933,65 @@ export type ProductReport = AnalyticsReport & {
         together: number;
     };
 };
+/** A query's search clicks, and the add-to-carts and orders of the products clicked, in the main currency.
+ * `searches` is its searches when it's one of the 1,000 most searched, else null. `typed`: shorter queries
+ * typed on the way to it, such as "perfor", whose clicks count here. */
+export type RevenueQuery = {
+    query: string;
+    searches: number | null;
+    clicks: number;
+    carts: number;
+    orders: number;
+    revenue: number;
+    typed: string[];
+};
+/** A product's orders and their value, beside those found through search, and the query it was found by most. */
+export type RevenueProduct = {
+    objectID: string;
+    title: string;
+    image: string | null;
+    orders: number;
+    revenue: number;
+    searchOrders: number;
+    searchRevenue: number;
+    topQuery: string | null;
+};
+/** Revenue from search (0.20.0): purchases and add-to-carts of products the shopper clicked in search results in
+ * the 24 hours before, by the same visitor ID, so it needs the index's visitor IDs on and purchases sent as
+ * events. Each order counts once; amounts are in the main `currency` (the most orders'), at the prices the
+ * events carry, and other currencies' orders are listed apart. Exact, from every event kept, like `products`. */
+export type RevenueReport = AnalyticsReport & {
+    computedAt: string;
+    currency: string | null;
+    orders: number;
+    revenue: number;
+    searchOrders: number;
+    searchRevenue: number;
+    carts: number;
+    cartValue: number;
+    searchCarts: number;
+    searchCartValue: number;
+    searchClicks: number;
+    otherCurrencies: {
+        currency: string;
+        orders: number;
+        revenue: number;
+        searchRevenue: number;
+    }[];
+    /** Orders and search clicks with visitor IDs, the first linked search click in the window, whether the
+     * index takes visitor IDs, and purchase lines without a price. */
+    coverage: {
+        linkedOrders: number;
+        linkedClicks: number;
+        linkedSince: string | null;
+        visitorIds: boolean;
+        unpricedLines: number;
+    };
+    /** The queries, the most revenue first, up to 100. */
+    queries: RevenueQuery[];
+    /** The products bought after a search, the most revenue from search first, up to 50. */
+    products: RevenueProduct[];
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -1016,6 +1124,9 @@ export declare class SearchServerClient {
             product: (objectID: string, options?: AnalyticsOptions & {
                 interval?: "hour" | "day";
             }) => Promise<ProductReport>;
+            /** Revenue from search: orders and add-to-carts of products found through search, per query and per
+             * product (0.20.0). */
+            revenue: (options?: Omit<AnalyticsOptions, "source">) => Promise<RevenueReport>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.d.ts

@@ -121,9 +121,11 @@ 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". */
+/** When a search meets a rule's `if`, the rule's `then` applies to that search: its words (one of the
+ * phrases), its filters (such as a category page's), the contexts it sends, and whether it has words; only
+ * between the rule's `active` times when it has them. 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". */
 export type QueryRule = {
     /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
     id: string;
@@ -131,25 +133,46 @@ export type QueryRule = {
     description?: string;
     /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
     enabled?: boolean;
+    /** Fires only from `from` and before `until`, ISO 8601 times with their zone, such as
+     * "2026-11-27T00:00:00Z"; either may be left out (0.20.0). */
+    active?: {
+        from?: string;
+        until?: string;
+    };
+    /** Every condition given must hold; with none, the rule fires on every search. */
     if: {
-        /** 1 to 20 phrases of one to four words. */
-        phrases: string[];
+        /** 1 to 20 phrases of one to four words. Reading settings returns [] for a rule without phrases. */
+        phrases?: string[];
         /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
         match?: "is" | "startsWith" | "contains";
+        /** The search filters each field (1 to 10 filter fields) to one of these values, alone or in an `in`
+         * list, as a category page filters its category (0.20.0). */
+        filters?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+        /** The search sends one of these contexts (its `context`), 1 to 10 names (0.20.0). */
+        context?: string[];
+        /** For a rule without phrases: only searches without words, such as a category page ("none"), or only
+         * with them ("some") (0.20.0). */
+        words?: "none" | "some";
     };
     /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
     then: {
         /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
          * Records without the field drop out, so `boost` is usually the better choice. */
         filters?: SearchRequest["filters"];
-        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
-         * sorted by relevance. Several rules' boosts add up. */
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches sorted by
+         * relevance, with words or without (0.20.0), but not named sorts or distance. Several rules' boosts add up. */
         boost?: SearchRequest["filters"];
         /** Records matching these come after the others, in the same searches as `boost`. */
         bury?: SearchRequest["filters"];
         /** Up to 100 objectIDs left out of the results. */
         hide?: string[];
-        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        /** 1 to 20 records at places from 1, on every sort, when they pass the search's filters (not necessarily its
+         * words); a later rule's pin at a taken place moves down (0.20.0). */
+        pin?: {
+            objectID: string;
+            position: number;
+        }[];
+        /** With phrases: words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
         replace?: string;
         /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
         userData?: unknown;
@@ -360,6 +383,17 @@ export type SearchRequest = {
     /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
      * records. */
     distinct?: boolean | number;
+    /** Contexts the page sends, which rules with a `context` condition fire on, such as "category-page": a
+     * name or up to 10, each 1 to 64 letters, digits, `_`, `:` or `-` (0.20.0). */
+    context?: string | string[];
+    /** Records matching these filters come first, after the index's rank first, in searches by relevance: filters as
+     * `filters` takes them, or a list of up to 10, each counting once, so records matching more come first (0.21.0). */
+    boost?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** Records matching these come last, the same way (0.21.0). */
+    bury?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** Checks rules as at this time, in milliseconds since 1970, such as a campaign's start, instead of now
+     * (0.20.0). Browser search doesn't take it. */
+    rulesAt?: number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -429,6 +463,14 @@ export type AppliedRule = {
     id: string;
     userData?: unknown;
 };
+/** A rule's banner: an image, where it links, its text, its place among the hits from 1, and the rule's ID. */
+export type Banner = {
+    image: string;
+    link?: string;
+    title?: string;
+    position?: number;
+    rule: string;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -452,6 +494,8 @@ export type SearchResponse<T> = {
         variant?: {
             index: number;
         };
+        /** A rule pinned it at its place (0.20.0). */
+        pinned?: true;
     }[];
     /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
@@ -481,6 +525,11 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** Banners of the rules that fired, in their order (0.21.0): show each at its `position` among the hits (from
+     * 1; the top when left out), linking to `link`. */
+    banners?: Banner[];
+    /** A page a rule sends this search to, such as "/pages/returns" (0.21.0): go there instead of showing results. */
+    redirect?: string;
     /** With the index's `relatedResults` on (0.18.0): when the query's words found nothing (`hits` empty,
      * `total` 0), the products closest to it in meaning, best first, with their similarity as `score`. Show
      * them under a heading of their own, such as "No exact matches. Related products". */
@@ -884,6 +933,65 @@ export type ProductReport = AnalyticsReport & {
         together: number;
     };
 };
+/** A query's search clicks, and the add-to-carts and orders of the products clicked, in the main currency.
+ * `searches` is its searches when it's one of the 1,000 most searched, else null. `typed`: shorter queries
+ * typed on the way to it, such as "perfor", whose clicks count here. */
+export type RevenueQuery = {
+    query: string;
+    searches: number | null;
+    clicks: number;
+    carts: number;
+    orders: number;
+    revenue: number;
+    typed: string[];
+};
+/** A product's orders and their value, beside those found through search, and the query it was found by most. */
+export type RevenueProduct = {
+    objectID: string;
+    title: string;
+    image: string | null;
+    orders: number;
+    revenue: number;
+    searchOrders: number;
+    searchRevenue: number;
+    topQuery: string | null;
+};
+/** Revenue from search (0.20.0): purchases and add-to-carts of products the shopper clicked in search results in
+ * the 24 hours before, by the same visitor ID, so it needs the index's visitor IDs on and purchases sent as
+ * events. Each order counts once; amounts are in the main `currency` (the most orders'), at the prices the
+ * events carry, and other currencies' orders are listed apart. Exact, from every event kept, like `products`. */
+export type RevenueReport = AnalyticsReport & {
+    computedAt: string;
+    currency: string | null;
+    orders: number;
+    revenue: number;
+    searchOrders: number;
+    searchRevenue: number;
+    carts: number;
+    cartValue: number;
+    searchCarts: number;
+    searchCartValue: number;
+    searchClicks: number;
+    otherCurrencies: {
+        currency: string;
+        orders: number;
+        revenue: number;
+        searchRevenue: number;
+    }[];
+    /** Orders and search clicks with visitor IDs, the first linked search click in the window, whether the
+     * index takes visitor IDs, and purchase lines without a price. */
+    coverage: {
+        linkedOrders: number;
+        linkedClicks: number;
+        linkedSince: string | null;
+        visitorIds: boolean;
+        unpricedLines: number;
+    };
+    /** The queries, the most revenue first, up to 100. */
+    queries: RevenueQuery[];
+    /** The products bought after a search, the most revenue from search first, up to 50. */
+    products: RevenueProduct[];
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -1016,6 +1124,9 @@ export declare class SearchServerClient {
             product: (objectID: string, options?: AnalyticsOptions & {
                 interval?: "hour" | "day";
             }) => Promise<ProductReport>;
+            /** Revenue from search: orders and add-to-carts of products found through search, per query and per
+             * product (0.20.0). */
+            revenue: (options?: Omit<AnalyticsOptions, "source">) => Promise<RevenueReport>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.js

@@ -272,7 +272,8 @@ class SearchServerClient {
         events: (options = {}) => report("events", options),
         products: (options = {}) => report("products", options),
         productCounts: (options = {}) => report("product-counts", options),
-        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options)
+        product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
+        revenue: (options = {}) => report("revenue", options)
       },
       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.19.0",
+  "version": "0.21.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",