@notionhq/apps 0.0.15 → 0.0.17

package/src/connections.ts

@@ -1,61 +1,127 @@
+import { validateOAuthConfiguration, type OAuthConfiguration } from "./oauth.js";
 import { connectionTriggerDefinitions } from "./connection-trigger-definitions.generated.js";
 import type { WorkflowTrigger } from "./triggers.generated.js";
 import type { Client } from "@notionhq/client";
-import { createConnectionProviders, type ConnectionProviders } from "./providers.generated.js";
+import {
+	connections as providerConnections,
+	createConnectionClient,
+	type ConnectionClients,
+} from "./providers.generated.js";
 import type { ConnectionActionInvoker } from "./connection-actions.js";
 
-/** A setup requirement. The server decides which providers are available. */
-export type WorkflowConnection<TProvider extends string = string, TKey extends string = string> = {
+/** A setup requirement. The property name in a workflow supplies its key. */
+export type WorkflowConnection<TProvider extends string = string> = {
 	type: TProvider;
-	key?: TKey;
+	oauth?: OAuthConfiguration;
 };
 
-/** Keys declared for one provider in a workflow. */
+export type WorkflowConnectionDeclarations = Readonly<Record<string, WorkflowConnection>>;
+
+/** Serialized connection requirement sent in the workflow manifest. */
+export type WorkflowConnectionRequirement = WorkflowConnection & { key: string };
+
+/** Declared property names belonging to one provider. */
 export type WorkflowConnectionKeys<
-	TConnections extends readonly WorkflowConnection[],
+	TConnections extends WorkflowConnectionDeclarations,
 	TProvider extends string,
-> = WorkflowConnectionKey<Extract<TConnections[number], { type: TProvider }>>;
-
-type WorkflowConnectionKey<TConnection extends WorkflowConnection> =
-	TConnection extends WorkflowConnection
-		? "key" extends keyof TConnection
-			? Exclude<TConnection["key"], undefined>
-			: TConnection["type"]
-		: never;
+> = Extract<
+	{
+		[TKey in keyof TConnections]: TConnections[TKey]["type"] extends TProvider ? TKey : never;
+	}[keyof TConnections],
+	string
+>;
+
 type ConnectionBinding = { key: string; type: string; id: string };
 
 /** Requirements are declarations, not credentials or permission grants. */
-export { connections } from "./providers.generated.js";
+export const connections = {
+	...providerConnections,
+	oauth(options: OAuthConfiguration): WorkflowConnection<"oauth"> {
+		validateOAuthConfiguration(options);
+		return { type: "oauth", oauth: structuredClone(options) };
+	},
+};
+export type { OAuthConfiguration } from "./oauth.js";
+export type OAuthConnection = { accessToken(): Promise<string> };
+
+type WorkflowConnectionClients = ConnectionClients & { oauth: OAuthConnection };
+
+type WorkflowConnectionClient = WorkflowConnectionClients[keyof WorkflowConnectionClients];
 
 export type WorkflowConnections<
-	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
-> = Pick<ConnectionProviders, Extract<keyof ConnectionProviders, TConnections[number]["type"]>>;
+	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
+> = {
+	readonly [TKey in keyof TConnections]: WorkflowConnectionClients[Extract<
+		keyof WorkflowConnectionClients,
+		TConnections[TKey]["type"]
+	>];
+};
 
 /** @internal */
-export function validateConnectionRequirements(requirements: readonly WorkflowConnection[]): void {
-	if (requirements.length > 100) throw new Error("Workflows support at most 100 connections.");
-	const keys = new Set<string>();
-	for (const requirement of requirements) {
-		if (!requirement.type) throw new Error("A workflow connection needs a provider type.");
-		const key = requirement.key ?? requirement.type;
-		if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(key)) {
+export function normalizeConnectionRequirements(
+	declarations: WorkflowConnectionDeclarations,
+): WorkflowConnectionRequirement[] {
+	if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) {
+		throw new Error("Workflow connections must be an object keyed by connection name.");
+	}
+	const prototype: unknown = Object.getPrototypeOf(declarations);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new Error("Workflow connections must contain only own connection declarations.");
+	}
+	const keys = Object.keys(declarations);
+	if (Reflect.ownKeys(declarations).length !== keys.length) {
+		throw new Error("Workflow connection keys must be enumerable strings.");
+	}
+	if (keys.length > 100) throw new Error("Workflows support at most 100 connections.");
+	return Object.entries(declarations).map(([key, requirement]) => {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(key) ||
+			["__proto__", "prototype", "constructor"].includes(key)
+		) {
 			throw new Error("Invalid workflow connection key: " + key);
 		}
-		if (keys.has(key)) throw new Error("Duplicate workflow connection: " + key);
-		keys.add(key);
-	}
+		if (
+			typeof requirement !== "object" ||
+			requirement === null ||
+			typeof requirement.type !== "string" ||
+			!requirement.type ||
+			!Object.hasOwn(requirement, "type")
+		) {
+			throw new Error("A workflow connection needs a provider type.");
+		}
+		if ("key" in requirement)
+			throw new Error(
+				"Declare a connection key as its workflow object property, not in the provider options.",
+			);
+
+		if (requirement.type === "oauth") {
+			if (!requirement.oauth)
+				throw new Error("OAuth connections require provider configuration.");
+			validateOAuthConfiguration(requirement.oauth);
+		} else if (requirement.oauth !== undefined) {
+			throw new Error("OAuth configuration is only valid on OAuth connections.");
+		}
+
+		return {
+			type: requirement.type,
+			key,
+			...(requirement.oauth === undefined
+				? {}
+				: { oauth: structuredClone(requirement.oauth) }),
+		};
+	});
 }
 
 /** @internal */
 export function validateTriggerConnections(
 	triggers: readonly WorkflowTrigger[],
-	requirements: readonly WorkflowConnection[],
+	requirements: readonly WorkflowConnectionRequirement[],
 ): void {
 	const seen = new Set<string>();
 	for (const trigger of triggers) {
 		if (!("connectionKey" in trigger) || trigger.connectionKey === undefined) continue;
 		const requirement = requirements.find(
-			(connection) => (connection.key ?? connection.type) === trigger.connectionKey,
+			(connection) => connection.key === trigger.connectionKey,
 		);
 		const definition = connectionTriggerDefinitions.find(
 			(definition) => definition.type === trigger.type,
@@ -75,10 +141,41 @@ export function validateTriggerConnections(
 }
 
 /** @internal */
-export function createWorkflowConnections(notion: Client): WorkflowConnections {
-	// Capture the execution's bindings; defer parsing so non-connection workflows
-	// remain usable without runtime connection metadata.
+export function createWorkflowConnections<TConnections extends WorkflowConnectionDeclarations>(
+	notion: Client,
+	declarations: TConnections | undefined,
+): WorkflowConnections<TConnections>;
+export function createWorkflowConnections(
+	notion: Client,
+	declarations: WorkflowConnectionDeclarations | undefined,
+): Record<string, WorkflowConnectionClient> {
+	const requirements = normalizeConnectionRequirements(declarations ?? {});
+	// Capture this execution's metadata, but do not parse unused bindings.
 	const rawBindings = process.env.NOTION_CONNECTION_BINDINGS;
+	const clients: Record<string, WorkflowConnectionClient> = {};
+	Object.setPrototypeOf(clients, null);
+	for (const requirement of requirements) {
+		let client: WorkflowConnectionClient | undefined;
+		Object.defineProperty(clients, requirement.key, {
+			enumerable: true,
+			get() {
+				if (client) return client;
+				const binding = resolveBinding(requirement.key);
+				if (binding.type !== requirement.type) {
+					throw new Error(
+						`Workflow connection "${requirement.key}" is ${binding.type}, not ${requirement.type}.`,
+					);
+				}
+				client =
+					requirement.type === "oauth"
+						? createOAuthConnection(binding)
+						: createConnectionClient(requirement.type, invoker(binding));
+				return client;
+			},
+		});
+	}
+	return Object.freeze(clients);
+
 	function resolveBinding(key: string): ConnectionBinding {
 		const bindings: unknown = JSON.parse(rawBindings ?? "[]");
 		if (!Array.isArray(bindings) || !bindings.every(isConnectionBinding)) {
@@ -92,11 +189,7 @@ export function createWorkflowConnections(notion: Client): WorkflowConnections {
 		}
 		return { ...matches[0] };
 	}
-	function invoker(provider: string, key: string): ConnectionActionInvoker {
-		const binding = resolveBinding(key);
-		if (binding.type !== provider) {
-			throw new Error(`Workflow connection "${key}" is ${binding.type}, not ${provider}.`);
-		}
+	function invoker(binding: ConnectionBinding): ConnectionActionInvoker {
 		return async <Result>(action: string, args: object): Promise<Result> => {
 			const response = await notion.request<{ result: Result }>({
 				path: "tools/run/internal",
@@ -106,7 +199,20 @@ export function createWorkflowConnections(notion: Client): WorkflowConnections {
 			return response.result;
 		};
 	}
-	return createConnectionProviders(invoker);
+}
+
+function createOAuthConnection(binding: ConnectionBinding): OAuthConnection {
+	const envKey = `NOTION_OAUTH_CONNECTION_${binding.id.replaceAll("-", "").toUpperCase()}`;
+	const token = process.env[envKey];
+	return {
+		async accessToken() {
+			if (!token)
+				throw new Error(
+					`Workflow OAuth connection "${binding.key}" requires authorization.`,
+				);
+			return token;
+		},
+	};
 }
 
 function isConnectionBinding(value: unknown): value is ConnectionBinding {

package/src/index.ts

@@ -3,5 +3,6 @@ export { customAgent } from "./notion-as-code/custom-agent.js";
 export { database } from "./notion-as-code/database.js";
 export { page } from "./notion-as-code/page.js";
 export { teamspace } from "./notion-as-code/teamspace.js";
+export { view } from "./notion-as-code/view.js";
 export { sync } from "./sync.js";
 export { workflow } from "./workflow.js";

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

@@ -12,6 +12,7 @@ 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 type { ViewSchema } from "./views.js";
 
 /** Input for declaring a database and its optional data sources. */
 export type DatabaseArgs<
@@ -21,8 +22,7 @@ export type DatabaseArgs<
 	/** Omit to create a private top-level database in the Apps workspace. */
 	parent?: Parent;
 	dataSources?: DataSources;
-	// TODO: Port view types.
-	views?: readonly unknown[];
+	views?: readonly ViewSchema[];
 	icon?: NotionAsCodeIcon;
 	// TODO: Port cover types.
 	cover?: unknown;
@@ -37,6 +37,19 @@ export type ChildDatabaseArgs<
 	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
 > = Omit<DatabaseArgs<DataSources>, "parent">;
 
+/** Single-source shorthand; the source ID is `${resourceId}-source`. */
+export type SingleSourceDatabaseArgs<
+	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
+> = Omit<DatabaseArgs, "dataSources" | "name"> & {
+	name: string;
+	properties: Properties;
+	dataSources?: never;
+};
+
+export type ChildSingleSourceDatabaseArgs<
+	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
+> = Omit<SingleSourceDatabaseArgs<Properties>, "parent">;
+
 /** Resolves one data source ID to the properties declared for it. */
 type DataSourcePropertiesForResourceId<
 	DataSources extends readonly DataSourceDefinition[],
@@ -68,14 +81,35 @@ export type DatabaseHandle<
 			DataSourcePropertiesForResourceId<DataSources, ResourceId>
 		>;
 	};
-	addView: (view: unknown) => void;
+	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>;
+};
+
+export type ChildDatabaseFactory = {
+	<const Properties extends readonly NotionAsCodeProperty[]>(
+		args: ChildSingleSourceDatabaseArgs<Properties>,
+	): SingleSourceDatabaseHandle<Properties>;
+	<const DataSources extends readonly DataSourceDefinition[]>(
+		args: ChildDatabaseArgs<DataSources> & { properties?: never },
+	): DatabaseHandle<DataSources>;
 };
 
 /** 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>,
+	args: DatabaseArgs<DataSources> & { properties?: never },
 ): DatabaseHandle<DataSources>;
-export function database(args: DatabaseArgs): DatabaseHandle {
+export function database(
+	args: DatabaseArgs | SingleSourceDatabaseArgs,
+): DatabaseHandle | SingleSourceDatabaseHandle {
 	if (args.parent) {
 		assertParent(args.parent);
 	}
@@ -83,9 +117,45 @@ export function database(args: DatabaseArgs): DatabaseHandle {
 		type: "resourceId",
 		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;
+		const source: DataSourceDefinition = {
+			resourceId: `${args.resourceId}-source`,
+			name: args.name,
+			properties,
+		};
+		const handle = createDatabase({ ...databaseArgs, dataSources: [source] }, parent);
+		const dataSource = handle.dataSources[source.resourceId];
+		if (!dataSource) {
+			throw new Error(`Missing data source "${source.resourceId}"`);
+		}
+		return { ...handle, dataSource };
+	}
 	return createDatabase(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 });
+		}
+		return database({ ...args, parent });
+	}
+	return addDatabase;
+}
+
 /** Record a database declaration and create handles for each of its data sources. */
 export function createDatabase(args: DatabaseArgs, parent: Parent): DatabaseHandle {
 	assertUserResourceId(args.resourceId);

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

@@ -4,12 +4,14 @@ import { date, datetime } from "./date.js";
 import { page } from "./page.js";
 import { assertUserResourceId } from "./resource.js";
 import { teamspace } from "./teamspace.js";
+import { view } from "./view.js";
 
 const notionAsCodeFacade = {
 	teamspace,
 	database,
 	page,
 	customAgent,
+	view,
 	text: (value: string) => [[value]],
 	number: (value: number) => [[String(value)]],
 	date,

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

@@ -5,12 +5,71 @@ export type { DataSourceDefinition, NotionAsCodeProperty, Parent } from "./inten
 export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
 export type {
 	ChildDatabaseArgs,
+	ChildDatabaseFactory,
+	ChildSingleSourceDatabaseArgs,
 	DataSourceHandle,
 	DatabaseArgs,
 	DatabaseHandle,
+	SingleSourceDatabaseArgs,
+	SingleSourceDatabaseHandle,
 } from "./database.js";
 export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";
+export type { ViewArgs, ViewHandle } from "./view.js";
+export type {
+	AdvancedFilterSchema,
+	BasePropertyFilter,
+	BaseViewSchema,
+	BoardViewSchema,
+	CalendarViewSchema,
+	CheckboxGroupByFormat,
+	CheckboxPropertyFilter,
+	CoverAspectFormat,
+	CoverFormat,
+	CoverSizeFormat,
+	DatabaseViewSortDirection,
+	DateFilterMode,
+	DateGroupByFormat,
+	DatePropertyFilter,
+	DatePropertyFilterValue,
+	DatePropertyTypes,
+	ExactDatePropertyFilterValue,
+	ExactRangeDatePropertyFilterValue,
+	FeedViewSchema,
+	FilterSchema,
+	FormulaGroupByFormat,
+	GalleryViewSchema,
+	GroupByFormat,
+	GroupByFormatBase,
+	GroupFormat,
+	ListViewSchema,
+	LocationGroupByFormat,
+	MultiSelectPropertyFilter,
+	NumberGroupByFormat,
+	NumberPropertyFilter,
+	PersonGroupByFormat,
+	PersonPropertyFilter,
+	PropertyFilterSchema,
+	PropertyFormat,
+	PropertyViewSortSchema,
+	PropertyVisibility,
+	RelationGroupByFormat,
+	RelationPropertyFilter,
+	RelativeDatePreset,
+	RelativeDatePropertyFilterValue,
+	RelativeDateRangeUnit,
+	RelativeToTodayDatePropertyFilterValue,
+	SelectGroupByFormat,
+	SelectPropertyFilter,
+	StatusGroupByFormat,
+	StatusPropertyFilter,
+	TableViewSchema,
+	TextGroupByFormat,
+	TextPropertyFilter,
+	TimelineViewSchema,
+	ViewSchema,
+	ViewType,
+} from "./views.js";
 
 /** Experimental Notion-as-Code facade for Apps SDK project metadata. */
 export const notion = createNotion();

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

@@ -2,6 +2,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. */
@@ -116,8 +117,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/page.ts

@@ -1,11 +1,10 @@
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
-	type DataSourceDefinition,
 	type PageIntent,
 	type Parent,
 	type ResourceId,
 } from "./intents.js";
-import { database, type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 
@@ -25,9 +24,7 @@ export type ChildPageArgs = Omit<PageArgs, "parent">;
 
 export type PageHandle = {
 	readonly resourceId: string;
-	addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources>,
-	) => DatabaseHandle<DataSources>;
+	addDatabase: ChildDatabaseFactory;
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
@@ -54,12 +51,7 @@ export function createPage(args: ChildPageArgs | PageArgs, parent: Parent): Page
 
 	return {
 		resourceId: args.resourceId,
-		addDatabase(databaseArgs) {
-			return database({
-				...databaseArgs,
-				parent: { type: "resourceId", resourceId: args.resourceId },
-			});
-		},
+		addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
 		addPage(pageArgs) {
 			return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
 		},

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

@@ -1,11 +1,10 @@
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
-	type DataSourceDefinition,
 	type NotionAsCodeIcon,
 	type ResourceId,
 	type TeamspaceIntent,
 } from "./intents.js";
-import { database, type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
 import { recordIntent } from "./recorder.js";
 import { assertUserResourceId } from "./resource.js";
@@ -20,9 +19,7 @@ export type TeamspaceArgs = {
 
 export type TeamspaceHandle = {
 	readonly resourceId: string;
-	addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources>,
-	) => DatabaseHandle<DataSources>;
+	addDatabase: ChildDatabaseFactory;
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
@@ -37,12 +34,7 @@ export function teamspace(args: TeamspaceArgs): TeamspaceHandle {
 
 	return {
 		resourceId: args.resourceId,
-		addDatabase(databaseArgs) {
-			return database({
-				...databaseArgs,
-				parent: { type: "resourceId", resourceId: args.resourceId },
-			});
-		},
+		addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
 		addPage(pageArgs) {
 			return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
 		},

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>();
+});