workflow 4.2.0-beta.74 → 4.2.0-beta.75

package/docs/api-reference/workflow/create-webhook.mdx

@@ -13,6 +13,10 @@ Creates a webhook that can be used to suspend and resume a workflow run upon rec
 
 Webhooks provide a way for external systems to send HTTP requests directly to your workflow. Unlike hooks which accept arbitrary payloads, webhooks work with standard HTTP `Request` objects and can return HTTP `Response` objects.
 
+<Callout type="warn">
+`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and simple resume links because it avoids creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+</Callout>
+
 ```ts lineNumbers
 import { createWebhook } from "workflow"
 

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

@@ -14,7 +14,7 @@ Use this function when you need direct access to the underlying workflow infrast
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = getWorld(); // [!code highlight]
 ```
 
 ## API Signature
@@ -34,167 +34,43 @@ export default World;`}
 showSections={["returns"]}
 />
 
-## Examples
-
-### List Workflow Runs
-
-List all workflow runs with pagination:
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const cursor = url.searchParams.get("cursor") ?? undefined;
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const runs = await world.runs.list({
-      pagination: { cursor },
-    });
-
-    return Response.json(runs);
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to list workflow runs" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Cancel a Workflow Run
-
-Cancel a running workflow:
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-export async function POST(req: Request) {
-  const { runId } = await req.json();
-
-  if (!runId) {
-    return Response.json({ error: "No runId provided" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const run = await world.runs.cancel(runId); // [!code highlight]
-
-    return Response.json({ status: run.status });
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to cancel workflow run" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### List Steps for a Run (Without Data)
-
-List steps for a workflow run with `resolveData: 'none'` to efficiently get step metadata without fetching serialized input/output. Use `parseStepName` to extract user-friendly display names:
+## World SDK
+
+The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
+        List, filter, and inspect workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
+        List and inspect step execution data.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
+        Look up hooks by ID or token.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
+        Query the append-only event log.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="world.streams">
+        Read, write, and manage data streams.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
+        Enqueue runs and create queue handlers.
+    </Card>
+</Cards>
+
+## Data Hydration
+
+Step and run data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `workflow/observability` to hydrate it for display:
 
 ```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-
-  if (!runId) {
-    return Response.json({ error: "No runId provided" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const steps = await world.steps.list({ // [!code highlight]
-      runId, // [!code highlight]
-      resolveData: "none", // Skip fetching input/output for performance // [!code highlight]
-    }); // [!code highlight]
-
-    // Map steps to a progress view using parseStepName for display
-    const progress = steps.data.map((step) => {
-      const parsed = parseStepName(step.stepName); // [!code highlight]
-      return {
-        stepId: step.stepId,
-        // Use shortName for UI display (e.g., "fetchUserData") // [!code highlight]
-        displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-        // Module info available for debugging // [!code highlight]
-        module: parsed?.moduleSpecifier, // [!code highlight]
-        status: step.status,
-        startedAt: step.startedAt,
-        completedAt: step.completedAt,
-      };
-    });
-
-    return Response.json({ progress, cursor: steps.cursor });
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to list steps" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Get Step with Hydrated Input/Output
-
-Retrieve a step with its serialized data and hydrate it for display. This example shows how to decrypt and deserialize step input/output:
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
 
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-} from "@workflow/core/serialization-format"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-  const stepId = url.searchParams.get("stepId");
-
-  if (!runId || !stepId) {
-    return Response.json({ error: "runId and stepId required" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    // Fetch step with data (default resolveData behavior) // [!code highlight]
-    const step = await world.steps.get(runId, stepId); // [!code highlight]
-
-    // Hydrate serialized input/output for display // [!code highlight]
-    const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-
-    // Parse the stepName for user-friendly display
-    const parsed = parseStepName(step.stepName);
-
-    return Response.json({
-      stepId: hydrated.stepId,
-      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-      module: parsed?.moduleSpecifier, // [!code highlight]
-      status: hydrated.status,
-      attempt: hydrated.attempt,
-      // Hydrated input/output ready for rendering // [!code highlight]
-      input: hydrated.input, // [!code highlight]
-      output: hydrated.output, // [!code highlight]
-    });
-  } catch (error) {
-    return Response.json(
-      { error: "Step not found" },
-      { status: 404 }
-    );
-  }
-}
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
 ```
 
-<Callout type="info">
-  The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`.
-  Use `parseStepName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processPayment"`)
-  and `moduleSpecifier` for display in your UI.
-</Callout>
+See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full hydration, parsing, and encryption API.
 
 ## Related Functions
 

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

@@ -30,4 +30,7 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
         Get direct access to workflow storage, queuing, and streaming backends.
     </Card>
+    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
+        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
+    </Card>
 </Cards>

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