@notionhq/apps 0.0.17 → 0.0.18

package/src/workflow-state.ts

@@ -0,0 +1,152 @@
+import type { RunMetadata } from "./runtime-metadata.js";
+
+export type WorkflowStateValue =
+	| null
+	| boolean
+	| number
+	| string
+	| ReadonlyArray<WorkflowStateValue>
+	| { readonly [key: string]: WorkflowStateValue };
+
+export type WorkflowState = {
+	get(key: string): Promise<WorkflowStateValue | undefined>;
+	set(key: string, value: WorkflowStateValue | undefined): void;
+};
+
+type WorkflowStateMutation =
+	| { operation: "set"; key: string; value: WorkflowStateValue }
+	| { operation: "delete"; key: string };
+
+type WorkflowStepScope = {
+	id: string;
+	active: boolean;
+	mutations: Map<string, WorkflowStateMutation>;
+};
+
+const MAX_STATE_KEY_BYTES = 256;
+const WORKFLOW_CAPABILITY_KEY_ENV = "NOTION_WORKFLOW_CAPABILITY_KEY";
+
+export function createWorkflowStepState(
+	metadata: Pick<RunMetadata, "workerId">,
+	stepId: string,
+): {
+	state: WorkflowState;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+} {
+	const scope: WorkflowStepScope = {
+		id: stepId,
+		active: true,
+		mutations: new Map(),
+	};
+	const state: WorkflowState = {
+		async get(key: string): Promise<WorkflowStateValue | undefined> {
+			requireActiveStep(scope, "get");
+			validateStateKey(key);
+			const pending = scope.mutations.get(key);
+			if (pending?.operation === "set") {
+				return pending.value;
+			}
+			if (pending?.operation === "delete") {
+				return undefined;
+			}
+
+			const response = await requestWorkflowState(metadata, {
+				operation: "get",
+				key,
+			});
+			const body: { exists: boolean; value?: WorkflowStateValue } = JSON.parse(
+				await response.text(),
+			);
+			if (!body.exists) {
+				return undefined;
+			}
+			return body.value;
+		},
+		set(key: string, value: WorkflowStateValue | undefined): void {
+			requireActiveStep(scope, "set");
+			validateStateKey(key);
+			if (value === undefined) {
+				recordMutation(scope, { operation: "delete", key });
+				return;
+			}
+			recordMutation(scope, { operation: "set", key, value });
+		},
+	};
+
+	return {
+		state,
+		async run<T>(fn: () => T | Promise<T>): Promise<T> {
+			try {
+				const result = await fn();
+				if (scope.mutations.size > 0) {
+					await requestWorkflowState(metadata, {
+						operation: "commit",
+						operationId: scope.id,
+						mutations: [...scope.mutations.values()],
+					});
+				}
+				return result;
+			} finally {
+				scope.active = false;
+			}
+		},
+	};
+}
+
+function requireActiveStep(expectedScope: WorkflowStepScope, operation: keyof WorkflowState): void {
+	if (!expectedScope.active) {
+		throw new Error(`state.${operation}() must be called inside context.step().`);
+	}
+}
+
+function recordMutation(scope: WorkflowStepScope, mutation: WorkflowStateMutation): void {
+	scope.mutations.set(mutation.key, mutation);
+}
+
+async function requestWorkflowState(
+	metadata: Pick<RunMetadata, "workerId">,
+	request:
+		| { operation: "get"; key: string }
+		| {
+				operation: "commit";
+				operationId: string;
+				mutations: WorkflowStateMutation[];
+		  },
+): Promise<Response> {
+	const baseUrl = process.env.NOTION_API_BASE_URL;
+	const token = process.env.NOTION_API_TOKEN;
+	const capabilityKey = process.env[WORKFLOW_CAPABILITY_KEY_ENV];
+	if (!baseUrl || !token || !capabilityKey) {
+		throw new Error(
+			`Workflow state is only available when the workflow runtime provides NOTION_API_BASE_URL, NOTION_API_TOKEN, and ${WORKFLOW_CAPABILITY_KEY_ENV}.`,
+		);
+	}
+
+	const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v3/workersWorkflowState`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json",
+		},
+		body: JSON.stringify({
+			...request,
+			workerId: metadata.workerId,
+			capabilityKey,
+		}),
+	});
+	if (!response.ok) {
+		throw new Error(
+			`Workflow state ${request.operation} failed with status ${response.status}.`,
+		);
+	}
+	return response;
+}
+
+function validateStateKey(key: string): void {
+	if (key.length === 0) {
+		throw new Error("Workflow state keys must not be empty.");
+	}
+	if (Buffer.byteLength(key) > MAX_STATE_KEY_BYTES) {
+		throw new Error(`Workflow state keys must be at most ${MAX_STATE_KEY_BYTES} UTF-8 bytes.`);
+	}
+}

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 });
 	}
@@ -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;