@notionhq/workers 0.1.0 → 0.3.0

package/src/worker.ts

@@ -1,3 +1,9 @@
+import type {
+	AiConnectorArchetype,
+	AiConnectorCapability,
+	AiConnectorConfiguration,
+} from "./capabilities/ai_connector.js";
+import { createAiConnectorCapability } from "./capabilities/ai_connector.js";
 import type {
 	AutomationCapability,
 	AutomationConfiguration,
@@ -16,6 +22,17 @@ 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 type {
+	WebhookCapability,
+	WebhookConfiguration,
+	WebhookEvent,
+} from "./capabilities/webhook.js";
+import {
+	createWebhookCapability,
+	WebhookVerificationError,
+} from "./capabilities/webhook.js";
+import type { PacerDeclaration } from "./pacer_internal.js";
+import { pacerWait } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
 
@@ -23,13 +40,17 @@ import type { HandlerOptions, JSONValue } from "./types.js";
 export type {
 	AutomationConfiguration,
 	AutomationEvent,
+	AiConnectorConfiguration,
 	CapabilityContext,
 	OAuthConfiguration,
 	NotionManagedOAuthConfiguration,
 	UserManagedOAuthConfiguration,
 	SyncConfiguration,
 	ToolConfiguration,
+	WebhookConfiguration,
+	WebhookEvent,
 };
+export { WebhookVerificationError };
 
 // ============================================================================
 // Capability types
@@ -37,10 +58,138 @@ export type {
 
 type Capability =
 	| SyncCapability
-	// biome-ignore lint/suspicious/noExplicitAny: any is used to allow any input and output types
+	| AiConnectorCapability
+	// biome-ignore lint/suspicious/noExplicitAny: tool capabilities are generic over arbitrary input/output payloads.
 	| ToolCapability<any, any>
 	| AutomationCapability
-	| OAuthCapability;
+	| OAuthCapability
+	| WebhookCapability;
+
+/**
+ * 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>;
+};
+
+// Re-exported from pacer_internal.js (the canonical definition).
+export type { PacerDeclaration };
+
+/** 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
@@ -48,6 +197,56 @@ type Capability =
 
 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 +261,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"),
 	 *         },
 	 *       },
@@ -101,7 +303,78 @@ export class Worker {
 		config: SyncConfiguration<PK, S, Context>,
 	): SyncCapability {
 		this.#validateUniqueKey(key);
-		const capability = createSyncCapability(key, config);
+		const capability = createSyncCapability(
+			key,
+			config,
+			Array.from(this.#pacers.values()),
+		) as SyncCapability;
+		this.#capabilities.set(key, capability);
+		return capability;
+	}
+
+	/**
+	 * Register an AI connector capability.
+	 *
+	 * Example:
+	 *
+	 * ```ts
+	 * const worker = new Worker();
+	 * export default worker;
+	 *
+	 * worker.aiConnector("supportChats", {
+	 *   aiConnectorId: "connector-record-id",
+	 *   archetype: "chat",
+	 *   mode: "incremental",
+	 *   schedule: "15m",
+	 *   execute: async (state) => ({
+	 *     changes: [
+	 *       {
+	 *         type: "upsert",
+	 *         key: "thread-1",
+	 *         record: {
+	 *           createdAt: "2026-01-01T00:00:00Z",
+	 *           updatedAt: "2026-01-01T00:00:00Z",
+	 *           channel: {
+	 *             id: "channel-1",
+	 *             name: "Support",
+	 *           },
+	 *           threadId: "thread-1",
+	 *           messages: [
+	 *             {
+	 *               id: "message-1",
+	 *               content: "Hello from support",
+	 *               timestamp: "2026-01-01T00:00:00Z",
+	 *               author: {
+	 *                 id: "user-1",
+	 *                 username: "alice",
+	 *               },
+	 *             },
+	 *           ],
+	 *         },
+	 *       },
+	 *     ],
+	 *     hasMore: false,
+	 *   }),
+	 * });
+	 * ```
+	 *
+	 * `aiConnectorId` must be the Notion record ID of an existing custom
+	 * connector in the workspace where you deploy this worker.
+	 *
+	 * @param key - The unique key for this capability.
+	 * @param config - The AI connector configuration.
+	 * @returns The capability object.
+	 */
+	aiConnector<A extends AiConnectorArchetype, Context = unknown>(
+		key: string,
+		config: AiConnectorConfiguration<A, Context>,
+	): AiConnectorCapability {
+		this.#validateUniqueKey(key);
+		const capability = createAiConnectorCapability(
+			key,
+			config,
+			Array.from(this.#pacers.values()),
+		) as AiConnectorCapability;
 		this.#capabilities.set(key, capability);
 		return capability;
 	}
@@ -181,6 +454,41 @@ export class Worker {
 		return capability;
 	}
 
+	/**
+	 * Register a webhook capability.
+	 *
+	 * Webhooks expose an HTTP endpoint that external services can call.
+	 * When hit, the request is processed by the worker's execute function.
+	 *
+	 * Example:
+	 *
+	 * ```ts
+	 * const worker = new Worker();
+	 * export default worker;
+	 *
+	 * worker.webhook("onGithubPush", {
+	 *   title: "GitHub Push Webhook",
+	 *   description: "Handles push events from GitHub",
+	 *   execute: async (events, { notion }) => {
+	 *    for (const event of events) {
+	 *      console.log("Received webhook:", event.body);
+	 *      console.log("Headers:", event.headers);
+	 *    }
+	 *   },
+	 * })
+	 * ```
+	 *
+	 * @param key - The unique key for this capability. Used as the webhook name in the URL.
+	 * @param config - The webhook configuration.
+	 * @returns The capability object.
+	 */
+	webhook(key: string, config: WebhookConfiguration): WebhookCapability {
+		this.#validateUniqueKey(key);
+		const capability = createWebhookCapability(key, config);
+		this.#capabilities.set(key, capability);
+		return capability;
+	}
+
 	/**
 	 * Register an OAuth capability.
 	 *
@@ -240,6 +548,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.
 	 *
@@ -265,6 +582,10 @@ export class Worker {
 			);
 		}
 
+		if (!capability.handler) {
+			throw new Error(`Capability "${key}" cannot be executed`);
+		}
+
 		// biome-ignore lint/suspicious/noExplicitAny: context is unknown, passed by external non-typed code.
 		return capability.handler(context as any, options);
 	}
@@ -273,8 +594,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`);
 		}
 	}
 }