@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 there.

Docs: https://findlane.dev/docs/server-sdk

Install

npm install @findlane/server

Quick start

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.

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:

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.

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.

Before saving a change to rules, synonyms, typo tolerance, or ranking, compareSettings shows what it does, and {} runs the search tests with the current settings:

const comparison = await products.compareSettings({ rules: nextRules })
const failing = comparison.tests.filter((test) => test.before && !test.after)
if (!failing.length) await products.replaceSettings({ ...(await products.getSettings()), rules: nextRules })

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.

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:

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.

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