@radishbot/sdk 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# Radish Logger
+
+Flow-based logging SDK. Track what your app is doing with nested actions, timing, and structured logs — then inspect everything in the dashboard.
+
+No account needed. Generate a key, start logging.
+
+## Install
+
+```bash
+npm install @radishbot/sdk
+```
+
+## Quick Start
+
+```ts
+import { RL, generateKey } from '@radishbot/sdk';
+
+const key = generateKey(); // save this — it's your dashboard login
+
+const root = await RL(key);
+
+await root.a('handle-request', async (req) => {
+  console.log('GET /api/users'); // automatically captured
+
+  const users = await req.a('db-query', async () => {
+    return await db.query('SELECT * FROM users');
+  });
+
+  console.log('Done', { count: users.length });
+});
+
+await root.finish();
+```
+
+Open the dashboard, paste your key, see everything.
+
+## Console Capture
+
+Inside `.a()` callbacks, `console.log/warn/error/debug` are automatically captured as action logs. Output still prints to the terminal — but it also gets sent to the dashboard with full context.
+
+```ts
+await root.a('migrate', async () => {
+  console.log('Starting migration');           // → info log
+  console.warn('Deprecated column found');     // → warn log
+  console.error('Failed to migrate users');    // → error log
+  console.debug('SQL: ALTER TABLE ...');       // → debug log
+  console.log('Done', { tables: 5 });          // → info log with data
+});
+```
+
+Objects are properly serialized — no more `[object Object]`.
+
+## Actions
+
+Actions are nested scopes. Every `RL()` call creates a root action at `/`. Sub-actions branch off from there.
+
+```ts
+const root = await RL(key);
+
+await root.a('request', async (req) => {
+  console.log('handling request');
+
+  await req.a('database', async () => {
+    console.log('querying users');
+  }); // auto-finished
+
+  await req.a('response', async () => {
+    console.log('sending 200');
+  }); // auto-finished
+}); // auto-finished
+
+await root.finish();
+```
+
+If your function throws, the action is marked as errored and the exception propagates:
+
+```ts
+await root.a('risky-op', async () => {
+  throw new Error('something broke');
+}); // action → error, rethrows
+```
+
+Return values pass through:
+
+```ts
+const users = await flow.a('db-query', async () => {
+  return await db.query('SELECT * FROM users');
+});
+// users is the query result
+```
+
+Duplicate names are allowed — the dashboard shows them as `request:1`, `request:2`, etc:
+
+```ts
+await root.a('batch', async (batch) => {
+  for (const item of items) {
+    await batch.a('request', async () => {
+      await processItem(item);
+    });
+  }
+});
+```
+
+For long-lived actions (websockets, streams), use the manual API:
+
+```ts
+const stream = root.action('websocket');
+stream.info('connected');
+// ... hours later ...
+stream.info('disconnected');
+await stream.finish();
+```
+
+## Explicit Logging
+
+Outside of `.a()` callbacks, or when you want to log to a specific action:
+
+```ts
+action.info('request received', { method: 'POST', path: '/api/users' });
+action.warn('rate limit approaching', { remaining: 3 });
+action.error('query failed', new Error('connection refused'));
+action.debug('cache hit', { key: 'user:123', ttl: 300 });
+```
+
+## Cross-Context Actions
+
+Export an action's handle to continue logging from another process, worker, or service:
+
+```ts
+// Service A
+const action = root.action('job');
+const handle = await action.exportID();
+// pass handle to service B via queue, HTTP, etc.
+
+// Service B
+import { restoreFlow } from '@radishbot/sdk';
+const action = await restoreFlow(key, handle);
+action.info('continuing from service B');
+await action.finish();
+```
+
+## Configuration
+
+```ts
+const root = await RL(key, {
+  host: 'wss://maincloud.spacetimedb.com', // default
+  dbName: 'radish-log',                     // default
+  defaultTimeout: 100,                       // seconds, default 100
+});
+```
+
+Sub-actions can have their own timeout:
+
+```ts
+await root.a('quick-task', async () => {
+  // ...
+}, 10); // 10 second timeout
+
+const slow = root.action('batch-job', 3600); // 1 hour
+```
+
+Actions that exceed their timeout are automatically marked as timed out.
+
+## API Reference
+
+### `RL(secretKey, options?) → Promise<Flow>`
+
+Connect and create a root action.
+
+### `generateKey() → string`
+
+Generate a random secret key (prefix `rl_`).
+
+### `restoreFlow(secretKey, handle, options?) → Promise<Flow>`
+
+Restore an action from an exported handle string.
+
+### Flow (Action)
+
+| Method | Description |
+|---|---|
+| `.a(name, fn, timeout?)` | Run a sub-action. Auto-finish, console capture. Returns fn result. |
+| `.action(name, timeout?)` | Create a sub-action manually. |
+| `.finish()` | Finish the action. |
+| `.finishWithError(err?)` | Finish the action as errored. |
+| `.info(msg, data?)` | Log at info level. |
+| `.warn(msg, data?)` | Log at warn level. |
+| `.error(msg, data?)` | Log at error level. |
+| `.debug(msg, data?)` | Log at debug level. |
+| `.log(msg, data?, level?)` | Log at any level. |
+| `.exportID()` | Export handle for cross-context restore. |
+| `.getId()` | Get server-assigned action ID. |

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@radishbot/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "radish": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "cli": "bun run ./src/cli.ts"
+  },
+  "dependencies": {
+    "spacetimedb": "^2.0.3",
+    "ws": "^8.19.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,383 @@
+#!/usr/bin/env bun
+/**
+ * Radish CLI — inspect flows and logs from the terminal.
+ *
+ * Usage:
+ *   radish <key>                  List recent flows
+ *   radish <key> <flowId>         Show flow detail + logs
+ *   radish <key> tail             Live-tail all logs
+ *   radish <key> tree <flowId>    Show flow tree
+ */
+import { DbConnection } from './module_bindings';
+
+const HOST = 'wss://maincloud.spacetimedb.com';
+const DB_NAME = 'radish-log';
+
+// ── Colors ───────────────────────────────────────────────────
+
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+};
+
+function levelColor(level: string): string {
+  switch (level) {
+    case 'info': return c.blue;
+    case 'warn': return c.yellow;
+    case 'error': return c.red;
+    case 'debug': return c.gray;
+    default: return c.dim;
+  }
+}
+
+function statusColor(status: string): string {
+  switch (status) {
+    case 'open': return c.blue;
+    case 'finished': return c.green;
+    case 'error': return c.red;
+    case 'timeout': return c.yellow;
+    default: return c.dim;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────
+
+async function hashKey(key: string): Promise<string> {
+  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));
+  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+function tsMicros(ts: any): bigint { return ts.microsSinceUnixEpoch; }
+
+function fmtTime(ts: any): string {
+  return new Date(Number(tsMicros(ts) / 1000n)).toLocaleTimeString();
+}
+
+function fmtDateTime(ts: any): string {
+  const d = new Date(Number(tsMicros(ts) / 1000n));
+  return d.toLocaleString();
+}
+
+function fmtMs(us: number): string {
+  const ms = us / 1000;
+  if (ms < 1) return '<1ms';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+function fmtDuration(startTs: any, endMicros: bigint): string {
+  return fmtMs(Number(endMicros - tsMicros(startTs)));
+}
+
+function fmtData(data: string): string {
+  if (!data || data === '{}') return '';
+  try {
+    const parsed = JSON.parse(data);
+    const str = JSON.stringify(parsed, null, 2);
+    // Indent continuation lines
+    return str.split('\n').map((line, i) => i === 0 ? ' ' + c.dim + line + c.reset : '                          ' + c.dim + line + c.reset).join('\n');
+  } catch {
+    return ' ' + c.dim + data + c.reset;
+  }
+}
+
+function padRight(s: string, n: number): string {
+  return s.length >= n ? s.slice(0, n) : s + ' '.repeat(n - s.length);
+}
+
+// ── Connect ──────────────────────────────────────────────────
+
+function connect(keyHash: string): Promise<{ conn: DbConnection; flows: () => any[]; logs: () => any[] }> {
+  return new Promise((resolve, reject) => {
+    const conn = DbConnection.builder()
+      .withUri(HOST)
+      .withDatabaseName(DB_NAME)
+      .onConnect((c, _identity, _token) => {
+        c.subscriptionBuilder()
+          .onApplied(() => {
+            const flows = () => {
+              const result: any[] = [];
+              for (const f of c.db.flow.iter()) if (f.keyHash === keyHash) result.push(f);
+              return result;
+            };
+            const logs = () => {
+              const result: any[] = [];
+              for (const l of c.db.logEntry.iter()) result.push(l);
+              return result;
+            };
+            resolve({ conn: c, flows, logs });
+          })
+          .subscribeToAllTables();
+      })
+      .onConnectError((_ctx, err) => reject(new Error(`Connection failed: ${err}`)))
+      .build();
+  });
+}
+
+// ── Commands ─────────────────────────────────────────────────
+
+function cmdList(flows: any[]) {
+  const roots = flows
+    .filter(f => f.parentFlowId === 0n)
+    .sort((a, b) => {
+      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      return am > bm ? -1 : am < bm ? 1 : 0;
+    });
+
+  if (roots.length === 0) {
+    console.log(`${c.dim}No flows found for this key.${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.bold}Flows${c.reset} ${c.dim}(${roots.length} total)${c.reset}\n`);
+  console.log(`${c.dim}  ${'ID'.padEnd(8)} ${'STATUS'.padEnd(10)} ${'DURATION'.padEnd(10)} CREATED${c.reset}`);
+  console.log(`${c.dim}  ${'─'.repeat(8)} ${'─'.repeat(10)} ${'─'.repeat(10)} ${'─'.repeat(24)}${c.reset}`);
+
+  for (const f of roots.slice(0, 30)) {
+    const id = f.id.toString().padEnd(8);
+    const sc = statusColor(f.status);
+    const status = padRight(f.status, 10);
+    const dur = f.finishedAt !== 0n ? padRight(fmtDuration(f.createdAt, f.finishedAt), 10) : padRight('—', 10);
+    const time = fmtDateTime(f.createdAt);
+    console.log(`  ${c.dim}${id}${c.reset} ${sc}${status}${c.reset} ${dur} ${c.dim}${time}${c.reset}`);
+  }
+
+  if (roots.length > 30) {
+    console.log(`${c.dim}  ... and ${roots.length - 30} more${c.reset}`);
+  }
+}
+
+function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
+  const flow = allFlows.find(f => f.id === flowId);
+  if (!flow) {
+    console.error(`${c.red}Flow ${flowId} not found.${c.reset}`);
+    process.exit(1);
+  }
+
+  // Header
+  const sc = statusColor(flow.status);
+  console.log(`${c.bold}Flow #${flow.id}${c.reset}  ${sc}${flow.status}${c.reset}`);
+  console.log(`${c.dim}Created: ${fmtDateTime(flow.createdAt)}${c.reset}`);
+  if (flow.finishedAt !== 0n) {
+    console.log(`${c.dim}Duration: ${fmtDuration(flow.createdAt, flow.finishedAt)}${c.reset}`);
+  }
+  console.log();
+
+  // Child flows
+  const children = allFlows
+    .filter(f => f.parentFlowId === flowId)
+    .sort((a, b) => {
+      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      return am < bm ? -1 : am > bm ? 1 : 0;
+    });
+
+  if (children.length > 0) {
+    console.log(`${c.bold}Actions${c.reset}\n`);
+    for (const ch of children) {
+      const sc = statusColor(ch.status);
+      const dur = ch.finishedAt !== 0n ? fmtDuration(ch.createdAt, ch.finishedAt) : '…';
+      console.log(`  ${sc}●${c.reset} ${c.bold}${ch.name}${c.reset} ${c.dim}#${ch.id}${c.reset}  ${sc}${ch.status}${c.reset}  ${c.dim}${dur}${c.reset}`);
+    }
+    console.log();
+  }
+
+  // Collect logs from this flow and all descendants
+  const flowIds = new Set<bigint>();
+  function collectIds(parentId: bigint) {
+    flowIds.add(parentId);
+    for (const f of allFlows) {
+      if (f.parentFlowId === parentId) collectIds(f.id);
+    }
+  }
+  collectIds(flowId);
+
+  const logs = allLogs
+    .filter(l => flowIds.has(l.flowId) && l.level !== 'flow' && l.level !== 'action')
+    .sort((a, b) => {
+      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      return am < bm ? -1 : am > bm ? 1 : 0;
+    });
+
+  if (logs.length === 0) {
+    console.log(`${c.dim}No logs.${c.reset}`);
+    return;
+  }
+
+  // Find source flow name for each log
+  const flowMap = new Map<bigint, string>();
+  for (const f of allFlows) flowMap.set(f.id, f.name === '/' ? 'root' : f.name);
+
+  console.log(`${c.bold}Logs${c.reset}\n`);
+  for (const l of logs) {
+    const time = fmtTime(l.createdAt);
+    const lc = levelColor(l.level);
+    const lvl = padRight(l.level, 5);
+    const source = l.flowId !== flowId ? ` ${c.cyan}[${flowMap.get(l.flowId) || '?'}]${c.reset}` : '';
+    const data = fmtData(l.data);
+    console.log(`  ${c.dim}${time}${c.reset} ${lc}${lvl}${c.reset}${source} ${l.message}${data}`);
+  }
+}
+
+function cmdTree(flowId: bigint, allFlows: any[]) {
+  const flow = allFlows.find(f => f.id === flowId);
+  if (!flow) {
+    console.error(`${c.red}Flow ${flowId} not found.${c.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`${c.bold}Flow Tree #${flow.id}${c.reset}\n`);
+
+  function printNode(f: any, prefix: string, connector: string) {
+    const sc = statusColor(f.status);
+    const name = f.name === '/' ? 'root' : f.name;
+    const dur = f.finishedAt !== 0n ? ` ${c.dim}${fmtDuration(f.createdAt, f.finishedAt)}${c.reset}` : '';
+    console.log(`${prefix}${connector}${sc}●${c.reset} ${c.bold}${name}${c.reset} ${c.dim}#${f.id}${c.reset} ${sc}${f.status}${c.reset}${dur}`);
+  }
+
+  function printChildren(parentId: bigint, prefix: string) {
+    const children = allFlows
+      .filter(ch => ch.parentFlowId === parentId)
+      .sort((a, b) => {
+        const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+        return am < bm ? -1 : am > bm ? 1 : 0;
+      });
+
+    for (let i = 0; i < children.length; i++) {
+      const isLast = i === children.length - 1;
+      printNode(children[i], prefix, isLast ? '└─ ' : '├─ ');
+      printChildren(children[i].id, prefix + (isLast ? '   ' : '│  '));
+    }
+  }
+
+  printNode(flow, '', '');
+  printChildren(flowId, '');
+}
+
+async function cmdTail(keyHash: string) {
+  console.log(`${c.bold}Tailing logs...${c.reset} ${c.dim}(Ctrl+C to stop)${c.reset}\n`);
+
+  const seen = new Set<bigint>();
+  const flowNames = new Map<bigint, string>();
+
+  const conn = await new Promise<DbConnection>((resolve, reject) => {
+    DbConnection.builder()
+      .withUri(HOST)
+      .withDatabaseName(DB_NAME)
+      .onConnect((c, _identity, _token) => {
+        c.subscriptionBuilder()
+          .onApplied(() => {
+            // Seed known flows and seen logs
+            for (const f of c.db.flow.iter()) {
+              if (f.keyHash === keyHash) flowNames.set(f.id, f.name === '/' ? 'root' : f.name);
+            }
+            for (const l of c.db.logEntry.iter()) seen.add(l.id);
+            resolve(c);
+          })
+          .subscribeToAllTables();
+      })
+      .onConnectError((_ctx, err) => reject(new Error(`Connection failed: ${err}`)))
+      .build();
+  });
+
+  // Poll for new logs
+  setInterval(() => {
+    // Update flow names
+    for (const f of conn.db.flow.iter()) {
+      if (f.keyHash === keyHash && !flowNames.has(f.id)) {
+        flowNames.set(f.id, f.name === '/' ? 'root' : f.name);
+      }
+    }
+
+    const newLogs: any[] = [];
+    for (const l of conn.db.logEntry.iter()) {
+      if (!seen.has(l.id) && l.level !== 'flow' && l.level !== 'action') {
+        // Only show logs belonging to this key's flows
+        if (flowNames.has(l.flowId)) {
+          seen.add(l.id);
+          newLogs.push(l);
+        }
+      }
+    }
+
+    newLogs.sort((a, b) => {
+      const am = tsMicros(a.createdAt), bm = tsMicros(b.createdAt);
+      return am < bm ? -1 : am > bm ? 1 : 0;
+    });
+
+    for (const l of newLogs) {
+      const time = fmtTime(l.createdAt);
+      const lc = levelColor(l.level);
+      const lvl = padRight(l.level, 5);
+      const source = `${c.cyan}[${flowNames.get(l.flowId) || '?'}]${c.reset}`;
+      const data = fmtData(l.data);
+      console.log(`${c.dim}${time}${c.reset} ${lc}${lvl}${c.reset} ${source} ${l.message}${data}`);
+    }
+  }, 500);
+}
+
+// ── Main ─────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`
+${c.bold}radish${c.reset} — inspect flows and logs
+
+${c.bold}Usage:${c.reset}
+  radish <key>                  List recent flows
+  radish <key> <flowId>         Show flow detail + logs
+  radish <key> tree <flowId>    Show flow tree
+  radish <key> tail             Live-tail all logs
+`);
+    process.exit(0);
+  }
+
+  const secretKey = args[0];
+  const keyHash = await hashKey(secretKey);
+  const subcmd = args[1];
+
+  if (subcmd === 'tail') {
+    await cmdTail(keyHash);
+    return; // stays alive
+  }
+
+  // Connect and fetch data
+  process.stderr.write(`${c.dim}Connecting...${c.reset}`);
+  const { conn, flows, logs } = await connect(keyHash);
+  process.stderr.write(`\r${' '.repeat(20)}\r`);
+
+  const allFlows = flows();
+  const allLogs = logs();
+
+  if (!subcmd) {
+    cmdList(allFlows);
+  } else if (subcmd === 'tree') {
+    const flowId = BigInt(args[2] || '0');
+    if (flowId === 0n) {
+      console.error(`${c.red}Usage: radish <key> tree <flowId>${c.reset}`);
+      process.exit(1);
+    }
+    cmdTree(flowId, allFlows);
+  } else {
+    const flowId = BigInt(subcmd);
+    cmdShow(flowId, allFlows, allLogs);
+  }
+
+  conn.disconnect();
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error(`${c.red}${err.message}${c.reset}`);
+  process.exit(1);
+});