@notionhq/apps 0.0.16 → 0.0.18

package/src/workflow.ts

@@ -1,8 +1,9 @@
 import {
 	createWorkflowConnections,
-	validateConnectionRequirements,
+	normalizeConnectionRequirements,
 	validateTriggerConnections,
-	type WorkflowConnection,
+	type WorkflowConnectionDeclarations,
+	type WorkflowConnectionRequirement,
 	type WorkflowConnections,
 } from "./connections.js";
 import { createHash } from "node:crypto";
@@ -16,6 +17,7 @@ import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata, type RunMetadata } from "./runtime-metadata.js";
 import { createWorkflowTriggers } from "./triggers.generated.js";
+import { createWorkflowStepState, type WorkflowState } from "./workflow-state.js";
 import type {
 	WorkflowEventMap,
 	WorkflowTrigger,
@@ -28,6 +30,45 @@ type HandlerOptions = {
 	concreteOutput?: true;
 };
 
+type WorkflowWaitDurationValues = {
+	milliseconds?: number;
+	seconds?: number;
+	minutes?: number;
+	hours?: number;
+	days?: number;
+	weeks?: number;
+};
+
+export type WorkflowWaitDuration = {
+	[Unit in keyof WorkflowWaitDurationValues]-?: Required<Pick<WorkflowWaitDurationValues, Unit>> &
+		WorkflowWaitDurationValues;
+}[keyof WorkflowWaitDurationValues];
+
+type WorkflowWaitKey = string | string[];
+
+export type WorkflowWaitUntilOptions =
+	| {
+			at: Date;
+			key?: WorkflowWaitKey;
+	  }
+	| {
+			after: WorkflowWaitDuration;
+			key?: WorkflowWaitKey;
+	  };
+
+export type WorkflowWaitUntilResult = {
+	status: "waiting";
+	wait: {
+		type: "until";
+		name: string;
+		resumeAtMs: number;
+	};
+};
+
+type WorkflowHandlerResult = { status: "success" } | WorkflowWaitUntilResult;
+
+const MAX_WORKFLOW_WAIT_MS = 7 * 24 * 60 * 60 * 1_000;
+
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
@@ -35,14 +76,22 @@ export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMa
 export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
 	WorkflowEventForTrigger<T[number]>;
 
-export { connections, type WorkflowConnection, type WorkflowConnections } from "./connections.js";
+export {
+	connections,
+	type WorkflowConnection,
+	type WorkflowConnectionDeclarations,
+	type WorkflowConnectionRequirement,
+	type WorkflowConnections,
+	type OAuthConfiguration,
+	type OAuthConnection,
+} from "./connections.js";
 
 /**
  * Configuration passed to {@link workflow}.
  */
 export type WorkflowConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
-	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
+	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
 > = {
 	/**
 	 * A human-readable name for the workflow, shown in the UI when viewing workflows
@@ -75,7 +124,7 @@ export type WorkflowConfiguration<
 /** Configuration that checks trigger keys against declared connections. */
 export type WorkflowTriggerConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
-	TConnections extends readonly WorkflowConnection[],
+	TConnections extends WorkflowConnectionDeclarations,
 > = Omit<WorkflowConfiguration<TTriggers, TConnections>, "triggers"> & {
 	triggers: (context: { triggers: WorkflowTriggerCreators<NoInfer<TConnections>> }) => TTriggers;
 };
@@ -97,12 +146,12 @@ export type Workflow<
 		name: string;
 		description: string;
 		triggers: TTriggers;
-		connections?: readonly WorkflowConnection[];
+		connections?: readonly WorkflowConnectionRequirement[];
 	};
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
 		options?: HandlerOptions,
-	) => Promise<{ status: "success" } | undefined>;
+	) => Promise<WorkflowHandlerResult | undefined>;
 };
 
 /**
@@ -136,26 +185,30 @@ export function workflow<
 		WorkflowTriggerForConnections<NoInfer<TConnections>>,
 		...WorkflowTriggerForConnections<NoInfer<TConnections>>[],
 	],
-	const TConnections extends readonly WorkflowConnection[] = readonly [],
+	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
 >(configuration: WorkflowTriggerConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
-	const TConnections extends readonly WorkflowConnection[] = readonly [],
+	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
 >(configuration: WorkflowConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
-	const TConnections extends readonly WorkflowConnection[] = readonly [],
+	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
 >(
 	configuration:
 		| WorkflowConfiguration<TTriggers, TConnections>
 		| WorkflowTriggerConfiguration<TTriggers, TConnections>,
 ): Workflow<TTriggers> {
+	const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
+	const connectionDeclarations =
+		configuration.connections === undefined
+			? undefined
+			: structuredClone(configuration.connections);
 	const triggers =
 		typeof configuration.triggers === "function"
 			? configuration.triggers({ triggers: createWorkflowTriggers<TConnections>() })
 			: configuration.triggers;
-	validateConnectionRequirements(configuration.connections ?? []);
-	validateTriggerConnections(triggers, configuration.connections ?? []);
+	validateTriggerConnections(triggers, requirements);
 
 	return {
 		_tag: "workflow",
@@ -163,23 +216,26 @@ export function workflow<
 			name: configuration.name,
 			description: configuration.description,
 			triggers,
-			...(configuration.connections === undefined
-				? {}
-				: { connections: configuration.connections }),
+			...(configuration.connections === undefined ? {} : { connections: requirements }),
 		},
 		async handler(
 			event: WorkflowEventForTriggers<TTriggers>,
 			options?: HandlerOptions,
-		): Promise<{ status: "success" } | undefined> {
+		): Promise<WorkflowHandlerResult | undefined> {
 			try {
 				event = await resolveRuntimeInput(event);
 				const runMetadata = readRunMetadata();
 				const baseContext = createCapabilityContext();
-				const capabilityContext: WorkflowContext = {
+				const step = createStep(runMetadata);
+				const capabilityContext: WorkflowContext<TConnections> = {
 					...baseContext,
-					connections: createWorkflowConnections(baseContext.notion),
+					connections: createWorkflowConnections(
+						baseContext.notion,
+						connectionDeclarations,
+					),
 					...runMetadata,
-					step: createStep(runMetadata),
+					step,
+					wait: createWait(step),
 				};
 				await configuration.handler(event, capabilityContext);
 
@@ -189,6 +245,18 @@ export function workflow<
 
 				writeOutput({ _tag: "success", value: { status: "success" } });
 			} catch (err) {
+				if (err instanceof WorkflowWaitInterrupt) {
+					if (options?.concreteOutput) {
+						return err.result;
+					}
+
+					writeOutput({
+						_tag: "wait",
+						wait: err.result.wait,
+					});
+					return;
+				}
+
 				const error = new ExecutionError(err);
 
 				if (!options?.concreteOutput) {
@@ -215,6 +283,13 @@ export type StepContext = {
 	 * Use this to make side effects idempotent when the workflow is retried.
 	 */
 	id: string;
+	/**
+	 * Durable key-value state shared by every run of this workflow.
+	 *
+	 * State is exposed on the step context because every operation participates
+	 * in the active step's durability and replay boundary.
+	 */
+	state: WorkflowState;
 };
 
 type WorkflowStepResult<T> = T extends void ? null : T;
@@ -238,9 +313,17 @@ type WorkflowStep = {
 	): Promise<WorkflowStepResult<T>>;
 };
 
+type WorkflowWait = {
+	/**
+	 * Suspend the workflow until a relative duration has elapsed or an absolute
+	 * date has been reached.
+	 */
+	until(name: string, options: WorkflowWaitUntilOptions): Promise<void>;
+};
+
 /** Context passed to a workflow handler. */
 export type WorkflowContext<
-	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
+	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
 > = CapabilityContext & {
 	connections: WorkflowConnections<TConnections>;
 } & RunMetadata & {
@@ -265,6 +348,8 @@ export type WorkflowContext<
 		 * ```
 		 */
 		step: WorkflowStep;
+		/** Suspend this workflow without consuming compute resources. */
+		wait: WorkflowWait;
 	};
 
 type StepCompletionType = "success" | "failure";
@@ -300,7 +385,10 @@ function writeStepEvent(
 	);
 }
 
-function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowContext["step"] {
+function createStep(
+	metadata: Pick<RunMetadata, "runGroupId" | "workerId">,
+): WorkflowContext["step"] {
+	const { runGroupId } = metadata;
 	const stepNameByKey = new Map<string, string>();
 
 	async function step<T>(
@@ -324,7 +412,9 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 		}
 		stepNameByKey.set(key, name);
 
-		const context: StepContext = { id: `${runGroupId}:${key}` };
+		const id = `${runGroupId}:${key}`;
+		const stepState = createWorkflowStepState(metadata, id);
+		const context: StepContext = { id, state: stepState.state };
 		const event = { id: context.id, name, key };
 		const startedAt = performance.now();
 
@@ -353,7 +443,7 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 				return checkpoint.value as WorkflowStepResult<T>;
 			}
 
-			const value = normalizeWorkflowStepResult(await fn(context));
+			const value = normalizeWorkflowStepResult(await stepState.run(() => fn(context)));
 			writeStepEvent("success", { ...event, value }, startedAt);
 			writeStepEvent(
 				"completed",
@@ -393,6 +483,104 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 	return step;
 }
 
+class WorkflowWaitInterrupt extends Error {
+	constructor(readonly result: WorkflowWaitUntilResult) {
+		super(`Workflow is waiting until ${new Date(result.wait.resumeAtMs).toISOString()}`);
+		this.name = "WorkflowWaitInterrupt";
+	}
+}
+
+function createWait(step: WorkflowStep): WorkflowWait {
+	return {
+		async until(name, options) {
+			const keyInput = options.key ?? name;
+			const keySegments = [
+				"wait",
+				"until",
+				...(typeof keyInput === "string" ? [keyInput] : keyInput),
+			];
+			const resumeAtMs = await step(name, { key: keySegments }, () =>
+				resolveWaitUntilMs(options),
+			);
+
+			if (Date.now() >= resumeAtMs) {
+				return;
+			}
+
+			throw new WorkflowWaitInterrupt({
+				status: "waiting",
+				wait: {
+					type: "until",
+					name,
+					resumeAtMs,
+				},
+			});
+		},
+	};
+}
+
+function resolveWaitUntilMs(options: WorkflowWaitUntilOptions): number {
+	const now = Date.now();
+	if ("at" in options) {
+		const resumeAtMs = options.at.getTime();
+		if (!Number.isFinite(resumeAtMs)) {
+			throw new Error("Workflow wait date must be valid.");
+		}
+		assertWaitFitsCheckpointRetention(resumeAtMs - now);
+		return resumeAtMs;
+	}
+
+	const durationMs = workflowWaitDurationMs(options.after);
+	assertWaitFitsCheckpointRetention(durationMs);
+	return now + durationMs;
+}
+
+function workflowWaitDurationMs(duration: WorkflowWaitDuration): number {
+	const entries = Object.entries(duration);
+	if (entries.length === 0) {
+		throw new Error("Workflow wait duration must specify at least one unit.");
+	}
+
+	let durationMs = 0;
+	for (const [unit, value] of entries) {
+		if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+			throw new Error("Workflow wait duration values must be positive finite integers.");
+		}
+
+		durationMs += value * waitDurationUnitMultiplier(unit);
+		if (!Number.isSafeInteger(durationMs)) {
+			throw new Error("Workflow wait duration is too large.");
+		}
+	}
+
+	return durationMs;
+}
+
+function assertWaitFitsCheckpointRetention(durationMs: number): void {
+	if (durationMs >= MAX_WORKFLOW_WAIT_MS) {
+		throw new Error("Workflow waits must be shorter than 7 days.");
+	}
+}
+
+function waitDurationUnitMultiplier(unit: string): number {
+	switch (unit) {
+		case "milliseconds":
+			return 1;
+		case "seconds":
+			return 1_000;
+		case "minutes":
+			return 60_000;
+		case "hours":
+			return 3_600_000;
+		case "days":
+			return 86_400_000;
+		case "weeks":
+			return 604_800_000;
+		default:
+			throw new Error(`Unsupported workflow wait duration unit: ${unit}`);
+	}
+}
+
 function createWorkflowStepKey(segments: readonly unknown[]): string {
 	if (segments.length === 0) {
 		throw new Error("Workflow step keys must contain at least one segment.");