workflow 4.2.0-beta.75 → 4.2.0-beta.76

package/docs/getting-started/nuxt.mdx

@@ -1,6 +1,6 @@
 ---
 title: Nuxt
-description: This guide will walk through setting up your first workflow in a Nuxt app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
+description: This guide will walk through setting up your first workflow in a Nuxt app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 type: guide
 summary: Set up Workflow SDK in a Nuxt app.
 prerequisites:

package/docs/getting-started/sveltekit.mdx

@@ -1,6 +1,6 @@
 ---
 title: SvelteKit
-description: This guide will walk through setting up your first workflow in a SvelteKit app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
+description: This guide will walk through setting up your first workflow in a SvelteKit app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 type: guide
 summary: Set up Workflow SDK in a SvelteKit app.
 prerequisites:

package/docs/getting-started/vite.mdx

@@ -9,7 +9,7 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-This guide will walk through setting up your first workflow in a Vite app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
+This guide will walk through setting up your first workflow in a Vite app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 ---
 

package/docs/how-it-works/understanding-directives.mdx

@@ -15,7 +15,7 @@ import { File, Folder, Files } from "fumadocs-ui/components/files";
 This guide explores how JavaScript directives enable the Workflow SDK's execution model. For getting started with workflows, see the [getting started](/docs/getting-started) guides for your framework.
 </Callout>
 
-The Workflow Development Kit uses JavaScript directives (`"use workflow"` and `"use step"`) as the foundation for its durable execution model. Directives provide the compile-time semantic boundary necessary for workflows to suspend, resume, and maintain deterministic behavior across replays.
+The Workflow SDK uses JavaScript directives (`"use workflow"` and `"use step"`) as the foundation for its durable execution model. Directives provide the compile-time semantic boundary necessary for workflows to suspend, resume, and maintain deterministic behavior across replays.
 
 This page explores how directives enable this execution model and the design principles that led us here.
 
@@ -339,7 +339,7 @@ This approach requires:
 - Storing/mutating class properties was not obvious (similar closure/mutation issues as the runtime-only approach)
 - Class-based syntax that doesn't feel "JavaScript native" to developers used to functional patterns
 
-As the JavaScript ecosystem has moved toward function-forward programming (exemplified by React's shift from class components to functions and hooks), requiring developers to use classes felt like a step backward and also didn't match our own personal taste as authors of the DevKit.
+As the JavaScript ecosystem has moved toward function-forward programming (exemplified by React's shift from class components to functions and hooks), requiring developers to use classes felt like a step backward and also didn't match our own personal taste as authors of the SDK.
 
 **The core problem: Presents workflows as regular runtime code**
 
@@ -615,4 +615,4 @@ As TC39 members, we at Vercel are actively working with the standards body and b
 
 Directives aren't about syntax preference, they're about expressing semantic boundaries. `"use workflow"` tells the compiler, developer, and runtime that this code is deterministic, resumable, and sandboxed.
 
-This clarity enables the Workflow Development Kit to provide durable execution with familiar JavaScript patterns, while maintaining the compile-time guarantees necessary for reliable workflow orchestration.
+This clarity enables the Workflow SDK to provide durable execution with familiar JavaScript patterns, while maintaining the compile-time guarantees necessary for reliable workflow orchestration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.75",
+  "version": "4.2.0-beta.76",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.49",
-    "@workflow/cli": "4.2.0-beta.75",
-    "@workflow/core": "4.2.0-beta.75",
+    "@workflow/astro": "4.0.0-beta.50",
+    "@workflow/cli": "4.2.0-beta.76",
+    "@workflow/core": "4.2.0-beta.76",
     "@workflow/errors": "4.1.0-beta.20",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
     "@workflow/utils": "4.1.0-beta.13",
-    "@workflow/next": "4.0.1-beta.71",
-    "@workflow/nest": "0.0.0-beta.24",
-    "@workflow/nitro": "4.0.1-beta.70",
-    "@workflow/nuxt": "4.0.1-beta.59",
-    "@workflow/sveltekit": "4.0.0-beta.64",
-    "@workflow/rollup": "4.0.0-beta.32"
+    "@workflow/next": "4.0.1-beta.72",
+    "@workflow/nest": "0.0.0-beta.25",
+    "@workflow/nitro": "4.0.1-beta.71",
+    "@workflow/nuxt": "4.0.1-beta.60",
+    "@workflow/sveltekit": "4.0.0-beta.65",
+    "@workflow/rollup": "4.0.0-beta.33"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

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

@@ -1,227 +0,0 @@
----
-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

@@ -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