@notionhq/apps 0.0.16 → 0.0.18

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

@@ -1,7 +1,7 @@
 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";
 
 /** Apps-specific resource IDs used while declaring Notion-as-Code metadata. */
 /** Synthetic workspace parent for teamspaces declared by an Apps project. */
@@ -65,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" })
@@ -91,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[],
 > = {
@@ -106,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 };
@@ -116,8 +154,7 @@ export type CustomAgentIntent = CustomAgentArgs;
 
 export type ViewIntent = {
 	databaseResourceId: ResourceId;
-	// TODO: Port view types.
-	view: unknown;
+	view: ViewSchema;
 };
 
 export type InfraAsCodeIntent =

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

@@ -5,11 +5,15 @@ import type { SelectOption, StatusGroup } from "../types.js";
 import type {
 	DataSourceDefinition,
 	NotionAsCodeProperty,
+	NotionAsCodePropertyConfig,
+	NotionAsCodeSchema,
 	NotionAsCodeSelectOption,
 	NotionAsCodeStatusOption,
 } from "./intents.js";
 
-type AppsPropertyFor<Property extends NotionAsCodeProperty> = Property extends { type: "title" }
+type AppsPropertyFor<Property extends NotionAsCodePropertyConfig> = Property extends {
+	type: "title";
+}
 	? { type: "title" }
 	: Property extends { type: "text" }
 		? { type: "text" }
@@ -35,8 +39,12 @@ type AppsPropertyFor<Property extends NotionAsCodeProperty> = Property extends {
 												? { type: "file" }
 												: PropertyConfiguration;
 
-export type AppsSchemaForProperties<Properties extends readonly NotionAsCodeProperty[]> = {
-	[Property in Properties[number] as Property["name"]]: AppsPropertyFor<Property>;
+/**
+ * Map keyed authoring properties to the Apps schema used by sync handlers. The explicit
+ * string-key mapping avoids a homomorphic mapped type interfering with `NoInfer` key checks.
+ */
+export type AppsSchemaForSchema<Schema extends NotionAsCodeSchema> = {
+	[Property in keyof Schema & string]: AppsPropertyFor<Schema[Property]>;
 };
 
 /** Convert a Notion-as-Code data source into the Apps database used by sync handlers. */

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

@@ -0,0 +1,23 @@
+import type { ResourceId } from "./intents.js";
+import { recordIntent } from "./recorder.js";
+import { assertUserResourceId } from "./resource.js";
+import type { ViewSchema } from "./views.js";
+
+/** Declare a view attached to a database resource. */
+export type ViewArgs = ViewSchema & {
+	databaseResourceId: ResourceId;
+};
+
+export type ViewHandle = {
+	readonly resourceId: string;
+};
+
+/** Record a database view for provisioning without making a Notion API request. */
+export function view(args: ViewArgs): ViewHandle {
+	assertUserResourceId(args.resourceId);
+	assertUserResourceId(args.databaseResourceId);
+	assertUserResourceId(args.dataSourceResourceId);
+	const { databaseResourceId, ...schema } = args;
+	recordIntent({ type: "view", databaseResourceId, view: schema });
+	return { resourceId: args.resourceId };
+}

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

@@ -0,0 +1,59 @@
+import { expectTypeOf, it } from "vitest";
+
+import type {
+	DatabaseArgs,
+	DatabaseHandle,
+	DatePropertyFilter,
+	GroupByFormat,
+	ViewSchema,
+} from "./index.js";
+
+it("requires date properties for calendar and timeline views at both entrypoints", () => {
+	type MissingDateProperty = {
+		resourceId: "view";
+		dataSourceResourceId: "source";
+		type: "calendar" | "timeline";
+	};
+	expectTypeOf<MissingDateProperty>().not.toExtend<ViewSchema>();
+	expectTypeOf<MissingDateProperty>().not.toExtend<NonNullable<DatabaseArgs["views"]>[number]>();
+	expectTypeOf<MissingDateProperty>().not.toExtend<Parameters<DatabaseHandle["addView"]>[0]>();
+});
+
+it("couples date operators to their value shapes and requires a range bound", () => {
+	type DateFilter = {
+		type: "property";
+		propertyId: "due";
+		propertyType: "date";
+	};
+	expectTypeOf<
+		DateFilter & {
+			operator: "date_is_within";
+			value: { type: "exact_range"; value: { startDate: "2026-01-01" } };
+		}
+	>().toExtend<DatePropertyFilter>();
+	expectTypeOf<
+		DateFilter & {
+			operator: "date_is_within";
+			value: { type: "exact_range"; value: {} };
+		}
+	>().not.toExtend<DatePropertyFilter>();
+	expectTypeOf<
+		DateFilter & {
+			operator: "date_is_relative_to";
+			value: { type: "exact"; value: "2026-01-01" };
+		}
+	>().not.toExtend<DatePropertyFilter>();
+});
+
+it("limits status grouping options to status properties", () => {
+	expectTypeOf<{
+		type: "status";
+		property: "status";
+		statusBy: "group";
+	}>().toExtend<GroupByFormat>();
+	expectTypeOf<{
+		type: "select";
+		property: "status";
+		statusBy: "group";
+	}>().not.toExtend<GroupByFormat>();
+});