@notionhq/apps 0.0.35 → 0.0.37

package/src/workflow.ts

@@ -23,9 +23,11 @@ import { ExecutionError } from "./error.js";
 import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata, type RunMetadata } from "./runtime-metadata.js";
-import { createWorkflowEvents } from "./events.generated.js";
+import { createWorkflowEvents, validateManualWorkflowInput } from "./events.generated.js";
 import { createWorkflowStepState, type WorkflowState } from "./workflow-state.js";
 import type {
+	ManualWorkflowTrigger,
+	WebhookTrigger,
 	WorkflowEventMap,
 	WorkflowTrigger,
 	WorkflowEventCreators,
@@ -37,6 +39,9 @@ type HandlerOptions = {
 	concreteOutput?: true;
 };
 
+/** The only trigger whose deliveries a verify handler can answer. */
+const WEBHOOK_TRIGGER_TYPE: WebhookTrigger["type"] = "webhooks.webhook";
+
 type WorkflowWaitDurationValues = {
 	milliseconds?: number;
 	seconds?: number;
@@ -200,7 +205,15 @@ export type {
 export { access } from "./workflow-access.js";
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
-export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
+export type WorkflowEventForTrigger<T extends WorkflowTrigger> =
+	T extends ManualWorkflowTrigger<infer TInput>
+		? {
+				type: "workflow.manual";
+				input: TInput;
+			}
+		: T extends { type: keyof WorkflowEventMap }
+			? WorkflowEventMap[T["type"]]
+			: never;
 
 export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
 	WorkflowEventForTrigger<T[number]>;
@@ -215,6 +228,73 @@ export {
 	type OAuthConnection,
 } from "./connections.js";
 
+/**
+ * The inbound HTTP request passed to a webhook verify handler.
+ */
+export type WebhookVerifyRequest = {
+	/** Uppercase HTTP method. Deliveries are POSTs; GET/HEAD cover challenge probes. */
+	method: "GET" | "HEAD" | "POST";
+	/** The full webhook URL as received. */
+	url: string;
+	/** Query string parameters. */
+	query: Record<string, string>;
+	/** Request headers with lowercased names. */
+	headers: Record<string, string>;
+	/** Raw request body. Empty string for bodyless methods like GET and HEAD. */
+	rawBody: string;
+};
+
+/**
+ * The HTTP response a verify handler produces. `deliver`, when present,
+ * explicitly controls whether the request is enqueued for the workflow
+ * handler. Otherwise delivery is derived from the status: 2xx enqueues and 4xx
+ * does not.
+ */
+export type WebhookVerifyResponse = {
+	/** Response status code. Only 2xx and 4xx statuses are allowed. */
+	status: number;
+	/** Optional response body, at most 8KB. */
+	body?: string;
+	/** Response content type. Defaults to "text/plain". */
+	contentType?: "application/json" | "text/plain";
+	/**
+	 * Whether to enqueue the request for the workflow handler. Defaults to true
+	 * for 2xx responses and false for 4xx responses.
+	 */
+	deliver?: boolean;
+};
+
+/**
+ * A webhook verify handler. Runs synchronously at Notion's webhook ingress,
+ * before the HTTP response is sent, in the app's own sandbox — the same
+ * runtime as the workflow handler, with the full Node.js standard library.
+ * Read signing secrets from `process.env` and use `node:crypto` for
+ * signature checks.
+ *
+ * Keep it fast: the run must fit a small wall-clock budget (a few seconds,
+ * including sandbox startup), so avoid network calls — including
+ * `context.notion` API calls, which typically won't fit the budget.
+ */
+export type WebhookVerifyHandler = (
+	request: WebhookVerifyRequest,
+	context: CapabilityContext,
+) => WebhookVerifyResponse | Promise<WebhookVerifyResponse>;
+
+/**
+ * A verify invocation as dispatched by the platform: a single `request`
+ * object rather than the event a workflow invocation carries.
+ */
+export type WebhookVerifyInvocation = {
+	request: WebhookVerifyRequest;
+};
+
+/**
+ * A trigger as the manifest records it. A declared `verify` handler is flagged
+ * on the webhook trigger itself, which is where the platform reads it to decide
+ * whether to run `verify` at webhook ingress.
+ */
+export type WorkflowManifestTrigger = WorkflowTrigger | (WebhookTrigger & { hasVerify: true });
+
 /**
  * Configuration passed to {@link workflow}.
  */
@@ -252,6 +332,40 @@ export type WorkflowConfiguration<
 	 */
 	connections?: TConnections;
 
+	/**
+	 * Optional synchronous verification handler, run at Notion's webhook
+	 * ingress before the HTTP response is sent. Use it for providers that
+	 * require a synchronous verification response: signature checks with
+	 * specific status codes, challenge echoes, or handshake requests.
+	 *
+	 * Only workflows with an `events.webhook()` trigger may declare one.
+	 *
+	 * The handler controls the HTTP response. Return `deliver: true` to enqueue
+	 * the request for the workflow handler, or `deliver: false` to answer the
+	 * provider without enqueueing it. When omitted, 2xx enqueues and 4xx does
+	 * not. `verify` runs in the app's own sandbox with full Node.js — read
+	 * secrets from `process.env` and use `node:crypto` for signature checks. It
+	 * receives the capability context as its second argument, without the run
+	 * metadata and `step` a workflow run carries.
+	 *
+	 * Without `verify`, the webhook keeps the current behavior: every request
+	 * is accepted with `202` and processed asynchronously.
+	 *
+	 * @example
+	 * ```ts
+	 * verify: (request) => {
+	 *   const signature = createHmac("sha256", process.env.WEBHOOK_SECRET ?? "")
+	 *     .update(request.rawBody)
+	 *     .digest("hex");
+	 *   const expected = Buffer.from(`sha256=${signature}`);
+	 *   const actual = Buffer.from(request.headers["x-hub-signature-256"] ?? "");
+	 *   const verified = expected.length === actual.length && timingSafeEqual(expected, actual);
+	 *   return verified ? { status: 200 } : { status: 401, body: "Invalid signature" };
+	 * },
+	 * ```
+	 */
+	verify?: WebhookVerifyHandler;
+
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
 		context: WorkflowContext<TConnections, TAccess>,
@@ -283,14 +397,14 @@ export type Workflow<
 	config: {
 		name: string;
 		description: string;
-		triggers: TTriggers;
+		triggers: WorkflowManifestTrigger[];
 		connections?: readonly WorkflowConnectionRequirement[];
 		access?: WorkflowAccessRequirements;
 	};
 	handler: (
-		event: WorkflowEventForTriggers<TTriggers>,
+		input: WorkflowEventForTriggers<TTriggers> | WebhookVerifyInvocation,
 		options?: HandlerOptions,
-	) => Promise<WorkflowHandlerResult | undefined>;
+	) => Promise<WorkflowHandlerResult | WebhookVerifyResponse | undefined>;
 };
 
 /**
@@ -354,22 +468,61 @@ export function workflow<
 			? configuration.triggers({ events: createWorkflowEvents<TConnections>() })
 			: configuration.triggers;
 	validateTriggerConnections(triggers, requirements);
+	const manualTriggers = triggers.filter(
+		(trigger): trigger is ManualWorkflowTrigger => trigger.type === "workflow.manual",
+	);
+	if (manualTriggers.length > 1) {
+		throw new Error("Workflows support at most one manual trigger");
+	}
+
+	if (
+		configuration.verify !== undefined &&
+		!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 !== undefined),
 			...(configuration.connections === undefined ? {} : { connections: requirements }),
 			...(configuration.access === undefined ? {} : { access: accessRequirements }),
 		},
 		async handler(
-			event: WorkflowEventForTriggers<TTriggers>,
+			input: WorkflowEventForTriggers<TTriggers> | WebhookVerifyInvocation,
 			options?: HandlerOptions,
-		): Promise<WorkflowHandlerResult | undefined> {
+		): Promise<WorkflowHandlerResult | WebhookVerifyResponse | undefined> {
 			try {
-				event = await resolveRuntimeInput(event);
+				input = await resolveRuntimeInput(input);
+
+				if (isVerifyInvocation(input)) {
+					if (configuration.verify === undefined) {
+						throw new Error(
+							`Workflow "${configuration.name}" received a verify request but does not ` +
+								`declare a verify handler`,
+						);
+					}
+
+					const response = await configuration.verify(
+						input.request,
+						createCapabilityContext(),
+					);
+
+					if (options?.concreteOutput) {
+						return response;
+					}
+
+					writeOutput({ _tag: "success", value: response });
+					return undefined;
+				}
+
+				const event = input;
 				const runMetadata = readRunMetadata();
 				const baseContext = createCapabilityContext();
 				const step = createStep(runMetadata);
@@ -384,6 +537,15 @@ export function workflow<
 					step,
 					wait: createWait(step),
 				};
+				if (event.type === "workflow.manual") {
+					const manualTrigger = manualTriggers[0];
+					if (manualTrigger === undefined) {
+						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) {
@@ -423,6 +585,31 @@ export function workflow<
 	};
 }
 
+/**
+ * The triggers as the manifest records them. The manifest only records that a
+ * verify handler exists, flagged on the webhook trigger; the handler itself
+ * ships in the app bundle and runs via a verify invocation.
+ */
+function manifestTriggers(
+	triggers: readonly WorkflowTrigger[],
+	hasVerify: boolean,
+): WorkflowManifestTrigger[] {
+	return triggers.map((trigger) =>
+		hasVerify && trigger.type === WEBHOOK_TRIGGER_TYPE
+			? { ...trigger, hasVerify: true as const }
+			: trigger,
+	);
+}
+
+/**
+ * Whether an invocation is the platform's synchronous verify dispatch. The
+ * platform sends workflow invocations as a trigger event and verify
+ * invocations as a `{ request }` object, so the shape disambiguates.
+ */
+function isVerifyInvocation(input: unknown): input is WebhookVerifyInvocation {
+	return typeof input === "object" && input !== null && "request" in input;
+}
+
 /** Context passed to a workflow step. */
 export type StepContext = {
 	/**