@notionhq/apps 0.0.18 → 0.0.20

package/src/cli/emit-manifest.ts

@@ -217,6 +217,7 @@ export async function extractManifest(
 	bundlePath: string,
 	capabilities: readonly DiscoveredCapability[],
 	blockConfigs: Record<string, unknown> = {},
+	provisioning?: RecordedProvisioning,
 ): Promise<AppManifest> {
 	clearRegisteredPacers();
 	const bundle = await importBundle(bundlePath);
@@ -267,8 +268,12 @@ export async function extractManifest(
 			const { database: _database, ...rest } = config;
 			config = { ...rest, databaseKey };
 		}
+		if (capability.type === "workflow") {
+			validateWorkflowAccessReferences(config.access, provisioning, capability.sourcePath);
+		}
 
 		assertJsonSafe(config, `${capability.sourcePath} config`);
+
 		return { type: capability.type, key: capability.key, config };
 	});
 
@@ -300,6 +305,108 @@ export async function extractManifest(
 	return manifest as AppManifest;
 }
 
+const WORKFLOW_ACCESS_TYPES: Record<string, true> = {
+	page: true,
+	database: true,
+	dataSource: true,
+	customAgent: true,
+};
+const WORKFLOW_ACCESS_LEVELS: Record<string, true> = {
+	view: true,
+	comment: true,
+	edit: true,
+	fullAccess: true,
+};
+
+function validateWorkflowAccessReferences(
+	access: unknown,
+	provisioning: RecordedProvisioning | undefined,
+	capabilityPath: string,
+): void {
+	if (access === undefined) return;
+	if (
+		typeof access !== "object" ||
+		access === null ||
+		Array.isArray(access) ||
+		(provisioning === undefined && Object.keys(access).length > 0)
+	) {
+		throw new Error(
+			`${capabilityPath}: workflow access must reference resources recorded by the current build`,
+		);
+	}
+	if (provisioning === undefined) {
+		return;
+	}
+
+	const accessObject = access as Record<string, unknown>;
+	const aliases = Object.keys(accessObject);
+	if (Reflect.ownKeys(accessObject).length !== aliases.length) {
+		throw new Error(`${capabilityPath}: workflow access aliases must be enumerable strings`);
+	}
+	for (const alias of aliases) {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(alias) ||
+			alias === "__proto__" ||
+			alias === "prototype" ||
+			alias === "constructor"
+		) {
+			throw new Error(`${capabilityPath}: invalid workflow access alias "${alias}"`);
+		}
+		const requirement = accessObject[alias];
+		if (
+			typeof requirement !== "object" ||
+			requirement === null ||
+			Array.isArray(requirement) ||
+			Reflect.ownKeys(requirement).length !== 3 ||
+			!Object.hasOwn(requirement, "type") ||
+			!Object.hasOwn(requirement, "resourceId") ||
+			!Object.hasOwn(requirement, "level")
+		) {
+			throw new Error(`${capabilityPath}: invalid workflow access requirement "${alias}"`);
+		}
+		const requirementObject = requirement as Record<string, unknown>;
+		const type = requirementObject.type;
+		const resourceId = requirementObject.resourceId;
+		const level = requirementObject.level;
+		if (
+			typeof type !== "string" ||
+			!Object.hasOwn(WORKFLOW_ACCESS_TYPES, type) ||
+			typeof resourceId !== "string" ||
+			resourceId.length === 0 ||
+			typeof level !== "string" ||
+			(type === "customAgent"
+				? level !== "call"
+				: !Object.hasOwn(WORKFLOW_ACCESS_LEVELS, level))
+		) {
+			throw new Error(`${capabilityPath}: invalid workflow access requirement "${alias}"`);
+		}
+
+		if (
+			!provisioning.intents.some((intent) => {
+				switch (type) {
+					case "page":
+						return intent.type === "page" && intent.resourceId === resourceId;
+					case "database":
+						return intent.type === "database" && intent.resourceId === resourceId;
+					case "customAgent":
+						return intent.type === "custom_agent" && intent.resourceId === resourceId;
+					case "dataSource":
+						return (
+							intent.type === "database" &&
+							(intent.dataSources ?? []).some(
+								(dataSource) => dataSource.resourceId === resourceId,
+							)
+						);
+				}
+			})
+		) {
+			throw new Error(
+				`${capabilityPath}: workflow access "${alias}" references ${type} "${resourceId}" that is not declared by the current build`,
+			);
+		}
+	}
+}
+
 /** Import the metadata bundle and return the provisioning declarations it recorded. */
 export async function extractProvisioning(bundlePath: string): Promise<RecordedProvisioning> {
 	const bundle = await importBundle(bundlePath);

package/src/index.ts

@@ -5,5 +5,24 @@ export { page } from "./notion-as-code/page.js";
 export { teamspace } from "./notion-as-code/teamspace.js";
 export { view } from "./notion-as-code/view.js";
 export { sync } from "./sync.js";
-export { workflow } from "./workflow.js";
+export {
+	workflow,
+	type Workflow,
+	type WorkflowAccess,
+	type WorkflowAccessAgentLevel,
+	type WorkflowAccessBindings,
+	type WorkflowAccessDeclaration,
+	type WorkflowAccessDeclarations,
+	type WorkflowAccessLevel,
+	type WorkflowAccessLevelFor,
+	type WorkflowAccessResource,
+	type WorkflowAccessResourceLevel,
+	type WorkflowAccessResourceType,
+	type WorkflowAccessRequirement,
+	type WorkflowAccessRequirements,
+	type WorkflowAccessValue,
+	type WorkflowConfiguration,
+	type WorkflowContext,
+	type WorkflowTriggerConfiguration,
+} from "./workflow.js";
 export type { WorkflowState, WorkflowStateValue } from "./workflow-state.js";

package/src/notion-as-code/custom-agent.ts

@@ -14,6 +14,7 @@ export type CustomAgentArgs = {
 };
 
 export type CustomAgentHandle = {
+	readonly resourceType: "customAgent";
 	readonly resourceId: string;
 };
 
@@ -26,5 +27,5 @@ export function customAgent(args: CustomAgentArgs): CustomAgentHandle {
 	recordIntent({ type: "custom_agent", ...args } satisfies {
 		type: "custom_agent";
 	} & CustomAgentIntent);
-	return { resourceId: args.resourceId };
+	return { resourceType: "customAgent", resourceId: args.resourceId };
 }

package/src/notion-as-code/database.ts

@@ -113,6 +113,7 @@ export type ChildDatabaseArgs<
 
 /** A source handle retains its keyed authoring schema for sync inference. */
 export type DataSourceHandle<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	readonly resourceType: "dataSource";
 	readonly resourceId: string;
 	readonly schema: Schema;
 	readonly database: Database<AppsSchemaForSchema<Schema>>;
@@ -120,6 +121,7 @@ export type DataSourceHandle<Schema extends NotionAsCodeSchema = NotionAsCodeSch
 };
 
 type DatabaseHandleBase = {
+	readonly resourceType: "database";
 	readonly resourceId: string;
 	addView: (view: ViewSchema) => void;
 };
@@ -262,6 +264,7 @@ function buildDatabaseHandle(
 			throw new Error(`Database "${databaseResourceId}" is missing its data source`);
 		}
 		return {
+			resourceType: "database",
 			resourceId: databaseResourceId,
 			dataSource,
 			addView: handle.addView,
@@ -396,6 +399,7 @@ function createDatabase(
 	recordIntent({ ...intent, type: "database" });
 
 	return {
+		resourceType: "database",
 		resourceId: intent.resourceId,
 		datasources: handles,
 		addView(view) {
@@ -428,6 +432,7 @@ function createDataSourceHandle(
 	}
 
 	return {
+		resourceType: "dataSource",
 		resourceId: dataSource.resourceId,
 		schema,
 		database: createAppsDatabase(dataSource.resourceId, dataSource),

package/src/notion-as-code/date.ts

@@ -1,5 +1,7 @@
+import type { TextValue } from "./page.js";
+
 /** Serialize Notion-as-Code date values for Apps property payloads. */
-export function date(startDate: string, endDate?: string): unknown[][] {
+export function date(startDate: string, endDate?: string): TextValue {
 	const start_date = parseIsoDate(startDate);
 	const end_date = endDate === undefined ? undefined : parseIsoDate(endDate);
 	if (end_date !== undefined && end_date < start_date) {
@@ -13,7 +15,7 @@ export function date(startDate: string, endDate?: string): unknown[][] {
 }
 
 /** Serialize Notion-as-Code datetime values for Apps property payloads. */
-export function datetime(value: { start: string; end?: string; timeZone?: string }): unknown[][] {
+export function datetime(value: { start: string; end?: string; timeZone?: string }): TextValue {
 	const timeZone = value.timeZone ?? "UTC";
 	try {
 		new Intl.DateTimeFormat("en-US", { timeZone }).format();

package/src/notion-as-code/handles.ts

@@ -1,8 +1,12 @@
 import { customAgent } from "./custom-agent.js";
 import { database } from "./database.js";
 import { date, datetime } from "./date.js";
-import { page } from "./page.js";
-import { assertUserResourceId } from "./resource.js";
+import {
+	page,
+	type TextValue,
+	type VerificationInput,
+	type VerificationPropertyValue,
+} from "./page.js";
 import { teamspace } from "./teamspace.js";
 import { view } from "./view.js";
 
@@ -12,22 +16,22 @@ const notionAsCodeFacade = {
 	page,
 	customAgent,
 	view,
-	text: (value: string) => [[value]],
-	number: (value: number) => [[String(value)]],
+	text: (value: string): TextValue => [[value]],
+	number: (value: number): TextValue => [[String(value)]],
 	date,
 	datetime,
+	verification: (value: VerificationInput): VerificationPropertyValue => ({
+		...value,
+		type: "verification",
+	}),
 	select: (value: string) => value,
 	status: (value: string) => value,
 	multiSelect: (values: readonly string[]) => values.join(","),
-	checkbox: (value: boolean) => [[value ? "Yes" : "No"]],
-	url: (value: string) => [[value, [["a", value]]]],
-	email: (value: string) => [[value, [["a", `mailto:${value}`]]]],
-	phone: (value: string) => [[value]],
+	checkbox: (value: boolean): TextValue => [[value ? "Yes" : "No"]],
+	url: (value: string): TextValue => [[value, [["a", value]]]],
+	email: (value: string): TextValue => [[value, [["a", `mailto:${value}`]]]],
+	phone: (value: string): TextValue => [[value]],
 	relation: (value: string | readonly string[]) => (Array.isArray(value) ? [...value] : value),
-	file: (resourceId: string) => {
-		assertUserResourceId(resourceId);
-		return { type: "file" as const, resourceId };
-	},
 };
 
 export type NotionAsCodeFacade = typeof notionAsCodeFacade;

package/src/notion-as-code/index.ts

@@ -28,7 +28,16 @@ export type {
 	SingleSourceDatabaseArgs,
 	SingleSourceDatabaseHandle,
 } from "./database.js";
-export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
+export type {
+	ChildPageArgs,
+	PageArgs,
+	PageHandle,
+	PropertyValue,
+	SimpleTextToken,
+	TextValue,
+	VerificationInput,
+	VerificationPropertyValue,
+} from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";
 export type { ViewArgs, ViewHandle } from "./view.js";
 export type {

package/src/notion-as-code/page.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { notion, type PageArgs, type PropertyValue } from "./index.js";
+import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
+
+describe("Notion-as-Code page declarations", () => {
+	it("records a regular page title separately from Markdown content", () => {
+		const properties = {
+			title: notion.text("Workflow guide"),
+		} satisfies Record<string, PropertyValue | undefined>;
+		const recorder = startMetadataRecording();
+
+		notion.page({
+			resourceId: "workflow-guide",
+			properties,
+			content: "# Body heading",
+		});
+
+		expectTypeOf<PageArgs["properties"]>().toEqualTypeOf<
+			Record<string, PropertyValue | undefined> | undefined
+		>();
+		expect(finishMetadataRecording(recorder).intents).toEqual([
+			{
+				type: "page",
+				resourceId: "workflow-guide",
+				parent: {
+					type: "resourceId",
+					resourceId: "__notion_apps_workspace__",
+				},
+				properties: { title: [["Workflow guide"]] },
+				content: "# Body heading",
+			},
+		]);
+	});
+});

package/src/notion-as-code/page.ts

@@ -8,14 +8,72 @@ import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 
+/**
+ * A single text token: plain text as `[string]`, or text with annotations as
+ * `[string, ...annotations]`.
+ */
+export type SimpleTextToken = [string] | [string, ...unknown[]];
+
+/**
+ * The JSON-serializable text format returned by Notion-as-Code text helpers.
+ */
+export type TextValue = SimpleTextToken[];
+
+export type VerificationInput =
+	| {
+			state: "verified";
+			/** Set an expiration with `notion.datetime(...)`; omit it for indefinite verification. */
+			datetime?: TextValue;
+	  }
+	| { state: "unverified" };
+
+export type VerificationPropertyValue = VerificationInput & {
+	type: "verification";
+};
+
+/**
+ * A page property value accepted by Notion as Code.
+ *
+ * Use helpers from `@notionhq/apps/notion-as-code` to construct rich values
+ * such as text, dates, checkboxes, and URLs.
+ */
+export type PropertyValue =
+	| string
+	| number
+	| TextValue
+	| string[]
+	| VerificationPropertyValue
+	| undefined;
+
+/**
+ * Arguments for declaring a page.
+ *
+ * For a regular page, set its title through
+ * `properties.title: notion.text("My Page Title")`. For a database page, use
+ * the title property's schema name instead of `title`.
+ */
 export type PageArgs = {
 	resourceId: ResourceId;
 	/** Omit to create a private top-level page in the Apps workspace. */
 	parent?: Parent;
 	// TODO: Port cover types.
 	cover?: unknown;
-	// TODO: Port page property types.
-	properties?: Record<string, unknown>;
+	/**
+	 * Page properties, including the page title.
+	 *
+	 * @example Regular page
+	 * properties: { title: notion.text("My Page Title") }
+	 *
+	 * @example Database page
+	 * properties: { Name: notion.text("Task Name"), Status: "In Progress" }
+	 */
+	properties?: Record<string, PropertyValue | undefined>;
+	/**
+	 * Page body in Notion-flavored Markdown.
+	 *
+	 * Markdown headings create child blocks. They do not set the page title;
+	 * set a regular page's title with `properties.title`.
+	 */
 	content?: string;
 	fullWidth?: boolean;
 };
@@ -23,6 +81,7 @@ export type PageArgs = {
 export type ChildPageArgs = Omit<PageArgs, "parent">;
 
 export type PageHandle = {
+	readonly resourceType: "page";
 	readonly resourceId: string;
 	addDatabase: ChildDatabaseFactory;
 	addPage: (args: ChildPageArgs) => PageHandle;
@@ -50,6 +109,7 @@ export function createPage(args: ChildPageArgs | PageArgs, parent: Parent): Page
 	} satisfies { type: "page" } & PageIntent);
 
 	return {
+		resourceType: "page",
 		resourceId: args.resourceId,
 		addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
 		addPage(pageArgs) {

package/src/workflow-access-types.test.ts

@@ -0,0 +1,69 @@
+import { expectTypeOf, it } from "vitest";
+
+import { customAgent } from "./notion-as-code/custom-agent.js";
+import { database } from "./notion-as-code/database.js";
+import { page } from "./notion-as-code/page.js";
+import { triggers } from "./triggers.generated.js";
+import { workflow } from "./workflow.js";
+
+it("infers access aliases and rejects resource-specific levels", () => {
+	const home = page({ resourceId: "home" });
+	const agent = customAgent({ resourceId: "agent", name: "Agent" });
+	const singleDatabase = database("single-database", {
+		dataSourceResourceId: "single-source",
+		name: "Single",
+		schema: { Title: { resourceId: "single-title", type: "title" } },
+	});
+	const multiDatabase = database("multi-database", {
+		name: "Multi",
+		datasources: {
+			Records: {
+				resourceId: "multi-source",
+				schema: { Title: { resourceId: "multi-title", type: "title" } },
+			},
+		},
+	});
+	workflow({
+		name: "Access types",
+		description: "Checks access types",
+		triggers: [triggers.notionPageCreated()],
+		access: {
+			home: { resource: home, level: "view" },
+			singleDatabase: { resource: singleDatabase, level: "edit" },
+			multiDatabase: { resource: multiDatabase, level: "view" },
+		},
+		handler: (_event, context) => {
+			expectTypeOf(context.access.home.type).toEqualTypeOf<"page">();
+			expectTypeOf(context.access.home.id).toEqualTypeOf<string>();
+			expectTypeOf(context.access.singleDatabase.type).toEqualTypeOf<"database">();
+			expectTypeOf(context.access.multiDatabase.type).toEqualTypeOf<"database">();
+			// @ts-expect-error Access aliases are limited to declarations.
+			void context.access.missing;
+			// @ts-expect-error Access values are readonly.
+			context.access.home.id = "changed";
+			// @ts-expect-error The access map is readonly.
+			context.access = {};
+		},
+	});
+
+	const invalidAccessLevels = () => {
+		workflow({
+			name: "Agent access types",
+			description: "Checks custom agent access types",
+			triggers: [triggers.notionPageCreated()],
+			// @ts-expect-error Custom agents only support the call level.
+			access: { agent: { resource: agent, level: "view" } },
+			handler: () => {},
+		});
+
+		workflow({
+			name: "Page access types",
+			description: "Checks page access types",
+			triggers: [triggers.notionPageCreated()],
+			// @ts-expect-error Pages do not support the custom-agent call level.
+			access: { home: { resource: home, level: "call" } },
+			handler: () => {},
+		});
+	};
+	void invalidAccessLevels;
+});