@notionhq/apps 0.0.16 → 0.0.18

package/src/workflow.test.ts

@@ -8,7 +8,13 @@ import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Moc
 import { ExecutionError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
-import { connections, workflow, type StepContext, type WorkflowContext } from "./workflow.js";
+import {
+	connections,
+	workflow,
+	type StepContext,
+	type WorkflowContext,
+	type WorkflowWaitDuration,
+} from "./workflow.js";
 
 let stdoutSpy: Mock<typeof process.stdout.write>;
 let checkpointDirectory: string | undefined;
@@ -17,6 +23,7 @@ let metadataDirectory: string | undefined;
 beforeEach(async () => {
 	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
+	process.env.NOTION_WORKFLOW_CAPABILITY_KEY = "workflow-key";
 	checkpointDirectory = undefined;
 	metadataDirectory = await mkdtemp(join(tmpdir(), "notion-workflow-metadata-"));
 	await writeRunMetadata();
@@ -25,8 +32,12 @@ beforeEach(async () => {
 afterEach(async () => {
 	stdoutSpy.mockRestore();
 	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
+	delete process.env.NOTION_WORKFLOW_CAPABILITY_KEY;
 	delete process.env.NOTION_INPUT_PAYLOAD_PATH;
 	delete process.env.NOTION_RUN_METADATA_PATH;
+	delete process.env.NOTION_API_BASE_URL;
+	delete process.env.NOTION_API_TOKEN;
+	vi.unstubAllGlobals();
 	if (checkpointDirectory) {
 		await rm(checkpointDirectory, { recursive: true, force: true });
 	}
@@ -37,8 +48,8 @@ afterEach(async () => {
 
 const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
 
-async function createWorkflowContext(): Promise<WorkflowContext<readonly []>> {
-	let context: WorkflowContext<readonly []> | undefined;
+async function createWorkflowContext(): Promise<WorkflowContext<Record<never, never>>> {
+	let context: WorkflowContext<Record<never, never>> | undefined;
 	const definition = workflow({
 		name: "Test workflow",
 		description: "Captures its workflow context",
@@ -80,6 +91,167 @@ function emittedStepEvents(): Array<{
 }
 
 describe("step", () => {
+	it("exposes workflow state only while a step callback is running", async () => {
+		const context = await createWorkflowContext();
+		let escapedState: StepContext["state"] | undefined;
+
+		await context.step("Capture state", ({ state }) => {
+			escapedState = state;
+		});
+
+		await expect(escapedState?.get("cursor")).rejects.toThrow(
+			"state.get() must be called inside context.step().",
+		);
+	});
+
+	it("reads and writes durable workflow state inside a step", async () => {
+		process.env.NOTION_API_BASE_URL = "https://api.example.com";
+		process.env.NOTION_API_TOKEN = "workflow-token";
+		const fetchMock = vi
+			.fn<typeof fetch>()
+			.mockResolvedValueOnce(
+				new Response(JSON.stringify({ exists: true, value: "cursor-1" }), {
+					status: 200,
+					headers: { "content-type": "application/json" },
+				}),
+			)
+			.mockResolvedValueOnce(
+				new Response(JSON.stringify({}), {
+					status: 200,
+					headers: { "content-type": "application/json" },
+				}),
+			);
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+
+		const cursor = await context.step("Update cursor", async ({ state }) => {
+			const current = await state.get("cursor");
+			await state.set("cursor", "cursor-2");
+			return current;
+		});
+
+		expect(cursor).toBe("cursor-1");
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			1,
+			"https://api.example.com/api/v3/workersWorkflowState",
+			expect.objectContaining({
+				method: "POST",
+				headers: expect.objectContaining({
+					authorization: "Bearer workflow-token",
+				}),
+				body: JSON.stringify({
+					operation: "get",
+					key: "cursor",
+					workerId: "worker-id",
+					capabilityKey: "workflow-key",
+				}),
+			}),
+		);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			2,
+			"https://api.example.com/api/v3/workersWorkflowState",
+			expect.objectContaining({
+				method: "POST",
+				body: expect.stringMatching(
+					/^\{"operation":"commit","operationId":"run-group-id:[^"]+","mutations":\[\{"operation":"set","key":"cursor","value":"cursor-2"\}\],"workerId":"worker-id","capabilityKey":"workflow-key"\}$/,
+				),
+			}),
+		);
+	});
+
+	it("discards buffered state when the step callback throws", async () => {
+		const fetchMock = vi.fn<typeof fetch>();
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+
+		await expect(
+			context.step("Do something", ({ state }) => {
+				state.set("foo", 42);
+				throw new Error("crash");
+			}),
+		).rejects.toThrow("crash");
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	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";
+		const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+			new Response(JSON.stringify({ success: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			}),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+
+		const value = await context.step("Write then read", async ({ state }) => {
+			state.set("foo", 42);
+			return state.get("foo");
+		});
+
+		expect(value).toBe(42);
+		expect(fetchMock).toHaveBeenCalledOnce();
+	});
+
+	it("coalesces repeated mutations of a key within the step transaction", async () => {
+		process.env.NOTION_API_BASE_URL = "https://api.example.com";
+		process.env.NOTION_API_TOKEN = "workflow-token";
+		const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+			new Response(JSON.stringify({ success: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			}),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+
+		const value = await context.step("Mutate repeatedly", async ({ state }) => {
+			state.set("cursor", "first");
+			state.set("cursor", undefined);
+			state.set("cursor", "final");
+			return state.get("cursor");
+		});
+
+		expect(value).toBe("final");
+		expect(fetchMock).toHaveBeenCalledOnce();
+		expect(fetchMock).toHaveBeenCalledWith(
+			"https://api.example.com/api/v3/workersWorkflowState",
+			expect.objectContaining({
+				body: expect.stringContaining(
+					'"mutations":[{"operation":"set","key":"cursor","value":"final"}]',
+				),
+			}),
+		);
+	});
+
+	it("deletes a key by setting it to undefined", async () => {
+		process.env.NOTION_API_BASE_URL = "https://api.example.com";
+		process.env.NOTION_API_TOKEN = "workflow-token";
+		const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+			new Response(JSON.stringify({ success: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			}),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+
+		const isDeleted = await context.step("Delete state", async ({ state }) => {
+			state.set("foo", 42);
+			state.set("foo", undefined);
+			return (await state.get("foo")) === undefined;
+		});
+
+		expect(isDeleted).toBe(true);
+		expect(fetchMock).toHaveBeenCalledWith(
+			"https://api.example.com/api/v3/workersWorkflowState",
+			expect.objectContaining({
+				body: expect.stringContaining('"mutations":[{"operation":"delete","key":"foo"}]'),
+			}),
+		);
+	});
+
 	it("provides required run metadata in the workflow context", async () => {
 		const context = await createWorkflowContext();
 
@@ -683,6 +855,162 @@ describe("step", () => {
 	});
 });
 
+describe("wait.until", () => {
+	it("stops the workflow and returns its absolute resume time", async () => {
+		const now = Date.parse("2026-09-17T09:00:00.000Z");
+		const resumeAt = new Date(now + 60_000);
+		const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(now);
+		let continued = false;
+		const definition = workflow({
+			name: "Wait for launch",
+			description: "Waits until launch time",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.wait.until("Launch time", { at: resumeAt });
+				continued = true;
+			},
+		});
+
+		try {
+			await expect(definition.handler(event, { concreteOutput: true })).resolves.toEqual({
+				status: "waiting",
+				wait: {
+					type: "until",
+					name: "Launch time",
+					resumeAtMs: resumeAt.getTime(),
+				},
+			});
+			expect(continued).toBe(false);
+		} finally {
+			dateNowSpy.mockRestore();
+		}
+	});
+
+	it("anchors a relative wait in its durable step checkpoint", async () => {
+		const directory = await createCheckpointDirectory();
+		const initialNow = Date.parse("2026-09-17T09:00:00.000Z");
+		const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(initialNow);
+		let continued = false;
+		const definition = workflow({
+			name: "Wait before following up",
+			description: "Waits before continuing",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.wait.until("Follow-up delay", {
+					after: { minutes: 30, seconds: 15 },
+				});
+				continued = true;
+			},
+		});
+
+		try {
+			const firstResult = await definition.handler(event, { concreteOutput: true });
+			expect(firstResult).toMatchObject({
+				status: "waiting",
+				wait: { resumeAtMs: initialNow + 1_815_000 },
+			});
+
+			const successEvent = emittedStepEvents().find(({ event }) => event === "success");
+			const stepKey = successEvent?.value.key;
+			const resumeAtMs = successEvent?.value.value;
+			if (typeof stepKey !== "string" || typeof resumeAtMs !== "number") {
+				throw new Error("Wait checkpoint event was not emitted");
+			}
+			await writeFile(
+				checkpointPath(directory, stepKey),
+				JSON.stringify({
+					version: 0,
+					key: stepKey,
+					value: resumeAtMs,
+					sourceRunId: "first-run",
+					sourceStepId: "wait-step",
+				}),
+			);
+
+			dateNowSpy.mockReturnValue(initialNow + 7_200_000);
+			await expect(definition.handler(event, { concreteOutput: true })).resolves.toEqual({
+				status: "success",
+			});
+			expect(continued).toBe(true);
+		} finally {
+			dateNowSpy.mockRestore();
+		}
+	});
+
+	it("uses composite keys to distinguish waits in a loop", async () => {
+		const now = Date.parse("2026-09-17T09:00:00.000Z");
+		const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(now);
+		const itemIds = ["first", "second"];
+		const definition = workflow({
+			name: "Wait between items",
+			description: "Uses one stable display name for repeated waits",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				for (const itemId of itemIds) {
+					await context.wait.until("Item delay", {
+						key: ["item-delay", itemId],
+						at: new Date(now),
+					});
+				}
+			},
+		});
+
+		try {
+			await expect(definition.handler(event, { concreteOutput: true })).resolves.toEqual({
+				status: "success",
+			});
+			expect(
+				emittedStepEvents()
+					.filter(({ event }) => event === "success")
+					.map(({ value }) => value.key),
+			).toEqual([
+				workflowStepKey(["wait", "until", "item-delay", "first"]),
+				workflowStepKey(["wait", "until", "item-delay", "second"]),
+			]);
+		} finally {
+			dateNowSpy.mockRestore();
+		}
+	});
+
+	it("rejects waits that can outlive their durable checkpoint", async () => {
+		const definition = workflow({
+			name: "Wait too long",
+			description: "Rejects an unsupported wait",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.wait.until("Beyond retention", {
+					after: { days: 7 },
+				});
+			},
+		});
+
+		await expect(definition.handler(event, { concreteOutput: true })).rejects.toThrow(
+			"Workflow waits must be shorter than 7 days.",
+		);
+	});
+
+	it.each([
+		[{ hours: 0 }, "positive finite integers"],
+		[{ minutes: 1.5 }, "positive finite integers"],
+		[{}, "at least one unit"],
+	])("rejects invalid relative durations", async (after, expectedMessage) => {
+		const definition = workflow({
+			name: "Wait for a valid duration",
+			description: "Rejects an invalid duration",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.wait.until("Invalid duration", {
+					after: after as WorkflowWaitDuration,
+				});
+			},
+		});
+
+		await expect(definition.handler(event, { concreteOutput: true })).rejects.toThrow(
+			expectedMessage,
+		);
+	});
+});
+
 async function createCheckpointDirectory(): Promise<string> {
 	checkpointDirectory = await mkdtemp(join(tmpdir(), "apps-step-checkpoints-"));
 	process.env.NOTION_WORKFLOW_STEP_DIRECTORY = checkpointDirectory;
@@ -743,23 +1071,54 @@ describe("workflow", () => {
 			name: "Schedule Follow-up",
 			description: "Schedules a follow-up after a page is created",
 			triggers: [triggers.notionPageCreated()],
-			connections: [connections.calendar()],
+			connections: { calendar: connections.calendar() },
 			handler: () => {},
 		});
 
-		expect(definition.config.connections).toEqual([{ type: "calendar" }]);
+		expect(definition.config.connections).toEqual([{ type: "calendar", key: "calendar" }]);
+	});
+
+	it("keeps declaration keys stable after the input object changes", async () => {
+		const declarations = { support: connections.slack() };
+		const seen: string[][] = [];
+		const definition = workflow({
+			name: "Snapshot connections",
+			description: "Captures declared keys",
+			connections: declarations,
+			triggers: [triggers.notionPageCreated()],
+			handler(_event, context) {
+				seen.push(Object.keys(context.connections));
+			},
+		});
+		Object.assign(declarations, { support: connections.calendar(), team: connections.slack() });
+		expect(definition.config.connections).toEqual([{ type: "slack", key: "support" }]);
+		await definition.handler(event, { concreteOutput: true });
+		expect(seen).toEqual([["support"]]);
+	});
+	it("rejects inherited declaration objects before cloning", () => {
+		const declarations = { support: connections.slack() };
+		Object.setPrototypeOf(declarations, { extra: connections.calendar() });
+		expect(() =>
+			workflow({
+				name: "Inherited keys",
+				description: "Reject prototype declarations",
+				connections: declarations,
+				triggers: [triggers.notionPageCreated()],
+				handler() {},
+			}),
+		).toThrow("only own");
 	});
 
-	it("rejects duplicate connection requirements", () => {
+	it("rejects invalid connection property names", () => {
 		expect(() =>
 			workflow({
 				name: "Schedule Follow-up",
 				description: "Schedules a follow-up after a page is created",
 				triggers: [triggers.notionPageCreated()],
-				connections: [connections.calendar(), connections.calendar()],
+				connections: { "bad/key": connections.calendar() },
 				handler: () => {},
 			}),
-		).toThrowError("Duplicate workflow connection: calendar");
+		).toThrowError("Invalid workflow connection key: bad/key");
 	});
 
 	it("writes a success envelope after the handler runs", async () => {
@@ -839,7 +1198,7 @@ describe("connection-bound triggers", () => {
 		const definition = workflow({
 			name: "Typed triggers",
 			description: "Uses only declared provider keys",
-			connections: [connections.slack({ key: "support" }), connections.calendar()],
+			connections: { support: connections.slack(), calendar: connections.calendar() },
 			triggers: ({ triggers }) => {
 				calls += 1;
 				expectTypeOf(triggers.slackMessage)
@@ -861,7 +1220,7 @@ describe("connection-bound triggers", () => {
 					"slack.message" | "calendar.event.created"
 				>();
 				expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<
-					"slack" | "calendar"
+					"support" | "calendar"
 				>();
 			},
 		});
@@ -876,7 +1235,7 @@ describe("connection-bound triggers", () => {
 		const definition = workflow({
 			name: "Support",
 			description: "Watch support messages",
-			connections: [connections.slack({ key: "support" })],
+			connections: { support: connections.slack() },
 			triggers: [triggers.slackMessage({ connectionKey: "support" })],
 			handler(event) {
 				expectTypeOf(event.type).toEqualTypeOf<"slack.message">();
@@ -887,9 +1246,9 @@ describe("connection-bound triggers", () => {
 		]);
 	});
 	it.each([
-		{ requirements: [] },
-		{ requirements: [connections.calendar({ key: "support" })] },
-		{ requirements: [connections.slack({ key: "other" })] },
+		{ requirements: {} },
+		{ requirements: { support: connections.calendar() } },
+		{ requirements: { other: connections.slack() } },
 	])("rejects missing or incompatible declarations: %j", ({ requirements }) => {
 		expect(() =>
 			workflow({
@@ -905,10 +1264,7 @@ describe("connection-bound triggers", () => {
 		const configuration = {
 			name: "Support",
 			description: "",
-			connections: [
-				connections.slack({ key: "support" }),
-				connections.slack({ key: "internal" }),
-			],
+			connections: { support: connections.slack(), internal: connections.slack() },
 			handler() {},
 		};
 		expect(() =>