@notionhq/apps 0.0.17 → 0.0.19

package/src/workflow.ts

@@ -6,6 +6,13 @@ import {
 	type WorkflowConnectionRequirement,
 	type WorkflowConnections,
 } from "./connections.js";
+import {
+	hydrateWorkflowAccess,
+	normalizeWorkflowAccess,
+	type WorkflowAccess,
+	type WorkflowAccessDeclarations,
+	type WorkflowAccessRequirements,
+} from "./workflow-access.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -17,6 +24,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,
@@ -29,6 +37,60 @@ 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 {
+	WorkflowAccess,
+	WorkflowAccessAgentLevel,
+	WorkflowAccessBindings,
+	WorkflowAccessDeclaration,
+	WorkflowAccessDeclarations,
+	WorkflowAccessLevel,
+	WorkflowAccessLevelFor,
+	WorkflowAccessResource,
+	WorkflowAccessResourceLevel,
+	WorkflowAccessResourceType,
+	WorkflowAccessRequirement,
+	WorkflowAccessRequirements,
+	WorkflowAccessValue,
+} from "./workflow-access.js";
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
@@ -52,6 +114,7 @@ export {
 export type WorkflowConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
 > = {
 	/**
 	 * A human-readable name for the workflow, shown in the UI when viewing workflows
@@ -70,6 +133,13 @@ export type WorkflowConfiguration<
 	 */
 	triggers: TTriggers;
 
+	/**
+	 * Notion-as-Code resources whose access is configured during cloud deployment.
+	 * Deployment reconciles grants through the existing Notion-module permissions
+	 * and supplies named runtime bindings on `context.access`.
+	 */
+	access?: TAccess;
+
 	/**
 	 * Connections that must be set up before this workflow can run.
 	 */
@@ -77,7 +147,7 @@ export type WorkflowConfiguration<
 
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
-		context: WorkflowContext<TConnections>,
+		context: WorkflowContext<TConnections, TAccess>,
 	) => Promise<void> | void;
 };
 
@@ -85,7 +155,8 @@ export type WorkflowConfiguration<
 export type WorkflowTriggerConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	TConnections extends WorkflowConnectionDeclarations,
-> = Omit<WorkflowConfiguration<TTriggers, TConnections>, "triggers"> & {
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
+> = Omit<WorkflowConfiguration<TTriggers, TConnections, TAccess>, "triggers"> & {
 	triggers: (context: { triggers: WorkflowTriggerCreators<NoInfer<TConnections>> }) => TTriggers;
 };
 
@@ -107,11 +178,12 @@ export type Workflow<
 		description: string;
 		triggers: TTriggers;
 		connections?: readonly WorkflowConnectionRequirement[];
+		access?: WorkflowAccessRequirements;
 	};
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
 		options?: HandlerOptions,
-	) => Promise<{ status: "success" } | undefined>;
+	) => Promise<WorkflowHandlerResult | undefined>;
 };
 
 /**
@@ -146,20 +218,26 @@ export function workflow<
 		...WorkflowTriggerForConnections<NoInfer<TConnections>>[],
 	],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
->(configuration: WorkflowTriggerConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
+>(
+	configuration: WorkflowTriggerConfiguration<TTriggers, TConnections, TAccess>,
+): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
->(configuration: WorkflowConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
+>(configuration: WorkflowConfiguration<TTriggers, TConnections, TAccess>): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
 >(
 	configuration:
-		| WorkflowConfiguration<TTriggers, TConnections>
-		| WorkflowTriggerConfiguration<TTriggers, TConnections>,
+		| WorkflowConfiguration<TTriggers, TConnections, TAccess>
+		| WorkflowTriggerConfiguration<TTriggers, TConnections, TAccess>,
 ): Workflow<TTriggers> {
 	const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
+	const accessRequirements = normalizeWorkflowAccess(configuration.access);
 	const connectionDeclarations =
 		configuration.connections === undefined
 			? undefined
@@ -177,23 +255,27 @@ export function workflow<
 			description: configuration.description,
 			triggers,
 			...(configuration.connections === undefined ? {} : { connections: requirements }),
+			...(configuration.access === undefined ? {} : { access: accessRequirements }),
 		},
 		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<TConnections> = {
+				const step = createStep(runMetadata);
+				const capabilityContext: WorkflowContext<TConnections, TAccess> = {
 					...baseContext,
+					access: hydrateWorkflowAccess<TAccess>(accessRequirements),
 					connections: createWorkflowConnections(
 						baseContext.notion,
 						connectionDeclarations,
 					),
 					...runMetadata,
-					step: createStep(runMetadata),
+					step,
+					wait: createWait(step),
 				};
 				await configuration.handler(event, capabilityContext);
 
@@ -203,6 +285,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) {
@@ -229,6 +323,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;
@@ -252,10 +353,21 @@ 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 WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
 > = CapabilityContext & {
+	/** Resolved NaC bindings for this invocation; UI-granted resources are not added here. */
+	readonly access: WorkflowAccess<TAccess>;
 	connections: WorkflowConnections<TConnections>;
 } & RunMetadata & {
 		/**
@@ -279,6 +391,8 @@ export type WorkflowContext<
 		 * ```
 		 */
 		step: WorkflowStep;
+		/** Suspend this workflow without consuming compute resources. */
+		wait: WorkflowWait;
 	};
 
 type StepCompletionType = "success" | "failure";
@@ -314,7 +428,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>(
@@ -338,7 +455,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();
 
@@ -367,7 +486,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",
@@ -407,6 +526,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.");