@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/builder.ts

@@ -0,0 +1,338 @@
+import type { NoticonName } from "./icon-names.js";
+import type {
+	Cover,
+	DateValue,
+	Icon,
+	NoticonColor,
+	PeopleValue,
+	PlaceValue,
+	RelationReference,
+	TextValue,
+} from "./types.js";
+
+/**
+ * Validates a date string is in YYYY-MM-DD format and represents a valid date.
+ */
+function validateDateString(dateString: string): void {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
+		throw new Error(`Invalid date format: ${dateString}. Expected YYYY-MM-DD format.`);
+	}
+
+	const date = new Date(dateString);
+	if (Number.isNaN(date.getTime())) {
+		throw new Error(`Invalid date: ${dateString}`);
+	}
+}
+
+/**
+ * Internal helper to create a date mention token from a DateValue object.
+ */
+function createDateToken(dateValue: DateValue): TextValue {
+	return [["‣", [["d", dateValue]]]];
+}
+
+/**
+ * Parses an ISO 8601 datetime string into date and time components.
+ * Accepts formats like "2024-01-15T10:30", "2024-01-15T10:30:00Z",
+ * "2024-01-15T10:30:00.000+05:00", etc.
+ */
+function parseISODateTime(isoString: string): { date: string; time: string } {
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(isoString)) {
+		throw new Error(
+			`Invalid ISO 8601 datetime: ${isoString}. Expected format like 2024-01-15T10:30 or 2024-01-15T10:30:00Z`,
+		);
+	}
+
+	const date = isoString.slice(0, 10);
+	const time = isoString.slice(11, 16);
+
+	if (Number.isNaN(new Date(isoString).getTime())) {
+		throw new Error(`Invalid datetime: ${isoString}`);
+	}
+
+	return { date, time };
+}
+
+/**
+ * Builders for property values in sync changes.
+ *
+ * @example
+ * ```ts
+ * import { Builder } from "@notionhq/workers/alpha/builder";
+ *
+ * const change = {
+ *   type: "upsert",
+ *   key: "task-1",
+ *   properties: {
+ *     "Task Name": Builder.title("Write docs"),
+ *     Status: Builder.select("Open"),
+ *     Due: Builder.date("2026-08-01"),
+ *     Assignees: Builder.people("alice@example.com"),
+ *   },
+ * };
+ * ```
+ */
+export const Builder = {
+	/**
+	 * Creates a rich text value.
+	 */
+	richText(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates a URL value.
+	 */
+	url(url: string): TextValue {
+		return [[url]];
+	},
+
+	/**
+	 * Creates a title value.
+	 */
+	title(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates a text value.
+	 */
+	text(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates an email value.
+	 */
+	email(email: string): TextValue {
+		return [[email]];
+	},
+
+	/**
+	 * Creates a phone number value.
+	 */
+	phoneNumber(phone: string): TextValue {
+		return [[phone]];
+	},
+
+	/**
+	 * Creates a checkbox value.
+	 */
+	checkbox(checked: boolean): TextValue {
+		return checked ? [["Yes"]] : [["No"]];
+	},
+
+	/**
+	 * Creates a file URL value.
+	 * @param fileUrl - The URL of the file
+	 * @param fileName - Optional display name for the file (defaults to URL)
+	 */
+	file(fileUrl: string, fileName?: string): TextValue {
+		return [[fileName ?? fileUrl, [["a", fileUrl]]]];
+	},
+
+	/**
+	 * Creates a number value.
+	 */
+	number(value: number): TextValue {
+		if (Number.isNaN(value)) {
+			return [];
+		}
+		return [[value.toString()]];
+	},
+
+	/**
+	 * Creates a date value from a date string (YYYY-MM-DD).
+	 */
+	date(dateString: string): TextValue {
+		validateDateString(dateString);
+
+		return createDateToken({
+			type: "date",
+			start_date: dateString,
+		});
+	},
+
+	/**
+	 * Creates a datetime value from an ISO 8601 datetime string.
+	 * @param isoString - An ISO 8601 datetime string (e.g., "2024-01-15T10:30", "2024-01-15T10:30:00Z")
+	 * @param timeZone - Optional IANA timezone name (e.g., "America/New_York")
+	 */
+	dateTime(isoString: string, timeZone?: string): TextValue {
+		const { date, time } = parseISODateTime(isoString);
+
+		const dateValue: DateValue = {
+			type: "datetime",
+			start_date: date,
+			start_time: time,
+		};
+
+		if (timeZone) {
+			dateValue.time_zone = timeZone;
+		}
+
+		return createDateToken(dateValue);
+	},
+
+	/**
+	 * Creates a date range value from date strings.
+	 */
+	dateRange(startDate: string, endDate: string): TextValue {
+		validateDateString(startDate);
+		validateDateString(endDate);
+
+		return createDateToken({
+			type: "daterange",
+			start_date: startDate,
+			end_date: endDate,
+		});
+	},
+
+	/**
+	 * Creates a datetime range value from ISO 8601 datetime strings.
+	 * @param startDateTime - An ISO 8601 datetime string for the range start
+	 * @param endDateTime - An ISO 8601 datetime string for the range end
+	 * @param timeZone - Optional IANA timezone name (e.g., "America/New_York")
+	 */
+	dateTimeRange(startDateTime: string, endDateTime: string, timeZone?: string): TextValue {
+		const start = parseISODateTime(startDateTime);
+		const end = parseISODateTime(endDateTime);
+
+		const dateValue: DateValue = {
+			type: "datetimerange",
+			start_date: start.date,
+			start_time: start.time,
+			end_date: end.date,
+			end_time: end.time,
+		};
+
+		if (timeZone) {
+			dateValue.time_zone = timeZone;
+		}
+
+		return createDateToken(dateValue);
+	},
+
+	/**
+	 * Creates a link with custom display text.
+	 * @param displayText - The text to display
+	 * @param url - The URL to link to
+	 */
+	link(displayText: string, url: string): TextValue {
+		return [[displayText, [["a", url]]]];
+	},
+
+	/**
+	 * Creates a select value from a single option.
+	 */
+	select(value: string): TextValue {
+		return [[value]];
+	},
+
+	/**
+	 * Creates a multi-select value from multiple options.
+	 * @param values - Array of option names to select
+	 */
+	multiSelect(...values: string[]): TextValue {
+		if (values.length === 0) {
+			return [];
+		}
+		return [[values.join(",")]];
+	},
+
+	/**
+	 * Creates a status value from a status option name.
+	 */
+	status(value: string): TextValue {
+		return [[value]];
+	},
+
+	/**
+	 * Creates a people value from email addresses.
+	 * @param emails - Array of email addresses for people to include
+	 */
+	people(...emails: string[]): PeopleValue {
+		return emails.map((email) => ({ email }));
+	},
+
+	/**
+	 * Creates a place value for a geographic location.
+	 * @param value - The place value with lat/lon coordinates and optional name/address
+	 */
+	place(value: PlaceValue): PlaceValue {
+		if (typeof value.lat !== "number" || typeof value.lon !== "number") {
+			throw new Error("Place value must have numeric lat and lon coordinates");
+		}
+		return value;
+	},
+
+	/**
+	 * Creates a relation reference from a primary key of a related record.
+	 * Use an array of relation references as the property value.
+	 *
+	 * @param primaryKey - The primary key of the related record
+	 * @example
+	 * ```typescript
+	 * // Single relation
+	 * { Project: [Builder.relation("project-123")] }
+	 *
+	 * // Multiple relations
+	 * { Projects: [Builder.relation("project-123"), Builder.relation("project-456")] }
+	 * ```
+	 */
+	relation(primaryKey: string): RelationReference {
+		return { type: "primaryKey", value: primaryKey };
+	},
+
+	/**
+	 * Creates an emoji icon.
+	 * @param emoji - An emoji string (e.g., "🎯", "✨", "🚀")
+	 */
+	emojiIcon(emoji: string): Icon {
+		return {
+			type: "emoji",
+			value: emoji,
+		};
+	},
+
+	/**
+	 * Creates a Notion icon with a specific color.
+	 * @param icon - The name of the Notion icon (e.g., "checkmark", "pizza", "rocket")
+	 * @param color - The color variant (defaults to "gray")
+	 */
+	notionIcon(icon: NoticonName, color: NoticonColor = "gray"): Icon {
+		return {
+			type: "notion",
+			icon,
+			color,
+		};
+	},
+
+	/**
+	 * Creates an image icon from an external URL.
+	 * @param url - The URL of the image (e.g., "https://example.com/icon.png")
+	 */
+	imageIcon(url: string): Icon {
+		return {
+			type: "image",
+			url,
+		};
+	},
+
+	/**
+	 * Creates an image cover from an external URL.
+	 * @param url - The URL of the image (e.g., "https://example.com/cover.png")
+	 * @param position - Vertical image position, from 0 (top) to 1 (bottom). Defaults to 0.5.
+	 */
+	imageCover(url: string, position = 0.5): Cover {
+		if (!Number.isFinite(position) || position < 0 || position > 1) {
+			throw new Error(`Invalid cover position: ${position}. Expected a number between 0 and 1.`);
+		}
+
+		return {
+			type: "image",
+			url,
+			position,
+		};
+	},
+};

package/src/alpha/cli/build.test.ts

@@ -0,0 +1,240 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildWorker } from "./build.js";
+
+const FIXTURES = fileURLToPath(new URL("../../../test/fixtures/", import.meta.url));
+const EXAMPLES = fileURLToPath(new URL("../../../examples/", import.meta.url));
+
+const builtDirectories: string[] = [];
+
+function fixture(name: string): string {
+	const root = path.join(FIXTURES, name);
+	builtDirectories.push(root);
+	return root;
+}
+
+function example(name: string): string {
+	const root = path.join(EXAMPLES, name);
+	builtDirectories.push(root);
+	return root;
+}
+
+afterEach(async () => {
+	for (const root of builtDirectories.splice(0)) {
+		for (const artifact of [".notion", "dist"]) {
+			await fs.promises.rm(path.join(root, artifact), { recursive: true, force: true });
+		}
+	}
+});
+
+describe("buildWorker", () => {
+	it("builds a bundle and manifest from capability files", async () => {
+		const { manifest, bundlePath, manifestPath } = await buildWorker(fixture("basic"));
+
+		expect(manifest.capabilities).toEqual([
+			{
+				type: "sync",
+				key: "static",
+				config: {
+					databaseKey: "tasks",
+					mode: "replace",
+					schedule: { type: "interval", intervalMs: 24 * 60 * 60 * 1000 },
+				},
+			},
+		]);
+
+		// The sync's inline database is keyed by its own name.
+		expect(manifest.databases).toEqual([
+			{
+				key: "tasks",
+				config: {
+					type: "managed",
+					primaryKey: "ID",
+					schema: { properties: { ID: { type: "text" } } },
+				},
+			},
+		]);
+
+		const written: unknown = JSON.parse(await fs.promises.readFile(manifestPath, "utf8"));
+		expect(written).toEqual(manifest);
+
+		// The bundle is runnable: run() dispatches to the sync's handler, which
+		// produces the v1-shaped run result.
+		const bundle = (await import(pathToFileURL(bundlePath).href)) as {
+			run: (
+				type: string,
+				key: string,
+				context?: unknown,
+				options?: { concreteOutput?: true },
+			) => Promise<unknown>;
+		};
+		await expect(
+			bundle.run("sync", "static", undefined, { concreteOutput: true }),
+		).resolves.toEqual({
+			changes: [
+				{ type: "upsert", key: "1", properties: { ID: [["1"]] }, targetDatabaseKey: "tasks" },
+			],
+			hasMore: false,
+			nextUserContext: undefined,
+			nextPacerStates: {},
+		});
+		await expect(bundle.run("sync", "missing")).rejects.toThrow(
+			'Capability "sync/missing" not found',
+		);
+	});
+
+	it("collects databases by reachability and resolves relations to names", async () => {
+		const { manifest } = await buildWorker(fixture("relations"));
+
+		// `projects` is reachable only through `tasks`' relation property, and
+		// both live in a plain lib/ module — no dedicated database directory.
+		expect(manifest.databases).toEqual([
+			{
+				key: "tasks",
+				config: {
+					type: "managed",
+					initialTitle: "Tasks",
+					primaryKey: "ID",
+					schema: {
+						properties: {
+							ID: { type: "text" },
+							Project: {
+								type: "relation",
+								relatedDatabaseKey: "projects",
+								config: { twoWay: false },
+							},
+						},
+					},
+				},
+			},
+			{
+				key: "projects",
+				config: {
+					type: "managed",
+					primaryKey: "ID",
+					schema: { properties: { ID: { type: "text" } } },
+				},
+			},
+		]);
+
+		expect(manifest.capabilities).toEqual([
+			{
+				type: "sync",
+				key: "tasks",
+				config: { databaseKey: "tasks", mode: undefined, schedule: undefined },
+			},
+		]);
+	});
+
+	it("deduplicates a database and pacer shared by two syncs", async () => {
+		const { manifest } = await buildWorker(example("shared-resources"));
+
+		// Both syncs import the same instances, so each shared resource lands
+		// in the manifest exactly once — not once per sync. `projects` is
+		// reachable only through the issues database's relation property.
+		expect(manifest.databases.map((database) => database.key)).toEqual(["issues", "projects"]);
+
+		const issuesConfig = manifest.databases[0]?.config as {
+			schema: { properties: Record<string, unknown> };
+		};
+		expect(issuesConfig.schema.properties.Project).toEqual({
+			type: "relation",
+			relatedDatabaseKey: "projects",
+			config: { twoWay: false },
+		});
+
+		expect(manifest.pacers).toHaveLength(1);
+		expect(manifest.pacers[0]).toEqual({
+			key: "jira",
+			config: { allowedRequests: 10, intervalMs: 1000 },
+		});
+
+		const syncConfigs = manifest.capabilities
+			.filter((capability) => capability.type === "sync")
+			.map((capability) => ({
+				key: capability.key,
+				databaseKey: (capability.config as { databaseKey: string }).databaseKey,
+			}));
+		expect(syncConfigs).toEqual([
+			{ key: "closedIssues", databaseKey: "issues" },
+			{ key: "openIssues", databaseKey: "issues" },
+		]);
+	});
+
+	it("re-collects pacers when rebuilding an unchanged project in one process", async () => {
+		// Pacer collection relies on the bundle's top-level side effects
+		// re-running on every import; a module-cache hit (identical bundle,
+		// same URL) would silently drop all pacers on the second build.
+		await buildWorker(example("shared-resources"));
+		const { manifest } = await buildWorker(example("shared-resources"));
+
+		expect(manifest.pacers).toHaveLength(1);
+	});
+
+	it("discovers tools with resolved schemas in the manifest", async () => {
+		const { manifest } = await buildWorker(example("shared-resources"));
+
+		const tools = manifest.capabilities.filter((capability) => capability.type === "tool");
+		expect(tools.map((tool) => tool.key)).toEqual(["createIssue", "listIssues"]);
+
+		expect(tools[0]?.config).toMatchObject({
+			title: "Create Issue",
+			schema: {
+				type: "object",
+				required: ["title", "project"],
+				additionalProperties: false,
+			},
+			outputSchema: {
+				type: "object",
+				required: ["key"],
+			},
+		});
+		expect(tools[1]?.config).toMatchObject({
+			title: "List Issues",
+			hints: { readOnlyHint: true },
+		});
+	});
+
+	it("discovers workflows with their triggers in the manifest", async () => {
+		const { manifest } = await buildWorker(example("sync"));
+
+		const workflows = manifest.capabilities.filter((capability) => capability.type === "workflow");
+		expect(workflows).toEqual([
+			{
+				type: "workflow",
+				key: "onPageCreated",
+				config: {
+					title: "Log New Pages",
+					description: "Logs every page created in the workspace",
+					triggers: [{ type: "notion.page.created" }],
+				},
+			},
+		]);
+	});
+
+	it("fails when two distinct databases share a name", async () => {
+		await expect(buildWorker(fixture("duplicate-name"))).rejects.toThrow(
+			/Two distinct databases are named "shared"/,
+		);
+	});
+
+	it("fails when a capability file's default export has the wrong tag", async () => {
+		await expect(buildWorker(fixture("wrong-tag"))).rejects.toThrow(
+			/tool\.ts.*default export is not a sync/,
+		);
+	});
+
+	it("fails when a capability file has no default export", async () => {
+		await expect(buildWorker(fixture("no-default-export"))).rejects.toThrow(
+			/"default" is not exported by .*nothing\.ts/,
+		);
+	});
+
+	it("fails when the project has no capabilities", async () => {
+		await expect(buildWorker(fixture("empty"))).rejects.toThrow(/No capabilities found/);
+	});
+});

package/src/alpha/cli/build.ts

@@ -0,0 +1,57 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { rolldown } from "rolldown";
+
+import type { WorkerManifest } from "../manifest.js";
+import { generateEntry } from "./codegen.js";
+import { discoverCapabilities } from "./discover.js";
+import { extractManifest } from "./emit-manifest.js";
+
+export type BuildResult = {
+	manifest: WorkerManifest;
+	bundlePath: string;
+	manifestPath: string;
+};
+
+/**
+ * Build a worker project: discover capability files by convention, generate
+ * the entry module, bundle it into a single `dist/worker.js`, and emit
+ * `dist/manifest.json` describing every capability.
+ */
+export async function buildWorker(projectRoot: string): Promise<BuildResult> {
+	const capabilities = await discoverCapabilities(projectRoot);
+
+	if (capabilities.length === 0) {
+		throw new Error(
+			`No capabilities found in ${projectRoot}. ` +
+				`Add capability files by convention, e.g. src/syncs/<name>.ts default-exporting createSync(...).`,
+		);
+	}
+
+	const entryPath = path.join(projectRoot, ".notion", "entry.ts");
+	await fs.promises.mkdir(path.dirname(entryPath), { recursive: true });
+	await fs.promises.writeFile(entryPath, generateEntry(capabilities));
+
+	const bundlePath = path.join(projectRoot, "dist", "worker.js");
+	// Bundle only the worker's own code. Bare imports (npm packages) stay
+	// external and resolve from node_modules at runtime, so packages behave
+	// normally — including native addons, which cannot be inlined.
+	const bundle = await rolldown({
+		input: entryPath,
+		platform: "node",
+		external: (id) => !id.startsWith(".") && !path.isAbsolute(id),
+	});
+	try {
+		await bundle.write({ format: "esm", file: bundlePath });
+	} finally {
+		await bundle.close();
+	}
+
+	const manifest = await extractManifest(bundlePath, capabilities);
+
+	const manifestPath = path.join(projectRoot, "dist", "manifest.json");
+	await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
+
+	return { manifest, bundlePath, manifestPath };
+}

package/src/alpha/cli/codegen.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+import { generateEntry } from "./codegen.js";
+
+describe("generateEntry", () => {
+	it("statically imports each capability and registers it by type and key", () => {
+		const entry = generateEntry([
+			{ type: "sync", tag: "sync", key: "static", sourcePath: "src/syncs/static.ts" },
+			{ type: "sync", tag: "sync", key: "my-sync", sourcePath: "src/syncs/my-sync.ts" },
+		]);
+
+		expect(entry).toContain(`import capability_0 from "../src/syncs/static.ts";`);
+		expect(entry).toContain(`import capability_1 from "../src/syncs/my-sync.ts";`);
+		expect(entry).toContain(`"static": capability_0,`);
+		expect(entry).toContain(`"my-sync": capability_1,`);
+		expect(entry).toContain("export async function run(");
+	});
+
+	it("quotes capability type keys so non-identifier types are valid JavaScript", () => {
+		const entry = generateEntry([
+			{
+				type: "ai-connector",
+				tag: "ai-connector",
+				key: "my-connector",
+				sourcePath: "src/ai-connectors/my-connector.ts",
+			},
+		]);
+
+		expect(entry).toContain(`"ai-connector": {`);
+	});
+});