@findlane/server 0.21.0 → 0.23.0

package/dist/index.cjs

@@ -265,6 +265,32 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(requestOptionsOrSignal);
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
+      merchandising: {
+        list: async (signal) => (await request("/merchandising", "GET", undefined, signal)).arrangements,
+        get: (target, signal) => request(`/merchandising/arrangement?${new URLSearchParams(target)}`, "GET", undefined, signal),
+        set: (target, change, signal) => request("/merchandising/arrangement", "PUT", { ...target, ...change }, signal),
+        remove: (target, signal) => request(`/merchandising/arrangement?${new URLSearchParams(target)}`, "DELETE", undefined, signal)
+      },
+      images: {
+        list: (signal) => request("/images", "GET", undefined, signal),
+        upload: async (image, options = {}) => {
+          const response = await this.fetcher(`${this.baseUrl}${path}/images`, {
+            method: "POST",
+            signal: options.signal,
+            headers: {
+              authorization: `Bearer ${this.key}`,
+              "content-type": options.contentType ?? (image instanceof Blob && image.type ? image.type : "application/octet-stream")
+            },
+            body: image
+          });
+          const data = await response.json();
+          if (!response.ok)
+            throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+          return data;
+        },
+        uploadFromUrl: (url, signal) => request("/images", "POST", { url }, signal),
+        delete: (key, signal) => request(`/images/${key}`, "DELETE", undefined, signal)
+      },
       lists: {
         get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
         getMany: async (ids, options = {}) => {
@@ -319,7 +345,8 @@ class SearchServerClient {
         products: (options = {}) => report("products", options),
         productCounts: (options = {}) => report("product-counts", options),
         product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
-        revenue: (options = {}) => report("revenue", options)
+        revenue: (options = {}) => report("revenue", options),
+        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "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

@@ -745,6 +745,92 @@ export type ServerEvent = {
  | {
     type: "cancel";
     orderID: string;
+}
+/** A rule's banner was clicked: its rule, as search responses give it with the banner, the search's
+ * query, and its place. */
+ | {
+    type: "bannerClick";
+    rule: string;
+    query?: string;
+    position?: number;
+    timestamp?: number;
+};
+/** A category page (a facet field's value, without search words), or a search's exact words. */
+export type MerchandisingTarget = {
+    field: string;
+    value: string;
+} | {
+    q: string;
+};
+export type MerchandisingBanner = {
+    image: string;
+    link?: string;
+    title?: string;
+    position?: number;
+};
+/** How a category page or search is arranged, as the dashboard's Merchandising page arranges it. */
+export type Arrangement = {
+    target: MerchandisingTarget;
+    /** The rule that holds it; null when nothing is arranged. */
+    rule: string | null;
+    /** The products placed first, in order; null when the rule's pins have gaps, listed in `pins`. */
+    order: string[] | null;
+    pins: {
+        objectID: string;
+        position: number;
+    }[];
+    hidden: string[];
+    banner: MerchandisingBanner | null;
+    active: {
+        from?: string;
+        until?: string;
+    } | null;
+    enabled: boolean;
+    status: "live" | "scheduled" | "ended" | "off" | "none";
+};
+/** What to change: each field given replaces the current one; null clears the banner or the times. */
+export type ArrangementChange = {
+    order?: string[];
+    hidden?: string[];
+    banner?: MerchandisingBanner | null;
+    active?: {
+        from?: string;
+        until?: string;
+    } | null;
+    enabled?: boolean;
+};
+/** An image uploaded for the index's banners, hosted by Findlane, and the rules showing it. */
+export type UploadedImage = {
+    key: string;
+    url: string;
+    bytes: number;
+    contentType: string;
+    width: number | null;
+    height: number | null;
+    createdAt: string;
+    usedBy: string[];
+};
+export type ImageLibrary = {
+    images: UploadedImage[];
+    used: {
+        files: number;
+        bytes: number;
+    };
+    limits: {
+        fileBytes: number;
+        files: number;
+        bytes: number;
+    };
+};
+/** Each banner's shown and clicks by its rule; `analytics` says whether they could be read. */
+export type BannerStatsReport = {
+    days: number;
+    banners: {
+        rule: string;
+        shown: number;
+        clicks: number;
+    }[];
+    analytics: "ok" | "off" | "unavailable";
 };
 /** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
 export type Order = {
@@ -1039,6 +1125,39 @@ export declare class SearchServerClient {
         /** The index's lists: rows of products, such as Popular, and facet fields' values for menus, built ahead
          * and served from a cache, so reading them isn't counted as searches. Reading needs the `search` scope;
          * setting them up needs `write`. */
+        /** Merchandising (0.23.0): category pages and searches arranged as the dashboard's Merchandising page does:
+         * the products placed first, hidden products, a banner, and when. Saved as the page's rule within seconds,
+         * keeping anything else the rule does. Reading needs the `search` or `write` scope; changing, `write`. */
+        merchandising: {
+            /** Every arranged category page and search. */
+            list: (signal?: AbortSignal) => Promise<Arrangement[]>;
+            /** One page's or search's arrangement; status "none" when nothing is arranged. */
+            get: (target: MerchandisingTarget, signal?: AbortSignal) => Promise<Arrangement>;
+            /** Changes one: `order` up to 20 objectIDs placed first, `hidden` up to 100, `banner` ({ image, link?, title?,
+             * position? } or null), `active` ({ from?, until? } or null), `enabled`. Fields left out stay as they are. */
+            set: (target: MerchandisingTarget, change: ArrangementChange, signal?: AbortSignal) => Promise<Arrangement>;
+            /** Stops arranging one: its order, hidden products and banner go; the rule's other actions stay. */
+            remove: (target: MerchandisingTarget, signal?: AbortSignal) => Promise<Arrangement>;
+        };
+        /** Images for the index's banners, hosted by Findlane at https://images.findlane.dev (0.23.0): JPEG, PNG,
+         * WebP or AVIF, up to 2 MB each, 50 images and 100 MB an index. An image no rule shows is deleted a week
+         * later. Uploading and deleting need the `write` scope. */
+        images: {
+            list: (signal?: AbortSignal) => Promise<ImageLibrary>;
+            /** Uploads an image's bytes; the same image again gives the same URL. */
+            upload: (image: Blob | ArrayBuffer | Uint8Array, options?: {
+                contentType?: string;
+                signal?: AbortSignal;
+            }) => Promise<UploadedImage & {
+                error?: string;
+            }>;
+            /** Uploads the image at an https address, which Findlane fetches. */
+            uploadFromUrl: (url: string, signal?: AbortSignal) => Promise<UploadedImage>;
+            /** Deletes an image by its key; refused (409) while a rule's banner shows it. */
+            delete: (key: string, signal?: AbortSignal) => Promise<{
+                deleted: true;
+            }>;
+        };
         lists: {
             /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
             get: <R = T>(id: string, options?: {
@@ -1127,6 +1246,12 @@ export declare class SearchServerClient {
             /** 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>;
+            /** Each banner's shown (shoppers' searches that showed it, cache answers included) and clicks, by its rule,
+             * over the last 7, 30 (by default) or 90 days (0.23.0). */
+            banners: (options?: {
+                range?: "7d" | "30d" | "90d";
+                signal?: AbortSignal;
+            }) => Promise<BannerStatsReport>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.d.ts

@@ -745,6 +745,92 @@ export type ServerEvent = {
  | {
     type: "cancel";
     orderID: string;
+}
+/** A rule's banner was clicked: its rule, as search responses give it with the banner, the search's
+ * query, and its place. */
+ | {
+    type: "bannerClick";
+    rule: string;
+    query?: string;
+    position?: number;
+    timestamp?: number;
+};
+/** A category page (a facet field's value, without search words), or a search's exact words. */
+export type MerchandisingTarget = {
+    field: string;
+    value: string;
+} | {
+    q: string;
+};
+export type MerchandisingBanner = {
+    image: string;
+    link?: string;
+    title?: string;
+    position?: number;
+};
+/** How a category page or search is arranged, as the dashboard's Merchandising page arranges it. */
+export type Arrangement = {
+    target: MerchandisingTarget;
+    /** The rule that holds it; null when nothing is arranged. */
+    rule: string | null;
+    /** The products placed first, in order; null when the rule's pins have gaps, listed in `pins`. */
+    order: string[] | null;
+    pins: {
+        objectID: string;
+        position: number;
+    }[];
+    hidden: string[];
+    banner: MerchandisingBanner | null;
+    active: {
+        from?: string;
+        until?: string;
+    } | null;
+    enabled: boolean;
+    status: "live" | "scheduled" | "ended" | "off" | "none";
+};
+/** What to change: each field given replaces the current one; null clears the banner or the times. */
+export type ArrangementChange = {
+    order?: string[];
+    hidden?: string[];
+    banner?: MerchandisingBanner | null;
+    active?: {
+        from?: string;
+        until?: string;
+    } | null;
+    enabled?: boolean;
+};
+/** An image uploaded for the index's banners, hosted by Findlane, and the rules showing it. */
+export type UploadedImage = {
+    key: string;
+    url: string;
+    bytes: number;
+    contentType: string;
+    width: number | null;
+    height: number | null;
+    createdAt: string;
+    usedBy: string[];
+};
+export type ImageLibrary = {
+    images: UploadedImage[];
+    used: {
+        files: number;
+        bytes: number;
+    };
+    limits: {
+        fileBytes: number;
+        files: number;
+        bytes: number;
+    };
+};
+/** Each banner's shown and clicks by its rule; `analytics` says whether they could be read. */
+export type BannerStatsReport = {
+    days: number;
+    banners: {
+        rule: string;
+        shown: number;
+        clicks: number;
+    }[];
+    analytics: "ok" | "off" | "unavailable";
 };
 /** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
 export type Order = {
@@ -1039,6 +1125,39 @@ export declare class SearchServerClient {
         /** The index's lists: rows of products, such as Popular, and facet fields' values for menus, built ahead
          * and served from a cache, so reading them isn't counted as searches. Reading needs the `search` scope;
          * setting them up needs `write`. */
+        /** Merchandising (0.23.0): category pages and searches arranged as the dashboard's Merchandising page does:
+         * the products placed first, hidden products, a banner, and when. Saved as the page's rule within seconds,
+         * keeping anything else the rule does. Reading needs the `search` or `write` scope; changing, `write`. */
+        merchandising: {
+            /** Every arranged category page and search. */
+            list: (signal?: AbortSignal) => Promise<Arrangement[]>;
+            /** One page's or search's arrangement; status "none" when nothing is arranged. */
+            get: (target: MerchandisingTarget, signal?: AbortSignal) => Promise<Arrangement>;
+            /** Changes one: `order` up to 20 objectIDs placed first, `hidden` up to 100, `banner` ({ image, link?, title?,
+             * position? } or null), `active` ({ from?, until? } or null), `enabled`. Fields left out stay as they are. */
+            set: (target: MerchandisingTarget, change: ArrangementChange, signal?: AbortSignal) => Promise<Arrangement>;
+            /** Stops arranging one: its order, hidden products and banner go; the rule's other actions stay. */
+            remove: (target: MerchandisingTarget, signal?: AbortSignal) => Promise<Arrangement>;
+        };
+        /** Images for the index's banners, hosted by Findlane at https://images.findlane.dev (0.23.0): JPEG, PNG,
+         * WebP or AVIF, up to 2 MB each, 50 images and 100 MB an index. An image no rule shows is deleted a week
+         * later. Uploading and deleting need the `write` scope. */
+        images: {
+            list: (signal?: AbortSignal) => Promise<ImageLibrary>;
+            /** Uploads an image's bytes; the same image again gives the same URL. */
+            upload: (image: Blob | ArrayBuffer | Uint8Array, options?: {
+                contentType?: string;
+                signal?: AbortSignal;
+            }) => Promise<UploadedImage & {
+                error?: string;
+            }>;
+            /** Uploads the image at an https address, which Findlane fetches. */
+            uploadFromUrl: (url: string, signal?: AbortSignal) => Promise<UploadedImage>;
+            /** Deletes an image by its key; refused (409) while a rule's banner shows it. */
+            delete: (key: string, signal?: AbortSignal) => Promise<{
+                deleted: true;
+            }>;
+        };
         lists: {
             /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
             get: <R = T>(id: string, options?: {
@@ -1127,6 +1246,12 @@ export declare class SearchServerClient {
             /** 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>;
+            /** Each banner's shown (shoppers' searches that showed it, cache answers included) and clicks, by its rule,
+             * over the last 7, 30 (by default) or 90 days (0.23.0). */
+            banners: (options?: {
+                range?: "7d" | "30d" | "90d";
+                signal?: AbortSignal;
+            }) => Promise<BannerStatsReport>;
         };
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;

package/dist/index.js

@@ -219,6 +219,32 @@ class SearchServerClient {
         const { signal, visitor } = requestOptions(requestOptionsOrSignal);
         return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
       },
+      merchandising: {
+        list: async (signal) => (await request("/merchandising", "GET", undefined, signal)).arrangements,
+        get: (target, signal) => request(`/merchandising/arrangement?${new URLSearchParams(target)}`, "GET", undefined, signal),
+        set: (target, change, signal) => request("/merchandising/arrangement", "PUT", { ...target, ...change }, signal),
+        remove: (target, signal) => request(`/merchandising/arrangement?${new URLSearchParams(target)}`, "DELETE", undefined, signal)
+      },
+      images: {
+        list: (signal) => request("/images", "GET", undefined, signal),
+        upload: async (image, options = {}) => {
+          const response = await this.fetcher(`${this.baseUrl}${path}/images`, {
+            method: "POST",
+            signal: options.signal,
+            headers: {
+              authorization: `Bearer ${this.key}`,
+              "content-type": options.contentType ?? (image instanceof Blob && image.type ? image.type : "application/octet-stream")
+            },
+            body: image
+          });
+          const data = await response.json();
+          if (!response.ok)
+            throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+          return data;
+        },
+        uploadFromUrl: (url, signal) => request("/images", "POST", { url }, signal),
+        delete: (key, signal) => request(`/images/${key}`, "DELETE", undefined, signal)
+      },
       lists: {
         get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
         getMany: async (ids, options = {}) => {
@@ -273,7 +299,8 @@ class SearchServerClient {
         products: (options = {}) => report("products", options),
         productCounts: (options = {}) => report("product-counts", options),
         product: (objectID, options = {}) => report(`products/${encodeURIComponent(objectID)}`, options),
-        revenue: (options = {}) => report("revenue", options)
+        revenue: (options = {}) => report("revenue", options),
+        banners: (options = {}) => request(`/banners?range=${options.range ?? "30d"}`, "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.21.0",
+  "version": "0.23.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",