@notionhq/apps 0.0.20 → 0.0.21

package/src/notion-as-code/custom-agent.ts

@@ -2,6 +2,105 @@ import type { CustomAgentIntent, NotionAsCodeIcon, ResourceId } from "./intents.
 import { recordIntent } from "./recorder.js";
 import { assertUserResourceId } from "./resource.js";
 
+type RecurrenceWeekday = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
+
+/** A nonempty selection of weekdays for a weekly recurrence. */
+export type RecurrenceWeekdays = {
+	[Day in RecurrenceWeekday]?: true;
+} & {
+	[Day in RecurrenceWeekday]: Required<Pick<Record<RecurrenceWeekday, true>, Day>>;
+}[RecurrenceWeekday];
+
+export type MonthlyWeekdayOccurrence = "1st" | "2nd" | "3rd" | "4th" | "last";
+
+export type MonthlyRecurrenceRestriction =
+	| { type: "day_of_month"; day: number }
+	| {
+			type: "weekday_of_month";
+			weekday: RecurrenceWeekday;
+			occurrence: MonthlyWeekdayOccurrence;
+	  };
+
+export type RecurrenceScheduleEnd =
+	| { type: "date"; endsAt: string }
+	| { type: "occurrences"; count: number };
+
+type RecurrenceScheduleBase = {
+	interval: number;
+	start: string;
+	timeZone: string;
+	end?: RecurrenceScheduleEnd;
+};
+
+export type HourlyRecurrenceSchedule = RecurrenceScheduleBase & {
+	frequency: "hour";
+};
+
+export type DailyRecurrenceSchedule = RecurrenceScheduleBase & {
+	frequency: "day";
+};
+
+export type WeeklyRecurrenceSchedule = RecurrenceScheduleBase & {
+	frequency: "week";
+	weekdays: RecurrenceWeekdays;
+};
+
+export type MonthlyRecurrenceSchedule = RecurrenceScheduleBase & {
+	frequency: "month";
+	monthlyRestriction: MonthlyRecurrenceRestriction;
+};
+
+export type YearlyRecurrenceSchedule = RecurrenceScheduleBase & {
+	frequency: "year";
+};
+
+export type CustomAgentRecurrenceSchedule = (
+	| HourlyRecurrenceSchedule
+	| DailyRecurrenceSchedule
+	| WeeklyRecurrenceSchedule
+	| MonthlyRecurrenceSchedule
+	| YearlyRecurrenceSchedule
+) & {
+	type: "recurrence";
+};
+
+export type CustomAgentTriggerBase = {
+	resourceId: ResourceId;
+	enabled?: boolean;
+};
+
+export type CustomAgentRecurrenceTrigger = CustomAgentTriggerBase & CustomAgentRecurrenceSchedule;
+
+export type PropertyTriggerCondition = {
+	type: "property_edited";
+};
+
+export type CustomAgentPageAddedTrigger = CustomAgentTriggerBase & {
+	type: "page_added";
+	dataSourceResourceId: ResourceId;
+};
+
+type PropertyUpdatedTriggerTarget =
+	| {
+			propertyConditions: Readonly<Record<ResourceId, PropertyTriggerCondition>>;
+			triggerWhenPageContentEdited?: boolean;
+	  }
+	| {
+			propertyConditions?: never;
+			triggerWhenPageContentEdited: true;
+	  };
+
+export type CustomAgentPropertyUpdatedTrigger = CustomAgentTriggerBase &
+	PropertyUpdatedTriggerTarget & {
+		type: "property_updated";
+		dataSourceResourceId: ResourceId;
+	};
+
+export type CustomAgentTrigger =
+	| CustomAgentRecurrenceTrigger
+	| CustomAgentPageAddedTrigger
+	| CustomAgentPropertyUpdatedTrigger;
+
 export type CustomAgentArgs = {
 	resourceId: ResourceId;
 	name: string;
@@ -9,8 +108,7 @@ export type CustomAgentArgs = {
 	instructions?: string;
 	model?: "ambrosia-tart-high" | "opal-quince-medium" | "almond-croissant-low";
 	sharedResources?: readonly ResourceId[];
-	// TODO: Port custom agent trigger types.
-	triggers?: readonly unknown[];
+	triggers?: readonly CustomAgentTrigger[];
 };
 
 export type CustomAgentHandle = {
@@ -24,6 +122,17 @@ export function customAgent(args: CustomAgentArgs): CustomAgentHandle {
 	for (const resourceId of args.sharedResources ?? []) {
 		assertUserResourceId(resourceId);
 	}
+	for (const trigger of args.triggers ?? []) {
+		assertUserResourceId(trigger.resourceId);
+		if (trigger.type === "page_added" || trigger.type === "property_updated") {
+			assertUserResourceId(trigger.dataSourceResourceId);
+		}
+		if (trigger.type === "property_updated") {
+			for (const propertyResourceId of Object.keys(trigger.propertyConditions ?? {})) {
+				assertUserResourceId(propertyResourceId);
+			}
+		}
+	}
 	recordIntent({ type: "custom_agent", ...args } satisfies {
 		type: "custom_agent";
 	} & CustomAgentIntent);

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

@@ -8,6 +8,44 @@ import { APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
 import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
 
 describe("Notion-as-Code database declarations", () => {
+	it("records a single-source page layout on the data source", () => {
+		const recorder = startMetadataRecording();
+
+		notion.database("layout-database", {
+			dataSourceResourceId: "layout-source",
+			name: "Tasks",
+			schema: {
+				Name: { type: "title", resourceId: "name" },
+				Estimate: { type: "number", resourceId: "estimate" },
+			},
+			pageLayout: {
+				main: [
+					{ type: "properties", properties: [{ property: "name" }] },
+					{ type: "property", property: "estimate", style: "large" },
+				],
+				pinnedProperties: ["estimate"],
+			},
+		});
+
+		expect(finishMetadataRecording(recorder).intents).toEqual([
+			expect.objectContaining({
+				resourceId: "layout-database",
+				dataSources: [
+					expect.objectContaining({
+						resourceId: "layout-source",
+						pageLayout: {
+							main: [
+								{ type: "properties", properties: [{ property: "name" }] },
+								{ type: "property", property: "estimate", style: "large" },
+							],
+							pinnedProperties: ["estimate"],
+						},
+					}),
+				],
+			}),
+		]);
+	});
+
 	it("converts the single-source form with keyed schemas and resolved property names", () => {
 		const recorder = startMetadataRecording();
 		const schema = {

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

@@ -2,6 +2,7 @@ import type { Database } from "../database.js";
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
 	type DatabaseIntent,
+	type DatabasePageLayout,
 	type DataSourceDefinition,
 	type NotionAsCodeIcon,
 	type NotionAsCodeProperty,
@@ -26,6 +27,7 @@ export type DataSourceArgs<Schema extends NotionAsCodeSchema = NotionAsCodeSchem
 	name?: never;
 	schema: Schema;
 	icon?: NotionAsCodeIcon;
+	pageLayout?: DatabasePageLayout<Schema>;
 };
 
 /** Data sources keyed by the names used to access their handles. */
@@ -42,6 +44,7 @@ type SingleSourceDatabaseOptions<Schema extends NotionAsCodeSchema = NotionAsCod
 	dataSourceResourceId: ResourceId;
 	name: string;
 	schema: Schema;
+	pageLayout?: DatabasePageLayout<Schema>;
 	datasources?: never;
 };
 
@@ -61,6 +64,7 @@ type MultiSourceDatabaseOptions<DataSources extends DataSourceMap = DataSourceMa
 		datasources: DataSources;
 		dataSourceResourceId?: never;
 		schema?: never;
+		pageLayout?: never;
 	} & (keyof NoInfer<DataSources> extends never
 			? { views: NonEmptyViewSchemas }
 			: { views?: readonly ViewSchema[] });
@@ -76,6 +80,7 @@ type ViewOnlyDatabaseOptions = DatabaseMetadata & {
 	datasources?: never;
 	dataSourceResourceId?: never;
 	schema?: never;
+	pageLayout?: never;
 	views: NonEmptyViewSchemas;
 };
 
@@ -255,6 +260,7 @@ function buildDatabaseHandle(
 			resourceId: args.dataSourceResourceId,
 			name: args.name,
 			properties: normalizeProperties(args.schema),
+			...(args.pageLayout === undefined ? {} : { pageLayout: args.pageLayout }),
 		};
 		const handle = recordDatabase(databaseResourceId, args, parent, [
 			{ key: "dataSource", schema: args.schema, definition: source },
@@ -295,6 +301,7 @@ function normalizeDatabaseMetadata(args: DatabaseArgs): DatabaseMetadata {
 		schema: _schema,
 		datasources: _datasources,
 		dataSourceResourceId: _dataSourceResourceId,
+		pageLayout: _pageLayout,
 		...metadata
 	} = args;
 	return metadata;

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

@@ -2,6 +2,9 @@ import { createNotion } from "./handles.js";
 
 export { APPS_RESERVED_RESOURCE_ID_PREFIX, APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
 export type {
+	ContentPageLayoutTab,
+	DatabasePageLayout,
+	DatabasePageLayoutTab,
 	DatabaseIntent,
 	DataSourceDefinition,
 	NotionAsCodeIcon,
@@ -10,10 +13,45 @@ export type {
 	NotionAsCodeSchema,
 	NotionAsCodeSelectOption,
 	NotionAsCodeStatusOption,
+	PageCoverReference,
+	PageLayoutMainModule,
+	PageLayoutNumberAndFormulaStyle,
+	PageLayoutPersonStyle,
+	PageLayoutPropertiesModule,
+	PageLayoutPropertyConfig,
+	PageLayoutPropertyModule,
+	PageLayoutPropertySection,
+	PageLayoutRelationConfig,
+	PageLayoutRelationsGroupModule,
+	PageLayoutSidebarModule,
 	Parent,
 	ResourceId,
+	RollupBaseAggregationType,
+	RollupDateAggregationType,
+	RollupNumberAggregationType,
+	RollupTargetPropertyType,
+	ViewPageLayoutTab,
 } from "./intents.js";
-export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
+export type {
+	CustomAgentArgs,
+	CustomAgentHandle,
+	CustomAgentPageAddedTrigger,
+	CustomAgentPropertyUpdatedTrigger,
+	CustomAgentRecurrenceSchedule,
+	CustomAgentRecurrenceTrigger,
+	CustomAgentTrigger,
+	CustomAgentTriggerBase,
+	DailyRecurrenceSchedule,
+	HourlyRecurrenceSchedule,
+	MonthlyRecurrenceRestriction,
+	MonthlyRecurrenceSchedule,
+	MonthlyWeekdayOccurrence,
+	PropertyTriggerCondition,
+	RecurrenceScheduleEnd,
+	RecurrenceWeekdays,
+	WeeklyRecurrenceSchedule,
+	YearlyRecurrenceSchedule,
+} from "./custom-agent.js";
 export type {
 	ChildDatabaseArgs,
 	ChildDatabaseFactory,

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

@@ -21,6 +21,14 @@ export type NotionAsCodeIcon =
 	| { type: "notion_icon"; description: string; color?: string }
 	| { type: "file"; resourceId: ResourceId };
 
+/** A URL reference used as a page or database cover. */
+export type PageCoverReference = {
+	type: "url";
+	url: string;
+	/** Vertical position from the top, where 0 is the top and 1 is the bottom. */
+	position?: number;
+};
+
 export type NotionAsCodeSelectColor =
 	| "default"
 	| "gray"
@@ -49,20 +57,102 @@ type PropertyBase = {
 	description?: string;
 };
 
-type UnsupportedProperty = PropertyBase & {
-	type:
-		| "relation"
-		| "formula"
-		| "rollup"
-		| "created_time"
-		| "last_edited_time"
-		| "created_by"
-		| "last_edited_by"
-		| "auto_increment_id"
-		| "person"
-		| "verification";
-	// TODO: Port configuration types for unsupported property kinds.
-	[key: string]: unknown;
+/** Rollup aggregations supported for every target property type. */
+export type RollupBaseAggregationType =
+	| "count"
+	| "count_values"
+	| "unique"
+	| "empty"
+	| "not_empty"
+	| "percent_empty"
+	| "percent_not_empty"
+	| "show_unique";
+
+/** Numeric-only rollup aggregations. */
+export type RollupNumberAggregationType =
+	| RollupBaseAggregationType
+	| "sum"
+	| "average"
+	| "median"
+	| "min"
+	| "max"
+	| "range";
+
+/** Date-only rollup aggregations. */
+export type RollupDateAggregationType =
+	| RollupBaseAggregationType
+	| "earliest_date"
+	| "latest_date"
+	| "date_range";
+
+export type RollupTargetPropertyType =
+	| "title"
+	| "text"
+	| "number"
+	| "select"
+	| "multi_select"
+	| "status"
+	| "date"
+	| "checkbox"
+	| "url"
+	| "email"
+	| "phone_number"
+	| "relation"
+	| "person"
+	| "created_time"
+	| "last_edited_time"
+	| "created_by"
+	| "last_edited_by";
+
+type RollupTarget =
+	| {
+			targetPropertyType: "number";
+			aggregation?: RollupNumberAggregationType;
+	  }
+	| {
+			targetPropertyType: "date" | "created_time" | "last_edited_time";
+			aggregation?: RollupDateAggregationType;
+	  }
+	| {
+			targetPropertyType: Exclude<
+				RollupTargetPropertyType,
+				"number" | "date" | "created_time" | "last_edited_time"
+			>;
+			aggregation?: RollupBaseAggregationType;
+	  };
+
+type RelationProperty = PropertyBase & {
+	type: "relation";
+	targetDataSourceResourceId: ResourceId;
+	targetDataSourcePropertyResourceId?: ResourceId;
+	limit?: 1;
+};
+
+type FormulaProperty = PropertyBase & {
+	type: "formula";
+	expression?: string;
+};
+
+type RollupProperty = PropertyBase &
+	RollupTarget & {
+		type: "rollup";
+		relationPropertyResourceId: ResourceId;
+		targetPropertyResourceId: ResourceId;
+	};
+
+type AutoIncrementIdProperty = PropertyBase & {
+	type: "auto_increment_id";
+	prefix?: string;
+};
+
+type PersonProperty = PropertyBase & {
+	type: "person";
+	limit?: 1;
+};
+
+type VerificationProperty = PropertyBase & {
+	type: "verification";
+	verifierPropertyResourceId: ResourceId;
 };
 
 /** A normalized Notion-as-Code property with its resolved display name. */
@@ -90,22 +180,29 @@ export type NotionAsCodeProperty =
 	| (PropertyBase & { type: "email" })
 	| (PropertyBase & { type: "phone_number" })
 	| (PropertyBase & { type: "file" })
-	| UnsupportedProperty;
+	| RelationProperty
+	| FormulaProperty
+	| RollupProperty
+	| (PropertyBase & { type: "created_time" })
+	| (PropertyBase & { type: "last_edited_time" })
+	| (PropertyBase & { type: "created_by" })
+	| (PropertyBase & { type: "last_edited_by" })
+	| AutoIncrementIdProperty
+	| PersonProperty
+	| VerificationProperty;
 
 /**
  * `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.
+ * would retain only shared keys.
  */
 type DistributivePropertyConfig<T extends NotionAsCodeProperty> = T extends unknown
-	? Omit<T, "name"> & Pick<T, "type" | "resourceId">
+	? Omit<T, "name">
 	: 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.
+ * `name` override would make the key and serialized property diverge.
  */
 export type NotionAsCodePropertyConfig = DistributivePropertyConfig<NotionAsCodeProperty> & {
 	name?: never;
@@ -113,6 +210,106 @@ export type NotionAsCodePropertyConfig = DistributivePropertyConfig<NotionAsCode
 /** A keyed property schema, with object keys supplying serialized property names. */
 export type NotionAsCodeSchema = Record<string, NotionAsCodePropertyConfig>;
 
+type SchemaProperty<Schema extends NotionAsCodeSchema> = Schema[keyof Schema & string];
+type PropertyType = NotionAsCodePropertyConfig["type"];
+type PropertyResourceIdFor<
+	Schema extends NotionAsCodeSchema,
+	Types extends PropertyType = PropertyType,
+> = Extract<SchemaProperty<Schema>, { type: Types }>["resourceId"];
+
+export type PageLayoutPropertyConfig<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	property: PropertyResourceIdFor<Schema>;
+	visibility?: "show" | "hide_if_empty" | "hide";
+};
+
+export type PageLayoutPropertySection<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	name: string;
+	properties: readonly PageLayoutPropertyConfig<Schema>[];
+};
+
+export type PageLayoutPropertiesModule<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	type: "properties";
+} & (
+	| {
+			properties?: readonly PageLayoutPropertyConfig<Schema>[];
+			sections?: never;
+	  }
+	| {
+			sections: readonly PageLayoutPropertySection<Schema>[];
+			properties?: never;
+	  }
+);
+
+export type PageLayoutPersonStyle = "compact" | "large";
+export type PageLayoutNumberAndFormulaStyle = "large" | "small";
+
+type PageLayoutStyleFor<Property extends NotionAsCodePropertyConfig> = Property["type"] extends
+	| "person"
+	| "created_by"
+	| "last_edited_by"
+	? { style?: PageLayoutPersonStyle }
+	: Property["type"] extends "number" | "formula"
+		? { style?: PageLayoutNumberAndFormulaStyle }
+		: { style?: never };
+
+type PageLayoutPropertyModuleFor<Property extends NotionAsCodePropertyConfig> =
+	Property extends unknown
+		? {
+				type: "property";
+				property: Property["resourceId"];
+			} & PageLayoutStyleFor<Property>
+		: never;
+
+/**
+ * A standalone property module. Its available style is inferred from the
+ * referenced property's type when the layout is declared with a literal schema.
+ */
+export type PageLayoutPropertyModule<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	PageLayoutPropertyModuleFor<SchemaProperty<Schema>>;
+
+export type PageLayoutRelationConfig<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	property: PropertyResourceIdFor<Schema, "relation">;
+	display: "pageSection" | "minimal";
+};
+
+export type PageLayoutRelationsGroupModule<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	{
+		type: "relations";
+		relations: readonly PageLayoutRelationConfig<Schema>[];
+	};
+
+export type PageLayoutMainModule<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	| PageLayoutPropertiesModule<Schema>
+	| PageLayoutPropertyModule<Schema>
+	| PageLayoutRelationsGroupModule<Schema>;
+
+export type PageLayoutSidebarModule<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> =
+	| PageLayoutPropertiesModule<Schema>
+	| PageLayoutPropertyModule<Schema>;
+
+export type ContentPageLayoutTab = {
+	type: "content";
+	name?: string;
+};
+
+export type ViewPageLayoutTab = {
+	type: "view";
+	resourceId: ResourceId;
+};
+
+export type DatabasePageLayoutTab = ContentPageLayoutTab | ViewPageLayoutTab;
+
+export type DatabasePageLayout<Schema extends NotionAsCodeSchema = NotionAsCodeSchema> = {
+	main: readonly PageLayoutMainModule<Schema>[];
+	sidebar?: readonly PageLayoutSidebarModule<Schema>[];
+	pinnedProperties?: readonly PropertyResourceIdFor<Schema>[];
+	discussions?: "top" | "bottom" | "hidden";
+	tabs?: readonly DatabasePageLayoutTab[];
+	fullWidth?: boolean;
+	showPropertyIcons?: boolean;
+	showTemplates?: boolean;
+};
+
 /** The normalized data-source shape emitted in provisioning artifacts. */
 export type DataSourceDefinition<
 	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
@@ -121,8 +318,7 @@ export type DataSourceDefinition<
 	name: string;
 	properties: Properties;
 	icon?: NotionAsCodeIcon;
-	// TODO: Port page layout types.
-	pageLayout?: unknown;
+	pageLayout?: DatabasePageLayout;
 };
 
 export type TeamspaceIntent = TeamspaceArgs & {
@@ -141,8 +337,7 @@ export type DatabaseIntent = {
 	dataSources: readonly DataSourceDefinition[];
 	views?: readonly ViewSchema[];
 	icon?: NotionAsCodeIcon;
-	// TODO: Port cover types.
-	cover?: unknown;
+	cover?: PageCoverReference;
 	hideDataSourceTitle?: boolean;
 	hideDatabaseTitleIfEmpty?: boolean;
 	name?: string;