@notionhq/apps 0.0.21 → 0.0.23

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

@@ -25,7 +25,8 @@ 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 } }`.
+custom agent, use the matching helper, such as
+`access: { guide: access.view(guide), analyst: access.call(analyst) }`.
 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
@@ -34,8 +35,8 @@ rejects it before upload.
 
 ## Where declarations are picked up
 
-The Apps build discovers direct `.ts` children of `src/workflows/` and
-`src/syncs/`, then evaluates their imports with the Notion as Code recorder active.
+The Apps build discovers direct `.ts` children of `src/workflows/`,
+`src/syncs/`, and `src/customBlocks/`, then evaluates their imports with the Notion as Code recorder active.
 Pages, databases, data sources, teamspaces, and custom agents all follow this
 same rule. Their resource type does not determine their file location.
 
@@ -50,6 +51,8 @@ src/
     myWorkflow/
       lib/
         notion.ts         Resources owned by myWorkflow
+  customBlocks/
+    board.ts              May import shared resource declarations
 ```
 
 Choose the location based on ownership, not resource type. Export an app-wide
@@ -64,8 +67,8 @@ either. Helpers under capability-specific `lib/` directories are not discovered
 on their own.
 Every direct file in a capability directory must still default-export that
 capability, so do not put a resource-only file there. Imports reached only
-through `src/customBlocks/` or browser code do not enter the Notion as Code recording
-phase. An App containing only unimported resource declarations is not a
+through browser code do not enter the Notion as Code recording phase. An App containing
+only unimported resource declarations is not a
 standalone Notion as Code project and has no discovered capabilities.
 
 ## Declare resources

package/skills/workflow/SKILL.md

@@ -132,7 +132,7 @@ export const guide = page({
 Import the handle into the workflow and declare the named binding it needs:
 
 ```ts
-import { workflow } from "@notionhq/apps";
+import { access, workflow } from "@notionhq/apps";
 import { triggers } from "@notionhq/apps/triggers";
 
 import { guide } from "./sayHello/lib/notion.js";
@@ -141,7 +141,7 @@ export default workflow({
 	name: "Read guide",
 	description: "Reads the App's guide on a recurring schedule.",
 	triggers: [triggers.scheduled()],
-	access: { guide: { resource: guide, level: "view" } },
+	access: { guide: access.view(guide) },
 	handler: async (_event, context) => {
 		await context.step("Read guide", () =>
 			context.notion.pages.retrieve({ page_id: context.access.guide.id }),
@@ -155,9 +155,9 @@ 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
+`access.view()`, `access.comment()`, `access.edit()`, and `access.fullAccess()`
+accept page, database, and data-source handles. `access.call()` accepts custom-agent
+handles. 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.

package/src/cli/build.test.ts

@@ -194,6 +194,56 @@ describe("buildApp", () => {
 		expect(worker).not.toMatch(/custom_block|customBlock|react|createRoot|NotionCustomBlock/);
 		expect(fs.existsSync(path.join(root, ".notion/blocks.js"))).toBe(false);
 	});
+
+	it("records resources imported only by a custom block and emits default bindings", async () => {
+		const root = fixture("custom-block-notion-as-code");
+		const { manifest } = await buildApp(root);
+
+		expect(manifest.capabilities).toEqual([
+			{
+				type: "custom_block",
+				key: "board",
+				config: expect.objectContaining({
+					defaultBindings: {
+						tasks: {
+							dataSourceResourceId: "tasks-source",
+							propertyResourceIdsByKey: {
+								Name: "task-name",
+								Status: "task-status",
+								Due: "task-due",
+							},
+						},
+					},
+					manifest: expect.objectContaining({
+						dataSources: {
+							tasks: expect.objectContaining({
+								name: "Tasks",
+								description: "Work items shown on the board",
+							}),
+						},
+					}),
+				}),
+			},
+		]);
+		const provisioning = JSON.parse(
+			await fs.promises.readFile(path.join(root, "dist", "provisioning.json"), "utf8"),
+		);
+		expect(provisioning.intents).toEqual([
+			expect.objectContaining({
+				type: "database",
+				resourceId: "tasks-db",
+				dataSources: [
+					expect.objectContaining({
+						resourceId: "tasks-source",
+						properties: expect.arrayContaining([
+							expect.objectContaining({ resourceId: "task-status" }),
+						]),
+					}),
+				],
+			}),
+		]);
+	});
+
 	it("names the block file when path is missing", async () => {
 		await expect(buildApp(fixture("custom-block-missing-path"))).rejects.toThrow(
 			/hello.ts.*non-empty path/,
@@ -217,6 +267,11 @@ describe("buildApp", () => {
 					access: {
 						home: { type: "page", resourceId: "home", level: "view" },
 						records: { type: "database", resourceId: "records", level: "edit" },
+						fullRecords: {
+							type: "database",
+							resourceId: "records",
+							level: "fullAccess",
+						},
 						source: {
 							type: "dataSource",
 							resourceId: "records-source",

package/src/cli/build.ts

@@ -54,10 +54,7 @@ export async function buildApp(projectRoot: string): Promise<BuildResult> {
 	}
 
 	const blockConfigs = await buildBlockDeclarations(projectRoot, capabilities);
-	const entityProvisioning = await buildMetadata(
-		projectRoot,
-		capabilities.filter((capability) => capability.runtime === "worker"),
-	);
+	const entityProvisioning = await buildMetadata(projectRoot, capabilities);
 	const manifest = await extractManifest(
 		bundlePath,
 		capabilities,

package/src/cli/codegen.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { generateEntry } from "./codegen.js";
+import { generateEntry, generateMetadataEntry } from "./codegen.js";
 
 describe("generateEntry", () => {
 	it("statically imports and registers workflows by key", () => {
@@ -36,3 +36,19 @@ describe("generateEntry", () => {
 		expect(entry).toContain(`"issues": capability_0,`);
 	});
 });
+
+describe("generateMetadataEntry", () => {
+	it("records resources imported by custom blocks", () => {
+		const entry = generateMetadataEntry([
+			{
+				type: "custom_block",
+				tag: "custom_block",
+				runtime: "build",
+				key: "board",
+				sourcePath: "src/customBlocks/board.ts",
+			},
+		]);
+
+		expect(entry).toContain(`await import("../src/customBlocks/board.ts");`);
+	});
+});

package/src/custom-block.test.ts

@@ -1,5 +1,8 @@
-import { describe, expect, it } from "vitest";
-import { customBlock } from "./custom-block.js";
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { customBlock, type CustomBlockOptions } from "./custom-block.js";
+import { notion, type DatabaseHandle } from "./notion-as-code/index.js";
+import { toCustomBlockPropertyType } from "./translate.js";
 
 describe("customBlock", () => {
 	it("supports static assets without a build command", () => {
@@ -16,4 +19,137 @@ describe("customBlock", () => {
 			);
 		},
 	);
+
+	it("generates mappings and default bindings from a single-source database", () => {
+		const tasks = notion.database("tasks-db", {
+			dataSourceResourceId: "tasks-source",
+			name: "Tasks",
+			description: "Work items shown on the board",
+			schema: {
+				Name: { resourceId: "task-name", type: "title" },
+				Notes: {
+					resourceId: "task-notes",
+					type: "text",
+					description: "Extra context",
+				},
+				Files: { resourceId: "task-files", type: "file" },
+				Due: { resourceId: "task-due", type: "date" },
+			},
+		});
+
+		expect(
+			customBlock({
+				path: "./blocks/board",
+				name: "Task board",
+				description: "Shows tasks by status",
+				dataSources: { tasks },
+			}).config,
+		).toEqual({
+			source: {
+				type: "project",
+				path: "./blocks/board",
+				command: "npx vite build",
+				output: "dist",
+			},
+			manifest: {
+				version: 1,
+				name: "Task board",
+				description: "Shows tasks by status",
+				dataSources: {
+					tasks: {
+						name: "Tasks",
+						description: "Work items shown on the board",
+						properties: {
+							Name: { name: "Name", type: "title" },
+							Notes: {
+								name: "Notes",
+								description: "Extra context",
+								type: "rich_text",
+							},
+							Files: { name: "Files", type: "files" },
+							Due: { name: "Due", type: "date" },
+						},
+					},
+				},
+			},
+			defaultBindings: {
+				tasks: {
+					dataSourceResourceId: "tasks-source",
+					propertyResourceIdsByKey: {
+						Name: "task-name",
+						Notes: "task-notes",
+						Files: "task-files",
+						Due: "task-due",
+					},
+				},
+			},
+		});
+	});
+
+	it("accepts a data-source handle alongside an inline mapping", () => {
+		const tasks = notion.database("tasks-db", {
+			name: "Project",
+			datasources: {
+				Tasks: {
+					resourceId: "tasks-source",
+					description: "Current tasks",
+					schema: { Name: { resourceId: "task-name", type: "title" } },
+				},
+			},
+		});
+		const block = customBlock({
+			path: "./blocks/board",
+			dataSources: {
+				tasks: tasks.datasources.Tasks,
+				people: { name: "People", properties: {} },
+			},
+		});
+
+		expect(block.config.manifest.dataSources).toEqual({
+			tasks: {
+				name: "Tasks",
+				description: "Current tasks",
+				properties: { Name: { name: "Name", type: "title" } },
+			},
+			people: { name: "People", properties: {} },
+		});
+		expect(block.config.defaultBindings).toEqual({
+			tasks: {
+				dataSourceResourceId: "tasks-source",
+				propertyResourceIdsByKey: { Name: "task-name" },
+			},
+		});
+	});
+
+	it("rejects multi-source database handles in the dataSources type", () => {
+		type DataSourceOption = NonNullable<CustomBlockOptions["dataSources"]>[string];
+		expectTypeOf<DatabaseHandle>().not.toExtend<DataSourceOption>();
+	});
+
+	it.each([
+		["title", "title"],
+		["text", "rich_text"],
+		["number", "number"],
+		["select", "select"],
+		["multi_select", "multi_select"],
+		["status", "status"],
+		["date", "date"],
+		["checkbox", "checkbox"],
+		["url", "url"],
+		["email", "email"],
+		["phone_number", "phone_number"],
+		["file", "files"],
+		["person", "people"],
+		["auto_increment_id", "unique_id"],
+		["relation", "relation"],
+		["formula", "formula"],
+		["rollup", "rollup"],
+		["created_time", "created_time"],
+		["last_edited_time", "last_edited_time"],
+		["created_by", "created_by"],
+		["last_edited_by", "last_edited_by"],
+		["verification", "verification"],
+	] as const)("maps Notion-as-Code %s properties to manifest %s properties", (input, output) => {
+		expect(toCustomBlockPropertyType(input)).toBe(output);
+	});
 });

package/src/custom-block.ts

@@ -1,9 +1,21 @@
 import type { ManifestDataSource } from "@notionhq/custom-blocks";
 
+import type { DataSourceHandle, SingleSourceDatabaseHandle } from "./notion-as-code/database.js";
+import { toCustomBlockDefaultBinding, toCustomBlockDataSource } from "./translate.js";
+
+export type CustomBlockDefaultBinding = {
+	dataSourceResourceId: string;
+	propertyResourceIdsByKey: Record<string, string>;
+};
+
+type CustomBlockDataSource = ManifestDataSource | DataSourceHandle | SingleSourceDatabaseHandle;
+
 export type CustomBlockOptions = {
 	path: string;
+	name?: string;
+	description?: string;
 	slashCommand?: string;
-	dataSources?: Record<string, ManifestDataSource>;
+	dataSources?: Record<string, CustomBlockDataSource>;
 } & (
 	| { static: true; command?: never; output?: never }
 	| { static?: false; command?: string; output?: string }
@@ -20,6 +32,7 @@ export function customBlock(options: CustomBlockOptions) {
 			"Custom block slashCommand must be 1–64 lowercase letters, numbers, hyphens or underscores, starting with a letter or number",
 		);
 	}
+	const { dataSources, defaultBindings } = lowerDataSources(options.dataSources ?? {});
 	return {
 		_tag: "custom_block" as const,
 		config: {
@@ -33,9 +46,43 @@ export function customBlock(options: CustomBlockOptions) {
 					},
 			manifest: {
 				version: 1 as const,
+				...(options.name === undefined ? {} : { name: options.name }),
+				...(options.description === undefined ? {} : { description: options.description }),
 				...(slashCommand === undefined ? {} : { slashCommand }),
-				dataSources: options.dataSources ?? {},
+				dataSources,
 			},
+			...(Object.keys(defaultBindings).length === 0 ? {} : { defaultBindings }),
 		},
 	};
 }
+
+function lowerDataSources(dataSources: Record<string, CustomBlockDataSource>) {
+	const manifestDataSources: Record<string, ManifestDataSource> = {};
+	const defaultBindings: Record<string, CustomBlockDefaultBinding> = {};
+
+	for (const [key, dataSource] of Object.entries(dataSources)) {
+		const handle = isSingleSourceDatabaseHandle(dataSource)
+			? dataSource.dataSource
+			: dataSource;
+		if (isDataSourceHandle(handle)) {
+			manifestDataSources[key] = toCustomBlockDataSource(handle);
+			defaultBindings[key] = toCustomBlockDefaultBinding(handle);
+		} else {
+			manifestDataSources[key] = handle;
+		}
+	}
+
+	return { dataSources: manifestDataSources, defaultBindings };
+}
+
+function isSingleSourceDatabaseHandle(
+	value: CustomBlockDataSource,
+): value is SingleSourceDatabaseHandle {
+	return "dataSource" in value;
+}
+
+function isDataSourceHandle(
+	value: ManifestDataSource | DataSourceHandle,
+): value is DataSourceHandle {
+	return "resourceId" in value && "schema" in value && "database" in value;
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export { teamspace } from "./notion-as-code/teamspace.js";
 export { view } from "./notion-as-code/view.js";
 export { sync } from "./sync.js";
 export {
+	access,
 	workflow,
 	type Workflow,
 	type WorkflowAccess,

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

@@ -75,6 +75,7 @@ describe("Notion-as-Code database declarations", () => {
 			database.dataSource.schema.Title.resourceId,
 		).toEqualTypeOf<"single-title-id">();
 		expect(database.dataSource.schema).toEqual(schema);
+		expect(database.dataSource.name).toBe("Tasks");
 
 		const declaration = sync({
 			dataSource: database.dataSource,
@@ -636,6 +637,7 @@ describe("Notion-as-Code database declarations", () => {
 		notion.database("metadata-database", {
 			dataSourceResourceId: "metadata-source",
 			name: "Metadata",
+			description: "Metadata source",
 			schema: {
 				Name: { type: "title", resourceId: "metadata-name" },
 			},
@@ -658,11 +660,13 @@ describe("Notion-as-Code database declarations", () => {
 			type: "database",
 			resourceId: "metadata-database",
 			name: "Metadata",
+			description: "Metadata source",
 			parent: { type: "resourceId", resourceId: APPS_WORKSPACE_RESOURCE_ID },
 			dataSources: [
 				{
 					resourceId: "metadata-source",
 					name: "Metadata",
+					description: "Metadata source",
 					properties: [{ type: "title", resourceId: "metadata-name", name: "Name" }],
 				},
 			],
@@ -680,7 +684,7 @@ describe("Notion-as-Code database declarations", () => {
 		expect(serialized).not.toHaveProperty("schema");
 		expect(serialized).not.toHaveProperty("dataSourceResourceId");
 		expect(serialized).not.toHaveProperty("datasources");
-		expect(serialized).not.toHaveProperty("description");
+		expect(serialized.description).toBe("Metadata source");
 	});
 
 	it("requires the status property configuration in authoring types", () => {

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

@@ -25,6 +25,7 @@ type NonEmptyViewSchemas = readonly [ViewSchema, ...ViewSchema[]];
 export type DataSourceArgs<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
 	resourceId: ResourceId;
 	name?: never;
+	description?: string;
 	schema: Schema;
 	icon?: NotionAsCodeIcon;
 	pageLayout?: DatabasePageLayout<Schema>;
@@ -120,6 +121,8 @@ export type ChildDatabaseArgs<
 export type DataSourceHandle<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
 	readonly resourceType: "dataSource";
 	readonly resourceId: string;
+	readonly name: string;
+	readonly description?: string;
 	readonly schema: Schema;
 	readonly database: Database<AppsSchemaForSchema<Schema>>;
 	addPage: (args: ChildPageArgs) => PageHandle;
@@ -259,6 +262,7 @@ function buildDatabaseHandle(
 		const source: DataSourceDefinition = {
 			resourceId: args.dataSourceResourceId,
 			name: args.name,
+			...(args.description === undefined ? {} : { description: args.description }),
 			properties: normalizeProperties(args.schema),
 			...(args.pageLayout === undefined ? {} : { pageLayout: args.pageLayout }),
 		};
@@ -400,7 +404,7 @@ function createDatabase(
 			);
 		}
 		dataSourceIds.add(definition.resourceId);
-		handles[key] = createDataSourceHandle(definition, schema);
+		handles[key] = createDataSourceHandle(definition, schema, intent.description);
 	}
 
 	recordIntent({ ...intent, type: "database" });
@@ -419,6 +423,7 @@ function createDatabase(
 function createDataSourceHandle(
 	dataSource: DataSourceDefinition,
 	schema: NotionAsCodeSchema,
+	databaseDescription: string | undefined,
 ): DataSourceHandle {
 	const propertyResourceIds = new Set<string>();
 	const propertyNames = new Set<string>();
@@ -437,10 +442,13 @@ function createDataSourceHandle(
 		propertyResourceIds.add(property.resourceId);
 		propertyNames.add(property.name);
 	}
+	const description = dataSource.description ?? databaseDescription;
 
 	return {
 		resourceType: "dataSource",
 		resourceId: dataSource.resourceId,
+		name: dataSource.name,
+		...(description === undefined ? {} : { description }),
 		schema,
 		database: createAppsDatabase(dataSource.resourceId, dataSource),
 		addPage(pageArgs) {

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

@@ -66,6 +66,7 @@ export type {
 	SingleSourceDatabaseArgs,
 	SingleSourceDatabaseHandle,
 } from "./database.js";
+export { toCustomBlockDefaultBinding, toCustomBlockDataSource } from "../translate.js";
 export type {
 	ChildPageArgs,
 	PageArgs,

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

@@ -316,6 +316,7 @@ export type DataSourceDefinition<
 > = {
 	resourceId: ResourceId;
 	name: string;
+	description?: string;
 	properties: Properties;
 	icon?: NotionAsCodeIcon;
 	pageLayout?: DatabasePageLayout;

package/src/translate.ts

@@ -0,0 +1,77 @@
+import type {
+	ManifestDataSource,
+	ManifestProperty,
+	NotionPropertyType,
+} from "@notionhq/custom-blocks";
+
+import type { CustomBlockDefaultBinding } from "./custom-block.js";
+import type { DataSourceHandle } from "./notion-as-code/database.js";
+import type { NotionAsCodeProperty } from "./notion-as-code/intents.js";
+
+/** Lower a Notion-as-Code handle into the declaration consumed by custom block hosts. */
+export function toCustomBlockDataSource(handle: DataSourceHandle): ManifestDataSource {
+	return {
+		name: handle.name,
+		...(handle.description === undefined ? {} : { description: handle.description }),
+		properties: Object.fromEntries(
+			Object.entries(handle.schema).map(([key, property]) => [
+				key,
+				{
+					name: key,
+					...(typeof property.description !== "string"
+						? {}
+						: { description: property.description }),
+					type: toCustomBlockPropertyType(property.type),
+				} satisfies ManifestProperty,
+			]),
+		),
+	};
+}
+
+/** Keep resource IDs in the build artifact so deploy can resolve workspace-local IDs later. */
+export function toCustomBlockDefaultBinding(handle: DataSourceHandle): CustomBlockDefaultBinding {
+	return {
+		dataSourceResourceId: handle.resourceId,
+		propertyResourceIdsByKey: Object.fromEntries(
+			Object.entries(handle.schema).map(([key, property]) => [key, property.resourceId]),
+		),
+	};
+}
+
+export function toCustomBlockPropertyType(type: NotionAsCodeProperty["type"]): NotionPropertyType {
+	switch (type) {
+		case "text":
+			return "rich_text";
+		case "file":
+			return "files";
+		case "person":
+			return "people";
+		case "auto_increment_id":
+			return "unique_id";
+		case "title":
+		case "number":
+		case "select":
+		case "multi_select":
+		case "status":
+		case "date":
+		case "checkbox":
+		case "url":
+		case "email":
+		case "phone_number":
+		case "relation":
+		case "formula":
+		case "rollup":
+		case "created_time":
+		case "last_edited_time":
+		case "created_by":
+		case "last_edited_by":
+		case "verification":
+			return type;
+		default:
+			return assertNever(type);
+	}
+}
+
+function assertNever(value: never): never {
+	throw new Error(`Unsupported Notion-as-Code property type: ${String(value)}`);
+}

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

@@ -4,7 +4,7 @@ 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";
+import { access, workflow } from "./workflow.js";
 
 it("infers access aliases and rejects resource-specific levels", () => {
 	const home = page({ resourceId: "home" });
@@ -28,15 +28,19 @@ it("infers access aliases and rejects resource-specific levels", () => {
 		description: "Checks access types",
 		triggers: [triggers.notionPageCreated()],
 		access: {
-			home: { resource: home, level: "view" },
-			singleDatabase: { resource: singleDatabase, level: "edit" },
-			multiDatabase: { resource: multiDatabase, level: "view" },
+			home: access.view(home),
+			singleDatabase: access.edit(singleDatabase),
+			multiDatabase: access.fullAccess(multiDatabase),
+			source: access.comment(singleDatabase.dataSource),
+			agent: access.call(agent),
 		},
 		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">();
+			expectTypeOf(context.access.source.type).toEqualTypeOf<"dataSource">();
+			expectTypeOf(context.access.agent.type).toEqualTypeOf<"customAgent">();
 			// @ts-expect-error Access aliases are limited to declarations.
 			void context.access.missing;
 			// @ts-expect-error Access values are readonly.