@notionhq/apps 0.0.4 → 0.0.7

package/docs/BUILD.md

@@ -43,6 +43,7 @@ The workflow-only manifest retains the platform's existing resource fields as em
 
 ```json
 {
+	"$schema": "notion:apps-manifest:v1",
 	"sdkVersion": "0.0.1",
 	"databases": [],
 	"xldbs": [],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.4",
+	"version": "0.0.7",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {
@@ -19,10 +19,34 @@
 			"types": "./dist/context.d.ts",
 			"default": "./dist/context.js"
 		},
+		"./builder": {
+			"types": "./dist/builder.d.ts",
+			"default": "./dist/builder.js"
+		},
+		"./database": {
+			"types": "./dist/database.d.ts",
+			"default": "./dist/database.js"
+		},
 		"./error": {
 			"types": "./dist/error.d.ts",
 			"default": "./dist/error.js"
 		},
+		"./pacer": {
+			"types": "./dist/pacer.d.ts",
+			"default": "./dist/pacer.js"
+		},
+		"./schema": {
+			"types": "./dist/schema.d.ts",
+			"default": "./dist/schema.js"
+		},
+		"./sync": {
+			"types": "./dist/sync.d.ts",
+			"default": "./dist/sync.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts",
+			"default": "./dist/types.js"
+		},
 		"./manifest": {
 			"types": "./dist/manifest.d.ts",
 			"default": "./dist/manifest.js"
@@ -40,6 +64,10 @@
 		"access": "public"
 	},
 	"scripts": {
+		"fmt": "oxfmt",
+		"fmt:check": "oxfmt --check",
+		"lint": "oxlint --no-error-on-unmatched-pattern",
+		"lint:fix": "oxlint --fix --no-error-on-unmatched-pattern",
 		"build": "rm -rf dist && pnpm run build:types && pnpm run build:js",
 		"build:types": "tsc",
 		"build:js": "tsx scripts/build.ts",
@@ -60,6 +88,8 @@
 		"@types/node": "^26.0.0",
 		"concurrently": "^9.2.1",
 		"esbuild": "^0.27.3",
+		"oxfmt": "^0.65.0",
+		"oxlint": "^1.80.0",
 		"tsx": "^4.20.6",
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.8"
@@ -70,5 +100,6 @@
 	"engines": {
 		"node": ">=26.0.0",
 		"pnpm": ">=11.24.0"
-	}
+	},
+	"packageManager": "pnpm@11.24.0"
 }

package/src/builder.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+
+import { Builder } from "./builder.js";
+
+describe("Builder", () => {
+	it("builds text, number, select, people, and file values", () => {
+		expect(Builder.richText("hello")).toEqual([["hello"]]);
+		expect(Builder.number(42)).toEqual([["42"]]);
+		expect(Builder.number(Number.NaN)).toEqual([]);
+		expect(Builder.select("Open")).toEqual([["Open"]]);
+		expect(Builder.multiSelect("Bug", "Urgent")).toEqual([["Bug,Urgent"]]);
+		expect(Builder.status("In progress")).toEqual([["In progress"]]);
+		expect(Builder.people("ada@example.com")).toEqual([{ email: "ada@example.com" }]);
+		expect(Builder.file("https://example.com/file.pdf", "File")).toEqual([
+			["File", [["a", "https://example.com/file.pdf"]]],
+		]);
+	});
+
+	it("builds dates and date ranges", () => {
+		expect(Builder.date("2026-08-26")).toEqual([
+			["‣", [["d", { type: "date", start_date: "2026-08-26" }]]],
+		]);
+		expect(Builder.dateTime("2026-08-26T10:30:00Z", "America/New_York")).toEqual([
+			[
+				"‣",
+				[
+					[
+						"d",
+						{
+							type: "datetime",
+							start_date: "2026-08-26",
+							start_time: "10:30",
+							time_zone: "America/New_York",
+						},
+					],
+				],
+			],
+		]);
+		expect(Builder.dateRange("2026-08-26", "2026-08-27")).toEqual([
+			[
+				"‣",
+				[
+					[
+						"d",
+						{
+							type: "daterange",
+							start_date: "2026-08-26",
+							end_date: "2026-08-27",
+						},
+					],
+				],
+			],
+		]);
+	});
+
+	it("builds places, relations, icons, and covers", () => {
+		expect(Builder.place({ lat: 40.7128, lon: -74.006, name: "New York" })).toEqual({
+			lat: 40.7128,
+			lon: -74.006,
+			name: "New York",
+		});
+		expect(Builder.relation("project-1")).toEqual({
+			type: "primaryKey",
+			value: "project-1",
+		});
+		expect(Builder.notionIcon("checkmark", "green")).toEqual({
+			type: "notion",
+			icon: "checkmark",
+			color: "green",
+		});
+		expect(Builder.imageIcon("https://example.com/icon.png")).toEqual({
+			type: "image",
+			url: "https://example.com/icon.png",
+		});
+		expect(Builder.imageCover("https://example.com/cover.png", 0.25)).toEqual({
+			type: "image",
+			url: "https://example.com/cover.png",
+			position: 0.25,
+		});
+	});
+});

package/src/builder.ts

@@ -0,0 +1,99 @@
+import type {
+	Cover,
+	DateValue,
+	Icon,
+	NoticonColor,
+	PeopleValue,
+	PlaceValue,
+	RelationReference,
+	TextValue,
+} from "./types.js";
+
+function validateDateString(value: string): void {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(new Date(value).getTime())) {
+		throw new Error(`Invalid date: ${value}. Expected YYYY-MM-DD.`);
+	}
+}
+
+function dateToken(value: DateValue): TextValue {
+	return [["‣", [["d", value]]]];
+}
+
+function parseISODateTime(value: string): { date: string; time: string } {
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value) || Number.isNaN(new Date(value).getTime())) {
+		throw new Error(`Invalid ISO 8601 datetime: ${value}`);
+	}
+	return { date: value.slice(0, 10), time: value.slice(11, 16) };
+}
+
+/** Build property values returned by a sync handler. */
+export const Builder = {
+	richText: (content: string): TextValue => [[content]],
+	text: (content: string): TextValue => [[content]],
+	title: (content: string): TextValue => [[content]],
+	url: (url: string): TextValue => [[url]],
+	email: (email: string): TextValue => [[email]],
+	phoneNumber: (phone: string): TextValue => [[phone]],
+	checkbox: (checked: boolean): TextValue => (checked ? [["Yes"]] : [["No"]]),
+	file: (url: string, name?: string): TextValue => [[name ?? url, [["a", url]]]],
+	number: (value: number): TextValue => (Number.isNaN(value) ? [] : [[String(value)]]),
+	date(value: string): TextValue {
+		validateDateString(value);
+		return dateToken({ type: "date", start_date: value });
+	},
+	dateTime(value: string, timeZone?: string): TextValue {
+		const parsed = parseISODateTime(value);
+		return dateToken({
+			type: "datetime",
+			start_date: parsed.date,
+			start_time: parsed.time,
+			...(timeZone === undefined ? {} : { time_zone: timeZone }),
+		});
+	},
+	dateRange(startDate: string, endDate: string): TextValue {
+		validateDateString(startDate);
+		validateDateString(endDate);
+		return dateToken({ type: "daterange", start_date: startDate, end_date: endDate });
+	},
+	dateTimeRange(startValue: string, endValue: string, timeZone?: string): TextValue {
+		const start = parseISODateTime(startValue);
+		const end = parseISODateTime(endValue);
+		return dateToken({
+			type: "datetimerange",
+			start_date: start.date,
+			start_time: start.time,
+			end_date: end.date,
+			end_time: end.time,
+			...(timeZone === undefined ? {} : { time_zone: timeZone }),
+		});
+	},
+	link: (text: string, url: string): TextValue => [[text, [["a", url]]]],
+	select: (value: string): TextValue => [[value]],
+	multiSelect: (...values: string[]): TextValue =>
+		values.length === 0 ? [] : [[values.join(",")]],
+	status: (value: string): TextValue => [[value]],
+	people: (...emails: string[]): PeopleValue => emails.map((email) => ({ email })),
+	place(value: PlaceValue): PlaceValue {
+		if (!Number.isFinite(value.lat) || !Number.isFinite(value.lon)) {
+			throw new Error("Place value must have numeric lat and lon coordinates");
+		}
+		return value;
+	},
+	relation: (primaryKey: string): RelationReference => ({
+		type: "primaryKey",
+		value: primaryKey,
+	}),
+	emojiIcon: (value: string): Icon => ({ type: "emoji", value }),
+	notionIcon: (icon: string, color: NoticonColor = "gray"): Icon => ({
+		type: "notion",
+		icon,
+		color,
+	}),
+	imageIcon: (url: string): Icon => ({ type: "image", url }),
+	imageCover(url: string, position = 0.5): Cover {
+		if (!Number.isFinite(position) || position < 0 || position > 1) {
+			throw new Error("Cover position must be between 0 and 1");
+		}
+		return { type: "image", url, position };
+	},
+};

package/src/cli/build.test.ts

@@ -34,10 +34,49 @@ afterEach(async () => {
 });
 
 describe("buildApp", () => {
+	it("builds a sync manifest with an attached database contract", async () => {
+		const { manifest } = await buildApp(example("sync"));
+
+		expect(manifest).toEqual({
+			$schema: "notion:apps-manifest:v1",
+			sdkVersion: SDK_VERSION,
+			databases: [
+				{
+					key: "issues",
+					config: {
+						initialTitle: "GitHub Issues",
+						schema: {
+							properties: {
+								Name: { type: "title" },
+								"GitHub ID": { type: "text" },
+								Closed: { type: "checkbox" },
+							},
+						},
+					},
+				},
+			],
+			xldbs: [],
+			pacers: [],
+			capabilities: [
+				{
+					type: "sync",
+					key: "issues",
+					config: {
+						databaseKey: "issues",
+						primaryKeyProperty: "GitHub ID",
+						mode: "incremental",
+						schedule: { type: "interval", intervalMs: 3_600_000 },
+					},
+				},
+			],
+		});
+	});
+
 	it("builds a workflow bundle and manifest", async () => {
 		const { manifest, bundlePath, manifestPath } = await buildApp(example("workflow"));
 
 		expect(manifest).toEqual({
+			$schema: "notion:apps-manifest:v1",
 			sdkVersion: SDK_VERSION,
 			databases: [],
 			xldbs: [],
@@ -58,6 +97,76 @@ describe("buildApp", () => {
 		expect(JSON.parse(await fs.promises.readFile(manifestPath, "utf8"))).toEqual(manifest);
 	});
 
+	it("collects relation databases and a shared pacer once", async () => {
+		const { manifest } = await buildApp(fixture("shared-primary-key"));
+
+		expect(manifest.databases).toEqual([
+			{
+				key: "issues",
+				config: {
+					schema: {
+						properties: {
+							Name: { type: "title" },
+							"GitHub ID": { type: "text" },
+							Project: {
+								type: "relation",
+								config: { twoWay: false },
+								relatedDatabaseKey: "projects",
+							},
+						},
+					},
+				},
+			},
+			{
+				key: "projects",
+				config: {
+					schema: {
+						properties: {
+							Name: { type: "title" },
+							"Project ID": { type: "text" },
+						},
+					},
+				},
+			},
+		]);
+		expect(manifest.pacers).toEqual([
+			{
+				key: "issues-api",
+				config: { allowedRequests: 10, intervalMs: 1_000 },
+			},
+		]);
+		expect(manifest.capabilities).toEqual([
+			{
+				type: "sync",
+				key: "closed",
+				config: {
+					databaseKey: "issues",
+					primaryKeyProperty: "GitHub ID",
+				},
+			},
+			{
+				type: "sync",
+				key: "open",
+				config: {
+					databaseKey: "issues",
+					primaryKeyProperty: "GitHub ID",
+				},
+			},
+		]);
+	});
+
+	it("rejects syncs that disagree on a shared database primary key", async () => {
+		await expect(buildApp(fixture("conflicting-primary-key"))).rejects.toThrow(
+			/Syncs for database "issues" disagree on its primary key/,
+		);
+	});
+
+	it("rejects distinct database objects with the same key", async () => {
+		await expect(buildApp(fixture("duplicate-database-name"))).rejects.toThrow(
+			/Two distinct databases use the key "shared"/,
+		);
+	});
+
 	it("rejects a workflow file whose default export is not a workflow", async () => {
 		await expect(buildApp(fixture("wrong-tag"))).rejects.toThrow(
 			/notWorkflow\.ts.*default export is not a workflow/,

package/src/cli/build.ts

@@ -25,7 +25,7 @@ export async function buildApp(projectRoot: string): Promise<BuildResult> {
 	if (capabilities.length === 0) {
 		throw new Error(
 			`No capabilities found in ${projectRoot}. ` +
-				`Add a workflow file under src/workflows/<name>.ts that default-exports createWorkflow(...).`,
+				`Add a workflow under src/workflows/ or a sync under src/syncs/.`,
 		);
 	}
 

package/src/cli/codegen.test.ts

@@ -18,4 +18,19 @@ describe("generateEntry", () => {
 		expect(entry).toContain(`"onPageCreated": capability_0,`);
 		expect(entry).toContain("export async function run(");
 	});
+
+	it("registers syncs in their own capability group", () => {
+		const entry = generateEntry([
+			{
+				type: "sync",
+				tag: "sync",
+				key: "issues",
+				sourcePath: "src/syncs/issues.ts",
+			},
+		]);
+
+		expect(entry).toContain(`import capability_0 from "../src/syncs/issues.ts";`);
+		expect(entry).toContain(`"sync": {`);
+		expect(entry).toContain(`"issues": capability_0,`);
+	});
 });

package/src/cli/discover.test.ts

@@ -9,7 +9,7 @@ const EXAMPLES = fileURLToPath(new URL("../../examples/", import.meta.url));
 const FIXTURES = fileURLToPath(new URL("../../test/fixtures/", import.meta.url));
 
 describe("discoverCapabilities", () => {
-	it("discovers only workflow files", async () => {
+	it("discovers workflow files", async () => {
 		await expect(discoverCapabilities(path.join(EXAMPLES, "workflow"))).resolves.toEqual([
 			{
 				type: "workflow",
@@ -20,7 +20,18 @@ describe("discoverCapabilities", () => {
 		]);
 	});
 
-	it("returns nothing when no workflow directory exists", async () => {
+	it("discovers sync files", async () => {
+		await expect(discoverCapabilities(path.join(EXAMPLES, "sync"))).resolves.toEqual([
+			{
+				type: "sync",
+				tag: "sync",
+				key: "issues",
+				sourcePath: path.join("src", "syncs", "issues.ts"),
+			},
+		]);
+	});
+
+	it("returns nothing when no capability directory exists", async () => {
 		expect(await discoverCapabilities(path.join(FIXTURES, "empty"))).toEqual([]);
 	});
 });

package/src/cli/discover.ts

@@ -6,7 +6,7 @@ import type { CapabilityType } from "../manifest.js";
 /**
  * A capability type the build tool knows how to discover: which directory
  * under `src/` its files live in, and the `_tag` its default exports must
- * carry. This SDK intentionally registers workflows only.
+ * carry. This SDK registers workflows and syncs.
  */
 export type CapabilityTypeDefinition = {
 	type: CapabilityType;
@@ -16,6 +16,7 @@ export type CapabilityTypeDefinition = {
 
 export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
 	{ type: "workflow", directory: "workflows", tag: "workflow" },
+	{ type: "sync", directory: "syncs", tag: "sync" },
 ];
 
 /**
@@ -35,7 +36,7 @@ export type DiscoveredCapability = {
  * `src/<directory>/` for each registered capability type. Subdirectories are
  * not searched — they hold plain modules, not capabilities.
  *
- * Only workflow files directly under `src/workflows/` are discovered.
+ * Workflow and sync files are discovered from their matching directories.
  */
 export async function discoverCapabilities(projectRoot: string): Promise<DiscoveredCapability[]> {
 	const discovered: DiscoveredCapability[] = [];