Transport & Endpoints
@kalamdb/client, @kalamdb/orm, and @kalamdb/consumer share auth and SQL concepts, but they do not own the same transport surface.
@kalamdb/clientowns HTTP SQL, auth endpoints, and the shared WebSocket used for realtime queries.@kalamdb/ormlayers Drizzle schemas, table helpers, generated schema files, and table-level live helpers on top of@kalamdb/client.@kalamdb/consumerlayers topic polling and ACK APIs on top of the base client, using its own worker-focused WASM bundle.
Understanding that split helps when debugging networking, tracing, and deployment issues.
Base URL
HTTP endpoints used by @kalamdb/client
| Method | Path | Used by |
|---|---|---|
POST | /v1/api/sql | query, queryWithFiles, convenience DML helpers |
POST | /v1/api/auth/login | login() |
POST | /v1/api/auth/refresh | refreshToken() |
GET | /v1/files/{namespace}/{table}/{sub}/{stored_name} | FileRef.getDownloadUrl(), KalamCellValue.asFileUrl(), row.file(...).downloadUrl() |
FILE download helpers return owner-scoped URLs. For user tables, the server
allows the row owner to fetch the file directly; only dba and system roles
can append user_id for an authorized cross-user byte download.
HTTP endpoints used by @kalamdb/consumer
| Method | Path | Used by |
|---|---|---|
POST | /v1/api/topics/consume | consumeBatch(), consumer().run(), runConsumer() |
POST | /v1/api/topics/ack | ack(), consumer().run(), runConsumer() |
WebSocket endpoint used by @kalamdb/client
| Method | Path | Used by |
|---|---|---|
GET | /v1/ws | internal shared-socket connection for live, liveTable, and liveEvents |
@kalamdb/consumer does not add a second application-level WebSocket API. Its worker surface is topic-oriented and uses the topic HTTP endpoints.
@kalamdb/client method-to-transport mapping
| SDK method | Transport |
|---|---|
query() | WASM-backed HTTP call to POST /v1/api/sql |
queryWithFiles() | direct multipart HTTP POST /v1/api/sql |
queryOne() / queryAll() | wrapper over query() plus local KalamCellValue wrapping |
queryRows() | wrapper over query() plus local KalamRow / bound FILE helpers |
insert() / update() / delete() | SQL helper methods backed by POST /v1/api/sql |
executeAsUser() | SQL wrapper over query() |
login() | direct HTTP POST /v1/api/auth/login and in-memory auth upgrade to JWT |
refreshToken() | HTTP POST /v1/api/auth/refresh |
liveEvents() | shared WebSocket low-level live event stream |
live() / liveTable() | shared WebSocket live-row materialization |
connect() | explicitly opens or restores the shared WebSocket |
disconnect() | closes the shared WebSocket |
shutdown() | disconnects, frees the WASM client, and resets SDK state |
@kalamdb/orm method-to-transport mapping
| SDK method | Transport |
|---|---|
kalamDriver(client) query execution | delegated to the provided @kalamdb/client query() method |
generateSchema(client) | delegated to query('SHOW TABLES') and best-effort DESCRIBE <table> calls |
liveTable() | delegated to the provided @kalamdb/client live-row API |
file() / bytes() / embedding() | local Drizzle custom-column mapping only |
@kalamdb/consumer method-to-transport mapping
| SDK method | Transport |
|---|---|
query() / queryOne() / queryAll() | delegated to the internal @kalamdb/client SQL client |
executeAsUser() | delegated to the internal @kalamdb/client SQL client |
login() / refreshToken() | delegated to the internal @kalamdb/client auth flow |
consumeBatch() | HTTP POST /v1/api/topics/consume |
ack() | HTTP POST /v1/api/topics/ack |
consumer().run() | repeated consumeBatch() calls plus optional ack() |
runConsumer() | built on consumer().run() with retry and failure hooks |
disconnect() | clears topic auth cache and disconnects the internal base client |
Connection and auth flow
@kalamdb/client
- Create the client with
Auth.basic(...),Auth.jwt(...), orAuth.none()throughauthProvider. - The client initializes lazily on first use and resolves
authProvider. - Optional
login()exchanges basic credentials for JWT early. - The first
live(),liveTable(), orliveEvents()call opens the shared WebSocket automatically. query()andqueryWithFiles()continue to run over HTTP.
Connection lifecycle notes:
onConnect()fires when the shared realtime socket becomes healthy.onConnectionError()receives both WebSocket failures and pre-connect bootstrap failures such as invalid URLs, auth-provider errors, login failures, and refused connections.onError()remains supported as an alias for older code.
@kalamdb/consumer
- Create the worker client with the same
authProvidercontract. - Topic requests resolve auth on demand and build the correct
Authorizationheader. consumeBatch()andack()call the topic HTTP endpoints directly.runConsumer()keeps ack timing in the worker runtime, not in the topic transport.
Consumer lifecycle notes:
createConsumerClient()exposesonConnect()andonConnectionError()with worker-oriented connection metadata.runConsumer()exposes the same high-level connection lifecycle and delegates to the consumer client underneath, so the worker runtime and client do not drift into different error models.
The high-level TypeScript app client exposes connect() for eager connection and manual reconnect flows. Most applications can still rely on lazy WebSocket connection from the first live call.
References
Last updated on