JavaScript and TypeScript SDK

Published package: @surrealdb/spectron — generated from Spectron’s OpenAPI specification with TypeScript types that track the server across releases.

Installation

npm install @surrealdb/spectron

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

Client construction

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

const client = createSpectronClient({
  baseUrl: process.env.SPECTRON_URL!,           // http://localhost:9090
  apiKey: process.env.SPECTRON_API_KEY!,
  contextId: process.env.SPECTRON_CONTEXT_ID!,
});

Requests send API-KEY: <secret> — not Authorization: Bearer.

Remember and recall

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

const hits = await client.query({
  query: "What is Alice's role?",
  limit: 10,
  scope: ["org=acme", "user=alice"],
});

const block = await client.context({
  query: "What is Alice's role?",
  limit: 10,
  scope: ["org=acme", "user=alice"],
});

Batch ingest:

await client.facts.createBatch({
  messages: [
    { role: "user", content: "I was promoted to CTO." },
    { role: "assistant", content: "Congratulations!" },
  ],
  scope: ["org=acme", "user=alice"],
  idempotencyKey: "thread-1",
});

Documents and chat

await client.documents.upload({ file: buffer, filename: "policy.pdf" });
await client.chat({ message: "Summarise Alice's role", scope: ["org=acme", "user=alice"] });

Vercel AI SDK adapter

npm install @surrealdb/spectron-vercel-ai

→ Vercel AI SDK

Reference

JavaScript SDK reference · REST API

Exported method names follow the generated client; use spectron-gen-spec and clients/typescript/generate.sh when developing Spectron itself.