Merge branch 'main' into peter/web-animation-fast

Author: VaguelySerious

.changeset/light-planes-grin.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+BREAKING: `resumeHook()` now throws errors (including when a Hook is not found for a given "token") instead of returning `null`

docs/content/docs/api-reference/workflow-api/resume-hook.mdx

@@ -19,15 +19,15 @@ import { resumeHook } from "workflow/api";
 
 export async function POST(request: Request) {
   const { token, data } = await request.json();
-  const result = await resumeHook(token, data); // [!code highlight]
 
-  if (!result) {
+  try {
+    const result = await resumeHook(token, data); // [!code highlight]
+    return Response.json({
+      runId: result.runId
+    });
+  } catch (error) {
     return new Response('Hook not found', { status: 404 });
   }
-
-  return Response.json({
-    runId: result.runId
-  });
 }
 ```
 
@@ -46,7 +46,7 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Hook | null>` that resolves to:
+Returns a `Promise<Hook>` that resolves to:
 
 <TSDoc
 definition={generateDefinition({
@@ -69,16 +69,16 @@ import { resumeHook } from "workflow/api";
 export async function POST(request: Request) {
   const { token, data } = await request.json();
 
-  const result = await resumeHook(token, data); // [!code highlight]
+  try {
+    const result = await resumeHook(token, data); // [!code highlight]
 
-  if (!result) {
+    return Response.json({
+      success: true,
+      runId: result.runId
+    });
+  } catch (error) {
     return new Response('Hook not found', { status: 404 });
   }
-
-  return Response.json({
-    success: true,
-    runId: result.runId
-  });
 }
 ```
 
@@ -97,16 +97,16 @@ type ApprovalPayload = {
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  const result = await resumeHook<ApprovalPayload>(token, { // [!code highlight]
-    approved, // [!code highlight]
-    comment, // [!code highlight]
-  }); // [!code highlight]
+  try {
+    const result = await resumeHook<ApprovalPayload>(token, { // [!code highlight]
+      approved, // [!code highlight]
+      comment, // [!code highlight]
+    }); // [!code highlight]
 
-  if (!result) {
+    return Response.json({ runId: result.runId });
+  } catch (error) {
     return Response.json({ error: 'Invalid token' }, { status: 404 });
   }
-
-  return Response.json({ runId: result.runId });
 }
 ```
 
@@ -120,13 +120,12 @@ Using `resumeHook` in Next.js server actions to resume a hook:
 import { resumeHook } from "workflow/api";
 
 export async function approveRequest(token: string, approved: boolean) {
-  const result = await resumeHook(token, { approved });
-
-  if (!result) {
+  try {
+    const result = await resumeHook(token, { approved });
+    return result.runId;
+  } catch (error) {
     throw new Error('Invalid approval token');
   }
-
-  return result.runId;
 }
 ```
 
@@ -146,14 +145,14 @@ export async function POST(request: Request) {
     return Response.json({ error: 'Missing token' }, { status: 400 });
   }
 
-  const body = await request.json();
-  const result = await resumeHook(token, body);
+  try {
+    const body = await request.json();
+    const result = await resumeHook(token, body);
 
-  if (!result) {
+    return Response.json({ success: true, runId: result.runId });
+  } catch (error) {
     return Response.json({ error: 'Hook not found' }, { status: 404 });
   }
-
-  return Response.json({ success: true, runId: result.runId });
 }
 ```
 

docs/content/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -25,13 +25,12 @@ export async function POST(request: Request) {
     return new Response('Missing token', { status: 400 });
   }
 
-  const response = await resumeWebhook(token, request); // [!code highlight]
-
-  if (!response) {
+  try {
+    const response = await resumeWebhook(token, request); // [!code highlight]
+    return response;
+  } catch (error) {
     return new Response('Webhook not found', { status: 404 });
   }
-
-  return response;
 }
 ```
 
@@ -50,10 +49,11 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Response | null>` that resolves to:
+Returns a `Promise<Response>` that resolves to:
 
 - `Response`: The HTTP response from the workflow's `respondWith()` call
-- `null`: If the webhook token is not found or invalid
+
+Throws an error if the webhook token is not found or invalid.
 
 ## Examples
 
@@ -72,13 +72,12 @@ export async function POST(request: Request) {
     return new Response('Token required', { status: 400 });
   }
 
-  const response = await resumeWebhook(token, request); // [!code highlight]
-
-  if (!response) {
+  try {
+    const response = await resumeWebhook(token, request); // [!code highlight]
+    return response; // Returns the workflow's custom response
+  } catch (error) {
     return new Response('Webhook not found', { status: 404 });
   }
-
-  return response; // Returns the workflow's custom response
 }
 ```
 
@@ -106,13 +105,12 @@ export async function POST(request: Request) {
   // Construct deterministic token
   const token = `github_webhook:${repo}`;
 
-  const response = await resumeWebhook(token, request); // [!code highlight]
-
-  if (!response) {
+  try {
+    const response = await resumeWebhook(token, request); // [!code highlight]
+    return response;
+  } catch (error) {
     return new Response('Workflow not found', { status: 404 });
   }
-
-  return response;
 }
 ```
 
@@ -137,9 +135,10 @@ export async function POST(request: Request) {
   // Construct token from channel ID
   const token = `slack_command:${channelId}`;
 
-  const response = await resumeWebhook(token, request); // [!code highlight]
-
-  if (!response) {
+  try {
+    const response = await resumeWebhook(token, request); // [!code highlight]
+    return response;
+  } catch (error) {
     // If no workflow is listening, return a default response
     return new Response(
       JSON.stringify({
@@ -151,8 +150,6 @@ export async function POST(request: Request) {
       }
     );
   }
-
-  return response;
 }
 ```
 
@@ -185,13 +182,12 @@ export async function POST(request: Request) {
   // Construct namespaced token
   const token = `tenant:${tenantId}:webhook:${webhookId}`;
 
-  const response = await resumeWebhook(token, request); // [!code highlight]
-
-  if (!response) {
+  try {
+    const response = await resumeWebhook(token, request); // [!code highlight]
+    return response;
+  } catch (error) {
     return new Response('Webhook not found or expired', { status: 404 });
   }
-
-  return response;
 }
 
 async function verifyTenantApiKey(tenantId: string, apiKey: string | null) {
@@ -222,19 +218,19 @@ export async function triggerWebhook(
     body: JSON.stringify(payload),
   });
 
-  const response = await resumeWebhook(token, request);
+  try {
+    const response = await resumeWebhook(token, request);
 
-  if (!response) {
-    throw new Error('Webhook not found');
-  }
+    // Parse and return the response
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('application/json')) {
+      return await response.json();
+    }
 
-  // Parse and return the response
-  const contentType = response.headers.get('content-type');
-  if (contentType?.includes('application/json')) {
-    return await response.json();
+    return await response.text();
+  } catch (error) {
+    throw new Error('Webhook not found');
   }
-
-  return await response.text();
 }
 ```
 

docs/content/docs/foundations/hooks.mdx

@@ -62,12 +62,11 @@ import { resumeHook } from "workflow/api";
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  // Resume the workflow with the approval data
-  const result = await resumeHook(token, { approved, comment });
-
-  if (result) {
+  try {
+    // Resume the workflow with the approval data
+    const result = await resumeHook(token, { approved, comment });
     return Response.json({ success: true, runId: result.runId });
-  } else {
+  } catch (error) {
     return Response.json({ error: "Invalid token" }, { status: 404 });
   }
 }
@@ -121,10 +120,14 @@ export async function POST(request: Request) {
   const slackEvent = await request.json();
   const channelId = slackEvent.channel;
 
-  // Reconstruct the token using the channel ID
-  await resumeHook(`slack_messages:${channelId}`, slackEvent);
+  try {
+    // Reconstruct the token using the channel ID
+    await resumeHook(`slack_messages:${channelId}`, slackEvent);
 
-  return new Response("OK");
+    return new Response("OK");
+  } catch (error) {
+    return new Response("Hook not found", { status: 404 });
+  }
 }
 ```
 
@@ -397,10 +400,13 @@ export async function documentApprovalWorkflow(documentId: string) {
 export async function POST(request: Request) {
   const { documentId, ...approvalData } = await request.json();
 
-  // The schema validates the payload before resuming the workflow
-  await approvalHook.resume(`approval:${documentId}`, approvalData);
-
-  return new Response("OK");
+  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 });
+  }
 }
 ```
 

packages/core/src/define-hook.test.ts

@@ -61,7 +61,11 @@ describe('defineHook', () => {
   it('passes payload through when no schema is provided', async () => {
     const hook = defineHook<{ approved: boolean; comment: string }>();
 
-    resumeHookMock.mockResolvedValue(null);
+    resumeHookMock.mockResolvedValue({
+      hookId: 'hook-id',
+      token: 'token',
+      runId: 'run-id',
+    });
 
     const payload = { approved: true, comment: 'Looks good' };
     await hook.resume('token', payload);
@@ -72,7 +76,11 @@ describe('defineHook', () => {
   it('parses payload with schema before resuming', async () => {
     const hook = defineHook({ schema: approvalSchema });
 
-    resumeHookMock.mockResolvedValue(null);
+    resumeHookMock.mockResolvedValue({
+      hookId: 'hook-id',
+      token: 'token',
+      runId: 'run-id',
+    });
 
     await hook.resume('token', { approved: true, comment: '  Ready!  ' });
 

packages/core/src/define-hook.ts

@@ -60,9 +60,10 @@ export function defineHook<TInput, TOutput = TInput>({
      *
      * @param token - The unique token identifying the hook
      * @param payload - The payload to send; if a `schema` is configured it is validated/transformed before resuming
-     * @returns Promise resolving to the hook entity, or null if the hook doesn't exist
+     * @returns Promise resolving to the hook entity
+     * @throws Error if the hook is not found or if there's an error during the process
      */
-    async resume(token: string, payload: TInput): Promise<HookEntity | null> {
+    async resume(token: string, payload: TInput): Promise<HookEntity> {
       if (!schema?.['~standard']) {
         return await resumeHook(token, payload);
       }