@notionhq/apps 0.0.20 → 0.0.22

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

@@ -4,6 +4,30 @@ 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"),

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";
@@ -56,8 +57,7 @@ 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;
+	cover?: PageCoverReference;
 	/**
 	 * Page properties, including the page title.
 	 *

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.

package/src/workflow-access.ts

@@ -14,6 +14,8 @@ export type WorkflowAccessResource =
 	| DataSourceHandle
 	| CustomAgentHandle;
 
+type WorkflowAccessContentResource = Exclude<WorkflowAccessResource, CustomAgentHandle>;
+
 /** Resource kinds accepted by workflow access declarations. */
 export type WorkflowAccessResourceType = WorkflowAccessResource["resourceType"];
 
@@ -82,6 +84,45 @@ export type WorkflowAccess<
 /** Resolved NaC bindings keyed by public aliases, without declaration metadata. */
 export type WorkflowAccessBindings = Readonly<Record<string, WorkflowAccessValue>>;
 
+/** Create type-safe access declarations for Notion-as-Code resource handles. */
+export const access = {
+	view,
+	comment,
+	edit,
+	fullAccess,
+	call,
+};
+
+function view<TResource extends WorkflowAccessContentResource>(
+	resource: TResource,
+): Readonly<{ resource: TResource; level: "view" }> {
+	return { resource, level: "view" };
+}
+
+function comment<TResource extends WorkflowAccessContentResource>(
+	resource: TResource,
+): Readonly<{ resource: TResource; level: "comment" }> {
+	return { resource, level: "comment" };
+}
+
+function edit<TResource extends WorkflowAccessContentResource>(
+	resource: TResource,
+): Readonly<{ resource: TResource; level: "edit" }> {
+	return { resource, level: "edit" };
+}
+
+function fullAccess<TResource extends WorkflowAccessContentResource>(
+	resource: TResource,
+): Readonly<{ resource: TResource; level: "fullAccess" }> {
+	return { resource, level: "fullAccess" };
+}
+
+function call(
+	resource: CustomAgentHandle,
+): Readonly<{ resource: CustomAgentHandle; level: "call" }> {
+	return { resource, level: "call" };
+}
+
 const ACCESS_ALIAS_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/;
 const RESERVED_ACCESS_ALIASES = new Set<string>(["__proto__", "prototype", "constructor"]);
 const RESOURCE_TYPES: Record<WorkflowAccessResourceType, true> = {

package/src/workflow.test.ts

@@ -12,6 +12,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 {
+	access,
 	connections,
 	workflow,
 	type StepContext,
@@ -1216,10 +1217,10 @@ describe("workflow", () => {
 			description: "Hydrates access",
 			triggers: [triggers.notionPageCreated()],
 			access: {
-				home: { resource: home, level: "view" },
-				table: { resource: table, level: "edit" },
-				source: { resource: table.dataSource, level: "comment" },
-				agent: { resource: agent, level: "call" },
+				home: access.view(home),
+				table: access.edit(table),
+				source: access.comment(table.dataSource),
+				agent: access.call(agent),
 			},
 			handler: (_event, context) => {
 				expectTypeOf(context.access.home.type).toEqualTypeOf<"page">();

package/src/workflow.ts

@@ -91,6 +91,7 @@ export type {
 	WorkflowAccessRequirements,
 	WorkflowAccessValue,
 } from "./workflow-access.js";
+export { access } from "./workflow-access.js";
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];