@notionhq/apps 0.0.17 → 0.0.19

package/src/workflow-access.ts

@@ -0,0 +1,299 @@
+import type { CustomAgentHandle } from "./notion-as-code/custom-agent.js";
+import type {
+	DataSourceHandle,
+	DatabaseHandle,
+	SingleSourceDatabaseHandle,
+} from "./notion-as-code/database.js";
+import type { PageHandle } from "./notion-as-code/page.js";
+
+/** A Notion-as-Code resource that can provide a named workflow binding. */
+export type WorkflowAccessResource =
+	| PageHandle
+	| DatabaseHandle
+	| SingleSourceDatabaseHandle
+	| DataSourceHandle
+	| CustomAgentHandle;
+
+/** Resource kinds accepted by workflow access declarations. */
+export type WorkflowAccessResourceType = WorkflowAccessResource["resourceType"];
+
+/** Levels accepted by pages, databases, and data sources. */
+export type WorkflowAccessResourceLevel = "view" | "comment" | "edit" | "fullAccess";
+
+/** The only level accepted by a custom agent. */
+export type WorkflowAccessAgentLevel = "call";
+
+/** Every level accepted by at least one workflow access resource. */
+export type WorkflowAccessLevel = WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+
+/** The level set accepted by a particular resource kind. */
+export type WorkflowAccessLevelFor<TType extends WorkflowAccessResourceType> =
+	TType extends "customAgent" ? WorkflowAccessAgentLevel : WorkflowAccessResourceLevel;
+
+type AccessResourceFor<TType extends WorkflowAccessResourceType> = Extract<
+	WorkflowAccessResource,
+	{ resourceType: TType }
+>;
+
+/** A named binding declaration pairing one NaC handle with its allowed level. */
+export type WorkflowAccessDeclaration = {
+	[TType in WorkflowAccessResourceType]: {
+		readonly resource: AccessResourceFor<TType>;
+		readonly level: WorkflowAccessLevelFor<TType>;
+	};
+}[WorkflowAccessResourceType];
+
+/** Named binding declarations keyed by the names exposed on workflow context. */
+export type WorkflowAccessDeclarations = Readonly<Record<string, WorkflowAccessDeclaration>>;
+
+/** A normalized named-binding requirement, including the required NaC resourceId. */
+export type WorkflowAccessRequirement = {
+	[TType in WorkflowAccessResourceType]: {
+		readonly type: TType;
+		readonly resourceId: string;
+		readonly level: WorkflowAccessLevelFor<TType>;
+	};
+}[WorkflowAccessResourceType];
+
+/** Normalized named-binding requirements keyed by public alias. */
+export type WorkflowAccessRequirements = Readonly<Record<string, WorkflowAccessRequirement>>;
+
+/** The resolved NaC binding exposed to a workflow handler. */
+export type WorkflowAccessValue<
+	TType extends WorkflowAccessResourceType = WorkflowAccessResourceType,
+> = Readonly<{
+	type: TType;
+	id: string;
+}>;
+
+/** Resolved access values keyed by their public aliases. */
+export type WorkflowAccess<
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
+> = Readonly<{
+	[TKey in keyof TAccess]: TAccess[TKey] extends {
+		readonly resource: { readonly resourceType: infer TType };
+	}
+		? TType extends WorkflowAccessResourceType
+			? WorkflowAccessValue<TType>
+			: never
+		: never;
+}>;
+
+/** Resolved NaC bindings keyed by public aliases, without declaration metadata. */
+export type WorkflowAccessBindings = Readonly<Record<string, WorkflowAccessValue>>;
+
+const ACCESS_ALIAS_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/;
+const RESERVED_ACCESS_ALIASES = new Set<string>(["__proto__", "prototype", "constructor"]);
+const RESOURCE_TYPES: Record<WorkflowAccessResourceType, true> = {
+	page: true,
+	database: true,
+	dataSource: true,
+	customAgent: true,
+};
+
+/**
+ * Normalize public binding declarations without retaining the handle objects.
+ * Handles contain methods and schema objects, so they must never be cloned into
+ * the manifest or captured by the runtime transport. These declarations do not
+ * grant or change the workflow's existing Notion-module permissions.
+ */
+export function normalizeWorkflowAccess(
+	declarations: WorkflowAccessDeclarations | undefined,
+): WorkflowAccessRequirements {
+	const source = declarations ?? {};
+	assertPlainObject(source, "Workflow access must be an object keyed by alias.");
+	const keys = Object.keys(source);
+	if (Reflect.ownKeys(source).length !== keys.length) {
+		throw new Error("Workflow access aliases must be enumerable strings.");
+	}
+	if (keys.length > 100) {
+		throw new Error("Workflows support at most 100 access requirements.");
+	}
+
+	const normalized: Record<string, WorkflowAccessRequirement> = Object.create(null) as Record<
+		string,
+		WorkflowAccessRequirement
+	>;
+	for (const alias of keys) {
+		if (!ACCESS_ALIAS_PATTERN.test(alias) || RESERVED_ACCESS_ALIASES.has(alias)) {
+			throw new Error(`Invalid workflow access alias: ${alias}`);
+		}
+
+		const declaration: unknown = source[alias];
+		if (
+			!isRecord(declaration) ||
+			!Object.hasOwn(declaration, "resource") ||
+			!Object.hasOwn(declaration, "level")
+		) {
+			throw new Error(`Workflow access "${alias}" must declare a resource and level.`);
+		}
+		const resource: unknown = declaration.resource;
+		if (
+			!isRecord(resource) ||
+			!Object.hasOwn(resource, "resourceType") ||
+			!Object.hasOwn(resource, "resourceId") ||
+			typeof resource.resourceId !== "string" ||
+			resource.resourceId.length === 0 ||
+			!isWorkflowAccessResourceType(resource.resourceType)
+		) {
+			throw new Error(
+				`Workflow access "${alias}" must reference a supported NaC resource handle.`,
+			);
+		}
+
+		let requirement: WorkflowAccessRequirement;
+		if (resource.resourceType === "customAgent") {
+			if (declaration.level !== "call") {
+				throw new Error(
+					`Workflow access "${alias}" custom agents only support level "call".`,
+				);
+			}
+			requirement = {
+				type: resource.resourceType,
+				resourceId: resource.resourceId,
+				level: declaration.level,
+			};
+		} else {
+			if (!isWorkflowAccessResourceLevel(declaration.level)) {
+				throw new Error(
+					`Workflow access "${alias}" ${resource.resourceType} level must be view, comment, edit, or fullAccess.`,
+				);
+			}
+			requirement = {
+				type: resource.resourceType,
+				resourceId: resource.resourceId,
+				level: declaration.level,
+			};
+		}
+		normalized[alias] = Object.freeze(requirement);
+	}
+
+	return Object.freeze(normalized);
+}
+
+/**
+ * Resolve trusted per-invocation NaC bindings into the minimal context value.
+ * This exposes only declared aliases and does not determine Notion API
+ * authorization; the workflow's existing Notion-module permissions do that.
+ * The environment is deliberately not parsed when no binding is required.
+ */
+export function hydrateWorkflowAccess<TAccess extends WorkflowAccessDeclarations>(
+	requirements: WorkflowAccessRequirements | undefined,
+): WorkflowAccess<TAccess>;
+export function hydrateWorkflowAccess(
+	requirements: WorkflowAccessRequirements | undefined,
+): WorkflowAccessBindings {
+	const expected = requirements ?? {};
+	const aliases = Object.keys(expected);
+	const empty: Record<string, WorkflowAccessValue> = Object.create(null) as Record<
+		string,
+		WorkflowAccessValue
+	>;
+	if (aliases.length === 0) {
+		return Object.freeze(empty);
+	}
+
+	const rawBindings = process.env.NOTION_ACCESS_BINDINGS;
+	if (rawBindings === undefined) {
+		throw new Error(
+			"Workflow access requirements are not bound. Deploy and configure this requirement before running it.",
+		);
+	}
+	if (rawBindings.length === 0) {
+		throw new Error("Invalid NOTION_ACCESS_BINDINGS metadata.");
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawBindings);
+	} catch (error) {
+		throw new Error("Invalid NOTION_ACCESS_BINDINGS metadata.", { cause: error });
+	}
+	assertPlainObject(parsed, "Invalid NOTION_ACCESS_BINDINGS metadata.");
+	const bindingKeys = Object.keys(parsed);
+	if (
+		Reflect.ownKeys(parsed).length !== bindingKeys.length ||
+		bindingKeys.length !== aliases.length ||
+		bindingKeys.some((alias) => !Object.hasOwn(expected, alias))
+	) {
+		throw new Error(
+			"Invalid NOTION_ACCESS_BINDINGS metadata: aliases do not match workflow access.",
+		);
+	}
+
+	const resolved: Record<string, WorkflowAccessValue> = Object.create(null) as Record<
+		string,
+		WorkflowAccessValue
+	>;
+	for (const alias of aliases) {
+		const requirement = expected[alias];
+		if (!requirement) {
+			throw new Error(`Workflow access "${alias}" is not declared.`);
+		}
+		const binding: unknown = parsed[alias];
+		if (!isBinding(binding)) {
+			throw new Error(`Invalid NOTION_ACCESS_BINDINGS metadata for access "${alias}".`);
+		}
+		if (
+			binding.type !== requirement.type ||
+			binding.resourceId !== requirement.resourceId ||
+			binding.level !== requirement.level
+		) {
+			throw new Error(
+				`Workflow access "${alias}" binding does not match its declared type, resourceId, or level.`,
+			);
+		}
+		resolved[alias] = Object.freeze({ type: binding.type, id: binding.id });
+	}
+
+	return Object.freeze(resolved);
+}
+
+function isWorkflowAccessResourceType(value: unknown): value is WorkflowAccessResourceType {
+	return typeof value === "string" && Object.hasOwn(RESOURCE_TYPES, value);
+}
+
+function isWorkflowAccessResourceLevel(value: unknown): value is WorkflowAccessResourceLevel {
+	return value === "view" || value === "comment" || value === "edit" || value === "fullAccess";
+}
+
+function isBinding(value: unknown): value is {
+	type: WorkflowAccessResourceType;
+	resourceId: string;
+	level: WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+	id: string;
+} {
+	if (!isRecord(value) || Reflect.ownKeys(value).length !== 4) return false;
+	const keys = Object.keys(value);
+	if (
+		keys.length !== 4 ||
+		!keys.includes("type") ||
+		!keys.includes("resourceId") ||
+		!keys.includes("level") ||
+		!keys.includes("id")
+	) {
+		return false;
+	}
+	return (
+		isWorkflowAccessResourceType(value.type) &&
+		typeof value.resourceId === "string" &&
+		value.resourceId.length > 0 &&
+		typeof value.level === "string" &&
+		(isWorkflowAccessResourceLevel(value.level) || value.level === "call") &&
+		typeof value.id === "string" &&
+		value.id.length > 0
+	);
+}
+
+function assertPlainObject(
+	value: unknown,
+	message: string,
+): asserts value is Record<string, unknown> {
+	if (!isRecord(value)) throw new Error(message);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error(message);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/workflow-state.ts

@@ -0,0 +1,152 @@
+import type { RunMetadata } from "./runtime-metadata.js";
+
+export type WorkflowStateValue =
+	| null
+	| boolean
+	| number
+	| string
+	| ReadonlyArray<WorkflowStateValue>
+	| { readonly [key: string]: WorkflowStateValue };
+
+export type WorkflowState = {
+	get(key: string): Promise<WorkflowStateValue | undefined>;
+	set(key: string, value: WorkflowStateValue | undefined): void;
+};
+
+type WorkflowStateMutation =
+	| { operation: "set"; key: string; value: WorkflowStateValue }
+	| { operation: "delete"; key: string };
+
+type WorkflowStepScope = {
+	id: string;
+	active: boolean;
+	mutations: Map<string, WorkflowStateMutation>;
+};
+
+const MAX_STATE_KEY_BYTES = 256;
+const WORKFLOW_CAPABILITY_KEY_ENV = "NOTION_WORKFLOW_CAPABILITY_KEY";
+
+export function createWorkflowStepState(
+	metadata: Pick<RunMetadata, "workerId">,
+	stepId: string,
+): {
+	state: WorkflowState;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+} {
+	const scope: WorkflowStepScope = {
+		id: stepId,
+		active: true,
+		mutations: new Map(),
+	};
+	const state: WorkflowState = {
+		async get(key: string): Promise<WorkflowStateValue | undefined> {
+			requireActiveStep(scope, "get");
+			validateStateKey(key);
+			const pending = scope.mutations.get(key);
+			if (pending?.operation === "set") {
+				return pending.value;
+			}
+			if (pending?.operation === "delete") {
+				return undefined;
+			}
+
+			const response = await requestWorkflowState(metadata, {
+				operation: "get",
+				key,
+			});
+			const body: { exists: boolean; value?: WorkflowStateValue } = JSON.parse(
+				await response.text(),
+			);
+			if (!body.exists) {
+				return undefined;
+			}
+			return body.value;
+		},
+		set(key: string, value: WorkflowStateValue | undefined): void {
+			requireActiveStep(scope, "set");
+			validateStateKey(key);
+			if (value === undefined) {
+				recordMutation(scope, { operation: "delete", key });
+				return;
+			}
+			recordMutation(scope, { operation: "set", key, value });
+		},
+	};
+
+	return {
+		state,
+		async run<T>(fn: () => T | Promise<T>): Promise<T> {
+			try {
+				const result = await fn();
+				if (scope.mutations.size > 0) {
+					await requestWorkflowState(metadata, {
+						operation: "commit",
+						operationId: scope.id,
+						mutations: [...scope.mutations.values()],
+					});
+				}
+				return result;
+			} finally {
+				scope.active = false;
+			}
+		},
+	};
+}
+
+function requireActiveStep(expectedScope: WorkflowStepScope, operation: keyof WorkflowState): void {
+	if (!expectedScope.active) {
+		throw new Error(`state.${operation}() must be called inside context.step().`);
+	}
+}
+
+function recordMutation(scope: WorkflowStepScope, mutation: WorkflowStateMutation): void {
+	scope.mutations.set(mutation.key, mutation);
+}
+
+async function requestWorkflowState(
+	metadata: Pick<RunMetadata, "workerId">,
+	request:
+		| { operation: "get"; key: string }
+		| {
+				operation: "commit";
+				operationId: string;
+				mutations: WorkflowStateMutation[];
+		  },
+): Promise<Response> {
+	const baseUrl = process.env.NOTION_API_BASE_URL;
+	const token = process.env.NOTION_API_TOKEN;
+	const capabilityKey = process.env[WORKFLOW_CAPABILITY_KEY_ENV];
+	if (!baseUrl || !token || !capabilityKey) {
+		throw new Error(
+			`Workflow state is only available when the workflow runtime provides NOTION_API_BASE_URL, NOTION_API_TOKEN, and ${WORKFLOW_CAPABILITY_KEY_ENV}.`,
+		);
+	}
+
+	const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v3/workersWorkflowState`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json",
+		},
+		body: JSON.stringify({
+			...request,
+			workerId: metadata.workerId,
+			capabilityKey,
+		}),
+	});
+	if (!response.ok) {
+		throw new Error(
+			`Workflow state ${request.operation} failed with status ${response.status}.`,
+		);
+	}
+	return response;
+}
+
+function validateStateKey(key: string): void {
+	if (key.length === 0) {
+		throw new Error("Workflow state keys must not be empty.");
+	}
+	if (Buffer.byteLength(key) > MAX_STATE_KEY_BYTES) {
+		throw new Error(`Workflow state keys must be at most ${MAX_STATE_KEY_BYTES} UTF-8 bytes.`);
+	}
+}