@notionhq/workers 0.4.0 → 0.6.0

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": {`);
+	});
+});

package/src/alpha/cli/codegen.ts

@@ -0,0 +1,51 @@
+import type { DiscoveredCapability } from "./discover.js";
+
+/**
+ * Generate the worker entry module for a set of discovered capabilities.
+ *
+ * The module uses only static imports so that the bundler can bundle the
+ * whole worker into a single file. It is written to `.notion/entry.ts` in
+ * the worker project, so imports are relative to that location.
+ */
+export function generateEntry(capabilities: readonly DiscoveredCapability[]): string {
+	const imports: string[] = [];
+	const registryEntries = new Map<string, string[]>();
+
+	capabilities.forEach((capability, index) => {
+		const binding = `capability_${index}`;
+		imports.push(`import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`);
+
+		const entries = registryEntries.get(capability.type) ?? [];
+		entries.push(`\t\t${JSON.stringify(capability.key)}: ${binding},`);
+		registryEntries.set(capability.type, entries);
+	});
+
+	const registry = Array.from(registryEntries.entries())
+		.map(([type, entries]) => `\t${JSON.stringify(type)}: {\n${entries.join("\n")}\n\t},`)
+		.join("\n");
+
+	return `// Generated by \`notion-workers build\`. Do not edit.
+${imports.join("\n")}
+
+type Handler = (context?: unknown, options?: { concreteOutput?: true }) => Promise<unknown>;
+
+export const capabilities: Record<string, Record<string, { handler: Handler }>> = {
+${registry}
+};
+
+export async function run(
+	type: string,
+	key: string,
+	context?: unknown,
+	options?: { concreteOutput?: true },
+): Promise<unknown> {
+	const capability = capabilities[type]?.[key];
+
+	if (!capability) {
+		throw new Error(\`Capability "\${type}/\${key}" not found\`);
+	}
+
+	return capability.handler(context, options);
+}
+`;
+}

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

@@ -0,0 +1,43 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { discoverCapabilities } from "./discover.js";
+
+const FIXTURES = fileURLToPath(new URL("../../../test/fixtures/", import.meta.url));
+
+describe("discoverCapabilities", () => {
+	it("finds top-level files in a registered capability type's directory", async () => {
+		const capabilities = await discoverCapabilities(path.join(FIXTURES, "custom-type"), [
+			{ type: "greeting", directory: "greetings", tag: "greeting" },
+		]);
+
+		// Only top-level .ts files count; subdirectories are plain modules.
+		expect(capabilities).toEqual([
+			{
+				type: "greeting",
+				tag: "greeting",
+				key: "hello",
+				sourcePath: path.join("src", "greetings", "hello.ts"),
+			},
+		]);
+	});
+
+	it("finds capability files by convention", async () => {
+		const capabilities = await discoverCapabilities(path.join(FIXTURES, "basic"));
+
+		expect(capabilities).toEqual([
+			{
+				type: "sync",
+				tag: "sync",
+				key: "static",
+				sourcePath: path.join("src", "syncs", "static.ts"),
+			},
+		]);
+	});
+
+	it("returns nothing when no capability directories exist", async () => {
+		expect(await discoverCapabilities(path.join(FIXTURES, "empty"))).toEqual([]);
+	});
+});

package/src/alpha/cli/discover.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+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. Adding a new capability type to the SDK means adding an entry here
+ * (plus its factory function).
+ */
+export type CapabilityTypeDefinition = {
+	type: CapabilityType;
+	directory: string;
+	tag: string;
+};
+
+export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
+	{ type: "sync", directory: "syncs", tag: "sync" },
+	{ type: "tool", directory: "tools", tag: "tool" },
+	{ type: "workflow", directory: "workflows", tag: "workflow" },
+];
+
+/**
+ * A capability file found during discovery. The key is the file's basename;
+ * combined with the type it forms the capability's identity (`sync/static`).
+ */
+export type DiscoveredCapability = {
+	type: CapabilityType;
+	tag: string;
+	key: string;
+	/** Path to the source file, relative to the project root. */
+	sourcePath: string;
+};
+
+/**
+ * Discover capability files by convention: every `.ts` file directly under
+ * `src/<directory>/` for each registered capability type. Subdirectories are
+ * not searched — they hold plain modules, not capabilities.
+ *
+ * Only capabilities are discovered by file location. Resources (databases,
+ * pacers) live anywhere and are discovered by walking capability configs at
+ * manifest time.
+ */
+export async function discoverCapabilities(
+	projectRoot: string,
+	capabilityTypes: readonly CapabilityTypeDefinition[] = CAPABILITY_TYPES,
+): Promise<DiscoveredCapability[]> {
+	const discovered: DiscoveredCapability[] = [];
+
+	for (const definition of capabilityTypes) {
+		const directory = path.join(projectRoot, "src", definition.directory);
+
+		let entries: fs.Dirent[];
+		try {
+			entries = await fs.promises.readdir(directory, { withFileTypes: true });
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+				continue;
+			}
+			throw error;
+		}
+
+		entries.sort((a, b) => a.name.localeCompare(b.name));
+
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".ts") || entry.name.endsWith(".d.ts")) {
+				continue;
+			}
+
+			discovered.push({
+				type: definition.type,
+				tag: definition.tag,
+				key: entry.name.slice(0, -".ts".length),
+				sourcePath: path.join("src", definition.directory, entry.name),
+			});
+		}
+	}
+
+	return discovered;
+}

package/src/alpha/cli/emit-manifest.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { assertJsonSafe } from "./emit-manifest.js";
+
+describe("assertJsonSafe", () => {
+	it("accepts plain JSON values, including nested objects and arrays", () => {
+		expect(() =>
+			assertJsonSafe(
+				{
+					name: "sync",
+					count: 3,
+					enabled: true,
+					missing: null,
+					tags: ["a", "b"],
+					nested: { list: [1, 2, { deep: "value" }] },
+				},
+				"config",
+			),
+		).not.toThrow();
+	});
+
+	it("omits undefined-valued object properties without throwing", () => {
+		expect(() => assertJsonSafe({ a: undefined, b: 1 }, "config")).not.toThrow();
+	});
+
+	it.each([
+		["function", { a: () => {} }],
+		["symbol", { a: Symbol("x") }],
+		["bigint", { a: 1n }],
+		["NaN", { a: Number.NaN }],
+		["Infinity", { a: Number.POSITIVE_INFINITY }],
+		["Map", { a: new Map() }],
+		["Set", { a: new Set() }],
+		["Date", { a: new Date(0) }],
+		["undefined array element", { a: [undefined] }],
+	])("throws for non-serializable %s", (_label, value) => {
+		expect(() => assertJsonSafe(value, "config")).toThrow(/not JSON-serializable/);
+	});
+
+	it("includes the path to the offending value in the error", () => {
+		expect(() => assertJsonSafe({ outer: { inner: () => {} } }, "src/syncs/foo.ts config")).toThrow(
+			"src/syncs/foo.ts config.outer.inner",
+		);
+	});
+});