@findlane/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dagur Leo Bergsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @findlane/server
+
+The Findlane server SDK: upload and update catalogs, manage index settings, and search, with a secret workspace API key. It runs wherever `fetch` does: Node.js 18+, Bun, Deno, and edge runtimes. Never bundle it, or its key, into browser code; use [`@findlane/browser`](https://www.npmjs.com/package/@findlane/browser) there.
+
+Docs: https://findlane.dev/docs/server-sdk
+
+## Install
+
+```sh
+npm install @findlane/server
+```
+
+## Quick start
+
+```ts
+import { SearchServerClient } from "@findlane/server"
+
+const client = new SearchServerClient({
+  workspaceId: process.env.FINDLANE_WORKSPACE_ID!,
+  apiKey: process.env.FINDLANE_API_KEY!,
+})
+const products = client.index("products")
+
+await products.upsert([{ objectID: "sku-1", title: "Trail shoe", brand: { name: "Acme" }, price: 12900 }])
+const results = await products.search({ q: "trail shoe", limit: 10 })
+console.log(results.total, results.hits[0]?.record.title)
+```
+
+The workspace ID is under Settings in the dashboard, and keys are under API keys. A key has one or both scopes:
+
+- `search`: `search()`.
+- `write`: record writes, settings, public search restrictions, and indexing status.
+
+## 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. |
+| `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. |
+| `delete(objectID)` | Delete a record. |
+| `getRecord(objectID)` | A record and its version. |
+| `upsertOne(record, { expectedVersion })`, `deleteOne(objectID, { expectedVersion })` | Write only if the record is still at `expectedVersion` (0 for one that never existed); retried with one idempotency key. |
+| `getSettings()`, `replaceSettings(settings)`, `waitForSettings()` | Read and change searchable fields, facets, filters, sorts, custom ranking, synonyms, typo tolerance, and text normalization. |
+| `getIndexingStatus()`, `waitUntilIndexed(revision)` | Writes return an accepted revision and are searchable when accepted, so `waitUntilIndexed` returns at once. |
+| `getPublicSearchAccess()`, `setPublicSearchPolicy(policy)`, `usePublicIndexDefaults()` | Restrict what browser search may read and query. |
+
+### Settings
+
+`replaceSettings` sends the full settings; fetch them first to keep the other fields. Its `applied` says how the change took effect:
+
+- `instant`: query-time settings, and removing or reordering searchable fields.
+- `fields`: facet, filter, sort, and ranking fields, filled in place.
+- `searchable`: new searchable fields, filled in.
+- `rebuild`: text normalization; the index is rebuilt.
+
+A large `searchable` or `rebuild` change continues in the background, with its progress in `rebuild` (also returned by `getSettings`). Searches use the previous settings until it finishes, and `waitForSettings()` waits for it.
+
+### Browser search
+
+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.
+
+## 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`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+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[][];
+    normalizationProfile?: "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[];
+    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>>;
+    tookMs: number;
+    sort?: 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>>;
+        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/dist/index.js

@@ -0,0 +1,199 @@
+// src/index.ts
+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),
+      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);
+        }
+      }
+    };
+  }
+}
+export {
+  FindlaneError,
+  SearchServerClient,
+  StagedReplacementError,
+  defaultBaseUrl
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@findlane/server",
+  "version": "0.1.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",
+  "homepage": "https://findlane.dev/docs/server-sdk",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "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",
+    "test": "bun test tests",
+    "prepublishOnly": "bun run build && bun run test"
+  }
+}