@notionhq/apps 0.0.40 → 0.0.41

package/src/error.ts

@@ -11,6 +11,31 @@ export class ExecutionError extends Error {
 	}
 }
 
+/** Explicitly permit another workflow or step attempt. */
+export class RetryableError extends Error {
+	readonly retryAfterMs: number | undefined;
+
+	constructor(message: string, options?: { retryAfterMs?: number }) {
+		super(message);
+		this.name = "RetryableError";
+		if (
+			options?.retryAfterMs !== undefined &&
+			(!Number.isFinite(options.retryAfterMs) || options.retryAfterMs < 0)
+		) {
+			throw new Error("RetryableError retryAfterMs must be zero or greater.");
+		}
+		this.retryAfterMs = options?.retryAfterMs;
+	}
+}
+
+/** Skip remaining workflow or step attempts. */
+export class FatalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "FatalError";
+	}
+}
+
 /** Tell the platform that an external service asked the sync to slow down. */
 export class RateLimitError extends ExecutionError {
 	readonly retryAfter: number | undefined;

package/src/workflow.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Mock } from "vitest";
 
 import { j } from "./schema-builder.js";
-import { ExecutionError } from "./error.js";
+import { ExecutionError, FatalError, RateLimitError, RetryableError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { events, type NotionPageCreatedEvent, type WebhookEvent } from "./events.generated.js";
 import { customAgent } from "./notion-as-code/custom-agent.js";
@@ -21,6 +21,7 @@ import {
 	type WebhookVerifyHandler,
 	type WorkflowContext,
 	type WorkflowInputDate,
+	type WorkflowRetryPolicy,
 	type WorkflowWaitDuration,
 } from "./workflow.js";
 
@@ -124,12 +125,15 @@ describe("manual workflow triggers", () => {
 	});
 });
 
-async function createWorkflowContext(): Promise<WorkflowContext<Record<never, never>>> {
+async function createWorkflowContext(
+	retry?: WorkflowRetryPolicy,
+): Promise<WorkflowContext<Record<never, never>>> {
 	let context: WorkflowContext<Record<never, never>> | undefined;
 	const definition = workflow({
 		name: "Test workflow",
 		description: "Captures its workflow context",
 		triggers: [events.notionPageCreated()],
+		...(retry === undefined ? {} : { retry }),
 		handler: (_event, workflowContext) => {
 			context = workflowContext;
 		},
@@ -249,6 +253,41 @@ describe("step", () => {
 		expect(fetchMock).not.toHaveBeenCalled();
 	});
 
+	it("isolates buffered state between step retry attempts", async () => {
+		process.env.NOTION_API_BASE_URL = "https://api.example.com";
+		process.env.NOTION_API_TOKEN = "workflow-token";
+		const fetchMock = vi.fn<typeof fetch>().mockImplementation(async (_input, init) => {
+			const body = JSON.parse(String(init?.body)) as { operation: string };
+			return new Response(
+				JSON.stringify(body.operation === "get" ? { exists: false } : { success: true }),
+				{ status: 200, headers: { "content-type": "application/json" } },
+			);
+		});
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+		const seen: unknown[] = [];
+		let attempts = 0;
+
+		await context.step("Retry with state", { retry: { maxAttempts: 2 } }, async ({ state }) => {
+			attempts += 1;
+			seen.push(await state.get("failed-attempt"));
+			if (attempts === 1) {
+				state.set("failed-attempt", true);
+				throw new RetryableError("try again");
+			}
+			state.set("succeeded", true);
+		});
+
+		expect(seen).toEqual([undefined, undefined]);
+		const commits = fetchMock.mock.calls
+			.map(([, init]) => String(init?.body))
+			.filter((body) => body.includes('"operation":"commit"'));
+		expect(commits).toHaveLength(1);
+		expect(commits[0]).toContain(
+			'"mutations":[{"operation":"set","key":"succeeded","value":true}]',
+		);
+	});
+
 	it("reads buffered state before the step commits", async () => {
 		process.env.NOTION_API_BASE_URL = "https://api.example.com";
 		process.env.NOTION_API_TOKEN = "workflow-token";
@@ -522,7 +561,9 @@ describe("step", () => {
 			throw originalError;
 		});
 
-		await expect(step("Explode", fn)).rejects.toBe(originalError);
+		await expect(step("Explode", { retry: { maxAttempts: 1 } }, fn)).rejects.toBe(
+			originalError,
+		);
 
 		expect(fn).toHaveBeenCalledOnce();
 		expect(stdoutSpy).toHaveBeenCalledTimes(3);
@@ -908,6 +949,244 @@ describe("step", () => {
 		expect(keys).toEqual([workflowStepKey(["First"]), workflowStepKey(["First"])]);
 	});
 
+	it("retries a failed callback using the step policy", async () => {
+		const { step } = await createWorkflowContext();
+		const callback = vi
+			.fn<() => string>()
+			.mockRejectedValueOnce(new Error("temporary"))
+			.mockReturnValue("done");
+
+		await expect(
+			step("Retry request", { retry: { maxAttempts: 2, initialDelayMs: 0 } }, callback),
+		).resolves.toBe("done");
+		expect(callback).toHaveBeenCalledTimes(2);
+	});
+
+	it("uses the workflow retry policy for steps without their own", async () => {
+		const { step } = await createWorkflowContext({ maxAttempts: 2, initialDelayMs: 0 });
+		const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+		await expect(step("Inherit policy", callback)).rejects.toThrow("down");
+		expect(callback).toHaveBeenCalledTimes(2);
+	});
+
+	it("replaces the workflow retry policy with the step policy", async () => {
+		const { step } = await createWorkflowContext({ maxAttempts: 3, initialDelayMs: 0 });
+		const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+		await expect(
+			step("Override policy", { retry: { maxAttempts: 1 } }, callback),
+		).rejects.toThrow("down");
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("makes three attempts with backoff when no policy is configured", async () => {
+		vi.useFakeTimers();
+		try {
+			const { step } = await createWorkflowContext();
+			const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+			const result = step("Default policy", callback);
+			const assertion = expect(result).rejects.toThrow("down");
+			await vi.advanceTimersByTimeAsync(3_000);
+			await assertion;
+			expect(callback).toHaveBeenCalledTimes(3);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("retries only errors matched by retryOn", async () => {
+		class TransientError extends Error {}
+		const { step } = await createWorkflowContext({
+			maxAttempts: 3,
+			initialDelayMs: 0,
+			retryOn: [TransientError, (error) => error instanceof Error && error.message === "429"],
+		});
+
+		const transient = vi.fn<() => string>().mockRejectedValue(new TransientError("blip"));
+		await expect(step("Class match", transient)).rejects.toThrow("blip");
+		expect(transient).toHaveBeenCalledTimes(3);
+
+		const predicate = vi.fn<() => string>().mockRejectedValue(new Error("429"));
+		await expect(step("Predicate match", predicate)).rejects.toThrow("429");
+		expect(predicate).toHaveBeenCalledTimes(3);
+
+		const other = vi.fn<() => string>().mockRejectedValue(new TypeError("bug"));
+		await expect(step("No match", other)).rejects.toThrow("bug");
+		expect(other).toHaveBeenCalledOnce();
+
+		const explicit = vi.fn<() => string>().mockRejectedValue(new RetryableError("again"));
+		await expect(step("Explicit retryable", explicit)).rejects.toThrow("again");
+		expect(explicit).toHaveBeenCalledTimes(3);
+	});
+
+	it("accepts a single retryOn matcher", async () => {
+		class TransientError extends Error {}
+		const { step } = await createWorkflowContext({
+			maxAttempts: 2,
+			initialDelayMs: 0,
+			retryOn: TransientError,
+		});
+
+		const transient = vi.fn<() => string>().mockRejectedValue(new TransientError("blip"));
+		await expect(step("Class match", transient)).rejects.toThrow("blip");
+		expect(transient).toHaveBeenCalledTimes(2);
+
+		const other = vi.fn<() => string>().mockRejectedValue(new TypeError("bug"));
+		await expect(step("No match", other)).rejects.toThrow("bug");
+		expect(other).toHaveBeenCalledOnce();
+	});
+
+	it("never retries a FatalError matched by retryOn", async () => {
+		const { step } = await createWorkflowContext({
+			maxAttempts: 3,
+			initialDelayMs: 0,
+			retryOn: [Error],
+		});
+		const callback = vi.fn<() => string>().mockRejectedValue(new FatalError("stop"));
+
+		await expect(step("Fatal", callback)).rejects.toThrow("stop");
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("rejects step retry policies that cannot fit in one invocation", async () => {
+		const { step } = await createWorkflowContext();
+		const callback = vi.fn(() => "done");
+
+		await expect(
+			step("Slow retries", { retry: { maxAttempts: 3, initialDelayMs: 200_000 } }, callback),
+		).rejects.toThrow(
+			'Workflow step "Slow retries" can spend up to 500000ms on retry delays and timeouts, which exceeds the 300000ms limit',
+		);
+		await expect(
+			step("Long timeout", { timeoutMs: 120_000, retry: { maxAttempts: 3 } }, callback),
+		).rejects.toThrow('Workflow step "Long timeout" can spend up to 363000ms');
+		expect(callback).not.toHaveBeenCalled();
+		expect(() =>
+			workflow({
+				name: "Slow workflow",
+				description: "Its retry policy is the default for every step",
+				triggers: [events.notionPageCreated()],
+				retry: { maxAttempts: 3, initialDelayMs: 200_000 },
+				handler: () => {},
+			}),
+		).toThrow("Workflow retry policy can spend up to 500000ms");
+	});
+
+	it("leaves a retry that no longer fits in the invocation to the run", async () => {
+		const definition = workflow({
+			name: "Deferred retry",
+			description: "Hands a long explicit delay to the platform",
+			triggers: [events.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Wait for service", () => {
+					throw new RetryableError("busy", { retryAfterMs: 10 * 60 * 1000 });
+				});
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"retryable","name":"RetryableError","message":"busy"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(`"retryAfterMs":600000`),
+		);
+	});
+
+	it("counts earlier work in the invocation against the step retry budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const callback = vi.fn(() => {
+				throw new RetryableError("busy", { retryAfterMs: 60_000 });
+			});
+			const definition = workflow({
+				name: "Late retry",
+				description: "Fails a step near the end of the invocation",
+				triggers: [events.notionPageCreated()],
+				handler: async (_event, context) => {
+					await new Promise((resolve) => setTimeout(resolve, 4.5 * 60 * 1000));
+					await context.step("Call service", callback);
+				},
+			});
+
+			const result = expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+			await vi.runAllTimersAsync();
+			await result;
+			expect(callback).toHaveBeenCalledOnce();
+			expect(stdoutSpy).toHaveBeenLastCalledWith(
+				expect.stringContaining(`"retryAfterMs":60000`),
+			);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("writes a rate limit envelope for a RateLimitError", async () => {
+		const definition = workflow({
+			name: "Rate limited",
+			description: "Reports the service's retry delay",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new RateLimitError({ retryAfter: 30 });
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`{"_tag":"error","error":{"_tag":"rate_limit","name":"RateLimitError"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining(`"retryAfter":30`));
+	});
+
+	it("waits for the delay requested by a RateLimitError", async () => {
+		vi.useFakeTimers();
+		try {
+			const { step } = await createWorkflowContext();
+			const callback = vi
+				.fn<() => string>()
+				.mockRejectedValueOnce(new RateLimitError({ retryAfter: 30 }))
+				.mockReturnValue("done");
+
+			const result = step("Rate limited", { retry: { maxAttempts: 2 } }, callback);
+			await vi.advanceTimersByTimeAsync(29_000);
+			expect(callback).toHaveBeenCalledOnce();
+			await vi.advanceTimersByTimeAsync(1_000);
+			await expect(result).resolves.toBe("done");
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not retry a FatalError", async () => {
+		const { step } = await createWorkflowContext();
+		const error = new FatalError("invalid input");
+		const callback = vi.fn(() => {
+			throw error;
+		});
+
+		await expect(step("Validate input", { retry: { maxAttempts: 3 } }, callback)).rejects.toBe(
+			error,
+		);
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("times out a step callback", async () => {
+		const { step } = await createWorkflowContext();
+
+		await expect(
+			step("Wait forever", { timeoutMs: 1 }, () => new Promise(() => {})),
+		).rejects.toMatchObject({
+			name: "StepTimeoutError",
+			message: "Workflow step timed out after 1ms.",
+		});
+	});
+
 	it("writes step events under concreteOutput", async () => {
 		const definition = workflow({
 			name: "Log Pages",
@@ -1350,6 +1629,74 @@ describe("workflow", () => {
 		});
 	});
 
+	it("exposes deadline and retry configuration", () => {
+		const deadline = { afterMs: 60_000 };
+		const retry = {
+			maxAttempts: 3,
+			initialDelayMs: 1_000,
+			maxDelayMs: 30_000,
+			backoffMultiplier: 2,
+		};
+		const definition = workflow({
+			name: "Reliable workflow",
+			description: "Configures failure handling",
+			triggers: [events.notionPageCreated()],
+			deadline,
+			retry,
+			handler: () => {},
+		});
+
+		expect(definition.config.deadline).toEqual(deadline);
+		expect(definition.config.retry).toEqual(retry);
+		expect(
+			workflow({
+				name: "Classified workflow",
+				description: "Keeps error matchers in the SDK",
+				triggers: [events.notionPageCreated()],
+				retry: { ...retry, retryOn: [TypeError] },
+				handler: () => {},
+			}).config.retry,
+		).toEqual(retry);
+		expect(definition.config.deadline).not.toBe(deadline);
+		expect(definition.config.retry).not.toBe(retry);
+	});
+
+	it("rejects invalid workflow reliability configuration", () => {
+		expect(() =>
+			workflow({
+				name: "Invalid workflow",
+				description: "Has an invalid retry budget",
+				triggers: [events.notionPageCreated()],
+				deadline: { afterMs: 0 },
+				retry: { maxAttempts: 0 },
+				handler: () => {},
+			}),
+		).toThrow("Workflow deadline afterMs must be greater than zero.");
+	});
+
+	it("rejects reliability configuration beyond platform limits", () => {
+		const define = (config: { deadline?: { afterMs: number }; retry?: WorkflowRetryPolicy }) =>
+			workflow({
+				name: "Limited workflow",
+				description: "Exceeds platform limits",
+				triggers: [events.notionPageCreated()],
+				...config,
+				handler: () => {},
+			});
+
+		expect(() => define({ retry: { maxAttempts: 4 } })).toThrow(
+			"Workflow retry policy maxAttempts must be an integer between 1 and 3.",
+		);
+		expect(() => define({ deadline: { afterMs: 8 * 24 * 60 * 60 * 1000 } })).toThrow(
+			"Workflow deadline afterMs must be at most 604800000.",
+		);
+		expect(() =>
+			define({ retry: { maxAttempts: 2, retryOn: ["TypeError"] as unknown as [] } }),
+		).toThrow(
+			"Workflow retry policy retryOn must be an error class, a predicate, or an array of them.",
+		);
+	});
+
 	it("declares a Calendar connection requirement", () => {
 		const definition = workflow({
 			name: "Schedule Follow-up",
@@ -1457,6 +1804,81 @@ describe("workflow", () => {
 		expect(stdoutSpy).not.toHaveBeenCalled();
 	});
 
+	it("writes retryable and terminal error envelopes", async () => {
+		const retryable = workflow({
+			name: "Retryable workflow",
+			description: "Classifies temporary failures",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new RetryableError("try later", { retryAfterMs: 5_000 });
+			},
+		});
+
+		await expect(retryable.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"retryable","name":"RetryableError","message":"try later"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining(`"retryAfterMs":5000`));
+
+		stdoutSpy.mockClear();
+		const fatal = workflow({
+			name: "Fatal workflow",
+			description: "Classifies permanent failures",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new FatalError("stop now");
+			},
+		});
+
+		await expect(fatal.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"FatalError","message":"stop now"`,
+			),
+		);
+	});
+
+	it("reports a step failure that used its retries as terminal", async () => {
+		const definition = workflow({
+			name: "Step failure",
+			description: "Does not retry the run after a step exhausts its retries",
+			triggers: [events.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Fail", { retry: { maxAttempts: 1 } }, () => {
+					throw new Error("step down");
+				});
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"Error","message":"step down"`,
+			),
+		);
+	});
+
+	it("reports failures outside steps not matched by the workflow retryOn as terminal", async () => {
+		const definition = workflow({
+			name: "Classified failure",
+			description: "Applies retryOn to failures outside steps",
+			triggers: [events.notionPageCreated()],
+			retry: { maxAttempts: 2, retryOn: RangeError },
+			handler: () => {
+				throw new TypeError("bug");
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"TypeError","message":"bug"`,
+			),
+		);
+	});
+
 	it("writes an error envelope and throws ExecutionError on failure", async () => {
 		const definition = workflow({
 			name: "Log Pages",