SDK quick start

The official TypeScript SDK ships at @vaultbase/sdk. One client object exposes auth, records, files, realtime, batch, flags, and custom routes.

Install

bun add @vaultbase/sdk
# or
npm install @vaultbase/sdk

Works in Bun, Node 20+, Deno, Cloudflare Workers, and the browser.

Hello, Vaultbase

import { Vaultbase } from "@vaultbase/sdk";

const vb = new Vaultbase({ baseUrl: "https://api.example.com" });

// Records
const post = await vb.collection("posts").create({ title: "hi" });
const list = await vb.collection("posts").list({ filter: "published = true" });

// Auth
await vb.auth.users.login({ email: "a@b.c", password: "•••" });

// Realtime
const off = vb.subscribe("posts", "*", (ev) => console.log(ev.type, ev.record));
// off() to disconnect

// Files
const meta = await vb.files.upload("posts", post.id, "cover", file);

// Custom routes
const result = await vb.custom.get("/hello?name=world");

Constructor

new Vaultbase({
  baseUrl: "https://api.example.com",      // required — your Vaultbase URL
  authStore: defaultAuthStore(),           // sessionStorage in browsers, memory in Node
  authTransport: "header",                 // "header" | "cookie-only" — default "header"
  withCredentials: true,                   // send cookies on cross-origin (CORS) — default true
  defaultAutoCancel: false,                // derive a requestKey from method + path — default false
  fetch: globalThis.fetch,                 // override for custom fetch wrappers
});

Auth stores

The SDK persists the auth token in a pluggable store.

Store	Where the token lives	When to use
MemoryAuthStore	RAM only	Tests, server-rendering, short-lived workers
SessionStorageAuthStore	sessionStorage	Browser SPA — cleared on tab close (default)
LocalStorageAuthStore	localStorage	Browser SPA persisting across tabs (less safe)
CookieAuthStore	document.cookie	When you also want the server’s HttpOnly cookie to be the source of truth

import { Vaultbase, MemoryAuthStore } from "@vaultbase/sdk";

const vb = new Vaultbase({
  baseUrl: "https://api.example.com",
  authStore: new MemoryAuthStore(),
});

Typed schema (codegen)

Run vb-types against a live admin to generate a Schema from your collections. Pass it to the Vaultbase generic and every collection / filter / record becomes typed end-to-end. See Codegen + migrate CLI.

import type { Schema } from "./vaultbase.gen";
const vb = new Vaultbase<Schema>({ baseUrl: "..." });

const post = await vb.collection("posts").create({
  title: "hi",       // ✓ typed
  publishedAt: "x",  // ✗ TS error if 'publishedAt' isn't on Post['create']
});

API versioning

The SDK targets /api/v1/. Future breaking changes ship as /api/v2/, and a later SDK release will let you opt in. See API versioning.

Where next

• Example apps: complete apps on the SDK, starting with a todo list with sign-in, per-user rules and realtime

• Authentication — login, register, OAuth2, OTP, MFA

• Records — CRUD, list, filter, iterate, ETag concurrency

• Files — upload, URLs, protected tokens

• Realtime — WebSocket + SSE subscriptions

• Batch — atomic multi-op transactions

• Feature flags — typed flag client + React hooks

• Codegen + migrate CLI — vb-types, vb-flags, vb-migrate

• Errors + ETags — VaultbaseError shapes, optimistic concurrency