@notionhq/workers 0.0.86 → 0.2.0

package/src/worker.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+
+import * as Schema from "./schema.js";
+import { Worker } from "./worker.js";
+
+describe("Worker", () => {
+	it("includes sdkVersion, databases, and capabilities in manifest", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		worker.sync("tasksSync", {
+			database: tasks,
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.sdkVersion).toMatch(/^\d+\.\d+\.\d+/);
+		expect(worker.manifest.databases).toEqual([
+			{
+				key: "tasks",
+				config: {
+					type: "managed",
+					initialTitle: "Tasks",
+					primaryKeyProperty: "Name",
+					schema: {
+						properties: {
+							Name: { type: "title" },
+						},
+					},
+				},
+			},
+		]);
+		expect(worker.manifest.pacers).toEqual([]);
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "sync",
+				key: "tasksSync",
+				config: {
+					databaseKey: "tasks",
+					primaryKeyProperty: "Name",
+					mode: undefined,
+					schedule: undefined,
+				},
+			},
+		]);
+	});
+
+	it("serializes manual schedules in the manifest", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		worker.sync("tasksBackfill", {
+			database: tasks,
+			schedule: "manual",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "sync",
+				key: "tasksBackfill",
+				config: {
+					databaseKey: "tasks",
+					primaryKeyProperty: "Name",
+					mode: undefined,
+					schedule: {
+						type: "manual",
+					},
+				},
+			},
+		]);
+	});
+
+	it("includes pacers in manifest and links to sync capabilities", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		const _jiraPacer = worker.pacer("jira", {
+			allowedRequests: 10,
+			intervalMs: 1000,
+		});
+
+		worker.sync("jiraBackfill", {
+			database: tasks,
+			schedule: "manual",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		worker.sync("jiraDelta", {
+			database: tasks,
+			schedule: "5m",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.pacers).toEqual([
+			{
+				key: "jira",
+				config: {
+					allowedRequests: 10,
+					intervalMs: 1000,
+				},
+			},
+		]);
+	});
+
+	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
+		const worker = new Worker();
+		const db = worker.database("shared-key", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		expect(() =>
+			worker.sync("shared-key", {
+				database: db,
+				execute: async () => ({
+					changes: [],
+					hasMore: false,
+				}),
+			}),
+		).toThrow('Worker item with key "shared-key" already registered');
+	});
+});

package/src/worker.ts

@@ -16,6 +16,7 @@ import type { SyncCapability, SyncConfiguration } from "./capabilities/sync.js";
 import { createSyncCapability } from "./capabilities/sync.js";
 import type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
 import { createToolCapability } from "./capabilities/tool.js";
+import { pacerWait } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
 
@@ -42,12 +43,193 @@ type Capability =
 	| AutomationCapability
 	| OAuthCapability;
 
+/**
+ * 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<PK extends string, S extends Schema<PK>> = {
+	type: "managed";
+	/**
+	 * The title for the database when it is first created in Notion.
+	 *
+	 * 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.
+	 */
+	primaryKeyProperty: PK;
+	/**
+	 * The database schema. Notion will migrate the database to match
+	 * the given schema on worker deploy.
+	 */
+	schema: S;
+};
+
+/**
+ * Configuration union for all database types.
+ * Currently only `"managed"` is supported.
+ */
+export type DatabaseConfig<
+	PK extends string,
+	S extends Schema<PK>,
+> = ManagedDatabaseConfig<PK, S>;
+
+/**
+ * An opaque handle returned by `worker.database()`. Pass this to
+ * `worker.sync()` to associate a sync capability with the database.
+ */
+export type DatabaseHandle<PK extends string, S extends Schema<PK>> = {
+	readonly key: string;
+	readonly config: DatabaseConfig<PK, S>;
+};
+
+/** Internal type-erased alias for storing heterogeneous databases. */
+type RegisteredDatabase = DatabaseHandle<string, Schema<string>>;
+
+/**
+ * Configuration for a pacer that rate-limits requests to an external API.
+ * If multiple syncs share a pacer, the server apportions the budget evenly.
+ */
+export type PacerConfig = {
+	/** Maximum number of requests allowed per interval. */
+	allowedRequests: number;
+	/** The interval window in milliseconds. */
+	intervalMs: number;
+};
+
+/**
+ * An opaque handle returned by `worker.pacer()`. Call `handle.wait()`
+ * before each API request to stay under the rate limit.
+ */
+export type PacerHandle = {
+	readonly key: string;
+	readonly config: PacerConfig;
+	/**
+	 * Wait until a request can proceed under this pacer's rate limit.
+	 *
+	 * Call this before **every** API request inside your sync's `execute` function.
+	 * The pacer ensures requests are evenly spaced over the interval window.
+	 *
+	 * @example
+	 * ```ts
+	 * const apiPacer = worker.pacer("myApi", { allowedRequests: 10, intervalMs: 1000 });
+	 *
+	 * worker.sync("mySync", {
+	 *   database: myDb,
+	 *   execute: async () => {
+	 *     await apiPacer.wait();
+	 *     const data = await fetchFromApi();
+	 *     // ...
+	 *   },
+	 * });
+	 * ```
+	 */
+	wait(): Promise<void>;
+};
+
+/**
+ * A pacer declaration as it appears in the manifest.
+ */
+export type PacerDeclaration = {
+	readonly key: string;
+	readonly config: PacerConfig;
+};
+
+/** A capability entry stripped of its handler, used in the manifest. */
+type CapabilityManifestEntry = Pick<Capability, "_tag" | "key" | "config">;
+
+/**
+ * The full worker manifest, read by the server at deploy time to discover
+ * databases, pacers, capabilities, and the SDK version.
+ */
+export type WorkerManifest = {
+	readonly sdkVersion: string;
+	readonly databases: readonly RegisteredDatabase[];
+	readonly pacers: readonly PacerDeclaration[];
+	readonly capabilities: readonly CapabilityManifestEntry[];
+};
+
+// Read SDK version from package.json at module load time.
+// createRequire bridges ESM → CJS so we can require() a JSON file.
+import { createRequire } from "node:module";
+
+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;
+})();
+
 // ============================================================================
 // Worker class
 // ============================================================================
 
 export class Worker {
 	#capabilities: Map<string, Capability> = new Map();
+	#databases: Map<string, RegisteredDatabase> = new Map();
+	#pacers: Map<string, PacerDeclaration> = new Map();
+
+	database<PK extends string, S extends Schema<PK>>(
+		key: string,
+		config: DatabaseConfig<PK, S>,
+	): DatabaseHandle<PK, S> {
+		this.#validateUniqueKey(key);
+		const database: DatabaseHandle<PK, S> = { key, config };
+		this.#databases.set(key, { key, config });
+		return database;
+	}
+
+	/**
+	 * Register a pacer for rate-limiting requests to an external API.
+	 *
+	 * Multiple syncs can share a pacer — the server will apportion the
+	 * budget evenly across all syncs that reference it.
+	 *
+	 * Example:
+	 *
+	 * ```ts
+	 * const jiraPacer = worker.pacer("jira", {
+	 *   allowedRequests: 10,
+	 *   intervalMs: 1000,
+	 * });
+	 *
+	 * worker.sync("jiraSync", {
+	 *   database: tasks,
+	 *   execute: async (state, { notion }) => {
+	 *     await jiraPacer.wait();
+	 *     const data = await fetchFromJira();
+	 *     // ...
+	 *   },
+	 * });
+	 * ```
+	 *
+	 * @param key - The unique key for this pacer.
+	 * @param config - The rate limit configuration.
+	 * @returns A pacer handle. Call `handle.wait()` before each API request.
+	 */
+	pacer(key: string, config: PacerConfig): PacerHandle {
+		this.#validateUniqueKey(key);
+		this.#pacers.set(key, { key, config });
+		return {
+			key,
+			config,
+			wait: () => pacerWait(key),
+		};
+	}
 
 	/**
 	 * Register a sync capability.
@@ -62,26 +244,29 @@ export class Worker {
 	 * const worker = new Worker();
 	 * export default worker;
 	 *
-	 * worker.sync("tasksSync", {
-	 *   primaryKeyProperty: "Task ID",
+	 * const tasks = worker.database("tasks", {
+	 *   type: "managed",
+	 *   initialTitle: "Tasks",
 	 *   schema: {
-	 *     defaultName: "Tasks",
 	 *     properties: {
 	 *       "Task Name": Schema.title(),
-	 *       "Task ID": Schema.richText(),
 	 *       Status: Schema.select([
 	 *         { name: "Open", color: "default" },
 	 *         { name: "Done", color: "green" },
 	 *       ]),
 	 *     },
 	 *   },
+	 * });
+	 *
+	 * worker.sync("tasksSync", {
+	 *   database: tasks,
 	 *   execute: async () => {
 	 *     const changes = [
 	 *       {
 	 *         key: "task-1",
+	 *         type: "upsert",
 	 *         properties: {
 	 *           "Task Name": Builder.title("Write docs"),
-	 *           "Task ID": Builder.richText("task-1"),
 	 *           Status: Builder.select("Open"),
 	 *         },
 	 *       },
@@ -240,6 +425,15 @@ export class Worker {
 		}));
 	}
 
+	get manifest(): WorkerManifest {
+		return {
+			sdkVersion: SDK_VERSION,
+			databases: Array.from(this.#databases.values()),
+			pacers: Array.from(this.#pacers.values()),
+			capabilities: this.capabilities,
+		};
+	}
+
 	/**
 	 * Execute a capability by key.
 	 *
@@ -273,8 +467,12 @@ export class Worker {
 		if (!key || typeof key !== "string") {
 			throw new Error("Capability key must be a non-empty string");
 		}
-		if (this.#capabilities.has(key)) {
-			throw new Error(`Capability with key "${key}" already registered`);
+		if (
+			this.#capabilities.has(key) ||
+			this.#databases.has(key) ||
+			this.#pacers.has(key)
+		) {
+			throw new Error(`Worker item with key "${key}" already registered`);
 		}
 	}
 }