TypeScript SDK (@kalamdb/client + @kalamdb/consumer)

KalamDB’s TypeScript surface is now split into two packages with different responsibilities. The old single-package story no longer matches the published API.

Status: The TypeScript SDK is in beta. The two-package split and the method boundaries below are current, but minor surface changes can still happen between releases.

• npm: @kalamdb/client 
• npm: @kalamdb/consumer 

Package responsibilities

@kalamdb/consumer is additive. It keeps the same auth model and wraps the base @kalamdb/client SQL client internally, but adds a separate worker-focused WASM bundle and the topic-consumer APIs.

@kalamdb/client: app-facing SDK

Install only this package when you are building the app-facing side of your system.

@kalamdb/client owns:

• client construction with createClient({ url, authProvider })
• SQL over HTTP via query(), queryOne(), queryAll(), queryRows()
• per-user writes with executeAsUser()
• auth helpers and flows with Auth, login(), and refreshToken()
• realtime over the shared WebSocket with live(), liveTableRows(), subscribe(), subscribeWithSql(), and subscribeRows()
• FILE upload and parsing helpers such as queryWithFiles(), FileRef, parseFileRef(), and KalamCellValue

For application UI state, start with live(). It gives you the latest materialized row set directly, which is usually what a screen or component actually needs.

import { Auth, createClient } from '@kalamdb/client';
 
const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),
});
 
const inboxSql = `
  SELECT id, room, role, body, created_at
  FROM support.inbox
  WHERE room = 'main'
`;
 
const stop = await client.live(
  inboxSql,
  (rows) => {
    renderInbox(rows);
  },
  {
    subscriptionOptions: { last_rows: 50 },
  },
);
 
await stop();
await client.disconnect();

Important boundaries for @kalamdb/client:

• there is no public high-level connect() method on createClient() clients
• query() returns the raw QueryResponse
• queryOne() and queryAll() return RowData with KalamCellValue wrappers
• queryRows<T>() is the typed FILE-aware row helper when you want typed app objects plus .file() access
• live SQL for live() and subscribeWithSql() should stay in SELECT ... FROM ... WHERE ... form without ORDER BY or LIMIT

@kalamdb/consumer: worker and agent SDK

Install this package when you are running background workers or agents that consume topics.

@kalamdb/consumer owns:

• worker client construction with createConsumerClient({ url, authProvider })
• topic polling with consumeBatch()
• explicit offset commits with ack()
• continuous polling loops with consumer({...}).run(...)
• retry-aware runtimes with runAgent() and runConsumer()
• optional LLM adapter integration with createLangChainAdapter()

The consumer client also exposes the base SQL helpers you often need in workers: query(), queryOne(), queryAll(), executeAsUser(), login(), refreshToken(), and disconnect().

import { Auth } from '@kalamdb/client';
import { createConsumerClient } from '@kalamdb/consumer';
 
const worker = createConsumerClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('support-worker', 'Secret123!'),
});
 
const handle = worker.consumer({
  topic: 'support.inbox_events',
  group_id: 'support-summary-agent',
  auto_ack: true,
  batch_size: 10,
});
 
await handle.run(async (ctx) => {
  console.log(ctx.message.offset, ctx.message.value);
});

Use runAgent() or runConsumer() when you want the worker runtime to own retry, failure hooks, and ack timing. Use consumer().run() or consumeBatch() when you want explicit control.

Which package should you install?

1. Browser app, React app, Next.js app, or app server with SQL/realtime only: install @kalamdb/client.
2. Background worker or agent that consumes topics: install @kalamdb/client and @kalamdb/consumer.
3. Monorepo with both app and workers: keep the packages split in code too. Use createClient() in the app process and createConsumerClient() in the worker process.

Runtime targets

• @kalamdb/client: modern browsers and Node.js >= 18
• @kalamdb/consumer: worker-focused Node.js >= 18 runtimes, layered on top of @kalamdb/client

If your bundler or deployment cannot resolve WASM automatically, use:

• wasmUrl with @kalamdb/client
• consumerWasmUrl with @kalamdb/consumer

Recommended reading order

App client track (@kalamdb/client)

1. Setup & Quick Start
2. Authentication
3. Querying & DML
4. Realtime Subscriptions
5. FILE Columns & Uploads
6. Cell Values (KalamCellValue)
7. Client Lifecycle
8. Types & Enums

Worker track (@kalamdb/consumer)

1. Setup & Quick Start
2. Topic Consumers & ACK
3. Agent Runtime
4. Cookbook

Repository examples

If you want full working apps instead of docs-only snippets, start with the repo examples:

• examples/simple-typescript: compact browser subscription demo using @kalamdb/client
• examples/chat-with-ai: browser app with @kalamdb/client plus background worker with @kalamdb/consumer
• examples/summarizer-agent: worker-only enrichment flow with @kalamdb/consumer

Source-backed notes

• subscribe() returns an Unsubscribe function (Promise<() => Promise<void>>).
• live() and liveTableRows() return materialized row snapshots maintained by the shared Rust core.
• getSubscriptions() exposes typed lastSeqId checkpoints for resume flows.
• subscribeWithSql() remains the lower-level event API when you need raw ack, snapshot, or change frames.
• queryWithFiles() posts multipart directly to POST /v1/api/sql.
• @kalamdb/consumer uses /v1/api/topics/consume and /v1/api/topics/ack for topic polling and commits.