@findlane/server 0.7.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,9 +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,
-      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
+      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

@@ -240,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);
@@ -262,15 +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, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
+        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

@@ -240,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);
@@ -262,15 +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, signal?: AbortSignal) => Promise<RecommendationsResponse<R>>;
+        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,9 +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,
-      recommendations: (objectID, options = {}, signal) => request("/recommendations", "POST", { objectID, ...options }, signal),
+      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.7.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",