@notionhq/apps 0.0.18 → 0.0.19

package/dist/workflow.js

@@ -3,6 +3,10 @@ import {
   normalizeConnectionRequirements,
   validateTriggerConnections
 } from "./connections.js";
+import {
+  hydrateWorkflowAccess,
+  normalizeWorkflowAccess
+} from "./workflow-access.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -19,6 +23,7 @@ import {
 } from "./connections.js";
 function workflow(configuration) {
   const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
+  const accessRequirements = normalizeWorkflowAccess(configuration.access);
   const connectionDeclarations = configuration.connections === void 0 ? void 0 : structuredClone(configuration.connections);
   const triggers = typeof configuration.triggers === "function" ? configuration.triggers({ triggers: createWorkflowTriggers() }) : configuration.triggers;
   validateTriggerConnections(triggers, requirements);
@@ -28,7 +33,8 @@ function workflow(configuration) {
       name: configuration.name,
       description: configuration.description,
       triggers,
-      ...configuration.connections === void 0 ? {} : { connections: requirements }
+      ...configuration.connections === void 0 ? {} : { connections: requirements },
+      ...configuration.access === void 0 ? {} : { access: accessRequirements }
     },
     async handler(event, options) {
       try {
@@ -38,6 +44,7 @@ function workflow(configuration) {
         const step = createStep(runMetadata);
         const capabilityContext = {
           ...baseContext,
+          access: hydrateWorkflowAccess(accessRequirements),
           connections: createWorkflowConnections(
             baseContext.notion,
             connectionDeclarations

package/docs/BUILD.md

@@ -43,10 +43,11 @@ natural capability owner.
 1. Discover top-level files in the capability directories.
 2. Generate `.notion/entry.ts` with workflow and sync imports and a dispatcher.
 3. Bundle the app's code into `dist/worker.js`, leaving npm packages external.
-4. Evaluate custom-block declarations separately, validate capability exports and
-   configuration, and write `dist/manifest.json`. Blocks do not enter `worker.js`.
+4. Evaluate custom-block declarations separately. Blocks do not enter `worker.js`.
 5. Evaluate worker capabilities in a separate build-only metadata bundle to record
-   Notion-as-Code declarations, then emit `dist/provisioning.json` if there are any.
+   Notion-as-Code declarations. Validate workflow access references against those
+   declarations before writing the manifest and optional provisioning artifact.
+6. Emit `dist/manifest.json` and, when declarations exist, `dist/provisioning.json`.
 
 Capability modules must therefore be importable without secrets or network access.
 Read required environment variables and make requests inside handlers or workflow
@@ -170,7 +171,8 @@ uploaded project must declare its SDK dependency and a `build` script that invok
 Worker using `workersCreateWorker` with `createApp: true`, or updates the existing
 Worker, then uploads source and calls `workersBuildWorker` with the Worker ID.
 For App-linked Workers, the build endpoint coordinates capability registration,
-Notion-as-Code provisioning, and database attachment before reporting build success.
+Notion-as-Code provisioning, database attachment, workflow binding resolution,
+and workflow permission reconciliation before reporting build success.
 It returns the normal build result and run ID, not provisioning state. No separate
 Apps deployment endpoint is required.
 
@@ -193,6 +195,9 @@ flow and local state, and reconciles attachments. It reads the optional
 `dist/provisioning.json` locally and does not upload it separately or invoke
 the cloud build endpoint.
 
+Workflows with nonempty `access` require cloud deployment. The local-build path
+rejects them after the SDK build and before uploading or deploying the bundle.
+
 Resource bindings are not stored in SDK build output. Local deployments retain a
 local state file and report `state_file`; cloud deployments keep installation-owned
 resource mappings and state on the server. Cloud builds do not import local state
@@ -202,6 +207,35 @@ switching between modes may recreate resources rather than reuse existing bindin
 Cloud failures never automatically retry locally. There is no rollback: code or
 resources may already have changed when a deployment fails.
 
+## Workflow access
+
+`workflow({ access: { handbook: { resource: handbook, level: "view" } }, ... })`
+declares access to a NaC resource and a named runtime binding. The manifest
+contains only the alias and its symbolic `{ type, resourceId, level }`
+requirement; live IDs are not build output.
+Build validation rejects references missing from the current provisioning
+declarations or having the wrong resource kind. `resourceId` is required because
+it identifies the declaration used for this validation and binding.
+
+After provisioning, cloud deployment resolves requirements against the successful
+NaC apply result. It reconciles code-managed grants through the existing
+Notion-module permissions and saves those permissions together with resolved
+bindings on the workflow's worker module, keyed by capability and alias, in one
+workflow transaction. Bindings are not authorization: the existing permissions
+authorize `context.notion` calls. Redeployment updates or removes code-managed
+grants as declarations change while preserving manually configured UI grants.
+
+Execution reads the selected workflow configuration, not the latest NaC state,
+validates the bindings against the capability requirements, and injects only that
+capability's declared bindings. The SDK exposes typed, readonly `{ type, id }`
+entries in `context.access`; UI-granted resources do not appear there. Use live
+record IDs directly in `context.notion` calls for UI-granted resources; those
+calls remain subject to the existing permissions. Missing or mismatched bindings
+fail before the handler executes.
+
+See the [workflow skill](../skills/workflow/SKILL.md#resources-created-with-the-app)
+for supported resource types, access levels, and an authoring example.
+
 ## Manifest
 
 The workflow-only manifest retains the platform's existing resource fields as empty arrays:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.18",
+	"version": "0.0.19",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {

package/skills/notion-as-code/SKILL.md

@@ -24,6 +24,14 @@ owned by one capability, use a local module such as
 are shared across capabilities or do not have a natural capability owner. Module
 evaluation must work without credentials or network access.
 
+To configure a workflow's access to a declared page, database, data source, or
+custom agent, pass its handle in `access: { alias: { resource: handle, level } }`.
+The handler receives the live identity as `context.access.alias.id`; importing
+a declaration alone does not request access. See the
+[workflow skill](../workflow/SKILL.md#resources-created-with-the-app) for levels
+and examples. Nonempty workflow `access` requires cloud deployment; `--local-build`
+rejects it before upload.
+
 ## Where declarations are picked up
 
 The Apps build discovers direct `.ts` children of `src/workflows/` and

package/skills/workflow/SKILL.md

@@ -110,8 +110,8 @@ 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. A small workflow-specific resource can be
@@ -127,32 +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 { workflow } from "@notionhq/apps";
 import { triggers } from "@notionhq/apps/triggers";
 
-import "./sayHello/lib/notion.js";
+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

@@ -204,6 +204,30 @@ 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"));

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,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/page.ts

@@ -23,6 +23,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 +51,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;
+});