@notionhq/apps 0.0.17 → 0.0.18

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

@@ -1,197 +1,414 @@
 import type { Database } from "../database.js";
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
-	type DataSourceDefinition,
 	type DatabaseIntent,
+	type DataSourceDefinition,
 	type NotionAsCodeIcon,
 	type NotionAsCodeProperty,
+	type NotionAsCodeSchema,
 	type Parent,
 	type ResourceId,
 } from "./intents.js";
 import { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
-import { createAppsDatabase, type AppsSchemaForProperties } from "./schema.js";
+import { createAppsDatabase, type AppsSchemaForSchema } from "./schema.js";
 import type { ViewSchema } from "./views.js";
 
-/** Input for declaring a database and its optional data sources. */
-export type DatabaseArgs<
-	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
-> = {
+/** Reuse serialized database intent metadata, excluding identity, parent, and sources. */
+type DatabaseMetadata = Omit<DatabaseIntent, "resourceId" | "parent" | "dataSources">;
+
+type NonEmptyViewSchemas = readonly [ViewSchema, ...ViewSchema[]];
+
+/** A keyed data-source declaration; the containing map key supplies the serialized source name. */
+export type DataSourceArgs<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
 	resourceId: ResourceId;
-	/** Omit to create a private top-level database in the Apps workspace. */
-	parent?: Parent;
-	dataSources?: DataSources;
-	views?: readonly ViewSchema[];
+	name?: never;
+	schema: Schema;
 	icon?: NotionAsCodeIcon;
-	// TODO: Port cover types.
-	cover?: unknown;
-	hideDataSourceTitle?: boolean;
-	hideDatabaseTitleIfEmpty?: boolean;
-	name?: string;
-	description?: string;
 };
 
-/** Input for adding a database beneath an existing resource. */
-export type ChildDatabaseArgs<
-	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
-> = Omit<DatabaseArgs<DataSources>, "parent">;
+/** Data sources keyed by the names used to access their handles. */
+export type DataSourceMap = Record<string, DataSourceArgs>;
 
-/** Single-source shorthand; the source ID is `${resourceId}-source`. */
-export type SingleSourceDatabaseArgs<
-	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
-> = Omit<DatabaseArgs, "dataSources" | "name"> & {
+/**
+ * Single-source inputs require a name for both database and source. `datasources?: never`
+ * keeps this form exclusive even when callers pass a predeclared object.
+ */
+type SingleSourceDatabaseOptions<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = Omit<
+	DatabaseMetadata,
+	"name"
+> & {
+	dataSourceResourceId: ResourceId;
 	name: string;
-	properties: Properties;
-	dataSources?: never;
+	schema: Schema;
+	datasources?: never;
 };
 
-export type ChildSingleSourceDatabaseArgs<
-	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
-> = Omit<SingleSourceDatabaseArgs<Properties>, "parent">;
+/** Top-level single-source inputs may choose a parent; page.addDatabase/teamspace.addDatabase bind it instead. */
+export type SingleSourceDatabaseArgs<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	SingleSourceDatabaseOptions<Schema> & {
+		parent?: Parent;
+	};
+
+/**
+ * Multi-source inputs preserve source-map keys. The NoInfer guard makes the
+ * emptiness check inspect the inferred map instead of widening it to the broad
+ * DataSourceMap constraint.
+ */
+type MultiSourceDatabaseOptions<DataSources extends DataSourceMap = DataSourceMap> =
+	DatabaseMetadata & {
+		datasources: DataSources;
+		dataSourceResourceId?: never;
+		schema?: never;
+	} & (keyof NoInfer<DataSources> extends never
+			? { views: NonEmptyViewSchemas }
+			: { views?: readonly ViewSchema[] });
+
+/** Top-level multi-source inputs may choose a parent; page.addDatabase/teamspace.addDatabase bind it instead. */
+export type MultiSourceDatabaseArgs<DataSources extends DataSourceMap = DataSourceMap> =
+	MultiSourceDatabaseOptions<DataSources> & {
+		parent?: Parent;
+	};
 
-/** Resolves one data source ID to the properties declared for it. */
-type DataSourcePropertiesForResourceId<
-	DataSources extends readonly DataSourceDefinition[],
-	ResourceId extends DataSources[number]["resourceId"],
+/** Linked-only databases use a nonempty typed view tuple and no authored source map. */
+type ViewOnlyDatabaseOptions = DatabaseMetadata & {
+	datasources?: never;
+	dataSourceResourceId?: never;
+	schema?: never;
+	views: NonEmptyViewSchemas;
+};
+
+type ViewOnlyDatabaseArgs = ViewOnlyDatabaseOptions & {
+	parent?: Parent;
+};
+
+/** Remove parent because page.addDatabase/teamspace.addDatabase supplies it. */
+export type ChildSingleSourceDatabaseArgs<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	Omit<SingleSourceDatabaseArgs<Schema>, "parent">;
+
+/** Remove parent because page.addDatabase/teamspace.addDatabase supplies it. */
+export type ChildMultiSourceDatabaseArgs<DataSources extends DataSourceMap = DataSourceMap> = Omit<
+	MultiSourceDatabaseArgs<DataSources>,
+	"parent"
+>;
+
+/** Input for declaring a database and its data sources. */
+export type DatabaseArgs<
+	Schema extends NotionAsCodeSchema = NotionAsCodeSchema,
+	DataSources extends DataSourceMap = DataSourceMap,
+> = SingleSourceDatabaseArgs<Schema> | MultiSourceDatabaseArgs<DataSources> | ViewOnlyDatabaseArgs;
+
+/**
+ * Child inputs omit parent from each union member separately. `page.addDatabase`
+ * and `teamspace.addDatabase` use this shape for their shared child factory.
+ */
+export type ChildDatabaseArgs<
+	Schema extends NotionAsCodeSchema = NotionAsCodeSchema,
+	DataSources extends DataSourceMap = DataSourceMap,
 > =
-	Extract<DataSources[number], { resourceId: ResourceId }> extends DataSourceDefinition<
-		infer Properties
-	>
-		? Properties
-		: never;
-
-/** Handle for a data source and the Apps database it backs. */
-export type DataSourceHandle<
-	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
-> = {
+	| ChildSingleSourceDatabaseArgs<Schema>
+	| ChildMultiSourceDatabaseArgs<DataSources>
+	| Omit<ViewOnlyDatabaseArgs, "parent">;
+
+/** A source handle retains its keyed authoring schema for sync inference. */
+export type DataSourceHandle<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
 	readonly resourceId: string;
-	readonly schema: Properties;
-	readonly database: Database<AppsSchemaForProperties<Properties>>;
+	readonly schema: Schema;
+	readonly database: Database<AppsSchemaForSchema<Schema>>;
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
-/** Handle for a database with data sources indexed by resource ID. */
-export type DatabaseHandle<
-	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
-> = {
+type DatabaseHandleBase = {
 	readonly resourceId: string;
-	readonly dataSources: {
-		readonly [ResourceId in DataSources[number]["resourceId"]]: DataSourceHandle<
-			DataSourcePropertiesForResourceId<DataSources, ResourceId>
-		>;
-	};
 	addView: (view: ViewSchema) => void;
 };
 
-/** A database whose sole data source is available without an ID lookup. */
-export type SingleSourceDatabaseHandle<
-	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
-> = DatabaseHandle<readonly DataSourceDefinition<Properties>[]> & {
-	readonly dataSource: DataSourceHandle<Properties>;
-};
+/** Map each authoring source key to a handle backed by that source's own schema. */
+export type DatabaseHandle<DataSources extends DataSourceMap = DataSourceMap> =
+	DatabaseHandleBase & {
+		readonly datasources: {
+			readonly [DataSourceName in keyof DataSources]: DataSourceHandle<
+				DataSources[DataSourceName]["schema"]
+			>;
+		};
+	};
 
+/** A database whose sole data source is available without a key lookup. */
+export type SingleSourceDatabaseHandle<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	DatabaseHandleBase & {
+		readonly dataSource: DataSourceHandle<Schema>;
+	};
+
+/**
+ * Overloaded callable used by page.addDatabase/teamspace.addDatabase. Each form
+ * returns its matching handle while preserving literal source and schema inference.
+ */
 export type ChildDatabaseFactory = {
-	<const Properties extends readonly NotionAsCodeProperty[]>(
-		args: ChildSingleSourceDatabaseArgs<Properties>,
-	): SingleSourceDatabaseHandle<Properties>;
-	<const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources> & { properties?: never },
+	<const Schema extends NotionAsCodeSchema>(
+		databaseResourceId: ResourceId,
+		args: ChildSingleSourceDatabaseArgs<Schema>,
+	): SingleSourceDatabaseHandle<Schema>;
+	<const DataSources extends DataSourceMap>(
+		databaseResourceId: ResourceId,
+		args: ChildMultiSourceDatabaseArgs<DataSources>,
 	): DatabaseHandle<DataSources>;
+	(
+		databaseResourceId: ResourceId,
+		args: Omit<ViewOnlyDatabaseArgs, "parent">,
+	): DatabaseHandle<{}>;
 };
 
-/** Declare a database, defaulting to a private top-level database in the Apps workspace. */
-export function database<const Properties extends readonly NotionAsCodeProperty[]>(
-	args: SingleSourceDatabaseArgs<Properties>,
-): SingleSourceDatabaseHandle<Properties>;
-export function database<const DataSources extends readonly DataSourceDefinition[]>(
-	args: DatabaseArgs<DataSources> & { properties?: never },
+/** Declare a database, defaulting to the Apps workspace. */
+export function database<const Schema extends NotionAsCodeSchema>(
+	databaseResourceId: ResourceId,
+	args: SingleSourceDatabaseArgs<Schema>,
+): SingleSourceDatabaseHandle<Schema>;
+export function database<const DataSources extends DataSourceMap>(
+	databaseResourceId: ResourceId,
+	args: MultiSourceDatabaseArgs<DataSources>,
 ): DatabaseHandle<DataSources>;
 export function database(
-	args: DatabaseArgs | SingleSourceDatabaseArgs,
+	databaseResourceId: ResourceId,
+	args: ViewOnlyDatabaseArgs,
+): DatabaseHandle<{}>;
+export function database(
+	databaseResourceId: ResourceId,
+	args: DatabaseArgs,
 ): DatabaseHandle | SingleSourceDatabaseHandle {
-	if (args.parent) {
-		assertParent(args.parent);
+	if (typeof args !== "object" || args === null || Array.isArray(args)) {
+		throw new Error("Notion-as-Code database arguments must be an object");
 	}
-	const parent = args.parent ?? {
-		type: "resourceId",
+	const parentValue = args.parent;
+	if (parentValue !== undefined) {
+		assertParent(parentValue);
+	}
+	const parent = parentValue ?? {
+		type: "resourceId" as const,
 		resourceId: APPS_WORKSPACE_RESOURCE_ID,
 	};
-	if ("properties" in args) {
-		if (args.dataSources !== undefined) {
-			throw new Error("Specify either properties or dataSources, not both");
-		}
-		const { properties, ...databaseArgs } = args;
+	return buildDatabaseHandle(databaseResourceId, args, parent);
+}
+
+/** Bind a parent for page.addDatabase/teamspace.addDatabase. */
+export function createChildDatabase(parent: Parent): ChildDatabaseFactory {
+	assertParent(parent);
+
+	function addDatabase<const Schema extends NotionAsCodeSchema>(
+		databaseResourceId: ResourceId,
+		args: ChildSingleSourceDatabaseArgs<Schema>,
+	): SingleSourceDatabaseHandle<Schema>;
+	function addDatabase<const DataSources extends DataSourceMap>(
+		databaseResourceId: ResourceId,
+		args: ChildMultiSourceDatabaseArgs<DataSources>,
+	): DatabaseHandle<DataSources>;
+	function addDatabase(
+		databaseResourceId: ResourceId,
+		args: Omit<ViewOnlyDatabaseArgs, "parent">,
+	): DatabaseHandle<{}>;
+	function addDatabase(
+		databaseResourceId: ResourceId,
+		args: ChildDatabaseArgs,
+	): DatabaseHandle | SingleSourceDatabaseHandle {
+		return buildDatabaseHandle(databaseResourceId, args, parent);
+	}
+
+	return addDatabase;
+}
+/**
+ * Internal bridge pairing an authoring key/schema with its serialized definition
+ * during database recording and handle creation; never serialized itself.
+ */
+type SourceEntry = {
+	key: string;
+	schema: NotionAsCodeSchema;
+	definition: DataSourceDefinition;
+};
+
+/**
+ * Build a database handle from one of the authoring forms. Form checks happen
+ * before normalization or recording so mixed and malformed declarations are atomic.
+ */
+function buildDatabaseHandle(
+	databaseResourceId: ResourceId,
+	args: DatabaseArgs,
+	parent: Parent,
+): DatabaseHandle | SingleSourceDatabaseHandle {
+	if (typeof args !== "object" || args === null || Array.isArray(args)) {
+		throw new Error("Notion-as-Code database arguments must be an object");
+	}
+	if (typeof databaseResourceId !== "string") {
+		throw new Error("Notion-as-Code database resourceId must be a string");
+	}
+	assertUserResourceId(databaseResourceId);
+
+	const hasSchema = Object.prototype.hasOwnProperty.call(args, "schema");
+	const hasDataSources = Object.prototype.hasOwnProperty.call(args, "datasources");
+	if (hasSchema && hasDataSources) {
+		throw new Error("Specify either schema or datasources, not both");
+	}
+
+	if (args.schema !== undefined) {
 		const source: DataSourceDefinition = {
-			resourceId: `${args.resourceId}-source`,
+			resourceId: args.dataSourceResourceId,
 			name: args.name,
-			properties,
+			properties: normalizeProperties(args.schema),
 		};
-		const handle = createDatabase({ ...databaseArgs, dataSources: [source] }, parent);
-		const dataSource = handle.dataSources[source.resourceId];
-		if (!dataSource) {
-			throw new Error(`Missing data source "${source.resourceId}"`);
+		const handle = recordDatabase(databaseResourceId, args, parent, [
+			{ key: "dataSource", schema: args.schema, definition: source },
+		]);
+		const dataSource = handle.datasources.dataSource;
+		if (dataSource === undefined) {
+			throw new Error(`Database "${databaseResourceId}" is missing its data source`);
 		}
-		return { ...handle, dataSource };
+		return {
+			resourceId: databaseResourceId,
+			dataSource,
+			addView: handle.addView,
+		};
 	}
-	return createDatabase(args, parent);
+
+	if (args.datasources !== undefined) {
+		if (
+			typeof args.datasources !== "object" ||
+			args.datasources === null ||
+			Array.isArray(args.datasources)
+		) {
+			throw new Error("Notion-as-Code datasources must be an object");
+		}
+		const sourceEntries = Object.entries(args.datasources).map(([key, sourceArgs]) =>
+			normalizeDataSource(key, sourceArgs),
+		);
+		return recordDatabase(databaseResourceId, args, parent, sourceEntries);
+	}
+
+	return recordDatabase(databaseResourceId, args, parent, []);
 }
 
-/** Bind both database declaration forms to an existing parent. */
-export function createChildDatabase(parent: Parent): ChildDatabaseFactory {
-	function addDatabase<const Properties extends readonly NotionAsCodeProperty[]>(
-		args: ChildSingleSourceDatabaseArgs<Properties>,
-	): SingleSourceDatabaseHandle<Properties>;
-	function addDatabase<const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources> & { properties?: never },
-	): DatabaseHandle<DataSources>;
-	function addDatabase(
-		args: ChildDatabaseArgs | ChildSingleSourceDatabaseArgs,
-	): DatabaseHandle | SingleSourceDatabaseHandle {
-		if ("properties" in args) {
-			return database({ ...args, parent });
+/** Strip authoring-only fields from database arguments before serializing metadata. */
+function normalizeDatabaseMetadata(args: DatabaseArgs): DatabaseMetadata {
+	const {
+		parent: _parent,
+		schema: _schema,
+		datasources: _datasources,
+		dataSourceResourceId: _dataSourceResourceId,
+		...metadata
+	} = args;
+	return metadata;
+}
+
+/** Normalize a keyed declaration into its serialized definition while retaining key/schema for handles. */
+function normalizeDataSource(key: string, sourceArgs: DataSourceArgs): SourceEntry {
+	if (typeof sourceArgs !== "object" || sourceArgs === null || Array.isArray(sourceArgs)) {
+		throw new Error(`Data source "${key}" must be an object`);
+	}
+	const { schema, ...sourceMetadata } = sourceArgs;
+	return {
+		key,
+		schema,
+		definition: {
+			...sourceMetadata,
+			name: key,
+			properties: normalizeProperties(schema),
+		},
+	};
+}
+
+/**
+ * Normalize keyed property configurations to the serialized property array.
+ * Property names always come from schema keys; authoring name fields are ignored.
+ */
+function normalizeProperties(schema: NotionAsCodeSchema): NotionAsCodeProperty[] {
+	if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+		throw new Error("Notion-as-Code schema must be an object");
+	}
+	const properties: NotionAsCodeProperty[] = [];
+	for (const [key, propertyConfig] of Object.entries(schema)) {
+		if (
+			typeof propertyConfig !== "object" ||
+			propertyConfig === null ||
+			Array.isArray(propertyConfig)
+		) {
+			throw new Error(`Property "${key}" must be an object`);
 		}
-		return database({ ...args, parent });
+		if (typeof propertyConfig.resourceId !== "string") {
+			throw new Error(`Property "${key}" must specify a resourceId`);
+		}
+		properties.push({
+			...propertyConfig,
+			name: key,
+		});
 	}
-	return addDatabase;
+	return properties;
 }
 
-/** Record a database declaration and create handles for each of its data sources. */
-export function createDatabase(args: DatabaseArgs, parent: Parent): DatabaseHandle {
-	assertUserResourceId(args.resourceId);
-	const dataSources = args.dataSources ?? [];
+/** Validate the views shape and require at least one data source or view. */
+function assertSourceOrView(sourceEntries: readonly SourceEntry[], views: unknown): void {
+	if (views !== undefined && !Array.isArray(views)) {
+		throw new Error("Notion-as-Code database views must be an array");
+	}
+	if (sourceEntries.length === 0 && (!Array.isArray(views) || views.length === 0)) {
+		throw new Error("Notion-as-Code database must define a data source or view");
+	}
+}
+
+/** Record a normalized database intent and create handles for its data sources. */
+function recordDatabase(
+	databaseResourceId: ResourceId,
+	args: DatabaseArgs,
+	parent: Parent,
+	sourceEntries: readonly SourceEntry[],
+): DatabaseHandle {
+	const metadata = normalizeDatabaseMetadata(args);
+	assertSourceOrView(sourceEntries, metadata.views);
+	const intent: DatabaseIntent = {
+		...metadata,
+		resourceId: databaseResourceId,
+		parent,
+		dataSources: sourceEntries.map(({ definition }) => definition),
+	};
+	return createDatabase(intent, sourceEntries);
+}
+
+/** Create a normalized database handle while preserving each source's authoring schema. */
+function createDatabase(
+	intent: DatabaseIntent,
+	sourceEntries: readonly SourceEntry[],
+): DatabaseHandle {
+	assertUserResourceId(intent.resourceId);
 	const dataSourceIds = new Set<string>();
-	const handles: Record<string, DataSourceHandle> = {};
+	const handles: Record<string, DataSourceHandle> = Object.create(null);
 
-	for (const dataSource of dataSources) {
-		assertUserResourceId(dataSource.resourceId);
-		if (dataSourceIds.has(dataSource.resourceId)) {
+	for (const { key, schema, definition } of sourceEntries) {
+		if (typeof definition.resourceId !== "string") {
+			throw new Error(`Data source "${key}" must specify a resourceId`);
+		}
+		assertUserResourceId(definition.resourceId);
+		if (dataSourceIds.has(definition.resourceId)) {
 			throw new Error(
-				`Database "${args.resourceId}" has duplicate data source "${dataSource.resourceId}"`,
+				`Database "${intent.resourceId}" has duplicate data source "${definition.resourceId}"`,
 			);
 		}
-		dataSourceIds.add(dataSource.resourceId);
-		handles[dataSource.resourceId] = createDataSourceHandle(dataSource);
+		dataSourceIds.add(definition.resourceId);
+		handles[key] = createDataSourceHandle(definition, schema);
 	}
 
-	recordIntent({
-		type: "database",
-		...args,
-		parent,
-		dataSources: [...dataSources],
-	} satisfies { type: "database" } & DatabaseIntent);
+	recordIntent({ ...intent, type: "database" });
 
 	return {
-		resourceId: args.resourceId,
-		dataSources: handles,
+		resourceId: intent.resourceId,
+		datasources: handles,
 		addView(view) {
-			recordIntent({ type: "view", databaseResourceId: args.resourceId, view });
+			recordIntent({ type: "view", databaseResourceId: intent.resourceId, view });
 		},
 	};
 }
 
-/** Create a data source handle backed by the Apps database used by syncs. */
-function createDataSourceHandle(dataSource: DataSourceDefinition): DataSourceHandle {
+/** Create a data-source handle backed by the Apps database used by syncs. */
+function createDataSourceHandle(
+	dataSource: DataSourceDefinition,
+	schema: NotionAsCodeSchema,
+): DataSourceHandle {
 	const propertyResourceIds = new Set<string>();
 	const propertyNames = new Set<string>();
 	for (const property of dataSource.properties) {
@@ -212,7 +429,7 @@ function createDataSourceHandle(dataSource: DataSourceDefinition): DataSourceHan
 
 	return {
 		resourceId: dataSource.resourceId,
-		schema: dataSource.properties,
+		schema,
 		database: createAppsDatabase(dataSource.resourceId, dataSource),
 		addPage(pageArgs) {
 			return createPage(pageArgs, { type: "resourceId", resourceId: dataSource.resourceId });

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

@@ -1,15 +1,30 @@
 import { createNotion } from "./handles.js";
 
 export { APPS_RESERVED_RESOURCE_ID_PREFIX, APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
-export type { DataSourceDefinition, NotionAsCodeProperty, Parent } from "./intents.js";
+export type {
+	DatabaseIntent,
+	DataSourceDefinition,
+	NotionAsCodeIcon,
+	NotionAsCodeProperty,
+	NotionAsCodePropertyConfig,
+	NotionAsCodeSchema,
+	NotionAsCodeSelectOption,
+	NotionAsCodeStatusOption,
+	Parent,
+	ResourceId,
+} from "./intents.js";
 export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
 export type {
 	ChildDatabaseArgs,
 	ChildDatabaseFactory,
+	ChildMultiSourceDatabaseArgs,
 	ChildSingleSourceDatabaseArgs,
+	DataSourceArgs,
 	DataSourceHandle,
+	DataSourceMap,
 	DatabaseArgs,
 	DatabaseHandle,
+	MultiSourceDatabaseArgs,
 	SingleSourceDatabaseArgs,
 	SingleSourceDatabaseHandle,
 } from "./database.js";

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

@@ -1,5 +1,4 @@
 import type { CustomAgentArgs } from "./custom-agent.js";
-import type { DatabaseArgs } from "./database.js";
 import type { PageArgs } from "./page.js";
 import type { TeamspaceArgs } from "./teamspace.js";
 import type { ViewSchema } from "./views.js";
@@ -66,6 +65,7 @@ type UnsupportedProperty = PropertyBase & {
 	[key: string]: unknown;
 };
 
+/** A normalized Notion-as-Code property with its resolved display name. */
 export type NotionAsCodeProperty =
 	| (PropertyBase & { type: "title" })
 	| (PropertyBase & { type: "text" })
@@ -92,6 +92,28 @@ export type NotionAsCodeProperty =
 	| (PropertyBase & { type: "file" })
 	| UnsupportedProperty;
 
+/**
+ * `T extends unknown` applies Omit to each property variant separately, preserving
+ * variant-specific fields such as required status options. Plain Omit on the union
+ * would retain only shared keys. Pick also restores type/resourceId on the
+ * unsupported variant, whose string index signature would otherwise erase them.
+ */
+type DistributivePropertyConfig<T extends NotionAsCodeProperty> = T extends unknown
+	? Omit<T, "name"> & Pick<T, "type" | "resourceId">
+	: never;
+
+/**
+ * Authoring properties are keyed by their schema object name. A property-level
+ * `name` override would make the key and serialized property diverge, so it is
+ * explicitly rejected even for the string-indexed unsupported-property variant.
+ */
+export type NotionAsCodePropertyConfig = DistributivePropertyConfig<NotionAsCodeProperty> & {
+	name?: never;
+};
+/** A keyed property schema, with object keys supplying serialized property names. */
+export type NotionAsCodeSchema = Record<string, NotionAsCodePropertyConfig>;
+
+/** The normalized data-source shape emitted in provisioning artifacts. */
 export type DataSourceDefinition<
 	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
 > = {
@@ -107,9 +129,24 @@ export type TeamspaceIntent = TeamspaceArgs & {
 	parent: Parent;
 };
 
-export type DatabaseIntent = DatabaseArgs & {
+/**
+ * The normalized database shape emitted in provisioning artifacts.
+ *
+ * This intentionally does not depend on the authoring argument shape. Authoring
+ * accepts keyed schemas and data-source maps; the recorder always stores arrays.
+ */
+export type DatabaseIntent = {
+	resourceId: ResourceId;
 	parent: Parent;
 	dataSources: readonly DataSourceDefinition[];
+	views?: readonly ViewSchema[];
+	icon?: NotionAsCodeIcon;
+	// TODO: Port cover types.
+	cover?: unknown;
+	hideDataSourceTitle?: boolean;
+	hideDatabaseTitleIfEmpty?: boolean;
+	name?: string;
+	description?: string;
 };
 
 export type PageIntent = PageArgs & { parent: Parent };