workflow 5.0.0-beta.1 → 5.0.0-beta.3

package/docs/cookbook/common-patterns/webhooks.mdx

@@ -0,0 +1,185 @@
+---
+title: Webhooks & External Callbacks
+description: Receive HTTP callbacks from external services, process them durably, and respond inline.
+type: guide
+summary: Create webhook endpoints that your workflow can await, process incoming requests in steps, and respond to the caller — all within durable workflow context.
+---
+
+Use webhooks when external services push events to your application via HTTP callbacks. The workflow creates a webhook URL, suspends with zero compute cost, and resumes when a request arrives.
+
+## When to use this
+
+- Accepting callbacks from payment processors (Stripe, PayPal)
+- Waiting for third-party verification or processing results
+- Any integration where an external system calls you back asynchronously
+
+## Pattern: Processing webhook events
+
+Create a webhook with manual response control, then iterate over incoming requests:
+
+```typescript
+import { createWebhook, type RequestWithResponse } from "workflow";
+
+declare function processEvent(request: RequestWithResponse): Promise<{ type: string }>; // @setup
+
+export async function paymentWebhook(orderId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" }); // [!code highlight]
+  // webhook.url is the URL to give to the external service
+
+  const ledger: { type: string }[] = [];
+
+  for await (const request of webhook) { // [!code highlight]
+    const entry = await processEvent(request);
+    ledger.push(entry);
+
+    // Break when we've received a terminal event
+    if (entry.type === "payment.succeeded" || entry.type === "refund.created") {
+      break;
+    }
+  }
+
+  return { orderId, webhookUrl: webhook.url, ledger, status: "settled" };
+}
+```
+
+### Step function for processing
+
+Each webhook request is processed in its own step, giving you full Node.js access for validation, database writes, and responding to the caller:
+
+```typescript
+import { type RequestWithResponse } from "workflow";
+
+async function processEvent(
+  request: RequestWithResponse
+): Promise<{ type: string }> {
+  "use step";
+
+  const body = await request.json().catch(() => ({}));
+  const type = body?.type ?? "unknown";
+
+  // Validate, process, and respond inline
+  if (type === "payment.succeeded") {
+    // Record the payment in your database
+    await request.respondWith(Response.json({ ack: true, action: "captured" })); // [!code highlight]
+  } else if (type === "payment.failed") {
+    await request.respondWith(Response.json({ ack: true, action: "flagged" }));
+  } else {
+    await request.respondWith(Response.json({ ack: true, action: "ignored" }));
+  }
+
+  return { type };
+}
+```
+
+## Pattern: Async request-reply with timeout
+
+Submit a request to an external service, pass it your webhook URL, then race the callback against a deadline:
+
+```typescript
+import { createWebhook, sleep, FatalError, type RequestWithResponse } from "workflow";
+
+export async function asyncVerification(documentId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" });
+
+  // Submit to vendor, passing our webhook URL for the callback
+  await submitToVendor(documentId, webhook.url);
+
+  // Race: wait for callback OR timeout after 30 seconds
+  const result = await Promise.race([ // [!code highlight]
+    (async () => {
+      for await (const request of webhook) {
+        const body = await processCallback(request);
+        return body;
+      }
+      throw new FatalError("Webhook closed without callback");
+    })(),
+    sleep("30s").then(() => ({ status: "timed_out" as const })), // [!code highlight]
+  ]);
+
+  return { documentId, ...result };
+}
+
+async function submitToVendor(documentId: string, callbackUrl: string): Promise<void> {
+  "use step";
+  await fetch("https://vendor.example.com/verify", {
+    method: "POST",
+    body: JSON.stringify({ documentId, callbackUrl }),
+  });
+}
+
+async function processCallback(
+  request: RequestWithResponse
+): Promise<{ status: string; details: string }> {
+  "use step";
+  const body = await request.json();
+  await request.respondWith(Response.json({ ack: true }));
+  return {
+    status: body.approved ? "verified" : "rejected",
+    details: body.details ?? body.reason ?? "",
+  };
+}
+```
+
+## Pattern: Large payload by reference
+
+When payloads are too large to serialize into the event log, pass a lightweight reference (a "claim check") instead. Use a hook to signal when the data is ready:
+
+```typescript
+import { defineHook } from "workflow";
+
+export const blobReady = defineHook<{ blobToken: string }>(); // [!code highlight]
+
+export async function importLargeFile(importId: string) {
+  "use workflow";
+
+  // Suspend until the external system signals the blob is uploaded
+  const { blobToken } = await blobReady.create({ token: `upload:${importId}` }); // [!code highlight]
+
+  // Process by reference -- the full payload never enters the event log
+  await processBlob(blobToken);
+
+  return { importId, blobToken, status: "indexed" };
+}
+
+async function processBlob(blobToken: string): Promise<void> {
+  "use step";
+  // Fetch the blob using the token, process it
+  const res = await fetch(`https://storage.example.com/blobs/${blobToken}`);
+  const data = await res.arrayBuffer();
+  // Index, transform, or store the data
+}
+```
+
+Resume from an API route when the upload completes:
+
+```typescript
+import { resumeHook } from "workflow/api";
+
+// POST /api/upload-complete
+export async function POST(request: Request) {
+  const { importId, blobToken } = await request.json();
+  await resumeHook(`upload:${importId}`, { blobToken }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Tips
+
+- **`respondWith: "manual"`** gives you control over the HTTP response from inside a step. Use this when you need to validate the request before responding.
+- **`for await` on a webhook** lets you process multiple events from the same URL. Use `break` to stop listening after a terminal event.
+- **Webhooks auto-generate URLs** at `/.well-known/workflow/v1/webhook/:token`. Pass this URL to external services.
+- **Race webhooks against `sleep()`** for deadlines. If the callback doesn't arrive in time, the workflow can take a fallback action.
+- **For large payloads**, use a hook + reference token instead of passing the data through the workflow. The event log serializes all step inputs/outputs, so large payloads hurt performance.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions with full Node.js access
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) -- creates an HTTP endpoint the workflow can await
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- creates a typed hook for signal-based patterns
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable timer for deadlines
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- prevents retry on permanent failures

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -0,0 +1,118 @@
+---
+title: Workflow Composition
+description: Call workflows from other workflows by direct await (flatten into the parent) or background spawn via start() (separate run).
+type: guide
+summary: Compose workflows two ways — direct await flattens the child into the parent's event log, while background spawn via start() runs the child as an independent run.
+related:
+  - /cookbook/advanced/child-workflows
+  - /docs/api-reference/workflow-api/start
+  - /docs/api-reference/workflow-api/get-run
+---
+
+Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with polling and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).
+
+## When to use this
+
+- **Direct await** — the parent needs the child's result before continuing, and you want a single unified event log
+- **Background spawn** — the parent doesn't need to wait, and you want the child to be observable as a separate run with its own `runId`
+
+## Pattern
+
+### Direct await (flattening)
+
+Call a child workflow with `await` and the child's steps execute inline within the parent — they appear in the parent's event log as if you'd called them directly.
+
+```typescript lineNumbers
+declare function sendEmail(userId: string): Promise<void>; // @setup
+declare function sendPushNotification(userId: string): Promise<void>; // @setup
+declare function createAccount(userId: string): Promise<void>; // @setup
+declare function setupPreferences(userId: string): Promise<void>; // @setup
+
+// Child workflow
+export async function sendNotifications(userId: string) {
+  "use workflow";
+
+  await sendEmail(userId);
+  await sendPushNotification(userId);
+  return { notified: true };
+}
+
+// Parent workflow calls the child directly
+export async function onboardUser(userId: string) {
+  "use workflow";
+
+  await createAccount(userId);
+  await sendNotifications(userId); // [!code highlight]
+  await setupPreferences(userId);
+
+  return { userId, status: "onboarded" };
+}
+```
+
+The parent waits for the child to finish before continuing. Both functions share a single workflow run, a single retry boundary, and a single event log.
+
+### Background spawn via `start()`
+
+To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+
+declare function generateReport(reportId: string): Promise<void>; // @setup
+declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
+declare function sendConfirmation(orderId: string): Promise<void>; // @setup
+
+async function triggerReportGeneration(reportId: string) {
+  "use step"; // [!code highlight]
+
+  const run = await start(generateReport, [reportId]); // [!code highlight]
+  return run.runId;
+}
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const order = await fulfillOrder(orderId);
+
+  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
+
+  await sendConfirmation(orderId);
+
+  return { orderId, reportRunId };
+}
+```
+
+The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).
+
+<Callout type="info">
+If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+</Callout>
+
+## How it works
+
+1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
+2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
+3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.
+
+## Choosing between the two modes
+
+| | Direct await | Background spawn (`start()`) |
+| --- | --- | --- |
+| Parent waits for child | Yes | No |
+| Has its own `runId` | No (shares parent's) | Yes |
+| Has its own event log | No | Yes |
+| Has its own retry boundary | No | Yes |
+| Best for | Sequential composition, helper workflows | Independent work, fire-and-forget, fan-out |
+
+## Adapting to your use case
+
+- **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
+- **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
+- **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
+- [`start()`](/docs/api-reference/workflow-api/start) — spawn a child workflow as a separate run
+- [`getRun()`](/docs/api-reference/workflow-api/get-run) — retrieve a workflow run's status and return value

package/docs/cookbook/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Cookbook
+description: Best-practice workflow patterns with copy-paste code examples.
+type: overview
+---
+
+A curated collection of workflow patterns with clean, copy-paste code examples for real use cases.
+
+## Agent Patterns
+
+- [**Durable Agent**](/cookbook/agent-patterns/durable-agent) — Replace a stateless AI agent with one that survives crashes and retries tool calls
+- [**Human-in-the-Loop**](/cookbook/agent-patterns/human-in-the-loop) — Pause an agent for human approval, then resume based on the decision
+- [**Agent Cancellation**](/cookbook/agent-patterns/agent-cancellation) — Stop a running agent immediately via `run.cancel()` or gracefully via a hook + `Promise.race`
+
+## Common Patterns
+
+- [**Sequential & Parallel Execution**](/cookbook/common-patterns/sequential-and-parallel) — Compose steps with `await`, `Promise.all`, and `Promise.race` against durable sleeps and webhooks
+- [**Workflow Composition**](/cookbook/common-patterns/workflow-composition) — Call workflows from other workflows by direct await or background spawn via `start()`
+- [**Saga**](/cookbook/common-patterns/saga) — Coordinate multi-step transactions with automatic rollback when a step fails
+- [**Batching**](/cookbook/common-patterns/batching) — Process large collections in parallel batches with failure isolation
+- [**Rate Limiting**](/cookbook/common-patterns/rate-limiting) — Handle 429 responses and transient failures with RetryableError and backoff
+- [**Scheduling**](/cookbook/common-patterns/scheduling) — Use durable sleep to schedule actions minutes, hours, or weeks ahead
+- [**Timeouts**](/cookbook/common-patterns/timeouts) — Add deadlines to slow steps, hooks, and webhooks by racing them against a durable sleep
+- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects happen exactly once, even when steps retry
+- [**Webhooks**](/cookbook/common-patterns/webhooks) — Receive HTTP callbacks from external services and process them durably
+
+## Integrations
+
+- [**AI SDK**](/cookbook/integrations/ai-sdk) — Use streamText() directly inside a workflow for lower-level control over model calls and tool execution
+- [**Chat SDK**](/cookbook/integrations/chat-sdk) — Build durable chat sessions with workflow persistence and AI SDK chat primitives
+- [**Sandbox**](/cookbook/integrations/sandbox) — Orchestrate Vercel Sandbox lifecycle inside durable workflows
+
+## Advanced
+
+- [**Child Workflows**](/cookbook/advanced/child-workflows) — Spawn and orchestrate child workflows from a parent
+- [**Distributed Abort Controller**](/cookbook/advanced/distributed-abort-controller) — Build a cross-process abort controller using workflow streams and hooks
+- [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable third-party objects so they cross the workflow boundary
+- [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions