@findlane/server 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -0,0 +1,240 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  FindlaneError: () => FindlaneError,
+  SearchServerClient: () => SearchServerClient,
+  StagedReplacementError: () => StagedReplacementError,
+  defaultBaseUrl: () => defaultBaseUrl
+});
+module.exports = __toCommonJS(exports_src);
+function pause(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+class StagedReplacementError extends Error {
+  stageId;
+  constructor(stageId, cause) {
+    super(`Staged replacement ${stageId} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.stageId = stageId;
+    this.name = "StagedReplacementError";
+  }
+}
+
+class FindlaneError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "FindlaneError";
+  }
+}
+var defaultBaseUrl = "https://api.findlane.dev";
+
+class SearchServerClient {
+  baseUrl;
+  workspaceId;
+  key;
+  fetcher;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "");
+    this.workspaceId = options.workspaceId;
+    this.key = options.apiKey;
+    this.fetcher = options.fetch ?? fetch;
+    if (!this.baseUrl || !this.workspaceId || !this.key)
+      throw new Error("workspaceId and apiKey are required");
+  }
+  index(name) {
+    const path = `/api/teams/${encodeURIComponent(this.workspaceId)}/indexes/${encodeURIComponent(name)}`;
+    const request = async (suffix, method = "GET", payload, signal) => {
+      const response = await this.fetcher(this.baseUrl + path + suffix, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.key}`,
+          ...payload === undefined ? {} : { "content-type": "application/json" }
+        },
+        body: payload === undefined ? undefined : JSON.stringify(payload),
+        signal
+      });
+      const data = await response.json();
+      if (!response.ok)
+        throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+      return data;
+    };
+    const retry = async (work, signal) => {
+      for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
+        try {
+          return await work();
+        } catch (error) {
+          if (attempt >= 3 || error instanceof FindlaneError && ![408, 429, 502, 503, 504].includes(error.status))
+            throw error;
+          await new Promise((resolve, reject) => {
+            const onAbort = () => {
+              clearTimeout(timer);
+              reject(signal?.reason);
+            };
+            const timer = setTimeout(() => {
+              signal?.removeEventListener("abort", onAbort);
+              resolve();
+            }, 100 * 2 ** attempt);
+            signal?.addEventListener("abort", onAbort, { once: true });
+          });
+        }
+      }
+    };
+    const stagePath = (stageId) => `/staged-replacements/${encodeURIComponent(stageId)}`;
+    const beginReplacement = (stageId, signal) => retry(() => request(stagePath(stageId), "POST", undefined, signal), signal);
+    const uploadReplacementBatch = (stageId, batchId, records, signal) => retry(() => request(`${stagePath(stageId)}/batches/${encodeURIComponent(batchId)}`, "POST", { records }, signal), signal);
+    const commitReplacement = (stageId, expectedBatches, expectedRecords, signal) => retry(() => request(`${stagePath(stageId)}/commit`, "POST", { expectedBatches, expectedRecords }, signal), signal);
+    const writeOne = (operation, objectID, record, options) => {
+      if (!Number.isSafeInteger(options.expectedVersion) || options.expectedVersion < 0)
+        throw new RangeError("expectedVersion must be a non-negative integer");
+      const idempotencyKey = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+      const payload = { operation, objectID, ...record === undefined ? {} : { record }, expectedVersion: options.expectedVersion, idempotencyKey };
+      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,
+      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),
+      deleteOne: (objectID, options) => writeOne("delete", objectID, undefined, options),
+      replaceAll: (records, signal) => request("/records", "PUT", { records }, signal),
+      beginReplacement,
+      uploadReplacementBatch,
+      commitReplacement,
+      abortReplacement: (stageId, signal) => retry(() => request(stagePath(stageId), "DELETE", undefined, signal), signal),
+      replaceAllStaged: async (records, options = {}) => {
+        const stageId = options.stageId ?? globalThis.crypto.randomUUID();
+        const batchSize = options.batchSize ?? 500;
+        const maxBatchBytes = options.maxBatchBytes ?? 8 * 1024 * 1024;
+        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)
+          throw new RangeError("maxBatchBytes must be between 32 bytes and 32 MiB");
+        try {
+          const stage = await beginReplacement(stageId, options.signal);
+          if (stage.status === "committed")
+            return { acceptedRevision: stage.acceptedRevision, recordCount: stage.recordCount, replaced: true };
+          if (stage.status !== "open")
+            throw new Error(`Stage is ${stage.status}`);
+          let batch = [];
+          let batchBytes = 14;
+          let batchCount = 0;
+          let recordCount = 0;
+          const upload = async () => {
+            if (batch.length === 0)
+              return;
+            await uploadReplacementBatch(stageId, String(batchCount), batch, options.signal);
+            recordCount += batch.length;
+            batchCount++;
+            batch = [];
+            batchBytes = 14;
+          };
+          for await (const record of records) {
+            options.signal?.throwIfAborted();
+            const recordBytes = new TextEncoder().encode(JSON.stringify(record)).byteLength;
+            if (recordBytes + 14 > maxBatchBytes)
+              throw new RangeError(`A record exceeds maxBatchBytes (${maxBatchBytes})`);
+            if (batch.length && (batch.length >= batchSize || batchBytes + recordBytes + 1 > maxBatchBytes))
+              await upload();
+            batch.push(record);
+            batchBytes += recordBytes + 1;
+          }
+          await upload();
+          return await commitReplacement(stageId, batchCount, recordCount, options.signal);
+        } catch (error) {
+          throw new StagedReplacementError(stageId, error);
+        }
+      },
+      delete: (objectID, signal) => request(`/records/${encodeURIComponent(objectID)}`, "DELETE", undefined, signal),
+      getSettings: (signal) => request("/config", "GET", undefined, signal),
+      replaceSettings: (settings, signal) => {
+        const { rebuild: _rebuild, rebuilt: _rebuilt, applied: _applied, ...body } = settings;
+        return request("/config", "PUT", body, signal);
+      },
+      waitForSettings: async (options = {}) => {
+        const deadline = Date.now() + (options.timeoutMs ?? 30 * 60000);
+        while (true) {
+          options.signal?.throwIfAborted();
+          const settings = await request("/config", "GET", undefined, options.signal);
+          if (settings.rebuild?.status === "failed")
+            throw new Error(`Settings rebuild failed: ${settings.rebuild.message}`);
+          if (!settings.rebuild)
+            return settings;
+          if (Date.now() >= deadline)
+            throw new Error("Timed out waiting for the settings rebuild");
+          await pause(Math.min(options.intervalMs ?? 1000, deadline - Date.now()), options.signal);
+        }
+      },
+      getPublicSearchAccess: (signal) => request("/public-access", "GET", undefined, signal),
+      setPublicSearchPolicy: (policy, signal) => request("/public-access/policy", "PUT", { policy }, signal),
+      usePublicIndexDefaults: (signal) => request("/public-access/policy", "DELETE", undefined, signal),
+      getIndexingStatus: (signal) => request("/indexing", "GET", undefined, signal),
+      waitUntilIndexed: async (revision, options = {}) => {
+        const deadline = Date.now() + (options.timeoutMs ?? 30000);
+        const interval = options.intervalMs ?? 100;
+        while (true) {
+          options.signal?.throwIfAborted();
+          const status = await request("/indexing", "GET", undefined, options.signal);
+          if (status.lastError)
+            throw new Error(status.lastError);
+          if (status.indexedRevision >= revision)
+            return status;
+          if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for revision ${revision}`);
+          await pause(Math.min(interval, deadline - Date.now()), options.signal);
+        }
+      }
+    };
+  }
+}

package/dist/index.d.cts

@@ -0,0 +1,243 @@
+export type JsonRecord = {
+    objectID: string;
+    [key: string]: unknown;
+};
+export type SortRule = {
+    field: string;
+    direction: "asc" | "desc";
+};
+export type SortOption = SortRule & {
+    id: string;
+    label: string;
+    thenBy: SortRule[];
+};
+export type IndexSettings = {
+    /** One to five fields, matched with their weight. */
+    searchableAttributes: {
+        field: string;
+        weight: number;
+    }[];
+    facetFields: string[];
+    filterFields?: string[];
+    typoTolerance: boolean;
+    sorts: SortOption[];
+    defaultSort: string;
+    /** Orders equally relevant results (within 10% of the best score) by up to three sort fields. */
+    customRanking?: SortRule[];
+    /** Groups of interchangeable words or phrases (up to four words each). */
+    synonyms?: string[][];
+    /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
+    languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
+    /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
+     * search that finds nothing. Off by default. */
+    didYouMean?: boolean;
+    normalizationProfile?: "default-v2" | "default-v1" | "icelandic-ascii-v1";
+    [key: string]: unknown;
+};
+/** A settings change running in the background (with the settings it applies), or the last one's
+ * failure. `kind` is "searchable" (new searchable fields filled in) or "rebuild" (a full copy). */
+export type SettingsRebuild = {
+    status: "running";
+    kind: "searchable" | "rebuild";
+    copied: number;
+    total: number;
+    startedAt: string;
+    updatedAt: string;
+    settings: IndexSettings;
+} | {
+    status: "failed";
+    code: number;
+    message: string;
+    finishedAt: string;
+    settings: IndexSettings;
+};
+/** The active settings, and a rebuild that will replace them (or the last one's failure). */
+export type CurrentSettings = IndexSettings & {
+    rebuild: SettingsRebuild | null;
+};
+/** How saved settings were applied: "none" (unchanged), "instant" (query-time settings, and removed
+ * or reordered searchable fields), "fields" (facet, filter, sort, and ranking fields filled in
+ * place), "searchable" (new searchable fields filled in, after any field changes), or "rebuild" (text
+ * normalization). The last two continue in the background when large:
+ * `rebuilt` is false and `rebuild` shows progress; searches use the previous settings until then. */
+export type SavedSettings = IndexSettings & {
+    applied: "none" | "instant" | "fields" | "searchable" | "rebuild";
+    rebuilt: boolean;
+    rebuild: SettingsRebuild | null;
+};
+export type PublicSearchPolicy = {
+    returnFields: string[];
+    searchFields: string[];
+    filterFields: string[];
+    facetFields: string[];
+    sortIds: string[];
+    defaultSort: string;
+};
+export type PublicSearchAccess = {
+    publicId: string;
+    allowedOrigins: string[];
+    policy: PublicSearchPolicy | null;
+};
+export type WriteReceipt = {
+    acceptedRevision: number;
+    recordCount: number;
+    recordVersion?: number;
+    [key: string]: unknown;
+};
+export type RecordSnapshot<T> = {
+    objectID: string;
+    version: number;
+    record: T | null;
+};
+export type SearchRequest = {
+    q?: string;
+    /** A sort ID from the index settings, or "relevance". */
+    sort?: string;
+    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    filters?: Record<string, unknown>;
+    facets?: string[];
+    /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
+     * keeps its other values, with counts, after one is chosen. */
+    disjunctiveFacets?: string[];
+    /** Number fields (up to eight) whose smallest and largest values across the matches to return in
+     * `facetStats`, such as a price slider's bounds. Each field's own filter is left out. */
+    facetStats?: string[];
+    limit?: number;
+    offset?: number;
+    attributesToRetrieve?: string[];
+    /** "page" (default) counts only the returned page when a query matches more; "exact" counts every match. */
+    countMode?: "page" | "exact";
+    /** "page" (default) counts facet values in the returned page; "exact" counts them across every match. */
+    facetMode?: "page" | "exact";
+    /** Mark the words the query matched in each hit's searchable fields: true for <mark> tags, or custom tags.
+     * Highlighted values are HTML-escaped, so they can be inserted as HTML. */
+    highlight?: boolean | {
+        preTag?: string;
+        postTag?: string;
+    };
+};
+export type SearchResponse<T> = {
+    hits: {
+        id: string;
+        score: number | null;
+        record: T;
+        /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
+        highlights?: Record<string, string | string[]>;
+    }[];
+    total: number;
+    /** "gte" when `total` is a lower bound (page count mode). */
+    totalRelation?: "eq" | "gte";
+    hasMore?: boolean;
+    facets: Record<string, Record<string, number>>;
+    /** With `facetStats`: each field's smallest and largest value across the matches, without the field's
+     * own filter. A field no match has is left out. */
+    facetStats?: Record<string, {
+        min: number;
+        max: number;
+    }>;
+    tookMs: number;
+    sort?: string;
+    /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
+     * results matched some words only by typo ("Showing results for …"), else null. */
+    didYouMean?: DidYouMean | null;
+};
+/** 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. */
+export type DidYouMean = {
+    q: string;
+    applied: boolean;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+};
+export type ConditionalWriteOptions = {
+    expectedVersion: number;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+};
+export type IndexingStatus = {
+    acceptedRevision: number;
+    indexedRevision: number;
+    lastError?: string | null;
+    [key: string]: unknown;
+};
+export type ReplacementStage = {
+    stageId: string;
+    status: "open" | "committed" | "aborted";
+    baseRevision: number;
+    recordCount: number;
+    batchCount: number;
+    acceptedRevision: number | null;
+};
+export type StagedReplaceOptions = {
+    stageId?: string;
+    /** Records per batch: 1–1,000 (default 500). */
+    batchSize?: number;
+    /** Bytes per batch request (default 8 MiB). */
+    maxBatchBytes?: number;
+    signal?: AbortSignal;
+};
+export declare class StagedReplacementError extends Error {
+    stageId: string;
+    constructor(stageId: string, cause: unknown);
+}
+export declare class FindlaneError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/** The hosted Findlane API, used unless `baseUrl` says otherwise. */
+export declare const defaultBaseUrl = "https://api.findlane.dev";
+export type ServerClientOptions = {
+    /** The API to call; defaults to the hosted Findlane API. */
+    baseUrl?: string;
+    workspaceId: string;
+    apiKey: string;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+};
+export declare class SearchServerClient {
+    private readonly baseUrl;
+    private readonly workspaceId;
+    private readonly key;
+    private readonly fetcher;
+    constructor(options: ServerClientOptions);
+    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>>;
+        /** 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>;
+        upsert: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
+        getRecord: (objectID: string, signal?: AbortSignal) => Promise<RecordSnapshot<T>>;
+        upsertOne: (record: T, options: ConditionalWriteOptions) => Promise<WriteReceipt>;
+        deleteOne: (objectID: string, options: ConditionalWriteOptions) => Promise<WriteReceipt>;
+        replaceAll: (records: T[], signal?: AbortSignal) => Promise<WriteReceipt>;
+        beginReplacement: (stageId: string, signal?: AbortSignal) => Promise<ReplacementStage>;
+        uploadReplacementBatch: (stageId: string, batchId: string, records: T[], signal?: AbortSignal) => Promise<ReplacementStage>;
+        commitReplacement: (stageId: string, expectedBatches: number, expectedRecords: number, signal?: AbortSignal) => Promise<WriteReceipt>;
+        abortReplacement: (stageId: string, signal?: AbortSignal) => Promise<ReplacementStage>;
+        replaceAllStaged: (records: Iterable<T> | AsyncIterable<T>, options?: StagedReplaceOptions) => Promise<WriteReceipt>;
+        delete: (objectID: string, signal?: AbortSignal) => Promise<WriteReceipt>;
+        getSettings: (signal?: AbortSignal) => Promise<CurrentSettings>;
+        replaceSettings: (settings: IndexSettings, signal?: AbortSignal) => Promise<SavedSettings>;
+        /** Waits until no settings rebuild is running; throws if it failed. */
+        waitForSettings: (options?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+            signal?: AbortSignal;
+        }) => Promise<CurrentSettings>;
+        getPublicSearchAccess: (signal?: AbortSignal) => Promise<PublicSearchAccess>;
+        setPublicSearchPolicy: (policy: PublicSearchPolicy, signal?: AbortSignal) => Promise<PublicSearchAccess>;
+        usePublicIndexDefaults: (signal?: AbortSignal) => Promise<PublicSearchAccess>;
+        getIndexingStatus: (signal?: AbortSignal) => Promise<IndexingStatus>;
+        waitUntilIndexed: (revision: number, options?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+            signal?: AbortSignal;
+        }) => Promise<IndexingStatus>;
+    };
+}

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@findlane/server",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",
   "homepage": "https://findlane.dev/docs/server-sdk",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
     },
     "./package.json": "./package.json"
   },
@@ -20,7 +21,7 @@
   "engines": { "node": ">=18" },
   "publishConfig": { "access": "public" },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --outdir=dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --outdir=dist && bun build src/index.ts --target=node --format=cjs --outfile=dist/index.cjs && tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
     "test": "bun test tests",
     "prepublishOnly": "bun run build && bun run test"
   }