@notionhq/apps 0.0.17 → 0.0.19

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/views.ts

@@ -411,29 +411,48 @@ export type AdvancedFilterSchema = {
  * `dataSourceResourceId` must reference a data source created by the script or
  * supplied through existing resources.
  *
+ * Database declarations require at least one data source or at least one view.
+ * A linked-only database may omit `datasources`, or use `datasources: {}`, only
+ * when its `views` list is nonempty. `{}`, `{ datasources: {} }`, and
+ * `{ datasources: {}, views: [] }` are invalid.
+ *
+ * @example
+ * // A linked-only database can use a typed table view for an explicit source.
+ * const linkedTableView: TableViewSchema = {
+ *   resourceId: "issues-table-view",
+ *   type: "table",
+ *   dataSourceResourceId: "issues-source",
+ *   properties: [{ property: "issue-title", visible: true }]
+ * };
+ * const linkedDatabase = notion.database("issues-linked-database", {
+ *   parent: { type: "resourceId", resourceId: "project-page" },
+ *   views: [linkedTableView]
+ * })
+ *
  * @example
  * // When creating a database with a data source
- * const db = await notion.database({
- *   resourceId: "my-database",
- *   dataSources: [{ resourceId: "my-datasource", name: "Main", properties: [...] }]
+ * const db = notion.database("my-database", {
+ *   dataSourceResourceId: "my-datasource",
+ *   name: "Main",
+ *   schema: { Name: { resourceId: "my-title", type: "title" } }
  * })
  *
  * // Views must reference that data source
- * await db.addView({
+ * db.addView({
  *   resourceId: "my-table-view",
  *   type: "table",
  *   dataSourceResourceId: "my-datasource"  // REQUIRED: matches data source above
  * })
  *
  * @example
- * // A linked database can reference another script-created or existing data source
- * const linkedDatabase = await notion.database({
- *   resourceId: "linked-database",
- *   parent: { type: "resourceId", resourceId: "project-page" },
+ * // The explicit empty `datasources` form is valid with a nonempty view list.
+ * const explicitLinkedDatabase = notion.database("issues-linked-database-explicit", {
+ *   datasources: {},
  *   views: [{
- *     resourceId: "linked-table-view",
+ *     resourceId: "issues-table-view-explicit",
  *     type: "table",
- *     dataSourceResourceId: "my-datasource"  // Created elsewhere or supplied through an existing collection
+ *     dataSourceResourceId: "issues-source",
+ *     properties: [{ property: "issue-title", visible: true }]
  *   }]
  * })
  */

package/src/sync.test.ts

@@ -36,6 +36,20 @@ const keyTypes = createDatabase("key-types", {
 		Project: Schema.relation(projects),
 	},
 });
+const partialMeetings = createDatabase("partial-meetings", {
+	schema: {
+		Name: Schema.title(),
+		"Meeting ID": Schema.richText(),
+		Other: Schema.richText(),
+		"Meeting date": Schema.date(),
+		"Prep complete": Schema.checkbox(),
+	},
+});
+const keyOnly = createDatabase("key-only", {
+	schema: {
+		ID: Schema.richText(),
+	},
+});
 
 type IssueKey = KeyPropertyName<typeof issues.config.schema>;
 const textKey: IssueKey = "GitHub ID";
@@ -128,6 +142,188 @@ describe("createSync", () => {
 		).toBe("GitHub ID");
 	});
 
+	it("accepts partial upsert properties in standalone handlers", () => {
+		const finiteProperties = {
+			Name: Builder.title("Prepared"),
+			Unknown: Builder.text("unexpected"),
+		};
+		const spreadProperties = {
+			Unknown: Builder.text("unexpected from spread"),
+		};
+
+		createSync({
+			database: partialMeetings,
+			primaryKey: "Meeting ID",
+			handler: async (state: { cursor: number } | undefined) => ({
+				changes: [
+					{
+						type: "upsert",
+						key: "meeting-1",
+						properties: { Name: Builder.title("One") },
+					},
+					{
+						type: "upsert",
+						key: "meeting-2",
+						properties: {
+							"Meeting date": Builder.date("2026-09-16"),
+							"Prep complete": Builder.checkbox(true),
+						},
+					},
+					{ type: "delete", key: "meeting-3" },
+				],
+				nextState: { cursor: (state?.cursor ?? 0) + 1 },
+			}),
+		});
+
+		const invalidSyncDeclarations = () => {
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Unknown property keys are rejected in inferred handler returns.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-inline",
+							properties: {
+								Name: Builder.title("Known"),
+								Unknown: Builder.text("unexpected"),
+							},
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Unknown properties remain rejected when another change shares the key.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "same",
+							properties: {
+								Name: Builder.title("Known"),
+								Unknown: Builder.text("unexpected"),
+							},
+						},
+						{
+							type: "upsert",
+							key: "same",
+							properties: { Name: Builder.title("Known sibling") },
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Upsert properties must include a non-primary-key schema property.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-empty",
+							properties: {},
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Finite property objects cannot contain unknown keys.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-finite",
+							properties: finiteProperties,
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Spread property objects cannot contain unknown keys.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-spread",
+							properties: {
+								Name: Builder.title("Known from spread"),
+								...spreadProperties,
+							},
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error Known properties must use their declared value types.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-value",
+							properties: {
+								Name: Builder.people("person@example.com"),
+							},
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				primaryKey: "Meeting ID",
+				// @ts-expect-error The primary-key property is supplied from change.key.
+				handler: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "invalid-primary-property",
+							properties: {
+								"Meeting ID": Builder.text("explicit"),
+							},
+						},
+					],
+				}),
+			});
+			createSync({
+				database: partialMeetings,
+				// @ts-expect-error Unknown schema properties cannot be sync primary keys.
+				primaryKey: "Unknown",
+				handler: async () => ({ changes: [] }),
+			});
+		};
+		void invalidSyncDeclarations;
+	});
+
+	it("rejects key-only upserts but allows deletes", () => {
+		const invalidKeyOnlyUpsert = () => {
+			createSync({
+				database: keyOnly,
+				primaryKey: "ID",
+				// @ts-expect-error Upserts require at least one non-primary-key schema property.
+				handler: async () => ({
+					changes: [{ type: "upsert", key: "invalid-key-only", properties: {} }],
+				}),
+			});
+		};
+		void invalidKeyOnlyUpsert;
+
+		createSync({
+			database: keyOnly,
+			primaryKey: "ID",
+			handler: async () => ({
+				changes: [{ type: "delete", key: "deleted-key-only" }],
+			}),
+		});
+	});
+
 	it("rejects invalid schedules when the sync is created", () => {
 		expect(() =>
 			createSync({
@@ -177,6 +373,105 @@ describe("createSync", () => {
 		]);
 	});
 
+	it("preserves omitted properties, partial upserts, and deletes at runtime", async () => {
+		const sync = createSync({
+			database: partialMeetings,
+			primaryKey: "Meeting ID",
+			handler: async (state: { cursor: number } | undefined) => ({
+				changes: [
+					{
+						type: "upsert",
+						key: "meeting-1",
+						properties: { Name: Builder.title("One") },
+					},
+					{
+						type: "upsert",
+						key: "meeting-2",
+						properties: { Other: Builder.text("Only other") },
+					},
+					{
+						type: "upsert",
+						key: "meeting-3",
+						properties: {
+							"Meeting date": Builder.date("2026-09-16"),
+							"Prep complete": Builder.checkbox(true),
+						},
+					},
+					{ type: "delete", key: "meeting-4" },
+				],
+				nextState: { cursor: (state?.cursor ?? 0) + 1 },
+			}),
+		});
+
+		const result = await sync.handler({ state: { cursor: 4 } }, { concreteOutput: true });
+
+		expect(result).toEqual({
+			changes: [
+				{
+					type: "upsert",
+					key: "meeting-1",
+					properties: {
+						Name: [["One"]],
+						"Meeting ID": [["meeting-1"]],
+					},
+					targetDatabaseKey: "partial-meetings",
+				},
+				{
+					type: "upsert",
+					key: "meeting-2",
+					properties: {
+						Other: [["Only other"]],
+						"Meeting ID": [["meeting-2"]],
+					},
+					targetDatabaseKey: "partial-meetings",
+				},
+				{
+					type: "upsert",
+					key: "meeting-3",
+					properties: {
+						"Meeting date": [
+							["‣", [["d", { type: "date", start_date: "2026-09-16" }]]],
+						],
+						"Prep complete": [["Yes"]],
+						"Meeting ID": [["meeting-3"]],
+					},
+					targetDatabaseKey: "partial-meetings",
+				},
+				{
+					type: "delete",
+					key: "meeting-4",
+					targetDatabaseKey: "partial-meetings",
+				},
+			],
+			hasMore: false,
+			nextUserContext: { cursor: 5 },
+			nextPacerStates: {},
+		});
+	});
+
+	it("rejects empty upserts at runtime", async () => {
+		const sync = createSync({
+			database: partialMeetings,
+			primaryKey: "Meeting ID",
+			handler: async () => ({
+				changes: [
+					{
+						type: "upsert",
+						key: "meeting-empty",
+						properties: {},
+						icon: Builder.notionIcon("warning"),
+						cover: Builder.imageCover("https://example.com/empty-cover.png"),
+						pageContentMarkdown: "# Empty properties",
+					},
+				],
+			}),
+		} as never);
+
+		await expect(sync.handler(undefined, { concreteOutput: true })).rejects.toBeInstanceOf(
+			ExecutionError,
+		);
+	});
+
 	it("passes deletes, paging state, and incremental mode through", async () => {
 		const sync = createSync({
 			database: issues,

package/src/sync.ts

@@ -3,8 +3,8 @@ 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 type { NotionAsCodeSchema } from "./notion-as-code/intents.js";
+import type { AppsSchemaForSchema } 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";
@@ -45,12 +45,50 @@ type PropertyValue<T extends PropertyConfiguration> = T extends { type: "people"
 			? RelationValue
 			: TextValue;
 
+type SyncPropertyName<S extends DatabaseSchema> = Extract<keyof S, string>;
+
+/**
+ * Collect unknown property names across the whole inferred change union before checking it.
+ * Otherwise a valid subset properties object could structurally hide an invalid sibling row.
+ */
+type SyncUnknownPropertyNames<AllowedPropertyNames extends string, Change> = Change extends {
+	type: "upsert";
+	properties: infer Properties extends object;
+}
+	? Exclude<keyof Properties, AllowedPropertyNames>
+	: never;
+
+/** Require at least one key while keeping all other keys optional. */
+type AtLeastOne<T extends object> = Partial<T> &
+	{
+		[RequiredKey in keyof T]-?: Required<Pick<T, RequiredKey>>;
+	}[keyof T];
+
+type SyncUpsertProperties<
+	S extends DatabaseSchema,
+	PrimaryKey extends KeyPropertyName<S>,
+> = AtLeastOne<{
+	[P in Exclude<SyncPropertyName<S>, PrimaryKey>]: PropertyValue<S[P]>;
+}>;
+
+type ExactSyncHandlerResult<
+	AllowedPropertyNames extends string,
+	Result extends { changes: readonly unknown[] },
+> = Result & {
+	changes: [SyncUnknownPropertyNames<AllowedPropertyNames, Result["changes"][number]>] extends [
+		never,
+	]
+		? Result["changes"]
+		: never;
+};
+
 export type SyncMode = "replace" | "incremental";
 
+/** Upsert one or more known non-primary-key properties; the key is supplied separately. */
 export type SyncChangeUpsert<S extends DatabaseSchema, PrimaryKey extends KeyPropertyName<S>> = {
 	type: "upsert";
 	key: string;
-	properties: Omit<{ [P in keyof S]: PropertyValue<S[P]> }, PrimaryKey>;
+	properties: SyncUpsertProperties<S, PrimaryKey>;
 	upstreamUpdatedAt?: string;
 	icon?: Icon;
 	cover?: Cover;
@@ -77,6 +115,11 @@ export type SyncConfiguration<
 	S extends DatabaseSchema,
 	PrimaryKey extends KeyPropertyName<S>,
 	State,
+	Result extends SyncHandlerResult<S, PrimaryKey, State> = SyncHandlerResult<
+		S,
+		PrimaryKey,
+		State
+	>,
 > = {
 	database: Database<S>;
 	primaryKey: PrimaryKey;
@@ -85,25 +128,25 @@ export type SyncConfiguration<
 	handler: (
 		state: State | undefined,
 		context: CapabilityContext,
-	) => Promise<SyncHandlerResult<NoInfer<S>, NoInfer<PrimaryKey>, State>>;
+	) => Promise<
+		// NoInfer prevents handler output from widening the source schema or primary-key inference.
+		SyncHandlerResult<NoInfer<S>, NoInfer<PrimaryKey>, State> &
+			ExactSyncHandlerResult<
+				Exclude<SyncPropertyName<NoInfer<S>>, NoInfer<PrimaryKey>>,
+				Result
+			>
+	>;
 };
 
 /** Configuration for a sync backed by a Notion-as-Code data source. */
 export type DataSourceSyncConfiguration<
-	Properties extends readonly NotionAsCodeProperty[],
-	PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	Schema extends NotionAsCodeSchema,
+	PrimaryKey extends KeyPropertyName<AppsSchemaForSchema<Schema>>,
 	State,
-> = {
-	dataSource: DataSourceHandle<Properties>;
-	primaryKey: PrimaryKey;
-	mode?: SyncMode;
-	schedule?: Schedule;
-	handler: (
-		state: State | undefined,
-		context: CapabilityContext,
-	) => Promise<
-		SyncHandlerResult<NoInfer<AppsSchemaForProperties<Properties>>, NoInfer<PrimaryKey>, State>
-	>;
+	Result extends SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State> =
+		SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State>,
+> = Omit<SyncConfiguration<AppsSchemaForSchema<Schema>, PrimaryKey, State, Result>, "database"> & {
+	dataSource: DataSourceHandle<Schema>;
 };
 
 export type SyncRuntimeContext = {
@@ -160,16 +203,23 @@ export function createSync<
 	const S extends DatabaseSchema,
 	const PrimaryKey extends KeyPropertyName<S>,
 	State = unknown,
->(configuration: SyncConfiguration<S, PrimaryKey, State>): Sync {
+	const Result extends SyncHandlerResult<S, PrimaryKey, State> = SyncHandlerResult<
+		S,
+		PrimaryKey,
+		State
+	>,
+>(configuration: SyncConfiguration<S, PrimaryKey, State, Result>): Sync {
 	return createSyncDefinition(configuration);
 }
 
 /** Create a sync backed by a Notion-as-Code data source. */
 export function sync<
-	const Properties extends readonly NotionAsCodeProperty[],
-	const PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	const Schema extends NotionAsCodeSchema,
+	const PrimaryKey extends KeyPropertyName<AppsSchemaForSchema<Schema>>,
 	State = unknown,
->(configuration: DataSourceSyncConfiguration<Properties, PrimaryKey, State>): Sync {
+	const Result extends SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State> =
+		SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State>,
+>(configuration: DataSourceSyncConfiguration<Schema, PrimaryKey, State, Result>): Sync {
 	return createSyncDefinition(configuration);
 }
 
@@ -199,6 +249,20 @@ function createSyncDefinition<State>(configuration: SyncDefinitionConfiguration<
 					if (change.type === "delete") {
 						return { ...change, targetDatabaseKey: database.key };
 					}
+
+					let hasOwnEnumerableProperty = false;
+					for (const propertyName in change.properties) {
+						if (Object.hasOwn(change.properties, propertyName)) {
+							hasOwnEnumerableProperty = true;
+							break;
+						}
+					}
+					if (!hasOwnEnumerableProperty) {
+						throw new Error(
+							"Sync upsert properties must include at least one property.",
+						);
+					}
+
 					return {
 						...change,
 						properties: {

package/src/workflow-access-types.test.ts

@@ -0,0 +1,69 @@
+import { expectTypeOf, it } from "vitest";
+
+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";
+
+it("infers access aliases and rejects resource-specific levels", () => {
+	const home = page({ resourceId: "home" });
+	const agent = customAgent({ resourceId: "agent", name: "Agent" });
+	const singleDatabase = database("single-database", {
+		dataSourceResourceId: "single-source",
+		name: "Single",
+		schema: { Title: { resourceId: "single-title", type: "title" } },
+	});
+	const multiDatabase = database("multi-database", {
+		name: "Multi",
+		datasources: {
+			Records: {
+				resourceId: "multi-source",
+				schema: { Title: { resourceId: "multi-title", type: "title" } },
+			},
+		},
+	});
+	workflow({
+		name: "Access types",
+		description: "Checks access types",
+		triggers: [triggers.notionPageCreated()],
+		access: {
+			home: { resource: home, level: "view" },
+			singleDatabase: { resource: singleDatabase, level: "edit" },
+			multiDatabase: { resource: multiDatabase, level: "view" },
+		},
+		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">();
+			// @ts-expect-error Access aliases are limited to declarations.
+			void context.access.missing;
+			// @ts-expect-error Access values are readonly.
+			context.access.home.id = "changed";
+			// @ts-expect-error The access map is readonly.
+			context.access = {};
+		},
+	});
+
+	const invalidAccessLevels = () => {
+		workflow({
+			name: "Agent access types",
+			description: "Checks custom agent access types",
+			triggers: [triggers.notionPageCreated()],
+			// @ts-expect-error Custom agents only support the call level.
+			access: { agent: { resource: agent, level: "view" } },
+			handler: () => {},
+		});
+
+		workflow({
+			name: "Page access types",
+			description: "Checks page access types",
+			triggers: [triggers.notionPageCreated()],
+			// @ts-expect-error Pages do not support the custom-agent call level.
+			access: { home: { resource: home, level: "call" } },
+			handler: () => {},
+		});
+	};
+	void invalidAccessLevels;
+});