@notionhq/apps 0.0.1

package/src/workflow.ts

@@ -0,0 +1,418 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import { ExecutionError } from "./error.js";
+import { writeOutput } from "./output.js";
+import { readRunMetadata, type RunMetadata } from "./runtime-metadata.js";
+import type { WorkflowEventMap, WorkflowTrigger } from "./triggers.generated.js";
+
+type HandlerOptions = {
+	/** Return the concrete result instead of writing the output envelope. */
+	concreteOutput?: true;
+};
+
+export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
+
+export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
+
+export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
+	WorkflowEventForTrigger<T[number]>;
+
+/**
+ * Configuration passed to {@link createWorkflow}.
+ */
+export type WorkflowConfiguration<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+> = {
+	/**
+	 * A human-readable name for the workflow, shown in the UI when viewing workflows
+	 */
+	name: string;
+
+	/**
+	 * A human-readable description of what the workflow does, shown in the UI when viewing workflows
+	 */
+	description: string;
+
+	/**
+	 * An array of triggers that can invoke this workflow.
+	 *
+	 * Each trigger defines a specific event or condition that causes the workflow to run.
+	 */
+	triggers: TTriggers;
+
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		context: WorkflowContext,
+	) => Promise<void> | void;
+};
+
+/**
+ * A workflow capability as returned by {@link createWorkflow}.
+ *
+ * Note that a workflow carries no key of its own — the build tool derives
+ * the capability key from the file the workflow is default-exported from.
+ */
+export type Workflow<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]] = readonly [
+		WorkflowTrigger,
+		...WorkflowTrigger[],
+	],
+> = {
+	_tag: "workflow";
+	config: {
+		name: string;
+		description: string;
+		triggers: TTriggers;
+	};
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		options?: HandlerOptions,
+	) => Promise<{ status: "success" } | undefined>;
+};
+
+/**
+ * Create a workflow capability.
+ *
+ * Default-export the result from a file directly under `src/workflows/` —
+ * the file's basename becomes the workflow's key.
+ *
+ * @example
+ * ```ts
+ * // src/workflows/onPageCreated.ts
+ * import { triggers } from "@notionhq/apps/triggers";
+ * import { createWorkflow } from "@notionhq/apps/workflow";
+ *
+ * export default createWorkflow({
+ *   name: "Send Welcome Email",
+ *   description: "Sends a welcome email when a new page is added",
+ *   triggers: [triggers.notionPageCreated()],
+ *   handler: async (event, context) => {
+ *     console.log(event.page);
+ *     await context.step("Process page", async ({ id }) => {
+ *       console.log(`Running step ${id}`);
+ *       return processPage(event.page);
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export function createWorkflow<
+	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+>(configuration: WorkflowConfiguration<TTriggers>): Workflow<TTriggers> {
+	return {
+		_tag: "workflow",
+		config: {
+			name: configuration.name,
+			description: configuration.description,
+			triggers: configuration.triggers,
+		},
+		async handler(
+			event: WorkflowEventForTriggers<TTriggers>,
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const runMetadata = readRunMetadata();
+				const capabilityContext: WorkflowContext = {
+					...createCapabilityContext(),
+					...runMetadata,
+					step: createStep(runMetadata),
+				};
+				await configuration.handler(event, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				}
+
+				writeOutput({ _tag: "success", value: { status: "success" } });
+			} catch (err) {
+				const error = new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
+				}
+
+				throw error;
+			}
+		},
+	};
+}
+
+/** Context passed to a workflow step. */
+export type StepContext = {
+	/**
+	 * An identifier that is stable for this step across attempts of the workflow run.
+	 * Use this to make side effects idempotent when the workflow is retried.
+	 */
+	id: string;
+};
+
+type WorkflowStepResult<T> = T extends void ? null : T;
+
+/** Options for a workflow step. */
+export type WorkflowStepOptions = {
+	/**
+	 * A stable key used to identify this step across attempts of a workflow run.
+	 * Pass a string for a single key segment or an array of strings for a composite
+	 * key. Defaults to the step name. Changing the key creates a new logical step.
+	 */
+	key: string | string[];
+};
+
+type WorkflowStep = {
+	<T>(name: string, fn: (context: StepContext) => T | Promise<T>): Promise<WorkflowStepResult<T>>;
+	<T>(
+		name: string,
+		options: WorkflowStepOptions,
+		fn: (context: StepContext) => T | Promise<T>,
+	): Promise<WorkflowStepResult<T>>;
+};
+
+/** Context passed to a workflow handler. */
+export type WorkflowContext = CapabilityContext &
+	RunMetadata & {
+		/**
+		 * Run an observable unit of work within the workflow.
+		 *
+		 * The callback may be synchronous or asynchronous, but `step` always returns
+		 * a promise. Its return value must be JSON-serializable so it can be included
+		 * in the success event written to stdout. A callback that returns `undefined`
+		 * is normalized to `null`, which keeps first runs and saved replays consistent.
+		 *
+		 * The step name is used to derive its stable replay key by default. Step key
+		 * inputs must be unique within a workflow invocation. Pass an explicit string
+		 * or array of strings when display names are duplicated or may change.
+		 *
+		 * @example
+		 * ```ts
+		 * const page = await context.step("Fetch page", async ({ id }) => {
+		 *   console.log(`Running step ${id}`);
+		 *   return context.notion.pages.retrieve({ page_id: pageId });
+		 * });
+		 * ```
+		 */
+		step: WorkflowStep;
+	};
+
+type StepCompletionType = "success" | "failure";
+type StepEventType = "started" | "success" | "failure" | "replayed" | "completed";
+
+type WorkflowStepCheckpoint = {
+	version: 0;
+	key: string;
+	value: unknown;
+	sourceRunId: string;
+	sourceStepId: string;
+};
+
+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_-]+$/;
+const WORKFLOW_STEP_KEY_HASH_DOMAIN = "notion-workflow-step-key";
+const WORKFLOW_STEP_KEY_HASH_VERSION = 1;
+
+function writeStepEvent(
+	event: StepEventType,
+	value: Record<string, unknown>,
+	startedAt: number,
+	emittedAt = performance.now(),
+) {
+	const tag = `__notion_step_${event}__`;
+	process.stdout.write(
+		`\n<${tag}>${JSON.stringify({
+			...value,
+			timestampMs: performance.timeOrigin + emittedAt,
+			durationMs: emittedAt - startedAt,
+		})}</${tag}>\n`,
+	);
+}
+
+function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowContext["step"] {
+	const stepNameByKey = new Map<string, string>();
+
+	async function step<T>(
+		name: string,
+		optionsOrFn: WorkflowStepOptions | ((context: StepContext) => T | Promise<T>),
+		maybeFn?: (context: StepContext) => T | Promise<T>,
+	): Promise<WorkflowStepResult<T>> {
+		const options = typeof optionsOrFn === "function" ? undefined : optionsOrFn;
+		const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+		if (!fn) {
+			throw new Error(`Workflow step "${name}" is missing its callback.`);
+		}
+
+		const keyInput = options?.key ?? name;
+		const key = createWorkflowStepKey(typeof keyInput === "string" ? [keyInput] : keyInput);
+		const existingStepName = stepNameByKey.get(key);
+		if (existingStepName !== undefined) {
+			throw new Error(
+				`Workflow step "${name}" has the same key as "${existingStepName}". Step names are used as keys by default; provide a unique name or an explicit key.`,
+			);
+		}
+		stepNameByKey.set(key, name);
+
+		const context: StepContext = { id: `${runGroupId}:${key}` };
+		const event = { id: context.id, name, key };
+		const startedAt = performance.now();
+
+		writeStepEvent("started", event, startedAt, startedAt);
+
+		try {
+			const checkpoint = await readWorkflowStepCheckpoint(key);
+			if (checkpoint) {
+				writeStepEvent(
+					"replayed",
+					{
+						...event,
+						sourceRunId: checkpoint.sourceRunId,
+						sourceStepId: checkpoint.sourceStepId,
+					},
+					startedAt,
+				);
+				writeStepEvent(
+					"completed",
+					{
+						...event,
+						type: "success" satisfies StepCompletionType,
+					},
+					startedAt,
+				);
+				return checkpoint.value as WorkflowStepResult<T>;
+			}
+
+			const value = normalizeWorkflowStepResult(await fn(context));
+			writeStepEvent("success", { ...event, value }, startedAt);
+			writeStepEvent(
+				"completed",
+				{
+					...event,
+					type: "success" satisfies StepCompletionType,
+				},
+				startedAt,
+			);
+			return value;
+		} catch (err) {
+			const error = new ExecutionError(err);
+			writeStepEvent(
+				"failure",
+				{
+					...event,
+					error: {
+						name: error.name,
+						message: error.message,
+						trace: error.stack,
+					},
+				},
+				startedAt,
+			);
+			writeStepEvent(
+				"completed",
+				{
+					...event,
+					type: "failure" satisfies StepCompletionType,
+				},
+				startedAt,
+			);
+			throw err;
+		}
+	}
+
+	return step;
+}
+
+function createWorkflowStepKey(segments: readonly unknown[]): string {
+	if (segments.length === 0) {
+		throw new Error("Workflow step keys must contain at least one segment.");
+	}
+	for (const segment of segments) {
+		if (typeof segment !== "string") {
+			throw new Error("Workflow step key segments must be strings.");
+		}
+		if (segment.length === 0) {
+			throw new Error("Workflow step key segments must not be empty.");
+		}
+	}
+
+	const serialized = JSON.stringify([
+		WORKFLOW_STEP_KEY_HASH_DOMAIN,
+		WORKFLOW_STEP_KEY_HASH_VERSION,
+		...segments,
+	]);
+	const key = createHash("sha256").update(serialized).digest("base64url");
+	if (key.length !== MAX_WORKFLOW_STEP_KEY_LENGTH || !WORKFLOW_STEP_KEY_PATTERN.test(key)) {
+		throw new Error(
+			`Workflow step keys must be ${MAX_WORKFLOW_STEP_KEY_LENGTH} Base64url characters after hashing.`,
+		);
+	}
+
+	return key;
+}
+
+function normalizeWorkflowStepResult<T>(value: T): WorkflowStepResult<T> {
+	return (value === undefined ? null : value) as WorkflowStepResult<T>;
+}
+
+async function readWorkflowStepCheckpoint(
+	key: string,
+): Promise<WorkflowStepCheckpoint | undefined> {
+	const directory = process.env[WORKFLOW_STEP_DIRECTORY_ENV_KEY];
+	if (!directory) {
+		return undefined;
+	}
+
+	// The key may contain slashes, private data, or more bytes than a file name
+	// allows. Hashing gives both sides a safe path while the key inside the file
+	// still proves that this checkpoint belongs to the requested step.
+	const path = join(directory, `${hashWorkflowStepKey(key)}.json`);
+	let serialized: string;
+	try {
+		serialized = await readFile(path, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") {
+			return undefined;
+		}
+		throw error;
+	}
+
+	const parsed: unknown = JSON.parse(serialized);
+	if (
+		!isRecord(parsed) ||
+		parsed.version !== 0 ||
+		parsed.key !== key ||
+		!Object.hasOwn(parsed, "value") ||
+		typeof parsed.sourceRunId !== "string" ||
+		typeof parsed.sourceStepId !== "string"
+	) {
+		throw new Error(`Workflow step checkpoint ${hashWorkflowStepKey(key)} is invalid.`);
+	}
+
+	return {
+		version: 0,
+		key,
+		value: parsed.value,
+		sourceRunId: parsed.sourceRunId,
+		sourceStepId: parsed.sourceStepId,
+	};
+}
+
+function hashWorkflowStepKey(key: string): string {
+	return createHash("sha256").update(key).digest("hex");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}