@notionhq/apps 0.0.19 → 0.0.21

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;

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

@@ -0,0 +1,167 @@
+import { expectTypeOf, it } from "vitest";
+
+import type {
+	CustomAgentArgs,
+	CustomAgentPropertyUpdatedTrigger,
+	CustomAgentTrigger,
+	DatabasePageLayout,
+	NotionAsCodePropertyConfig,
+	PageArgs,
+	PageCoverReference,
+	PageLayoutPropertyModule,
+	SingleSourceDatabaseArgs,
+} from "./index.js";
+
+it("types page and database covers as URL references", () => {
+	expectTypeOf<{
+		type: "url";
+		url: "https://example.com/cover.png";
+		position: 0.25;
+	}>().toExtend<PageCoverReference>();
+	expectTypeOf<{
+		type: "external";
+		url: "https://example.com/cover.png";
+	}>().not.toExtend<PageCoverReference>();
+	expectTypeOf<PageArgs["cover"]>().toEqualTypeOf<PageCoverReference | undefined>();
+});
+
+it("requires configuration for each advanced property kind", () => {
+	expectTypeOf<{
+		type: "relation";
+		resourceId: "project";
+		targetDataSourceResourceId: "projects";
+		limit: 1;
+	}>().toExtend<NotionAsCodePropertyConfig>();
+	expectTypeOf<{
+		type: "relation";
+		resourceId: "project";
+	}>().not.toExtend<NotionAsCodePropertyConfig>();
+
+	expectTypeOf<{
+		type: "rollup";
+		resourceId: "total";
+		relationPropertyResourceId: "project";
+		targetPropertyResourceId: "estimate";
+		targetPropertyType: "number";
+		aggregation: "sum";
+	}>().toExtend<NotionAsCodePropertyConfig>();
+	expectTypeOf<{
+		type: "rollup";
+		resourceId: "invalid-total";
+		relationPropertyResourceId: "project";
+		targetPropertyResourceId: "name";
+		targetPropertyType: "title";
+		aggregation: "sum";
+	}>().not.toExtend<NotionAsCodePropertyConfig>();
+
+	expectTypeOf<{
+		type: "verification";
+		resourceId: "verification";
+		verifierPropertyResourceId: "owner";
+	}>().toExtend<NotionAsCodePropertyConfig>();
+	expectTypeOf<{
+		type: "verification";
+		resourceId: "verification";
+	}>().not.toExtend<NotionAsCodePropertyConfig>();
+});
+
+it("links page-layout property styles and relation groups to the data source schema", () => {
+	type Schema = {
+		Name: { type: "title"; resourceId: "name" };
+		Estimate: { type: "number"; resourceId: "estimate" };
+		Owner: { type: "person"; resourceId: "owner" };
+		Project: {
+			type: "relation";
+			resourceId: "project";
+			targetDataSourceResourceId: "projects";
+		};
+	};
+
+	expectTypeOf<{
+		type: "property";
+		property: "estimate";
+		style: "large";
+	}>().toExtend<PageLayoutPropertyModule<Schema>>();
+	expectTypeOf<{
+		type: "property";
+		property: "estimate";
+		style: "landscape";
+	}>().not.toExtend<PageLayoutPropertyModule<Schema>>();
+	expectTypeOf<{
+		type: "property";
+		property: "name";
+		style: "large";
+	}>().not.toExtend<PageLayoutPropertyModule<Schema>>();
+
+	type ValidLayout = {
+		main: [
+			{ type: "properties"; properties: [{ property: "name" }] },
+			{
+				type: "relations";
+				relations: [{ property: "project"; display: "pageSection" }];
+			},
+		];
+		pinnedProperties: ["owner"];
+	};
+	type InvalidRelationLayout = {
+		main: [
+			{ type: "properties"; properties: [{ property: "name" }] },
+			{
+				type: "relations";
+				relations: [{ property: "estimate"; display: "pageSection" }];
+			},
+		];
+	};
+	expectTypeOf<ValidLayout>().toExtend<DatabasePageLayout<Schema>>();
+	expectTypeOf<InvalidRelationLayout>().not.toExtend<DatabasePageLayout<Schema>>();
+
+	expectTypeOf<{
+		dataSourceResourceId: "tasks";
+		name: "Tasks";
+		schema: Schema;
+		pageLayout: ValidLayout;
+	}>().toExtend<SingleSourceDatabaseArgs<Schema>>();
+	expectTypeOf<{
+		dataSourceResourceId: "tasks";
+		name: "Tasks";
+		schema: Schema;
+		pageLayout: InvalidRelationLayout;
+	}>().not.toExtend<SingleSourceDatabaseArgs<Schema>>();
+});
+
+it("requires a meaningful custom agent trigger configuration", () => {
+	expectTypeOf<{
+		type: "recurrence";
+		resourceId: "weekday-trigger";
+		frequency: "week";
+		interval: 1;
+		start: "2026-09-21T09:00:00";
+		timeZone: "America/Los_Angeles";
+		weekdays: { MO: true; FR: true };
+	}>().toExtend<CustomAgentTrigger>();
+	expectTypeOf<{
+		type: "recurrence";
+		resourceId: "empty-weekdays";
+		frequency: "week";
+		interval: 1;
+		start: "2026-09-21T09:00:00";
+		timeZone: "America/Los_Angeles";
+		weekdays: {};
+	}>().not.toExtend<CustomAgentTrigger>();
+
+	expectTypeOf<{
+		type: "property_updated";
+		resourceId: "content-trigger";
+		dataSourceResourceId: "tasks";
+		triggerWhenPageContentEdited: true;
+	}>().toExtend<CustomAgentPropertyUpdatedTrigger>();
+	expectTypeOf<{
+		type: "property_updated";
+		resourceId: "empty-trigger";
+		dataSourceResourceId: "tasks";
+	}>().not.toExtend<CustomAgentPropertyUpdatedTrigger>();
+
+	expectTypeOf<CustomAgentArgs["triggers"]>().toEqualTypeOf<
+		readonly CustomAgentTrigger[] | undefined
+	>();
+});

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

@@ -0,0 +1,59 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { notion, type PageArgs, type PropertyValue } from "./index.js";
+import { finishMetadataRecording, startMetadataRecording } from "./recorder.js";
+
+describe("Notion-as-Code page declarations", () => {
+	it("records typed URL covers", () => {
+		const recorder = startMetadataRecording();
+
+		notion.page({
+			resourceId: "url-cover-page",
+			cover: {
+				type: "url",
+				url: "https://example.com/cover.png",
+				position: 0.25,
+			},
+		});
+
+		expect(finishMetadataRecording(recorder).intents).toEqual([
+			expect.objectContaining({
+				resourceId: "url-cover-page",
+				cover: {
+					type: "url",
+					url: "https://example.com/cover.png",
+					position: 0.25,
+				},
+			}),
+		]);
+	});
+
+	it("records a regular page title separately from Markdown content", () => {
+		const properties = {
+			title: notion.text("Workflow guide"),
+		} satisfies Record<string, PropertyValue | undefined>;
+		const recorder = startMetadataRecording();
+
+		notion.page({
+			resourceId: "workflow-guide",
+			properties,
+			content: "# Body heading",
+		});
+
+		expectTypeOf<PageArgs["properties"]>().toEqualTypeOf<
+			Record<string, PropertyValue | undefined> | undefined
+		>();
+		expect(finishMetadataRecording(recorder).intents).toEqual([
+			{
+				type: "page",
+				resourceId: "workflow-guide",
+				parent: {
+					type: "resourceId",
+					resourceId: "__notion_apps_workspace__",
+				},
+				properties: { title: [["Workflow guide"]] },
+				content: "# Body heading",
+			},
+		]);
+	});
+});

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

@@ -1,6 +1,7 @@
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
 	type PageIntent,
+	type PageCoverReference,
 	type Parent,
 	type ResourceId,
 } from "./intents.js";
@@ -8,14 +9,71 @@ import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 
+/**
+ * A single text token: plain text as `[string]`, or text with annotations as
+ * `[string, ...annotations]`.
+ */
+export type SimpleTextToken = [string] | [string, ...unknown[]];
+
+/**
+ * The JSON-serializable text format returned by Notion-as-Code text helpers.
+ */
+export type TextValue = SimpleTextToken[];
+
+export type VerificationInput =
+	| {
+			state: "verified";
+			/** Set an expiration with `notion.datetime(...)`; omit it for indefinite verification. */
+			datetime?: TextValue;
+	  }
+	| { state: "unverified" };
+
+export type VerificationPropertyValue = VerificationInput & {
+	type: "verification";
+};
+
+/**
+ * A page property value accepted by Notion as Code.
+ *
+ * Use helpers from `@notionhq/apps/notion-as-code` to construct rich values
+ * such as text, dates, checkboxes, and URLs.
+ */
+export type PropertyValue =
+	| string
+	| number
+	| TextValue
+	| string[]
+	| VerificationPropertyValue
+	| undefined;
+
+/**
+ * Arguments for declaring a page.
+ *
+ * For a regular page, set its title through
+ * `properties.title: notion.text("My Page Title")`. For a database page, use
+ * the title property's schema name instead of `title`.
+ */
 export type PageArgs = {
 	resourceId: ResourceId;
 	/** Omit to create a private top-level page in the Apps workspace. */
 	parent?: Parent;
-	// TODO: Port cover types.
-	cover?: unknown;
-	// TODO: Port page property types.
-	properties?: Record<string, unknown>;
+	cover?: PageCoverReference;
+	/**
+	 * Page properties, including the page title.
+	 *
+	 * @example Regular page
+	 * properties: { title: notion.text("My Page Title") }
+	 *
+	 * @example Database page
+	 * properties: { Name: notion.text("Task Name"), Status: "In Progress" }
+	 */
+	properties?: Record<string, PropertyValue | undefined>;
+	/**
+	 * Page body in Notion-flavored Markdown.
+	 *
+	 * Markdown headings create child blocks. They do not set the page title;
+	 * set a regular page's title with `properties.title`.
+	 */
 	content?: string;
 	fullWidth?: boolean;
 };