@workflow/core 4.0.1-beta.8 → 4.1.0-beta.51

package/docs/foundations/hooks.mdx

@@ -0,0 +1,455 @@
+---
+title: Hooks & Webhooks
+---
+
+Hooks provide a powerful mechanism for pausing workflow execution and resuming it later with external data. They enable workflows to wait for external events, user interactions (also known as "human in the loop"), or HTTP requests. This guide will teach you the core concepts, starting with the low-level Hook primitive and building up to the higher-level Webhook abstraction.
+
+## Understanding Hooks
+
+At their core, **Hooks** are a low-level primitive that allows you to pause a workflow and resume it later with arbitrary [serializable data](/docs/foundations/serialization). Think of them as suspension points in your workflow where you're waiting for external input.
+
+When you create a hook, it generates a unique token that external systems can use to send data back to your workflow. This makes hooks perfect for scenarios like:
+
+- Waiting for approval from a user or admin
+- Receiving data from an external system or service
+- Implementing event-driven workflows that react to multiple events over time
+
+### Creating Your First Hook
+
+Let's start with a simple example. Here's a workflow that creates a hook and waits for external data:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function approvalWorkflow() {
+  "use workflow";
+
+  // Create a hook that expects an approval payload
+  const hook = createHook<{ approved: boolean; comment: string }>();
+
+  console.log("Waiting for approval...");
+  console.log("Send approval to token:", hook.token);
+
+  // Workflow pauses here until data is sent
+  const result = await hook;
+
+  if (result.approved) {
+    console.log("Approved with comment:", result.comment);
+    // Continue with approved workflow...
+  } else {
+    console.log("Rejected:", result.comment);
+    // Handle rejection...
+  }
+}
+```
+
+The workflow will pause at `await hook` until external code sends data to resume it.
+
+<Callout type="info">
+See the full API reference for [`createHook()`](/docs/api-reference/workflow/create-hook) for all available options.
+</Callout>
+
+### Resuming a Hook
+
+To send data to a waiting workflow, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) from an API route, server action, or any other external context:
+
+```typescript lineNumbers
+import { resumeHook } from "workflow/api";
+
+// In an API route or external handler
+export async function POST(request: Request) {
+  const { token, approved, comment } = await request.json();
+
+  try {
+    // Resume the workflow with the approval data
+    const result = await resumeHook(token, { approved, comment });
+    return Response.json({ success: true, runId: result.runId });
+  } catch (error) {
+    return Response.json({ error: "Invalid token" }, { status: 404 });
+  }
+}
+```
+
+The key points:
+- Hooks allow you to pass **any [serializable data](/docs/foundations/serialization)** as the payload
+- You need the hook's `token` to resume it
+- The workflow will resume execution right where it left off
+
+### Custom Tokens for Deterministic Hooks
+
+By default, hooks generate a random token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.
+
+For example, imagine a Slack bot where each channel should have its own workflow instance:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function slackChannelBot(channelId: string) {
+  "use workflow";
+
+  // Use channel ID in the token so Slack webhooks can find this workflow
+  const hook = createHook<SlackMessage>({
+    token: `slack_messages:${channelId}`
+  });
+
+  for await (const message of hook) {
+    console.log(`${message.user}: ${message.text}`);
+
+    if (message.text === "/stop") {
+      break;
+    }
+
+    await processMessage(message);
+  }
+}
+
+async function processMessage(message: SlackMessage) {
+  "use step";
+  // Process the Slack message
+}
+```
+
+Now your Slack webhook handler can deterministically resume the correct workflow:
+
+```typescript lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const slackEvent = await request.json();
+  const channelId = slackEvent.channel;
+
+  try {
+    // Reconstruct the token using the channel ID
+    await resumeHook(`slack_messages:${channelId}`, slackEvent);
+
+    return new Response("OK");
+  } catch (error) {
+    return new Response("Hook not found", { status: 404 });
+  }
+}
+```
+
+### Receiving Multiple Events
+
+Hooks are _reusable_ - they implement `AsyncIterable`, which means you can use `for await...of` to receive multiple events over time:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function dataCollectionWorkflow() {
+  "use workflow";
+
+  const hook = createHook<{ value: number; done?: boolean }>();
+
+  const values: number[] = [];
+
+  // Keep receiving data until we get a "done" signal
+  for await (const payload of hook) {
+    values.push(payload.value);
+
+    if (payload.done) {
+      break;
+    }
+  }
+
+  console.log("Collected values:", values);
+  return values;
+}
+```
+
+Each time you call `resumeHook()` with the same token, the loop receives another value.
+
+## Understanding Webhooks
+
+While hooks are powerful, they require you to manually handle HTTP requests and route them to workflows. **Webhooks** solve this by providing a higher-level abstraction built on top of hooks that:
+
+1. Automatically serializes the entire HTTP [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
+2. Provides an automatically addressable `url` property pointing to the generated webhook endpoint
+3. Handles sending HTTP [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects back to the caller
+
+When using Workflow DevKit, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
+
+<Callout type="info">
+See the full API reference for [`createWebhook()`](/docs/api-reference/workflow/create-webhook) for all available options.
+</Callout>
+
+### Creating Your First Webhook
+
+Here's a simple webhook that receives HTTP requests:
+
+```typescript lineNumbers
+import { createWebhook } from "workflow";
+
+export async function webhookWorkflow() {
+  "use workflow";
+
+  const webhook = createWebhook();
+
+  // The webhook is automatically available at this URL
+  console.log("Send HTTP requests to:", webhook.url);
+  // Example: https://your-app.com/.well-known/workflow/v1/webhook/lJHkuMdQ2FxSFTbUMU84k
+
+  // Workflow pauses until an HTTP request is received
+  const request = await webhook;
+
+  console.log("Received request:", request.method, request.url);
+
+  // Access the request body
+  const data = await request.json();
+  console.log("Data:", data);
+}
+```
+
+The webhook will automatically respond with a `202 Accepted` status by default. External systems can simply make an HTTP request to the `webhook.url` to resume your workflow.
+
+### Sending Custom Responses
+
+Webhooks provide two ways to send custom HTTP responses: **static responses** and **dynamic responses**.
+
+#### Static Responses
+
+Use the `respondWith` option to provide a static response that will be sent automatically for every request:
+
+```typescript lineNumbers
+import { createWebhook } from "workflow";
+
+export async function webhookWithStaticResponse() {
+  "use workflow";
+
+  const webhook = createWebhook({
+    respondWith: Response.json({
+      success: true, message: "Webhook received"
+    }),
+  });
+
+  const request = await webhook;
+
+  // The response was already sent automatically
+  // Continue processing the request asynchronously
+  const data = await request.json();
+  await processData(data);
+}
+
+async function processData(data: any) {
+  "use step";
+  // Long-running processing here
+}
+```
+
+#### Dynamic Responses (Manual Mode)
+
+For dynamic responses based on the request content, set `respondWith: "manual"` and call the `respondWith()` method on the request:
+
+```typescript lineNumbers
+import { createWebhook, type RequestWithResponse } from "workflow";
+
+async function sendCustomResponse(request: RequestWithResponse, message: string) {
+  "use step";
+
+  // Call respondWith() to send the response
+  await request.respondWith(
+    new Response(
+      JSON.stringify({ message }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      }
+    )
+  );
+}
+
+export async function webhookWithDynamicResponse() {
+  "use workflow";
+
+  // Set respondWith to "manual" to handle responses yourself
+  const webhook = createWebhook({ respondWith: "manual" });
+
+  const request = await webhook;
+  const data = await request.json();
+
+  // Decide what response to send based on the data
+  if (data.type === "urgent") {
+    await sendCustomResponse(request, "Processing urgently");
+  } else {
+    await sendCustomResponse(request, "Processing normally");
+  }
+
+  // Continue workflow...
+}
+```
+
+<Callout type="warning">
+When using `respondWith: "manual"`, the `respondWith()` method **must** be called from within a step function due to serialization requirements. This requirement may be removed in the future.
+</Callout>
+
+### Handling Multiple Webhook Requests
+
+Like hooks, webhooks support iteration:
+
+```typescript lineNumbers
+import { createWebhook, type RequestWithResponse } from "workflow";
+
+async function respondToSlack(request: RequestWithResponse, text: string) {
+  "use step";
+
+  await request.respondWith(
+    new Response(
+      JSON.stringify({ response_type: "in_channel", text }),
+      { headers: { "Content-Type": "application/json" } }
+    )
+  );
+}
+
+export async function slackCommandWorkflow(channelId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({
+    token: `slack_command:${channelId}`,
+    respondWith: "manual"
+  });
+
+  console.log("Configure Slack command webhook:", webhook.url);
+
+  for await (const request of webhook) {
+    const formData = await request.formData();
+    const command = formData.get("command");
+    const text = formData.get("text");
+
+    if (command === "/status") {
+      await respondToSlack(request, "Checking status...");
+      const status = await checkSystemStatus();
+      await postToSlack(channelId, `Status: ${status}`);
+    }
+
+    if (text === "stop") {
+      await respondToSlack(request, "Stopping workflow...");
+      break;
+    }
+  }
+}
+
+async function checkSystemStatus() {
+  "use step";
+  return "All systems operational";
+}
+
+async function postToSlack(channelId: string, message: string) {
+  "use step";
+  // Post message to Slack
+}
+```
+
+## Hooks vs. Webhooks: When to Use Each
+
+| Feature | Hooks | Webhooks |
+|---------|-------|----------|
+| **Data Format** | Arbitrary serializable data | HTTP `Request` objects |
+| **URL** | No automatic URL | Automatic `webhook.url` property |
+| **Response Handling** | N/A | Can send HTTP `Response` (static or dynamic) |
+| **Use Case** | Custom integrations, type-safe payloads | HTTP webhooks, standard REST APIs |
+| **Resuming** | [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) | Automatic via HTTP, or [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) |
+
+**Use Hooks when:**
+- You need full control over the payload structure
+- You're integrating with custom event sources
+- You want strong TypeScript typing with [`defineHook()`](/docs/api-reference/workflow/define-hook)
+
+**Use Webhooks when:**
+- You're receiving HTTP requests from external services
+- You need to send HTTP responses back to the caller
+- You want automatic URL routing without writing API handlers
+
+## Advanced Patterns
+
+### Type-Safe Hooks with `defineHook()`
+
+The [`defineHook()`](/docs/api-reference/workflow/define-hook) helper provides type safety and runtime validation between creating and resuming hooks using [Standard Schema v1](https://standardschema.dev). Use any compliant validator like Zod or Valibot:
+
+```typescript lineNumbers
+import { defineHook } from "workflow";
+import { z } from "zod";
+
+// Define the hook with schema for type safety and runtime validation
+const approvalHook = defineHook({ // [!code highlight]
+  schema: z.object({ // [!code highlight]
+    requestId: z.string(), // [!code highlight]
+    approved: z.boolean(), // [!code highlight]
+    approvedBy: z.string(), // [!code highlight]
+    comment: z.string().transform((value) => value.trim()), // [!code highlight]
+  }), // [!code highlight]
+}); // [!code highlight]
+
+// In your workflow
+export async function documentApprovalWorkflow(documentId: string) {
+  "use workflow";
+
+  const hook = approvalHook.create({
+    token: `approval:${documentId}`
+  });
+
+  // Payload is type-safe and validated
+  const approval = await hook;
+
+  console.log(`Document ${approval.requestId} ${approval.approved ? "approved" : "rejected"}`);
+  console.log(`By: ${approval.approvedBy}, Comment: ${approval.comment}`);
+}
+
+// In your API route - both type-safe and runtime-validated!
+export async function POST(request: Request) {
+  const { documentId, ...approvalData } = await request.json();
+
+  try {
+    // The schema validates the payload before resuming the workflow
+    await approvalHook.resume(`approval:${documentId}`, approvalData);
+    return new Response("OK");
+  } catch (error) {
+    return Response.json({ error: "Invalid token or validation failed" }, { status: 400 });
+  }
+}
+```
+
+This pattern is especially valuable in larger applications where the workflow and API code are in separate files, providing both compile-time type safety and runtime validation.
+
+## Best Practices
+
+### Token Design
+
+When using custom tokens:
+
+- **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
+- **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)
+- **Include routing information**: Ensure the token contains enough information to identify the correct workflow instance
+
+### Response Handling in Webhooks
+
+- Use **static responses** (`respondWith: Response`) for simple acknowledgments
+- Use **manual mode** (`respondWith: "manual"`) when responses depend on request processing
+- Remember that `respondWith()` must be called from within a step function
+
+### Iterating Over Events
+
+Both hooks and webhooks support iteration, making them perfect for long-running event loops:
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript
+const hook = createHook<Event>();
+
+for await (const event of hook) {
+  await processEvent(event);
+
+  if (shouldStop(event)) {
+    break;
+  }
+}
+```
+
+This pattern allows a single workflow instance to handle multiple events over time, maintaining state between events.
+
+## Related Documentation
+
+- [Serialization](/docs/foundations/serialization) - Understanding what data can be passed through hooks
+- [`createHook()` API Reference](/docs/api-reference/workflow/create-hook)
+- [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook)
+- [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook)
+- [`resumeHook()` API Reference](/docs/api-reference/workflow-api/resume-hook)
+- [`resumeWebhook()` API Reference](/docs/api-reference/workflow-api/resume-webhook)

package/docs/foundations/idempotency.mdx

@@ -0,0 +1,55 @@
+---
+title: Idempotency
+---
+
+Idempotency is a property of an operation that ensures it can be safely retried without producing duplicate side effects.
+
+In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once just by seeing if it succeeds.
+Consider a payment API that charges the user $10, but due to network failures, the confirmation response is lost. When the step retries (because the previous attempt was considered a failure), it will charge the user again.
+
+To prevent this, many external APIs support idempotency keys. An idempotency key is a unique identifier for an operation that can be used to deduplicate requests.
+
+## The core pattern: use the step ID as your idempotency key
+
+Every step invocation has a stable `stepId` that stays the same across retries.
+Use it as the idempotency key when calling third-party APIs.
+
+```typescript lineNumbers
+import { getStepMetadata } from "workflow";
+
+async function chargeUser(userId: string, amount: number) {
+  "use step";
+
+  const { stepId } = getStepMetadata();
+
+  // Example: Stripe-style idempotency key
+  // This guarantees only one charge is created even if the step retries
+  await stripe.charges.create(
+    {
+      amount,
+      currency: "usd",
+      customer: userId,
+    },
+    {
+      idempotencyKey: stepId, // [!code highlight]
+    }
+  );
+}
+```
+
+Why this works:
+
+- **Stable across retries**: `stepId` does not change between attempts.
+- **Globally unique per step**: Fulfills the uniqueness requirement for an idempotency key.
+
+## Best practices
+
+- **Always provide idempotency keys to external side effects that are not idempotent** inside steps (payments, emails, SMS, queues).
+- **Prefer `stepId` as your key**; it is stable across retries and unique per step.
+- **Keep keys deterministic**; avoid including timestamps or attempt counters.
+- **Handle 409/conflict responses** gracefully; treat them as success if the prior attempt completed.
+
+## Related docs
+
+- Learn about retries in [Errors & Retrying](/docs/foundations/errors-and-retries)
+- API reference: [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata)

package/docs/foundations/index.mdx

@@ -0,0 +1,32 @@
+---
+title: Foundations
+---
+
+Workflow programming can be a slight shift from how you traditionally write real-world applications. Learning the foundations now will go a long way toward helping you use workflows effectively.
+
+<Cards>
+    <Card href="/docs/foundations/workflows-and-steps" title="Workflows and Steps">
+        Learn about the building blocks of durability
+    </Card>
+    <Card href="/docs/foundations/starting-workflows" title="Starting Workflows">
+        Trigger workflows and track their execution using the `start()` function.
+    </Card>
+    <Card href="/docs/foundations/common-patterns" title="Common Patterns">
+        Common patterns useful in workflows.
+    </Card>
+    <Card href="/docs/foundations/errors-and-retries" title="Errors & Retrying">
+        Types of errors and how retrying work in workflows.
+    </Card>
+    <Card href="/docs/foundations/hooks" title="Webhooks (and hooks)">
+        Respond to external events in your workflow using hooks and webhooks.
+    </Card>
+    <Card href="/docs/foundations/streaming" title="Streaming">
+        Stream data in real-time to clients without waiting for the workflow to complete.
+    </Card>
+    <Card href="/docs/foundations/serialization" title="Serialization">
+        Understand which types can be passed between workflow and step functions.
+    </Card>
+    <Card href="/docs/foundations/idempotency" title="Idempotency">
+        Prevent duplicate side effects when retrying operations.
+    </Card>
+</Cards>

package/docs/foundations/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "Foundations",
+  "pages": [
+    "workflows-and-steps",
+    "starting-workflows",
+    "common-patterns",
+    "errors-and-retries",
+    "hooks",
+    "streaming",
+    "serialization",
+    "idempotency"
+  ],
+  "defaultOpen": true
+}