SDK

JavaScript SDK

The @boltstore/client SDK provides a type-safe, promise-based interface to interact with your Boltstore databases. HTTP-only — no realtime, no offline sync, no client-side cache. Works in Node.js, Bun, Deno, and browsers.

Installation

# npm
npm install @boltstore/client
# yarn
yarn add @boltstore/client
# bun
bun install @boltstore/client

Initialization

import { BoltstoreClient } from '@boltstore/client';
const client = new BoltstoreClient({
url: 'http://localhost:8080',
database: 'my-app',
key: 'boltstore_...', // per-database API key, or admin session token
});
// Update the key later
client.setKey('boltstore_...');

The key is sent as Authorization: Bearer <key> on every request. Use a per-database API key for data access, or an admin session token (from POST /api/admin/login) for admin methods.

Tables

// List all tables
const tables = await client.tables.list();
// Create a table with column definitions
await client.tables.create('posts', [
{ name: 'id', type: 'integer', primary_key: true, auto_increment: true },
{ name: 'title', type: 'text', nullable: false },
{ name: 'views', type: 'integer', default: '0' },
]);
// Get table schema
const schema = await client.tables.get('posts');
// Rename, add/drop columns
await client.tables.update('posts', {
name: 'articles',
add_columns: [{ name: 'body', type: 'text' }],
});
// Drop a table
await client.tables.delete('articles');

Typed Records

const posts = client.table<{ id: number; title: string; views: number }>('posts');
// Create
const created = await posts.create({ title: 'Hello World', views: 0 });
// Get by ID
const fetched = await posts.get(created.id);
// Update
await posts.update(created.id, { views: 1 });
// Delete
await posts.delete(created.id);
// List with filter, sort, pagination
const result = await posts.list({
filter: { title: 'Hello' }, // exact match; use filter: { title__like: '%Hello%' } for pattern matching
sort: '-id',
limit: 10,
offset: 0,
});

Query Builder

const list = await posts
.query()
.where('title', 'like', 'Hello%')
.orWhere('views', 'gt', 100)
.orderBy('id', 'desc')
.limit(10)
.get();
// Select specific columns
const titles = await posts.query().select('id', 'title').get();
// Count rows (without fetching data)
const total = await posts.query().where('views', 'gt', 0).count();
// Get first match
const first = await posts.query().where('title', 'eq', 'Hello').first();
// Paginate
const page = await posts.query().paginate(1, 20);

Supported operators: eq, ne, gt, gte, lt, lte, in, like, glob.

Raw SQL

// Execute any SQL — SELECT, INSERT, UPDATE, DELETE, DDL, PRAGMA, etc.
const rows = await client.sql<{ id: number; title: string }>(
'SELECT id, title FROM posts WHERE views > ? ORDER BY id',
[0],
);

Database Operations

These methods accept either a per-database API key or an admin session token (except import and delete, which require admin):

// Database info / export
const info = await client.info();
const blob = await client.export();
// Per-database config
const config = await client.config.get();
await client.config.update({ cors_origins: ['https://myapp.com'] });
// API key management
const keys = await client.keys.list();
const newKey = await client.keys.create('Production Backend');
await client.keys.rotate(newKey.id);
await client.keys.revoke(newKey.id);
// Database deletion (admin only)
await client.delete();

Health Check

const health = await client.health();
// { status: "ok", version: "1.0.0", databases: 3 }

Authentication Model

The SDK holds a single key used for every request. Most methods (info, export, config.*, keys.*, tables.*, table(), sql()) accept either a per-database API key or an admin session token. Only import and delete require admin credentials.

Known Issues

• PaginatedResult.total may return current-page count. In rare cases where the server doesn't return a valid meta.total, the SDK falls back to the current page's row count. Usually the server returns the correct total; this only affects edge cases.