@notionhq/workers 0.2.0 → 0.3.0

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();
+			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;
+		},
+	};
+}

package/src/capabilities/automation.ts

@@ -2,6 +2,7 @@ import { ExecutionError } from "../error.js";
 import type { HandlerOptions } from "../types.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
 
 /**
  * Event provided to automation execute functions
@@ -110,17 +111,20 @@ export function createAutomationCapability(
 				if (options?.concreteOutput) {
 					return { status: "success" };
 				} else {
-					process.stdout.write(
-						`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: { status: "success" } })}</__notion_output__>\n`,
-					);
+					writeOutput({ _tag: "success", value: { status: "success" } });
 				}
 			} catch (err) {
 				const error = new ExecutionError(err);
 
 				if (!options?.concreteOutput) {
-					process.stdout.write(
-						`\n<__notion_output__>${JSON.stringify({ _tag: "error", error: { name: error.name, message: error.message, trace: error.stack } })}</__notion_output__>\n`,
-					);
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
 				}
 
 				throw error;

package/src/capabilities/output.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes a notion_output envelope to stdout using the shared wire format.
+ */
+export function writeOutput(value: unknown): void {
+	process.stdout.write(
+		`\n<__notion_output__>${JSON.stringify(value)}</__notion_output__>\n`,
+	);
+}

package/src/capabilities/stateful-capability.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { parseSchedule } from "./stateful-capability.js";
+
+describe("stateful capability shared primitives", () => {
+	it("parses interval schedules into normalized backend config", () => {
+		expect(parseSchedule("15m")).toEqual({
+			type: "interval",
+			intervalMs: 15 * 60 * 1000,
+		});
+	});
+
+	it("parses continuous schedules directly", () => {
+		expect(parseSchedule("continuous")).toEqual({ type: "continuous" });
+	});
+
+	it("parses manual schedules directly", () => {
+		expect(parseSchedule("manual")).toEqual({ type: "manual" });
+	});
+
+	it("rejects intervals longer than the supported maximum", () => {
+		expect(() => parseSchedule("8d")).toThrow(
+			'Schedule interval must be at most 7 days. Got: "8d"',
+		);
+	});
+});

package/src/capabilities/stateful-capability.ts

@@ -0,0 +1,87 @@
+import { unreachable } from "../error.js";
+import type { PacerEntry } from "../pacer_internal.js";
+import type { Schedule, SyncSchedule, TimeUnit } from "../types.js";
+
+/**
+ * Shared lifecycle mode used by sync-like capabilities.
+ */
+export type StatefulCapabilityMode = "replace" | "incremental";
+
+/**
+ * Base runtime context shared by sync-like capabilities.
+ */
+export type RuntimeContext<UserContext = unknown> = {
+	/** The user-defined/-controlled state (cursor, pagination state, etc.) */
+	state?: UserContext;
+	/** Legacy field for user-defined/-controlled state. */
+	userContext?: UserContext;
+	/** Pacer state from the server for rate limiting. */
+	pacers?: Record<string, PacerEntry>;
+};
+
+/**
+ * Shared execution result returned from stateful capability execute functions.
+ */
+export type StatefulExecutionResult<Change, State = unknown> = {
+	changes: Change[];
+	hasMore: boolean;
+	nextState?: State;
+};
+
+const MS_PER_MINUTE = 60 * 1000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+
+const MIN_INTERVAL_MS = MS_PER_MINUTE; // 1m
+const MAX_INTERVAL_MS = 7 * MS_PER_DAY; // 7d
+
+/**
+ * Parses a user-friendly schedule string into the normalized backend format.
+ */
+export function parseSchedule(schedule: Schedule): SyncSchedule {
+	if (schedule === "continuous") {
+		return { type: "continuous" };
+	}
+
+	if (schedule === "manual") {
+		return { type: "manual" };
+	}
+
+	const match = schedule.match(/^(\d+)(m|h|d)$/);
+	if (!match || !match[1] || !match[2]) {
+		throw new Error(
+			`Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`,
+		);
+	}
+
+	const value = parseInt(match[1], 10);
+	const unit = match[2] as TimeUnit;
+
+	let intervalMs: number;
+	switch (unit) {
+		case "m":
+			intervalMs = value * MS_PER_MINUTE;
+			break;
+		case "h":
+			intervalMs = value * MS_PER_HOUR;
+			break;
+		case "d":
+			intervalMs = value * MS_PER_DAY;
+			break;
+		default:
+			unreachable(unit);
+	}
+
+	if (intervalMs < MIN_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at least 1 minute. Got: "${schedule}"`,
+		);
+	}
+	if (intervalMs > MAX_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at most 7 days. Got: "${schedule}"`,
+		);
+	}
+
+	return { type: "interval", intervalMs };
+}