@notionhq/apps 0.0.35 → 0.0.37

package/src/workflow-schema.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import { getSchema, j, type Infer } from "./schema-builder.js";
+import { events } from "./events.generated.js";
+import { compileWorkflowInputSchema } from "./workflow-schema.js";
+import type { WorkflowEventForTrigger } from "./workflow.js";
+
+const releaseSchema = j.object({
+	releases: j.array(j.object({ version: j.string(), dryRun: j.boolean().nullable() })),
+});
+
+describe("manual input schema builders", () => {
+	it("infers nested nullable fields without optional keys or readonly output", () => {
+		const trigger = events.manual({ inputSchema: releaseSchema });
+		type Input = WorkflowEventForTrigger<typeof trigger>["input"];
+		expectTypeOf<Input>().toEqualTypeOf<{
+			releases: { version: string; dryRun: boolean | null }[];
+		}>();
+		expectTypeOf<Input>().toEqualTypeOf<Infer<typeof releaseSchema>>();
+	});
+
+	it("serializes a builder as standard JSON Schema with all keys required", () => {
+		const trigger = events.manual({ inputSchema: releaseSchema });
+		expect(JSON.parse(JSON.stringify(trigger))).toEqual({
+			type: "workflow.manual",
+			inputJsonSchema: {
+				type: "object",
+				required: ["releases"],
+				additionalProperties: false,
+				properties: {
+					releases: {
+						type: "array",
+						items: {
+							type: "object",
+							required: ["version", "dryRun"],
+							additionalProperties: false,
+							properties: {
+								version: { type: "string" },
+								dryRun: { anyOf: [{ type: "boolean" }, { type: "null" }] },
+							},
+						},
+					},
+				},
+			},
+		});
+	});
+
+	it("accepts explicit null and rejects missing, invalid, and extra fields without coercion", () => {
+		const { validate } = compileWorkflowInputSchema(releaseSchema);
+		for (const dryRun of [true, false, null]) {
+			expect(() => validate({ releases: [{ version: "1", dryRun }] })).not.toThrow();
+		}
+		for (const input of [
+			{},
+			{ releases: [{}] },
+			{ releases: [{ version: "1" }] },
+			{ releases: [{ version: "1", dryRun: "false" }] },
+			{ releases: null },
+			{ releases: [], extra: true },
+		]) {
+			const original = structuredClone(input);
+			expect(() => validate(input)).toThrow("Invalid manual workflow input");
+			expect(input).toEqual(original);
+		}
+	});
+
+	it("supports primitive, enum, nullable object, and nullable array inference and validation", () => {
+		const inputSchema = j.object({
+			count: j.integer(),
+			ratio: j.number(),
+			stage: j.enum("draft", "live"),
+			config: j.object({ label: j.string() }).nullable(),
+			tags: j.array(j.string(), { minItems: 1 }).nullable(),
+		});
+		const trigger = events.manual({ inputSchema });
+		type Input = WorkflowEventForTrigger<typeof trigger>["input"];
+		expectTypeOf<Input>().toEqualTypeOf<{
+			count: number;
+			ratio: number;
+			stage: "draft" | "live";
+			config: { label: string } | null;
+			tags: string[] | null;
+		}>();
+		const { validate } = compileWorkflowInputSchema(inputSchema);
+		const input = { count: 1, ratio: 0.5, stage: "draft", config: null, tags: null };
+		expect(() => validate(input)).not.toThrow();
+		for (const change of [{ count: 0.5 }, { stage: "unknown" }, { config: {} }, { tags: [] }]) {
+			expect(() => validate({ ...input, ...change })).toThrow();
+		}
+	});
+
+	it("keeps metadata outside nullable unions and builders immutable", () => {
+		const name = j.string().label("Name").describe("A name");
+		const nullable = name.nullable();
+		expect(getSchema(nullable)).toEqual({
+			title: "Name",
+			description: "A name",
+			anyOf: [{ type: "string" }, { type: "null" }],
+		});
+		const copy = getSchema(name);
+		copy.description = "Changed";
+		expect(getSchema(name)).toEqual({ type: "string", title: "Name", description: "A name" });
+		expect(getSchema(j.object({ z: name, a: name }).describe("Root"))).toMatchObject({
+			required: ["z", "a"],
+			description: "Root",
+		});
+	});
+
+	it("rejects plain JSON schemas and non-object roots from untyped callers", () => {
+		for (const inputSchema of [
+			JSON.parse('{"type":"object","properties":{}}'),
+			JSON.parse("null"),
+			JSON.parse('"string"'),
+		]) {
+			expect(() => events.manual({ inputSchema })).toThrow();
+		}
+	});
+});
+
+describe("formatted manual inputs", () => {
+	it.each([
+		{
+			builder: j.datetime,
+			format: "date-time",
+			valid: "2026-09-24T10:30:00Z",
+			invalid: "2026-09-24",
+		},
+		{ builder: j.date, format: "date", valid: "2024-02-29", invalid: "2025-02-29" },
+		{ builder: j.time, format: "time", valid: "10:30:00Z", invalid: "25:00:00Z" },
+		{ builder: j.duration, format: "duration", valid: "P1DT2H", invalid: "tomorrow" },
+		{ builder: j.email, format: "email", valid: "user@example.com", invalid: "not-an-email" },
+		{ builder: j.hostname, format: "hostname", valid: "example.com", invalid: "bad host" },
+		{ builder: j.ipv4, format: "ipv4", valid: "192.0.2.1", invalid: "256.0.0.1" },
+		{ builder: j.ipv6, format: "ipv6", valid: "2001:db8::1", invalid: "2001:db8::xyz" },
+		{
+			builder: j.uuid,
+			format: "uuid",
+			valid: "74877cbb-93f9-41fb-9143-c1a11bf88f6b",
+			invalid: "not-a-uuid",
+		},
+	])(
+		"serializes and validates $format, including nested nullable inputs",
+		({ builder, format, valid, invalid }) => {
+			const field = builder().label("Input").describe("Help").nullable();
+			expectTypeOf<Infer<typeof field>>().toEqualTypeOf<string | null>();
+			expect(getSchema(field)).toEqual({
+				title: "Input",
+				description: "Help",
+				anyOf: [{ type: "string", format }, { type: "null" }],
+			});
+			const schema = j.object({ values: j.array(j.object({ value: field })) });
+			const { validate } = compileWorkflowInputSchema(schema);
+			for (const value of [valid, null])
+				expect(() => validate({ values: [{ value }] })).not.toThrow();
+			expect(() => validate({ values: [{ value: invalid }] })).toThrow(
+				"Invalid manual workflow input",
+			);
+			expect(() => validate({ values: [{}] })).toThrow();
+		},
+	);
+});

package/src/workflow-schema.ts

@@ -0,0 +1,42 @@
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
+import { getSchema, type SchemaBuilder } from "./schema-builder.js";
+
+/** @internal */
+export function compileWorkflowInputSchema(
+	schema: SchemaBuilder<Record<string, unknown>, "object">,
+): {
+	jsonSchema: Record<string, unknown>;
+	validate: (input: unknown) => void;
+} {
+	const jsonSchema = getSchema(schema);
+	if (!("type" in jsonSchema) || jsonSchema.type !== "object") {
+		throw new Error("workflow manual inputSchema: must be a j.object() schema");
+	}
+	const ajv = new Ajv({ allErrors: true, strict: true });
+	addFormats.default(ajv, {
+		formats: [
+			"date-time",
+			"date",
+			"time",
+			"duration",
+			"email",
+			"hostname",
+			"ipv4",
+			"ipv6",
+			"uuid",
+		],
+		keywords: false,
+	});
+	const validate = ajv.compile(jsonSchema);
+	return {
+		jsonSchema,
+		validate(input) {
+			if (!validate(input)) {
+				throw new Error(
+					`Invalid manual workflow input: ${ajv.errorsText(validate.errors)}`,
+				);
+			}
+		},
+	};
+}

package/src/workflow-types.test.ts

@@ -4,6 +4,70 @@ import { expect, it } from "vitest";
 
 it("checks provider keys on callback arguments and returned triggers", () => {
 	const cases = [
+		{
+			name: "manual",
+			valid: true,
+			connections: undefined,
+			trigger:
+				"events.manual({ inputSchema: j.object({version: j.string(), dryRun: j.boolean()}) })",
+			handler:
+				"(event) => { const version: string = event.input.version; const dryRun: boolean = event.input.dryRun; void version; void dryRun; }",
+		},
+		{
+			name: "manual_input_mismatch",
+			valid: false,
+			connections: undefined,
+			trigger: "events.manual({ inputSchema: j.object({version: j.string()}) })",
+			handler: "(event) => { const version: number = event.input.version; void version; }",
+		},
+		{
+			name: "manual_requires_object_schema",
+			valid: false,
+			connections: undefined,
+			trigger: "events.manual({ inputSchema: j.string() })",
+			handler: "() => {}",
+		},
+		{
+			name: "manual_nested",
+			valid: true,
+			connections: undefined,
+			trigger:
+				"events.manual({ inputSchema: j.object({releases: j.array(j.object({version: j.string(), dryRun: j.boolean().nullable()}))}) })",
+			handler:
+				'(event) => { const releases: { version: string; dryRun: boolean | null }[] = event.input.releases; event.input.releases = [{ version: "1.0", dryRun: null }]; void releases; }',
+		},
+		{
+			name: "manual_nullable_not_boolean",
+			valid: false,
+			connections: undefined,
+			trigger: "events.manual({ inputSchema: j.object({dryRun: j.boolean().nullable()}) })",
+			handler: "(event) => { const dryRun: boolean = event.input.dryRun; void dryRun; }",
+		},
+		{
+			name: "manual_unknown_property",
+			valid: false,
+			connections: undefined,
+			trigger: "globalTriggers.manual({ inputSchema: j.object({}) })",
+			handler: "(event) => { void event.input.unknown; }",
+		},
+		{
+			name: "manual_rejects_plain_schema",
+			valid: false,
+			connections: undefined,
+			trigger:
+				'events.manual({ inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } })',
+			handler: "() => {}",
+		},
+
+		{
+			name: "manual_open_object",
+			valid: false,
+			connections: undefined,
+			trigger:
+				'events.manual({ inputSchema: { type: "object", properties: {}, additionalProperties: true } })',
+			handler: "() => {}",
+		},
+
 		{
 			name: "valid",
 			valid: true,
@@ -166,6 +230,7 @@ it("checks provider keys on callback arguments and returned triggers", () => {
 			resolve("src", `__workflow_types_${testCase.name}.ts`),
 			`import { connections, workflow } from "./workflow.js";
 		import { events as globalTriggers } from "./events.generated.js";
+		import { j } from "./schema-builder.js";
 		const support = connections.slack();
 		const oauthConfig = { authorizationEndpoint: "https://example.com/authorize", tokenEndpoint: "https://example.com/token", clientId: "client", clientSecretEnv: "CLIENT_SECRET", scope: "read" };
 		workflow({

package/src/workflow.test.ts

@@ -5,9 +5,10 @@ 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 type { RunMetadata } from "./runtime-metadata.js";
-import { events, type NotionPageCreatedEvent } from "./events.generated.js";
+import { events, type NotionPageCreatedEvent, type WebhookEvent } from "./events.generated.js";
 import { customAgent } from "./notion-as-code/custom-agent.js";
 import { database } from "./notion-as-code/database.js";
 import { page } from "./notion-as-code/page.js";
@@ -17,6 +18,7 @@ import {
 	input,
 	workflow,
 	type StepContext,
+	type WebhookVerifyHandler,
 	type WorkflowContext,
 	type WorkflowInputDate,
 	type WorkflowWaitDuration,
@@ -56,6 +58,72 @@ afterEach(async () => {
 
 const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
 
+describe("manual workflow triggers", () => {
+	it("runs a manual trigger without arguments and rejects undeclared input", async () => {
+		const handler = vi.fn();
+		const definition = workflow({
+			name: "No inputs",
+			description: "Runs without form fields",
+			triggers: [events.manual()],
+			handler: async (event) => {
+				handler(event.input);
+			},
+		});
+		await definition.handler({ type: "workflow.manual", input: {} });
+		expect(handler).toHaveBeenCalledWith({});
+		await expect(
+			definition.handler(JSON.parse('{"type":"workflow.manual","input":{"extra":true}}')),
+		).rejects.toBeInstanceOf(ExecutionError);
+		expect(handler).toHaveBeenCalledTimes(1);
+	});
+
+	it("infers and validates the manual event input", async () => {
+		const handler = vi.fn();
+		const definition = workflow({
+			name: "Publish release",
+			description: "Publishes a release from manually entered values.",
+			triggers: [
+				events.manual({
+					inputSchema: j.object({ version: j.string(), dryRun: j.boolean() }),
+				}),
+			],
+			handler: async (manualEvent) => {
+				handler(manualEvent.input);
+			},
+		});
+
+		await definition.handler({
+			type: "workflow.manual",
+			input: { version: "1.2.3", dryRun: true },
+		});
+
+		expect(handler).toHaveBeenCalledWith({
+			version: "1.2.3",
+			dryRun: true,
+		});
+	});
+
+	it("rejects invalid manual input before invoking the handler", async () => {
+		const handler = vi.fn();
+		const definition = workflow({
+			name: "Publish release",
+			description: "Publishes a release from manually entered values.",
+			triggers: [
+				events.manual({
+					inputSchema: j.object({ version: j.string() }),
+				}),
+			],
+			handler,
+		});
+
+		await expect(
+			definition.handler(JSON.parse('{"type":"workflow.manual","input":{"version":42}}')),
+		).rejects.toBeInstanceOf(ExecutionError);
+
+		expect(handler).not.toHaveBeenCalled();
+	});
+});
+
 async function createWorkflowContext(): Promise<WorkflowContext<Record<never, never>>> {
 	let context: WorkflowContext<Record<never, never>> | undefined;
 	const definition = workflow({
@@ -1621,3 +1689,240 @@ describe("connection-bound triggers", () => {
 		).not.toThrow();
 	});
 });
+
+describe("workflow verify", () => {
+	const verifyRequest = {
+		method: "POST" as const,
+		url: "https://123456.webhook.notionusercontent.com/webhooks/app/s/w/u/incoming",
+		query: {},
+		headers: { "x-signature": "sig" },
+		rawBody: '{"challenge":"abc"}',
+	};
+
+	it("marks the webhook trigger with hasVerify when a verify handler is set", () => {
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: () => ({ status: 200 }),
+			handler: () => {},
+		});
+
+		expect(incoming.config).toEqual({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [{ type: "webhooks.webhook", hasVerify: true }],
+		});
+	});
+
+	it("flags only the webhook trigger among a workflow's triggers", () => {
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.notionPageCreated(), events.webhook()],
+			verify: () => ({ status: 200 }),
+			handler: () => {},
+		});
+
+		expect(incoming.config.triggers).toEqual([
+			{ type: "notion.page.created" },
+			{ type: "webhooks.webhook", hasVerify: true },
+		]);
+	});
+
+	it("omits hasVerify from the trigger when no verify handler is set", () => {
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			handler: () => {},
+		});
+
+		expect(incoming.config.triggers).toEqual([{ type: "webhooks.webhook" }]);
+	});
+
+	it("rejects a verify handler on a workflow without a webhook trigger", () => {
+		expect(() =>
+			workflow({
+				name: "Log Pages",
+				description: "Logs created pages",
+				triggers: [events.notionPageCreated()],
+				verify: () => ({ status: 200 }),
+				handler: () => {},
+			}),
+		).toThrow(/has no webhook trigger/);
+	});
+
+	it("dispatches a verify invocation to the verify handler, not the workflow handler", async () => {
+		const handler = vi.fn();
+		const verify: WebhookVerifyHandler = (request) => ({
+			status: 200,
+			body: (JSON.parse(request.rawBody) as { challenge: string }).challenge,
+			contentType: "text/plain",
+		});
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify,
+			handler,
+		});
+
+		const response = await incoming.handler(
+			{ request: verifyRequest },
+			{ concreteOutput: true },
+		);
+
+		expect(response).toEqual({ status: 200, body: "abc", contentType: "text/plain" });
+		expect(handler).not.toHaveBeenCalled();
+	});
+
+	it("returns an explicit delivery decision from the verify handler", async () => {
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: () => ({ status: 200, deliver: false }),
+			handler: () => {},
+		});
+
+		const response = await incoming.handler(
+			{ request: verifyRequest },
+			{ concreteOutput: true },
+		);
+
+		expect(response).toEqual({ status: 200, deliver: false });
+	});
+
+	it("passes the capability context to the verify handler", async () => {
+		let receivedContext: unknown;
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: (_request, context) => {
+				receivedContext = context;
+				return { status: 200 };
+			},
+			handler: () => {},
+		});
+
+		await incoming.handler({ request: verifyRequest }, { concreteOutput: true });
+
+		expect(receivedContext).toHaveProperty("notion");
+		expect(receivedContext).not.toHaveProperty("step");
+	});
+
+	it("verifies without workflow run metadata", async () => {
+		delete process.env.NOTION_RUN_METADATA_PATH;
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: () => ({ status: 200 }),
+			handler: () => {},
+		});
+
+		await expect(
+			incoming.handler({ request: verifyRequest }, { concreteOutput: true }),
+		).resolves.toEqual({ status: 200 });
+	});
+
+	it("writes the verify response as a success envelope without concreteOutput", async () => {
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: () => ({ status: 401 }),
+			handler: () => {},
+		});
+
+		await incoming.handler({ request: verifyRequest });
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining('"_tag":"success","value":{"status":401}'),
+		);
+	});
+
+	it("runs in the app bundle, so verify handlers may capture module scope", async () => {
+		const signingSecret = "shh";
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: (request) => ({
+				status: request.headers["x-signature"] === signingSecret ? 200 : 401,
+			}),
+			handler: () => {},
+		});
+
+		const response = await incoming.handler(
+			{ request: { ...verifyRequest, headers: { "x-signature": "shh" } } },
+			{ concreteOutput: true },
+		);
+
+		expect(response).toEqual({ status: 200 });
+	});
+
+	it("uses a file-backed verify request instead of the inline invocation", async () => {
+		if (!metadataDirectory) {
+			throw new Error("Metadata directory was not created");
+		}
+		const payloadPath = join(metadataDirectory, "verify-input.json");
+		await writeFile(
+			payloadPath,
+			JSON.stringify({ request: { ...verifyRequest, rawBody: '{"challenge":"file"}' } }),
+		);
+		process.env.NOTION_INPUT_PAYLOAD_PATH = payloadPath;
+
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: (request) => ({
+				status: 200,
+				body: (JSON.parse(request.rawBody) as { challenge: string }).challenge,
+			}),
+			handler: () => {},
+		});
+
+		const response = await incoming.handler(
+			{ request: verifyRequest },
+			{ concreteOutput: true },
+		);
+
+		expect(response).toEqual({ status: 200, body: "file" });
+	});
+
+	it("still dispatches trigger events to the workflow handler when verify is configured", async () => {
+		const handler = vi.fn();
+		const webhookEvent = { type: "webhooks.webhook" } as WebhookEvent;
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			verify: () => ({ status: 200 }),
+			handler,
+		});
+
+		const result = await incoming.handler(webhookEvent, { concreteOutput: true });
+
+		expect(result).toEqual({ status: "success" });
+		expect(handler).toHaveBeenCalledWith(webhookEvent, expect.anything());
+	});
+
+	it("rejects a verify invocation when no verify handler is declared", async () => {
+		const handler = vi.fn();
+		const incoming = workflow({
+			name: "Incoming",
+			description: "Processes an incoming webhook",
+			triggers: [events.webhook()],
+			handler,
+		});
+
+		await expect(
+			incoming.handler({ request: verifyRequest }, { concreteOutput: true }),
+		).rejects.toThrow(/does not declare a verify handler/);
+		expect(handler).not.toHaveBeenCalled();
+	});
+});