@radishbot/sdk 0.3.1 → 0.5.0

package/README.md

@@ -139,6 +139,34 @@ action.info("continuing from service B");
 await action.finish();
 ```
 
+## Run ID
+
+Every `RL()` call auto-generates a **run ID** — a short random string that groups flows across processes. Pass it to subprocesses via env vars, CLI args, or message queues so all flows from one logical execution link together.
+
+```ts
+const root = await RL(key);
+
+// Pass to subprocess
+spawn("worker.ts", { env: { ...process.env, RADISH_RUN_ID: root.runId } });
+
+// In the subprocess — same run ID groups them together
+const worker = await RL(key, { runId: process.env.RADISH_RUN_ID });
+worker.info("processing");
+await worker.finishAndDisconnect();
+```
+
+You can also generate a run ID upfront:
+
+```ts
+import { generateRunId } from "@radishbot/sdk";
+const runId = generateRunId();
+// pass to multiple services
+const a = await RL(key, { runId });
+const b = await RL(key, { runId });
+```
+
+In the dashboard, click a run ID badge to filter all flows from that run.
+
 ## Release Tracking
 
 Tag every flow with a version or commit SHA. Errors are tracked per-release, and regressions (errors reappearing after being resolved) are detected automatically.
@@ -181,6 +209,7 @@ const root = await RL(key, {
   defaultTimeout: 100, // seconds, default 100
   release: "v1.0.0", // version or commit SHA
   retention: "30d", // data retention period
+  runId: "abc123", // optional, auto-generated if omitted
 });
 ```
 
@@ -204,12 +233,16 @@ Actions that exceed their timeout are automatically marked as timed out.
 
 ### `RL(secretKey, options?) → Promise<Flow>`
 
-Connect and create a root action. Options: `host`, `dbName`, `defaultTimeout`, `release`, `retention`.
+Connect and create a root action. Options: `host`, `dbName`, `defaultTimeout`, `release`, `retention`, `runId`.
 
 ### `generateKey() → string`
 
 Generate a random secret key (prefix `rl_`).
 
+### `generateRunId() → string`
+
+Generate a random run ID. Useful when you want to create the ID before calling `RL()`.
+
 ### `restoreFlow(secretKey, handle, options?) → Promise<Flow>`
 
 Restore an action from an exported handle string.
@@ -228,4 +261,5 @@ Restore an action from an exported handle string.
 | `.debug(msg, data?)`       | Log at debug level.                                                |
 | `.log(msg, data?, level?)` | Log at any level.                                                  |
 | `.exportID()`              | Export handle for cross-context restore.                           |
+| `.runId`                   | The run ID (read-only). Pass to subprocesses.                      |
 | `.getId()`                 | Get server-assigned action ID.                                     |

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/connection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SpacetimeDB connection wrapper for the Radish SDK.
+ * Uses the generated bindings + SpacetimeDB WebSocket client.
+ */
+import { DbConnection as StdbConnection } from './module_bindings';
+export declare class SdkConnection {
+    private _host;
+    private _dbName;
+    private _conn;
+    private _connectPromise;
+    private _timeoutInterval;
+    private _keyHash;
+    private _flowWaiters;
+    constructor(host: string, dbName: string);
+    setKeyHash(keyHash: string): void;
+    connect(): Promise<StdbConnection>;
+    get conn(): StdbConnection;
+    /**
+     * Call a reducer and wait for the flow to appear in the subscription.
+     * Returns the server-assigned flow ID.
+     */
+    createFlowAndResolveId(reducerCall: () => void, exportToken: string): Promise<bigint>;
+    disconnect(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export type LogLevel = "info" | "warn" | "error" | "debug";
+
+export declare class Flow {
+  readonly runId: string;
+  log(message: string, data?: unknown, level?: LogLevel): this;
+  info(message: string, data?: unknown): this;
+  warn(message: string, data?: unknown): this;
+  error(message: string, data?: unknown): this;
+  debug(message: string, data?: unknown): this;
+  action(name: string, timeoutSeconds?: number): Flow;
+  flow(name: string, timeoutSeconds?: number): Flow;
+  a<T>(name: string, fn: (action: Flow) => T | Promise<T>, timeoutSeconds?: number): Promise<T>;
+  finish(): Promise<void>;
+  finishWithError(err?: Error | string): Promise<void>;
+  exportID(): Promise<string>;
+  getId(): Promise<bigint>;
+  disconnect(): void;
+  finishAndDisconnect(): Promise<void>;
+}
+
+export interface RLOptions {
+  host?: string;
+  dbName?: string;
+  label?: string;
+  defaultTimeout?: number;
+  release?: string;
+  retention?: string;
+  runId?: string;
+}
+
+export declare function RL(secretKey: string, options?: RLOptions): Promise<Flow>;
+export declare function restoreFlow(secretKey: string, exportedId: string, options?: RLOptions): Promise<Flow>;
+export declare function generateKey(): string;
+export declare function generateRunId(): string;