@findlane/server 0.6.0 → 0.8.0

package/README.md

@@ -31,13 +31,23 @@ The workspace ID is under Settings in the dashboard, and keys are under API keys
 - `search`: `search()`.
 - `write`: record writes, settings, public search restrictions, and indexing status.
 
+## Searching for a visitor
+
+When your server searches for someone, such as a shopper loading a server-rendered search page, pass the visitor. The index's limits and bot rules then apply to them as they do to browser search, and searches from verified crawlers like Googlebot are free:
+
+```ts
+const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent: req.get("user-agent") } })
+```
+
+`suggest()` and `recommendations()` take the same option. Without it, a search counts as your server's own.
+
 ## An index's methods
 
 `client.index<T>(name)` returns these; `T` types your records, which each need a string `objectID`.
 
 | Method | What it does |
 | --- | --- |
-| `search(request)` | Search with a query, filters, facets, a sort, paging, and highlighting. |
+| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `options` takes `signal` and `visitor` (below). |
 | `upsert(records)` | Add or update up to 1,000 records by `objectID`. |
 | `replaceAll(records)` | Replace the whole catalog in one request (up to 100,000 records). |
 | `replaceAllStaged(records, options)` | Replace a larger catalog in batches under one stage ID, switched in one commit. Retrying with the same `stageId` resumes. `abortReplacement(stageId)` drops a stage. |

package/dist/index.cjs

@@ -67,6 +67,11 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+var visitorHeaders = (visitor) => visitor?.ip ? {
+  "findlane-visitor-ip": visitor.ip.trim(),
+  ...visitor.userAgent ? { "findlane-visitor-agent": visitor.userAgent.replace(/[^\x20-\x7e]/g, "").slice(0, 512) } : {}
+} : {};
 
 class FindlaneError extends Error {
   status;
@@ -93,12 +98,13 @@ class SearchServerClient {
   }
   index(name) {
     const path = `/api/teams/${encodeURIComponent(this.workspaceId)}/indexes/${encodeURIComponent(name)}`;
-    const request = async (suffix, method = "GET", payload, signal) => {
+    const request = async (suffix, method = "GET", payload, signal, extra = {}) => {
       const response = await this.fetcher(this.baseUrl + path + suffix, {
         method,
         headers: {
           authorization: `Bearer ${this.key}`,
-          ...payload === undefined ? {} : { "content-type": "application/json" }
+          ...payload === undefined ? {} : { "content-type": "application/json" },
+          ...extra
         },
         body: payload === undefined ? undefined : JSON.stringify(payload),
         signal
@@ -142,8 +148,18 @@ class SearchServerClient {
       return retry(() => request("/record-writes", "POST", payload, options.signal), options.signal);
     };
     return {
-      search: (query = {}, signal) => request("/search", "POST", query, signal),
-      suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
+      search: (query = {}, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return request("/search", "POST", query, signal, visitorHeaders(visitor));
+      },
+      suggest: async (query, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
+      },
+      recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
+        const { signal, visitor } = requestOptions(requestOptionsOrSignal);
+        return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
+      },
       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

@@ -173,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. */
@@ -215,6 +240,20 @@ export declare class StagedReplacementError extends Error {
     stageId: string;
     constructor(stageId: string, cause: unknown);
 }
+/** The visitor a server searches for, such as a shopper loading a server-rendered search page. With it,
+ * the index's limits and bot rules apply to that visitor, as they do to browser search, and searches
+ * from verified crawlers like Googlebot are free. */
+export type Visitor = {
+    /** The visitor's IP address: on Express `req.ip`, on Next.js the first address in `x-forwarded-for`. */
+    ip: string;
+    /** The visitor's User-Agent header. */
+    userAgent?: string;
+};
+/** Options for a search, a suggestion, or recommendations. */
+export type RequestOptions = {
+    signal?: AbortSignal;
+    visitor?: Visitor;
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -237,12 +276,16 @@ export declare class SearchServerClient {
     index<T extends {
         objectID: string;
     } = JsonRecord>(name: string): {
-        /** Searches the index; the API key needs the `search` scope. */
-        search: <R = T>(query?: SearchRequest, signal?: AbortSignal) => Promise<SearchResponse<R>>;
+        /** Searches the index; the API key needs the `search` scope. Pass `{ visitor }` when searching for
+         * someone, such as a shopper loading a server-rendered page (see Visitor). */
+        search: <R = T>(query?: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<SearchResponse<R>>;
         /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the
          * 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>;
+        suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => 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, requestOptionsOrSignal?: AbortSignal | RequestOptions) => 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

@@ -173,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. */
@@ -215,6 +240,20 @@ export declare class StagedReplacementError extends Error {
     stageId: string;
     constructor(stageId: string, cause: unknown);
 }
+/** The visitor a server searches for, such as a shopper loading a server-rendered search page. With it,
+ * the index's limits and bot rules apply to that visitor, as they do to browser search, and searches
+ * from verified crawlers like Googlebot are free. */
+export type Visitor = {
+    /** The visitor's IP address: on Express `req.ip`, on Next.js the first address in `x-forwarded-for`. */
+    ip: string;
+    /** The visitor's User-Agent header. */
+    userAgent?: string;
+};
+/** Options for a search, a suggestion, or recommendations. */
+export type RequestOptions = {
+    signal?: AbortSignal;
+    visitor?: Visitor;
+};
 export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
@@ -237,12 +276,16 @@ export declare class SearchServerClient {
     index<T extends {
         objectID: string;
     } = JsonRecord>(name: string): {
-        /** Searches the index; the API key needs the `search` scope. */
-        search: <R = T>(query?: SearchRequest, signal?: AbortSignal) => Promise<SearchResponse<R>>;
+        /** Searches the index; the API key needs the `search` scope. Pass `{ visitor }` when searching for
+         * someone, such as a shopper loading a server-rendered page (see Visitor). */
+        search: <R = T>(query?: SearchRequest, options?: AbortSignal | RequestOptions) => Promise<SearchResponse<R>>;
         /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the
          * 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>;
+        suggest: (query: SearchRequest, options?: AbortSignal | RequestOptions) => 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, requestOptionsOrSignal?: AbortSignal | RequestOptions) => 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

@@ -21,6 +21,11 @@ class StagedReplacementError extends Error {
     this.name = "StagedReplacementError";
   }
 }
+var requestOptions = (value) => value === undefined ? {} : ("aborted" in value) ? { signal: value } : value;
+var visitorHeaders = (visitor) => visitor?.ip ? {
+  "findlane-visitor-ip": visitor.ip.trim(),
+  ...visitor.userAgent ? { "findlane-visitor-agent": visitor.userAgent.replace(/[^\x20-\x7e]/g, "").slice(0, 512) } : {}
+} : {};
 
 class FindlaneError extends Error {
   status;
@@ -47,12 +52,13 @@ class SearchServerClient {
   }
   index(name) {
     const path = `/api/teams/${encodeURIComponent(this.workspaceId)}/indexes/${encodeURIComponent(name)}`;
-    const request = async (suffix, method = "GET", payload, signal) => {
+    const request = async (suffix, method = "GET", payload, signal, extra = {}) => {
       const response = await this.fetcher(this.baseUrl + path + suffix, {
         method,
         headers: {
           authorization: `Bearer ${this.key}`,
-          ...payload === undefined ? {} : { "content-type": "application/json" }
+          ...payload === undefined ? {} : { "content-type": "application/json" },
+          ...extra
         },
         body: payload === undefined ? undefined : JSON.stringify(payload),
         signal
@@ -96,8 +102,18 @@ class SearchServerClient {
       return retry(() => request("/record-writes", "POST", payload, options.signal), options.signal);
     };
     return {
-      search: (query = {}, signal) => request("/search", "POST", query, signal),
-      suggest: async (query, signal) => (await request("/suggest", "POST", query, signal)).didYouMean,
+      search: (query = {}, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return request("/search", "POST", query, signal, visitorHeaders(visitor));
+      },
+      suggest: async (query, options) => {
+        const { signal, visitor } = requestOptions(options);
+        return (await request("/suggest", "POST", query, signal, visitorHeaders(visitor))).didYouMean;
+      },
+      recommendations: (objectID, options = {}, requestOptionsOrSignal) => {
+        const { signal, visitor } = requestOptions(requestOptionsOrSignal);
+        return request("/recommendations", "POST", { objectID, ...options }, signal, visitorHeaders(visitor));
+      },
       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.6.0",
+  "version": "0.8.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",