@reddb-io/sdk 1.0.1

package/README.md

@@ -0,0 +1,199 @@
+# @reddb-io/sdk
+
+Official RedDB SDK for JavaScript and TypeScript. Speaks JSON-RPC 2.0 over
+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:
+
+```bash
+npx @reddb-io/cli@latest version
+npx @reddb-io/cli@latest server --http-bind 127.0.0.1:8080 --path ./data.rdb
+```
+
+## Install
+
+```bash
+pnpm add @reddb-io/sdk
+# or
+npm install @reddb-io/sdk
+# or
+bun add @reddb-io/sdk
+```
+
+In Deno:
+
+```ts
+import { connect } from 'npm:@reddb-io/sdk'
+```
+
+The `postinstall` script downloads the matching `red` binary from GitHub
+Releases into `node_modules/@reddb-io/sdk/bin/`. If your environment blocks
+postinstall scripts or has no network, set `REDDB_BINARY_PATH=/path/to/red`
+and the driver will use that instead.
+
+## Quickstart
+
+```js
+import { connect } from '@reddb-io/sdk'
+
+const db = await connect('memory://')        // ephemeral
+// or:  await connect('file:///var/lib/reddb/data.rdb')   // persisted
+
+await db.insert('users', { name: 'Alice', age: 30 })
+await db.bulkInsert('users', [{ name: 'Bob' }, { name: 'Carol' }])
+
+const result = await db.query('SELECT * FROM users')
+console.log(result.rows)
+
+await db.close()
+```
+
+TypeScript is the same API:
+
+```ts
+import { connect, RedDBError } from '@reddb-io/sdk'
+
+const db = await connect('file:///var/lib/reddb/data.rdb')
+
+try {
+  const result = await db.query('SELECT * FROM users LIMIT 10')
+  console.log(result.rows)
+} catch (err) {
+  if (err instanceof RedDBError) {
+    console.error(err.code, err.message)
+  }
+}
+
+await db.close()
+```
+
+## Connection URIs
+
+| URI                        | Mode                                 |
+|----------------------------|--------------------------------------|
+| `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.
+
+## API
+
+### `connect(uri, options?) → Promise<RedDB>`
+
+Spawns `red rpc --stdio` with arguments derived from the URI, attaches a
+JSON-RPC client to its stdin/stdout, then returns a connection handle.
+
+Options:
+- `binary` — override the `red` binary path. Defaults to `bin/red` next to the
+  package, or `REDDB_BINARY_PATH` env var if set.
+
+Examples:
+
+```js
+import { connect } from '@reddb-io/sdk'
+
+const db = await connect('memory://')
+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.insert(collection, payload) → Promise<{ affected, id? }>`
+
+### `db.bulkInsert(collection, payloads) → Promise<{ affected }>`
+
+### `db.get(collection, id) → Promise<{ entity }>`
+
+### `db.delete(collection, id) → Promise<{ affected }>`
+
+### `db.health() → Promise<{ ok, version }>`
+
+### `db.version() → Promise<{ version, protocol }>`
+
+### `db.close() → Promise<void>`
+
+Sends `close` to the binary, waits for it to exit. Calls after `close()` reject
+with `RedDBError('CLIENT_CLOSED', ...)`.
+
+## Errors
+
+All RPC failures throw `RedDBError`:
+
+```js
+import { RedDBError } from '@reddb-io/sdk'
+
+try {
+  await db.query('NOT VALID SQL')
+} catch (err) {
+  if (err instanceof RedDBError) {
+    console.error(err.code)    // 'QUERY_ERROR'
+    console.error(err.message) // server-provided detail
+    console.error(err.data)    // optional structured data
+  }
+}
+```
+
+Stable error codes:
+
+| code              | when                                                       |
+|-------------------|------------------------------------------------------------|
+| `PARSE_ERROR`     | Server got malformed JSON (driver bug, please report)      |
+| `INVALID_REQUEST` | Missing field or unknown method                            |
+| `INVALID_PARAMS`  | params didn't match the method schema                      |
+| `QUERY_ERROR`     | SQL parse, type or constraint error                        |
+| `NOT_FOUND`       | Entity / collection does not exist                         |
+| `INTERNAL_ERROR`  | Server caught a panic                                      |
+| `CLIENT_CLOSED`   | Driver-side: call after `close()` or unexpected EOF        |
+| `UNSUPPORTED_SCHEME` | URI scheme not yet supported by the driver              |
+
+## Limits
+
+- **stdio IPC overhead.** Each call is a JSON serialize, write, parse, read
+  round-trip. For most apps (web servers, scripts, ETL) this is invisible.
+  For very high-throughput single-process ingestion, use the embedded Rust
+  crate `reddb` directly.
+- **No edge runtimes.** Cloudflare Workers, Vercel Edge and the browser have
+  no subprocess support. If you need RedDB there, wait for the planned HTTP
+  transport (see `PLAN_DRIVERS.md`).
+- **One process per connection.** No connection pooling yet. If you need
+  concurrent independent transactions, open multiple `connect()` handles.
+
+## Testing locally
+
+```bash
+cargo build --bin red       # at repo root
+cd drivers/js
+node test/smoke.test.mjs
+```
+
+Same test runs in Bun and Deno:
+
+```bash
+bun test/smoke.test.mjs
+deno run -A test/smoke.test.mjs
+```
+
+## Production deploy
+
+When you're ready to point this driver at a production RedDB cluster:
+
+- **Run RedDB with the encrypted vault** so auth state and
+  `red.secret.*` values are protected at rest. See
+  [`docs/security/vault.md`](../../docs/security/vault.md).
+- **Use Docker secrets or your cloud secret manager** to inject the
+  certificate — never bake it into an image. See
+  [`docs/getting-started/docker.md`](../../docs/getting-started/docker.md).
+- **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.
+- **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

@@ -0,0 +1,362 @@
+/**
+ * RedDB JavaScript driver — TypeScript definitions.
+ *
+ * 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 }
+  | { username: string; password: string; loginUrl?: string }
+
+/**
+ * TLS / mTLS configuration for `redwire(s)://` connections.
+ * `ca` / `cert` / `key` accept a filesystem path or a PEM string
+ * starting with `-----BEGIN`.
+ */
+export interface TlsOptions {
+  ca?: string | Uint8Array
+  cert?: string | Uint8Array
+  key?: string | Uint8Array
+  servername?: string
+  rejectUnauthorized?: boolean
+}
+
+export interface ConnectOptions {
+  /** Override the path to the `red` binary (defaults to bundled). */
+  binary?: string
+  /** Authentication credentials (grpc:// only). */
+  auth?: AuthOptions
+  /**
+   * TLS for `redwire(s)://` connections. URL params (`tls=true`,
+   * `cert=`, `key=`, `ca=`) feed the same field; this option
+   * always wins.
+   */
+  tls?: TlsOptions
+}
+
+export interface QueryResult {
+  statement: string
+  affected: number
+  columns: string[]
+  rows: Array<Record<string, unknown>>
+}
+
+export interface InsertResult {
+  affected: number
+  /** Present when the underlying engine surfaces the inserted entity id. */
+  id?: string | number
+}
+
+export interface BulkInsertResult {
+  affected: number
+}
+
+export interface GetResult {
+  entity: Record<string, unknown> | null
+}
+
+export interface DeleteResult {
+  affected: number
+}
+
+export interface HealthResult {
+  ok: boolean
+  version: string
+}
+
+export interface VersionResult {
+  version: string
+  protocol: string
+}
+
+export type Role = 'read' | 'write' | 'admin'
+
+export interface LoginResult {
+  token: string
+  username: string
+  role: Role
+  expires_at: number
+}
+
+export interface WhoamiResult {
+  username: string
+  role: Role
+}
+
+export interface CreateApiKeyResult {
+  key: string
+  role: Role
+  created_at: number
+}
+
+export interface ChangePasswordResult {
+  ok: true
+}
+
+export interface RevokeApiKeyResult {
+  ok: true
+}
+
+export class RedDBError extends Error {
+  readonly name: 'RedDBError'
+  readonly code: string
+  readonly data: unknown
+  constructor(code: string, message: string, data?: unknown)
+}
+
+// ---------------------------------------------------------------------------
+// Cache API
+// ---------------------------------------------------------------------------
+
+/** Options for cache.put(). Maps to Rust BlobCachePolicy fields. */
+export interface CachePutOptions {
+  /** Entry TTL in milliseconds. Omit to use the namespace default. */
+  ttl_ms?: number
+  /** Tags for group invalidation via cache.invalidateTags(). */
+  tags?: string[]
+  /** Extended TTL policy (idle eviction, stale-while-revalidate, jitter). */
+  policy?: {
+    idle_evict_ms?: number
+    stale_while_revalidate_ms?: number
+    jitter_ms?: number
+  }
+}
+
+export interface CacheGetResult {
+  /** Raw bytes of the cached value. null when not found. */
+  value: Uint8Array | null
+}
+
+export type CacheExistsStatus = 'present' | 'absent' | 'maybe'
+
+export interface CacheInvalidateResult {
+  removed: number
+}
+
+export class CacheClient {
+  /** Fetch a cached value. Returns Uint8Array on hit, null on miss. */
+  get(namespace: string, key: string): Promise<Uint8Array | null>
+  /** Store a value in the cache. */
+  put(
+    namespace: string,
+    key: string,
+    value: Uint8Array | Buffer | string,
+    opts?: CachePutOptions,
+  ): Promise<void>
+  /** Check whether a key exists. */
+  exists(namespace: string, key: string): Promise<CacheExistsStatus>
+  /** Remove a single entry. */
+  invalidate(namespace: string, key: string): Promise<void>
+  /** Remove all entries whose key starts with prefix. Returns count removed. */
+  invalidatePrefix(namespace: string, prefix: string): Promise<number>
+  /** Remove all entries tagged with any of the given tags. Returns count removed. */
+  invalidateTags(namespace: string, tags: string[]): Promise<number>
+  /** Remove all entries in a namespace (routes to POST /admin/blob_cache/flush_namespace). */
+  flushNamespace(namespace: string): Promise<void>
+}
+
+export interface KvWatchEvent {
+  key: string
+  op: 'insert' | 'update' | 'delete'
+  before: unknown
+  after: unknown
+  lsn: number
+  committed_at: number
+  dropped_event_count: number
+}
+
+export class KvClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: { collection?: string; expireMs?: number; tags?: string[] },
+  ): Promise<QueryResult>
+  invalidateTags(tags: string[], options?: { collection?: string }): Promise<number>
+  watch(
+    key: string,
+    options?: { collection?: string; sinceLsn?: number; limit?: number },
+  ): AsyncIterable<KvWatchEvent>
+  watchPrefix(
+    prefix: string,
+    options?: { collection?: string; sinceLsn?: number; limit?: number },
+  ): AsyncIterable<KvWatchEvent>
+}
+
+export class ConfigClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: {
+      collection?: string
+      tags?: string[]
+      secretRef?: { collection: string; key: string }
+    },
+  ): Promise<QueryResult>
+  get(key: string, options?: { collection?: string }): Promise<QueryResult>
+  resolve(key: string, options?: { collection?: string }): Promise<QueryResult>
+}
+
+export class VaultClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: { collection?: string; tags?: string[] },
+  ): Promise<QueryResult>
+  get(key: string, options?: { collection?: string }): Promise<QueryResult>
+  unseal(key: string, options?: { collection?: string }): Promise<QueryResult>
+}
+
+export class RedDB {
+  readonly cache: CacheClient
+  readonly kv: KvClient & ((collection?: string) => KvClient)
+  readonly config: (collection?: string) => ConfigClient
+  readonly vault: (collection?: string) => VaultClient
+
+  query(sql: string): Promise<QueryResult>
+  insert(collection: string, payload: Record<string, unknown>): Promise<InsertResult>
+  bulkInsert(
+    collection: string,
+    payloads: Array<Record<string, unknown>>,
+  ): Promise<BulkInsertResult>
+  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.
+  login(username: string, password: string): Promise<LoginResult>
+  whoami(): Promise<WhoamiResult>
+  changePassword(currentPassword: string, newPassword: string): Promise<ChangePasswordResult>
+  createApiKey(opts?: { username?: string; role?: Role }): Promise<CreateApiKeyResult>
+  revokeApiKey(key: string): Promise<RevokeApiKeyResult>
+
+  close(): Promise<void>
+}
+
+/**
+ * Connect to a RedDB instance.
+ *
+ * Accepted URI schemes:
+ *   - `memory://`              — ephemeral in-memory database
+ *   - `file:///absolute/path`  — embedded, persisted to disk
+ *   - `grpc://host:port`       — remote server
+ */
+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>
+
+/**
+ * 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.
+ */
+export function uriToArgs(
+  uri: string,
+  auth?: { kind: 'token'; token: string } | null,
+): string[]
+
+/**
+ * Parsed `red://` (or legacy) URI. Returned by `parseUri`.
+ */
+export interface ParsedUri {
+  kind: 'embedded' | 'http' | 'https' | 'grpc' | 'grpcs' | 'pg'
+  host?: string
+  port?: number
+  path?: string
+  username?: string
+  password?: string
+  token?: string
+  apiKey?: string
+  loginUrl?: string
+  params?: URLSearchParams
+  originalUri: string
+}
+
+/** Parse any URI (red://, memory://, file://, grpc://, http(s)://) into a normalised shape. */
+export function parseUri(uri: string): ParsedUri
+
+/** Derive the HTTP `/auth/login` URL from a parsed URI. */
+export function deriveLoginUrl(parsed: ParsedUri): string
+
+// ---------------------------------------------------------------
+// RedWire native TCP transport (drivers/js/src/redwire.js)
+// ---------------------------------------------------------------
+
+/** RedWire frame kinds. Numeric values are the wire-stable spec. */
+export const MessageKind: Readonly<{
+  Query: 0x01
+  Result: 0x02
+  Error: 0x03
+  BulkInsert: 0x04
+  BulkOk: 0x05
+  Hello: 0x10
+  HelloAck: 0x11
+  AuthRequest: 0x12
+  AuthResponse: 0x13
+  AuthOk: 0x14
+  AuthFail: 0x15
+  Bye: 0x16
+  Ping: 0x17
+  Pong: 0x18
+}>
+
+export type RedWireAuth =
+  | { kind: 'anonymous' }
+  | { kind: 'bearer'; token: string }
+
+export interface RedWireConnectOptions {
+  host: string
+  port: number
+  auth?: RedWireAuth
+  clientName?: string
+  /** When set, wraps the socket in TLS (mTLS via cert + key). */
+  tls?: TlsOptions
+}
+
+/**
+ * Open a RedWire connection. Speaks the binary protocol directly via
+ * a TCP socket — no spawn, no fetch. Returned client matches the
+ * `RpcClient` / `HttpRpcClient` surface so it slots into the
+ * existing `RedDB` class.
+ */
+export function connectRedwire(opts: RedWireConnectOptions): Promise<RedWireClient>
+
+export class RedWireClient {
+  /**
+   * Generic RPC entry. Routes:
+   *  - 'query' → Query frame (SQL string)
+   *  - 'insert' → BulkInsert frame, single-row shape
+   *  - 'bulk_insert' → BulkInsert frame, array shape
+   *  - 'health' / 'version' → Ping frame
+   */
+  call(method: string, params?: Record<string, unknown>): Promise<unknown>
+  close(): Promise<void>
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@reddb-io/sdk",
+  "version": "1.0.1",
+  "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.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts",
+    "postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "reddb",
+    "database",
+    "client",
+    "driver",
+    "json-rpc",
+    "multi-model",
+    "vector",
+    "graph",
+    "document",
+    "key-value"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/reddb-io/reddb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reddb-io/reddb.git",
+    "directory": "drivers/js"
+  },
+  "bugs": {
+    "url": "https://github.com/reddb-io/reddb/issues"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "node --test test/cache.test.mjs && node test/smoke.test.mjs"
+  }
+}

package/postinstall.js

@@ -0,0 +1,86 @@
+/**
+ * postinstall.js — download the matching `red` binary from GitHub Releases.
+ *
+ * Behavior:
+ *   - Resolves `red-<platform>-<arch>` from `process.platform` + `process.arch`
+ *     via the vendored asset fetcher.
+ *   - Targets the GitHub release matching this package's version.
+ *   - Drops the binary at `<package>/bin/red[.exe]` and chmods +x on Unix.
+ *   - On any failure, prints a warning to stderr but exits 0 — `npm install`
+ *     never breaks because of this script. The user gets a clear error
+ *     later when they call `connect()` if the binary isn't present.
+ *
+ * Override hooks (env vars):
+ *   REDDB_SKIP_POSTINSTALL=1      do nothing
+ *   REDDB_POSTINSTALL_VERSION=…   pull a different release tag
+ *   REDDB_POSTINSTALL_REPO=…      pull from a fork (default: reddb-io/reddb)
+ */
+
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
+
+import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const pkg = require('./package.json')
+
+const DEFAULT_REPO = 'reddb-io/reddb'
+
+if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
+  process.stdout.write('reddb: postinstall skipped (REDDB_SKIP_POSTINSTALL=1)\n')
+  process.exit(0)
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `reddb: postinstall could not download the binary (${err.message}).\n` +
+      `       The package will still install. To use the driver you can:\n` +
+      `         - set REDDB_BINARY_PATH=/path/to/red\n` +
+      `         - or install the binary manually from https://github.com/${DEFAULT_REPO}/releases\n`,
+  )
+  process.exit(0)
+})
+
+async function main() {
+  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
+  const tag = process.env.REDDB_POSTINSTALL_VERSION
+    ? normalizeTag(process.env.REDDB_POSTINSTALL_VERSION)
+    : `v${pkg.version}`
+
+  const binDir = join(HERE, 'bin')
+  const binaryPath = join(binDir, defaultBinaryName())
+
+  if (existsSync(binaryPath)) {
+    process.stdout.write(`reddb: binary already present at ${binaryPath}\n`)
+    return
+  }
+
+  process.stdout.write(
+    `reddb: downloading red ${tag} for ${process.platform}/${process.arch} from ${repo}\n`,
+  )
+  const body = await fetchReleaseAsset({
+    repo,
+    tag,
+    platform: process.platform,
+    arch: process.arch,
+    binName: 'red',
+  })
+  mkdirSync(binDir, { recursive: true })
+  writeFileSync(binaryPath, body)
+  if (process.platform !== 'win32') {
+    chmodSync(binaryPath, 0o755)
+  }
+  process.stdout.write(`reddb: installed binary at ${binaryPath}\n`)
+}
+
+function defaultBinaryName() {
+  return process.platform === 'win32' ? 'red.exe' : 'red'
+}
+
+function normalizeTag(value) {
+  const v = String(value).trim()
+  return v.startsWith('v') ? v : `v${v}`
+}