@notionhq/apps 0.0.9 → 0.0.11

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

@@ -0,0 +1,50 @@
+import type { InfraAsCodeIntent } from "./intents.js";
+
+export const APPS_PROVISIONING_SCHEMA = "notion:apps-provisioning:v1";
+
+/** Provisioning intents recorded while evaluating the build-only metadata bundle. */
+export type RecordedProvisioning = {
+	intents: InfraAsCodeIntent[];
+};
+
+/** Teamspaces are always created in the Apps workspace, so Apps supplies their parent. */
+export type ProvisioningIntent =
+	| Omit<Extract<InfraAsCodeIntent, { type: "teamspace" }>, "parent">
+	| Exclude<InfraAsCodeIntent, { type: "teamspace" }>;
+
+export type ProvisioningArtifact = {
+	$schema: typeof APPS_PROVISIONING_SCHEMA;
+	version: 1;
+	intents: readonly ProvisioningIntent[];
+};
+
+/** Convert recorded declarations into the server-facing provisioning artifact. */
+export function createProvisioningArtifact(
+	intents: readonly InfraAsCodeIntent[],
+): ProvisioningArtifact {
+	const provisioningIntents: ProvisioningIntent[] = [];
+	for (const intent of intents) {
+		if (intent.type === "teamspace") {
+			const { parent: _parent, ...teamspace } = intent;
+			provisioningIntents.push(teamspace);
+		} else {
+			provisioningIntents.push(intent);
+		}
+	}
+
+	return {
+		$schema: APPS_PROVISIONING_SCHEMA,
+		version: 1,
+		intents: provisioningIntents,
+	};
+}
+
+/** Check that a metadata bundle exported the recorder output. */
+export function isRecordedProvisioning(value: unknown): value is RecordedProvisioning {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"intents" in value &&
+		Array.isArray(value.intents)
+	);
+}

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

@@ -0,0 +1,26 @@
+/** Records Notion-as-Code declarations while the build-only metadata bundle evaluates. */
+import type { InfraAsCodeIntent } from "./intents.js";
+import type { RecordedProvisioning } from "./provisioning.js";
+
+let activeRecorder: RecordedProvisioning | undefined;
+
+/** Start collecting declarations from the metadata bundle. */
+export function startMetadataRecording(): RecordedProvisioning {
+	const recorder: RecordedProvisioning = { intents: [] };
+	activeRecorder = recorder;
+	return recorder;
+}
+
+/** Finish the active metadata collection and return its declarations. */
+export function finishMetadataRecording(recorder: RecordedProvisioning): RecordedProvisioning {
+	if (activeRecorder !== recorder) {
+		throw new Error("Notion-as-Code metadata recorder was replaced before build completed");
+	}
+	activeRecorder = undefined;
+	return recorder;
+}
+
+/** Record one declaration when metadata collection is active. */
+export function recordIntent(intent: InfraAsCodeIntent): void {
+	activeRecorder?.intents.push(intent);
+}

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

@@ -0,0 +1,19 @@
+import { APPS_RESERVED_RESOURCE_ID_PREFIX, type Parent } from "./intents.js";
+
+/** Validate parent references accepted by Apps declarations. */
+export function assertParent(parent: Parent): void {
+	if (parent.type !== "resourceId") {
+		throw new Error("Notion-as-Code parents must reference a resourceId");
+	}
+	assertUserResourceId(parent.resourceId);
+}
+
+/** Reject empty or runtime-reserved resource IDs in user declarations. */
+export function assertUserResourceId(resourceId: string): void {
+	if (resourceId.length === 0) {
+		throw new Error("Notion-as-Code resourceId must be a non-empty string");
+	}
+	if (resourceId.startsWith(APPS_RESERVED_RESOURCE_ID_PREFIX)) {
+		throw new Error(`Resource ID "${resourceId}" uses the reserved Apps prefix`);
+	}
+}

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

@@ -0,0 +1,149 @@
+// TODO: Converge on one schema. Until then, keep this translation layer aligned with Notion-as-Code.
+import { createDatabase, type Database } from "../database.js";
+import type { DatabaseSchema, PropertyConfiguration } from "../schema.js";
+import type { SelectOption, StatusGroup } from "../types.js";
+import type {
+	DataSourceDefinition,
+	NotionAsCodeProperty,
+	NotionAsCodeSelectOption,
+	NotionAsCodeStatusOption,
+} from "./intents.js";
+
+type AppsPropertyFor<Property extends NotionAsCodeProperty> = Property extends { type: "title" }
+	? { type: "title" }
+	: Property extends { type: "text" }
+		? { type: "text" }
+		: Property extends { type: "number" }
+			? { type: "number" }
+			: Property extends { type: "select" }
+				? { type: "select"; options: SelectOption[] }
+				: Property extends { type: "multi_select" }
+					? { type: "multi_select"; options: SelectOption[] }
+					: Property extends { type: "status" }
+						? { type: "status"; groups: StatusGroup[] }
+						: Property extends { type: "date" }
+							? { type: "date" }
+							: Property extends { type: "checkbox" }
+								? { type: "checkbox" }
+								: Property extends { type: "url" }
+									? { type: "url" }
+									: Property extends { type: "email" }
+										? { type: "email" }
+										: Property extends { type: "phone_number" }
+											? { type: "phone_number" }
+											: Property extends { type: "file" }
+												? { type: "file" }
+												: PropertyConfiguration;
+
+export type AppsSchemaForProperties<Properties extends readonly NotionAsCodeProperty[]> = {
+	[Property in Properties[number] as Property["name"]]: AppsPropertyFor<Property>;
+};
+
+/** Convert a Notion-as-Code data source into the Apps database used by sync handlers. */
+export function createAppsDatabase(
+	databaseKey: string,
+	dataSource: DataSourceDefinition,
+): Database {
+	const properties: DatabaseSchema = {};
+	const propertyResourceIds = new Set<string>();
+	let titleCount = 0;
+
+	for (const property of dataSource.properties) {
+		if (property.resourceId.length === 0) {
+			throw new Error(
+				`Data source "${dataSource.resourceId}" has a property without a resourceId`,
+			);
+		}
+		if (propertyResourceIds.has(property.resourceId)) {
+			throw new Error(
+				`Data source "${dataSource.resourceId}" has duplicate property resourceId "${property.resourceId}"`,
+			);
+		}
+		if (properties[property.name] !== undefined) {
+			throw new Error(
+				`Data source "${dataSource.resourceId}" has duplicate property name "${property.name}"`,
+			);
+		}
+		propertyResourceIds.add(property.resourceId);
+		if (property.type === "title") {
+			titleCount += 1;
+		}
+		properties[property.name] = toAppsProperty(dataSource.resourceId, property);
+	}
+
+	if (titleCount !== 1) {
+		throw new Error(
+			`Data source "${dataSource.resourceId}" must have exactly one title property to bind a sync`,
+		);
+	}
+
+	return createDatabase(databaseKey, {
+		initialTitle: dataSource.name,
+		schema: properties,
+	});
+}
+
+/** Map Notion-as-Code properties to Apps properties; their schemas differ for selects and status groups. */
+function toAppsProperty(
+	dataSourceResourceId: string,
+	property: NotionAsCodeProperty,
+): PropertyConfiguration {
+	switch (property.type) {
+		case "title":
+			return { type: "title" };
+		case "text":
+			return { type: "text" };
+		case "number":
+			return { type: "number" };
+		case "select":
+			return { type: "select", options: (property.options ?? []).map(toAppsSelectOption) };
+		case "multi_select":
+			return {
+				type: "multi_select",
+				options: (property.options ?? []).map(toAppsSelectOption),
+			};
+		case "status":
+			return {
+				type: "status",
+				groups: [
+					{ name: "To-do", options: property.options.todo.map(toAppsStatusOption) },
+					{
+						name: "In progress",
+						options: property.options.inProgress.map(toAppsStatusOption),
+					},
+					{
+						name: "Complete",
+						options: property.options.complete.map(toAppsStatusOption),
+					},
+				],
+			};
+		case "date":
+			return { type: "date" };
+		case "checkbox":
+			return { type: "checkbox" };
+		case "url":
+			return { type: "url" };
+		case "email":
+			return { type: "email" };
+		case "phone_number":
+			return { type: "phone_number" };
+		case "file":
+			return { type: "file" };
+		default:
+			throw new Error(
+				`Data source "${dataSourceResourceId}" property "${property.name}" uses unsupported sync type "${property.type}"`,
+			);
+	}
+}
+
+function toAppsSelectOption(option: NotionAsCodeSelectOption): SelectOption {
+	return option.color === undefined
+		? { name: option.name }
+		: { name: option.name, color: option.color };
+}
+
+function toAppsStatusOption(option: NotionAsCodeStatusOption): SelectOption {
+	return option.color === undefined
+		? { name: option.name }
+		: { name: option.name, color: option.color };
+}

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

@@ -0,0 +1,50 @@
+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 { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
+import { recordIntent } from "./recorder.js";
+import { assertUserResourceId } from "./resource.js";
+
+export type TeamspaceArgs = {
+	resourceId: ResourceId;
+	name: string;
+	accessLevel: "default" | "open" | "closed" | "private";
+	icon?: NotionAsCodeIcon;
+	description?: string;
+};
+
+export type TeamspaceHandle = {
+	readonly resourceId: string;
+	addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(
+		args: ChildDatabaseArgs<DataSources>,
+	) => DatabaseHandle<DataSources>;
+	addPage: (args: ChildPageArgs) => PageHandle;
+};
+
+/** Declare a teamspace that Apps automatically creates in its workspace. */
+export function teamspace(args: TeamspaceArgs): TeamspaceHandle {
+	assertUserResourceId(args.resourceId);
+	recordIntent({
+		type: "teamspace",
+		...args,
+		parent: { type: "resourceId", resourceId: APPS_WORKSPACE_RESOURCE_ID },
+	} satisfies { type: "teamspace" } & TeamspaceIntent);
+
+	return {
+		resourceId: args.resourceId,
+		addDatabase(databaseArgs) {
+			return database({
+				...databaseArgs,
+				parent: { type: "resourceId", resourceId: args.resourceId },
+			});
+		},
+		addPage(pageArgs) {
+			return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
+		},
+	};
+}

package/src/sync.ts

@@ -2,6 +2,9 @@ import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
 import type { Database } from "./database.js";
 import { ExecutionError, RateLimitError } from "./error.js";
+import type { DataSourceHandle } from "./notion-as-code/database.js";
+import type { NotionAsCodeProperty } from "./notion-as-code/intents.js";
+import type { AppsSchemaForProperties } from "./notion-as-code/schema.js";
 import { writeOutput } from "./output.js";
 import { initPacerState, pacerStates, type PacerEntry } from "./pacer.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
@@ -82,7 +85,25 @@ export type SyncConfiguration<
 	handler: (
 		state: State | undefined,
 		context: CapabilityContext,
-	) => Promise<SyncHandlerResult<S, PrimaryKey, State>>;
+	) => Promise<SyncHandlerResult<NoInfer<S>, NoInfer<PrimaryKey>, State>>;
+};
+
+/** Configuration for a sync backed by a Notion-as-Code data source. */
+type DataSourceSyncConfiguration<
+	Properties extends readonly NotionAsCodeProperty[],
+	PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	State,
+> = {
+	dataSource: DataSourceHandle<Properties>;
+	primaryKey: PrimaryKey;
+	mode?: SyncMode;
+	schedule?: Schedule;
+	handler: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<
+		SyncHandlerResult<NoInfer<AppsSchemaForProperties<Properties>>, NoInfer<PrimaryKey>, State>
+	>;
 };
 
 export type SyncRuntimeContext = {
@@ -98,6 +119,29 @@ type SyncDefinitionConfig = {
 	schedule?: NormalizedSchedule;
 };
 
+type SyncDatabaseConfiguration = { database: Database } | { dataSource: { database: Database } };
+
+type RuntimeSyncChange =
+	| { type: "delete"; key: string }
+	| { type: "upsert"; key: string; properties: Record<string, unknown> };
+
+type SyncDefinitionConfiguration<State> = SyncDatabaseConfiguration & {
+	primaryKey: string;
+	mode?: SyncMode;
+	schedule?: Schedule;
+	handler: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<{ changes: RuntimeSyncChange[]; hasMore?: boolean; nextState?: State }>;
+};
+
+/** Resolve a Notion-as-Code data source to the Apps database used by its sync. */
+function resolveSyncDatabase(configuration: SyncDatabaseConfiguration): Database {
+	return "dataSource" in configuration
+		? configuration.dataSource.database
+		: configuration.database;
+}
+
 export type SyncRunResult = {
 	changes: unknown[];
 	hasMore: boolean;
@@ -111,16 +155,30 @@ export type Sync = {
 	handler: (context?: SyncRuntimeContext, options?: HandlerOptions) => Promise<SyncRunResult>;
 };
 
-/** Create a database sync. Default-export it from a file in `src/syncs/`. */
+/** Create a database sync. Default-export it from a sync file. */
 export function createSync<
 	const S extends DatabaseSchema,
 	const PrimaryKey extends KeyPropertyName<S>,
 	State = unknown,
 >(configuration: SyncConfiguration<S, PrimaryKey, State>): Sync {
+	return createSyncDefinition(configuration);
+}
+
+/** Create a sync backed by a Notion-as-Code data source. */
+export function createDataSourceSync<
+	const Properties extends readonly NotionAsCodeProperty[],
+	const PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	State = unknown,
+>(configuration: DataSourceSyncConfiguration<Properties, PrimaryKey, State>): Sync {
+	return createSyncDefinition(configuration);
+}
+
+function createSyncDefinition<State>(configuration: SyncDefinitionConfiguration<State>): Sync {
 	const schedule =
 		configuration.schedule === undefined ? undefined : parseSchedule(configuration.schedule);
+	const database = resolveSyncDatabase(configuration);
 	const config: SyncDefinitionConfig = {
-		database: configuration.database,
+		database,
 		primaryKeyProperty: configuration.primaryKey,
 		...(configuration.mode === undefined ? {} : { mode: configuration.mode }),
 		...(schedule === undefined ? {} : { schedule }),
@@ -139,7 +197,7 @@ export function createSync<
 				const handlerResult = await configuration.handler(state, createCapabilityContext());
 				const changes = handlerResult.changes.map((change) => {
 					if (change.type === "delete") {
-						return { ...change, targetDatabaseKey: configuration.database.key };
+						return { ...change, targetDatabaseKey: database.key };
 					}
 					return {
 						...change,
@@ -147,7 +205,7 @@ export function createSync<
 							...change.properties,
 							[configuration.primaryKey]: [[change.key]],
 						},
-						targetDatabaseKey: configuration.database.key,
+						targetDatabaseKey: database.key,
 					};
 				});
 				const result: SyncRunResult = {