@notionhq/apps 0.0.30 → 0.0.32

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

@@ -1,13 +1,117 @@
 import { describe, expect, expectTypeOf, it } from "vitest";
 
 import { Builder } from "../builder.js";
+import { customBlock } from "../custom-block.js";
 import { ExecutionError } from "../error.js";
 import { sync } from "../sync.js";
 import { notion, type DataSourceHandle, type SingleSourceDatabaseHandle } from "./index.js";
 import { APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
-import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
+import {
+	finishMetadataRecording,
+	startMetadataRecording,
+	withMetadataCapabilityKey,
+} from "./recorder.js";
 
 describe("Notion-as-Code database declarations", () => {
+	it("infers a custom view data source from the block's default bindings", async () => {
+		const recorder = startMetadataRecording();
+		const tasks = notion.database("tasks-db", {
+			dataSourceResourceId: "tasks-source",
+			name: "Tasks",
+			schema: { Name: { resourceId: "task-name", type: "title" } },
+		});
+
+		await withMetadataCapabilityKey("board", async () => {
+			const board = customBlock({
+				path: "./blocks/board",
+				dataSources: { tasks },
+			});
+			tasks.addCustomView({
+				resourceId: "tasks-board-view",
+				name: "Board",
+				customBlock: board,
+			});
+		});
+
+		expect(finishMetadataRecording(recorder).intents.at(-1)).toEqual({
+			type: "view",
+			databaseResourceId: "tasks-db",
+			view: {
+				type: "custom",
+				resourceId: "tasks-board-view",
+				name: "Board",
+				dataSourceResourceId: "tasks-source",
+				customBlockKey: "board",
+			},
+		});
+	});
+
+	it("requires an explicit bound source when a block binds multiple database sources", async () => {
+		const recorder = startMetadataRecording();
+		const tasks = notion.database("tasks-db", {
+			name: "Tasks",
+			datasources: {
+				Active: {
+					resourceId: "active-source",
+					schema: { Name: { resourceId: "active-name", type: "title" } },
+				},
+				Archive: {
+					resourceId: "archive-source",
+					schema: { Name: { resourceId: "archive-name", type: "title" } },
+				},
+			},
+		});
+		const projects = notion.database("projects-db", {
+			dataSourceResourceId: "projects-source",
+			name: "Projects",
+			schema: { Name: { resourceId: "project-name", type: "title" } },
+		});
+
+		await withMetadataCapabilityKey("board", async () => {
+			const board = customBlock({
+				path: "./blocks/board",
+				dataSources: {
+					active: tasks.datasources.Active,
+					archive: tasks.datasources.Archive,
+				},
+			});
+			expect(() =>
+				tasks.addCustomView({
+					resourceId: "ambiguous-board-view",
+					customBlock: board,
+				}),
+			).toThrow("must bind exactly one data source");
+			tasks.addCustomView({
+				resourceId: "active-board-view",
+				customBlock: board,
+				dataSource: tasks.datasources.Active,
+			});
+			expect(() =>
+				tasks.addCustomView({
+					resourceId: "foreign-board-view",
+					customBlock: board,
+					dataSource: projects.dataSource,
+				}),
+			).toThrow('dataSource must belong to database "tasks-db"');
+			const activeOnlyBoard = customBlock({
+				path: "./blocks/active-board",
+				dataSources: { active: tasks.datasources.Active },
+			});
+			expect(() =>
+				tasks.addCustomView({
+					resourceId: "unbound-board-view",
+					customBlock: activeOnlyBoard,
+					dataSource: tasks.datasources.Archive,
+				}),
+			).toThrow('dataSource must be bound by custom block "board"');
+		});
+
+		expect(finishMetadataRecording(recorder).intents.at(-1)).toEqual(
+			expect.objectContaining({
+				view: expect.objectContaining({ dataSourceResourceId: "active-source" }),
+			}),
+		);
+	});
 	it("records a single-source page layout on the data source", () => {
 		const recorder = startMetadataRecording();
 

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

@@ -1,4 +1,5 @@
 import type { Database } from "../database.js";
+import type { CustomBlockHandle } from "../custom-block.js";
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
 	type DatabaseIntent,
@@ -11,7 +12,7 @@ import {
 	type ResourceId,
 } from "./intents.js";
 import { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
-import { recordIntent } from "./recorder.js";
+import { isMetadataRecording, recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 import { createAppsDatabase, type AppsSchemaForSchema } from "./schema.js";
 import type { ViewSchema } from "./views.js";
@@ -132,6 +133,15 @@ type DatabaseHandleBase = {
 	readonly resourceType: "database";
 	readonly resourceId: string;
 	addView: (view: ViewSchema) => void;
+	addCustomView: (view: AddCustomViewArgs) => void;
+};
+
+export type AddCustomViewArgs = {
+	resourceId: ResourceId;
+	name?: string;
+	icon?: Extract<NotionAsCodeIcon, { type: "notion_icon" }>;
+	customBlock: CustomBlockHandle;
+	dataSource?: DataSourceHandle;
 };
 
 /** Map each authoring source key to a handle backed by that source's own schema. */
@@ -278,6 +288,7 @@ function buildDatabaseHandle(
 			resourceId: databaseResourceId,
 			dataSource,
 			addView: handle.addView,
+			addCustomView: handle.addCustomView,
 		};
 	}
 
@@ -416,9 +427,74 @@ function createDatabase(
 		addView(view) {
 			recordIntent({ type: "view", databaseResourceId: intent.resourceId, view });
 		},
+		addCustomView(view) {
+			recordCustomView(intent.resourceId, view, handles);
+		},
 	};
 }
 
+function recordCustomView(
+	databaseResourceId: ResourceId,
+	view: AddCustomViewArgs,
+	handles: Readonly<Record<string, DataSourceHandle>>,
+): void {
+	assertUserResourceId(view.resourceId);
+	const customBlockKey = view.customBlock.key;
+	if (typeof customBlockKey !== "string" || customBlockKey.trim() === "") {
+		if (!isMetadataRecording()) {
+			return;
+		}
+		throw new Error(
+			"addCustomView must be called from the custom block capability file so its key is available during build",
+		);
+	}
+
+	const dataSources = Object.values(handles);
+	const boundDataSourceIds = new Set(
+		Object.values(view.customBlock.config.defaultBindings ?? {}).map(
+			(binding) => binding.dataSourceResourceId,
+		),
+	);
+	let dataSourceResourceId: string;
+	if (view.dataSource !== undefined) {
+		if (!dataSources.includes(view.dataSource)) {
+			throw new Error(
+				`Custom view "${view.resourceId}" dataSource must belong to database "${databaseResourceId}"`,
+			);
+		}
+		if (!boundDataSourceIds.has(view.dataSource.resourceId)) {
+			throw new Error(
+				`Custom view "${view.resourceId}" dataSource must be bound by custom block "${customBlockKey}"`,
+			);
+		}
+		dataSourceResourceId = view.dataSource.resourceId;
+	} else {
+		const matchingSources = dataSources.filter((source) =>
+			boundDataSourceIds.has(source.resourceId),
+		);
+		const matchingSource = matchingSources[0];
+		if (matchingSources.length !== 1 || matchingSource === undefined) {
+			throw new Error(
+				`Custom view "${view.resourceId}" must bind exactly one data source from database "${databaseResourceId}" or specify dataSource`,
+			);
+		}
+		dataSourceResourceId = matchingSource.resourceId;
+	}
+
+	recordIntent({
+		type: "view",
+		databaseResourceId,
+		view: {
+			type: "custom",
+			resourceId: view.resourceId,
+			...(view.name === undefined ? {} : { name: view.name }),
+			...(view.icon === undefined ? {} : { icon: view.icon }),
+			dataSourceResourceId,
+			customBlockKey,
+		},
+	});
+}
+
 /** Create a data-source handle backed by the Apps database used by syncs. */
 function createDataSourceHandle(
 	dataSource: DataSourceDefinition,

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

@@ -34,7 +34,6 @@ export type {
 } from "./intents.js";
 export type {
 	CustomAgentAccess,
-	CustomAgentAccessRole,
 	CustomAgentArgs,
 	CustomAgentHandle,
 	CustomAgentPageAddedTrigger,
@@ -56,6 +55,7 @@ export type {
 	YearlyRecurrenceSchedule,
 } from "./custom-agent.js";
 export type {
+	AddCustomViewArgs,
 	ChildDatabaseArgs,
 	ChildDatabaseFactory,
 	ChildMultiSourceDatabaseArgs,
@@ -93,6 +93,7 @@ export type {
 	CoverAspectFormat,
 	CoverFormat,
 	CoverSizeFormat,
+	CustomViewSchema,
 	DatabaseViewSortDirection,
 	DateFilterMode,
 	DateGroupByFormat,

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

@@ -1,3 +1,4 @@
+import type { ResourceAccessLevel } from "../workflow-access.js";
 import type { CustomAgentArgs } from "./custom-agent.js";
 import type { PageArgs } from "./page.js";
 import type { TeamspaceArgs } from "./teamspace.js";
@@ -346,7 +347,9 @@ export type DatabaseIntent = {
 };
 
 export type PageIntent = PageArgs & { parent: Parent };
-export type CustomAgentIntent = CustomAgentArgs;
+export type CustomAgentIntent = Omit<CustomAgentArgs, "access"> & {
+	access?: readonly { resourceId: ResourceId; level: ResourceAccessLevel }[];
+};
 
 export type ViewIntent = {
 	databaseResourceId: ResourceId;

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

@@ -1,8 +1,9 @@
 import { expectTypeOf, it } from "vitest";
+import { access } from "../workflow-access.js";
+import { page, database, customAgent } from "../index.js";
 
 import type {
 	CustomAgentAccess,
-	CustomAgentAccessRole,
 	CustomAgentArgs,
 	CustomAgentPropertyUpdatedTrigger,
 	CustomAgentTrustedUrls,
@@ -16,17 +17,26 @@ import type {
 } from "./index.js";
 
 it("types custom agent resource access and URL trust", () => {
-	expectTypeOf<
-		"full_access" | "can_edit_content" | "can_comment" | "can_view"
-	>().toEqualTypeOf<CustomAgentAccessRole>();
-	expectTypeOf<{
-		resourceId: "tasks";
-		role: "can_view";
-	}>().toExtend<CustomAgentAccess>();
-	expectTypeOf<{
-		resourceId: "tasks";
-		role: "read_and_write";
+	const home = page({ resourceId: "home" });
+	const tasks = database("tasks", {
+		dataSourceResourceId: "source",
+		name: "Tasks",
+		schema: { Title: { resourceId: "title", type: "title" } },
+	});
+	expectTypeOf(access.view(home)).toExtend<CustomAgentAccess>();
+	expectTypeOf(access.edit(tasks)).toExtend<CustomAgentAccess>();
+	expectTypeOf(access.view(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.comment(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.edit(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.fullAccess(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf<{
+		resource: typeof tasks.dataSource;
+		level: "view";
 	}>().not.toExtend<CustomAgentAccess>();
+	expectTypeOf<{ resourceId: "tasks"; role: "can_view" }>().not.toExtend<CustomAgentAccess>();
+	expectTypeOf(
+		access.call(customAgent({ resourceId: "agent", name: "Agent" })),
+	).not.toExtend<CustomAgentAccess>();
 	expectTypeOf<{ type: "all" }>().toEqualTypeOf<CustomAgentTrustedUrls>();
 	expectTypeOf<CustomAgentArgs["webAccess"]>().toEqualTypeOf<boolean | undefined>();
 	expectTypeOf<CustomAgentArgs["trustedUrls"]>().toEqualTypeOf<

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import { notion } from "./index.js";
+import { createProvisioningArtifact } from "./provisioning.js";
+import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
+import type { CustomViewSchema } from "./views.js";
+
+const customView: CustomViewSchema = {
+	resourceId: "tasks-board-view",
+	dataSourceResourceId: "tasks-source",
+	type: "custom",
+	customBlockKey: "board",
+};
+const databaseArgs = {
+	name: "Tasks",
+	dataSourceResourceId: "tasks-source",
+	schema: { Name: { resourceId: "task-name", type: "title" } },
+} as const;
+
+describe.each([
+	{
+		name: "standalone views",
+		declare: (view: CustomViewSchema) =>
+			notion.view({ ...view, databaseResourceId: "tasks-db" }),
+	},
+	{
+		name: "database views",
+		declare: (view: CustomViewSchema) =>
+			notion.database("tasks-db", { ...databaseArgs, views: [view] }),
+	},
+	{
+		name: "addView",
+		declare: (view: CustomViewSchema) =>
+			notion.database("tasks-db", databaseArgs).addView(view),
+	},
+])("provisioning $name", ({ declare }) => {
+	it.each([
+		["sorts", []],
+		["filters", []],
+		["properties", []],
+		["showPageIcon", true],
+		["defaultTemplate", "template"],
+	] as const)("rejects %s on custom views when creating the artifact", (field, value) => {
+		const recorder = startMetadataRecording();
+		// Extra fields can arrive from JavaScript callers despite the TypeScript contract.
+		declare({ ...customView, [field]: value });
+		const { intents } = finishMetadataRecording(recorder);
+
+		expect(() => createProvisioningArtifact(intents)).toThrow(
+			`Custom views do not support ${field}`,
+		);
+	});
+
+	it("rejects a blank custom block key when creating the artifact", () => {
+		const recorder = startMetadataRecording();
+		declare({ ...customView, customBlockKey: " " });
+		const { intents } = finishMetadataRecording(recorder);
+
+		expect(() => createProvisioningArtifact(intents)).toThrow("non-empty customBlockKey");
+	});
+
+	it("preserves the custom block key for server-side capability resolution", () => {
+		const recorder = startMetadataRecording();
+		declare(customView);
+		const { intents } = finishMetadataRecording(recorder);
+
+		expect(createProvisioningArtifact(intents).intents).toEqual(intents);
+	});
+});

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

@@ -1,4 +1,5 @@
 import type { InfraAsCodeIntent } from "./intents.js";
+import type { ViewSchema } from "./views.js";
 
 export const APPS_PROVISIONING_SCHEMA = "notion:apps-provisioning:v1";
 
@@ -24,6 +25,13 @@ export function createProvisioningArtifact(
 ): ProvisioningArtifact {
 	const provisioningIntents: ProvisioningIntent[] = [];
 	for (const intent of intents) {
+		if (intent.type === "view") {
+			validateCustomView(intent.view);
+		} else if (intent.type === "database") {
+			for (const view of intent.views ?? []) {
+				validateCustomView(view);
+			}
+		}
 		if (intent.type === "teamspace") {
 			const { parent: _parent, ...teamspace } = intent;
 			provisioningIntents.push(teamspace);
@@ -48,3 +56,22 @@ export function isRecordedProvisioning(value: unknown): value is RecordedProvisi
 		Array.isArray(value.intents)
 	);
 }
+
+function validateCustomView(view: ViewSchema): void {
+	if (view.type === "custom") {
+		if (typeof view.customBlockKey !== "string" || view.customBlockKey.trim() === "") {
+			throw new Error("Custom views require a non-empty customBlockKey");
+		}
+		for (const field of [
+			"sorts",
+			"filters",
+			"properties",
+			"showPageIcon",
+			"defaultTemplate",
+		] as const) {
+			if (field in view) {
+				throw new Error(`Custom views do not support ${field}`);
+			}
+		}
+	}
+}

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

@@ -3,11 +3,13 @@ import type { InfraAsCodeIntent } from "./intents.js";
 import type { RecordedProvisioning } from "./provisioning.js";
 
 let activeRecorder: RecordedProvisioning | undefined;
+let currentCapabilityKey: string | undefined;
 
 /** Start collecting declarations from the metadata bundle. */
 export function startMetadataRecording(): RecordedProvisioning {
 	const recorder: RecordedProvisioning = { intents: [] };
 	activeRecorder = recorder;
+	currentCapabilityKey = undefined;
 	return recorder;
 }
 
@@ -17,6 +19,7 @@ export function finishMetadataRecording(recorder: RecordedProvisioning): Recorde
 		throw new Error("Notion-as-Code metadata recorder was replaced before build completed");
 	}
 	activeRecorder = undefined;
+	currentCapabilityKey = undefined;
 	return recorder;
 }
 
@@ -24,3 +27,27 @@ export function finishMetadataRecording(recorder: RecordedProvisioning): Recorde
 export function recordIntent(intent: InfraAsCodeIntent): void {
 	activeRecorder?.intents.push(intent);
 }
+
+/** Evaluate one discovered capability with its build-time identity available to declarations. */
+export async function withMetadataCapabilityKey<T>(
+	capabilityKey: string | undefined,
+	evaluate: () => Promise<T>,
+): Promise<T> {
+	const previousCapabilityKey = currentCapabilityKey;
+	currentCapabilityKey = capabilityKey;
+	try {
+		return await evaluate();
+	} finally {
+		currentCapabilityKey = previousCapabilityKey;
+	}
+}
+
+/** Return the capability key only while a metadata bundle is recording. */
+export function getCurrentMetadataCapabilityKey(): string | undefined {
+	return activeRecorder === undefined ? undefined : currentCapabilityKey;
+}
+
+/** Whether declarations are currently being collected by the build metadata bundle. */
+export function isMetadataRecording(): boolean {
+	return activeRecorder !== undefined;
+}

package/src/notion-as-code/views-types.test.ts

@@ -1,6 +1,7 @@
 import { expectTypeOf, it } from "vitest";
 
 import type {
+	CustomViewSchema,
 	DatabaseArgs,
 	DatabaseHandle,
 	DatePropertyFilter,
@@ -8,6 +9,29 @@ import type {
 	ViewSchema,
 } from "./index.js";
 
+it("keeps custom views free of standard view query and property configuration", () => {
+	expectTypeOf<{
+		resourceId: "custom-view";
+		dataSourceResourceId: "source";
+		type: "custom";
+		customBlockKey: "board";
+	}>().toExtend<CustomViewSchema>();
+	expectTypeOf<{
+		resourceId: "custom-view";
+		dataSourceResourceId: "source";
+		type: "custom";
+		customBlockKey: "board";
+		sorts: [];
+	}>().not.toExtend<ViewSchema>();
+	expectTypeOf<{
+		resourceId: "custom-view";
+		dataSourceResourceId: "source";
+		type: "custom";
+		customBlockKey: "board";
+		properties: [];
+	}>().not.toExtend<ViewSchema>();
+});
+
 it("requires date properties for calendar and timeline views at both entrypoints", () => {
 	type MissingDateProperty = {
 		resourceId: "view";

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

@@ -1,7 +1,15 @@
 import type { NotionAsCodeIcon, NotionAsCodeProperty, ResourceId } from "./intents.js";
 
 // Ported from notion-next/src/server/helpers/infraAsCode/types.ts.
-export type ViewType = "table" | "board" | "calendar" | "list" | "gallery" | "feed" | "timeline";
+export type ViewType =
+	| "table"
+	| "board"
+	| "calendar"
+	| "list"
+	| "gallery"
+	| "feed"
+	| "timeline"
+	| "custom";
 
 export type PropertyVisibility = "show" | "hide" | "hide_if_empty";
 
@@ -563,6 +571,19 @@ export type TimelineViewSchema = BaseViewSchema & {
 	showTable?: boolean;
 };
 
+export type CustomViewSchema = Omit<
+	BaseViewSchema,
+	"type" | "sorts" | "filters" | "showPageIcon" | "defaultTemplate"
+> & {
+	type: "custom";
+	customBlockKey: string;
+	sorts?: never;
+	filters?: never;
+	properties?: never;
+	showPageIcon?: never;
+	defaultTemplate?: never;
+};
+
 export type ViewSchema =
 	| TableViewSchema
 	| BoardViewSchema
@@ -570,4 +591,5 @@ export type ViewSchema =
 	| ListViewSchema
 	| GalleryViewSchema
 	| FeedViewSchema
-	| TimelineViewSchema;
+	| TimelineViewSchema
+	| CustomViewSchema;