@notionhq/apps 0.0.3 → 0.0.6

package/src/schedule.ts

@@ -0,0 +1,25 @@
+import type { NormalizedSchedule, Schedule, TimeUnit } from "./types.js";
+
+const MIN_INTERVAL_MS = 60_000;
+const MAX_INTERVAL_MS = 7 * 24 * 60 * 60_000;
+
+export function parseSchedule(schedule: Schedule): NormalizedSchedule {
+	if (schedule === "continuous" || schedule === "manual") return { type: schedule };
+
+	const match = schedule.match(/^(\d+)(m|h|d)$/);
+	if (!match?.[1] || !match[2]) {
+		throw new Error(`Invalid schedule format: "${schedule}"`);
+	}
+
+	const value = Number.parseInt(match[1], 10);
+	const multipliers: Record<TimeUnit, number> = {
+		m: 60_000,
+		h: 60 * 60_000,
+		d: 24 * 60 * 60_000,
+	};
+	const intervalMs = value * multipliers[match[2] as TimeUnit];
+	if (intervalMs < MIN_INTERVAL_MS)
+		throw new Error("Schedule interval must be at least 1 minute");
+	if (intervalMs > MAX_INTERVAL_MS) throw new Error("Schedule interval must be at most 7 days");
+	return { type: "interval", intervalMs };
+}

package/src/schema.ts

@@ -0,0 +1,73 @@
+import type { Database } from "./database.js";
+import type { DateFormat, Icon, NumberFormat, SelectOption, StatusGroup } from "./types.js";
+
+export type TitleProperty = { type: "title" };
+export type TextProperty = { type: "text" };
+
+export type PropertyConfiguration =
+	| TitleProperty
+	| TextProperty
+	| { type: "url" }
+	| { type: "email" }
+	| { type: "phone_number" }
+	| { type: "checkbox" }
+	| { type: "file" }
+	| { type: "number"; format?: NumberFormat }
+	| { type: "date"; date_format?: DateFormat }
+	| { type: "select"; options: SelectOption[] }
+	| { type: "multi_select"; options: SelectOption[] }
+	| { type: "status"; groups: StatusGroup[] }
+	| { type: "people" }
+	| { type: "place" }
+	| {
+			type: "relation";
+			database: Database;
+			config: { twoWay: false } | { twoWay: true; relatedPropertyName: string };
+	  };
+
+export type DatabaseSchema = Record<string, PropertyConfiguration>;
+
+export type DatabaseSchemaOptions = {
+	databaseIcon?: Icon;
+	subItems?: { parentPropertyName: string; childPropertyName: string };
+};
+
+export const Schema = {
+	title: (): TitleProperty => ({ type: "title" }),
+	richText: (): TextProperty => ({ type: "text" }),
+	url: (): { type: "url" } => ({ type: "url" }),
+	email: (): { type: "email" } => ({ type: "email" }),
+	phoneNumber: (): { type: "phone_number" } => ({ type: "phone_number" }),
+	checkbox: (): { type: "checkbox" } => ({ type: "checkbox" }),
+	file: (): { type: "file" } => ({ type: "file" }),
+	number: (format?: NumberFormat): { type: "number"; format?: NumberFormat } => ({
+		type: "number",
+		...(format === undefined ? {} : { format }),
+	}),
+	date: (date_format?: DateFormat): { type: "date"; date_format?: DateFormat } => ({
+		type: "date",
+		...(date_format === undefined ? {} : { date_format }),
+	}),
+	select: (options: SelectOption[]): { type: "select"; options: SelectOption[] } => ({
+		type: "select",
+		options,
+	}),
+	multiSelect: (options: SelectOption[]): { type: "multi_select"; options: SelectOption[] } => ({
+		type: "multi_select",
+		options,
+	}),
+	status: (config: { groups: StatusGroup[] }): { type: "status"; groups: StatusGroup[] } => ({
+		type: "status",
+		groups: config.groups,
+	}),
+	people: (): { type: "people" } => ({ type: "people" }),
+	place: (): { type: "place" } => ({ type: "place" }),
+	relation: (
+		database: Database,
+		config?: { twoWay: false } | { twoWay: true; relatedPropertyName: string },
+	): Extract<PropertyConfiguration, { type: "relation" }> => ({
+		type: "relation",
+		database,
+		config: config ?? { twoWay: false },
+	}),
+};

package/src/sync.test.ts

@@ -0,0 +1,359 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+
+import { Builder } from "./builder.js";
+import { createDatabase } from "./database.js";
+import { ExecutionError, RateLimitError } from "./error.js";
+import { createPacer } from "./pacer.js";
+import { Schema } from "./schema.js";
+import { createSync, type KeyPropertyName } from "./sync.js";
+
+const issues = createDatabase("issues", {
+	schema: {
+		Name: Schema.title(),
+		"GitHub ID": Schema.richText(),
+		Closed: Schema.checkbox(),
+	},
+});
+
+const projects = createDatabase("projects", {
+	schema: {
+		Name: Schema.title(),
+		"Project ID": Schema.richText(),
+	},
+});
+
+const keyTypes = createDatabase("key-types", {
+	schema: {
+		Name: Schema.title(),
+		ID: Schema.richText(),
+		Closed: Schema.checkbox(),
+		Count: Schema.number(),
+		Due: Schema.date(),
+		Project: Schema.relation(projects),
+	},
+});
+
+type IssueKey = KeyPropertyName<typeof issues.config.schema>;
+const textKey: IssueKey = "GitHub ID";
+const titleKey: IssueKey = "Name";
+// @ts-expect-error Checkboxes cannot be sync primary keys.
+const checkboxKey: IssueKey = "Closed";
+// @ts-expect-error The primary key must exist in the schema.
+const missingKey: IssueKey = "Missing";
+void [textKey, titleKey, checkboxKey, missingKey];
+
+createSync({
+	database: keyTypes,
+	// @ts-expect-error Checkboxes cannot be sync primary keys.
+	primaryKey: "Closed",
+	handler: async () => ({ changes: [] }),
+});
+createSync({
+	database: keyTypes,
+	// @ts-expect-error Numbers cannot be sync primary keys.
+	primaryKey: "Count",
+	handler: async () => ({ changes: [] }),
+});
+createSync({
+	database: keyTypes,
+	// @ts-expect-error Dates cannot be sync primary keys.
+	primaryKey: "Due",
+	handler: async () => ({ changes: [] }),
+});
+createSync({
+	database: keyTypes,
+	// @ts-expect-error Relations cannot be sync primary keys.
+	primaryKey: "Project",
+	handler: async () => ({ changes: [] }),
+});
+createSync({
+	database: keyTypes,
+	// @ts-expect-error The primary key must be present in the database schema.
+	primaryKey: "Missing",
+	handler: async () => ({ changes: [] }),
+});
+
+let stdoutSpy: Mock<typeof process.stdout.write>;
+let inputDirectory: string | undefined;
+
+beforeEach(() => {
+	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(async () => {
+	stdoutSpy.mockRestore();
+	vi.unstubAllEnvs();
+	if (inputDirectory !== undefined) {
+		await rm(inputDirectory, { recursive: true, force: true });
+		inputDirectory = undefined;
+	}
+});
+
+describe("createSync", () => {
+	it("stores its primary key on the sync config", () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			mode: "replace",
+			schedule: "1h",
+			handler: async () => ({ changes: [] }),
+		});
+
+		expect(sync.config).toEqual({
+			database: issues,
+			primaryKeyProperty: "GitHub ID",
+			mode: "replace",
+			schedule: { type: "interval", intervalMs: 3_600_000 },
+		});
+	});
+
+	it("accepts title and rich-text primary keys", () => {
+		expect(
+			createSync({
+				database: issues,
+				primaryKey: "Name",
+				handler: async () => ({ changes: [] }),
+			}).config.primaryKeyProperty,
+		).toBe("Name");
+		expect(
+			createSync({
+				database: issues,
+				primaryKey: "GitHub ID",
+				handler: async () => ({ changes: [] }),
+			}).config.primaryKeyProperty,
+		).toBe("GitHub ID");
+	});
+
+	it("rejects invalid schedules when the sync is created", () => {
+		expect(() =>
+			createSync({
+				database: issues,
+				primaryKey: "GitHub ID",
+				schedule: "30d",
+				handler: async () => ({ changes: [] }),
+			}),
+		).toThrow(/at most 7 days/);
+	});
+
+	it("writes the key property and replaces an unsafe handler value", async () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler: async () => ({
+				changes: [
+					{
+						type: "upsert",
+						key: "issue-123",
+						properties: {
+							Name: Builder.title("Fix the bug"),
+							Closed: Builder.checkbox(false),
+							...({ "GitHub ID": Builder.richText("wrong") } as Record<
+								string,
+								unknown
+							>),
+						},
+					},
+				],
+			}),
+		});
+
+		const result = await sync.handler(undefined, { concreteOutput: true });
+
+		expect(result.changes).toEqual([
+			{
+				type: "upsert",
+				key: "issue-123",
+				properties: {
+					Name: [["Fix the bug"]],
+					Closed: [["No"]],
+					"GitHub ID": [["issue-123"]],
+				},
+				targetDatabaseKey: "issues",
+			},
+		]);
+	});
+
+	it("passes deletes, paging state, and incremental mode through", async () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			mode: "incremental",
+			handler: async (state: { cursor: string } | undefined) => ({
+				changes: [{ type: "delete", key: "issue-123" }],
+				hasMore: true,
+				nextState: { cursor: `${state?.cursor ?? ""}next` },
+			}),
+		});
+
+		const result = await sync.handler({ state: { cursor: "page-" } }, { concreteOutput: true });
+
+		expect(sync.config.mode).toBe("incremental");
+		expect(result).toEqual({
+			changes: [{ type: "delete", key: "issue-123", targetDatabaseKey: "issues" }],
+			hasMore: true,
+			nextUserContext: { cursor: "page-next" },
+			nextPacerStates: {},
+		});
+	});
+
+	it("uses file-backed runtime state instead of inline state", async () => {
+		const handler = vi.fn(async (state: { cursor: string } | undefined) => {
+			if (state === undefined) throw new Error("Expected sync state");
+			return { changes: [], nextState: state };
+		});
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler,
+		});
+		inputDirectory = await mkdtemp(join(tmpdir(), "notion-apps-sync-input-"));
+		const inputPath = join(inputDirectory, "input.json");
+		await writeFile(inputPath, JSON.stringify({ state: { cursor: "file" } }));
+		vi.stubEnv("NOTION_INPUT_PAYLOAD_PATH", inputPath);
+
+		const result = await sync.handler(
+			{ state: { cursor: "inline" } },
+			{ concreteOutput: true },
+		);
+
+		expect(handler).toHaveBeenCalledWith({ cursor: "file" }, expect.anything());
+		expect(result.nextUserContext).toEqual({ cursor: "file" });
+	});
+
+	it("passes relations, icons, covers, and page content through", async () => {
+		const tasks = createDatabase("tasks", {
+			schema: {
+				Name: Schema.title(),
+				ID: Schema.richText(),
+				Project: Schema.relation(projects),
+			},
+		});
+		const sync = createSync({
+			database: tasks,
+			primaryKey: "ID",
+			handler: async () => ({
+				changes: [
+					{
+						type: "upsert",
+						key: "task-1",
+						properties: {
+							Name: Builder.title("Write tests"),
+							Project: [Builder.relation("project-1")],
+						},
+						icon: Builder.emojiIcon("✅"),
+						cover: Builder.imageCover("https://example.com/cover.png"),
+						pageContentMarkdown: "# Details",
+					},
+				],
+			}),
+		});
+
+		const result = await sync.handler(undefined, { concreteOutput: true });
+
+		expect(result.changes).toEqual([
+			{
+				type: "upsert",
+				key: "task-1",
+				properties: {
+					Name: [["Write tests"]],
+					ID: [["task-1"]],
+					Project: [{ type: "primaryKey", value: "project-1" }],
+				},
+				icon: { type: "emoji", value: "✅" },
+				cover: {
+					type: "image",
+					url: "https://example.com/cover.png",
+					position: 0.5,
+				},
+				pageContentMarkdown: "# Details",
+				targetDatabaseKey: "tasks",
+			},
+		]);
+	});
+
+	it("returns the result and writes a success envelope", async () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler: async () => ({ changes: [] }),
+		});
+
+		await expect(sync.handler()).resolves.toEqual({
+			changes: [],
+			hasMore: false,
+			nextUserContext: undefined,
+			nextPacerStates: {},
+		});
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			'\n<__notion_output__>{"_tag":"success","value":{"changes":[],"hasMore":false,"nextPacerStates":{}}}</__notion_output__>\n',
+		);
+	});
+
+	it("threads platform pacer state through the handler", async () => {
+		const pacer = createPacer("sync-test-pacer", {
+			allowedRequests: 10,
+			intervalMs: 1_000,
+		});
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler: async () => {
+				await pacer.wait();
+				return { changes: [] };
+			},
+		});
+
+		const result = await sync.handler(
+			{
+				pacers: {
+					[pacer.name]: {
+						lastScheduledAtMs: 0,
+						allowedRequests: 5,
+						intervalMs: 500,
+					},
+				},
+			},
+			{ concreteOutput: true },
+		);
+
+		expect(result.nextPacerStates[pacer.name]).toMatchObject({
+			allowedRequests: 5,
+			intervalMs: 500,
+			lastScheduledAtMs: expect.any(Number),
+		});
+	});
+
+	it("writes a rate-limit envelope and rethrows the rate-limit error", async () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler: async () => {
+				throw new RateLimitError({ retryAfter: 30 });
+			},
+		});
+
+		await expect(sync.handler()).rejects.toBeInstanceOf(RateLimitError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			'\n<__notion_output__>{"_tag":"error","error":{"_tag":"rate_limit","name":"RateLimitError","message":"Error during app execution: Rate limited by external API","retryAfter":30}}</__notion_output__>\n',
+		);
+	});
+
+	it("writes a generic error envelope and throws ExecutionError", async () => {
+		const sync = createSync({
+			database: issues,
+			primaryKey: "GitHub ID",
+			handler: async () => {
+				throw new Error("boom");
+			},
+		});
+
+		await expect(sync.handler()).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			'\n<__notion_output__>{"_tag":"error","error":{"_tag":"generic","name":"ExecutionError","message":"Error during app execution: Error: boom"}}</__notion_output__>\n',
+		);
+	});
+});

package/src/sync.ts

@@ -0,0 +1,190 @@
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import type { Database } from "./database.js";
+import { ExecutionError, RateLimitError } from "./error.js";
+import { writeOutput } from "./output.js";
+import { initPacerState, pacerStates, type PacerEntry } from "./pacer.js";
+import { resolveRuntimeInput } from "./runtime-input.js";
+import { parseSchedule } from "./schedule.js";
+import type {
+	DatabaseSchema,
+	PropertyConfiguration,
+	TextProperty,
+	TitleProperty,
+} from "./schema.js";
+import type {
+	Cover,
+	HandlerOptions,
+	Icon,
+	NormalizedSchedule,
+	PeopleValue,
+	PlaceValue,
+	RelationValue,
+	Schedule,
+	TextValue,
+} from "./types.js";
+
+type KeyProperty = TitleProperty | TextProperty;
+
+/** Names of title or rich-text properties in a database schema. */
+export type KeyPropertyName<S extends DatabaseSchema> = Extract<
+	{
+		[P in keyof S]: S[P] extends KeyProperty ? P : never;
+	}[keyof S],
+	string
+>;
+
+type PropertyValue<T extends PropertyConfiguration> = T extends { type: "people" }
+	? PeopleValue
+	: T extends { type: "place" }
+		? PlaceValue
+		: T extends { type: "relation" }
+			? RelationValue
+			: TextValue;
+
+export type SyncMode = "replace" | "incremental";
+
+export type SyncChangeUpsert<S extends DatabaseSchema, PrimaryKey extends KeyPropertyName<S>> = {
+	type: "upsert";
+	key: string;
+	properties: Omit<{ [P in keyof S]: PropertyValue<S[P]> }, PrimaryKey>;
+	upstreamUpdatedAt?: string;
+	icon?: Icon;
+	cover?: Cover;
+	pageContentMarkdown?: string;
+};
+
+export type SyncChangeDelete = { type: "delete"; key: string };
+
+export type SyncChange<S extends DatabaseSchema, PrimaryKey extends KeyPropertyName<S>> =
+	| SyncChangeUpsert<S, PrimaryKey>
+	| SyncChangeDelete;
+
+export type SyncHandlerResult<
+	S extends DatabaseSchema,
+	PrimaryKey extends KeyPropertyName<S>,
+	State,
+> = {
+	changes: SyncChange<S, PrimaryKey>[];
+	hasMore?: boolean;
+	nextState?: State;
+};
+
+export type SyncConfiguration<
+	S extends DatabaseSchema,
+	PrimaryKey extends KeyPropertyName<S>,
+	State,
+> = {
+	database: Database<S>;
+	primaryKey: PrimaryKey;
+	mode?: SyncMode;
+	schedule?: Schedule;
+	handler: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<SyncHandlerResult<S, PrimaryKey, State>>;
+};
+
+export type SyncRuntimeContext = {
+	state?: unknown;
+	userContext?: unknown;
+	pacers?: Record<string, PacerEntry>;
+};
+
+type SyncDefinitionConfig = {
+	database: Database;
+	primaryKeyProperty: string;
+	mode?: SyncMode;
+	schedule?: NormalizedSchedule;
+};
+
+export type SyncRunResult = {
+	changes: unknown[];
+	hasMore: boolean;
+	nextUserContext?: unknown;
+	nextPacerStates: Record<string, PacerEntry>;
+};
+
+export type Sync = {
+	_tag: "sync";
+	config: SyncDefinitionConfig;
+	handler: (context?: SyncRuntimeContext, options?: HandlerOptions) => Promise<SyncRunResult>;
+};
+
+/** Create a database sync. Default-export it from a file in `src/syncs/`. */
+export function createSync<
+	const S extends DatabaseSchema,
+	const PrimaryKey extends KeyPropertyName<S>,
+	State = unknown,
+>(configuration: SyncConfiguration<S, PrimaryKey, State>): Sync {
+	const schedule =
+		configuration.schedule === undefined ? undefined : parseSchedule(configuration.schedule);
+	const config: SyncDefinitionConfig = {
+		database: configuration.database,
+		primaryKeyProperty: configuration.primaryKey,
+		...(configuration.mode === undefined ? {} : { mode: configuration.mode }),
+		...(schedule === undefined ? {} : { schedule }),
+	};
+
+	return {
+		_tag: "sync",
+		config,
+		async handler(runtimeContext, options) {
+			try {
+				runtimeContext = await resolveRuntimeInput(runtimeContext);
+				initPacerState(runtimeContext?.pacers);
+				const state = (runtimeContext?.state ?? runtimeContext?.userContext) as
+					| State
+					| undefined;
+				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,
+						properties: {
+							...change.properties,
+							[configuration.primaryKey]: [[change.key]],
+						},
+						targetDatabaseKey: configuration.database.key,
+					};
+				});
+				const result: SyncRunResult = {
+					changes,
+					hasMore: handlerResult.hasMore ?? false,
+					nextUserContext: handlerResult.nextState,
+					nextPacerStates: pacerStates(),
+				};
+
+				if (options?.concreteOutput) return result;
+				writeOutput({ _tag: "success", value: result });
+				return result;
+			} catch (cause) {
+				if (cause instanceof RateLimitError) {
+					if (!options?.concreteOutput) {
+						writeOutput({
+							_tag: "error",
+							error: {
+								_tag: "rate_limit",
+								name: cause.name,
+								message: cause.message,
+								retryAfter: cause.retryAfter,
+							},
+						});
+					}
+					throw cause;
+				}
+
+				const error = new ExecutionError(cause);
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: { _tag: "generic", name: error.name, message: error.message },
+					});
+				}
+				throw error;
+			}
+		},
+	};
+}

package/src/triggers.generated.ts

@@ -404,7 +404,7 @@ export const triggers = {
 	 *
 	 * A recurring schedule fired.
 	 */
-	recurrence(): RecurrenceTrigger {
+	scheduled(): RecurrenceTrigger {
 		return {
 			type: "recurrence",
 		};