@findlane/server 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -144,6 +144,7 @@ class SearchServerClient {
     return {
       search: (query = {}, signal) => request("/search", "POST", query, signal),
       suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
+      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),

package/dist/index.d.cts

@@ -34,6 +34,9 @@ export type IndexSettings = {
     normalizationProfile?: "default-v2" | "default-v1" | "icelandic-ascii-v1";
     /** An object field of lat and lng numbers, such as `_geoloc`, that `near` and `within` search; null for none. */
     locationField?: string | null;
+    /** When saving: types for fields no record has yet, so settings can come before the records. Records'
+     * types win once they have the field. Not returned when reading settings. */
+    fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
 /** A settings change running in the background (with the settings it applies), or the last one's
@@ -170,6 +173,31 @@ export type SearchResponse<T> = {
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
 };
+/** How a product's recommendations are served (the recommendations add-on). */
+export type RecommendationsRequest = {
+    /** Up to this many products in each list, 1 to 20; 8 by default. */
+    limit?: number;
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    filters?: SearchRequest["filters"];
+    /** The record fields to return; all of them by default. */
+    attributesToRetrieve?: string[];
+    /** Goes with picks cost at most this many times the product; null for no limit. By default, the index's setting. */
+    maxPriceRatio?: number | null;
+};
+export type RecommendationHit<T> = {
+    id: string;
+    score: number | null;
+    record: T;
+};
+export type RecommendationsResponse<T> = {
+    objectID: string;
+    /** false until the product's lists are built; both lists are empty meanwhile. */
+    ready: boolean;
+    /** Products a shopper would want with this one, the likeliest first; `score` is the decision model's probability. */
+    goesWith: RecommendationHit<T>[];
+    /** Products a shopper could choose instead, then (unless the index hides them) variants of this one. */
+    similar: RecommendationHit<T>[];
+};
 /** A corrected query. `applied`: the results are already for `q` (a search's "Showing results for");
  * otherwise searching `q` finds results that the query didn't ("Did you mean"). `changes` lists each
  * changed part of the query as typed. */
@@ -240,6 +268,9 @@ export declare class SearchServerClient {
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
         suggest: (query: SearchRequest, signal?: AbortSignal) => Promise<DidYouMean | null>;
+        /** A product's recommendations (the recommendations add-on): products that go with it, and similar products.
+         * The API key needs the `search` scope; not counted as a search. */
+        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;

package/dist/index.d.ts

@@ -34,6 +34,9 @@ export type IndexSettings = {
     normalizationProfile?: "default-v2" | "default-v1" | "icelandic-ascii-v1";
     /** An object field of lat and lng numbers, such as `_geoloc`, that `near` and `within` search; null for none. */
     locationField?: string | null;
+    /** When saving: types for fields no record has yet, so settings can come before the records. Records'
+     * types win once they have the field. Not returned when reading settings. */
+    fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
 /** A settings change running in the background (with the settings it applies), or the last one's
@@ -170,6 +173,31 @@ export type SearchResponse<T> = {
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
 };
+/** How a product's recommendations are served (the recommendations add-on). */
+export type RecommendationsRequest = {
+    /** Up to this many products in each list, 1 to 20; 8 by default. */
+    limit?: number;
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    filters?: SearchRequest["filters"];
+    /** The record fields to return; all of them by default. */
+    attributesToRetrieve?: string[];
+    /** Goes with picks cost at most this many times the product; null for no limit. By default, the index's setting. */
+    maxPriceRatio?: number | null;
+};
+export type RecommendationHit<T> = {
+    id: string;
+    score: number | null;
+    record: T;
+};
+export type RecommendationsResponse<T> = {
+    objectID: string;
+    /** false until the product's lists are built; both lists are empty meanwhile. */
+    ready: boolean;
+    /** Products a shopper would want with this one, the likeliest first; `score` is the decision model's probability. */
+    goesWith: RecommendationHit<T>[];
+    /** Products a shopper could choose instead, then (unless the index hides them) variants of this one. */
+    similar: RecommendationHit<T>[];
+};
 /** A corrected query. `applied`: the results are already for `q` (a search's "Showing results for");
  * otherwise searching `q` finds results that the query didn't ("Did you mean"). `changes` lists each
  * changed part of the query as typed. */
@@ -240,6 +268,9 @@ export declare class SearchServerClient {
          * same request (its q, filters, and fields matter). Needs the `didYouMean` setting; not counted as
          * a search. */
         suggest: (query: SearchRequest, signal?: AbortSignal) => Promise<DidYouMean | null>;
+        /** A product's recommendations (the recommendations add-on): products that go with it, and similar products.
+         * The API key needs the `search` scope; not counted as a search. */
+        recommendations: <R = T>(objectID: string, options?: RecommendationsRequest, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
         upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
         getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
         upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;

package/dist/index.js

@@ -98,6 +98,7 @@ class SearchServerClient {
     return {
       search: (query = {}, signal) => request("/search", "POST", query, signal),
       suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
+      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
       upsert: (records, signal) => request("/records", "POST", { records }, signal),
       getRecord: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "GET", undefined, signal),
       upsertOne: (record, options) => writeOne("upsert", record.objectID, record, options),

package/package.json

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