@notionhq/apps 0.0.17 → 0.0.19

package/skills/workflow/SKILL.md

@@ -38,6 +38,53 @@ and Notion API calls, mutable state reads, timestamps, random values, generated
 IDs, messages, creates, and updates. Keep deterministic transforms of the event
 and completed step results outside a step.
 
+Workflow-level key-value state is available through the step closure's `state`.
+State is shared across runs of the same workflow and every operation executes
+inside that step's durability boundary:
+
+```ts
+await context.step("Update cursor", async ({ state }) => {
+	state.set("cursor", nextCursor);
+	const pendingCursor = await state.get("cursor"); // Reads the buffered write.
+	if (!(await saveCursor(pendingCursor))) {
+		throw new Error("Save failed"); // The state write is discarded.
+	}
+});
+```
+
+Use `get` and `set`; passing `undefined` to `set` deletes the key, while `null`
+is stored as a value. Mutations are buffered and committed atomically only
+after the step callback succeeds. Repeated mutations of one key are allowed,
+reads observe the latest buffered value, and only the final mutation is
+committed. If the callback throws, none of that step's state mutations are
+persisted.
+
+Use `context.wait.until(name, { after })` for a relative wait shorter than seven
+days, or `context.wait.until(name, { at })` for an absolute date within the next
+seven days. The runtime checkpoints the target time, releases the workflow's
+compute, and resumes it from the same point later:
+
+```ts
+await context.wait.until("Cooling-off period", {
+	after: { days: 1, hours: 6 },
+});
+await context.wait.until("Launch time", { at: launchAt });
+```
+
+Relative durations can combine `milliseconds`, `seconds`, `minutes`, `hours`,
+`days`, and `weeks`. Every specified value must be a positive finite integer.
+Repeated waits can keep one stable display name when each call has a unique
+composite `key`:
+
+```ts
+for (const page of pages) {
+	await context.wait.until("Rate limit delay", {
+		key: ["rate-limit", page.id],
+		after: { seconds: 1 },
+	});
+}
+```
+
 Completed steps replay saved results. Do not rely on in-memory mutations inside
 a step. Return the values required by later code. Keep calls in a stable order
 and give every step a stable display name. The name is the replay key by
@@ -63,12 +110,13 @@ configuration, and do not log secrets or private payloads.
 
 ## Resources created with the App
 
-Use [Notion as Code](../notion-as-code/SKILL.md) for pages and databases that
-should be created during deployment. Prefer it over equivalent manual setup
+Use [Notion as Code](../notion-as-code/SKILL.md) for pages, databases, and custom agents
+that should be created during deployment. Prefer it over equivalent manual setup
 or API calls that create the App's resources. Use runtime API calls for dynamic
 data changes, not as a substitute for supported Notion as Code setup.
-Keep declarations at module scope in
-an imported helper. For example, declare a guide page in `src/lib/resources.ts`:
+Keep declarations at module scope. A small workflow-specific resource can be
+declared inline. A larger set can live in a local module; for example, declare a
+guide page in `src/workflows/sayHello/lib/notion.ts`:
 
 ```ts
 import { page } from "@notionhq/apps";
@@ -79,31 +127,67 @@ export const guide = page({
 });
 ```
 
-Import the module from `src/workflows/sayHello.ts` so the build records it:
+Import the handle into the workflow and declare the named binding it needs:
 
 ```ts
-import "../lib/resources";
 import { workflow } from "@notionhq/apps";
 import { triggers } from "@notionhq/apps/triggers";
 
+import { guide } from "./sayHello/lib/notion.js";
+
 export default workflow({
-	name: "Say Hello",
-	description: "Says hello on a recurring schedule.",
+	name: "Read guide",
+	description: "Reads the App's guide on a recurring schedule.",
 	triggers: [triggers.scheduled()],
+	access: { guide: { resource: guide, level: "view" } },
 	handler: async (_event, context) => {
-		await context.step("Say hello", () => {
-			console.log("Hello from your workflow!");
-		});
+		await context.step("Read guide", () =>
+			context.notion.pages.retrieve({ page_id: context.access.guide.id }),
+		);
 	},
 });
 ```
 
-The page is provisioned during deployment, not on every workflow run.
-Database declarations follow the same import pattern; see the
-[sync example](../sync/SKILL.md#choose-the-database-source) for using a Notion as Code
-data source in a sync. Notion as Code resource IDs are declaration identities, not live
-Notion UUIDs to pass to `context.notion`. Runtime API calls still belong in
-durable steps and need actual resolved Notion IDs.
+The page is provisioned during deployment, not on every workflow run. Inline
+declarations in `access` work too. Importing a declaration alone provisions the
+resource but does not create a `context.access` alias. An `access` entry declares
+the needed permission level and a named binding for that NaC resource.
+
+`access` accepts page, database, data-source, and custom-agent handles. Pages,
+databases, and data sources support `view`, `comment`, `edit`, and `fullAccess`;
+custom agents support only `call`. Keys are workflow-local aliases. The handler's
+typed `context.access` exposes each declared alias as a readonly `{ type, id }`,
+not the declaration handle or a permission-management API. UI-granted resources
+are permissions only: they do not create `context.access` aliases.
+
+For a resource already granted to the workflow in Notion's UI, use its live
+record ID directly in a `context.notion` call:
+
+```ts
+await context.step("Read granted page", () =>
+	context.notion.pages.retrieve({ page_id: "page-id" }),
+);
+```
+
+Such a UI grant needs no `access` entry, NaC declaration, or NaC `resourceId`.
+The call remains subject to the workflow's existing Notion-module permissions.
+
+Use a data-source handle when calling `context.notion.dataSources`: its resolved
+ID is a collection ID. A database handle resolves to the database block ID;
+these identities are not interchangeable. Notion as Code `resourceId` values
+remain declaration identities, not live Notion UUIDs.
+
+Cloud deployment resolves declared handles to live IDs and reconciles their
+grants through the existing Notion-module permissions. It saves permissions and
+bindings together; bindings themselves do not authorize calls. Changing `access`
+updates code-managed grants and bindings while preserving manually configured
+UI grants. Normal draft/publish and runtime authorization still apply. Missing
+or mismatched required bindings fail before the handler runs.
+
+Deploy workflows with nonempty `access` using `ntn apps deploy`, without
+`--local-build`. Local-build deployment rejects them before upload. Runtime API
+calls still belong in durable steps. For syncs, see the
+[data-source example](../sync/SKILL.md#choose-the-database-source).
 
 ## Review a workflow
 

package/src/cli/build.test.ts

@@ -15,17 +15,18 @@ import { finishMetadataRecording, startMetadataRecording } from "../notion-as-co
 describe("Notion-as-Code database shorthand", () => {
 	it("keeps provisioning and sync identity equivalent to an explicit source", () => {
 		const recorder = startMetadataRecording();
-		const database = notion.database({
-			resourceId: "issues",
+		const schema = {
+			Name: { resourceId: "title", type: "title" },
+			Count: { resourceId: "count", type: "number" },
+		} as const;
+		const database = notion.database("issues", {
+			dataSourceResourceId: "issues-source",
 			name: "Issues",
-			properties: [
-				{ resourceId: "title", name: "Name", type: "title" },
-				{ resourceId: "count", name: "Count", type: "number" },
-			],
+			schema,
 		});
-		expectTypeOf(database).toExtend<
-			SingleSourceDatabaseHandle<typeof database.dataSource.schema>
-		>();
+		expectTypeOf(database).toExtend<SingleSourceDatabaseHandle<typeof schema>>();
+		expectTypeOf(database.dataSource.schema.Name.type).toEqualTypeOf<"title">();
+		expectTypeOf(database.dataSource.schema.Name.resourceId).toEqualTypeOf<"title">();
 		expectTypeOf(
 			database.dataSource.database.config.schema.Count.type,
 		).toEqualTypeOf<"number">();
@@ -33,18 +34,19 @@ describe("Notion-as-Code database shorthand", () => {
 		const shorthand = finishMetadataRecording(recorder).intents;
 
 		const explicitRecorder = startMetadataRecording();
-		const explicit = notion.database({
-			resourceId: "issues",
+		const explicit = notion.database("issues", {
 			name: "Issues",
-			dataSources: [
-				{
+			datasources: {
+				Issues: {
 					resourceId: "issues-source",
-					name: "Issues",
-					properties: database.dataSource.schema,
+					schema,
 				},
-			],
+			},
 		});
-		explicit.dataSources["issues-source"].addPage({ resourceId: "issue" });
+		expectTypeOf(explicit.datasources.Issues).toExtend<DataSourceHandle<typeof schema>>();
+		expectTypeOf(explicit.datasources.Issues.schema.Name.type).toEqualTypeOf<"title">();
+		expectTypeOf(explicit.datasources.Issues.schema.Name.resourceId).toEqualTypeOf<"title">();
+		explicit.datasources.Issues.addPage({ resourceId: "issue" });
 		// @ts-expect-error Explicit databases do not guarantee a single source.
 		void explicit.dataSource;
 		expect(shorthand).toEqual(finishMetadataRecording(explicitRecorder).intents);
@@ -56,22 +58,24 @@ describe("Notion-as-Code database shorthand", () => {
 		});
 	});
 
-	it("preserves parent binding and inferred source types through child helpers", () => {
+	it("preserves parent binding and keyed source types through child helpers", () => {
 		const recorder = startMetadataRecording();
 		const page = notion.page({ resourceId: "page" });
 		const team = notion.teamspace({ resourceId: "team", name: "Team", accessLevel: "private" });
+		const schema = {
+			Title: { resourceId: "child-title", type: "title" },
+		} as const;
 		for (const parent of [page, team]) {
-			const database = parent.addDatabase({
-				resourceId: `${parent.resourceId}-db`,
+			const database = parent.addDatabase(`${parent.resourceId}-db`, {
+				dataSourceResourceId: `${parent.resourceId}-source`,
 				name: "Child",
-				properties: [
-					{ resourceId: `${parent.resourceId}-title`, name: "Title", type: "title" },
-				],
+				schema,
 			});
-			expectTypeOf(database.dataSource).toExtend<
-				DataSourceHandle<typeof database.dataSource.schema>
-			>();
-			expectTypeOf(database.dataSource.schema[0].name).toEqualTypeOf<"Title">();
+			expectTypeOf(database.dataSource).toExtend<DataSourceHandle<typeof schema>>();
+			expectTypeOf(database.dataSource.schema.Title.type).toEqualTypeOf<"title">();
+			expectTypeOf(
+				database.dataSource.schema.Title.resourceId,
+			).toEqualTypeOf<"child-title">();
 		}
 		const intents = finishMetadataRecording(recorder).intents;
 		expect(
@@ -82,19 +86,60 @@ describe("Notion-as-Code database shorthand", () => {
 		]);
 	});
 
-	it("rejects mixed forms before recording an intent", () => {
+	it("keeps keyed child inference and rejects empty child databases", () => {
 		const recorder = startMetadataRecording();
-		const declareMixedDatabase = () => {
-			// @ts-expect-error The shorthand and explicit forms are mutually exclusive.
-			notion.database({
-				resourceId: "mixed",
-				name: "Mixed",
-				properties: [],
-				dataSources: [],
-			});
+		const page = notion.page({ resourceId: "child-page" });
+		const schema = {
+			Name: { type: "title", resourceId: "child-name" },
+			"Issue ID": { type: "text", resourceId: "child-issue-id" },
+		} as const;
+		const database = page.addDatabase("child-multi-database", {
+			datasources: {
+				Issues: {
+					resourceId: "child-issues-source",
+					schema,
+				},
+			},
+		});
+		expectTypeOf(database.datasources.Issues).toExtend<DataSourceHandle<typeof schema>>();
+		expectTypeOf(
+			database.datasources.Issues.schema.Name.resourceId,
+		).toEqualTypeOf<"child-name">();
+
+		const invalidChildDeclarations = () => {
+			// @ts-expect-error Child databases need a source or a view.
+			page.addDatabase("child-empty-datasources", { datasources: {} });
+			// @ts-expect-error Child databases need a source or a view.
+			page.addDatabase("child-empty-arguments", {});
+			// @ts-expect-error Empty child sources and views are invalid.
+			page.addDatabase("child-empty-with-views", { datasources: {}, views: [] });
 		};
-		expect(declareMixedDatabase).toThrow();
-		expect(finishMetadataRecording(recorder).intents).toEqual([]);
+		void invalidChildDeclarations;
+		expect(() =>
+			page.addDatabase("child-runtime-empty", { datasources: {}, views: [] } as never),
+		).toThrow();
+
+		const intents = finishMetadataRecording(recorder).intents;
+		expect(intents).toHaveLength(2);
+		expect(intents).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					type: "database",
+					resourceId: "child-multi-database",
+					parent: { type: "resourceId", resourceId: "child-page" },
+					dataSources: [
+						{
+							resourceId: "child-issues-source",
+							name: "Issues",
+							properties: [
+								{ resourceId: "child-name", name: "Name", type: "title" },
+								{ resourceId: "child-issue-id", name: "Issue ID", type: "text" },
+							],
+						},
+					],
+				}),
+			]),
+		);
 	});
 });
 
@@ -159,45 +204,77 @@ describe("buildApp", () => {
 			/hello.ts.*customBlock/,
 		);
 	});
+	it("emits symbolic access requirements for every NaC resource kind", async () => {
+		const { manifest } = await buildApp(fixture("workflow-access"));
+		expect(manifest.capabilities).toEqual([
+			{
+				type: "workflow",
+				key: "access",
+				config: {
+					name: "Access",
+					description: "Declares all workflow access resource kinds",
+					triggers: [{ type: "notion.page.created" }],
+					access: {
+						home: { type: "page", resourceId: "home", level: "view" },
+						records: { type: "database", resourceId: "records", level: "edit" },
+						source: {
+							type: "dataSource",
+							resourceId: "records-source",
+							level: "comment",
+						},
+						agent: { type: "customAgent", resourceId: "agent", level: "call" },
+					},
+				},
+			},
+		]);
+	});
 
 	it("builds a sync manifest with a Notion-as-Code meetings database", async () => {
 		const { manifest } = await buildApp(example("sync"));
 
-		expect(manifest).toEqual({
-			$schema: "notion:apps-manifest:v1",
-			sdkVersion: SDK_VERSION,
-			databases: [
-				{
+		expect(manifest).toEqual(
+			expect.objectContaining({
+				$schema: "notion:apps-manifest:v1",
+				sdkVersion: SDK_VERSION,
+				xldbs: [],
+				pacers: [],
+			}),
+		);
+		expect(manifest.databases).toHaveLength(2);
+		expect(manifest.databases).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
 					key: "issues",
-					config: {
+					config: expect.objectContaining({
 						initialTitle: "GitHub Issues",
-						schema: {
-							properties: {
+						schema: expect.objectContaining({
+							properties: expect.objectContaining({
 								Name: { type: "title" },
 								"GitHub ID": { type: "text" },
 								Closed: { type: "checkbox" },
-							},
-						},
-					},
-				},
-				{
+							}),
+						}),
+					}),
+				}),
+				expect.objectContaining({
 					key: "homebase-meetings-db-source",
-					config: {
+					config: expect.objectContaining({
 						initialTitle: "Meetings",
-						schema: {
-							properties: {
+						schema: expect.objectContaining({
+							properties: expect.objectContaining({
 								Name: { type: "title" },
 								"Meeting ID": { type: "text" },
 								"Meeting date": { type: "date" },
 								"Prep complete": { type: "checkbox" },
-							},
-						},
-					},
-				},
-			],
-			xldbs: [],
-			pacers: [],
-			capabilities: [
+							}),
+						}),
+					}),
+				}),
+			]),
+		);
+		expect(manifest.capabilities).toHaveLength(2);
+		expect(manifest.capabilities).toEqual(
+			expect.arrayContaining([
 				{
 					type: "sync",
 					key: "issues",
@@ -218,8 +295,8 @@ describe("buildApp", () => {
 						schedule: { type: "interval", intervalMs: 3_600_000 },
 					},
 				},
-			],
-		});
+			]),
+		);
 	});
 
 	it("emits a separate Notion-as-Code provisioning artifact", async () => {
@@ -285,6 +362,13 @@ describe("buildApp", () => {
 						resourceId: "__notion_apps_workspace__",
 					},
 					dataSources: [],
+					views: [
+						{
+							resourceId: "github-app-private-view",
+							type: "table",
+							dataSourceResourceId: "issues-source",
+						},
+					],
 				},
 				{
 					type: "database",

package/src/cli/build.ts

@@ -54,24 +54,29 @@ export async function buildApp(projectRoot: string): Promise<BuildResult> {
 	}
 
 	const blockConfigs = await buildBlockDeclarations(projectRoot, capabilities);
-	const manifest = await extractManifest(bundlePath, capabilities, blockConfigs);
-	const manifestPath = path.join(projectRoot, "dist", "manifest.json");
-	await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
-
-	await emitProvisioningArtifact(
+	const entityProvisioning = await buildMetadata(
 		projectRoot,
 		capabilities.filter((capability) => capability.runtime === "worker"),
 	);
+	const manifest = await extractManifest(
+		bundlePath,
+		capabilities,
+		blockConfigs,
+		entityProvisioning,
+	);
+	const manifestPath = path.join(projectRoot, "dist", "manifest.json");
+	await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
+
+	await emitProvisioningArtifact(projectRoot, entityProvisioning);
 
 	return { manifest, bundlePath, manifestPath };
 }
 
-/** Build Notion-as-Code metadata separately so it does not ship in the Worker bundle. */
+/** Emit the Notion-as-Code artifact recorded by the build-only metadata bundle. */
 async function emitProvisioningArtifact(
 	projectRoot: string,
-	capabilities: readonly DiscoveredCapability[],
+	entityProvisioning: RecordedProvisioning,
 ): Promise<void> {
-	const entityProvisioning = await buildMetadata(projectRoot, capabilities);
 	const provisioningPath = path.join(projectRoot, "dist", "provisioning.json");
 	if (entityProvisioning.intents.length === 0) {
 		await fs.promises.rm(provisioningPath, { force: true });

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,4 +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 };
 }