workflow 4.2.0-beta.75 → 4.2.0-beta.77

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

@@ -1,181 +0,0 @@
----
-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/runs.mdx

@@ -1,223 +0,0 @@
----
-title: world.runs
-description: List, filter, and inspect workflow runs with cursor pagination and status filtering.
-type: reference
-summary: "Methods: get(), list(). Query workflow runs by status, paginate results, and inspect run metadata."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/steps
-  - /docs/api-reference/workflow-api/world/events
-  - /docs/api-reference/workflow-api/get-run
-keywords:
-  - world.runs
-  - world.runs.get
-  - world.runs.list
-  - WorkflowRun
-  - cursor pagination
-  - run status
-  - resolveData
-  - parseWorkflowName
-  - list workflow runs
-  - filter runs
----
-
-The `world.runs` interface provides direct access to workflow run data. Use it to list runs with pagination, filter by status, and inspect individual run metadata.
-
-## Import
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const runs = world.runs; // [!code highlight]
-```
-
-## Methods
-
-### get()
-
-Retrieve a single workflow run by ID.
-
-```typescript lineNumbers
-const run = await world.runs.get(runId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data. Default: `'all'` |
-
-**Returns:** `WorkflowRun`
-
-### list()
-
-List workflow runs with cursor pagination.
-
-```typescript lineNumbers
-const result = await world.runs.list({ // [!code highlight]
-  pagination: { cursor },
-}); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `params.pagination.cursor` | `string` | Cursor for the next page |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data |
-
-**Returns:** `{ data: WorkflowRun[], cursor?: string }`
-
-### cancel()
-
-Cancel a running workflow. This is a convenience method that creates a `run_cancelled` event.
-
-```typescript lineNumbers
-const run = await world.runs.cancel(runId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID to cancel |
-
-**Returns:** `WorkflowRun`
-
-<Callout type="info">
-  Cancellation works by creating an event with `eventType: 'run_cancelled'`. See [world.events](/docs/api-reference/workflow-api/world/events) for the full event creation API.
-</Callout>
-
-## Types
-
-### WorkflowRun
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `runId` | `string` | Unique run identifier |
-| `status` | `string` | Run status: `'running'`, `'completed'`, `'failed'`, `'cancelled'` |
-| `workflowName` | `string` | Machine-readable workflow identifier |
-| `input` | `any` | Workflow input data (when `resolveData: 'all'`) |
-| `output` | `any` | Workflow output data (when `resolveData: 'all'`) |
-| `error` | `any` | Error data if the run failed |
-| `startedAt` | `string` | ISO timestamp when the run started |
-| `completedAt` | `string \| null` | ISO timestamp when the run completed |
-| `specVersion` | `number` | Workflow spec version |
-
-<Callout type="warn">
-  The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//processOrder`. Use `parseWorkflowName()` from `workflow/observability` to extract a display-friendly name.
-</Callout>
-
-## Examples
-
-### List Workflow Runs with Cursor Pagination
-
-```typescript lineNumbers
-// app/api/workflow-runs/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(); // [!code highlight]
-  const runs = await world.runs.list({ // [!code highlight]
-    pagination: { cursor }, // [!code highlight]
-  }); // [!code highlight]
-
-  return Response.json(runs);
-}
-```
-
-### Get a Single Run with Full Data
-
-Use `resolveData: 'all'` (the default) to fetch the complete run including input and output:
-
-```typescript lineNumbers
-// app/api/workflow-runs/[runId]/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 run = await world.runs.get(runId, { // [!code highlight]
-    resolveData: "all", // [!code highlight]
-  }); // [!code highlight]
-
-  return Response.json({
-    runId: run.runId,
-    status: run.status,
-    input: run.input,
-    output: run.output,
-    startedAt: run.startedAt,
-    completedAt: run.completedAt,
-  });
-}
-```
-
-### Get Run without Data for Lightweight Status Checks
-
-Use `resolveData: 'none'` when you only need status metadata:
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const run = await world.runs.get(runId, { // [!code highlight]
-  resolveData: "none", // Skip input/output for performance // [!code highlight]
-}); // [!code highlight]
-
-console.log(run.status); // 'running' | 'completed' | 'failed' | 'cancelled'
-```
-
-### Parse Workflow Display Name from Machine-Readable ID
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const world = getWorld();
-const runs = await world.runs.list({});
-
-for (const run of runs.data) {
-  const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
-  console.log(parsed?.shortName); // e.g., "processOrder" // [!code highlight]
-  console.log(parsed?.moduleSpecifier); // e.g., "./src/workflows/order"
-}
-```
-
-### Cancel a Running Workflow
-
-```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();
-
-  if (!runId) {
-    return Response.json({ error: "runId required" }, { status: 400 });
-  }
-
-  const world = getWorld();
-  const run = await world.runs.cancel(runId); // [!code highlight]
-
-  return Response.json({ status: run.status });
-}
-```
-
-## Related
-
-- [world.steps](/docs/api-reference/workflow-api/world/steps) — Inspect individual step execution within a run
-- [world.events](/docs/api-reference/workflow-api/world/events) — Query the event log for a run
-- [getRun()](/docs/api-reference/workflow-api/get-run) — Higher-level API for working with individual runs
-- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Parse workflow names and hydrate data

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

@@ -1,216 +0,0 @@
----
-title: world.steps
-description: List and inspect workflow step execution data with input/output hydration.
-type: reference
-summary: "Methods: get(), list(). Query step metadata, hydrate serialized I/O, calculate durations."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/runs
-  - /docs/api-reference/workflow-api/world/observability
-keywords:
-  - world.steps
-  - world.steps.get
-  - world.steps.list
-  - Step
-  - step input output
-  - hydrateResourceIO
-  - step duration
-  - resolveData
-  - parseStepName
-  - devalue serialization
----
-
-The `world.steps` interface provides access to individual step execution data within workflow runs. Use it to list steps, inspect their input/output, and build progress dashboards.
-
-## Import
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const steps = world.steps; // [!code highlight]
-```
-
-## Methods
-
-### get()
-
-Retrieve a single step by run ID and step ID.
-
-```typescript lineNumbers
-const step = await world.steps.get(runId, stepId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-| `stepId` | `string` | The step ID |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data. Default: `'all'` |
-
-**Returns:** `Step`
-
-### list()
-
-List steps with cursor pagination.
-
-```typescript lineNumbers
-const result = await world.steps.list({ // [!code highlight]
-  runId,
-  pagination: { cursor },
-}); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `params.runId` | `string` | Filter steps by run ID |
-| `params.pagination.cursor` | `string` | Cursor for the next page |
-| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data |
-
-**Returns:** `{ data: Step[], cursor?: string }`
-
-## Types
-
-### Step
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `runId` | `string` | Parent workflow run ID |
-| `stepId` | `string` | Unique step identifier |
-| `stepName` | `string` | Machine-readable step identifier |
-| `status` | `string` | Step status: `'running'`, `'completed'`, `'failed'` |
-| `input` | `any` | Step input data (when `resolveData: 'all'`) |
-| `output` | `any` | Step output data (when `resolveData: 'all'`) |
-| `error` | `any` | Error data if the step failed |
-| `attempt` | `number` | Current retry attempt number |
-| `startedAt` | `string` | ISO timestamp when the step started |
-| `completedAt` | `string \| null` | ISO timestamp when the step completed |
-| `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
-
-<Callout type="info">
-  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
-</Callout>
-
-## Examples
-
-### List Steps for a Run without Data
-
-Use `resolveData: 'none'` to efficiently get step metadata for progress dashboards:
-
-```typescript lineNumbers
-// app/api/workflow-steps/route.ts
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "workflow/observability"; // [!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: "runId required" }, { status: 400 });
-  }
-
-  const world = getWorld();
-  const steps = await world.steps.list({ // [!code highlight]
-    runId,
-    resolveData: "none", // Skip I/O for performance // [!code highlight]
-  }); // [!code highlight]
-
-  const progress = steps.data.map((step) => {
-    const parsed = parseStepName(step.stepName); // [!code highlight]
-    return {
-      stepId: step.stepId,
-      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-      module: parsed?.moduleSpecifier,
-      status: step.status,
-      startedAt: step.startedAt,
-      completedAt: step.completedAt,
-    };
-  });
-
-  return Response.json({ progress, cursor: steps.cursor });
-}
-```
-
-### Get Step with Hydrated Input and Output Data
-
-Retrieve a step with its full serialized data and hydrate it for display:
-
-```typescript lineNumbers
-// app/api/workflow-steps/[stepId]/route.ts
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "workflow/observability";
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-} from "workflow/observability"; // [!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 });
-  }
-
-  const world = getWorld();
-  const step = await world.steps.get(runId, stepId); // [!code highlight]
-
-  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-  const parsed = parseStepName(step.stepName);
-
-  return Response.json({
-    stepId: hydrated.stepId,
-    displayName: parsed?.shortName ?? step.stepName,
-    status: hydrated.status,
-    attempt: hydrated.attempt,
-    input: hydrated.input, // [!code highlight]
-    output: hydrated.output, // [!code highlight]
-  });
-}
-```
-
-### Calculate Step Duration from Timestamps
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = getWorld();
-const steps = await world.steps.list({ runId });
-
-for (const step of steps.data) {
-  if (step.completedAt) {
-    const start = new Date(step.startedAt).getTime();
-    const end = new Date(step.completedAt).getTime();
-    const durationMs = end - start; // [!code highlight]
-    console.log(`${step.stepName}: ${durationMs}ms`);
-  }
-}
-```
-
-### Parse Step Display Name from Machine-Readable ID
-
-The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` to extract display-friendly names:
-
-```typescript lineNumbers
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseStepName(step.stepName); // [!code highlight]
-// parsed.shortName → "processPayment"
-// parsed.moduleSpecifier → "./src/workflows/order"
-```
-
-<Callout type="warn">
-  The `stepName` field is a machine-readable identifier, not a display name. Always use `parseStepName()` from `workflow/observability` to extract the `shortName` for UI display.
-</Callout>
-
-## Related
-
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — List and inspect workflow runs
-- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O and parse display names
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps