@notionhq/apps 0.0.1

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@notionhq/apps",
+  "version": "0.0.1",
+  "description": "An SDK for building workflow apps for Notion",
+  "license": "MIT",
+  "bin": {
+    "notion-apps": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "docs/",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "default": "./dist/context.js"
+    },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "default": "./dist/error.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./triggers": {
+      "types": "./dist/triggers.generated.d.ts",
+      "default": "./dist/triggers.generated.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "default": "./dist/workflow.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "rolldown": "^1.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "concurrently": "^9.2.1",
+    "esbuild": "^0.27.3",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
+  },
+  "peerDependencies": {
+    "@notionhq/client": ">=2.2.15"
+  },
+  "engines": {
+    "node": ">=26.0.0",
+    "pnpm": ">=11.24.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && pnpm run build:types && pnpm run build:js",
+    "build:types": "tsc",
+    "build:js": "tsx scripts/build.ts",
+    "build:watch": "concurrently --group \"pnpm run build:watch:types\" \"pnpm run build:watch:js\"",
+    "build:watch:types": "tsc --watch",
+    "build:watch:js": "esbuild --watch --format=esm --outdir=dist --target=node26 --packages=external ./src/**.ts ./src/**/*.ts",
+    "generate": "tsx scripts/generate-triggers.ts",
+    "generate:check": "tsx scripts/generate-triggers.ts --check",
+    "sync:triggers": "tsx scripts/sync-triggers.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json"
+  }
+}

package/src/cli/build.test.ts

@@ -0,0 +1,73 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildApp } 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("buildApp", () => {
+	it("builds a workflow bundle and manifest", async () => {
+		const { manifest, bundlePath, manifestPath } = await buildApp(example("workflow"));
+
+		expect(manifest).toEqual({
+			sdkVersion: "0.0.1",
+			databases: [],
+			xldbs: [],
+			pacers: [],
+			capabilities: [
+				{
+					type: "workflow",
+					key: "onPageCreated",
+					config: {
+						name: "Log New Pages",
+						description: "Logs every page created in the workspace",
+						triggers: [{ type: "notion.page.created" }],
+					},
+				},
+			],
+		});
+		expect(path.basename(bundlePath)).toBe("worker.js");
+		expect(JSON.parse(await fs.promises.readFile(manifestPath, "utf8"))).toEqual(manifest);
+	});
+
+	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/,
+		);
+	});
+
+	it("rejects a workflow file with no default export", async () => {
+		await expect(buildApp(fixture("no-default-export"))).rejects.toThrow(
+			/"default" is not exported by .*nothing\.ts/,
+		);
+	});
+
+	it("rejects a project with no workflows", async () => {
+		await expect(buildApp(fixture("empty"))).rejects.toThrow(/No capabilities found/);
+	});
+});

package/src/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 { AppManifest } from "../manifest.js";
+import { generateEntry } from "./codegen.js";
+import { discoverCapabilities } from "./discover.js";
+import { extractManifest } from "./emit-manifest.js";
+
+export type BuildResult = {
+	manifest: AppManifest;
+	bundlePath: string;
+	manifestPath: string;
+};
+
+/**
+ * Build an app 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 buildApp(projectRoot: string): Promise<BuildResult> {
+	const capabilities = await discoverCapabilities(projectRoot);
+
+	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(...).`,
+		);
+	}
+
+	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 app'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/cli/codegen.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+import { generateEntry } from "./codegen.js";
+
+describe("generateEntry", () => {
+	it("statically imports and registers workflows by key", () => {
+		const entry = generateEntry([
+			{
+				type: "workflow",
+				tag: "workflow",
+				key: "onPageCreated",
+				sourcePath: "src/workflows/onPageCreated.ts",
+			},
+		]);
+
+		expect(entry).toContain(`import capability_0 from "../src/workflows/onPageCreated.ts";`);
+		expect(entry).toContain(`"workflow": {`);
+		expect(entry).toContain(`"onPageCreated": capability_0,`);
+		expect(entry).toContain("export async function run(");
+	});
+});

package/src/cli/codegen.ts

@@ -0,0 +1,51 @@
+import type { DiscoveredCapability } from "./discover.js";
+
+/**
+ * Generate the app entry module for a set of discovered capabilities.
+ *
+ * The module uses only static imports so that the bundler can bundle the
+ * whole app into a single file. It is written to `.notion/entry.ts` in
+ * the app 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-apps 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/cli/discover.test.ts

@@ -0,0 +1,26 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { discoverCapabilities } from "./discover.js";
+
+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 () => {
+		await expect(discoverCapabilities(path.join(EXAMPLES, "workflow"))).resolves.toEqual([
+			{
+				type: "workflow",
+				tag: "workflow",
+				key: "onPageCreated",
+				sourcePath: path.join("src", "workflows", "onPageCreated.ts"),
+			},
+		]);
+	});
+
+	it("returns nothing when no workflow directory exists", async () => {
+		expect(await discoverCapabilities(path.join(FIXTURES, "empty"))).toEqual([]);
+	});
+});

package/src/cli/discover.ts

@@ -0,0 +1,73 @@
+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. This SDK intentionally registers workflows only.
+ */
+export type CapabilityTypeDefinition = {
+	type: CapabilityType;
+	directory: string;
+	tag: string;
+};
+
+export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
+	{ 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 (`workflow/onPageCreated`).
+ */
+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 workflow files directly under `src/workflows/` are discovered.
+ */
+export async function discoverCapabilities(projectRoot: string): Promise<DiscoveredCapability[]> {
+	const discovered: DiscoveredCapability[] = [];
+
+	for (const definition of CAPABILITY_TYPES) {
+		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/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: "workflow",
+					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/workflows/foo.ts config"),
+		).toThrow("src/workflows/foo.ts config.outer.inner");
+	});
+});

package/src/cli/emit-manifest.ts

@@ -0,0 +1,190 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { Ajv } from "ajv";
+
+import type { AppManifest } from "../manifest.js";
+import type { DiscoveredCapability } from "./discover.js";
+
+const SDK_VERSION = (() => {
+	const require = createRequire(import.meta.url);
+	const packageJson: unknown = require("../../package.json");
+
+	if (
+		typeof packageJson !== "object" ||
+		packageJson === null ||
+		!("version" in packageJson) ||
+		typeof packageJson.version !== "string"
+	) {
+		throw new Error("Failed to read SDK version from package.json");
+	}
+
+	return packageJson.version;
+})();
+
+const MANIFEST_SCHEMA = {
+	type: "object",
+	properties: {
+		sdkVersion: { type: "string" },
+		databases: { type: "array", maxItems: 0 },
+		xldbs: { type: "array", maxItems: 0 },
+		pacers: { type: "array", maxItems: 0 },
+		capabilities: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					type: { type: "string", const: "workflow" },
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["type", "key", "config"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["sdkVersion", "databases", "xldbs", "pacers", "capabilities"],
+	additionalProperties: false,
+} as const;
+
+type TaggedWorkflow = {
+	_tag: "workflow";
+	config: Record<string, unknown>;
+};
+
+/** Extract the workflow-only app manifest from a built bundle. */
+export async function extractManifest(
+	bundlePath: string,
+	capabilities: readonly DiscoveredCapability[],
+): Promise<AppManifest> {
+	const bundle = await importBundle(bundlePath);
+	const capabilityRegistry = getCapabilityRegistry(bundle);
+
+	const capabilityEntries = capabilities.map((capability) => {
+		const value = capabilityRegistry.workflow?.[capability.key];
+		const workflow = asWorkflow(value);
+
+		if (!workflow) {
+			throw new Error(
+				`${capability.sourcePath}: default export is not a workflow — ` +
+					`files under src/workflows/ must default-export createWorkflow(...)`,
+			);
+		}
+
+		assertJsonSafe(workflow.config, `${capability.sourcePath} config`);
+		return { type: "workflow" as const, key: capability.key, config: workflow.config };
+	});
+
+	const manifest: unknown = JSON.parse(
+		JSON.stringify({
+			sdkVersion: SDK_VERSION,
+			databases: [],
+			xldbs: [],
+			pacers: [],
+			capabilities: capabilityEntries,
+		} satisfies AppManifest),
+	);
+
+	const ajv = new Ajv();
+	if (!ajv.validate(MANIFEST_SCHEMA, manifest)) {
+		throw new Error(`Generated manifest is invalid: ${ajv.errorsText(ajv.errors)}`);
+	}
+
+	return manifest as AppManifest;
+}
+
+let importNonce = 0;
+
+async function importBundle(bundlePath: string): Promise<unknown> {
+	try {
+		return await import(`${pathToFileURL(bundlePath).href}?import=${importNonce++}`);
+	} catch (error) {
+		throw new Error(
+			`Failed to import built app bundle. Workflow modules must be importable ` +
+				`without secrets or network access — check for top-level code that throws.\n` +
+				`Caused by: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function getCapabilityRegistry(
+	bundle: unknown,
+): Record<string, Record<string, unknown> | undefined> {
+	if (
+		typeof bundle !== "object" ||
+		bundle === null ||
+		!("capabilities" in bundle) ||
+		typeof bundle.capabilities !== "object" ||
+		bundle.capabilities === null
+	) {
+		throw new Error("Built app bundle does not export a capability registry");
+	}
+
+	return bundle.capabilities as Record<string, Record<string, unknown> | undefined>;
+}
+
+function asWorkflow(value: unknown): TaggedWorkflow | undefined {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		"_tag" in value &&
+		value._tag === "workflow" &&
+		"config" in value &&
+		typeof value.config === "object" &&
+		value.config !== null
+	) {
+		return value as TaggedWorkflow;
+	}
+
+	return undefined;
+}
+
+/**
+ * Throw if `value` contains anything `JSON.stringify` would silently drop or
+ * rewrite, so invalid workflow configuration fails during the build.
+ */
+export function assertJsonSafe(value: unknown, path: string): void {
+	const reject = (reason: string): never => {
+		throw new Error(`${path}: not JSON-serializable (${reason})`);
+	};
+
+	switch (typeof value) {
+		case "function":
+			reject("function");
+			break;
+		case "symbol":
+			reject("symbol");
+			break;
+		case "bigint":
+			reject("bigint");
+			break;
+		case "number":
+			if (!Number.isFinite(value)) reject(String(value));
+			return;
+		case "string":
+		case "boolean":
+		case "undefined":
+			return;
+	}
+
+	if (value === null) return;
+
+	if (Array.isArray(value)) {
+		value.forEach((element, index) => {
+			if (element === undefined) reject(`undefined at [${index}]`);
+			assertJsonSafe(element, `${path}[${index}]`);
+		});
+		return;
+	}
+
+	const object = value as { constructor?: { name?: string } };
+	const prototype = Object.getPrototypeOf(object);
+	if (prototype !== null && prototype !== Object.prototype) {
+		reject(object.constructor?.name ?? "non-plain object");
+	}
+
+	for (const [key, property] of Object.entries(object as Record<string, unknown>)) {
+		if (property === undefined) continue;
+		assertJsonSafe(property, `${path}.${key}`);
+	}
+}

package/src/cli/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import * as path from "node:path";
+
+import { buildApp } from "./build.js";
+
+const USAGE = `Usage: notion-apps <command>
+
+Commands:
+  build    Build the app in the current directory
+`;
+
+async function main(): Promise<void> {
+	const command = process.argv[2];
+
+	switch (command) {
+		case "build": {
+			const projectRoot = process.cwd();
+			const { manifest, bundlePath, manifestPath } = await buildApp(projectRoot);
+			const count = manifest.capabilities.length;
+			console.log(
+				`Built ${path.relative(projectRoot, bundlePath)} and ` +
+					`${path.relative(projectRoot, manifestPath)} ` +
+					`(${count} ${count === 1 ? "capability" : "capabilities"})`,
+			);
+			break;
+		}
+		case undefined:
+		case "help":
+		case "--help":
+			console.log(USAGE);
+			break;
+		default:
+			console.error(`Unknown command: ${command}\n\n${USAGE}`);
+			process.exitCode = 1;
+	}
+}
+
+main().catch((error: unknown) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});