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

package/docs/api-reference/create-webhook.mdx

@@ -0,0 +1,225 @@
+---
+title: createWebhook
+---
+
+Creates a webhook that can be used to suspend and resume a workflow run upon receiving an HTTP request.
+
+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.
+
+```ts lineNumbers
+import { createWebhook } from "workflow"
+
+export async function webhookWorkflow() {
+  "use workflow";
+  const webhook = createWebhook();  // [!code highlight]
+  console.log("Webhook URL:", webhook.url);
+
+  const request = await webhook; // Suspends until HTTP request received
+  console.log("Received request:", request.method, request.url);
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { createWebhook } from "workflow";
+export default createWebhook;`}
+showSections={['parameters']}
+/>
+
+### Returns
+
+<TSDoc
+definition={`
+import { createWebhook } from "workflow";
+export default createWebhook;`}
+showSections={['returns']}
+/>
+
+The returned `Webhook` object has:
+
+- `url`: The HTTP endpoint URL that external systems can call
+- `token`: The unique token identifying this webhook
+- Implements `AsyncIterable<RequestWithResponse>` for handling multiple requests
+
+The `RequestWithResponse` type extends the standard `Request` interface with a `respondWith(response: Response)` method for sending custom responses back to the caller.
+
+## Examples
+
+### Basic Usage
+
+Create a webhook that receives HTTP requests and logs the request details:
+
+```typescript lineNumbers
+import { createWebhook } from "workflow"
+
+export async function basicWebhookWorkflow() {
+  "use workflow";
+
+  const webhook = createWebhook(); // [!code highlight]
+  console.log("Send requests to:", webhook.url);
+
+  const request = await webhook;
+
+  console.log("Method:", request.method);
+  console.log("Headers:", Object.fromEntries(request.headers));
+
+  const body = await request.text();
+  console.log("Body:", body);
+}
+```
+
+### Responding to Webhook Requests
+
+Use the `respondWith()` method to send custom HTTP responses. Note that `respondWith()` must be called from within a step function:
+
+```typescript lineNumbers
+import { createWebhook, type RequestWithResponse } from "workflow"
+
+async function sendResponse(request: RequestWithResponse) { // [!code highlight]
+  "use step"; // [!code highlight]
+  await request.respondWith( // [!code highlight]
+    new Response(JSON.stringify({ success: true, message: "Received!" }), { // [!code highlight]
+      status: 200, // [!code highlight]
+      headers: { "Content-Type": "application/json" } // [!code highlight]
+    }) // [!code highlight]
+  ); // [!code highlight]
+} // [!code highlight]
+
+export async function respondingWebhookWorkflow() {
+  "use workflow";
+
+  const webhook = createWebhook();
+  console.log("Webhook URL:", webhook.url);
+
+  const request = await webhook;
+
+  // Send a custom response back to the caller
+  await sendResponse(request);
+
+  // Continue workflow processing
+  const data = await request.json();
+  await processData(data);
+}
+
+async function processData(data: any) {
+  "use step";
+  // Process the webhook data
+  console.log("Processing:", data);
+}
+```
+
+### Customizing Tokens
+
+Tokens are used to identify a specific webhook. You can customize the token to be more specific to a use case.
+
+```typescript lineNumbers
+import { type RequestWithResponse } from "workflow"
+
+async function sendAck(request: RequestWithResponse) {
+  "use step";
+  await request.respondWith(
+    new Response(JSON.stringify({ received: true }), {
+      headers: { "Content-Type": "application/json" }
+    })
+  );
+}
+
+export async function githubWebhookWorkflow(repoName: string) {
+  "use workflow";
+
+  // Use a deterministic token based on the repository
+  const webhook = createWebhook({ // [!code highlight]
+    token: `github_webhook:${repoName}`, // [!code highlight]
+  }); // [!code highlight]
+
+  console.log("Configure GitHub webhook:", webhook.url);
+
+  const request = await webhook;
+  const event = await request.json();
+
+  await sendAck(request);
+
+  await deployCommit(event);
+}
+
+async function deployCommit(event: any) {
+  "use step";
+  // Deploy logic here
+}
+```
+
+### Waiting for Multiple Requests
+
+You can also wait for multiple requests by using the `for await...of` syntax.
+
+```typescript lineNumbers
+import { createWebhook, type RequestWithResponse } from "workflow"
+
+async function sendSlackResponse(request: RequestWithResponse, message: string) {
+  "use step";
+  await request.respondWith(
+    new Response(
+      JSON.stringify({
+        response_type: "in_channel",
+        text: message
+      }),
+      { headers: { "Content-Type": "application/json" } }
+    )
+  );
+}
+
+async function sendStopResponse(request: RequestWithResponse) {
+  "use step";
+  await request.respondWith(
+    new Response("Stopping workflow...")
+  );
+}
+
+export async function slackCommandWorkflow(channelId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({
+    token: `slack_command:${channelId}`,
+  });
+
+  for await (const request of webhook) { // [!code highlight]
+    const formData = await request.formData();
+    const command = formData.get("command");
+    const text = formData.get("text");
+
+    if (command === "/status") {
+      // Respond immediately to Slack
+      await sendSlackResponse(request, "Checking status...");
+
+      // Process the command
+      const status = await checkSystemStatus();
+      await postToSlack(channelId, `Status: ${status}`);
+    }
+
+    if (text === "stop") {
+      await sendStopResponse(request);
+      break;
+    }
+  }
+}
+
+async function checkSystemStatus() {
+  "use step";
+  return "All systems operational";
+}
+
+async function postToSlack(channelId: string, message: string) {
+  "use step";
+  // Post message to Slack
+}
+```
+
+## Related Functions
+
+- [`createHook()`](/docs/api-reference/workflow/create-hook) - Lower-level hook primitive for arbitrary payloads
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
+- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) - Resume a webhook from an API route

package/docs/api-reference/define-hook.mdx

@@ -0,0 +1,206 @@
+---
+title: defineHook
+---
+
+Creates a type-safe hook helper that ensures the payload type is consistent between hook creation and resumption.
+
+This is a lightweight wrapper around [`createHook()`](/docs/api-reference/workflow/create-hook) and [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid type mismatches. It also supports optional runtime validation and transformation of payloads using any [Standard Schema v1](https://standardschema.dev) compliant validator like Zod or Valibot.
+
+<Callout>
+We recommend using `defineHook()` over `createHook()` in production codebases for better type safety and optional runtime validation.
+</Callout>
+
+```ts lineNumbers
+import { defineHook } from "workflow";
+
+const nameHook = defineHook<{
+  name: string;
+}>();
+
+export async function nameWorkflow() {
+  "use workflow";
+
+  const hook = nameHook.create();  // [!code highlight]
+  const result = await hook; // Fully typed as { name: string }
+  console.log("Name:", result.name);
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { defineHook } from "workflow";
+export default defineHook;`}
+showSections={['parameters']}
+/>
+
+### Returns
+
+<TSDoc
+definition={`
+interface DefineHook<T> {
+  /**
+
+* Creates a new hook with the defined payload type.
+  */
+  create: (options?: HookOptions) => Hook<T>;
+
+  /**
+
+* Resumes a hook by sending a payload with the defined type.
+   */
+  resume: (token: string, payload: T) => Promise<HookEntity | null>;
+}
+export default DefineHook;`}
+/>
+
+## Examples
+
+### Basic Type-Safe Hook Definition
+
+By defining the hook once with a specific payload type, you can reuse it in multiple workflows and API routes with automatic type safety.
+
+```typescript lineNumbers
+import { defineHook } from "workflow";
+
+// Define once with a specific payload type
+const approvalHook = defineHook<{ // [!code highlight]
+  approved: boolean; // [!code highlight]
+  comment: string; // [!code highlight]
+}>(); // [!code highlight]
+
+// In your workflow
+export async function workflowWithApproval() {
+  "use workflow";
+
+  const hook = approvalHook.create();
+  const result = await hook; // Fully typed as { approved: boolean; comment: string }
+
+  console.log("Approved:", result.approved);
+  console.log("Comment:", result.comment);
+}
+```
+
+### Resuming with Type Safety
+
+Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.
+
+```typescript lineNumbers
+// Use the same defined hook to resume
+export async function POST(request: Request) {
+  const { token, approved, comment } = await request.json();
+
+  // Type-safe resumption - TypeScript ensures the payload matches
+  const result = await approvalHook.resume(token, { // [!code highlight]
+    approved, // [!code highlight]
+    comment, // [!code highlight]
+  }); // [!code highlight]
+
+  if (!result) {
+    return Response.json({ error: "Hook not found" }, { status: 404 });
+  }
+
+  return Response.json({ success: true, runId: result.runId });
+}
+```
+
+### Validate and Transform with Schema
+
+You can provide runtime validation and transformation of hook payloads using the `schema` option. This option accepts any validator that conforms to the [Standard Schema v1](https://standardschema.dev) specification.
+
+<Callout type="info">
+Standard Schema is a standardized specification for schema validation libraries. Most popular validation libraries support it, including Zod, Valibot, ArkType, and Effect Schema. You can also write custom validators.
+</Callout>
+
+#### Using Zod with defineHook
+
+Here's an example using [Zod](https://zod.dev) to validate and transform hook payloads:
+
+```typescript lineNumbers
+import { defineHook } from "workflow";
+import { z } from "zod";
+
+export const approvalHook = defineHook({
+  schema: z.object({ // [!code highlight]
+    approved: z.boolean(), // [!code highlight]
+    comment: z.string().min(1).transform((value) => value.trim()), // [!code highlight]
+  }), // [!code highlight]
+});
+
+export async function approvalWorkflow(approvalId: string) {
+  "use workflow";
+
+  const hook = approvalHook.create({
+    token: `approval:${approvalId}`,
+  });
+
+  // Payload is automatically typed based on the schema
+  const { approved, comment } = await hook;
+  console.log("Approved:", approved);
+  console.log("Comment (trimmed):", comment);
+}
+```
+
+When resuming the hook from an API route, the schema validates and transforms the incoming payload before the workflow resumes:
+
+```typescript lineNumbers
+export async function POST(request: Request) {
+  // Incoming payload: { token: "...", approved: true, comment: "   Ready!   " }
+  const { token, approved, comment } = await request.json();
+
+  // The schema validates and transforms the payload:
+  // - Checks that `approved` is a boolean
+  // - Checks that `comment` is a non-empty string
+  // - Trims whitespace from the comment
+  // If validation fails, an error is thrown and the hook is not resumed
+  await approvalHook.resume(token, { // [!code highlight]
+    approved, // [!code highlight]
+    comment, // Automatically trimmed to "Ready!" // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+#### Using Other Standard Schema Libraries
+
+The same pattern works with any Standard Schema v1 compliant library. Here's an example with [Valibot](https://valibot.dev):
+
+```typescript lineNumbers
+import { defineHook } from "workflow";
+import * as v from "valibot";
+
+export const approvalHook = defineHook({
+  schema: v.object({ // [!code highlight]
+    approved: v.boolean(), // [!code highlight]
+    comment: v.pipe(v.string(), v.minLength(1), v.trim()), // [!code highlight]
+  }), // [!code highlight]
+});
+```
+
+### Customizing Tokens
+
+Tokens are used to identify a specific hook and for resuming a hook. You can customize the token to be more specific to a use case.
+
+```typescript lineNumbers
+const slackHook = defineHook<{ text: string; userId: string }>();
+
+export async function slackBotWorkflow(channelId: string) {
+  "use workflow";
+
+  const hook = slackHook.create({
+    token: `slack:${channelId}`, // [!code highlight]
+  });
+
+  const message = await hook;
+  console.log(`Message from ${message.userId}: ${message.text}`);
+}
+```
+
+## Related Functions
+
+* [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
+* [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload.

package/docs/api-reference/fatal-error.mdx

@@ -0,0 +1,37 @@
+---
+title: FatalError
+---
+
+When a `FatalError` is thrown in a step, it indicates that the workflow should not retry a step, marking it as failure.
+
+You should use this when you don't want a specific step to retry.
+
+```typescript lineNumbers
+import { FatalError } from "workflow"
+
+async function fallibleWorkflow() {
+    "use workflow"
+    await fallibleStep();
+}
+
+async function fallibleStep() {
+    "use step"
+    throw new FatalError("Fallible!") // [!code highlight]
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+interface Error {
+  /**
+
+* The error message.
+   */
+  message: string;
+}
+export default Error;`}
+/>

package/docs/api-reference/fetch.mdx

@@ -0,0 +1,139 @@
+---
+title: fetch
+---
+
+Makes HTTP requests from within a workflow. This is a special step function that wraps the standard `fetch` API, automatically handling serialization and providing retry semantics.
+
+This is useful when you need to call external APIs or services from within your workflow.
+
+<Callout>
+`fetch` is a *special* type of step function provided and should be called directly inside workflow functions.
+</Callout>
+
+```typescript lineNumbers
+import { fetch } from "workflow"
+
+async function apiWorkflow() {
+    "use workflow"
+
+    // Fetch data from an API
+    const response = await fetch("https://api.example.com/data") // [!code highlight]
+    return await response.json()
+}
+```
+
+## API Signature
+
+### Parameters
+
+Accepts the same arguments as web [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)
+
+<TSDoc
+definition={`
+import { fetch } from "workflow";
+export default fetch;`}
+showSections={['parameters']}
+/>
+
+### Returns
+
+Returns the same response as web [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)
+
+<TSDoc
+definition={`
+import { fetch } from "workflow";
+export default fetch;`}
+showSections={['returns']}
+/>
+
+## Examples
+
+### Basic Usage
+
+Here's a simple example of how you can use `fetch` inside your workflow.
+
+```typescript lineNumbers
+import { fetch } from "workflow"
+
+async function apiWorkflow() {
+    "use workflow"
+
+    // Fetch data from an API
+    const response = await fetch("https://api.example.com/data") // [!code highlight]
+    const data = await response.json()
+
+    // Make a POST request
+    const postResponse = await fetch("https://api.example.com/create", { // [!code highlight]
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ name: "test" })
+    })
+
+    return data
+}
+```
+
+We call `fetch()` with a URL and optional request options, just like the standard fetch API. The workflow runtime automatically handles the response serialization.
+
+This API is provided as a convenience to easily use `fetch` in workflow, but often, you might want to extend and implement your own fetch for more powerful error handing and retry logic.
+
+### Customizing Fetch Behavior
+
+Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic:
+
+```typescript lineNumbers
+import { FatalError, RetryableError } from "workflow"
+
+export async function customFetch(
+    url: string,
+    init?: RequestInit
+) {
+    "use step"
+
+    const response = await fetch(url, init)
+
+    // Handle client errors (4xx) - don't retry
+    if (response.status >= 400 && response.status < 500) {
+        if (response.status === 429) {
+            // Rate limited - retry with backoff from Retry-After header
+            const retryAfter = response.headers.get("Retry-After")
+
+            if (retryAfter) {
+                // The Retry-After header is either a number (seconds) or an RFC 7231 date string
+                const retryAfterValue = /^\d+$/.test(retryAfter)
+                    ? parseInt(retryAfter) * 1000  // Convert seconds to milliseconds
+                    : new Date(retryAfter);        // Parse RFC 7231 date format
+
+                // Use `RetryableError` to customize the retry
+                throw new RetryableError( // [!code highlight]
+                    `Rate limited by ${url}`, // [!code highlight]
+                    { retryAfter: retryAfterValue } // [!code highlight]
+                ) // [!code highlight]
+            }
+        }
+
+        // Other client errors are fatal (400, 401, 403, 404, etc.)
+        throw new FatalError( // [!code highlight]
+            `Client error ${response.status}: ${response.statusText}` // [!code highlight]
+        ) // [!code highlight]
+    }
+
+    // Handle server errors (5xx) - will retry automatically
+    if (!response.ok) {
+        throw new Error(
+            `Server error ${response.status}: ${response.statusText}`
+        )
+    }
+
+    return response
+}
+```
+
+This example demonstrates:
+
+- Setting custom `maxRetries` to 5 retries (6 total attempts including the initial attempt).
+- Throwing [`FatalError`](/docs/api-reference/workflow/fatal-error) for client errors (400-499) to prevent retries.
+- Handling 429 rate limiting by reading the `Retry-After` header and using [`RetryableError`](/docs/api-reference/workflow/retryable-error).
+- Allowing automatic retries for server errors (5xx).

package/docs/api-reference/get-step-metadata.mdx

@@ -0,0 +1,76 @@
+---
+title: getStepMetadata
+---
+
+Returns metadata available in the current step function.
+
+You may want to use this function when you need to:
+
+- Track retry attempts in error handling
+- Access timing information of a step and execution metadata
+- Generate idempotency keys for external APIs
+
+<Callout type="warn">
+  This function can only be called inside a step function.
+</Callout>
+
+```typescript lineNumbers
+import { getStepMetadata } from "workflow";
+
+async function testWorkflow() {
+  "use workflow";
+  await logStepId();
+}
+
+async function logStepId() {
+  "use step";
+  const ctx = getStepMetadata(); // [!code highlight]
+  console.log(ctx.stepId); // Grab the current step ID
+}
+```
+
+### Example: Use `stepId` as an idempotency key
+
+```typescript lineNumbers
+import { getStepMetadata } from "workflow";
+
+async function chargeUser(userId: string, amount: number) {
+  "use step";
+  const { stepId } = getStepMetadata();
+
+  await stripe.charges.create(
+    {
+      amount,
+      currency: "usd",
+      customer: userId,
+    },
+    {
+      idempotencyKey: `charge:${stepId}`, // [!code highlight]
+    }
+  );
+}
+```
+
+<Callout type="info">
+  Learn more about patterns and caveats in the{" "}
+  <a href="/docs/foundations/idempotency">Idempotency</a> guide.
+</Callout>
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+  definition={`
+import { getStepMetadata } from "workflow";
+export default getStepMetadata;`}
+  showSections={["parameters"]}
+/>
+
+### Returns
+
+<TSDoc
+  definition={`
+import type { StepMetadata } from "workflow";
+export default StepMetadata;`}
+/>