@findlane/browser 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,63 @@
+# @findlane/browser
+
+The Findlane browser SDK: fast, typo-tolerant search from the browser with an index's public ID. No dependencies, about 1 KB.
+
+Docs: https://findlane.dev/docs/browser-sdk
+
+## Install
+
+```sh
+npm install @findlane/browser
+```
+
+## Quick start
+
+```ts
+import { SearchBrowserClient } from "@findlane/browser"
+
+const client = new SearchBrowserClient({ publicId: "pub_your_public_index_id" })
+const results = await client.search({ q: "trail shoe", limit: 10, highlight: true })
+// results.hits[0].highlights?.title: "Trail <mark>shoe</mark>" (HTML-escaped, safe to insert as HTML)
+```
+
+Without a build step, load it with a script tag, which defines a global `Findlane`:
+
+```html
+<script src="https://cdn.findlane.dev/browser/0/findlane.min.js"></script>
+<script>
+  const client = new Findlane.SearchBrowserClient({ publicId: "pub_your_public_id" })
+</script>
+```
+
+Each index has a copyable public ID in the dashboard. An owner must save allowed origins for the index before browser search is enabled.
+
+## Search requests
+
+| Option | |
+| --- | --- |
+| `q` | The query. Words match with typos and as prefixes, depending on the index's settings. |
+| `filters` | Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. |
+| `facets` | Fields to count values for, such as `["brand.name"]`. |
+| `sort` | A sort ID from the index settings, or `"relevance"`. |
+| `limit`, `offset` | Paging: up to 50 hits a request, and offsets up to 1,000. |
+| `countMode`, `facetMode` | `"page"` (the default, fastest) or `"exact"` for totals and facet counts across every match. |
+| `highlight` | `true` to wrap matched words in `<mark>`, or `{ preTag, postTag }`. |
+| `attributesToRetrieve` | Return only these fields. |
+
+A response has `hits` (each with its `record` and any `highlights`), `total`, `facets`, and `tookMs`. Pass `{ signal }` as a second argument to cancel a request, as search-as-you-type should.
+
+## Security
+
+The public ID grants search access only to its index, and it is visible in browser source. By default the API returns every uploaded record field. `attributesToRetrieve` requests fewer fields for speed, but it does not make the others private. Origin checks constrain browsers; they do not authenticate other callers. Keep public catalog fields safe to expose. The dashboard can remove origins, add server-enforced restrictions, or rotate the ID.
+
+## Errors
+
+Failed requests throw a `FindlaneError` with the HTTP `status` and the API's message:
+
+- 403: this origin isn't allowed.
+- 429: the public search rate limit.
+- 402: the workspace has used its monthly searches.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+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[];
+    /** Hits per request: 1–50 (default 20). */
+    limit?: number;
+    /** Up to 1,000. */
+    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 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 BrowserClientOptions = {
+    /** The API to call; defaults to the hosted Findlane API. */
+    baseUrl?: string;
+    publicId: string;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+};
+export declare class SearchBrowserClient {
+    private readonly url;
+    private readonly fetcher;
+    constructor(options: BrowserClientOptions);
+    search<T = Record<string, unknown>>(request: SearchRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<SearchResponse<T>>;
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+// src/index.ts
+class FindlaneError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "FindlaneError";
+  }
+}
+var defaultBaseUrl = "https://api.findlane.dev";
+
+class SearchBrowserClient {
+  url;
+  fetcher;
+  constructor(options) {
+    if (!/^pub_[a-f0-9]{32}$/.test(options.publicId))
+      throw new Error("A valid public index ID (pub_…) is required");
+    this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}/search`;
+    this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+  async search(request, options = {}) {
+    const response = await this.fetcher(this.url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(request),
+      signal: options.signal
+    });
+    const data = await response.json();
+    if (!response.ok)
+      throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+    return data;
+  }
+}
+export {
+  FindlaneError,
+  SearchBrowserClient,
+  defaultBaseUrl
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@findlane/browser",
+  "version": "0.1.0",
+  "description": "Findlane browser SDK: fast, typo-tolerant public search from the browser with an index's public ID.",
+  "keywords": ["findlane", "search", "full-text search", "typo tolerance", "instant search", "ecommerce search", "browser"],
+  "license": "MIT",
+  "homepage": "https://findlane.dev/docs/browser-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,
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --target=browser --format=esm --outdir=dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build"
+  }
+}