@findlane/server 0.28.0 → 0.30.0

package/README.md

@@ -88,6 +88,23 @@ if (!failing.length) await products.replaceSettings({ ...(await products.getSett
 
 Only upload fields you intend to make public if browser search is enabled. `getPublicSearchAccess()` shows the current mode. `setPublicSearchPolicy({ returnFields, searchFields, filterFields, facetFields, sortIds, defaultSort })` restricts the index at the API, and `usePublicIndexDefaults()` removes the restrictions. Only a workspace owner can change allowed browser origins, in the dashboard.
 
+### Signed keys
+
+For a logged-in person's browser searches, sign a short-lived key with a signing key from the dashboard's API keys page. It makes no request, and its restrictions replace the index's public settings:
+
+```ts
+import { signSearchKey } from "@findlane/server"
+
+const signedKey = await signSearchKey(process.env.FINDLANE_SIGNING_KEY!, {
+  validUntil: new Date(Date.now() + 60 * 60 * 1000),
+  indexes: ["products"],
+  filters: { customerGroup: user.group },
+  userToken: user.id,
+})
+```
+
+The browser SDK takes it as `signedKey`. See [Logged-in visitors](https://findlane.dev/docs/security#logged-in-visitors).
+
 ## Errors
 
 Failed requests throw a `FindlaneError` with the HTTP `status` and the API's message. A 402 means a plan limit, such as records or monthly searches. `replaceAllStaged` throws a `StagedReplacementError` with the `stageId` to retry. Every method takes an optional `AbortSignal`.

package/dist/index.cjs

@@ -42,7 +42,8 @@ __export(exports_src, {
   FindlaneError: () => FindlaneError,
   SearchServerClient: () => SearchServerClient,
   StagedReplacementError: () => StagedReplacementError,
-  defaultBaseUrl: () => defaultBaseUrl
+  defaultBaseUrl: () => defaultBaseUrl,
+  signSearchKey: () => signSearchKey
 });
 module.exports = __toCommonJS(exports_src);
 function pause(ms, signal) {
@@ -104,6 +105,41 @@ class FindlaneError extends Error {
     this.name = "FindlaneError";
   }
 }
+var signingKeyPattern = /^ssk_[A-Za-z0-9_-]{43}$/;
+async function signSearchKey(signingKey, restrictions) {
+  if (!signingKeyPattern.test(signingKey))
+    throw new Error("A signing key (ssk_…) is required");
+  const { validUntil: until, indexes, filters, returnFields, userToken, restrictSources, referers } = restrictions;
+  const validUntil = until instanceof Date ? Math.floor(until.getTime() / 1000) : until;
+  if (!Number.isSafeInteger(validUntil))
+    throw new Error("validUntil must be a Date or a Unix time in seconds");
+  if (validUntil > Date.now() / 1000 + 7 * 86400 + 60)
+    throw new Error("A signed key lasts 7 days at most");
+  if (userToken !== undefined && (!userToken || userToken.length > 128))
+    throw new Error("userToken must be 1 to 128 characters");
+  for (const [name, list] of Object.entries({ indexes, returnFields, restrictSources, referers }))
+    if (list !== undefined && (!list.length || list.some((item) => typeof item != "string" || !item || item.includes(","))))
+      throw new Error(`${name} must list one or more names without commas`);
+  const values = {
+    validUntil,
+    restrictIndices: indexes,
+    filters: filters && JSON.stringify(filters),
+    returnFields,
+    userToken,
+    restrictSources,
+    referers
+  };
+  const params = Object.keys(values).filter((key) => values[key] !== undefined).sort().map((key) => {
+    const value = values[key];
+    return `${key}=${encodeURIComponent(Array.isArray(value) ? value.join(",") : String(value)).replace(/\+/g, "%20")}`;
+  }).join("&");
+  const nodeCrypto = "node:crypto";
+  const subtle = globalThis.crypto?.subtle ?? (await import(nodeCrypto)).webcrypto.subtle;
+  const encoder = new TextEncoder;
+  const key = await subtle.importKey("raw", encoder.encode(signingKey), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(params)));
+  return btoa([...mac].map((byte) => byte.toString(16).padStart(2, "0")).join("") + params);
+}
 var defaultBaseUrl = "https://api.findlane.dev";
 
 class SearchServerClient {
@@ -372,10 +408,10 @@ class SearchServerClient {
       replaceAllStaged: async (records, options = {}) => {
         const stageId = options.stageId ?? globalThis.crypto.randomUUID();
         const batchSize = options.batchSize ?? 500;
-        const maxBatchBytes = options.maxBatchBytes ?? 8 * 1024 * 1024;
+        const maxBatchBytes = options.maxBatchBytes ?? 8388608;
         if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1000)
           throw new RangeError("batchSize must be between 1 and 1,000");
-        if (!Number.isInteger(maxBatchBytes) || maxBatchBytes < 32 || maxBatchBytes > 32 * 1024 * 1024)
+        if (!Number.isInteger(maxBatchBytes) || maxBatchBytes < 32 || maxBatchBytes > 33554432)
           throw new RangeError("maxBatchBytes must be between 32 bytes and 32 MiB");
         try {
           const stage = await beginReplacement(stageId, options.signal);
@@ -431,7 +467,7 @@ class SearchServerClient {
       getSearchTests: async (signal) => (await request("/tests", "GET", undefined, signal)).tests,
       setSearchTests: async (tests, signal) => (await request("/tests", "PUT", { tests }, signal)).tests,
       waitForSettings: async (options = {}) => {
-        const deadline = Date.now() + (options.timeoutMs ?? 30 * 60000);
+        const deadline = Date.now() + (options.timeoutMs ?? 1800000);
         while (true) {
           options.signal?.throwIfAborted();
           const settings = await request("/config", "GET", undefined, options.signal);

package/dist/index.d.cts

@@ -59,6 +59,11 @@ export type IndexSettings = {
     rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
+    /** Icelandic word forms (0.30.0), with "is" among the languages: a query word of 4+ letters that no word
+     * of the index is or begins with also matches the other forms of its word from the BÍN dictionary
+     * ("kjólar" finds "Kjóll", "jokerinn" finds "Joker"), and a search that finds nothing tries every word's
+     * forms. Searches that find results with the words as typed don't change. Off by default. */
+    inflections?: boolean;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
      * search that finds nothing. Off by default. */
     didYouMean?: boolean;
@@ -437,7 +442,8 @@ export type GeoBox = {
     west: number;
 };
 /** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym,
- * as another form of the word in the index's languages (a plural or another spelling), or, with the
+ * as another form of the word in the index's languages (a plural or another spelling, or with `inflections`
+ * an Icelandic case or plural), or, with the
  * `compoundWords` setting, as a compound: its parts written apart, or the word it makes with a neighbouring
  * query word. */
 export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form" | "compound";
@@ -1232,6 +1238,33 @@ export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+/** What a signed key allows (signSearchKey). Every restriction but the expiry is optional. */
+export type SignedKeyRestrictions = {
+    /** When it stops working: a Date, or a Unix time in seconds. At most 7 days ahead. */
+    validUntil: Date | number;
+    /** The indexes it searches, by name, `*` matching any characters; every index its signing key signs for when
+     * left out. */
+    indexes?: string[];
+    /** Filters forced onto every search it makes, in the search API's form; the page's own filters apply as well. */
+    filters?: Record<string, unknown>;
+    /** The only fields its results return. */
+    returnFields?: string[];
+    /** The person it's for, such as a hash of your user ID (up to 128 characters): limits and the heavy-visitors
+     * list count them rather than their address. */
+    userToken?: string;
+    /** IP addresses or ranges (CIDR, such as 192.0.2.0/24) it works from. */
+    restrictSources?: string[];
+    /** The sites it works from: origins or host names, `*` matching any characters (`https://shop.example`,
+     * `*.shop.example`). */
+    referers?: string[];
+};
+/**
+ * A short-lived key for one person's browser searches (0.29.0), signed on your server with a signing key (ssk_…)
+ * from the API keys page; pass it to the browser SDK's `signedKey`. Its restrictions replace the index's public
+ * policy and allowed sites, so a catalog behind a login needs no browser search settings. Makes no request: sign
+ * one per person when they log in, or when their page asks. See findlane.dev/docs/security#logged-in-visitors.
+ */
+export declare function signSearchKey(signingKey: string, restrictions: SignedKeyRestrictions): Promise<string>;
 /** The hosted Findlane API, used unless `baseUrl` says otherwise. */
 export declare const defaultBaseUrl = "https://api.findlane.dev";
 export type ServerClientOptions = {

package/dist/index.d.ts

@@ -59,6 +59,11 @@ export type IndexSettings = {
     rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
+    /** Icelandic word forms (0.30.0), with "is" among the languages: a query word of 4+ letters that no word
+     * of the index is or begins with also matches the other forms of its word from the BÍN dictionary
+     * ("kjólar" finds "Kjóll", "jokerinn" finds "Joker"), and a search that finds nothing tries every word's
+     * forms. Searches that find results with the words as typed don't change. Off by default. */
+    inflections?: boolean;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
      * search that finds nothing. Off by default. */
     didYouMean?: boolean;
@@ -437,7 +442,8 @@ export type GeoBox = {
     west: number;
 };
 /** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym,
- * as another form of the word in the index's languages (a plural or another spelling), or, with the
+ * as another form of the word in the index's languages (a plural or another spelling, or with `inflections`
+ * an Icelandic case or plural), or, with the
  * `compoundWords` setting, as a compound: its parts written apart, or the word it makes with a neighbouring
  * query word. */
 export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form" | "compound";
@@ -1232,6 +1238,33 @@ export declare class FindlaneError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+/** What a signed key allows (signSearchKey). Every restriction but the expiry is optional. */
+export type SignedKeyRestrictions = {
+    /** When it stops working: a Date, or a Unix time in seconds. At most 7 days ahead. */
+    validUntil: Date | number;
+    /** The indexes it searches, by name, `*` matching any characters; every index its signing key signs for when
+     * left out. */
+    indexes?: string[];
+    /** Filters forced onto every search it makes, in the search API's form; the page's own filters apply as well. */
+    filters?: Record<string, unknown>;
+    /** The only fields its results return. */
+    returnFields?: string[];
+    /** The person it's for, such as a hash of your user ID (up to 128 characters): limits and the heavy-visitors
+     * list count them rather than their address. */
+    userToken?: string;
+    /** IP addresses or ranges (CIDR, such as 192.0.2.0/24) it works from. */
+    restrictSources?: string[];
+    /** The sites it works from: origins or host names, `*` matching any characters (`https://shop.example`,
+     * `*.shop.example`). */
+    referers?: string[];
+};
+/**
+ * A short-lived key for one person's browser searches (0.29.0), signed on your server with a signing key (ssk_…)
+ * from the API keys page; pass it to the browser SDK's `signedKey`. Its restrictions replace the index's public
+ * policy and allowed sites, so a catalog behind a login needs no browser search settings. Makes no request: sign
+ * one per person when they log in, or when their page asks. See findlane.dev/docs/security#logged-in-visitors.
+ */
+export declare function signSearchKey(signingKey: string, restrictions: SignedKeyRestrictions): Promise<string>;
 /** The hosted Findlane API, used unless `baseUrl` says otherwise. */
 export declare const defaultBaseUrl = "https://api.findlane.dev";
 export type ServerClientOptions = {

package/dist/index.js

@@ -58,6 +58,41 @@ class FindlaneError extends Error {
     this.name = "FindlaneError";
   }
 }
+var signingKeyPattern = /^ssk_[A-Za-z0-9_-]{43}$/;
+async function signSearchKey(signingKey, restrictions) {
+  if (!signingKeyPattern.test(signingKey))
+    throw new Error("A signing key (ssk_…) is required");
+  const { validUntil: until, indexes, filters, returnFields, userToken, restrictSources, referers } = restrictions;
+  const validUntil = until instanceof Date ? Math.floor(until.getTime() / 1000) : until;
+  if (!Number.isSafeInteger(validUntil))
+    throw new Error("validUntil must be a Date or a Unix time in seconds");
+  if (validUntil > Date.now() / 1000 + 7 * 86400 + 60)
+    throw new Error("A signed key lasts 7 days at most");
+  if (userToken !== undefined && (!userToken || userToken.length > 128))
+    throw new Error("userToken must be 1 to 128 characters");
+  for (const [name, list] of Object.entries({ indexes, returnFields, restrictSources, referers }))
+    if (list !== undefined && (!list.length || list.some((item) => typeof item != "string" || !item || item.includes(","))))
+      throw new Error(`${name} must list one or more names without commas`);
+  const values = {
+    validUntil,
+    restrictIndices: indexes,
+    filters: filters && JSON.stringify(filters),
+    returnFields,
+    userToken,
+    restrictSources,
+    referers
+  };
+  const params = Object.keys(values).filter((key) => values[key] !== undefined).sort().map((key) => {
+    const value = values[key];
+    return `${key}=${encodeURIComponent(Array.isArray(value) ? value.join(",") : String(value)).replace(/\+/g, "%20")}`;
+  }).join("&");
+  const nodeCrypto = "node:crypto";
+  const subtle = globalThis.crypto?.subtle ?? (await import(nodeCrypto)).webcrypto.subtle;
+  const encoder = new TextEncoder;
+  const key = await subtle.importKey("raw", encoder.encode(signingKey), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(params)));
+  return btoa([...mac].map((byte) => byte.toString(16).padStart(2, "0")).join("") + params);
+}
 var defaultBaseUrl = "https://api.findlane.dev";
 
 class SearchServerClient {
@@ -326,10 +361,10 @@ class SearchServerClient {
       replaceAllStaged: async (records, options = {}) => {
         const stageId = options.stageId ?? globalThis.crypto.randomUUID();
         const batchSize = options.batchSize ?? 500;
-        const maxBatchBytes = options.maxBatchBytes ?? 8 * 1024 * 1024;
+        const maxBatchBytes = options.maxBatchBytes ?? 8388608;
         if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1000)
           throw new RangeError("batchSize must be between 1 and 1,000");
-        if (!Number.isInteger(maxBatchBytes) || maxBatchBytes < 32 || maxBatchBytes > 32 * 1024 * 1024)
+        if (!Number.isInteger(maxBatchBytes) || maxBatchBytes < 32 || maxBatchBytes > 33554432)
           throw new RangeError("maxBatchBytes must be between 32 bytes and 32 MiB");
         try {
           const stage = await beginReplacement(stageId, options.signal);
@@ -385,7 +420,7 @@ class SearchServerClient {
       getSearchTests: async (signal) => (await request("/tests", "GET", undefined, signal)).tests,
       setSearchTests: async (tests, signal) => (await request("/tests", "PUT", { tests }, signal)).tests,
       waitForSettings: async (options = {}) => {
-        const deadline = Date.now() + (options.timeoutMs ?? 30 * 60000);
+        const deadline = Date.now() + (options.timeoutMs ?? 1800000);
         while (true) {
           options.signal?.throwIfAborted();
           const settings = await request("/config", "GET", undefined, options.signal);
@@ -426,5 +461,6 @@ export {
   FindlaneError,
   SearchServerClient,
   StagedReplacementError,
-  defaultBaseUrl
+  defaultBaseUrl,
+  signSearchKey
 };

package/package.json

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