@radishbot/sdk 0.1.0

package/src/connection.ts

@@ -0,0 +1,124 @@
+/**
+ * SpacetimeDB connection wrapper for the Radish SDK.
+ * Uses the generated bindings + SpacetimeDB WebSocket client.
+ */
+import { DbConnection as StdbConnection } from './module_bindings';
+
+export class SdkConnection {
+  private _host: string;
+  private _dbName: string;
+  private _conn: StdbConnection | null = null;
+  private _connectPromise: Promise<StdbConnection> | null = null;
+  private _timeoutInterval: ReturnType<typeof setInterval> | null = null;
+  private _keyHash: string | null = null;
+
+  // Callbacks waiting for flow creation by exportToken
+  private _flowWaiters = new Map<string, (id: bigint) => void>();
+
+  constructor(host: string, dbName: string) {
+    this._host = host;
+    this._dbName = dbName;
+  }
+
+  setKeyHash(keyHash: string): void {
+    this._keyHash = keyHash;
+  }
+
+  async connect(): Promise<StdbConnection> {
+    if (this._conn) return this._conn;
+    if (this._connectPromise) return this._connectPromise;
+
+    this._connectPromise = new Promise<StdbConnection>((resolve, reject) => {
+      const conn = StdbConnection.builder()
+        .withUri(this._host)
+        .withDatabaseName(this._dbName)
+        .onConnect((c, _identity, _token) => {
+          this._conn = c;
+
+          // Subscribe to flow table to detect newly created flows
+          c.subscriptionBuilder()
+            .onApplied(() => {
+              resolve(c);
+            })
+            .subscribeToAllTables();
+
+          // Periodic timeout check (every 30s)
+          this._timeoutInterval = setInterval(() => {
+            if (this._keyHash) {
+              c.reducers.checkTimeouts({ keyHash: this._keyHash });
+            }
+          }, 30_000);
+        })
+        .onConnectError((_ctx, err) => {
+          reject(new Error(`SpacetimeDB connection failed: ${err}`));
+        })
+        .build();
+    });
+
+    return this._connectPromise;
+  }
+
+  get conn(): StdbConnection {
+    if (!this._conn) throw new Error('Not connected');
+    return this._conn;
+  }
+
+  /**
+   * Call a reducer and wait for the flow to appear in the subscription.
+   * Returns the server-assigned flow ID.
+   */
+  async createFlowAndResolveId(
+    reducerCall: () => void,
+    exportToken: string
+  ): Promise<bigint> {
+    const conn = this.conn;
+
+    // Check if flow already exists (from a previous subscription update)
+    for (const f of conn.db.flow.iter()) {
+      if (f.exportToken === exportToken) return f.id;
+    }
+
+    return new Promise<bigint>((resolve) => {
+      // Set up watcher
+      this._flowWaiters.set(exportToken, resolve);
+
+      // Call the reducer
+      reducerCall();
+
+      // Also poll in case subscription update was missed
+      const check = () => {
+        for (const f of conn.db.flow.iter()) {
+          if (f.exportToken === exportToken) {
+            this._flowWaiters.delete(exportToken);
+            resolve(f.id);
+            return true;
+          }
+        }
+        return false;
+      };
+
+      // Poll every 100ms for up to 10 seconds
+      let attempts = 0;
+      const interval = setInterval(() => {
+        if (check() || attempts++ > 100) {
+          clearInterval(interval);
+          if (attempts > 100) {
+            this._flowWaiters.delete(exportToken);
+            throw new Error(`Flow creation timed out for token ${exportToken}`);
+          }
+        }
+      }, 100);
+    });
+  }
+
+  disconnect(): void {
+    if (this._timeoutInterval) {
+      clearInterval(this._timeoutInterval);
+      this._timeoutInterval = null;
+    }
+    if (this._conn) {
+      this._conn.disconnect();
+      this._conn = null;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,383 @@
+import { SdkConnection } from './connection';
+
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+
+// ── Console capture ──────────────────────────────────────────
+
+const _origConsole = {
+  log: console.log,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+  debug: console.debug,
+};
+
+const _flowStack: Flow[] = [];
+
+function _patchConsole() {
+  const capture = (level: LogLevel) => (...args: unknown[]) => {
+    const flow = _flowStack[_flowStack.length - 1];
+    if (flow) {
+      const msg = args.map(a => {
+        if (typeof a === 'string') return a;
+        if (a instanceof Error) return a.message;
+        try { return JSON.stringify(a); } catch { return String(a); }
+      }).join(' ');
+      const data = args.length <= 1 ? undefined
+        : args.length === 2 ? args[1]
+        : args.slice(1);
+      flow.log(msg, data, level);
+    }
+    _origConsole[level === 'info' ? 'log' : level](...args);
+  };
+  console.log = capture('info');
+  console.info = capture('info');
+  console.warn = capture('warn');
+  console.error = capture('error');
+  console.debug = capture('debug');
+}
+
+function _restoreConsole() {
+  console.log = _origConsole.log;
+  console.info = _origConsole.info;
+  console.warn = _origConsole.warn;
+  console.error = _origConsole.error;
+  console.debug = _origConsole.debug;
+}
+
+function serialize(value: unknown): string {
+  if (value === undefined || value === null) return '{}';
+  if (value instanceof Error)
+    return JSON.stringify({
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    });
+  try {
+    return JSON.stringify(value, (_key, v) =>
+      typeof v === 'bigint' ? v.toString() : v
+    );
+  } catch {
+    return JSON.stringify({ value: String(value) });
+  }
+}
+
+async function hashKey(secretKey: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(secretKey);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function generateToken(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export class Flow {
+  private _sdk: SdkConnection;
+  private _keyHash: string;
+  private _id: bigint | null = null;
+  private _exportToken: string;
+  private _ready: Promise<void>;
+  private _resolveReady!: () => void;
+  private _pendingLogs: Array<{ level: string; message: string; data: string }> = [];
+  private _flushScheduled = false;
+  private _isReady = false;
+  private _finished = false;
+  private _parentId: bigint;
+  private _name: string;
+  private _timeoutSeconds: bigint;
+
+  /** @internal */
+  constructor(
+    sdk: SdkConnection,
+    keyHash: string,
+    parentId: bigint,
+    name: string,
+    timeoutSeconds: number
+  ) {
+    this._sdk = sdk;
+    this._keyHash = keyHash;
+    this._parentId = parentId;
+    this._name = name;
+    this._timeoutSeconds = (!timeoutSeconds || timeoutSeconds === Infinity) ? 0n : BigInt(timeoutSeconds);
+    this._exportToken = generateToken();
+    this._ready = new Promise<void>((resolve) => {
+      this._resolveReady = resolve;
+    });
+  }
+
+  /** @internal */
+  async _create(): Promise<void> {
+    const conn = this._sdk.conn;
+    const exportToken = this._exportToken;
+    const keyHash = this._keyHash;
+    const timeoutSeconds = this._timeoutSeconds;
+
+    if (this._parentId === 0n) {
+      const id = await this._sdk.createFlowAndResolveId(
+        () => conn.reducers.createRootFlow({ keyHash, timeoutSeconds, exportToken }),
+        exportToken
+      );
+      this._id = id;
+    } else {
+      const parentFlowId = this._parentId;
+      const name = this._name;
+      const id = await this._sdk.createFlowAndResolveId(
+        () =>
+          conn.reducers.createSubFlow({
+            keyHash,
+            parentFlowId,
+            name,
+            timeoutSeconds,
+            exportToken,
+          }),
+        exportToken
+      );
+      this._id = id;
+    }
+    this._isReady = true;
+    this._resolveReady();
+    this._drain(); // flush any logs queued before ready
+  }
+
+  /** Log a message with optional data */
+  log(message: string, data?: unknown, level: LogLevel = 'info'): this {
+    if (this._finished) {
+      console.warn(`[radish] Cannot log to finished flow`);
+      return this;
+    }
+    this._pendingLogs.push({
+      level,
+      message,
+      data: data !== undefined ? serialize(data) : '{}',
+    });
+    this._scheduleFlush();
+    return this;
+  }
+
+  info(message: string, data?: unknown): this {
+    return this.log(message, data, 'info');
+  }
+  warn(message: string, data?: unknown): this {
+    return this.log(message, data, 'warn');
+  }
+  error(message: string, data?: unknown): this {
+    return this.log(message, data, 'error');
+  }
+  debug(message: string, data?: unknown): this {
+    return this.log(message, data, 'debug');
+  }
+
+  /** Create a sub-action. Returns immediately — creation runs in background. */
+  action(name: string, timeoutSeconds = 100): Flow {
+    const child = new Flow(this._sdk, this._keyHash, 0n, name, timeoutSeconds);
+    this._ready.then(() => {
+      (child as any)._parentId = this._id!;
+      child._create();
+    });
+    return child;
+  }
+
+  /** Alias for action() */
+  flow(name: string, timeoutSeconds = 100): Flow {
+    return this.action(name, timeoutSeconds);
+  }
+
+  /** Run a sub-action — auto-creates, runs fn, auto-finishes. console.* inside fn becomes action logs. */
+  async a<T>(name: string, fn: (action: Flow) => T | Promise<T>, timeoutSeconds = 100): Promise<T> {
+    const child = this.action(name, timeoutSeconds);
+    _flowStack.push(child);
+    _patchConsole();
+    try {
+      const result = await fn(child);
+      await child.finish();
+      return result;
+    } catch (e) {
+      await child.finishWithError(e instanceof Error ? e : String(e));
+      throw e;
+    } finally {
+      _flowStack.pop();
+      if (_flowStack.length === 0) _restoreConsole();
+    }
+  }
+
+  /** Finish this flow successfully */
+  async finish(): Promise<void> {
+    await this._ready;
+    this._drain(); // sync flush — sends over same WS, ordering preserved
+    this._finished = true;
+    this._sdk.conn.reducers.finishFlow({
+      keyHash: this._keyHash,
+      flowId: this._id!,
+      status: 'finished',
+    });
+  }
+
+  /** Finish this flow with error status */
+  async finishWithError(err?: Error | string): Promise<void> {
+    if (err) {
+      this.error(typeof err === 'string' ? err : err.message, err);
+    }
+    await this._ready;
+    this._drain();
+    this._finished = true;
+    this._sdk.conn.reducers.finishFlow({
+      keyHash: this._keyHash,
+      flowId: this._id!,
+      status: 'error',
+    });
+  }
+
+  /** Export this flow's handle for restoration in another context */
+  async exportID(): Promise<string> {
+    await this._ready;
+    return JSON.stringify({
+      flowId: this._id!.toString(),
+      exportToken: this._exportToken,
+      keyHash: this._keyHash,
+    });
+  }
+
+  /** Get the resolved server-assigned flow ID */
+  async getId(): Promise<bigint> {
+    await this._ready;
+    return this._id!;
+  }
+
+  /** Schedule a drain on the next microtask — batches sync logs with ~0ms delay */
+  private _scheduleFlush() {
+    if (this._flushScheduled) return;
+    this._flushScheduled = true;
+    queueMicrotask(() => {
+      this._flushScheduled = false;
+      this._drain();
+    });
+  }
+
+  /** Synchronously send all pending logs. No-op if flow not ready yet (they'll flush when ready). */
+  private _drain(): void {
+    if (!this._isReady || this._pendingLogs.length === 0) return;
+    const batch = this._pendingLogs.splice(0);
+    const conn = this._sdk.conn;
+
+    if (batch.length === 1) {
+      const e = batch[0];
+      conn.reducers.addLog({
+        keyHash: this._keyHash,
+        flowId: this._id!,
+        level: e.level,
+        message: e.message,
+        data: e.data,
+      });
+    } else {
+      conn.reducers.addLogsBatch({
+        keyHash: this._keyHash,
+        flowId: this._id!,
+        entries: JSON.stringify(batch),
+      });
+    }
+  }
+}
+
+export interface RLOptions {
+  host?: string;
+  dbName?: string;
+  label?: string;
+  defaultTimeout?: number;
+}
+
+/**
+ * Create a Radish Logger instance. Returns the root action.
+ *
+ * ```ts
+ * const root = await RL('my-secret-key');
+ *
+ * // Auto-managed — auto-finish on return, auto-error on throw
+ * await root.a('request', async (req) => {
+ *   console.log('GET /api/users');
+ *   const rows = await req.a('db_query', () => db.query('SELECT ...'));
+ *   console.log('Done', { count: rows.length });
+ * });
+ *
+ * // Manual — when you need more control
+ * const ws = root.action('websocket');
+ * ws.info('Connected');
+ * await ws.finish();
+ *
+ * await root.finish();
+ * ```
+ */
+export async function RL(secretKey: string, options: RLOptions = {}): Promise<Flow> {
+  const {
+    host = 'wss://maincloud.spacetimedb.com',
+    dbName = 'radish-log',
+    label = '',
+    defaultTimeout = 100,
+  } = options;
+
+  const keyHash = await hashKey(secretKey);
+  const sdk = new SdkConnection(host, dbName);
+  sdk.setKeyHash(keyHash);
+  await sdk.connect();
+
+  // Register key (idempotent — server rejects dupes)
+  try {
+    sdk.conn.reducers.registerKey({ keyHash, label });
+  } catch {
+    // Already registered
+  }
+
+  // Check for timed-out flows (fire-and-forget)
+  try {
+    sdk.conn.reducers.checkTimeouts({ keyHash });
+  } catch {
+    // Non-critical
+  }
+
+  // Root flow — creation runs in background, logs queue until ready
+  const root = new Flow(sdk, keyHash, 0n, '/', 0);
+  root._create(); // fire-and-forget — resolves _ready when server assigns ID
+  return root;
+}
+
+/** Restore a flow from an exported ID string */
+export async function restoreFlow(
+  secretKey: string,
+  exportedId: string,
+  options: RLOptions = {}
+): Promise<Flow> {
+  const { host = 'wss://maincloud.spacetimedb.com', dbName = 'radish-log' } = options;
+
+  const parsed = JSON.parse(exportedId);
+  const keyHash = await hashKey(secretKey);
+  if (keyHash !== parsed.keyHash) {
+    throw new Error('Secret key does not match the flow owner');
+  }
+
+  const sdk = new SdkConnection(host, dbName);
+  await sdk.connect();
+
+  const flow = new Flow(sdk, keyHash, 0n, 'restored', 100);
+  (flow as any)._id = BigInt(parsed.flowId);
+  (flow as any)._exportToken = parsed.exportToken;
+  (flow as any)._resolveReady();
+  return flow;
+}
+
+/** Generate a random secret key */
+export function generateKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return (
+    'rl_' +
+    Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('')
+  );
+}

package/src/module_bindings/action_table.ts

@@ -0,0 +1,20 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default __t.row({
+  id: __t.u64().primaryKey(),
+  flowId: __t.u64().name("flow_id"),
+  name: __t.string(),
+  status: __t.string(),
+  createdAt: __t.timestamp().name("created_at"),
+  finishedAt: __t.u64().name("finished_at"),
+});

package/src/module_bindings/add_log_reducer.ts

@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  flowId: __t.u64(),
+  level: __t.string(),
+  message: __t.string(),
+  data: __t.string(),
+};

package/src/module_bindings/add_logs_batch_reducer.ts

@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  flowId: __t.u64(),
+  entries: __t.string(),
+};

package/src/module_bindings/api_key_table.ts

@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default __t.row({
+  keyHash: __t.string().primaryKey().name("key_hash"),
+  label: __t.string(),
+  createdAt: __t.timestamp().name("created_at"),
+});

package/src/module_bindings/check_timeouts_reducer.ts

@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+};

package/src/module_bindings/create_root_flow_reducer.ts

@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  timeoutSeconds: __t.u64(),
+  exportToken: __t.string(),
+};

package/src/module_bindings/create_sub_flow_reducer.ts

@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  parentFlowId: __t.u64(),
+  name: __t.string(),
+  timeoutSeconds: __t.u64(),
+  exportToken: __t.string(),
+};

package/src/module_bindings/finish_action_reducer.ts

@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  actionId: __t.u64(),
+  status: __t.string(),
+};

package/src/module_bindings/finish_flow_reducer.ts

@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default {
+  keyHash: __t.string(),
+  flowId: __t.u64(),
+  status: __t.string(),
+};

package/src/module_bindings/flow_table.ts

@@ -0,0 +1,24 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+/* eslint-disable */
+/* tslint:disable */
+import {
+  TypeBuilder as __TypeBuilder,
+  t as __t,
+  type AlgebraicTypeType as __AlgebraicTypeType,
+  type Infer as __Infer,
+} from "spacetimedb";
+
+export default __t.row({
+  id: __t.u64().primaryKey(),
+  keyHash: __t.string().name("key_hash"),
+  parentFlowId: __t.u64().name("parent_flow_id"),
+  name: __t.string(),
+  path: __t.string(),
+  status: __t.string(),
+  timeoutSeconds: __t.u64().name("timeout_seconds"),
+  createdAt: __t.timestamp().name("created_at"),
+  finishedAt: __t.u64().name("finished_at"),
+  exportToken: __t.string().name("export_token"),
+});