@notionhq/workers 0.2.0 → 0.4.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,16 @@ 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";
@@ -24,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
@@ -38,10 +58,14 @@ 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;
+
+export type CapabilityType = Capability["_tag"];
 
 /**
  * Configuration for a database that Notion creates and manages on behalf
@@ -132,13 +156,8 @@ export type PacerHandle = {
 	wait(): Promise<void>;
 };
 
-/**
- * A pacer declaration as it appears in the manifest.
- */
-export type PacerDeclaration = {
-	readonly key: string;
-	readonly config: PacerConfig;
-};
+// 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">;
@@ -286,7 +305,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;
 	}
@@ -366,6 +456,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.
 	 *
@@ -459,6 +584,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);
 	}