@notionhq/workers 0.2.0 → 0.4.0

package/dist/worker.js

@@ -1,7 +1,12 @@
+import { createAiConnectorCapability } from "./capabilities/ai_connector.js";
 import { createAutomationCapability } from "./capabilities/automation.js";
 import { createOAuthCapability } from "./capabilities/oauth.js";
 import { createSyncCapability } from "./capabilities/sync.js";
 import { createToolCapability } from "./capabilities/tool.js";
+import {
+  createWebhookCapability,
+  WebhookVerificationError
+} from "./capabilities/webhook.js";
 import { pacerWait } from "./pacer_internal.js";
 import { createRequire } from "node:module";
 const SDK_VERSION = (() => {
@@ -111,7 +116,74 @@ class Worker {
    */
   sync(key, config) {
     this.#validateUniqueKey(key);
-    const capability = createSyncCapability(key, config);
+    const capability = createSyncCapability(
+      key,
+      config,
+      Array.from(this.#pacers.values())
+    );
+    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(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createAiConnectorCapability(
+      key,
+      config,
+      Array.from(this.#pacers.values())
+    );
     this.#capabilities.set(key, capability);
     return capability;
   }
@@ -181,6 +253,40 @@ class Worker {
     this.#capabilities.set(key, capability);
     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, config) {
+    this.#validateUniqueKey(key);
+    const capability = createWebhookCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
   /**
    * Register an OAuth capability.
    *
@@ -264,6 +370,9 @@ class Worker {
         `Cannot run OAuth capability "${key}" - OAuth capabilities only provide configuration`
       );
     }
+    if (!capability.handler) {
+      throw new Error(`Capability "${key}" cannot be executed`);
+    }
     return capability.handler(context, options);
   }
   #validateUniqueKey(key) {
@@ -276,5 +385,6 @@ class Worker {
   }
 }
 export {
+  WebhookVerificationError,
   Worker
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"type": "module",
@@ -70,7 +70,7 @@
 		"vitest": "^4.0.8"
 	},
 	"peerDependencies": {
-		"@notionhq/client": "^2.2.15"
+		"@notionhq/client": ">=2.2.15"
 	},
 	"dependencies": {
 		"ajv": "^8.17.1",

package/src/capabilities/ai_connector.test.ts

@@ -0,0 +1,341 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import { ExecutionError } from "../error.js";
+import { getPacerState } from "../pacer_internal.js";
+import { Worker } from "../worker.js";
+import type { AiConnectorExecutionResult } from "./ai_connector.js";
+import { createAiConnectorCapability } from "./ai_connector.js";
+
+describe("Worker.aiConnector", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("registers an ai_connector capability with normalized config", () => {
+		const capability = createAiConnectorCapability("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			mode: "incremental",
+			schedule: "15m",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(capability._tag).toBe("ai_connector");
+		expect(capability.config).toEqual({
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			mode: "incremental",
+			schedule: {
+				type: "interval",
+				intervalMs: 15 * 60 * 1000,
+			},
+		});
+	});
+
+	it("wraps successful handler output in the success envelope", async () => {
+		const capability = createAiConnectorCapability("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			execute: async () => ({
+				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",
+							},
+							messages: [
+								{
+									id: "message-1",
+									content: "Hello",
+									timestamp: "2026-01-01T00:00:00Z",
+									author: {
+										id: "user-1",
+										username: "alice",
+									},
+								},
+							],
+						},
+					},
+				],
+				hasMore: false,
+			}),
+		});
+
+		await capability.handler();
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(`"_tag":"success"`),
+		);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(`"thread-1"`),
+		);
+	});
+
+	it("passes state through from legacy runtime userContext", async () => {
+		const execute = vi.fn(async (state?: { cursor: string }) => ({
+			changes: [],
+			hasMore: false,
+			...(state === undefined ? {} : { nextState: state }),
+		}));
+		const capability = createAiConnectorCapability("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			execute,
+		});
+
+		await capability.handler(
+			{ userContext: { cursor: "cursor-1" } },
+			{ concreteOutput: true },
+		);
+
+		expect(execute).toHaveBeenCalledWith(
+			{ cursor: "cursor-1" },
+			expect.anything(),
+		);
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("hydrates and persists pacer state", async () => {
+		const worker = new Worker();
+		const pacer = worker.pacer("api", {
+			allowedRequests: 1,
+			intervalMs: 1000,
+		});
+		const capability = worker.aiConnector("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			execute: async () => {
+				await pacer.wait();
+				return {
+					changes: [],
+					hasMore: false,
+				};
+			},
+		});
+
+		const before = Date.now() - 1000;
+		const result = await capability.handler(
+			{
+				pacers: {
+					api: {
+						lastScheduledAtMs: before,
+						allowedRequests: 1,
+						intervalMs: 1000,
+					},
+				},
+			},
+			{ concreteOutput: true },
+		);
+
+		expect(result).toEqual({
+			changes: [],
+			hasMore: false,
+			nextPacerStates: {
+				api: {
+					lastScheduledAtMs: expect.any(Number),
+					allowedRequests: 1,
+					intervalMs: 1000,
+				},
+			},
+		});
+		expect(
+			result.nextPacerStates.api?.lastScheduledAtMs,
+		).toBeGreaterThanOrEqual(before);
+	});
+
+	describe("pacer local fallback", () => {
+		it("seeds pacer state from declarations when runtime context has no pacers", async () => {
+			const worker = new Worker();
+			const pacer = worker.pacer("myApi", {
+				allowedRequests: 10,
+				intervalMs: 1000,
+			});
+
+			let pacerWaitCalled = false;
+			const capability = worker.aiConnector("supportChats", {
+				aiConnectorId: "connector-record-id",
+				archetype: "chat",
+				execute: async () => {
+					await pacer.wait();
+					pacerWaitCalled = true;
+					return { changes: [], hasMore: false };
+				},
+			});
+
+			// No runtimeContext → no pacers from server → should fall back to declarations
+			await capability.handler(undefined, { concreteOutput: true });
+
+			expect(pacerWaitCalled).toBe(true);
+			const state = getPacerState();
+			expect(state.pacers.myApi).toBeDefined();
+			expect(state.pacers.myApi?.allowedRequests).toBe(10);
+			expect(state.pacers.myApi?.intervalMs).toBe(1000);
+		});
+
+		it("uses server-provided pacers when available", async () => {
+			const worker = new Worker();
+			const pacer = worker.pacer("myApi", {
+				allowedRequests: 10,
+				intervalMs: 1000,
+			});
+
+			let pacerWaitCalled = false;
+			const capability = worker.aiConnector("supportChats", {
+				aiConnectorId: "connector-record-id",
+				archetype: "chat",
+				execute: async () => {
+					await pacer.wait();
+					pacerWaitCalled = true;
+					return { changes: [], hasMore: false };
+				},
+			});
+
+			// Server provides apportioned budget (e.g., 5 instead of 10)
+			await capability.handler(
+				{
+					pacers: {
+						myApi: {
+							lastScheduledAtMs: 0,
+							allowedRequests: 5,
+							intervalMs: 1000,
+						},
+					},
+				},
+				{ concreteOutput: true },
+			);
+
+			expect(pacerWaitCalled).toBe(true);
+			// Should use server-provided value, not the declaration
+			expect(getPacerState().pacers.myApi?.allowedRequests).toBe(5);
+		});
+	});
+
+	it("wraps handler errors in the shared error envelope", async () => {
+		const capability = createAiConnectorCapability("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			execute: async () => {
+				throw new Error("failed");
+			},
+		});
+
+		await expect(capability.handler()).rejects.toThrow(ExecutionError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(`"_tag":"error"`),
+		);
+	});
+
+	it("accepts chat records at compile time", () => {
+		const result = {
+			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",
+						},
+						messages: [
+							{
+								id: "message-1",
+								content: "Hello",
+								timestamp: "2026-01-01T00:00:00Z",
+								author: {
+									id: "user-1",
+									username: "alice",
+								},
+							},
+						],
+					},
+				},
+			],
+			hasMore: false,
+		} satisfies AiConnectorExecutionResult<"chat">;
+
+		expect(result.hasMore).toBe(false);
+	});
+
+	it("accepts project records with required blocks at compile time", () => {
+		const result = {
+			changes: [
+				{
+					type: "upsert",
+					key: "project-1",
+					record: {
+						name: "Roadmap",
+						createdAt: "2026-01-01T00:00:00Z",
+						updatedAt: "2026-01-01T00:00:00Z",
+						blocks: [
+							{
+								id: "block-1",
+								type: "paragraph",
+								content: "Ship the roadmap",
+							},
+						],
+					},
+				},
+			],
+			hasMore: false,
+		} satisfies AiConnectorExecutionResult<"project">;
+
+		expect(result.changes).toHaveLength(1);
+	});
+
+	it("rejects project records without blocks at compile time", () => {
+		const changes = [
+			{
+				type: "upsert",
+				key: "project-1",
+				// @ts-expect-error Project records must include blocks.
+				record: {
+					name: "Roadmap",
+					createdAt: "2026-01-01T00:00:00Z",
+					updatedAt: "2026-01-01T00:00:00Z",
+				},
+			},
+		] satisfies AiConnectorExecutionResult<"project">["changes"];
+
+		expect(changes).toHaveLength(1);
+	});
+
+	it("rejects replace mode at compile time", () => {
+		createAiConnectorCapability("supportChats", {
+			aiConnectorId: "connector-record-id",
+			archetype: "chat",
+			// @ts-expect-error AI connector capabilities are incremental-only for now.
+			mode: "replace",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(true).toBe(true);
+	});
+});

package/src/capabilities/ai_connector.ts

@@ -0,0 +1,194 @@
+import { ExecutionError } from "../error.js";
+import {
+	getPacerState,
+	initPacerState,
+	type PacerDeclaration,
+	type PacerEntry,
+} from "../pacer_internal.js";
+import type { HandlerOptions, Schedule } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
+import {
+	parseSchedule,
+	type StatefulCapabilityMode,
+	type StatefulExecutionResult,
+	type RuntimeContext as StatefulRuntimeContext,
+} from "./stateful-capability.js";
+
+export type AiConnectorArchetype = "chat" | "project";
+/**
+ * AI connector syncs are incremental-only for now.
+ *
+ * Unlike collection syncs, AI connector ingestion does not yet support
+ * replace-style reconciliation semantics, so exposing `replace` here would
+ * encourage a misleading reset-and-replay model.
+ */
+export type AiConnectorMode = Exclude<StatefulCapabilityMode, "replace">;
+
+export type AiConnectorChatAuthor = {
+	id: string;
+	username: string;
+};
+
+export type AiConnectorChatMessage = {
+	id: string;
+	content: string;
+	timestamp: string;
+	editedTimestamp?: string;
+	author: AiConnectorChatAuthor;
+};
+
+export type AiConnectorChatChannel = {
+	id: string;
+	name: string;
+};
+
+export type AiConnectorChatRecord = {
+	createdAt: string;
+	updatedAt: string;
+	externalUrl?: string;
+	channel: AiConnectorChatChannel;
+	threadId?: string;
+	messages: AiConnectorChatMessage[];
+	chatType?: string;
+};
+
+export type AiConnectorProjectBlock = {
+	id: string;
+	type: string;
+	content: string;
+};
+
+export type AiConnectorProjectRecord = {
+	name: string;
+	createdAt: string;
+	updatedAt: string;
+	externalUrl?: string;
+	priority?: string;
+	teams?: string[];
+	targetEnd?: string;
+	createdBy?: {
+		id: string;
+	};
+	blocks: AiConnectorProjectBlock[];
+};
+
+export type AiConnectorRecordByArchetype = {
+	chat: AiConnectorChatRecord;
+	project: AiConnectorProjectRecord;
+};
+
+export type AiConnectorChangeUpsert<A extends AiConnectorArchetype> = {
+	type: "upsert";
+	key: string;
+	record: AiConnectorRecordByArchetype[A];
+};
+
+export type AiConnectorChange<A extends AiConnectorArchetype> =
+	AiConnectorChangeUpsert<A>;
+
+export type AiConnectorExecutionResult<
+	A extends AiConnectorArchetype,
+	State = unknown,
+> = StatefulExecutionResult<AiConnectorChange<A>, State>;
+
+export type AiConnectorConfiguration<
+	A extends AiConnectorArchetype,
+	State = unknown,
+> = {
+	/**
+	 * The Notion record ID of an existing custom connector in the target workspace.
+	 *
+	 * This must be the connector record UUID that Notion created, not an external
+	 * source identifier.
+	 */
+	aiConnectorId: string;
+	archetype: A;
+	mode?: AiConnectorMode;
+	schedule?: Schedule;
+	execute: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<AiConnectorExecutionResult<A, State>>;
+};
+
+export type AiConnectorCapability = ReturnType<
+	typeof createAiConnectorCapability
+>;
+
+type NormalizedAiConnectorConfiguration<A extends AiConnectorArchetype> = {
+	aiConnectorId: string;
+	archetype: A;
+	mode?: AiConnectorMode;
+	schedule?: ReturnType<typeof parseSchedule>;
+};
+
+type AiConnectorHandlerResult<A extends AiConnectorArchetype, State> = {
+	changes: AiConnectorChange<A>[];
+	hasMore: boolean;
+	nextUserContext?: State;
+	nextPacerStates: Record<string, PacerEntry>;
+};
+
+export function createAiConnectorCapability<
+	A extends AiConnectorArchetype,
+	State = unknown,
+>(
+	key: string,
+	configuration: AiConnectorConfiguration<A, State>,
+	pacerDeclarations?: readonly PacerDeclaration[],
+) {
+	return {
+		_tag: "ai_connector" as const,
+		key,
+		config: {
+			aiConnectorId: configuration.aiConnectorId,
+			archetype: configuration.archetype,
+			...(configuration.mode === undefined ? {} : { mode: configuration.mode }),
+			...(configuration.schedule === undefined
+				? {}
+				: { schedule: parseSchedule(configuration.schedule) }),
+		} satisfies NormalizedAiConnectorConfiguration<A>,
+		async handler(
+			runtimeContext?: StatefulRuntimeContext<State>,
+			options?: HandlerOptions,
+		) {
+			const capabilityContext = createCapabilityContext("ai_connector");
+			const state = runtimeContext?.state ?? runtimeContext?.userContext;
+
+			initPacerState(runtimeContext?.pacers, pacerDeclarations);
+
+			let executionResult: AiConnectorExecutionResult<A, State>;
+			try {
+				executionResult = await configuration.execute(state, capabilityContext);
+			} catch (err) {
+				const error = new ExecutionError(err);
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: { name: error.name, message: error.message },
+					});
+				}
+				throw error;
+			}
+
+			const result = {
+				changes: executionResult.changes,
+				hasMore: executionResult.hasMore,
+				...(executionResult.nextState === undefined
+					? {}
+					: { nextUserContext: executionResult.nextState }),
+				nextPacerStates: getPacerState().pacers,
+			} satisfies AiConnectorHandlerResult<A, State>;
+
+			if (options?.concreteOutput) {
+				return result;
+			}
+
+			writeOutput({ _tag: "success", value: result });
+
+			return result;
+		},
+	};
+}