workflow 4.2.0-beta.74 → 4.2.0-beta.76

package/README.md

@@ -5,7 +5,7 @@
       <img alt="Workflow SDK logo" src="https://useworkflow.dev/workflow-circle-symbol-light.svg" height="128">
     </picture>
   </a>
-  <h1>Workflow Development Kit</h1>
+  <h1>Workflow SDK</h1>
 
 <a href="https://vercel.com"><img alt="Vercel logo" src="https://img.shields.io/badge/MADE%20BY%20Vercel-000000.svg?style=for-the-badge&logo=Vercel&labelColor=000"></a>
 <a href="https://www.npmjs.com/package/workflow"><img alt="NPM version" src="https://img.shields.io/npm/v/workflow?style=for-the-badge&labelColor=000000"></a>
@@ -16,7 +16,7 @@
 
 ## Getting Started
 
-The **Workflow Development Kit** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
+The **Workflow SDK** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
 
 Visit [https://useworkflow.dev](https://useworkflow.dev) to view the full documentation.
 

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,37 @@ export default World;`}
 showSections={["returns"]}
 />
 
-## Examples
+## World SDK
 
-### List Workflow Runs
+The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
 
-List all workflow runs with pagination:
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
+        Read, write, and manage data streams.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability">
+        Hydrate step I/O, parse display names, decrypt data.
+    </Card>
+</Cards>
 
-```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";
+## Data Hydration
 
-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:
+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 }
-    );
-  }
-}
-```
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
 
-### 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:
-
-```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/index.mdx

@@ -0,0 +1,58 @@
+---
+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]
+```
+
+## Interfaces
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
+    </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="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </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,4 @@
+{
+  "title": "World SDK",
+  "pages": ["storage", "streams", "queue", "observability"]
+}

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

@@ -0,0 +1,164 @@
+---
+title: Observability Utilities
+description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
+type: reference
+summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/storage
+keywords:
+  - workflow/observability
+  - hydrateResourceIO
+  - observabilityRevivers
+  - parseStepName
+  - parseWorkflowName
+  - parseClassName
+  - getEncryptionKeyForRun
+  - hydrateResourceIOWithKey
+  - data hydration
+  - devalue deserialization
+  - encryption decryption
+  - display name parsing
+---
+
+The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
+
+## Import
+
+```typescript lineNumbers
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  parseStepName, // [!code highlight]
+  parseWorkflowName, // [!code highlight]
+  parseClassName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+```
+
+## Data Hydration
+
+### hydrateResourceIO()
+
+Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Required to display step input/output in your UI.
+
+```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);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
+
+**Returns:** The resource with hydrated `input` and `output` fields.
+
+### observabilityRevivers
+
+A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
+
+## Name Parsing
+
+Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
+
+### parseStepName()
+
+```typescript lineNumbers
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
+// parsed?.shortName → "processPayment"
+// parsed?.moduleSpecifier → "./src/workflows/order"
+```
+
+### parseWorkflowName()
+
+```typescript lineNumbers
+import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
+// parsed?.shortName → "processOrder"
+```
+
+### parseClassName()
+
+```typescript lineNumbers
+import { parseClassName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
+// parsed?.shortName → "User"
+```
+
+## Encryption
+
+For workflows with encrypted step data, decrypt before hydrating.
+
+### getEncryptionKeyForRun()
+
+Retrieve the encryption key used for a specific workflow run.
+
+{/* @expect-error:2305 */}
+```typescript lineNumbers
+import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** Encryption key for the run
+
+### hydrateResourceIOWithKey()
+
+Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
+
+{/* @expect-error:2305,2724 */}
+```typescript lineNumbers
+import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
+| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
+
+**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
+
+## Examples
+
+### Parse Display Names for a Run's Steps
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const world = getWorld();
+const run = await world.runs.get(runId, { resolveData: "none" });
+console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
+
+const steps = await world.steps.list({ runId, resolveData: "none" });
+for (const step of steps.data) {
+  const parsed = parseStepName(step.stepName); // [!code highlight]
+  console.log(`  ${parsed?.shortName}: ${step.status}`); // [!code highlight]
+}
+```
+
+## Related
+
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
+- [Serialization](/docs/foundations/serialization) — How workflow data is serialized

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

@@ -0,0 +1,86 @@
+---
+title: Queue
+description: Low-level queue interface for dispatching workflow and step invocations.
+type: reference
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/starting-workflows
+keywords:
+  - world.queue
+  - getDeploymentId
+  - queue
+  - createQueueHandler
+  - ValidQueueName
+  - queue dispatch
+---
+
+Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
+
+<Callout type="warn">
+  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
+</Callout>
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld(); // [!code highlight]
+// Queue methods are called directly on world — e.g. world.queue()
+```
+
+## Methods
+
+### getDeploymentId()
+
+Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
+
+```typescript lineNumbers
+const deploymentId = await world.getDeploymentId(); // [!code highlight]
+```
+
+**Returns:** `string` — The current deployment ID
+
+### queue()
+
+Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
+
+```typescript lineNumbers
+const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `queueName` | `ValidQueueName` | The queue name (branded string) |
+| `message` | `QueuePayload` | Internal SDK payload |
+| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
+
+**Returns:** `{ messageId: MessageId | null }`
+
+### createQueueHandler()
+
+Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
+
+```typescript lineNumbers
+const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `QueuePrefix` | Queue name prefix to match |
+| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
+
+**Returns:** `(req: Request) => Promise<Response>`
+
+## Related
+
+- [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
+- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Create events that trigger queue dispatch