@notionhq/apps 0.0.35 → 0.0.37

package/dist/workflow.js

@@ -15,8 +15,9 @@ import { ExecutionError } from "./error.js";
 import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata } from "./runtime-metadata.js";
-import { createWorkflowEvents } from "./events.generated.js";
+import { createWorkflowEvents, validateManualWorkflowInput } from "./events.generated.js";
 import { createWorkflowStepState } from "./workflow-state.js";
+const WEBHOOK_TRIGGER_TYPE = "webhooks.webhook";
 const input = {
   text(options) {
     return { type: "text", ...options };
@@ -56,18 +57,46 @@ function workflow(configuration) {
   const connectionDeclarations = configuration.connections === void 0 ? void 0 : structuredClone(configuration.connections);
   const triggers = typeof configuration.triggers === "function" ? configuration.triggers({ events: createWorkflowEvents() }) : configuration.triggers;
   validateTriggerConnections(triggers, requirements);
+  const manualTriggers = triggers.filter(
+    (trigger) => trigger.type === "workflow.manual"
+  );
+  if (manualTriggers.length > 1) {
+    throw new Error("Workflows support at most one manual trigger");
+  }
+  if (configuration.verify !== void 0 && !triggers.some((trigger) => trigger.type === WEBHOOK_TRIGGER_TYPE)) {
+    throw new Error(
+      `Workflow "${configuration.name}" declares a verify handler but has no webhook trigger. Add events.webhook() or remove verify.`
+    );
+  }
   return {
     _tag: "workflow",
     config: {
       name: configuration.name,
       description: configuration.description,
-      triggers,
+      triggers: manifestTriggers(triggers, configuration.verify !== void 0),
       ...configuration.connections === void 0 ? {} : { connections: requirements },
       ...configuration.access === void 0 ? {} : { access: accessRequirements }
     },
-    async handler(event, options) {
+    async handler(input2, options) {
       try {
-        event = await resolveRuntimeInput(event);
+        input2 = await resolveRuntimeInput(input2);
+        if (isVerifyInvocation(input2)) {
+          if (configuration.verify === void 0) {
+            throw new Error(
+              `Workflow "${configuration.name}" received a verify request but does not declare a verify handler`
+            );
+          }
+          const response = await configuration.verify(
+            input2.request,
+            createCapabilityContext()
+          );
+          if (options?.concreteOutput) {
+            return response;
+          }
+          writeOutput({ _tag: "success", value: response });
+          return void 0;
+        }
+        const event = input2;
         const runMetadata = readRunMetadata();
         const baseContext = createCapabilityContext();
         const step = createStep(runMetadata);
@@ -82,6 +111,15 @@ function workflow(configuration) {
           step,
           wait: createWait(step)
         };
+        if (event.type === "workflow.manual") {
+          const manualTrigger = manualTriggers[0];
+          if (manualTrigger === void 0) {
+            throw new Error(
+              "Received workflow.manual for a workflow without a manual trigger"
+            );
+          }
+          validateManualWorkflowInput(manualTrigger, event.input);
+        }
         await configuration.handler(event, capabilityContext);
         if (options?.concreteOutput) {
           return { status: "success" };
@@ -114,6 +152,14 @@ function workflow(configuration) {
     }
   };
 }
+function manifestTriggers(triggers, hasVerify) {
+  return triggers.map(
+    (trigger) => hasVerify && trigger.type === WEBHOOK_TRIGGER_TYPE ? { ...trigger, hasVerify: true } : trigger
+  );
+}
+function isVerifyInvocation(input2) {
+  return typeof input2 === "object" && input2 !== null && "request" in input2;
+}
 const WORKFLOW_STEP_DIRECTORY_ENV_KEY = "NOTION_WORKFLOW_STEP_DIRECTORY";
 const MAX_WORKFLOW_STEP_KEY_LENGTH = 43;
 const WORKFLOW_STEP_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.35",
+	"version": "0.0.37",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {
@@ -83,7 +83,11 @@
 			"types": "./dist/react.d.ts",
 			"default": "./dist/react.js"
 		},
-		"./nds.css": "./dist/nds.css"
+		"./nds.css": "./dist/nds.css",
+		"./schema-builder": {
+			"types": "./dist/schema-builder.d.ts",
+			"default": "./dist/schema-builder.js"
+		}
 	},
 	"publishConfig": {
 		"access": "public"
@@ -108,6 +112,7 @@
 	"dependencies": {
 		"@notionhq/custom-blocks": "latest",
 		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1",
 		"rolldown": "^1.1.5"
 	},
 	"devDependencies": {

package/skills/workflow/SKILL.md

@@ -108,6 +108,39 @@ placeholders to `.env.example` when configuration is required. Return only
 JSON-serializable step values, throw on failed requests and missing required
 configuration, and do not log secrets or private payloads.
 
+## Manual workflow inputs
+
+Provide up to one `events.manual` to allow triggering the workflow manually from the UI or CLI for testing purposes.
+
+Specify the inputs accepted using `@notionhq/apps/schema-builder`.
+
+```ts
+import { workflow } from "@notionhq/apps/workflow";
+import { events } from "@notionhq/apps/events";
+import { j } from "@notionhq/apps/schema-builder";
+
+export default workflow({
+	name: "Prepare releases",
+	description: "Prepares the supplied releases.",
+	triggers: [
+		events.manual({
+			inputSchema: j.object({
+				releases: j.array(
+					j.object({
+						version: j.string(),
+						dryRun: j.boolean().nullable().describe("Whether to preview the release"),
+					}),
+				),
+			}),
+		}),
+	],
+	handler: async (event, context) => {
+		// event.input: { releases: { version: string; dryRun: boolean | null }[] }
+		await context.step("Log releases", () => console.log(event.input.releases));
+	},
+});
+```
+
 ## Resources created with the App
 
 Use [Notion as Code](../notion-as-code/SKILL.md) for pages, databases, and custom agents

package/src/cli/build.test.ts

@@ -480,6 +480,7 @@ describe("buildApp", () => {
 			const { manifest } = await buildApp(root);
 			expect(manifest.capabilities).toEqual([
 				expect.objectContaining({ type: "workflow", key: "onPageCreated" }),
+				expect.objectContaining({ type: "workflow", key: "prepareReleases" }),
 			]);
 			await expect(fs.promises.readFile(provisioningPath)).rejects.toMatchObject({
 				code: "ENOENT",
@@ -538,12 +539,67 @@ describe("buildApp", () => {
 						triggers: [{ type: "notion.page.created" }],
 					},
 				},
+				{
+					type: "workflow",
+					key: "prepareReleases",
+					config: {
+						name: "Prepare releases",
+						description: "Prepares the supplied releases.",
+						triggers: [
+							{
+								type: "workflow.manual",
+								inputJsonSchema: {
+									type: "object",
+									additionalProperties: false,
+									required: ["releases"],
+									properties: {
+										releases: {
+											type: "array",
+											items: {
+												type: "object",
+												additionalProperties: false,
+												required: ["version", "dryRun"],
+												properties: {
+													version: { type: "string" },
+													dryRun: {
+														anyOf: [
+															{ type: "boolean" },
+															{ type: "null" },
+														],
+													},
+												},
+											},
+										},
+									},
+								},
+							},
+						],
+					},
+				},
 			],
 		});
 		expect(path.basename(bundlePath)).toBe("worker.js");
 		expect(JSON.parse(await fs.promises.readFile(manifestPath, "utf8"))).toEqual(manifest);
 	});
 
+	it("records a workflow's verify handler in the manifest", async () => {
+		const { manifestPath } = await buildApp(fixture("webhook-verify"));
+
+		expect(JSON.parse(await fs.promises.readFile(manifestPath, "utf8"))).toMatchObject({
+			capabilities: [
+				{
+					type: "workflow",
+					key: "onIncoming",
+					config: {
+						name: "Incoming Webhook",
+						description: "Verifies and processes an incoming webhook",
+						triggers: [{ type: "webhooks.webhook", hasVerify: true }],
+					},
+				},
+			],
+		});
+	});
+
 	it("collects relation databases and a shared pacer once", async () => {
 		const { manifest } = await buildApp(fixture("shared-primary-key"));
 

package/src/cli/codegen.test.ts

@@ -20,6 +20,20 @@ describe("generateEntry", () => {
 		expect(entry).toContain("export async function run(");
 	});
 
+	it("resolves the webhook verify invocation type to the workflow registry", () => {
+		const entry = generateEntry([
+			{
+				type: "workflow",
+				tag: "workflow",
+				key: "onIncoming",
+				sourcePath: "src/workflows/onIncoming.ts",
+				runtime: "worker",
+			},
+		]);
+
+		expect(entry).toContain(`workflowWebhookVerify: "workflow",`);
+	});
+
 	it("registers syncs in their own capability group", () => {
 		const entry = generateEntry([
 			{

package/src/cli/codegen.ts

@@ -37,16 +37,24 @@ export const capabilities: Record<string, Record<string, { handler: Handler }>>
 ${registry}
 };
 
+// The platform dispatches a workflow's synchronous webhook verify run under its
+// own invocation type. It resolves to the same capability, which tells a verify
+// invocation from a trigger event by the shape of its input.
+const invocationTypes: Record<string, string | undefined> = {
+	workflowWebhookVerify: "workflow",
+};
+
 export async function run(
 	type: string,
 	key: string,
 	context?: unknown,
 	options?: { concreteOutput?: true },
 ): Promise<unknown> {
-	const capability = capabilities[type]?.[key];
+	const capabilityType = invocationTypes[type] ?? type;
+	const capability = capabilities[capabilityType]?.[key];
 
 	if (!capability) {
-		throw new Error(\`Capability "\${type}/\${key}" not found\`);
+		throw new Error(\`Capability "\${capabilityType}/\${key}" not found\`);
 	}
 
 	return capability.handler(context, options);

package/src/cli/discover.test.ts

@@ -27,6 +27,13 @@ describe("discoverCapabilities", () => {
 				key: "onPageCreated",
 				sourcePath: path.join("src", "workflows", "onPageCreated.ts"),
 			},
+			{
+				type: "workflow",
+				tag: "workflow",
+				runtime: "worker",
+				key: "prepareReleases",
+				sourcePath: path.join("src", "workflows", "prepareReleases.ts"),
+			},
 		]);
 	});
 

package/src/events.generated.ts

@@ -2,6 +2,8 @@
 // Regenerate with: pnpm run generate
 
 import type { WorkflowConnectionDeclarations, WorkflowConnectionKeys } from "./connections.js";
+import { compileWorkflowInputSchema } from "./workflow-schema.js";
+import { j, type SchemaBuilder } from "./schema-builder.js";
 import { scheduled, notionPageCreated, notionPageUpdated } from "./configured-events.js";
 import type { NotionPageCreatedTrigger, NotionPageUpdatedTrigger, PageUpdatedOptions, RecurrenceTrigger } from "./configured-events.js";
 import type { DataSourceHandle } from "./notion-as-code/database.js";
@@ -82,6 +84,15 @@ export type {
 export type { NotionPageCreatedTrigger, NotionPageUpdatedTrigger, PageUpdatedOptions, RecurrenceTrigger } from "./configured-events.js";
 export type { RecurrenceSchedule } from "./notion-as-code/recurrence.js";
 
+declare const manualWorkflowInputSchema: unique symbol;
+const manualInputValidators = new WeakMap<object, (input: unknown) => void>();
+
+export type ManualWorkflowTrigger<TInput extends Record<string, unknown> = Record<string, unknown>> = {
+	type: "workflow.manual";
+	inputJsonSchema: Record<string, unknown>;
+	readonly [manualWorkflowInputSchema]?: TInput;
+};
+
 /** Triggers immediately after a new message is posted in Slack (includes new threads and replies) */
 export type SlackMessageTrigger<TKey extends string = string> = {
 	type: "slack.message";
@@ -194,8 +205,27 @@ export type GoogleDriveOauthFilesChangedTrigger<TKey extends string = string> =
 	connectionKey?: TKey;
 };
 
+function manual(): ManualWorkflowTrigger<Record<string, never>>;
+function manual<TInput extends Record<string, unknown>>(options: {
+	inputSchema: SchemaBuilder<TInput, "object">;
+}): ManualWorkflowTrigger<TInput>;
+function manual(options?: {
+	inputSchema: SchemaBuilder<Record<string, unknown>, "object">;
+}): ManualWorkflowTrigger {
+	const { jsonSchema, validate } = compileWorkflowInputSchema(
+		options === undefined ? j.object({}) : options.inputSchema,
+	);
+	const trigger: ManualWorkflowTrigger = {
+		type: "workflow.manual",
+		inputJsonSchema: jsonSchema,
+	};
+	manualInputValidators.set(trigger, validate);
+	return trigger;
+}
+
 /** Creators for each event that can trigger a workflow. */
 export const events = {
+	manual,
 	/**
 	 * Declare that a workflow can run on `slack.message` events.
 	 *
@@ -414,6 +444,8 @@ export const events = {
 
 /** Trigger creators restricted to the workflow's declared provider keys. */
 export type WorkflowEventCreators<TConnections extends WorkflowConnectionDeclarations> = {
+	manual(): ManualWorkflowTrigger<Record<string, never>>;
+	manual<TInput extends Record<string, unknown>>(options: { inputSchema: SchemaBuilder<TInput, "object"> }): ManualWorkflowTrigger<TInput>;
 	slackMessage(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackMessageTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
 	slackReactionAdded(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackReactionAddedTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
 	slackAppMention(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackAppMentionTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
@@ -439,6 +471,7 @@ export type WorkflowEventCreators<TConnections extends WorkflowConnectionDeclara
 
 /** Triggers whose connection keys belong to the declared provider. */
 export type WorkflowTriggerForConnections<TConnections extends WorkflowConnectionDeclarations> =
+	| ManualWorkflowTrigger
 	| SlackMessageTrigger<WorkflowConnectionKeys<TConnections, "slack">>
 	| SlackReactionAddedTrigger<WorkflowConnectionKeys<TConnections, "slack">>
 	| SlackAppMentionTrigger<WorkflowConnectionKeys<TConnections, "slack">>
@@ -468,6 +501,7 @@ export function createWorkflowEvents<TConnections extends WorkflowConnectionDecl
 
 /** Event that can trigger a workflow. */
 export type WorkflowTrigger =
+	| ManualWorkflowTrigger
 	| SlackMessageTrigger
 	| SlackReactionAddedTrigger
 	| SlackAppMentionTrigger
@@ -492,6 +526,7 @@ export type WorkflowTrigger =
 
 /** All workflow trigger type strings. */
 export const WORKFLOW_TRIGGER_TYPES = [
+	"workflow.manual",
 	"slack.message",
 	"slack.reaction.added",
 	"slack.app.mention",
@@ -542,3 +577,15 @@ export type WorkflowEventMap = {
 	"googleDriveOauth.filesChanged": GoogleDriveOauthFilesChangedEvent;
 	recurrence: RecurrenceEvent;
 };
+
+/** @internal */
+export function validateManualWorkflowInput(
+	trigger: ManualWorkflowTrigger,
+	input: unknown,
+): void {
+	const validate = manualInputValidators.get(trigger);
+	if (validate === undefined) {
+		throw new Error("Manual workflow trigger is missing its input schema");
+	}
+	validate(input);
+}

package/src/schema-builder.ts

@@ -0,0 +1,149 @@
+/** Fluent JSON Schema builders following the classic Workers schema-builder API. */
+const SCHEMA: unique symbol = Symbol("schema");
+const KIND: unique symbol = Symbol("kind");
+declare const VALUE: unique symbol;
+
+export type StringFormat =
+	| "date-time"
+	| "date"
+	| "time"
+	| "duration"
+	| "email"
+	| "hostname"
+	| "ipv4"
+	| "ipv6"
+	| "uuid";
+
+type Kind = "object" | "value";
+type JsonSchema = {
+	title?: string;
+	description?: string;
+} & (
+	| {
+			type: "string" | "number" | "integer" | "boolean" | "null";
+			enum?: readonly (string | number)[];
+			format?: StringFormat;
+	  }
+	| { type: "array"; items: JsonSchema; minItems?: 0 | 1 }
+	| {
+			type: "object";
+			properties: Record<string, JsonSchema>;
+			required: string[];
+			additionalProperties: false;
+	  }
+	| { anyOf: JsonSchema[] }
+);
+
+export interface SchemaBuilder<T, K extends Kind = Kind> {
+	readonly [SCHEMA]: JsonSchema;
+	readonly [KIND]: K;
+	readonly [VALUE]?: T;
+	describe(text: string): SchemaBuilder<T, K>;
+	label(text: string): SchemaBuilder<T, K>;
+	nullable(): SchemaBuilder<T | null, "value">;
+}
+
+export type Infer<S> = S extends SchemaBuilder<infer T> ? T : never;
+
+/** Returns a copy so callers cannot mutate the builder's validation contract. */
+export function getSchema(builder: SchemaBuilder<unknown>): JsonSchema {
+	if (typeof builder !== "object" || builder === null || !(SCHEMA in builder)) {
+		throw new Error("Expected a schema builder; use j.object() for manual inputs");
+	}
+	return structuredClone(builder[SCHEMA]);
+}
+
+function makeBuilder<T, K extends Kind>(schema: JsonSchema, kind: K): SchemaBuilder<T, K> {
+	return {
+		[SCHEMA]: schema,
+		[KIND]: kind,
+		describe(description) {
+			return makeBuilder<T, K>({ ...schema, description }, kind);
+		},
+		label(title) {
+			return makeBuilder<T, K>({ ...schema, title }, kind);
+		},
+		nullable() {
+			const { title, description, ...inner } = schema;
+			return makeBuilder<T | null, "value">(
+				{
+					anyOf: [inner, { type: "null" }],
+					...(title === undefined ? {} : { title }),
+					...(description === undefined ? {} : { description }),
+				},
+				"value",
+			);
+		},
+	};
+}
+
+function string(): SchemaBuilder<string, "value"> {
+	return makeBuilder({ type: "string" }, "value");
+}
+function formattedString(format: StringFormat): SchemaBuilder<string, "value"> {
+	return makeBuilder({ type: "string", format }, "value");
+}
+
+function number(): SchemaBuilder<number, "value"> {
+	return makeBuilder({ type: "number" }, "value");
+}
+function integer(): SchemaBuilder<number, "value"> {
+	return makeBuilder({ type: "integer" }, "value");
+}
+function boolean(): SchemaBuilder<boolean, "value"> {
+	return makeBuilder({ type: "boolean" }, "value");
+}
+
+function enumBuilder<const T extends string>(first: T, ...rest: T[]): SchemaBuilder<T, "value">;
+function enumBuilder<const T extends number>(first: T, ...rest: T[]): SchemaBuilder<T, "value">;
+function enumBuilder(
+	first: string | number,
+	...rest: (string | number)[]
+): SchemaBuilder<string | number, "value"> {
+	return makeBuilder(
+		{ type: typeof first === "string" ? "string" : "number", enum: [first, ...rest] },
+		"value",
+	);
+}
+
+function array<T>(
+	items: SchemaBuilder<T>,
+	options?: { minItems?: 0 | 1 },
+): SchemaBuilder<T[], "value"> {
+	return makeBuilder({ type: "array", items: getSchema(items), ...options }, "value");
+}
+
+function object<P extends Record<string, SchemaBuilder<unknown>>>(
+	properties: P,
+): SchemaBuilder<{ -readonly [K in keyof P]: Infer<P[K]> }, "object"> {
+	return makeBuilder(
+		{
+			type: "object",
+			properties: Object.fromEntries(
+				Object.entries(properties).map(([key, value]) => [key, getSchema(value)]),
+			),
+			required: Object.keys(properties),
+			additionalProperties: false,
+		},
+		"object",
+	);
+}
+
+export const j = {
+	string,
+	number,
+	integer,
+	boolean,
+	enum: enumBuilder,
+	array,
+	object,
+	datetime: () => formattedString("date-time"),
+	date: () => formattedString("date"),
+	time: () => formattedString("time"),
+	duration: () => formattedString("duration"),
+	email: () => formattedString("email"),
+	hostname: () => formattedString("hostname"),
+	ipv4: () => formattedString("ipv4"),
+	ipv6: () => formattedString("ipv6"),
+	uuid: () => formattedString("uuid"),
+};