Transport & Endpoints
@kalamdb/client 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/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://localhost:8080HTTP 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() |
HTTP endpoints used by @kalamdb/consumer
| Method | Path | Used by |
|---|---|---|
POST | /v1/api/topics/consume | consumeBatch(), consumer().run(), runAgent(), runConsumer() |
POST | /v1/api/topics/ack | ack(), consumer().run(), runAgent(), runConsumer() |
WebSocket endpoint used by @kalamdb/client
| Method | Path | Used by |
|---|---|---|
GET | /v1/ws | internal shared-socket connection for subscribe, subscribeWithSql, subscribeRows, live, and liveTableRows |
@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 |
subscribe() / subscribeWithSql() | shared WebSocket subscription stream |
subscribeRows() | subscribe() plus local KalamChange / KalamRow wrapping |
live() / liveTableRows() | shared WebSocket live-row materialization |
disconnect() | closes the shared WebSocket |
shutdown() | disconnects, frees the WASM client, and resets SDK state |
@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() |
runAgent() / 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
subscribe(),subscribeWithSql(), orlive()call opens the shared WebSocket automatically. query()andqueryWithFiles()continue to run over HTTP.
@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.runAgent()andrunConsumer()keep ack timing in the worker runtime, not in the topic transport.
The high-level TypeScript app client does not expose a public connect() method. That method exists only on the low-level @kalamdb/client/wasm bindings.
References
Last updated on