@ironflow/node 0.7.0 → 0.8.0

package/README.md

@@ -1,99 +1,1194 @@
 # @ironflow/node
 
-Node.js SDK for [Ironflow](https://github.com/sahina/ironflow), an event-driven backend platform. Provides workers, serve handlers, step execution, projections, entity streams, KV store, and config management.
+Node.js SDK for [Ironflow](https://github.com/sahina/ironflow), an event-driven backend platform. Provides workers (pull mode), serve handlers (push mode), step execution, projections, entity streams, subscriptions, KV store, config management, webhooks, auth management, and testing utilities.
+
+This is a **private** npm package (`"access": "restricted"`).
 
 ## Installation
 
-```bash
-npm install @ironflow/node
+```bash
+npm install @ironflow/node
+```
+
+Requires Node.js 22+.
+
+## Table of Contents
+
+1. [Defining Functions](#defining-functions)
+2. [Step Primitives](#step-primitives)
+3. [Saga Compensation](#saga-compensation)
+4. [Push Mode (serve)](#push-mode-serve)
+5. [Pull Mode (createWorker)](#pull-mode-createworker)
+6. [Streaming Worker](#streaming-worker)
+7. [Server-Side Client](#server-side-client)
+8. [Entity Streams](#entity-streams)
+9. [KV Store](#kv-store)
+10. [Config Management](#config-management)
+11. [Auth Management](#auth-management)
+12. [Subscriptions](#subscriptions)
+13. [Projections](#projections)
+14. [Webhooks](#webhooks)
+15. [Event Versioning (Upcasters)](#event-versioning-upcasters)
+16. [Error Handling](#error-handling)
+17. [Environment Variables](#environment-variables)
+18. [Testing](#testing)
+
+---
+
+## Defining Functions
+
+Use `createFunction(config, handler)` to define a workflow function. The function is triggered by events and executes durable steps.
+
+### Basic function (untyped)
+
+```typescript
+import { createFunction } from '@ironflow/node';
+
+const processOrder = createFunction(
+  {
+    id: 'process-order',
+    triggers: [{ event: 'order.placed' }],
+  },
+  async ({ event, step }) => {
+    const validated = await step.run('validate', async () => {
+      return validateOrder(event.data);
+    });
+    return { success: true, orderId: validated.orderId };
+  }
+);
+```
+
+### With Zod schema validation
+
+When you provide a `schema`, `event.data` is fully typed from the schema.
+
+```typescript
+import { createFunction } from '@ironflow/node';
+import { z } from 'zod';
+
+const OrderSchema = z.object({
+  orderId: z.string(),
+  amount: z.number(),
+  customerId: z.string(),
+});
+
+const processOrder = createFunction(
+  {
+    id: 'process-order',
+    triggers: [{ event: 'order.placed' }],
+    schema: OrderSchema,
+  },
+  async ({ event, step }) => {
+    // event.data is typed as { orderId: string; amount: number; customerId: string }
+    const receipt = await step.run('charge', async () => {
+      return chargeCard(event.data.customerId, event.data.amount);
+    });
+    return { receiptId: receipt.id };
+  }
+);
+```
+
+### FunctionConfig reference
+
+All fields on the config object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | **Required.** Unique function identifier. |
+| `name` | `string` | Display name. Defaults to `id`. |
+| `triggers` | `Trigger[]` | **Required.** Array of event triggers. |
+| `retry` | `RetryConfig` | Retry policy for failed steps. |
+| `timeout` | `number` | Function timeout in milliseconds (default: 600000 = 10 min). |
+| `concurrency` | `ConcurrencyConfig` | Concurrency control. |
+| `mode` | `"push" \| "pull"` | Preferred execution mode. |
+| `actorKey` | `string` | JSON path for actor-based sticky routing (e.g., `"event.data.customerId"`). |
+| `schema` | `ZodType` | Zod schema for event data validation and type inference. |
+| `secrets` | `string[]` | Secret names this function requires (resolved by the engine). |
+| `stepTimeout` | `string` | Default timeout for all `step.run()` calls (e.g., `"30s"`, `"5m"`). |
+| `recording` | `boolean` | Enable audit recording for this function. |
+| `recordingRetention` | `string` | Retention period for audit events (`"7d"`, `"30d"`, `"90d"`, `"forever"`). |
+
+**Trigger** fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `event` | `string` | Event name pattern (e.g., `"order.placed"`). |
+| `expression` | `string` | Optional CEL expression for filtering. |
+| `cron` | `string` | Cron schedule (e.g., `"0 9 * * *"` for 9am daily). |
+
+**RetryConfig** fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `maxAttempts` | `number` | `3` | Maximum retry attempts. |
+| `initialDelayMs` | `number` | `1000` | Initial delay between retries. |
+| `backoffFactor` | `number` | `2.0` | Backoff multiplier. |
+| `maxDelayMs` | `number` | `300000` | Maximum delay between retries. |
+
+**ConcurrencyConfig** fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `limit` | `number` | Maximum concurrent executions. |
+| `key` | `string` | JSON path for grouping (e.g., `"event.data.customerId"`). |
+
+### Full config example
+
+```typescript
+const processOrder = createFunction(
+  {
+    id: 'process-order',
+    name: 'Process Order',
+    triggers: [
+      { event: 'order.placed' },
+      { event: 'order.retry', expression: 'event.data.priority > 5' },
+      { cron: '0 */6 * * *', event: 'scheduled.cleanup' },
+    ],
+    retry: { maxAttempts: 5, initialDelayMs: 2000, backoffFactor: 3 },
+    timeout: 300000,
+    concurrency: { limit: 10, key: 'event.data.customerId' },
+    mode: 'pull',
+    actorKey: 'event.data.customerId',
+    schema: OrderSchema,
+    secrets: ['STRIPE_SECRET_KEY', 'SENDGRID_API_KEY'],
+    stepTimeout: '30s',
+    recording: true,
+    recordingRetention: '30d',
+  },
+  async ({ event, step, secrets }) => {
+    const apiKey = secrets.get('STRIPE_SECRET_KEY');
+    // ...
+  }
+);
+```
+
+---
+
+## Step Primitives
+
+Every step is durable and memoized. If the workflow retries, previously completed steps are skipped and their stored results are returned.
+
+### step.run(name, fn, options?)
+
+Execute a memoized step. Use for any non-idempotent operation (API calls, payments, emails).
+
+```typescript
+const processOrder = createFunction(
+  { id: 'process-order', triggers: [{ event: 'order.placed' }] },
+  async ({ event, step }) => {
+    // Basic usage
+    const result = await step.run('charge-card', async () => {
+      return chargeCard(event.data.amount);
+    });
+
+    // With timeout override
+    const enriched = await step.run('enrich-data', async () => {
+      return callSlowApi(event.data.id);
+    }, { timeout: '60s' });
+
+    return { transactionId: result.id, enriched };
+  }
+);
+```
+
+**Options:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timeout` | `string` | Step timeout (e.g., `"30s"`, `"5m"`, `"1h"`). Overrides function-level `stepTimeout`. |
+
+### step.sleep(name, duration)
+
+Durable sleep that survives process restarts and server upgrades.
+
+```typescript
+const delayedNotification = createFunction(
+  { id: 'delayed-notify', triggers: [{ event: 'user.signup' }] },
+  async ({ event, step }) => {
+    await step.run('send-welcome', async () => {
+      return sendWelcomeEmail(event.data.email);
+    });
+
+    // Durable sleep - workflow pauses and resumes after duration
+    await step.sleep('wait-for-trial', '7d');
+
+    await step.run('send-trial-ending', async () => {
+      return sendTrialEndingEmail(event.data.email);
+    });
+  }
+);
+```
+
+**Duration formats:** `"30s"`, `"5m"`, `"1h"`, `"7d"`, or milliseconds as a number.
+
+### step.sleepUntil(name, date)
+
+Sleep until a specific point in time.
+
+```typescript
+const scheduledTask = createFunction(
+  { id: 'scheduled-task', triggers: [{ event: 'task.scheduled' }] },
+  async ({ event, step }) => {
+    // Sleep until a specific Date object
+    await step.sleepUntil('wait-until-date', new Date('2025-12-31T00:00:00Z'));
+
+    // Or an ISO string
+    await step.sleepUntil('wait-until-deadline', event.data.deadline);
+
+    await step.run('execute', async () => {
+      return executeTask(event.data.taskId);
+    });
+  }
+);
+```
+
+### step.waitForEvent(name, filter)
+
+Wait for an external event to arrive. The workflow pauses durably until a matching event is emitted.
+
+```typescript
+const approvalWorkflow = createFunction(
+  { id: 'approval-flow', triggers: [{ event: 'approval.requested' }] },
+  async ({ event, step }) => {
+    await step.run('notify-approver', async () => {
+      return sendApprovalRequest(event.data.approverId);
+    });
+
+    // Wait for the approval event (default timeout: 7 days)
+    const approval = await step.waitForEvent('wait-approval', {
+      event: 'approval.received',
+      match: 'data.requestId',  // JSON path for matching
+      timeout: '48h',
+    });
+
+    if (approval.data.approved) {
+      await step.run('process-approved', async () => {
+        return processApproval(event.data.requestId);
+      });
+    }
+
+    return { approved: approval.data.approved };
+  }
+);
+```
+
+**EventFilter fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `event` | `string` | -- | Event name to wait for. |
+| `match` | `string` | -- | JSON path for correlating events. |
+| `timeout` | `Duration` | `"7d"` | How long to wait before timing out. |
+
+### step.invoke(functionId, input?, options?)
+
+Call another Ironflow function and wait for its result. Creates a child run.
+
+```typescript
+const orchestrator = createFunction(
+  { id: 'orchestrator', triggers: [{ event: 'workflow.start' }] },
+  async ({ event, step }) => {
+    // Invoke and wait for result (default timeout: 30s)
+    const result = await step.invoke('process-payment', {
+      orderId: event.data.orderId,
+      amount: event.data.amount,
+    });
+
+    // With custom timeout
+    const report = await step.invoke('generate-report', {
+      orderId: event.data.orderId,
+    }, { timeout: '5m' });
+
+    return { paymentResult: result, report };
+  }
+);
+```
+
+### step.invokeAsync(functionId, input?)
+
+Fire-and-forget: trigger another function without waiting for its result. Returns the child run ID.
+
+```typescript
+const orderPipeline = createFunction(
+  { id: 'order-pipeline', triggers: [{ event: 'order.placed' }] },
+  async ({ event, step }) => {
+    // Fire and forget - does not block
+    const { runId } = await step.invokeAsync('send-confirmation-email', {
+      orderId: event.data.orderId,
+      email: event.data.email,
+    });
+
+    return { emailRunId: runId };
+  }
+);
+```
+
+### step.parallel(name, branches, options?)
+
+Execute multiple branches in parallel. Each branch receives its own scoped `step` client with isolated step IDs.
+
+```typescript
+const enrichUser = createFunction(
+  { id: 'enrich-user', triggers: [{ event: 'user.created' }] },
+  async ({ event, step }) => {
+    const [profile, creditScore, preferences] = await step.parallel(
+      'fetch-all',
+      [
+        async (s) => s.run('fetch-profile', () => fetchProfile(event.data.userId)),
+        async (s) => s.run('fetch-credit', () => fetchCreditScore(event.data.userId)),
+        async (s) => s.run('fetch-prefs', () => fetchPreferences(event.data.userId)),
+      ]
+    );
+
+    return { profile, creditScore, preferences };
+  }
+);
+```
+
+**ParallelOptions:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `concurrency` | `number` | unlimited | Maximum concurrent branches. |
+| `onError` | `"failFast" \| "allSettled"` | `"failFast"` | `"failFast"`: first failure cancels pending branches. `"allSettled"`: all branches complete, errors in results. |
+
+```typescript
+// With concurrency limit and allSettled error handling
+const results = await step.parallel(
+  'batch-process',
+  items.map((item) => async (s) => {
+    return s.run(`process-${item.id}`, () => processItem(item));
+  }),
+  { concurrency: 5, onError: 'allSettled' }
+);
+```
+
+### step.map(name, items, fn, options?)
+
+Parallel map over an array of items. Convenience wrapper around `step.parallel`.
+
+```typescript
+const batchProcessor = createFunction(
+  { id: 'batch-process', triggers: [{ event: 'batch.ready' }] },
+  async ({ event, step }) => {
+    const results = await step.map(
+      'process-items',
+      event.data.items,
+      async (item, s, index) => {
+        return s.run(`process-${index}`, () => processItem(item));
+      },
+      { concurrency: 3 }
+    );
+
+    return { processed: results.length };
+  }
+);
+```
+
+### step.compensate(stepName, fn)
+
+Register a compensation function (saga rollback) for a previously completed step. Compensations run automatically in reverse order on terminal (non-retryable) failures.
+
+```typescript
+const transferFunds = createFunction(
+  { id: 'transfer-funds', triggers: [{ event: 'transfer.requested' }] },
+  async ({ event, step }) => {
+    const debit = await step.run('debit', async () => {
+      return debitAccount(event.data.fromAccount, event.data.amount);
+    });
+    step.compensate('debit', async () => {
+      await creditAccount(event.data.fromAccount, event.data.amount);
+    });
+
+    const credit = await step.run('credit', async () => {
+      return creditAccount(event.data.toAccount, event.data.amount);
+    });
+    step.compensate('credit', async () => {
+      await debitAccount(event.data.toAccount, event.data.amount);
+    });
+
+    return { debitRef: debit.ref, creditRef: credit.ref };
+  }
+);
+```
+
+### step.publish(topic, data)
+
+Publish a message to a developer pub/sub topic. The publish is memoized like any other step.
+
+```typescript
+const orderProcessor = createFunction(
+  { id: 'order-processor', triggers: [{ event: 'order.placed' }] },
+  async ({ event, step }) => {
+    const result = await step.run('process', async () => {
+      return processOrder(event.data);
+    });
+
+    // Publish to a topic (does NOT trigger workflow functions)
+    await step.publish('order-notifications', {
+      orderId: event.data.orderId,
+      status: 'processed',
+    });
+
+    return result;
+  }
+);
+```
+
+---
+
+## Saga Compensation
+
+Compensations provide automatic rollback for distributed transactions. When a terminal (non-retryable) failure occurs, all registered compensations run in reverse order. Each compensation is itself a durable, memoized step.
+
+```typescript
+import { createFunction, NonRetryableError } from '@ironflow/node';
+
+const bookTrip = createFunction(
+  { id: 'book-trip', triggers: [{ event: 'trip.requested' }] },
+  async ({ event, step }) => {
+    // Step 1: Book flight
+    const flight = await step.run('book-flight', async () => {
+      return bookFlight(event.data.flightId);
+    });
+    step.compensate('book-flight', async () => {
+      await cancelFlight(flight.confirmationId);
+    });
+
+    // Step 2: Book hotel
+    const hotel = await step.run('book-hotel', async () => {
+      return bookHotel(event.data.hotelId, event.data.dates);
+    });
+    step.compensate('book-hotel', async () => {
+      await cancelHotel(hotel.confirmationId);
+    });
+
+    // Step 3: Book car rental (if this fails with a non-retryable error,
+    // both hotel and flight compensations run in reverse order)
+    const car = await step.run('book-car', async () => {
+      const result = await bookCar(event.data.carId);
+      if (!result.available) {
+        throw new NonRetryableError('Car not available');
+      }
+      return result;
+    });
+    step.compensate('book-car', async () => {
+      await cancelCar(car.confirmationId);
+    });
+
+    return { flight, hotel, car };
+  }
+);
+```
+
+Key behaviors:
+- Compensations only run on **terminal** (non-retryable) failures.
+- They run in **reverse registration order** (last registered runs first).
+- Each compensation is recorded as a durable step (`compensate:<stepName>`).
+- If a compensation itself fails, the error is logged but remaining compensations still run.
+
+---
+
+## Push Mode (serve)
+
+The `serve()` function creates a universal HTTP handler for serverless deployment. It works with any framework that uses the Fetch `Request`/`Response` API or Node.js `IncomingMessage`/`ServerResponse`.
+
+### ServeConfig reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `functions` | `IronflowFunction[]` | **Required.** Functions to handle. |
+| `projections` | `IronflowProjection[]` | Logs a warning -- use `createWorker` for projections. |
+| `signingKey` | `string` | HMAC-SHA256 signing key for request verification. |
+| `skipVerification` | `boolean` | Skip signature verification (dev only). |
+| `logger` | `Logger \| false` | Custom logger or `false` to disable. |
+| `environment` | `string` | Target environment (default: `IRONFLOW_ENV` or `"default"`). |
+| `eventDefinitions` | `EventDefinitionRegistry` | Registry for automatic event upcasting. |
+| `serverUrl` | `string` | Ironflow server URL (for emitting webhook events). |
+| `webhooks` | `IronflowWebhook[]` | Webhook sources to handle. |
+
+### Next.js App Router
+
+```typescript
+// app/api/ironflow/route.ts
+import { serve } from '@ironflow/node';
+import { processOrder } from '@/functions/process-order';
+
+export const POST = serve({
+  functions: [processOrder],
+  signingKey: process.env.IRONFLOW_SIGNING_KEY,
+});
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { serve } from '@ironflow/node';
+import { processOrder } from './functions/process-order.js';
+
+const app = express();
+
+app.post('/api/ironflow', serve({
+  functions: [processOrder],
+  signingKey: process.env.IRONFLOW_SIGNING_KEY,
+}));
+
+app.listen(3000);
+```
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { serve } from '@ironflow/node';
+import { processOrder } from './functions/process-order.js';
+
+const app = new Hono();
+
+app.post('/api/ironflow', serve({
+  functions: [processOrder],
+  signingKey: process.env.IRONFLOW_SIGNING_KEY,
+}));
+
+export default app;
+```
+
+---
+
+## Pull Mode (createWorker)
+
+Workers poll the Ironflow server for jobs via REST HTTP. Use for long-running tasks with no timeout limits.
+
+### WorkerConfig reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `serverUrl` | `string` | `http://localhost:9123` | Ironflow server URL. |
+| `functions` | `IronflowFunction[]` | -- | **Required.** Functions this worker handles. |
+| `projections` | `IronflowProjection[]` | -- | Projections to run alongside functions. |
+| `maxConcurrentJobs` | `number` | `10` | Maximum concurrent job executions. |
+| `heartbeatInterval` | `number` | `30000` | Heartbeat interval in ms. |
+| `reconnectDelay` | `number` | `5000` | Reconnect delay in ms. |
+| `labels` | `Record<string, string>` | -- | Worker labels for routing. |
+| `transport` | `"polling" \| "streaming"` | `"polling"` | Transport type. |
+| `logger` | `Logger \| false` | -- | Custom logger or `false` to disable. |
+| `environment` | `string` | `IRONFLOW_ENV` or `"default"` | Target environment. |
+| `eventDefinitions` | `EventDefinitionRegistry` | -- | Registry for automatic event upcasting. |
+| `apiKey` | `string` | `IRONFLOW_API_KEY` env | API key for authentication. |
+
+### Worker interface
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Start the worker. Blocks until stopped. Auto-reconnects on failure. |
+| `drain()` | Gracefully drain: stop accepting new jobs, wait for active jobs to complete, then stop. |
+| `stop()` | Force stop immediately. Cancels all active jobs. |
+
+```typescript
+import { createWorker } from '@ironflow/node';
+import { processOrder, sendNotification } from './functions.js';
+import { orderTotals } from './projections.js';
+
+const worker = createWorker({
+  serverUrl: 'http://localhost:9123',
+  functions: [processOrder, sendNotification],
+  projections: [orderTotals],
+  maxConcurrentJobs: 20,
+  labels: { region: 'us-east-1' },
+  apiKey: process.env.IRONFLOW_API_KEY,
+});
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await worker.drain();
+  process.exit(0);
+});
+
+await worker.start();
+```
+
+---
+
+## Streaming Worker
+
+For low-latency bidirectional streaming via ConnectRPC. Same `WorkerConfig` as `createWorker`, but uses gRPC bidirectional streaming instead of HTTP polling.
+
+Import from the separate `@ironflow/node/worker-streaming` entry point to avoid loading protobuf dependencies unless needed.
+
+```typescript
+import { createStreamingWorker } from '@ironflow/node/worker-streaming';
+import { processOrder } from './functions.js';
+
+const worker = createStreamingWorker({
+  serverUrl: 'http://localhost:9123',
+  functions: [processOrder],
+  maxConcurrentJobs: 10,
+});
+
+process.on('SIGTERM', async () => {
+  await worker.drain();
+  process.exit(0);
+});
+
+await worker.start();
+```
+
+Requires optional dependencies: `@bufbuild/protobuf`, `@connectrpc/connect`, `@connectrpc/connect-node`.
+
+---
+
+## Server-Side Client
+
+The HTTP client for interacting with the Ironflow server from your backend code.
+
+### IronflowClientConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `serverUrl` | `string` | `http://localhost:9123` or `IRONFLOW_SERVER_URL` | Server URL. |
+| `apiKey` | `string` | -- | API key for authentication. |
+| `timeout` | `number` | `30000` | Request timeout in ms. |
+
+### Creating a client
+
+```typescript
+import { createClient } from '@ironflow/node';
+
+const client = createClient({
+  serverUrl: 'http://localhost:9123',
+  apiKey: process.env.IRONFLOW_API_KEY,
+});
+```
+
+### emit(eventName, data, options?)
+
+Emit an event to trigger workflow functions.
+
+```typescript
+const result = await client.emit('order.placed', {
+  orderId: '123',
+  amount: 99.99,
+});
+console.log('Run IDs:', result.runIds);
+console.log('Event ID:', result.eventId);
+```
+
+**EmitOptions:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `number` | Event schema version (default: 1). |
+| `idempotencyKey` | `string` | Prevent duplicate processing. |
+| `metadata` | `Record<string, unknown>` | Additional metadata. |
+
+```typescript
+await client.emit('order.placed', { orderId: '123' }, {
+  version: 2,
+  idempotencyKey: 'order-123-placed',
+  metadata: { source: 'api', traceId: 'abc' },
+});
+```
+
+### trigger(eventName, data, options?)
+
+Deprecated alias for `emit()`. Use `emit()` instead.
+
+### getRun(runId)
+
+Get a run by its ID.
+
+```typescript
+const run = await client.getRun('run_abc123');
+console.log(run.status);    // "completed" | "running" | "failed" | "cancelled" | ...
+console.log(run.output);    // Function return value (if completed)
+console.log(run.error);     // { message, code } (if failed)
+```
+
+### listRuns(options?)
+
+List runs with optional filtering and pagination.
+
+```typescript
+const result = await client.listRuns({
+  functionId: 'process-order',
+  status: 'failed',
+  limit: 25,
+  cursor: 'next_page_cursor',
+});
+console.log(result.runs);       // Run[]
+console.log(result.totalCount); // number
+console.log(result.nextCursor); // string | undefined
+```
+
+### cancelRun(runId, reason?)
+
+Cancel a running workflow.
+
+```typescript
+const run = await client.cancelRun('run_abc123', 'no longer needed');
+```
+
+### retryRun(runId, fromStep?)
+
+Retry a failed run, optionally from a specific step.
+
+```typescript
+await client.retryRun('run_abc123');
+await client.retryRun('run_abc123', 'validate'); // Retry from specific step
+```
+
+### resumeRun(runId, fromStep?)
+
+Resume a paused or failed run.
+
+```typescript
+await client.resumeRun('run_abc123');
+await client.resumeRun('run_abc123', 'charge-card');
+```
+
+### patchStep(stepId, output, reason?)
+
+Hot-patch a step's output. Useful for debugging or correcting bad data.
+
+```typescript
+await client.patchStep('step_xyz', { correctedValue: 42 }, 'fix bad data');
+```
+
+### listFunctions()
+
+List all registered functions.
+
+```typescript
+const functions = await client.listFunctions();
+```
+
+### listWorkers()
+
+List all connected workers.
+
+```typescript
+const workers = await client.listWorkers();
+```
+
+### health()
+
+Server health check. Returns the status string.
+
+```typescript
+const status = await client.health();
+console.log(status); // "ok"
+```
+
+### publish(topic, data, options?)
+
+Publish a message to a developer pub/sub topic. Unlike `emit()`, this does **not** trigger workflow functions.
+
+```typescript
+const result = await client.publish('notifications', {
+  userId: '123',
+  message: 'Hello!',
+});
+console.log(result.eventId);  // string
+console.log(result.sequence); // number
+```
+
+**PublishOptions:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `idempotencyKey` | `string` | Prevent duplicate publishing. |
+
+### listTopics()
+
+List all active developer pub/sub topics.
+
+```typescript
+const topics = await client.listTopics();
+for (const t of topics) {
+  console.log(t.name, t.messageCount, t.consumerCount);
+}
+```
+
+### getTopicStats(topic)
+
+Get detailed statistics for a specific topic.
+
+```typescript
+const stats = await client.getTopicStats('notifications');
+console.log('Messages:', stats.messageCount);
+console.log('Lag:', stats.lag);
+console.log('Consumers:', stats.consumerCount);
+console.log('First seq:', stats.firstSeq, 'Last seq:', stats.lastSeq);
+```
+
+---
+
+## Entity Streams
+
+Event sourcing primitives via `client.streams`. Append domain events per entity, read them back, and use optimistic concurrency.
+
+### streams.append(entityId, input, options?)
+
+Append an event to an entity stream.
+
+```typescript
+const client = createClient({ serverUrl: 'http://localhost:9123' });
+
+const result = await client.streams.append('order-123', {
+  name: 'item.added',
+  data: { sku: 'ABC', qty: 2 },
+  entityType: 'order',
+});
+console.log(result.entityVersion); // number
+console.log(result.eventId);      // string
+```
+
+### Optimistic concurrency with expectedVersion
+
+```typescript
+// Read current version
+const info = await client.streams.getInfo('order-123');
+
+// Append with version check (fails if another writer modified the stream)
+try {
+  await client.streams.append('order-123', {
+    name: 'item.removed',
+    data: { sku: 'ABC' },
+    entityType: 'order',
+  }, { expectedVersion: info.version });
+} catch (err) {
+  console.error('Concurrent modification detected');
+}
 ```
 
-## Quick Start
+**AppendOptions:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `expectedVersion` | `number` | Optimistic concurrency check. |
+| `idempotencyKey` | `string` | Prevent duplicate appends. |
+| `version` | `number` | Event schema version (default: 1). |
 
-### Define a Function
+### streams.read(entityId, options?)
+
+Read events from an entity stream.
 
 ```typescript
-import { ironflow } from '@ironflow/node';
+const { events, totalCount } = await client.streams.read('order-123', {
+  direction: 'forward',  // "forward" | "backward"
+  fromVersion: 0,
+  limit: 50,
+});
 
-const processOrder = ironflow.createFunction(
-  {
-    id: 'process-order',
-    triggers: [{ event: 'order.placed' }],
-  },
-  async ({ event, step }) => {
-    const validated = await step.run('validate', async () => {
-      return validateOrder(event.data);
-    });
+for (const event of events) {
+  console.log(event.name, event.data, event.entityVersion);
+}
+```
 
-    await step.sleep('wait', '5m');
+### streams.getInfo(entityId)
 
-    const result = await step.run('process', async () => {
-      return processPayment(validated);
-    });
+Get metadata about an entity stream.
 
-    return { success: true, receiptId: result.id };
-  }
-);
+```typescript
+const info = await client.streams.getInfo('order-123');
+console.log(info.entityId);    // "order-123"
+console.log(info.entityType);  // "order"
+console.log(info.version);     // current version number
+console.log(info.eventCount);  // total events
+console.log(info.createdAt);   // ISO string
+console.log(info.updatedAt);   // ISO string
+```
+
+---
+
+## KV Store
+
+Distributed key-value storage with bucket management, CAS (compare-and-swap), TTL, and wildcard key listing.
+
+### Getting a KV client
+
+```typescript
+const client = createClient({ serverUrl: 'http://localhost:9123' });
+const kv = client.kv();
 ```
 
-### Push Mode (Serverless)
+### Bucket management
 
 ```typescript
-// app/api/ironflow/route.ts (Next.js App Router)
-import { serve } from '@ironflow/node';
+// Create a bucket with TTL
+await kv.createBucket({ name: 'sessions', ttlSeconds: 3600 });
 
-export const POST = serve({
-  functions: [processOrder],
-  signingKey: process.env.IRONFLOW_SIGNING_KEY,
-});
+// List all buckets
+const buckets = await kv.listBuckets();
+
+// Get bucket info
+const info = await kv.getBucketInfo('sessions');
+
+// Delete a bucket
+await kv.deleteBucket('sessions');
 ```
 
-### Pull Mode (Worker)
+**KVBucketConfig:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Bucket name. |
+| `description` | `string` | Optional description. |
+| `ttlSeconds` | `number` | Time-to-live for keys in seconds. |
+| `maxValueSize` | `number` | Maximum value size in bytes. |
+| `maxBytes` | `number` | Maximum total bucket size. |
+| `history` | `number` | Number of historical revisions to keep. |
+
+### Key operations
 
 ```typescript
-import { createWorker } from '@ironflow/node';
+const bucket = kv.bucket('sessions');
 
-const worker = createWorker({
+// Put a value (unconditional write)
+const { revision } = await bucket.put('user-123', { token: 'abc', role: 'admin' });
+
+// Get a value
+const entry = await bucket.get('user-123');
+console.log(entry.value);    // the stored value
+console.log(entry.revision); // revision number for CAS
+
+// Create only if key doesn't exist (throws HTTP 412 on conflict)
+await bucket.create('user-456', { token: 'def' });
+
+// Compare-and-swap update (throws HTTP 412 on revision mismatch)
+await bucket.update('user-123', { token: 'xyz', role: 'admin' }, entry.revision);
+
+// Soft delete (tombstone)
+await bucket.delete('user-123');
+
+// Purge key and all history
+await bucket.purge('user-123');
+
+// List keys with optional wildcard filter
+const keys = await bucket.listKeys('user-*');
+const allKeys = await bucket.listKeys();
+```
+
+---
+
+## Config Management
+
+Centralized configuration store with set, get, patch (shallow merge), list, and delete.
+
+```typescript
+const client = createClient({ serverUrl: 'http://localhost:9123' });
+const config = client.config();
+
+// Set a config (full replacement)
+await config.set('app-settings', { theme: 'dark', locale: 'en', maxRetries: 3 });
+
+// Get a config
+const settings = await config.get('app-settings');
+console.log(settings.data); // { theme: 'dark', locale: 'en', maxRetries: 3 }
+
+// Patch a config (shallow merge)
+await config.patch('app-settings', { locale: 'fr' });
+// Result: { theme: 'dark', locale: 'fr', maxRetries: 3 }
+
+// List all configs
+const all = await config.list();
+for (const entry of all) {
+  console.log(entry.name, entry.data);
+}
+
+// Delete a config (idempotent)
+await config.delete('app-settings');
+```
+
+---
+
+## Auth Management
+
+### API Keys
+
+```typescript
+const client = createClient({
   serverUrl: 'http://localhost:9123',
-  functions: [processOrder],
-  maxConcurrentJobs: 10,
+  apiKey: process.env.IRONFLOW_API_KEY,
 });
 
-await worker.start();
+// Create an API key
+const newKey = await client.apiKeys.create({ name: 'ci-key', envId: 'env_default' });
+console.log(newKey.secret); // Only returned on create/rotate
+
+// List all API keys
+const keys = await client.apiKeys.list();
+
+// Get a specific key
+const key = await client.apiKeys.get(keys[0].id);
+
+// Rotate (generates new secret)
+const rotated = await client.apiKeys.rotate(key.id);
+console.log(rotated.secret);
+
+// Delete
+await client.apiKeys.delete(key.id);
 ```
 
-### Streaming Worker (ConnectRPC)
+### Organizations (Enterprise)
 
-For low-latency bidirectional streaming via ConnectRPC:
+Requires an enterprise license.
 
 ```typescript
-import { createStreamingWorker } from '@ironflow/node/worker-streaming';
+const org = await client.orgs.create({ name: 'Acme Corp' });
+const orgs = await client.orgs.list();
+const fetched = await client.orgs.get(org.id);
+await client.orgs.update(org.id, { name: 'Acme Inc' });
+await client.orgs.delete(org.id);
+```
 
-const worker = createStreamingWorker({
+### Roles (Enterprise)
+
+```typescript
+const role = await client.roles.create({ name: 'deployer', org_id: orgId });
+const roles = await client.roles.list(orgId);  // optional org filter
+const fetched = await client.roles.get(role.id);
+await client.roles.update(role.id, { name: 'senior-deployer' });
+
+// Assign/remove policies
+await client.roles.assignPolicy(role.id, policyId);
+await client.roles.removePolicy(role.id, policyId);
+
+await client.roles.delete(role.id);
+```
+
+### Policies (Enterprise)
+
+```typescript
+const policy = await client.policies.create({
+  name: 'allow-emit',
+  effect: 'allow',
+  actions: 'emit:*',
+  resources: '*',
+  org_id: orgId,
+});
+const policies = await client.policies.list(orgId);  // optional org filter
+const fetched = await client.policies.get(policy.id);
+await client.policies.update(policy.id, { name: 'allow-all-emit' });
+await client.policies.delete(policy.id);
+```
+
+---
+
+## Subscriptions
+
+Real-time event subscriptions via WebSocket with auto-reconnect, consumer groups, and ackable delivery.
+
+### SubscriptionClientConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `serverUrl` | `string` | -- | **Required.** Server URL (e.g., `"http://localhost:9123"`). |
+| `apiKey` | `string` | -- | API key for authentication. |
+| `environment` | `string` | -- | Environment for scoped subscriptions. |
+| `autoReconnect` | `boolean` | `true` | Enable automatic reconnection. |
+| `reconnectDelay` | `number` | `1000` | Initial reconnect delay in ms. |
+| `maxReconnectDelay` | `number` | `30000` | Maximum reconnect delay in ms. |
+| `reconnectBackoff` | `number` | `1.5` | Reconnect backoff multiplier. |
+| `connectionTimeout` | `number` | `10000` | Connection timeout in ms. |
+
+### Basic subscription
+
+```typescript
+import { createSubscriptionClient } from '@ironflow/node';
+
+const sub = createSubscriptionClient({
   serverUrl: 'http://localhost:9123',
-  functions: [processOrder],
-  maxConcurrentJobs: 10,
+  apiKey: process.env.IRONFLOW_API_KEY,
 });
 
-await worker.start();
+await sub.connect();
+
+// Subscribe with callbacks
+const subscription = await sub.subscribe('events:order.*', {
+  onEvent: (event) => {
+    console.log('Topic:', event.topic);
+    console.log('Data:', event.data);
+  },
+  onError: (err) => console.error(err.message),
+});
+
+// Replay last N events on subscribe
+const replaySubscription = await sub.subscribe('system.run.>', {
+  onEvent: (event) => console.log(event),
+  replay: 100,
+  includeMetadata: true,
+});
+
+// Cleanup
+subscription.unsubscribe();
+sub.close();
+```
+
+### Ackable subscriptions with consumer groups
+
+For load-balanced processing with manual acknowledgment.
+
+```typescript
+const subscription = await sub.subscribe('events:order.*', {
+  consumerGroup: 'order-processors',
+  ackMode: 'manual',
+  onEvent: async (event) => {
+    try {
+      await processOrder(event.data);
+      await subscription.ack(event.eventId!);
+    } catch (err) {
+      // Negative ack with optional redeliver delay in ms
+      await subscription.nak(event.eventId!, 5000);
+    }
+  },
+});
+
+// Terminal ack - message will not be redelivered
+await subscription.term(eventId);
 ```
 
-## Features
+### Connection monitoring
+
+```typescript
+// Global connection state changes
+const unsubscribe = sub.onConnectionChange((state) => {
+  console.log('Connection:', state);
+  // state: "connecting" | "connected" | "disconnected" | "reconnecting"
+});
+
+// Global error handler
+const unsubErr = sub.onError((error) => {
+  console.error('Subscription error:', error.code, error.message);
+});
+
+// Remove listeners
+unsubscribe();
+unsubErr();
+```
 
-- **Durable step execution** with automatic memoization
-- **Push mode** for serverless (Next.js, Lambda, Vercel)
-- **Pull mode** for long-running workers (REST polling or ConnectRPC streaming)
-- **Step primitives**: `run`, `sleep`, `sleepUntil`, `waitForEvent`, `parallel`, `map`
-- **Projections** for building read models from event streams
-- **Entity streams** for event sourcing with optimistic concurrency
-- **KV store** for distributed key-value storage with buckets, CAS (Compare-And-Swap), and TTL
-- **Config management** for centralized configuration
-- **Server-side client** for emitting events, managing runs, and inspecting workers
-- **Type-safe** API with full TypeScript support
+---
 
 ## Projections
 
-Build read models from event streams with managed (pure reducer) or external (side effects) mode:
+Projections build derived state from event streams. Two modes: **managed** (pure reducer maintaining state) and **external** (side effects).
+
+### ProjectionConfig
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | **Required.** Unique projection name. |
+| `events` | `string[]` | **Required.** Events to subscribe to. |
+| `mode` | `"managed" \| "external"` | Auto-detected: `"managed"` if `initialState` is provided, else `"external"`. |
+| `initialState` | `() => TState` | Initial state factory (managed mode). |
+| `handler` | Function | Event handler (signature varies by mode). |
+| `maxRetries` | `number` | Maximum retries per event (default: 3). |
+| `batchSize` | `number` | Events per batch (default: 100). |
+
+### Managed projection (pure reducer)
+
+The handler receives current state and an event, and returns the new state. Ironflow persists the state.
 
 ```typescript
 import { createProjection, createWorker } from '@ironflow/node';
@@ -101,150 +1196,367 @@ import { createProjection, createWorker } from '@ironflow/node';
 const orderTotals = createProjection({
   name: 'order-totals',
   events: ['order.placed', 'order.cancelled'],
-  mode: 'managed',
   initialState: () => ({ total: 0, count: 0 }),
   handler: (state, event) => {
     if (event.name === 'order.placed') {
-      return { total: state.total + event.data.amount, count: state.count + 1 };
+      return {
+        total: state.total + event.data.amount,
+        count: state.count + 1,
+      };
+    }
+    if (event.name === 'order.cancelled') {
+      return {
+        total: state.total - event.data.amount,
+        count: state.count - 1,
+      };
     }
-    return { total: state.total - event.data.amount, count: state.count - 1 };
+    return state;
   },
 });
+```
+
+### External projection (side effects)
+
+The handler receives the event and a context object. Use for sending emails, updating external databases, calling APIs.
+
+```typescript
+const emailNotifier = createProjection({
+  name: 'email-notifier',
+  events: ['order.completed'],
+  handler: async (event, ctx) => {
+    await sendEmail(event.data.email, 'Your order is complete!');
+  },
+});
+```
 
-// Run projections alongside functions in a worker
+### Running projections
+
+Projections run inside a worker, not in push mode.
+
+```typescript
 const worker = createWorker({
   serverUrl: 'http://localhost:9123',
   functions: [processOrder],
-  projections: [orderTotals],
+  projections: [orderTotals, emailNotifier],
 });
-```
 
-## Server-Side Client
+await worker.start();
+```
 
-Use the client to interact with Ironflow from your backend:
+---
 
-```typescript
-import { createClient } from '@ironflow/node';
+## Webhooks
 
-const client = createClient({ serverUrl: 'http://localhost:9123' });
+Receive and transform external HTTP events from third-party services.
 
-// Emit events
-await client.emit('order.placed', { orderId: '123', amount: 99.99 });
+### WebhookConfig
 
-// Trigger workflows
-const run = await client.trigger('process-order', { data: { orderId: '123' } });
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Webhook source identifier (used in URL path). |
+| `verify` | `(req) => void \| Promise<void>` | Verification function. Throw to reject. |
+| `transform` | `(payload) => WebhookEvent` | Transform raw payload to an Ironflow event. |
 
-// Run management
-const runInfo = await client.getRun(run.id);
-const runs = await client.listRuns({ functionId: 'process-order', status: 'failed' });
-await client.cancelRun(run.id, 'no longer needed');
-await client.retryRun(run.id);
-await client.resumeRun(run.id, 'validate');
+### Stripe webhook example
 
-// Hot-patch a step output (debugging)
-await client.patchStep(stepId, { correctedValue: 42 }, 'fix bad data');
+```typescript
+import { createWebhook, serve } from '@ironflow/node';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+const stripeWebhook = createWebhook({
+  id: 'stripe',
+  verify: async (req) => {
+    const sig = req.headers['stripe-signature'];
+    if (!sig) throw new Error('Missing stripe-signature header');
+    // Throws if invalid
+    stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
+  },
+  transform: (payload) => ({
+    name: `stripe.${payload.type}`,
+    data: payload.data.object,
+    idempotencyKey: payload.id,
+  }),
+});
 
-// Server inspection
-const functions = await client.listFunctions();
-const workers = await client.listWorkers();
-const health = await client.health();
+// Webhook endpoint: POST /api/ironflow/webhooks/stripe
+export const POST = serve({
+  functions: [processOrder],
+  webhooks: [stripeWebhook],
+  serverUrl: process.env.IRONFLOW_SERVER_URL,
+});
 ```
 
-## Entity Streams (Event Sourcing)
+The webhook URL path is derived from the `id`: `POST /api/ironflow/webhooks/<id>`.
+
+---
+
+## Event Versioning (Upcasters)
+
+Upcasters transform event data from older schema versions to newer ones. They are applied SDK-side when reading events.
+
+### defineEvent and EventDefinitionRegistry
 
 ```typescript
-const client = createClient({ serverUrl: 'http://localhost:9123' });
+import { defineEvent, createEventDefinitionRegistry } from '@ironflow/core';
 
-// Append events with optimistic concurrency
-await client.streams.append('order-123', {
-  eventName: 'item.added',
-  data: { sku: 'ABC', qty: 2 },
-  expectedVersion: 3,
+// Define event versions with upcasters
+const orderPlacedV1 = defineEvent({
+  name: 'order.placed',
+  version: 1,
 });
 
-// Read events from a stream
-const events = await client.streams.read('order-123', {
-  direction: 'forward',
-  limit: 50,
+const orderPlacedV2 = defineEvent({
+  name: 'order.placed',
+  version: 2,
+  upcast: (data) => ({
+    ...(data as Record<string, unknown>),
+    // v2 adds a currency field with a default
+    currency: (data as Record<string, unknown>).currency ?? 'USD',
+  }),
 });
 
-// Get stream metadata
-const info = await client.streams.getInfo('order-123');
-```
+const orderPlacedV3 = defineEvent({
+  name: 'order.placed',
+  version: 3,
+  upcast: (data) => {
+    const d = data as Record<string, unknown>;
+    return {
+      ...d,
+      // v3 renames "total" to "amount"
+      amount: d.total ?? d.amount,
+      total: undefined,
+    };
+  },
+});
 
-## KV Store
+// Register all versions
+const registry = createEventDefinitionRegistry();
+registry.register(orderPlacedV1);
+registry.register(orderPlacedV2);
+registry.register(orderPlacedV3);
+
+// Pass to worker or serve for automatic upcasting
+const worker = createWorker({
+  serverUrl: 'http://localhost:9123',
+  functions: [processOrder],
+  eventDefinitions: registry,
+});
+```
 
-Distributed key-value storage with bucket management:
+### UpcasterRegistry (lower-level)
 
 ```typescript
-const kv = client.kv();
-
-// Bucket management
-await kv.createBucket({ name: 'sessions', ttl: 3600 });
-const buckets = await kv.listBuckets();
+import { createUpcasterRegistry } from '@ironflow/core';
 
-// Key operations
-const bucket = kv.bucket('sessions');
-await bucket.put('user-123', { token: 'abc', role: 'admin' });
-const entry = await bucket.get('user-123');
+const upcasters = createUpcasterRegistry();
 
-// Compare-and-swap update
-await bucket.update('user-123', { token: 'xyz', role: 'admin' }, entry.revision);
+upcasters.register('order.placed', 1, 2, (data) => ({
+  ...(data as Record<string, unknown>),
+  currency: 'USD',
+}));
 
-// Create only if key doesn't exist
-await bucket.create('user-456', { token: 'def' });
+upcasters.register('order.placed', 2, 3, (data) => {
+  const d = data as Record<string, unknown>;
+  return { ...d, amount: d.total, total: undefined };
+});
 
-// List keys with wildcard filtering
-const keys = await bucket.listKeys({ pattern: 'user-*' });
+// Manually upcast
+const v3Data = upcasters.upcast('order.placed', v1Data, 1, 3);
 ```
 
-## Config Management
+The upcaster chain must be complete. If v2->v3 is registered but v1->v2 is missing, upcasting from v1 to v3 throws an error.
+
+---
+
+## Error Handling
 
-Centralized configuration store:
+All error classes are re-exported from `@ironflow/core`:
+
+| Error Class | Description |
+|-------------|-------------|
+| `IronflowError` | Base error class. Has `code`, `retryable`, `details` properties. |
+| `StepError` | Step execution failure. Has `stepId`, `stepName`. |
+| `TimeoutError` | Request or operation timeout. |
+| `ValidationError` | Input validation failure. |
+| `SchemaValidationError` | Zod schema validation failure. |
+| `SignatureError` | Request signature verification failure. |
+| `FunctionNotFoundError` | Function not found. |
+| `RunNotFoundError` | Run not found. |
+| `NonRetryableError` | Marks an error as non-retryable (triggers compensations). |
+| `UnauthenticatedError` | Missing or invalid authentication (HTTP 401). |
+| `UnauthorizedError` | Insufficient permissions (HTTP 403). |
+| `EnterpriseRequiredError` | Feature requires enterprise license (HTTP 402). |
+
+### Utility functions
 
 ```typescript
-const config = client.config();
+import { isRetryable, isIronflowError, NonRetryableError } from '@ironflow/node';
+
+// Check if an error is retryable
+try {
+  await step.run('api-call', async () => { /* ... */ });
+} catch (err) {
+  if (isRetryable(err)) {
+    console.log('Will be retried');
+  }
+}
 
-await config.set('app-settings', { theme: 'dark', locale: 'en' });
-const settings = await config.get('app-settings');
-await config.patch('app-settings', { locale: 'fr' });  // Shallow merge
-const all = await config.list();
-await config.delete('app-settings');
+// Check if an error is an Ironflow error
+if (isIronflowError(err)) {
+  console.log(err.code, err.retryable);
+}
+
+// Mark an error as non-retryable (stops retries, triggers compensations)
+throw new NonRetryableError('Payment declined - do not retry');
 ```
 
-## Key APIs
-
-| API | Description |
-|-----|-------------|
-| `ironflow.createFunction(config, handler)` | Define a workflow function |
-| `createFunction(config, handler)` | Shorthand function definition |
-| `serve({ functions })` | Create HTTP handler for push mode |
-| `createWorker({ functions, projections? })` | Create pull mode worker |
-| `createStreamingWorker({ functions })` | Create ConnectRPC streaming worker |
-| `createProjection(config)` | Define a projection |
-| `createClient(config)` | Create server-side client |
-| `step.run(id, fn)` | Execute memoized step |
-| `step.sleep(id, duration)` | Durable sleep |
-| `step.sleepUntil(id, timestamp)` | Sleep until specific time |
-| `step.waitForEvent(id, options)` | Wait for external event |
-| `step.parallel(name, branches, options?)` | Execute branches in parallel |
-| `step.map(name, items, fn, options?)` | Map over items in parallel |
+---
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `IRONFLOW_SERVER_URL` | Server URL | `http://localhost:9123` |
-| `IRONFLOW_SIGNING_KEY` | Request signing key | - |
-| `IRONFLOW_LOG_LEVEL` | Log level | `info` |
+| `IRONFLOW_SERVER_URL` | Ironflow server URL | `http://localhost:9123` |
+| `IRONFLOW_SIGNING_KEY` | HMAC-SHA256 signing key for push mode verification | -- |
+| `IRONFLOW_API_KEY` | API key for authentication (worker and client) | -- |
+| `IRONFLOW_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` | `info` |
+| `IRONFLOW_ENV` | Target environment name | `default` |
+
+---
+
+## Testing
+
+The `@ironflow/node/test` entry point provides a `createTestClient` for unit testing functions without a running server.
+
+### Import
+
+```typescript
+import { createTestClient } from '@ironflow/node/test';
+```
+
+### TestClient interface
+
+| Method | Description |
+|--------|-------------|
+| `mockStep(name, fn)` | Mock a `step.run()` call by name. |
+| `mockInvoke(functionId, fn)` | Mock a `step.invoke()` or `step.invokeAsync()` call. |
+| `sendEvent(eventName, data)` | Pre-register an event for `step.waitForEvent()`. |
+| `emit(eventName, data)` | Run the function triggered by this event. Returns `TestRun`. |
+
+### TestRun interface
+
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `status` | `"completed" \| "failed"` | Run outcome. |
+| `output` | `unknown` | Function return value (if completed). |
+| `error` | `Error` | Error (if failed). |
+| `steps` | `TestStep[]` | All executed steps. |
+| `compensationsRan` | `string[]` | Step names whose compensations executed. |
+| `stepOutput(name)` | `unknown` | Get output of a specific step by name. |
+
+### Example
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createFunction } from '@ironflow/node';
+import { createTestClient } from '@ironflow/node/test';
+
+const processOrder = createFunction(
+  { id: 'process-order', triggers: [{ event: 'order.placed' }] },
+  async ({ event, step }) => {
+    const validated = await step.run('validate', async () => {
+      return { orderId: event.data.orderId, valid: true };
+    });
+
+    const approval = await step.waitForEvent('wait-approval', {
+      event: 'approval.received',
+    });
+
+    const result = await step.invoke('send-confirmation', {
+      orderId: validated.orderId,
+    });
+
+    return { orderId: validated.orderId, confirmed: true };
+  }
+);
+
+describe('processOrder', () => {
+  it('completes successfully', async () => {
+    const t = createTestClient({ functions: [processOrder] });
+
+    // Mock steps
+    t.mockStep('validate', () => ({ orderId: '123', valid: true }));
+    t.mockInvoke('send-confirmation', (input) => ({ sent: true }));
+
+    // Pre-register events for waitForEvent
+    t.sendEvent('approval.received', { approved: true });
+
+    // Run function
+    const run = await t.emit('order.placed', { orderId: '123' });
+
+    expect(run.status).toBe('completed');
+    expect(run.output).toEqual({ orderId: '123', confirmed: true });
+    expect(run.stepOutput('validate')).toEqual({ orderId: '123', valid: true });
+  });
+});
+```
+
+### Testing compensations
+
+```typescript
+import { NonRetryableError } from '@ironflow/node';
+
+const transferFunds = createFunction(
+  { id: 'transfer', triggers: [{ event: 'transfer.requested' }] },
+  async ({ event, step }) => {
+    await step.run('debit', async () => ({ ref: 'D1' }));
+    step.compensate('debit', async () => { /* refund */ });
+
+    await step.run('credit', async () => {
+      throw new NonRetryableError('Insufficient funds');
+    });
+  }
+);
+
+describe('transferFunds', () => {
+  it('runs compensations on failure', async () => {
+    const t = createTestClient({ functions: [transferFunds] });
+    t.mockStep('debit', () => ({ ref: 'D1' }));
+    t.mockStep('credit', () => { throw new NonRetryableError('Insufficient funds'); });
+
+    const run = await t.emit('transfer.requested', {});
+
+    expect(run.status).toBe('failed');
+    expect(run.compensationsRan).toContain('debit');
+  });
+});
+```
+
+**Note:** Every `step.run()` and `step.invoke()` call **must** have a corresponding mock registered via `mockStep()` or `mockInvoke()`. Unmocked steps throw with a helpful error message.
+
+---
 
-## Requirements
+## API Summary
 
-- Node.js 22+
+| Export | Description |
+|--------|-------------|
+| `createFunction(config, handler)` | Define a workflow function. |
+| `serve(config)` | Create HTTP handler for push mode. |
+| `createWorker(config)` | Create pull mode worker (REST polling). |
+| `createStreamingWorker(config)` | Create pull mode worker (ConnectRPC streaming). Import from `@ironflow/node/worker-streaming`. |
+| `createProjection(config)` | Define a projection. |
+| `createClient(config)` | Create server-side HTTP client. |
+| `createSubscriptionClient(config)` | Create WebSocket subscription client. |
+| `createWebhook(config)` | Define a webhook source. |
+| `createTestClient(config)` | Create test client. Import from `@ironflow/node/test`. |
+| `createSecretsClient(secrets)` | Create a read-only secrets accessor. |
+| `ironflow` | Singleton with `ironflow.createFunction()`. |
 
 ## Documentation
 
-For the full API reference, see the [Node Package Documentation](https://ironflow.dev/docs/api-reference/js-sdk/node).
+Full documentation: [https://github.com/sahina/ironflow/tree/main/docs](https://github.com/sahina/ironflow/tree/main/docs)
 
 ## License