@reddb-io/sdk 1.0.8 → 1.1.1

package/README.md

@@ -5,8 +5,9 @@ stdio to a local `red` binary, which is downloaded automatically on install.
 Works in **Node 18+**, **Bun** and **Deno** (via `npm:` specifier) — same
 package, no per-runtime fork.
 
-Use this package for application code. If you just want to launch the CLI from
-npm, use:
+Use this package when your application should run an embedded local RedDB
+engine. For remote HTTP, gRPC, or RedWire connections, install
+`@reddb-io/client` instead. If you just want to launch the CLI from npm, use:
 
 ```bash
 npx @reddb-io/cli@latest version
@@ -76,10 +77,9 @@ await db.close()
 |----------------------------|--------------------------------------|
 | `memory://`                | Ephemeral, in-memory database        |
 | `file:///absolute/path`    | Embedded engine, persisted to disk   |
-| `grpc://host:port`         | Remote server (planned, not yet)     |
 
-`grpc://` is not supported by the JS driver yet — the binary needs the
-`--connect` flag wired up first. See `PLAN_DRIVERS.md` in the repo root.
+Remote URIs such as `http://...`, `red://...`, and `grpc://...` are rejected
+with `EMBEDDED_ONLY`. Use `@reddb-io/client` for those transports.
 
 ## API
 
@@ -102,7 +102,38 @@ const persisted = await connect('file:///tmp/app.rdb')
 const custom = await connect('memory://', { binary: '/usr/local/bin/red' })
 ```
 
-### `db.query(sql) → Promise<{ statement, affected, columns, rows }>`
+### `db.query(sql, ...params) → Promise<{ statement, affected, columns, rows }>`
+
+Bind user values with `$1`, `$2`, ... placeholders. The variadic form is the
+preferred API; the older `db.query(sql, paramsArray)` form remains supported.
+
+```js
+const result = await db.query(
+  'SELECT * FROM users WHERE id = $1 AND name = $2',
+  42,
+  'Alice',
+)
+```
+
+`db.execute(sql, ...params)` is an alias for statements where the affected row
+count is the primary result.
+
+`ASK '...'` returns the ASK envelope directly:
+
+```js
+const answer = await db.query("ASK 'why did deploy fail?'")
+answer.answer
+answer.citations
+answer.sources_flat
+answer.validation
+answer.cache_hit
+answer.cost_usd
+```
+
+`ASK '...' STREAM` notifications are not wired over the JS stdio JSON-RPC
+client yet. Use the HTTP streaming API for incremental ASK frames; stdio
+currently supports materialised cursor batching through `query.open` /
+`query.next`, which is separate from ASK token streaming.
 
 ### `db.insert(collection, payload) → Promise<{ affected, id? }>`
 
@@ -179,9 +210,11 @@ bun test/smoke.test.mjs
 deno run -A test/smoke.test.mjs
 ```
 
-## Production deploy
+## Remote Deploy
 
-When you're ready to point this driver at a production RedDB cluster:
+When you're ready to point JavaScript code at a production RedDB cluster, use
+`@reddb-io/client`. The SDK package is embedded-only and intentionally rejects
+remote URIs.
 
 - **Run RedDB with the encrypted vault** so auth state and
   `red.secret.*` values are protected at rest. See
@@ -192,8 +225,7 @@ When you're ready to point this driver at a production RedDB cluster:
 - **Track every secret** the driver consumes (bearer tokens, mTLS
   cert + key, OAuth JWTs) in
   [`docs/operations/secrets.md`](../../docs/operations/secrets.md).
-- **Use `reds://` (TLS)** or `red://...?tls=true` for any traffic
-  crossing the network — never plain `red://` outside localhost.
+- **Use TLS** for any traffic crossing the network.
 - **TLS posture, mTLS, OAuth/JWT and reverse-proxy patterns** are
   covered in [`docs/security/transport-tls.md`](../../docs/security/transport-tls.md).
 - See [Policies](../../docs/security/policies.md) for IAM-style authorization.

package/index.d.ts

@@ -4,16 +4,6 @@
  * Hand-written, kept in sync with src/index.js.
  */
 
-/**
- * Authentication credentials. Only meaningful for `grpc://` URIs;
- * embedded modes (memory://, file://) inherit the caller's
- * filesystem privileges and reject auth options at the boundary.
- *
- * The shape is `{ token }` (or its `{ apiKey }` alias). For
- * username/password login, mint a token first via the standalone
- * `login(httpUrl, { username, password })` helper, then pass it
- * here — the gRPC surface does not currently bridge `auth.login`.
- */
 export type AuthOptions =
   | { token: string }
   | { apiKey: string }
@@ -35,13 +25,9 @@ export interface TlsOptions {
 export interface ConnectOptions {
   /** Override the path to the `red` binary (defaults to bundled). */
   binary?: string
-  /** Authentication credentials (grpc:// only). */
+  /** Rejected for embedded SDK connections; use @reddb-io/client remotely. */
   auth?: AuthOptions
-  /**
-   * TLS for `redwire(s)://` connections. URL params (`tls=true`,
-   * `cert=`, `key=`, `ca=`) feed the same field; this option
-   * always wins.
-   */
+  /** Reserved for remote clients; ignored by the embedded SDK. */
   tls?: TlsOptions
 }
 
@@ -52,14 +38,63 @@ export interface QueryResult {
   rows: Array<Record<string, unknown>>
 }
 
+export type QueryParam =
+  | null
+  | boolean
+  | number
+  | string
+  | Uint8Array
+  | Buffer
+  | Date
+  | Float32Array
+  | Float64Array
+  | number[]
+  | Record<string, unknown>
+
+export interface AskSource {
+  urn: string
+  payload: string
+}
+
+export interface AskCitation {
+  marker: number
+  urn: string
+}
+
+export interface AskValidationItem {
+  kind: string
+  detail: string
+}
+
+export interface AskValidation {
+  ok: boolean
+  warnings: AskValidationItem[]
+  errors: AskValidationItem[]
+}
+
+export interface AskQueryResult {
+  answer: string
+  cache_hit: boolean
+  citations: AskCitation[]
+  completion_tokens: number
+  cost_usd: number
+  mode: 'strict' | 'lenient'
+  model: string
+  prompt_tokens: number
+  provider: string
+  retry_count: number
+  sources_flat: AskSource[]
+  validation: AskValidation
+}
+
 export interface InsertResult {
   affected: number
-  /** Present when the underlying engine surfaces the inserted entity id. */
-  id?: string | number
+  id: string | number
 }
 
 export interface BulkInsertResult {
   affected: number
+  ids: Array<string | number>
 }
 
 export interface GetResult {
@@ -70,6 +105,13 @@ export interface DeleteResult {
   affected: number
 }
 
+export interface CollectionMeta {
+  name: string
+  model: string
+  capabilities: string[]
+  [key: string]: unknown
+}
+
 export interface HealthResult {
   ok: boolean
   version: string
@@ -144,6 +186,13 @@ export interface CacheInvalidateResult {
   removed: number
 }
 
+/**
+ * Cache client. Requires an HTTP or gRPC / RedWire transport — the
+ * underlying `cache.*` RPC methods are not served by the embedded
+ * (stdio JSON-RPC) handler. Calls on an unsupported transport throw
+ * `RedDBError` with code `UNSUPPORTED_TRANSPORT` before issuing any
+ * RPC.
+ */
 export class CacheClient {
   /** Fetch a cached value. Returns Uint8Array on hit, null on miss. */
   get(namespace: string, key: string): Promise<Uint8Array | null>
@@ -182,6 +231,8 @@ export class KvClient {
     value: unknown,
     options?: { collection?: string; expireMs?: number; tags?: string[] },
   ): Promise<QueryResult>
+  get(key: string, options?: { collection?: string }): Promise<unknown | null>
+  getMany(keys: string[], options?: { collection?: string }): Promise<Array<unknown | null>>
   invalidateTags(tags: string[], options?: { collection?: string }): Promise<number>
   watch(
     key: string,
@@ -193,6 +244,32 @@ export class KvClient {
   ): AsyncIterable<KvWatchEvent>
 }
 
+export class QueueClient {
+  push(
+    queue: string,
+    value: unknown,
+    options?: { priority?: number },
+  ): Promise<QueryResult>
+  pop(queue: string, count?: number): Promise<unknown[]>
+  peek(queue: string, count?: number): Promise<unknown[]>
+  len(queue: string): Promise<number>
+  purge(queue: string): Promise<QueryResult>
+}
+
+/**
+ * Caller-typed SELECT builder. RedDB does not infer `T`; provide it
+ * explicitly with `db.from<T>('collection')`.
+ */
+export class TypedQueryBuilder<T extends Record<string, unknown> = Record<string, unknown>> {
+  select(): TypedQueryBuilder<T>
+  select(column: '*'): TypedQueryBuilder<T>
+  select<K extends keyof T & string>(...columns: K[]): TypedQueryBuilder<Pick<T, K>>
+  select<K extends keyof T & string>(columns: K[]): TypedQueryBuilder<Pick<T, K>>
+  where(condition: string, params: QueryParam[]): TypedQueryBuilder<T>
+  where(condition: string, ...params: QueryParam[]): TypedQueryBuilder<T>
+  run(): Promise<T[]>
+}
+
 export class ConfigClient {
   put(
     key: string,
@@ -218,25 +295,42 @@ export class VaultClient {
 }
 
 export class RedDB {
+  /** Underlying transport label. connect() returns 'embedded'. */
+  readonly transport: string | null
   readonly cache: CacheClient
+  readonly queue: QueueClient
   readonly kv: KvClient & ((collection?: string) => KvClient)
   readonly config: (collection?: string) => ConfigClient
   readonly vault: (collection?: string) => VaultClient
 
+  query(sql: `ASK ${string}`): Promise<AskQueryResult>
   query(sql: string): Promise<QueryResult>
-  query(sql: string, params: Array<number | string | null>): Promise<QueryResult>
+  query(sql: string, params: QueryParam[]): Promise<QueryResult>
+  query(sql: string, ...params: QueryParam[]): Promise<QueryResult>
+  execute(sql: string): Promise<QueryResult>
+  execute(sql: string, params: QueryParam[]): Promise<QueryResult>
+  execute(sql: string, ...params: QueryParam[]): Promise<QueryResult>
   insert(collection: string, payload: Record<string, unknown>): Promise<InsertResult>
   bulkInsert(
     collection: string,
     payloads: Array<Record<string, unknown>>,
   ): Promise<BulkInsertResult>
+  exists(collection: string): Promise<boolean>
+  list(): Promise<CollectionMeta[]>
+  /**
+   * Caller-typed collection handle. Supply `T`; the SDK does not
+   * generate or validate row types at runtime.
+   */
+  from<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+  ): TypedQueryBuilder<T>
   get(collection: string, id: string | number): Promise<GetResult>
   delete(collection: string, id: string | number): Promise<DeleteResult>
   health(): Promise<HealthResult>
   version(): Promise<VersionResult>
 
-  // Auth surface — only meaningful when connected via grpc://.
-  // Embedded modes will receive 'unknown method' from the bridge.
+  // Auth surface is not available through embedded SDK connections.
+  // Use @reddb-io/client for remote authenticated servers.
   login(username: string, password: string): Promise<LoginResult>
   whoami(): Promise<WhoamiResult>
   changePassword(currentPassword: string, newPassword: string): Promise<ChangePasswordResult>
@@ -252,32 +346,16 @@ export class RedDB {
  * Accepted URI schemes:
  *   - `memory://`              — ephemeral in-memory database
  *   - `file:///absolute/path`  — embedded, persisted to disk
- *   - `grpc://host:port`       — remote server
+ *
+ * Remote URI schemes throw `EMBEDDED_ONLY`; use @reddb-io/client.
  */
 export function connect(uri: string, options?: ConnectOptions): Promise<RedDB>
 
-/**
- * Exchange username + password for a bearer token by hitting the
- * server's `POST /auth/login` HTTP endpoint. The returned `token`
- * can be passed to `connect(uri, { auth: { token } })`.
- *
- * @example
- * import { connect, login } from '@reddb-io/sdk'
- * const { token } = await login(
- *   'https://reddb.example.com/auth/login',
- *   { username: 'admin', password: 'secret' },
- * )
- * const db = await connect('grpc://reddb.example.com:5051', { auth: { token } })
- */
-export function login(
-  loginUrl: string,
-  credentials: { username: string; password: string },
-): Promise<LoginResult>
+export const EMBEDDED_ONLY_MESSAGE: string
 
 /**
  * Translate a connection URI + (optional) auth into argv for
- * `red rpc --stdio`. Exported for tests / debug. New code should
- * use `parseUri` directly and let `connect` handle dispatch.
+ * `red rpc --stdio`. Remote URI schemes throw `EMBEDDED_ONLY`.
  */
 export function uriToArgs(
   uri: string,
@@ -288,7 +366,7 @@ export function uriToArgs(
  * Parsed `red://` (or legacy) URI. Returned by `parseUri`.
  */
 export interface ParsedUri {
-  kind: 'embedded' | 'http' | 'https' | 'grpc' | 'grpcs' | 'pg'
+  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'grpc' | 'grpcs' | 'pg'
   host?: string
   port?: number
   path?: string

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.0.8",
-  "description": "Official RedDB driver — talks the native RedWire TCP protocol (mTLS), HTTP, gRPC bridge, or embedded stdio JSON-RPC. Works in Node 18+, Bun and Deno.",
+  "version": "1.1.1",
+  "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -45,6 +45,6 @@
   },
   "scripts": {
     "postinstall": "node postinstall.js",
-    "test": "node --test test/cache.test.mjs test/params.test.mjs test/redwire.params.test.mjs && node test/smoke.test.mjs"
+    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/postinstall.test.mjs test/queue.test.mjs test/redwire.params.test.mjs && node test/smoke.test.mjs"
   }
 }

package/src/cache.js

@@ -6,13 +6,37 @@
  * flushNamespace routes to the existing POST /admin/blob_cache/flush_namespace.
  * All others target endpoints planned for a future server release.
  *
+ * Requires an HTTP or gRPC transport. On embedded (stdio JSON-RPC), every
+ * method throws `UNSUPPORTED_TRANSPORT` before issuing the RPC call —
+ * the engine's stdio handler doesn't implement `cache.*`.
+ *
  * Values are base64-encoded in transit so binary payloads survive JSON.
  */
 
+import { RedDBError } from './protocol.js'
+
+const UNSUPPORTED_TRANSPORTS = new Set(['embedded'])
+
 export class CacheClient {
-  /** @param {{ call: Function }} client */
-  constructor(client) {
+  /**
+   * @param {{ call: Function }} client
+   * @param {string} [transport] Underlying transport label (e.g. 'http',
+   *   'grpc', 'embedded'). When the transport doesn't serve `cache.*`,
+   *   every method throws `UNSUPPORTED_TRANSPORT` before any RPC call.
+   */
+  constructor(client, transport) {
     this._client = client
+    this._transport = transport ?? null
+  }
+
+  _guard(method) {
+    if (this._transport && UNSUPPORTED_TRANSPORTS.has(this._transport)) {
+      throw new RedDBError(
+        'UNSUPPORTED_TRANSPORT',
+        `cache.${method} is not available on '${this._transport}' transport; `
+          + 'use @reddb-io/client for remote cache endpoints.',
+      )
+    }
   }
 
   /**
@@ -22,6 +46,7 @@ export class CacheClient {
    * @returns {Promise<Uint8Array | null>}
    */
   async get(namespace, key) {
+    this._guard('get')
     const result = await this._client.call('cache.get', { namespace, key })
     if (result == null || result.value == null) return null
     return base64ToBytes(result.value)
@@ -39,6 +64,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async put(namespace, key, value, opts = {}) {
+    this._guard('put')
     const encoded = bytesToBase64(value)
     await this._client.call('cache.put', {
       namespace,
@@ -55,6 +81,7 @@ export class CacheClient {
    * @returns {Promise<'present' | 'absent' | 'maybe'>}
    */
   async exists(namespace, key) {
+    this._guard('exists')
     const result = await this._client.call('cache.exists', { namespace, key })
     return result?.status ?? 'maybe'
   }
@@ -66,6 +93,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async invalidate(namespace, key) {
+    this._guard('invalidate')
     await this._client.call('cache.invalidate', { namespace, key })
   }
 
@@ -76,6 +104,7 @@ export class CacheClient {
    * @returns {Promise<number>} Number of entries removed.
    */
   async invalidatePrefix(namespace, prefix) {
+    this._guard('invalidatePrefix')
     const result = await this._client.call('cache.invalidate_prefix', { namespace, prefix })
     return result?.removed ?? 0
   }
@@ -87,6 +116,7 @@ export class CacheClient {
    * @returns {Promise<number>} Number of entries removed.
    */
   async invalidateTags(namespace, tags) {
+    this._guard('invalidateTags')
     const result = await this._client.call('cache.invalidate_tags', { namespace, tags })
     return result?.removed ?? 0
   }
@@ -98,6 +128,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async flushNamespace(namespace) {
+    this._guard('flushNamespace')
     await this._client.call('cache.flush_namespace', { namespace })
   }
 }

package/src/db-helpers.js

@@ -0,0 +1,95 @@
+import { RedDBError } from './protocol.js'
+
+export async function listCollections(db) {
+  const result = await db.query('SHOW COLLECTIONS')
+  return (result.rows ?? []).map(collectionMeta)
+}
+
+export async function collectionExists(db, collection) {
+  const result = await db.query(`SHOW COLLECTIONS WHERE name = ${sqlString(collection)}`)
+  return (result.rows ?? []).some((row) => row.name === String(collection))
+}
+
+export class TypedQueryBuilder {
+  constructor(db, collection, columns = null, whereClauses = [], params = []) {
+    this.db = db
+    this.collection = collection
+    this.columns = columns
+    this.whereClauses = whereClauses
+    this.params = params
+  }
+
+  select(...columns) {
+    const selected = columns.length === 1 && Array.isArray(columns[0]) ? columns[0] : columns
+    const projection = selected.length === 1 && selected[0] === '*' ? null : selected
+    return new TypedQueryBuilder(
+      this.db,
+      this.collection,
+      projection != null && projection.length > 0 ? projection : null,
+      this.whereClauses,
+      this.params,
+    )
+  }
+
+  where(condition, ...params) {
+    if (typeof condition !== 'string' || condition.trim().length === 0) {
+      throw new RedDBError('INVALID_QUERY_BUILDER', 'where() requires a non-empty SQL condition')
+    }
+    const nextParams = params.length === 1 && Array.isArray(params[0]) ? params[0] : params
+    return new TypedQueryBuilder(
+      this.db,
+      this.collection,
+      this.columns,
+      [...this.whereClauses, condition.trim()],
+      [...this.params, ...nextParams],
+    )
+  }
+
+  async run() {
+    const projection = this.columns == null
+      ? '*'
+      : this.columns.map(sqlIdentifierPath).join(', ')
+    const where = this.whereClauses.length > 0
+      ? ` WHERE ${this.whereClauses.map((clause) => `(${clause})`).join(' AND ')}`
+      : ''
+    const sql = `SELECT ${projection} FROM ${sqlIdentifierPath(this.collection)}${where}`
+    const result = this.params.length > 0
+      ? await this.db.query(sql, this.params)
+      : await this.db.query(sql)
+    const rows = result.rows ?? []
+    if (this.columns == null) return rows
+    return rows.map((row) => {
+      const selected = {}
+      for (const column of this.columns) selected[column] = row[column]
+      return selected
+    })
+  }
+}
+
+function collectionMeta(row) {
+  return {
+    ...row,
+    name: String(row.name),
+    model: String(row.model),
+    capabilities: Array.isArray(row.capabilities) ? row.capabilities : [],
+  }
+}
+
+function sqlIdentifierPath(value) {
+  return String(value).split('.').map(sqlIdentifier).join('.')
+}
+
+function sqlIdentifier(value) {
+  const ident = String(value)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new RedDBError(
+      'INVALID_IDENTIFIER',
+      `invalid SQL identifier "${ident}"`,
+    )
+  }
+  return ident
+}
+
+function sqlString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/src/http.js

@@ -123,9 +123,14 @@ async function parseResponse(response) {
 const ROUTES = {
   health: (base) => ({ url: `${base}/health`, init: { method: 'GET' } }),
   version: (base) => ({ url: `${base}/admin/version`, init: { method: 'GET' } }),
-  query: (base, { sql }) => ({
+  query: (base, { sql, params }) => ({
     url: `${base}/query`,
-    init: { method: 'POST', body: JSON.stringify({ query: sql }) },
+    init: {
+      method: 'POST',
+      body: JSON.stringify(
+        Array.isArray(params) ? { query: sql, params } : { query: sql },
+      ),
+    },
   }),
   insert: (base, { collection, payload }) => ({
     url: `${base}/collections/${encodeURIComponent(collection)}/rows`,

package/src/index.js

@@ -14,46 +14,35 @@
  * Connection URIs:
  *   - 'memory://'                — ephemeral in-memory database (embedded)
  *   - 'file:///absolute/path'    — embedded, persisted to disk
- *   - 'grpc://host:port'         — remote server via gRPC
  *
- * Authentication (only meaningful for `grpc://`; embedded modes ignore
- * auth options because the spawned binary inherits the caller's
- * filesystem privileges):
- *
- *   await connect('grpc://host:5051', {
- *     auth: { token: 'sk-...' }                     // raw bearer / api key
- *   })
- *   await connect('grpc://host:5051', {
- *     auth: { apiKey: 'ak-...' }                    // alias for token
- *   })
- *   await connect('grpc://host:5051', {
- *     auth: { username: 'admin', password: 'x' }    // login flow — driver
- *                                                   // calls /auth/login,
- *                                                   // caches the bearer
- *   })
- *
- * Username/password requires the server to expose the `auth.login`
- * JSON-RPC method (proxied through the gRPC bridge).
+ * Remote URIs belong to @reddb-io/client. This SDK is embedded-only.
  */
 
 import { spawnRed } from './spawn.js'
 import { resolveSdkBinary } from './binary.js'
 import { RpcClient, RedDBError } from './protocol.js'
-import { HttpRpcClient } from './http.js'
-import { connectRedwire } from './redwire.js'
-import { parseUri, deriveLoginUrl } from './url.js'
+import { parseUri } from './url.js'
 import { CacheClient } from './cache.js'
 import { KvClient } from './kv.js'
+import { QueueClient } from './queue.js'
 import { ConfigClient } from './config.js'
 import { VaultClient } from './vault.js'
+import { TypedQueryBuilder, collectionExists, listCollections } from './db-helpers.js'
 
 export { RedDBError }
 export { CacheClient } from './cache.js'
 export { KvClient } from './kv.js'
+export { QueueClient } from './queue.js'
 export { ConfigClient } from './config.js'
 export { VaultClient } from './vault.js'
+export { TypedQueryBuilder } from './db-helpers.js'
 export { parseUri, deriveLoginUrl } from './url.js'
 
+export const EMBEDDED_ONLY_MESSAGE =
+  'remote URIs are not supported in @reddb-io/sdk; install @reddb-io/client for grpc/http/red transports'
+
+const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
+
 /**
  * Connect to a RedDB instance.
  *
@@ -69,11 +58,12 @@ export { parseUri, deriveLoginUrl } from './url.js'
  */
 export async function connect(uri, options = {}) {
   const parsed = parseUri(uri)
-  const merged = mergeAuthFromUri(parsed, options.auth)
+  rejectRemoteUri(parsed)
 
   // Embedded modes: spawn the binary with stdio JSON-RPC. Auth is
   // not applicable (caller already has filesystem privileges).
   if (parsed.kind === 'embedded') {
+    const merged = mergeAuthFromUri(parsed, options.auth)
     if (merged.token || merged.username) {
       throw new RedDBError(
         'AUTH_NOT_APPLICABLE',
@@ -85,95 +75,130 @@ export async function connect(uri, options = {}) {
     const child = await spawnRed(binary, args)
     const client = new RpcClient(child)
     await client.call('version', {})
-    return new RedDB(client)
-  }
-
-  // HTTP / HTTPS: speak directly to the server via fetch().
-  if (parsed.kind === 'http' || parsed.kind === 'https') {
-    const baseUrl = `${parsed.kind}://${parsed.host}:${parsed.port}`
-    let token = merged.token
-    if (!token && merged.username && merged.password) {
-      const loginUrl = merged.loginUrl ?? `${baseUrl}/auth/login`
-      const session = await login(loginUrl, {
-        username: merged.username,
-        password: merged.password,
-      })
-      token = session.token
-    }
-    const client = new HttpRpcClient({ baseUrl, token })
-    // Sanity check before returning the handle.
-    await client.call('health', {})
-    return new RedDB(client)
-  }
-
-  // gRPC / gRPCs / RedWire (default for grpc-shaped URIs):
-  // speak the RedWire binary protocol natively via TCP. No spawn, no
-  // gRPC bridge. Resolves bearer auth from username/password via
-  // HTTP /auth/login first when needed.
-  //
-  // The server multiplexes RedWire on the same port as gRPC and HTTP
-  // via the service router's 0xFE detector, so pure grpc:// URLs
-  // still flow through RedWire because it wins on perf and parity.
-  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
-    let token = merged.token
-    if (!token && merged.username && merged.password) {
-      const loginUrl = merged.loginUrl ?? deriveLoginUrl(parsed)
-      const session = await login(loginUrl, {
-        username: merged.username,
-        password: merged.password,
-      })
-      token = session.token
-    }
-
-    // Honour `proto=spawn-grpc` as an escape hatch for callers that
-    // explicitly want the legacy stdio→gRPC bridge. Default is the
-    // RedWire transport.
-    const protoOverride = parsed.params?.get?.('proto') ?? ''
-    if (protoOverride === 'spawn-grpc') {
-      const args = grpcArgs(parsed, token)
-      const binary = options.binary ?? resolveSdkBinary()
-      const child = await spawnRed(binary, args)
-      const legacy = new RpcClient(child)
-      await legacy.call('version', {})
-      return new RedDB(legacy)
-    }
+    return new RedDB(client, { transport: 'embedded' })
+  }
+}
 
-    const auth = token ? { kind: 'bearer', token } : { kind: 'anonymous' }
-    const tls = buildTlsOpts(parsed, options.tls)
-    const client = await connectRedwire({
-      host: parsed.host,
-      port: parsed.port,
-      auth,
-      ...(tls ? { tls } : {}),
-    })
-    return new RedDB(client)
+// Coerce a JS query parameter to a JSON-serializable shape the server
+// understands. Values JSON cannot represent losslessly use the
+// stdio/HTTP query parameter envelopes.
+function serializeParam(value) {
+  assertSupportedParam(value)
+  if (value instanceof Float32Array || value instanceof Float64Array) {
+    return Array.from(value)
+  }
+  if (value instanceof Date) {
+    return { $ts: String(BigInt(value.getTime()) * 1_000_000n) }
+  }
+  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
+    return { $bytes: bytesToBase64(value) }
   }
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    if (Number.isNaN(value)) return { $float: 'NaN' }
+    return { $float: value > 0 ? 'Infinity' : '-Infinity' }
+  }
+  if (typeof value === 'string' && isUuidString(value)) {
+    return { $uuid: value }
+  }
+  return value
+}
 
-  // Postgres wire: not yet wired in the driver. Document the gap
-  // so users get a clear actionable error instead of a silent
-  // unsupported transport.
-  if (parsed.kind === 'pg') {
+function assertSupportedParam(value) {
+  if (value == null) return
+  if (
+    typeof value === 'boolean'
+    || typeof value === 'number'
+    || typeof value === 'string'
+  ) {
+    return
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new RedDBError('UNSUPPORTED_PARAM', 'cannot encode invalid Date query parameter')
+    }
+    return
+  }
+  if (
+    value instanceof Uint8Array
+    || value instanceof Float32Array
+    || value instanceof Float64Array
+    || (typeof Buffer !== 'undefined' && value instanceof Buffer)
+  ) {
+    return
+  }
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === 'number')) return
     throw new RedDBError(
-      'PG_TRANSPORT_NOT_WIRED',
-      "PostgreSQL wire (proto=pg) requires a node-pg-style client; "
-        + "the JS driver doesn't bundle one yet. Use a separate `pg` package "
-        + 'against the same host:port for now, or open an issue if you want it built in.',
+      'UNSUPPORTED_PARAM',
+      'array query parameters must contain only numbers',
     )
   }
-
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return
+  }
   throw new RedDBError(
-    'UNSUPPORTED_KIND',
-    `internal: parsed kind '${parsed.kind}' has no transport`,
+    'UNSUPPORTED_PARAM',
+    `cannot encode query parameter of type ${typeof value}`,
   )
 }
 
-// Coerce a JS query parameter to a JSON-serializable shape the server
-// understands. The tracer scope (#355) lifts vector params: `Float32Array`
-// and `Float64Array` round-trip as plain JSON arrays of numbers, which
-// the embedded stdio handler maps to `Value::Vector`.
-function serializeParam(value) {
-  if (value instanceof Float32Array || value instanceof Float64Array) {
-    return Array.from(value)
+function normalizeQueryParams(args) {
+  if (args.length === 0) return null
+  if (args.length === 1 && Array.isArray(args[0])) return args[0].map(serializeParam)
+  return args.map(serializeParam)
+}
+
+function bytesToBase64(value) {
+  const bytes = value instanceof Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
+  }
+  let text = ''
+  for (const byte of bytes) text += String.fromCharCode(byte)
+  // eslint-disable-next-line no-undef
+  return btoa(text)
+}
+
+function base64ToBytes(value) {
+  if (typeof Buffer !== 'undefined') {
+    const buf = Buffer.from(value, 'base64')
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+  }
+  // eslint-disable-next-line no-undef
+  const text = atob(value)
+  const out = new Uint8Array(text.length)
+  for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i)
+  return out
+}
+
+function isUuidString(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+}
+
+function normalizeResult(value) {
+  if (Array.isArray(value)) return value.map(normalizeResult)
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value)
+    if (keys.length === 1) {
+      if (typeof value.$bytes === 'string') return base64ToBytes(value.$bytes)
+      if (typeof value.$uuid === 'string') return value.$uuid
+      if (typeof value.$float === 'string') {
+        if (value.$float === 'NaN') return Number.NaN
+        if (value.$float === 'Infinity' || value.$float === '+Infinity') return Infinity
+        if (value.$float === '-Infinity') return -Infinity
+      }
+      if (typeof value.$ts === 'string' || typeof value.$ts === 'number') {
+        const raw = typeof value.$ts === 'string'
+          ? BigInt(value.$ts)
+          : BigInt(Math.trunc(value.$ts))
+        return new Date(Number(raw / 1_000_000n))
+      }
+    }
+    const out = {}
+    for (const [key, item] of Object.entries(value)) out[key] = normalizeResult(item)
+    return out
   }
   return value
 }
@@ -183,51 +208,11 @@ function embeddedArgs(parsed) {
   return ['rpc', '--stdio']
 }
 
-function grpcArgs(parsed, token) {
-  const scheme = parsed.kind === 'grpcs' ? 'grpcs' : 'grpc'
-  const url = `${scheme}://${parsed.host}:${parsed.port}${parsed.path ?? ''}`
-  const args = ['rpc', '--stdio', '--connect', url]
-  if (token) args.push('--token', token)
-  return args
-}
-
 /**
  * Merge `options.auth` (legacy `{ token, apiKey, username, password }`
  * shape) with credentials lifted from the URI itself. Explicit
  * `options.auth` always wins to keep behaviour predictable.
  */
-/**
- * Resolve TLS options for a redwire(s) connection.
- *
- * Sources, in priority order:
- *   - `options.tls` from the caller (object form), wins everything
- *   - `parsed.kind === 'grpcs'` (i.e. `redwires://` or `?proto=grpcs`)
- *   - `?tls=true` in the URL params
- *   - `?ca=`, `?cert=`, `?key=`, `?servername=`,
- *     `?rejectUnauthorized=false` URL params (paths or PEM strings)
- *
- * Returns `null` when TLS isn't requested.
- */
-function buildTlsOpts(parsed, callerTls) {
-  if (callerTls && typeof callerTls === 'object') {
-    return callerTls
-  }
-  const params = parsed.params
-  const wantsTls =
-    parsed.kind === 'grpcs'
-    || params?.get?.('tls') === 'true'
-    || params?.get?.('tls') === '1'
-  if (!wantsTls) return null
-  return {
-    ca: params?.get?.('ca') ?? undefined,
-    cert: params?.get?.('cert') ?? undefined,
-    key: params?.get?.('key') ?? undefined,
-    servername: params?.get?.('servername') ?? undefined,
-    rejectUnauthorized:
-      params?.get?.('rejectUnauthorized') === 'false' ? false : true,
-  }
-}
-
 function mergeAuthFromUri(parsed, optionAuth) {
   const out = {
     token: parsed.token ?? parsed.apiKey ?? null,
@@ -269,53 +254,6 @@ function mergeAuthFromUri(parsed, optionAuth) {
   return out
 }
 
-/**
- * Exchange username + password for a bearer token by hitting the
- * server's `POST /auth/login` HTTP endpoint, then return that token
- * for use with subsequent `connect({ auth: { token } })` calls.
- *
- * Why a separate function: the gRPC surface does not currently
- * expose `auth.login` as an RPC, so the driver can't piggyback on
- * the binary spawn for password auth. The HTTP listener does
- * expose it, and is the canonical login site (the same endpoint
- * the dashboard uses).
- *
- * @param {string} loginUrl Full URL of the server's auth endpoint
- *                          (e.g. `https://reddb.example.com/auth/login`).
- * @param {{ username: string, password: string }} credentials
- * @returns {Promise<{ token: string, username: string, role: string, expires_at: number }>}
- */
-export async function login(loginUrl, { username, password }) {
-  if (typeof loginUrl !== 'string' || !loginUrl.startsWith('http')) {
-    throw new TypeError("login() requires an http(s):// URL pointing at /auth/login")
-  }
-  if (typeof username !== 'string' || username.length === 0) {
-    throw new TypeError('login() requires a non-empty username')
-  }
-  if (typeof password !== 'string' || password.length === 0) {
-    throw new TypeError('login() requires a non-empty password')
-  }
-  const response = await fetch(loginUrl, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ username, password }),
-  })
-  const body = await response.json().catch(() => ({}))
-  if (!response.ok || body.ok === false) {
-    const code = body.error_code || `HTTP_${response.status}`
-    const message = body.error || `auth/login returned ${response.status}`
-    throw new RedDBError(code, message, body)
-  }
-  if (typeof body.token !== 'string') {
-    throw new RedDBError(
-      'AUTH_LOGIN_BAD_RESPONSE',
-      'auth/login response missing string token',
-      body,
-    )
-  }
-  return body
-}
-
 /**
  * Backwards-compatible shim: translate a URI into argv for
  * `red rpc --stdio`. New code should call `parseUri` directly and
@@ -325,14 +263,12 @@ export async function login(loginUrl, { username, password }) {
 export function uriToArgs(uri, auth = null) {
   const parsed = parseUri(uri)
   if (parsed.kind === 'embedded') return embeddedArgs(parsed)
-  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
-    const token = auth?.kind === 'token' ? auth.token : (parsed.token ?? parsed.apiKey ?? null)
-    return grpcArgs(parsed, token)
-  }
-  throw new RedDBError(
-    'UNSUPPORTED_SCHEME',
-    `uriToArgs() supports embedded + grpc kinds; for '${parsed.kind}' use connect() directly.`,
-  )
+  rejectRemoteUri(parsed)
+}
+
+function rejectRemoteUri(parsed) {
+  if (parsed.kind === 'embedded') return
+  throw new RedDBError('EMBEDDED_ONLY', EMBEDDED_ONLY_MESSAGE)
 }
 
 
@@ -340,10 +276,18 @@ export function uriToArgs(uri, auth = null) {
  * Connection handle. Methods map 1:1 to JSON-RPC methods on the binary.
  */
 export class RedDB {
-  /** @param {RpcClient} client */
-  constructor(client) {
+  /**
+   * @param {RpcClient} client
+   * @param {object} [opts]
+   * @param {string} [opts.transport] Underlying transport label
+   *   (normally 'embedded'). Used to gate calls that the embedded
+   *   stdio bridge does not serve, like `cache.*`.
+   */
+  constructor(client, opts = {}) {
     this.client = client
-    this.cache = new CacheClient(client)
+    this.transport = opts.transport ?? null
+    this.cache = new CacheClient(client, this.transport)
+    this.queue = new QueueClient(client)
     const defaultKv = new KvClient(client)
     this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
       put: defaultKv.put.bind(defaultKv),
@@ -360,32 +304,49 @@ export class RedDB {
    *
    * Two signatures:
    *   - `query(sql)` — legacy single-arg form.
-   *   - `query(sql, params)` — positional `$N` bind values. `params` is
-   *     an array (JS scalars: number | string | null map to engine
-   *     int/float / text / null). Indices in the SQL are 1-based
-   *     (`$1`, `$2`, ...), `params` is 0-based JS-style.
+   *   - `query(sql, ...params)` — positional `$N` bind values.
+   *   - `query(sql, paramsArray)` — legacy array form.
    *
    * Returns `{ statement, affected, columns, rows }`.
    */
-  query(sql, params) {
-    if (params === undefined) {
-      return this.client.call('query', { sql })
+  query(sql, ...params) {
+    const wireParams = normalizeQueryParams(params)
+    if (wireParams == null) {
+      return this.client.call('query', { sql }).then(normalizeResult)
     }
-    if (!Array.isArray(params)) {
-      throw new TypeError('query: `params` must be an array')
-    }
-    const wireParams = params.map(serializeParam)
-    return this.client.call('query', { sql, params: wireParams })
+    return this.client.call('query', { sql, params: wireParams }).then(normalizeResult)
   }
 
-  /** Insert one row. Returns `{ affected, id? }`. */
-  insert(collection, payload) {
-    return this.client.call('insert', { collection, payload })
+  /** Execute a SQL statement. Alias for `query`, including parameter binding. */
+  execute(sql, ...params) {
+    return this.query(sql, ...params)
   }
 
-  /** Insert many rows in one call. Returns `{ affected }`. */
-  bulkInsert(collection, payloads) {
-    return this.client.call('bulk_insert', { collection, payloads })
+  /** Insert one row. Returns `{ affected, id }`. */
+  async insert(collection, payload) {
+    const result = await this.client.call('insert', { collection, payload })
+    return requireInsertId(result, 'insert')
+  }
+
+  /** Insert many rows in one call. Returns `{ affected, ids }`. */
+  async bulkInsert(collection, payloads) {
+    const result = await this.client.call('bulk_insert', { collection, payloads })
+    return requireInsertIds(result, payloads.length)
+  }
+
+  /** Return true when a collection is visible in the catalog. */
+  exists(collection) {
+    return collectionExists(this, collection)
+  }
+
+  /** List visible collections using SHOW COLLECTIONS. */
+  list() {
+    return listCollections(this)
+  }
+
+  /** Return a caller-typed query builder for a collection. */
+  from(collection) {
+    return new TypedQueryBuilder(this, collection)
   }
 
   /** Get an entity by id. Returns `{ entity }` (entity is `null` if not found). */
@@ -409,18 +370,14 @@ export class RedDB {
   }
 
   // ---------------------------------------------------------------
-  // Auth surface — these are no-ops in embedded mode because the
+  // Auth surface — these are not available in embedded mode because the
   // bridge layer doesn't expose `auth.*` JSON-RPC methods locally.
-  // They forward to the server when the connection is grpc://.
+  // Use @reddb-io/client for remote authenticated servers.
   // ---------------------------------------------------------------
 
   /**
-   * Exchange username + password for a bearer token. Returns
-   * `{ token, username, role, expires_at }`. Server-side this
-   * routes to `POST /auth/login`.
-   *
-   * Prefer the `auth: { username, password }` form on `connect()`
-   * — it does the same exchange + caches the token transparently.
+   * Exchange username + password for a bearer token when the underlying
+   * client supports auth RPCs. Embedded SDK connections do not.
    */
   login(username, password) {
     return this.client.call('auth.login', { username, password })
@@ -459,3 +416,29 @@ export class RedDB {
     return this.client.close()
   }
 }
+
+function requireInsertId(result, method) {
+  if (!result || typeof result !== 'object' || result.id == null) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
+    )
+  }
+  return result
+}
+
+function requireInsertIds(result, expected) {
+  if (!result || typeof result !== 'object' || !Array.isArray(result.ids)) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `bulkInsert() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with bulk insert id support`,
+    )
+  }
+  if (result.ids.length !== expected) {
+    throw new RedDBError(
+      'INVALID_RESPONSE',
+      `bulkInsert() expected ${expected} ids, got ${result.ids.length}`,
+    )
+  }
+  return result
+}

package/src/kv.js

@@ -17,6 +17,20 @@ export class KvClient {
     })
   }
 
+  async get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `KV GET ${kvPath(collection, key)}`,
+    })
+    return result?.rows?.[0]?.value ?? null
+  }
+
+  async getMany(keys, options = {}) {
+    const values = []
+    for (const key of keys) values.push(await this.get(key, options))
+    return values
+  }
+
   async invalidateTags(tags, options = {}) {
     const collection = options.collection ?? this.collection
     const result = await this.client.call('query', {
@@ -56,7 +70,15 @@ function kvPath(collection, key) {
 }
 
 function kvIdentifier(value) {
-  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+  const ident = String(value)
+  const invalid = ident.match(/[^A-Za-z0-9_]/)
+  if (invalid) {
+    throw new RedDBError(
+      'INVALID_KV_KEY',
+      `invalid KV key "${ident}": character "${invalid[0]}" is not supported`,
+    )
+  }
+  return ident
 }
 
 function kvValueLiteral(value) {

package/src/queue.js

@@ -0,0 +1,78 @@
+import { RedDBError } from './protocol.js'
+
+export class QueueClient {
+  constructor(client) {
+    this.client = client
+  }
+
+  push(queue, value, options = {}) {
+    const priority = options.priority != null ? ` PRIORITY ${queuePriority(options.priority)}` : ''
+    return this.client.call('query', {
+      sql: `QUEUE PUSH ${queueIdentifier(queue)} ${queueValueLiteral(value)}${priority}`,
+    })
+  }
+
+  async pop(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE POP ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async peek(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE PEEK ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async len(queue) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE LEN ${queueIdentifier(queue)}`,
+    })
+    return Number(result?.rows?.[0]?.len ?? 0)
+  }
+
+  purge(queue) {
+    return this.client.call('query', {
+      sql: `QUEUE PURGE ${queueIdentifier(queue)}`,
+    })
+  }
+}
+
+function queueIdentifier(value) {
+  const ident = String(value)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new RedDBError(
+      'INVALID_QUEUE_NAME',
+      `invalid queue name "${ident}": expected an SQL identifier`,
+    )
+  }
+  return ident
+}
+
+function queueCount(count) {
+  if (count == null) return ''
+  if (!Number.isInteger(count) || count < 0) {
+    throw new RedDBError('INVALID_QUEUE_COUNT', 'queue count must be a non-negative integer')
+  }
+  return ` COUNT ${count}`
+}
+
+function queuePriority(priority) {
+  if (!Number.isInteger(priority)) {
+    throw new RedDBError('INVALID_QUEUE_PRIORITY', 'queue priority must be an integer')
+  }
+  return String(priority)
+}
+
+function queueValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`
+  return JSON.stringify(value)
+}
+
+function queuePayloads(result) {
+  return Array.isArray(result?.rows) ? result.rows.map((row) => row.payload) : []
+}

package/src/redwire.js

@@ -843,10 +843,14 @@ export function encodeValue(v) {
       if (k === '$bytes' && typeof v.$bytes === 'string') {
         return encodeLenPrefixed(ValueTag.Bytes, base64ToBytes(v.$bytes))
       }
-      if (k === '$ts' && typeof v.$ts === 'number' && Number.isFinite(v.$ts)) {
+      if (k === '$ts' && (
+        (typeof v.$ts === 'number' && Number.isFinite(v.$ts))
+        || typeof v.$ts === 'string'
+      )) {
         const out = new Uint8Array(1 + 8)
         out[0] = ValueTag.Timestamp
-        new DataView(out.buffer).setBigInt64(1, BigInt(Math.trunc(v.$ts)), true)
+        const raw = typeof v.$ts === 'string' ? BigInt(v.$ts) : BigInt(Math.trunc(v.$ts))
+        new DataView(out.buffer).setBigInt64(1, raw, true)
         return out
       }
       if (k === '$uuid' && typeof v.$uuid === 'string') {