@notionhq/workers 0.1.0 → 0.3.0

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";
@@ -33,4 +55,13 @@ export type {
 	PlaceValue,
 	Schedule,
 } from "./types.js";
+export type {
+	DatabaseConfig,
+	DatabaseHandle,
+	ManagedDatabaseConfig,
+	PacerConfig,
+	PacerDeclaration,
+	PacerHandle,
+	WorkerManifest,
+} from "./worker.js";
 export { Worker } from "./worker.js";

package/src/pacer.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getPacerState, pacerWait, setPacerState } from "./pacer_internal.js";
+
+describe("pacerWait", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(0);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("paces requests using server-provided config", async () => {
+		setPacerState({
+			pacers: {
+				api: {
+					lastScheduledAtMs: 0,
+					allowedRequests: 10,
+					intervalMs: 60_000,
+				},
+			},
+		});
+
+		const first = pacerWait("api");
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(6000);
+		await vi.advanceTimersByTimeAsync(6000);
+		await first;
+
+		const second = pacerWait("api");
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(12_000);
+		await vi.advanceTimersByTimeAsync(6000);
+		await second;
+	});
+
+	it("does not wait when the next slot is already in the past", async () => {
+		setPacerState({
+			pacers: {
+				api: {
+					lastScheduledAtMs: 0,
+					allowedRequests: 10,
+					intervalMs: 60_000,
+				},
+			},
+		});
+
+		const first = pacerWait("api");
+		await vi.advanceTimersByTimeAsync(6000);
+		await first;
+
+		vi.advanceTimersByTime(20_000);
+
+		const second = pacerWait("api");
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(26_000);
+		await second;
+	});
+
+	it("works with apportioned (reduced) budget", async () => {
+		// Server apportioned: 5 requests per 10s (original was 10/10s, shared by 2 syncs)
+		setPacerState({
+			pacers: {
+				shared: {
+					lastScheduledAtMs: 0,
+					allowedRequests: 5,
+					intervalMs: 10_000,
+				},
+			},
+		});
+
+		// Pace should be 10_000 / 5 = 2000ms between requests
+		const first = pacerWait("shared");
+		expect(getPacerState().pacers.shared?.lastScheduledAtMs).toBe(2000);
+		await vi.advanceTimersByTimeAsync(2000);
+		await first;
+
+		const second = pacerWait("shared");
+		expect(getPacerState().pacers.shared?.lastScheduledAtMs).toBe(4000);
+		await vi.advanceTimersByTimeAsync(2000);
+		await second;
+	});
+
+	it("throws when pacer key not found in runtime context", async () => {
+		setPacerState({ pacers: {} });
+
+		await expect(pacerWait("unknown")).rejects.toThrow(
+			'Pacer "unknown" not found',
+		);
+	});
+
+	it("preserves allowedRequests and intervalMs across calls", async () => {
+		setPacerState({
+			pacers: {
+				api: {
+					lastScheduledAtMs: 0,
+					allowedRequests: 10,
+					intervalMs: 60_000,
+				},
+			},
+		});
+
+		await vi.advanceTimersByTimeAsync(6000);
+		await pacerWait("api");
+
+		// Config should still be present after wait
+		const entry = getPacerState().pacers.api;
+		expect(entry?.allowedRequests).toBe(10);
+		expect(entry?.intervalMs).toBe(60_000);
+	});
+});

package/src/pacer.ts

@@ -0,0 +1,25 @@
+/**
+ * Pacer module for rate limiting API requests.
+ *
+ * The preferred API is the handle returned by `worker.pacer()`:
+ *
+ * ```ts
+ * const apiPacer = worker.pacer("myApi", { allowedRequests: 10, intervalMs: 1000 });
+ * await apiPacer.wait();
+ * ```
+ *
+ * @module
+ */
+
+import { pacerWait } from "./pacer_internal.js";
+
+export const Pacer = {
+	/**
+	 * Wait until a request can proceed under the named pacer's rate limit.
+	 *
+	 * Prefer using the handle-based API instead: `await myPacer.wait()`.
+	 *
+	 * @param key - The pacer key, matching the key used in `worker.pacer()`.
+	 */
+	wait: pacerWait,
+};

package/src/pacer_internal.ts

@@ -0,0 +1,94 @@
+/**
+ * Internal pacer state helpers used by the runtime.
+ * @internal
+ */
+export type PacerEntry = {
+	lastScheduledAtMs: number;
+	/** Server-provided (apportioned) request budget. */
+	allowedRequests: number;
+	/** Server-provided interval window in milliseconds. */
+	intervalMs: number;
+};
+
+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 {
+	pacerState = state;
+}
+
+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.
+ * @internal
+ */
+export async function pacerWait(key: string): Promise<void> {
+	const state = getPacerState();
+	const entry = state.pacers[key];
+
+	if (!entry) {
+		throw new Error(
+			`Pacer "${key}" not found. Make sure you declared it with worker.pacer("${key}", ...) ` +
+				`and are running inside the worker runtime.`,
+		);
+	}
+
+	const { allowedRequests, intervalMs } = entry;
+	const paceMs = Math.ceil(intervalMs / allowedRequests);
+	const now = Date.now();
+	const lastScheduledAtMs = entry.lastScheduledAtMs;
+
+	// Schedule at the later of: (last scheduled + pace) or now
+	const scheduledAtMs = Math.max(lastScheduledAtMs + paceMs, now);
+	const delayMs = scheduledAtMs - now;
+
+	// Update state with new scheduled timestamp
+	state.pacers[key] = { ...entry, lastScheduledAtMs: scheduledAtMs };
+	setPacerState(state);
+
+	// Sleep if needed
+	if (delayMs > 0) {
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+}

package/src/schema.ts

@@ -68,21 +68,14 @@ export type PropertyConfiguration =
 	| {
 			type: "relation";
 			/**
-			 * The export name of the sync capability that defines the related collection.
-			 * 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 };
 	  };
 
 export type Schema<PK extends string> = {
-	/**
-	 * The default name for the database when it is first created.
-	 *
-	 * Updating this after the database has been created will not change the
-	 * name of the database.
-	 */
-	defaultName: string;
 	/**
 	 * Optional icon to use as the icon for the database page.
 	 * If not provided, defaults to 📋.
@@ -210,32 +203,49 @@ export function place(): PropertyConfiguration {
 }
 
 /**
- * Creates a relation property definition that references another sync capability.
- * The related collection 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 collection.
+ * @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 },
 	};
 }

package/src/types.ts

@@ -236,7 +236,7 @@ export type RelationReference = {
 
 /**
  * Relation value representing references to related records.
- * Each reference identifies a record in the target collection.
+ * Each reference identifies a record in the target database.
  */
 export type RelationValue = RelationReference[];
 
@@ -256,15 +256,17 @@ export type IntervalString = `${number}${TimeUnit}`;
 /**
  * Schedule configuration for sync capabilities.
  * - "continuous": Run as frequently as the system allows
+ * - "manual": Only run when explicitly triggered
  * - IntervalString: Run at specified intervals, e.g. "30m", "1h", "1d"
  */
-export type Schedule = "continuous" | IntervalString;
+export type Schedule = "continuous" | "manual" | IntervalString;
 
 /**
  * Normalized schedule representation stored in the backend.
  */
 export type SyncSchedule =
 	| { type: "continuous" }
+	| { type: "manual" }
 	| { type: "interval"; intervalMs: number };
 
 export type HandlerOptions = {

package/src/worker.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+
+import * as Schema from "./schema.js";
+import { Worker } from "./worker.js";
+
+describe("Worker", () => {
+	it("includes sdkVersion, databases, and capabilities in manifest", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		worker.sync("tasksSync", {
+			database: tasks,
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.sdkVersion).toMatch(/^\d+\.\d+\.\d+/);
+		expect(worker.manifest.databases).toEqual([
+			{
+				key: "tasks",
+				config: {
+					type: "managed",
+					initialTitle: "Tasks",
+					primaryKeyProperty: "Name",
+					schema: {
+						properties: {
+							Name: { type: "title" },
+						},
+					},
+				},
+			},
+		]);
+		expect(worker.manifest.pacers).toEqual([]);
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "sync",
+				key: "tasksSync",
+				config: {
+					databaseKey: "tasks",
+					primaryKeyProperty: "Name",
+					mode: undefined,
+					schedule: undefined,
+				},
+			},
+		]);
+	});
+
+	it("serializes manual schedules in the manifest", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		worker.sync("tasksBackfill", {
+			database: tasks,
+			schedule: "manual",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "sync",
+				key: "tasksBackfill",
+				config: {
+					databaseKey: "tasks",
+					primaryKeyProperty: "Name",
+					mode: undefined,
+					schedule: {
+						type: "manual",
+					},
+				},
+			},
+		]);
+	});
+
+	it("includes pacers in manifest and links to sync capabilities", () => {
+		const worker = new Worker();
+		const tasks = worker.database("tasks", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		const _jiraPacer = worker.pacer("jira", {
+			allowedRequests: 10,
+			intervalMs: 1000,
+		});
+
+		worker.sync("jiraBackfill", {
+			database: tasks,
+			schedule: "manual",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		worker.sync("jiraDelta", {
+			database: tasks,
+			schedule: "5m",
+			execute: async () => ({
+				changes: [],
+				hasMore: false,
+			}),
+		});
+
+		expect(worker.manifest.pacers).toEqual([
+			{
+				key: "jira",
+				config: {
+					allowedRequests: 10,
+					intervalMs: 1000,
+				},
+			},
+		]);
+	});
+
+	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
+		const worker = new Worker();
+		const db = worker.database("shared-key", {
+			type: "managed",
+			initialTitle: "Tasks",
+			primaryKeyProperty: "Name",
+			schema: {
+				properties: {
+					Name: Schema.title(),
+				},
+			},
+		});
+
+		expect(() =>
+			worker.sync("shared-key", {
+				database: db,
+				execute: async () => ({
+					changes: [],
+					hasMore: false,
+				}),
+			}),
+		).toThrow('Worker item with key "shared-key" already registered');
+	});
+});