@reddb-io/sdk 1.0.7 → 1.1.0

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.7",
-  "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.0",
+  "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 && 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`,