@notionhq/workers 0.5.0 → 0.6.0

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

@@ -0,0 +1,409 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { Ajv } from "ajv";
+
+import type { DatabaseManifestEntry, PacerManifestEntry, WorkerManifest } from "../manifest.js";
+import { clearRegisteredPacers, registeredPacers } from "../pacer.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",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
+		pacers: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
+		capabilities: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					type: { type: "string" },
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["type", "key", "config"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["sdkVersion", "databases", "pacers", "capabilities"],
+	additionalProperties: false,
+} as const;
+
+type TaggedObject = { _tag: string; config: Record<string, unknown> };
+
+type DatabaseObject = TaggedObject & { name: string };
+
+/**
+ * Collects the databases reachable from capability configs, deduplicating
+ * by object identity within the build and by `name` across deploys.
+ */
+class DatabaseCollector {
+	/** Database object → name, for identity-based dedup. */
+	#names = new Map<unknown, string>();
+	/** Name → database object, for detecting distinct objects sharing a name. */
+	#byName = new Map<string, DatabaseObject>();
+	/** Names in first-seen order, for deterministic manifest output. */
+	#order: string[] = [];
+
+	/**
+	 * Register a database and, transitively, every database its schema's
+	 * relation properties reference. Returns the database's name.
+	 */
+	collect(value: unknown, referencedFrom: string): string {
+		const known = this.#names.get(value);
+		if (known !== undefined) {
+			return known;
+		}
+
+		const database = asDatabase(value);
+		if (!database) {
+			throw new Error(`${referencedFrom}: expected a database created with createDatabase(...)`);
+		}
+
+		const existing = this.#byName.get(database.name);
+		if (existing && existing !== value) {
+			throw new Error(
+				`Two distinct databases are named "${database.name}" (found via ${referencedFrom}). ` +
+					`A name identifies one database — share a single createDatabase(...) instance ` +
+					`via import instead of declaring it twice`,
+			);
+		}
+
+		this.#names.set(value, database.name);
+		this.#byName.set(database.name, database);
+		this.#order.push(database.name);
+
+		validatePrimaryKey(database);
+
+		// Relations pull their target databases into the manifest even when
+		// no sync writes to them directly.
+		for (const [propertyName, property] of schemaProperties(database)) {
+			if (isRelationProperty(property)) {
+				this.collect(
+					property.database,
+					`relation property "${propertyName}" of database "${database.name}"`,
+				);
+			}
+		}
+
+		return database.name;
+	}
+
+	/** Manifest entries with relation references resolved to names. */
+	entries(): DatabaseManifestEntry[] {
+		return this.#order.map((name) => {
+			const database = this.#byName.get(name)!;
+			const resolvedProperties: Record<string, unknown> = {};
+
+			for (const [propertyName, property] of schemaProperties(database)) {
+				if (isRelationProperty(property)) {
+					const { database: target, ...rest } = property;
+					resolvedProperties[propertyName] = {
+						...rest,
+						relatedDatabaseKey: this.#names.get(target)!,
+					};
+				} else {
+					resolvedProperties[propertyName] = property;
+				}
+			}
+
+			const schema = database.config.schema as Record<string, unknown>;
+			return {
+				key: name,
+				config: { ...database.config, schema: { ...schema, properties: resolvedProperties } },
+			};
+		});
+	}
+}
+
+/**
+ * Extract the worker manifest from a built bundle.
+ *
+ * This is the one place the build executes worker code: the bundle is
+ * imported once (running module top-level code only — handlers are never
+ * invoked), each discovered capability's default export is validated
+ * against the tag its directory requires, and the handler-free configs are
+ * assembled into the manifest.
+ *
+ * Resources are not discovered from the filesystem. Databases are collected
+ * by walking capability configs — a sync's `database`, and transitively any
+ * database referenced by a schema's `relation` properties. Pacers register
+ * themselves when created, so importing the bundle populates the pacer
+ * registry as a side effect. Within a build, resources deduplicate by
+ * object identity; across deploys their `name` is the stable key. Two
+ * distinct resource objects sharing a name fail the build.
+ */
+export async function extractManifest(
+	bundlePath: string,
+	capabilities: readonly DiscoveredCapability[],
+): Promise<WorkerManifest> {
+	// Importing the bundle registers every pacer created at module top level;
+	// clear first so repeated builds in one process don't see stale entries.
+	clearRegisteredPacers();
+	const bundle = await importBundle(bundlePath);
+	const pacerEntries: PacerManifestEntry[] = registeredPacers().map((pacer) => ({
+		key: pacer.name,
+		config: pacer.config,
+	}));
+
+	const capabilityRegistry = getCapabilityRegistry(bundle);
+	const databaseCollector = new DatabaseCollector();
+
+	const capabilityEntries = capabilities.map((capability) => {
+		const value = capabilityRegistry[capability.type]?.[capability.key];
+		const tagged = asTagged(value);
+
+		if (!tagged) {
+			throw new Error(`${capability.sourcePath}: default export is not a capability`);
+		}
+
+		if (tagged._tag !== capability.tag) {
+			throw new Error(
+				`${capability.sourcePath}: default export is not a ${capability.type} — ` +
+					`files under this directory must default-export create${capitalize(capability.type)}(...)`,
+			);
+		}
+
+		const config = { ...tagged.config };
+
+		if (capability.type === "sync") {
+			config.databaseKey = databaseCollector.collect(config.database, capability.sourcePath);
+			config.database = undefined;
+		}
+
+		// Verify after the sync transform above swaps the non-plain database
+		// object out for its string key.
+		assertJsonSafe(config, `${capability.sourcePath} config`);
+
+		return { type: capability.type, key: capability.key, config };
+	});
+
+	const databaseEntries = databaseCollector.entries();
+	for (const entry of databaseEntries) {
+		assertJsonSafe(entry.config, `database "${entry.key}" config`);
+	}
+	for (const entry of pacerEntries) {
+		assertJsonSafe(entry.config, `pacer "${entry.key}" config`);
+	}
+
+	// Every config was verified JSON-safe above, so this round-trip is lossless;
+	// it normalizes the already-validated values into plain JSON before the
+	// manifest-structure check below.
+	const manifest: unknown = JSON.parse(
+		JSON.stringify({
+			sdkVersion: SDK_VERSION,
+			databases: databaseEntries,
+			pacers: pacerEntries,
+			capabilities: capabilityEntries,
+		} satisfies WorkerManifest),
+	);
+
+	const ajv = new Ajv();
+	if (!ajv.validate(MANIFEST_SCHEMA, manifest)) {
+		throw new Error(`Generated manifest is invalid: ${ajv.errorsText(ajv.errors)}`);
+	}
+
+	return manifest as WorkerManifest;
+}
+
+function schemaProperties(database: DatabaseObject): [string, unknown][] {
+	const schema = database.config.schema;
+	if (
+		typeof schema !== "object" ||
+		schema === null ||
+		!("properties" in schema) ||
+		typeof schema.properties !== "object" ||
+		schema.properties === null
+	) {
+		throw new Error(`Database "${database.name}" has no schema.properties`);
+	}
+
+	return Object.entries(schema.properties);
+}
+
+function validatePrimaryKey(database: DatabaseObject): void {
+	const propertyNames = schemaProperties(database).map(([name]) => name);
+	const primaryKey = database.config.primaryKey;
+
+	if (typeof primaryKey !== "string" || !propertyNames.includes(primaryKey)) {
+		throw new Error(
+			`Database "${database.name}": primaryKey "${String(primaryKey)}" is not a property ` +
+				`in the schema`,
+		);
+	}
+}
+
+function isRelationProperty(property: unknown): property is { database: unknown } {
+	return (
+		typeof property === "object" &&
+		property !== null &&
+		"type" in property &&
+		property.type === "relation" &&
+		"database" in property
+	);
+}
+
+// Node's ESM module cache is keyed by URL and never evicts, so importing
+// the same bundle path twice in one process (tests, watch mode) would
+// return whichever module loaded first: stale code after a rebuild, and —
+// even when the code is unchanged — a cache hit skips re-running module
+// top-level side effects, which manifest extraction depends on (e.g.
+// pacers register themselves at creation). A per-import nonce forces a
+// fresh module instance every time; the abandoned cache entries are
+// negligible for a build process. Irrelevant for a single `notion-workers
+// build`, which imports exactly once.
+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 worker bundle. Capability 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 worker bundle does not export a capability registry`);
+	}
+
+	return bundle.capabilities as Record<string, Record<string, unknown> | undefined>;
+}
+
+function asTagged(value: unknown): TaggedObject | undefined {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		"_tag" in value &&
+		typeof value._tag === "string" &&
+		"config" in value &&
+		typeof value.config === "object" &&
+		value.config !== null
+	) {
+		return value as TaggedObject;
+	}
+
+	return undefined;
+}
+
+function asDatabase(value: unknown): DatabaseObject | undefined {
+	const tagged = asTagged(value);
+	if (tagged?._tag === "database" && "name" in tagged && typeof tagged.name === "string") {
+		return tagged as DatabaseObject;
+	}
+
+	return undefined;
+}
+
+function capitalize(value: string): string {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/**
+ * Throw if `value` contains anything `JSON.stringify` would silently drop or
+ * rewrite, so a config that can't round-trip fails the build here rather than
+ * producing a manifest that quietly disagrees with the author's source.
+ *
+ * Rejects functions, symbols, bigints, non-finite numbers, `undefined` array
+ * elements, and non-plain objects (Map, Set, Date, class instances). Allows
+ * null, booleans, finite numbers, strings, plain arrays, and plain objects.
+ * `undefined`-valued object properties are permitted and omitted, mirroring
+ * JSON semantics for unset optional fields.
+ */
+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/alpha/cli/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import * as path from "node:path";
+
+import { buildWorker } from "./build.js";
+
+const USAGE = `Usage: notion-workers <command>
+
+Commands:
+  build    Build the worker 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 buildWorker(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;
+});

package/src/alpha/context.ts

@@ -0,0 +1,61 @@
+import { Client } from "@notionhq/client";
+import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
+import type { CapabilityType } from "./manifest.js";
+
+export type CapabilityContext = {
+	/** Notion API SDK client for this execution. */
+	notion: Client;
+};
+
+const FIX_STEPS =
+	"\n\nTo fix this:\n" +
+	"1. Create a personal access token at https://app.notion.com/developers/tokens\n" +
+	"2. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"3. For deployed workers, run: ntn workers env push";
+
+function missingTokenMessage(capabilityType: CapabilityType): string {
+	if (capabilityType === "tool") {
+		return (
+			"NOTION_API_TOKEN is not set. " +
+			"When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, " +
+			"using the permissions of the Custom Agent. " +
+			"Outside of that context (e.g. ntn workers exec), you must set it yourself." +
+			FIX_STEPS
+		);
+	}
+
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		`context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(capabilityType: CapabilityType): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage(capabilityType));
+		},
+	});
+}
+
+export function createCapabilityContext(capabilityType: CapabilityType): CapabilityContext {
+	const options: ClientOptions = {};
+
+	if (process.env.NOTION_API_BASE_URL) {
+		options.baseUrl = process.env.NOTION_API_BASE_URL;
+	}
+
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy(capabilityType) };
+	}
+
+	options.auth = process.env.NOTION_API_TOKEN;
+	const notion = new Client(options);
+
+	return { notion };
+}

package/src/alpha/database.ts

@@ -0,0 +1,102 @@
+import type { PropertySchema, Schema } from "./schema.js";
+
+/**
+ * Configuration for a database that Notion creates and manages on behalf
+ * of the worker. The database is created on first deploy and its schema
+ * is migrated on subsequent deploys.
+ */
+export type ManagedDatabaseConfig<S extends PropertySchema = PropertySchema> = {
+	type: "managed";
+	/**
+	 * The title for the database when it is first created in Notion.
+	 * Defaults to the database's name.
+	 *
+	 * Updating this after the database has been created will not change the
+	 * title of the database — users may rename it freely.
+	 */
+	initialTitle?: string;
+	/**
+	 * The property that serves as the primary key for matching records.
+	 * Must be a property defined in the schema. The value of this property
+	 * should match the `key` field on each sync change.
+	 */
+	primaryKey: Extract<keyof S, string>;
+	/**
+	 * The database schema. Notion will migrate the database to match
+	 * the given schema on worker deploy.
+	 */
+	schema: Schema<S>;
+};
+
+/**
+ * Configuration union for all database types.
+ * Currently only `"managed"` is supported.
+ */
+export type DatabaseConfig<S extends PropertySchema = PropertySchema> = ManagedDatabaseConfig<S>;
+
+/**
+ * A database declaration as returned by {@link createDatabase}.
+ */
+export type Database<S extends PropertySchema = PropertySchema> = {
+	_tag: "database";
+	name: string;
+	config: DatabaseConfig<S>;
+};
+
+/**
+ * Declare a database.
+ *
+ * A database can be declared anywhere — inline in a sync's config, in the
+ * sync's file, or in a shared module that several syncs import. The build
+ * discovers databases by walking capability configs: any database attached
+ * to a sync (or referenced by a `Schema.relation(...)`) is included in the
+ * manifest and created on deploy.
+ *
+ * The `name` is the database's stable identity across deploys — it is how
+ * the platform matches the declaration to the actual Notion database it
+ * created previously. Renaming it orphans that database, so treat it like a
+ * primary key: pick it once and leave it alone. Two distinct
+ * `createDatabase(...)` calls sharing a name fail the build; share one
+ * instance via import instead.
+ *
+ * @example
+ * ```ts
+ * // src/lib/databases.ts — shared by several syncs
+ * import { createDatabase } from "@notionhq/workers/alpha/database";
+ * import { Schema } from "@notionhq/workers/alpha/schema";
+ *
+ * export const projects = createDatabase("projects", {
+ *   type: "managed",
+ *   primaryKey: "Project ID",
+ *   schema: {
+ *     properties: {
+ *       Name: Schema.title(),
+ *       "Project ID": Schema.richText(),
+ *     },
+ *   },
+ * });
+ *
+ * export const tasks = createDatabase("tasks", {
+ *   type: "managed",
+ *   initialTitle: "Tasks",
+ *   primaryKey: "Task ID",
+ *   schema: {
+ *     properties: {
+ *       Title: Schema.title(),
+ *       "Task ID": Schema.richText(),
+ *       Project: Schema.relation(projects),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createDatabase<S extends PropertySchema>(
+	name: string,
+	config: DatabaseConfig<S>,
+): Database<S> {
+	if (!name || typeof name !== "string") {
+		throw new Error("Database name must be a non-empty string");
+	}
+
+	return { _tag: "database", name, config };
+}

package/src/alpha/error.ts

@@ -0,0 +1,49 @@
+/**
+ * An error that occurred during the execution of a worker capability.
+ */
+export class ExecutionError extends Error {
+	override readonly cause: unknown;
+
+	constructor(cause: unknown) {
+		super(`Error during worker execution: ${cause}`);
+		this.name = "ExecutionError";
+		this.cause = cause;
+	}
+}
+
+/**
+ * Throw this error from your sync handler to signal that the external API
+ * returned a rate-limit response (e.g. HTTP 429).
+ *
+ * When the platform receives this error it applies exponential backoff
+ * instead of retrying immediately. If `retryAfter` is provided, the
+ * platform will wait at least that many seconds before the next attempt.
+ *
+ * @example
+ * ```ts
+ * handler: async () => {
+ *   const res = await fetch("https://api.example.com/issues");
+ *   if (res.status === 429) {
+ *     const retryAfter = Number(res.headers.get("Retry-After"));
+ *     throw new RateLimitError({
+ *       retryAfter: Number.isFinite(retryAfter) ? retryAfter : undefined,
+ *     });
+ *   }
+ *   // ...
+ * },
+ * ```
+ */
+export class RateLimitError extends ExecutionError {
+	/**
+	 * Optional number of seconds the external API asked us to wait
+	 * before retrying. The platform takes the max of this value and its
+	 * own exponential-backoff delay.
+	 */
+	readonly retryAfter: number | undefined;
+
+	constructor(options?: { retryAfter?: number }) {
+		super("Rate limited by external API");
+		this.name = "RateLimitError";
+		this.retryAfter = options?.retryAfter;
+	}
+}