JavaScript and TypeScript SDK

Published package: @surrealdb/spectron — a typed REST client for the Spectron end-user API. It uses platform fetch, ships no runtime dependencies, and aligns with Spectron’s OpenAPI specification.

npm: The client is published under the @surrealdb scope (@surrealdb/spectron), so no third party can squat the namespace. The bare name spectron on npm is unrelated.

Installation

npm install @surrealdb/spectron
# or: pnpm / yarn / bun add @surrealdb/spectron

Node.js 18+ or a modern bundler for browser use.

Client construction

import { Spectron } from "@surrealdb/spectron";

const client = new Spectron({
  endpoint: process.env.SPECTRON_ENDPOINT!,
  context: "acme-prod",
  apiKey: process.env.SPECTRON_API_KEY!,
});

The client is async-only (all methods return Promises). It is pinned to one context and calls /api/v1/{context}/….

Scope

On the wire, scope is a ScopeSet: an ordered array of slash-path strings (for example ["org/acme/user/alice"]). Register paths before first use — see Contexts and scope.

The TypeScript client accepts a path string or an array of paths — both serialise to the wire ScopeSet.

Remember and recall

await client.remember("Alice was promoted to CTO.", {
  infer: "full",
  scope: ["org/acme/user/alice"],
});

await client.rememberMany([
  { role: "user", content: "I was promoted to CTO." },
  { role: "assistant", content: "Congratulations!" },
], { scope: ["org/acme/user/alice"] });

const hits = await client.recall("What is Alice's role?", { k: 10 });

const block = await client.context("What is Alice's role?", { k: 10 });

remember and rememberMany attach an Idempotency-Key header for safe retries within a 30-second window.

Documents and chat

const doc = await client.documents.upload({
  file: documentFile,
  title: "Returns policy",
  scope: ["org/acme/team/eng"],
  labels: ["team=eng"],
});

await client.chat("Summarise what you know about Alice", {
  scope: ["user/alice"],
});

const stream = await client.chat("Tell me a story", { stream: true });
for await (const chunk of stream) {
  process.stdout.write(chunk.delta);
}

Other verbs and namespaces

Top-level: forget, consolidate, reflect, elaborate, state, profile, inspect, audit, fsck, health.

Namespaces: client.documents (including keywords), client.sessions, client.entities, client.scopes, client.principals, client.traces, client.lifecycle.

→ Full tables: JavaScript SDK reference

Vercel AI SDK adapter

npm install @surrealdb/spectron-vercel-ai

→ Vercel AI SDK

Reference

JavaScript SDK reference · REST API