@notionhq/workers 0.2.0 → 0.3.0

package/src/capabilities/sync.test.ts

@@ -9,6 +9,7 @@ import {
 } from "vitest";
 import * as Builder from "../builder.js";
 import { ExecutionError } from "../error.js";
+import { getPacerState } from "../pacer_internal.js";
 import * as Schema from "../schema.js";
 import { Worker } from "../worker.js";
 import { createSyncCapability } from "./sync.js";
@@ -28,11 +29,11 @@ describe("Worker.sync", () => {
 
 	describe("Schema.relation", () => {
 		it("creates a relation property configuration", () => {
-			const relationProp = Schema.relation("projectsSync");
+			const relationProp = Schema.relation("projects");
 
 			expect(relationProp).toEqual({
 				type: "relation",
-				relatedSyncKey: "projectsSync",
+				relatedDatabaseKey: "projects",
 				config: { twoWay: false },
 			});
 		});
@@ -68,7 +69,7 @@ describe("Worker.sync", () => {
 				schema: {
 					properties: {
 						"Task ID": Schema.title(),
-						Project: Schema.relation("projectsSync"),
+						Project: Schema.relation("projects"),
 					},
 				},
 			});
@@ -106,6 +107,91 @@ describe("Worker.sync", () => {
 		});
 	});
 
+	describe("pacer local fallback", () => {
+		it("seeds pacer state from declarations when runtime context has no pacers", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: { properties: { ID: Schema.title() } },
+			});
+			const pacer = worker.pacer("myApi", {
+				allowedRequests: 10,
+				intervalMs: 1000,
+			});
+
+			let pacerWaitCalled = false;
+			const capability = createSyncCapability(
+				"testSync",
+				{
+					database: db,
+					execute: async () => {
+						await pacer.wait();
+						pacerWaitCalled = true;
+						return { changes: [], hasMore: false };
+					},
+				},
+				[{ key: "myApi", config: { allowedRequests: 10, intervalMs: 1000 } }],
+			);
+
+			// 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 db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: { properties: { ID: Schema.title() } },
+			});
+			const pacer = worker.pacer("myApi", {
+				allowedRequests: 10,
+				intervalMs: 1000,
+			});
+
+			let pacerWaitCalled = false;
+			const capability = createSyncCapability(
+				"testSync",
+				{
+					database: db,
+					execute: async () => {
+						await pacer.wait();
+						pacerWaitCalled = true;
+						return { changes: [], hasMore: false };
+					},
+				},
+				[{ key: "myApi", config: { allowedRequests: 10, intervalMs: 1000 } }],
+			);
+
+			// 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);
+		});
+	});
+
 	describe("handler output envelope", () => {
 		it("wraps successful result in success envelope", async () => {
 			const worker = new Worker();

package/src/capabilities/sync.ts

@@ -1,8 +1,8 @@
-import { ExecutionError, unreachable } from "../error.js";
+import { ExecutionError } from "../error.js";
 import {
 	getPacerState,
-	type PacerEntry,
-	setPacerState,
+	initPacerState,
+	type PacerDeclaration,
 } from "../pacer_internal.js";
 import type {
 	PropertyConfiguration,
@@ -16,13 +16,17 @@ import type {
 	PlaceValue,
 	RelationValue,
 	Schedule,
-	SyncSchedule,
 	TextValue,
-	TimeUnit,
 } from "../types.js";
 import type { DatabaseHandle } from "../worker.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
+import {
+	parseSchedule,
+	type StatefulCapabilityMode,
+	type RuntimeContext as StatefulRuntimeContext,
+} from "./stateful-capability.js";
 
 /**
  * Maps a property configuration to its corresponding value type.
@@ -40,7 +44,7 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
 /**
  * Sync mode determines how the sync handles data lifecycle.
  */
-export type SyncMode = "replace" | "incremental";
+export type SyncMode = StatefulCapabilityMode;
 
 /**
  * A change representing a record to be created or updated.
@@ -204,18 +208,6 @@ export type SyncConfiguration<
 
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
 
-/**
- * Runtime context object passed from the runtime to sync capability handlers.
- */
-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>;
-};
-
 /**
  * Creates a special handler for syncing third-party data to a database.
  *
@@ -227,7 +219,11 @@ export function createSyncCapability<
 	PK extends string,
 	S extends Schema<PK>,
 	Context = unknown,
->(key: string, syncConfiguration: SyncConfiguration<PK, S, Context>) {
+>(
+	key: string,
+	syncConfiguration: SyncConfiguration<PK, S, Context>,
+	pacerDeclarations?: readonly PacerDeclaration[],
+) {
 	return {
 		_tag: "sync" as const,
 		key,
@@ -240,14 +236,13 @@ export function createSyncCapability<
 				: undefined,
 		},
 		async handler(
-			runtimeContext?: RuntimeContext<Context>,
+			runtimeContext?: StatefulRuntimeContext<Context>,
 			options?: HandlerOptions,
 		) {
 			const capabilityContext = createCapabilityContext();
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
-			// Initialize pacer state from runtime context
-			setPacerState({ pacers: runtimeContext?.pacers ?? {} });
+			initPacerState(runtimeContext?.pacers, pacerDeclarations);
 
 			let executionResult: SyncExecutionResult<PK, Context>;
 			try {
@@ -258,9 +253,10 @@ export function createSyncCapability<
 			} 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 } })}</__notion_output__>\n`,
-					);
+					writeOutput({
+						_tag: "error",
+						error: { name: error.name, message: error.message },
+					});
 				}
 				throw error;
 			}
@@ -281,70 +277,10 @@ export function createSyncCapability<
 			if (options?.concreteOutput) {
 				return result;
 			} else {
-				process.stdout.write(
-					`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: result })}</__notion_output__>\n`,
-				);
+				writeOutput({ _tag: "success", value: result });
 			}
 
 			return result;
 		},
 	};
 }
-
-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.
- */
-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 };
-}

package/src/capabilities/tool.ts

@@ -6,6 +6,7 @@ import { getSchema } from "../schema-builder.js";
 import type { HandlerOptions, JSONValue } from "../types.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
 
 /**
  * Validates that every object schema in the tree has all its `properties`
@@ -211,9 +212,7 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-			);
+			writeOutput(result);
 
 			return result;
 		}
@@ -239,9 +238,7 @@ export function createToolCapability<
 					},
 				};
 
-				process.stdout.write(
-					`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-				);
+				writeOutput(result);
 
 				return result;
 			}
@@ -250,9 +247,7 @@ export function createToolCapability<
 				return result;
 			}
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: result })}</__notion_output__>\n`,
-			);
+			writeOutput({ _tag: "success", value: result });
 
 			return {
 				_tag: "success" as const,
@@ -272,9 +267,7 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-			);
+			writeOutput(result);
 
 			return result;
 		}

package/src/capabilities/webhook.ts

@@ -0,0 +1,148 @@
+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";
+
+/**
+ * A single incoming webhook request.
+ */
+export interface WebhookEvent {
+	/**
+	 * Unique ID for this webhook delivery, stable across retries.
+	 * Best-effort idempotency key — prefer using the webhook provider's
+	 * own delivery/event ID when available, since providers may redeliver
+	 * the same event with a new deliveryId.
+	 */
+	deliveryId: string;
+	/**
+	 * The parsed JSON body of the incoming request, or an empty object if
+	 * the body is not valid JSON.
+	 */
+	body: Record<string, unknown>;
+	/**
+	 * The raw request body as a string, useful for signature verification.
+	 */
+	rawBody: string;
+	/**
+	 * The HTTP headers from the incoming request
+	 */
+	headers: Record<string, string>;
+	/**
+	 * The HTTP method of the incoming request (e.g. "POST")
+	 */
+	method: string;
+}
+
+/**
+ * Throw this error from your webhook execute handler to signal that
+ * signature verification failed. After 5 consecutive verification
+ * failures, the platform will short-circuit and reject all incoming
+ * requests for this webhook without executing the handler.
+ *
+ * @example
+ * ```ts
+ * worker.webhook("onGithubPush", {
+ *   title: "GitHub Push",
+ *   description: "Handles GitHub push events",
+ *   execute: async (events) => {
+ *     const secret = process.env.GITHUB_WEBHOOK_SECRET;
+ *     if (!secret) {
+ *       throw new WebhookVerificationError("GITHUB_WEBHOOK_SECRET not set");
+ *     }
+ *     for (const event of events) {
+ *       if (!verifyGitHubSignature(event.rawBody, event.headers, secret)) {
+ *         throw new WebhookVerificationError("Invalid GitHub signature");
+ *       }
+ *       // ... handle verified event
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export class WebhookVerificationError extends ExecutionError {
+	constructor(cause?: unknown) {
+		super(cause ?? "Webhook signature verification failed");
+		this.name = "WebhookVerificationError";
+	}
+}
+
+/**
+ * Configuration for a webhook capability
+ */
+export interface WebhookConfiguration {
+	/**
+	 * Title of the webhook - shown in the UI when viewing webhooks
+	 */
+	title: string;
+
+	/**
+	 * Description of what this webhook does - shown in the UI
+	 */
+	description: string;
+
+	/**
+	 * The function that executes when the webhook is triggered.
+	 * Receives an array of events (currently always a single event,
+	 * but may be batched in the future).
+	 *
+	 * To signal a verification failure, throw a `WebhookVerificationError`.
+	 * After 5 consecutive verification failures, the platform will
+	 * short-circuit and stop executing the handler.
+	 *
+	 * @param events - The incoming webhook events
+	 * @param context - The capability execution context (Notion client, etc.)
+	 * @returns A promise that resolves when the webhook processing completes
+	 */
+	execute: (
+		events: WebhookEvent[],
+		context: CapabilityContext,
+	) => Promise<void> | void;
+}
+
+export type WebhookCapability = ReturnType<typeof createWebhookCapability>;
+
+export function createWebhookCapability(
+	key: string,
+	config: WebhookConfiguration,
+) {
+	return {
+		_tag: "webhook" as const,
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+		},
+		async handler(
+			events: WebhookEvent[],
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext();
+				await config.execute(events, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				} else {
+					writeOutput({ _tag: "success", value: { status: "success" } });
+				}
+			} catch (err) {
+				const error =
+					err instanceof ExecutionError ? err : new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
+				}
+
+				throw error;
+			}
+		},
+	};
+}

package/src/index.ts

@@ -1,4 +1,20 @@
 export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+export type {
+	AiConnectorArchetype,
+	AiConnectorCapability,
+	AiConnectorChange,
+	AiConnectorChangeUpsert,
+	AiConnectorChatAuthor,
+	AiConnectorChatChannel,
+	AiConnectorChatMessage,
+	AiConnectorChatRecord,
+	AiConnectorConfiguration,
+	AiConnectorExecutionResult,
+	AiConnectorMode,
+	AiConnectorProjectBlock,
+	AiConnectorProjectRecord,
+	AiConnectorRecordByArchetype,
+} from "./capabilities/ai_connector.js";
 export type {
 	AutomationCapability,
 	AutomationConfiguration,
@@ -22,6 +38,12 @@ export type {
 	SyncMode,
 } from "./capabilities/sync.js";
 export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+export type {
+	WebhookCapability,
+	WebhookConfiguration,
+	WebhookEvent,
+} from "./capabilities/webhook.js";
+export { WebhookVerificationError } from "./capabilities/webhook.js";
 export type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
 export type { Infer, SchemaBuilder } from "./schema-builder.js";
 export { getSchema, j } from "./schema-builder.js";

package/src/pacer_internal.ts

@@ -14,6 +14,11 @@ export type PacerState = {
 	pacers: Record<string, PacerEntry>;
 };
 
+export type PacerDeclaration = {
+	readonly key: string;
+	readonly config: { allowedRequests: number; intervalMs: number };
+};
+
 let pacerState: PacerState = { pacers: {} };
 
 export function setPacerState(state: PacerState): void {
@@ -24,6 +29,35 @@ export function getPacerState(): PacerState {
 	return pacerState;
 }
 
+/**
+ * Initialize pacer state from runtime context, falling back to the worker's
+ * own declarations for local execution.
+ * @internal
+ */
+export function initPacerState(
+	runtimePacers: Record<string, PacerEntry> | undefined,
+	declarations?: readonly PacerDeclaration[],
+): void {
+	const pacers = runtimePacers ?? {};
+	if (
+		Object.keys(pacers).length === 0 &&
+		declarations &&
+		declarations.length > 0
+	) {
+		const localPacers: Record<string, PacerEntry> = {};
+		for (const decl of declarations) {
+			localPacers[decl.key] = {
+				lastScheduledAtMs: 0,
+				allowedRequests: decl.config.allowedRequests,
+				intervalMs: decl.config.intervalMs,
+			};
+		}
+		setPacerState({ pacers: localPacers });
+	} else {
+		setPacerState({ pacers });
+	}
+}
+
 /**
  * Core wait logic for pacing API requests.
  * Sleeps if needed to stay under the rate limit.

package/src/schema.ts

@@ -68,10 +68,10 @@ export type PropertyConfiguration =
 	| {
 			type: "relation";
 			/**
-			 * The export name of the sync capability that defines the related database.
-			 * This must match the export name used when defining the related sync capability.
+			 * The key of the related database declaration.
+			 * This must match the key passed to `worker.database()`.
 			 */
-			relatedSyncKey: string;
+			relatedDatabaseKey: string;
 			config: { twoWay: false } | { twoWay: true; relatedPropertyName: string };
 	  };
 
@@ -203,32 +203,49 @@ export function place(): PropertyConfiguration {
 }
 
 /**
- * Creates a relation property definition that references another sync capability.
- * The related database must be defined by a sync capability in the same worker.
+ * Creates a relation property definition that references another database.
+ * The related database must be declared in the same worker.
  *
- * @param relatedSyncKey - The export name of the sync capability that defines the related database.
+ * @param relatedDatabaseKey - The key of the related database declaration.
  * @example
  * ```typescript
- * export const projectsSync = sync({...});
+ * const projects = worker.database("projects", {
+ *   type: "managed",
+ *   initialTitle: "Projects",
+ *   primaryKeyProperty: "Project ID",
+ *   schema: {
+ *     properties: {
+ *       "Project Name": Schema.title(),
+ *       "Project ID": Schema.richText(),
+ *     },
+ *   },
+ * });
  *
- * export const tasksSync = sync({
+ * const tasks = worker.database("tasks", {
+ *   type: "managed",
+ *   initialTitle: "Tasks",
+ *   primaryKeyProperty: "Task ID",
  *   schema: {
  *     properties: {
  *       "Task Title": Schema.title(),
- *       "Project": Schema.relation("projectsSync"),
+ *       "Project": Schema.relation("projects"),
  *     },
  *   },
- *   ...
+ * });
+ *
+ * export const tasksSync = worker.sync("tasksSync", {
+ *   database: tasks,
+ *   execute: async () => ({ changes: [], hasMore: false }),
  * });
  * ```
  */
 export function relation(
-	relatedSyncKey: string,
+	relatedDatabaseKey: string,
 	config?: { twoWay: false } | { twoWay: true; relatedPropertyName: string },
 ): PropertyConfiguration {
 	return {
 		type: "relation",
-		relatedSyncKey,
+		relatedDatabaseKey,
 		config: config ?? { twoWay: false },
 	};
 }