workflow 4.2.0-beta.73 → 4.2.0-beta.75

package/docs/api-reference/workflow-api/world/events.mdx

@@ -0,0 +1,227 @@
+---
+title: world.events
+description: Query the append-only event log for workflow state changes, audit trails, and run cancellation.
+type: reference
+summary: "Methods: create(), get(), list(), listByCorrelationId(). The event log is the source of truth for all workflow state."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/runs
+  - /docs/api-reference/workflow-api/world/steps
+keywords:
+  - world.events
+  - world.events.create
+  - world.events.get
+  - world.events.list
+  - world.events.listByCorrelationId
+  - event log
+  - audit trail
+  - run_cancelled
+  - event types
+  - correlation ID
+  - cancel workflow run
+---
+
+The `world.events` interface provides access to the append-only event log that drives all workflow state. Runs, steps, and hooks are materialized views derived from events. Use this interface for audit trails, debugging, and programmatic run cancellation.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const events = world.events; // [!code highlight]
+```
+
+## Methods
+
+### create()
+
+Create a new event for a workflow run. Most commonly used to cancel a run.
+
+```typescript lineNumbers
+await world.events.create(runId, { // [!code highlight]
+  eventType: "run_cancelled", // [!code highlight]
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `data` | `object` | Event data including `eventType` |
+| `params` | `object` | Optional parameters |
+
+**Returns:** `Event`
+
+### get()
+
+Retrieve a single event by run ID and event ID.
+
+```typescript lineNumbers
+const event = await world.events.get(runId, eventId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `eventId` | `string` | The event ID |
+| `params` | `object` | Optional parameters |
+
+**Returns:** `Event`
+
+### list()
+
+List events with cursor pagination.
+
+```typescript lineNumbers
+const result = await world.events.list({ // [!code highlight]
+  runId,
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Filter events by run ID |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Event[], cursor?: string }`
+
+### listByCorrelationId()
+
+List events that share a correlation ID, useful for tracing related events across runs.
+
+```typescript lineNumbers
+const result = await world.events.listByCorrelationId({ // [!code highlight]
+  correlationId: "order-123",
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.correlationId` | `string` | The correlation ID to filter by |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Event[], cursor?: string }`
+
+## Event Types
+
+Events are grouped by the entity they affect:
+
+### Run Events
+
+| Event Type | Description |
+|-----------|-------------|
+| `run_created` | Workflow run was created |
+| `run_started` | Workflow run execution began |
+| `run_completed` | Workflow run completed successfully |
+| `run_failed` | Workflow run failed with an error |
+| `run_cancelled` | Workflow run was cancelled |
+
+### Step Events
+
+| Event Type | Description |
+|-----------|-------------|
+| `step_created` | Step was created |
+| `step_started` | Step execution began |
+| `step_completed` | Step completed successfully |
+| `step_failed` | Step failed with an error |
+| `step_retrying` | Step scheduled for retry |
+
+### Hook Events
+
+| Event Type | Description |
+|-----------|-------------|
+| `hook_created` | Hook was created (workflow paused) |
+| `hook_received` | Hook received a payload |
+| `hook_disposed` | Hook was disposed (workflow reached terminal state) |
+| `hook_conflict` | Hook token conflict detected |
+
+### Wait Events
+
+| Event Type | Description |
+|-----------|-------------|
+| `wait_created` | Workflow entered a wait state (e.g., `sleep()`) |
+| `wait_completed` | Wait state completed |
+
+<Callout type="info">
+  Events are the append-only source of truth for all workflow state. `WorkflowRun`, `Step`, and `Hook` objects are materialized views derived from these events.
+</Callout>
+
+## Examples
+
+### List Events for a Run as Audit Trail
+
+```typescript lineNumbers
+// app/api/workflow-events/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+
+  if (!runId) {
+    return Response.json({ error: "runId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const events = await world.events.list({ runId }); // [!code highlight]
+
+  return Response.json(events);
+}
+```
+
+### Cancel a Run via Event Creation
+
+Cancelling a run is done by creating a `run_cancelled` event:
+
+```typescript lineNumbers
+// app/api/workflow-runs/cancel/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+
+  const world = getWorld();
+  await world.events.create(runId, { // [!code highlight]
+    eventType: "run_cancelled", // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+<Callout type="info">
+  `world.runs.cancel(runId)` is a convenience wrapper around this event creation pattern. Use `world.events.create()` directly when you need to attach custom data to the cancellation event.
+</Callout>
+
+### List Events by Correlation ID
+
+Trace related events across workflow runs using a shared correlation ID:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const events = await world.events.listByCorrelationId({ // [!code highlight]
+  correlationId: "order-123", // [!code highlight]
+}); // [!code highlight]
+
+for (const event of events.data) {
+  console.log(event.eventType, event.runId, event.createdAt);
+}
+```
+
+## Related
+
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — Inspect runs (materialized from events)
+- [world.steps](/docs/api-reference/workflow-api/world/steps) — Inspect steps (materialized from events)
+- [world.hooks](/docs/api-reference/workflow-api/world/hooks) — Inspect hooks (materialized from events)

package/docs/api-reference/workflow-api/world/hooks.mdx

@@ -0,0 +1,181 @@
+---
+title: world.hooks
+description: Look up workflow hooks by ID or token for webhook resume flows and metadata inspection.
+type: reference
+summary: "Methods: get(), getByToken(), list(). Query hook details for resume flows."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/events
+  - /docs/api-reference/workflow-api/resume-hook
+  - /docs/api-reference/workflow-api/resume-webhook
+keywords:
+  - world.hooks
+  - world.hooks.get
+  - world.hooks.getByToken
+  - world.hooks.list
+  - Hook
+  - webhook token
+  - hook metadata
+  - resume flow
+  - pending approvals
+---
+
+The `world.hooks` interface provides access to workflow hook data. Hooks are pause points in workflows that wait for external input. Use this interface to look up hooks by ID or token, inspect metadata, and build admin UIs for pending approvals.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const hooks = world.hooks; // [!code highlight]
+```
+
+## Methods
+
+### get()
+
+Retrieve a hook by its ID.
+
+```typescript lineNumbers
+const hook = await world.hooks.get(hookId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hookId` | `string` | The hook ID |
+| `params` | `object` | Optional parameters |
+
+**Returns:** `Hook`
+
+### getByToken()
+
+Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.
+
+```typescript lineNumbers
+const hook = await world.hooks.getByToken(token); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `string` | The hook token |
+| `params` | `object` | Optional parameters |
+
+**Returns:** `Hook`
+
+### list()
+
+List hooks with cursor pagination.
+
+```typescript lineNumbers
+const result = await world.hooks.list({ // [!code highlight]
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Hook[], cursor?: string }`
+
+## Types
+
+### Hook
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Parent workflow run ID |
+| `hookId` | `string` | Unique hook identifier |
+| `token` | `string` | Hook token for resuming |
+| `ownerId` | `string` | Owner (team/user) ID |
+| `projectId` | `string` | Project ID |
+| `environment` | `string` | Deployment environment |
+| `metadata` | `object` | Custom metadata attached to the hook |
+| `isWebhook` | `boolean` | Whether this is a webhook-style hook |
+
+## Examples
+
+### Look Up Hook by ID
+
+```typescript lineNumbers
+// app/api/workflow-hooks/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const hookId = url.searchParams.get("hookId");
+
+  if (!hookId) {
+    return Response.json({ error: "hookId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const hook = await world.hooks.get(hookId); // [!code highlight]
+
+  return Response.json({
+    hookId: hook.hookId,
+    runId: hook.runId,
+    token: hook.token,
+    metadata: hook.metadata,
+  });
+}
+```
+
+### Look Up Hook by Token for Webhook Resume
+
+When you receive a webhook callback with a token, look up the hook to inspect metadata before resuming:
+
+```typescript lineNumbers
+// app/api/workflow-hooks/resume/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function POST(req: Request) {
+  const { token } = await req.json();
+
+  const world = getWorld();
+  const hook = await world.hooks.getByToken(token); // [!code highlight]
+
+  // Inspect hook metadata before deciding to resume
+  console.log(hook.runId, hook.metadata); // [!code highlight]
+
+  return Response.json({
+    runId: hook.runId,
+    hookId: hook.hookId,
+    metadata: hook.metadata,
+  });
+}
+```
+
+### List All Hooks for Pending Approvals Dashboard
+
+```typescript lineNumbers
+// app/api/workflow-hooks/pending/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  const world = getWorld();
+  const hooks = await world.hooks.list({ // [!code highlight]
+    pagination: { cursor },
+  }); // [!code highlight]
+
+  return Response.json(hooks);
+}
+```
+
+## Related
+
+- [resumeHook()](/docs/api-reference/workflow-api/resume-hook) — Resume a workflow by sending a payload to a hook
+- [resumeWebhook()](/docs/api-reference/workflow-api/resume-webhook) — Resume a workflow via webhook
+- [getHookByToken()](/docs/api-reference/workflow-api/get-hook-by-token) — Higher-level API for hook lookup
+- [Hooks](/docs/foundations/hooks) — Core concepts for hooks and pause points

package/docs/api-reference/workflow-api/world/index.mdx

@@ -0,0 +1,67 @@
+---
+title: World SDK
+description: Low-level API for inspecting and managing workflow runs, steps, events, hooks, streams, and queues.
+type: overview
+summary: Access workflow infrastructure directly via getWorld() for building observability dashboards, admin tools, and custom integrations.
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+keywords:
+  - getWorld
+  - World SDK
+  - workflow runtime
+  - observability dashboard
+  - admin panel
+  - workflow management
+---
+
+The World SDK provides direct access to workflow infrastructure — runs, steps, events, hooks, streams, and queues. Use it to build observability dashboards, admin panels, debugging tools, and custom workflow management logic.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld(); // [!code highlight]
+```
+
+## Entities
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
+        List, filter, and inspect workflow runs with pagination and status filtering.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
+        List and inspect step execution data including input/output hydration.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
+        Look up hooks by ID or token for webhook resume flows.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
+        Query the append-only event log — the source of truth for all workflow state changes.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
+        Read, write, and manage real-time data streams for workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
+        Enqueue workflow runs and create queue handlers for processing.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
+        Hydrate step I/O, parse display names, and decrypt workflow data.
+    </Card>
+</Cards>
+
+<Callout type="info">
+  The World SDK is the low-level foundation that higher-level functions like [`getRun()`](/docs/api-reference/workflow-api/get-run) and [`start()`](/docs/api-reference/workflow-api/start) are built on. Use it when you need capabilities beyond what those functions provide.
+</Callout>
+
+## Data Hydration
+
+Step input/output data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. To display this data in your UI, use the hydration utilities from `workflow/observability`:
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input, hydrated.output);
+```
+
+See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full API.

package/docs/api-reference/workflow-api/world/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "World SDK",
+  "pages": [
+    "runs",
+    "steps",
+    "hooks",
+    "events",
+    "streams",
+    "queue",
+    "observability"
+  ]
+}