@notionhq/workers 0.2.0 → 0.4.0

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
@@ -104,23 +105,26 @@ export function createAutomationCapability(
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext();
+				const capabilityContext = createCapabilityContext("automation");
 				await config.execute(event, capabilityContext);
 
 				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/context.ts

@@ -1,22 +1,64 @@
 import { Client } from "@notionhq/client";
 import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+import type { CapabilityType } from "../worker.js";
 
 export type CapabilityContext = {
 	/** Notion API SDK client for this execution. */
 	notion: Client;
 };
 
-export function createCapabilityContext(): CapabilityContext {
+const FIX_STEPS =
+	"\n\nTo fix this:\n" +
+	"1. Create an internal integration at https://www.notion.so/profile/integrations/internal\n" +
+	"2. Give the integration access to the relevant pages/databases\n" +
+	"3. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"4. For deployed workers, run: ntn workers env push";
+
+function missingTokenMessage(capabilityType: CapabilityType): string {
+	if (capabilityType === "tool") {
+		return (
+			"NOTION_API_TOKEN is not set. " +
+			"When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, " +
+			"using the permissions of the Custom Agent. " +
+			"Outside of that context (e.g. ntn workers exec), you must set it yourself." +
+			FIX_STEPS
+		);
+	}
+
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		`context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(
+	capabilityType: CapabilityType,
+): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage(capabilityType));
+		},
+	});
+}
+
+export function createCapabilityContext(
+	capabilityType: CapabilityType,
+): CapabilityContext {
 	const options: ClientOptions = {};
 
 	if (process.env.NOTION_API_BASE_URL) {
 		options.baseUrl = process.env.NOTION_API_BASE_URL;
 	}
 
-	if (process.env.NOTION_API_TOKEN) {
-		options.auth = process.env.NOTION_API_TOKEN;
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy(capabilityType) };
 	}
 
+	options.auth = process.env.NOTION_API_TOKEN;
 	const notion = new Client(options);
 
 	return { notion };

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 };
+}

package/src/capabilities/sync.test.ts

@@ -8,7 +8,8 @@ import {
 	vi,
 } from "vitest";
 import * as Builder from "../builder.js";
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } 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();
@@ -165,6 +251,113 @@ describe("Worker.sync", () => {
 			);
 		});
 
+		it("wraps RateLimitError in error envelope with _tag rate_limit", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			expect(stdoutSpy).toHaveBeenCalledWith(
+				expect.stringContaining(`"_tag":"rate_limit"`),
+			);
+			expect(stdoutSpy).toHaveBeenCalledWith(
+				expect.stringContaining(`"name":"RateLimitError"`),
+			);
+		});
+
+		it("includes retryAfter in rate_limit error envelope when provided", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError({ retryAfter: 30 });
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.map((call) => String(call[0]))
+				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
+			const parsed = JSON.parse(
+				output.replace(
+					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
+					"$1",
+				),
+			);
+			expect(parsed).toEqual({
+				_tag: "error",
+				error: {
+					_tag: "rate_limit",
+					name: "RateLimitError",
+					message:
+						"Error during worker execution: Rate limited by external API",
+					retryAfter: 30,
+				},
+			});
+		});
+
+		it("wraps RateLimitError without retryAfter correctly", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.map((call) => String(call[0]))
+				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
+			const parsed = JSON.parse(
+				output.replace(
+					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
+					"$1",
+				),
+			);
+			expect(parsed.error.retryAfter).toBeUndefined();
+		});
+
 		it("emits sync output with key and default targetDatabaseKey", async () => {
 			const worker = new Worker();
 			const tasks = worker.database("tasks", {

package/src/capabilities/sync.ts

@@ -1,8 +1,8 @@
-import { ExecutionError, unreachable } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import {
 	getPacerState,
-	type PacerEntry,
-	setPacerState,
+	initPacerState,
+	type PacerDeclaration,
 } from "../pacer_internal.js";
 import type {
 	PropertyConfiguration,
@@ -16,13 +16,29 @@ 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";
+
+type SyncErrorEnvelope =
+	| { _tag: "error"; error: { _tag: "generic"; name: string; message: string } }
+	| {
+			_tag: "error";
+			error: {
+				_tag: "rate_limit";
+				name: string;
+				message: string;
+				retryAfter?: number;
+			};
+	  };
 
 /**
  * Maps a property configuration to its corresponding value type.
@@ -40,7 +56,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 +220,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 +231,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 +248,13 @@ export function createSyncCapability<
 				: undefined,
 		},
 		async handler(
-			runtimeContext?: RuntimeContext<Context>,
+			runtimeContext?: StatefulRuntimeContext<Context>,
 			options?: HandlerOptions,
 		) {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("sync");
 			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 {
@@ -256,11 +263,35 @@ export function createSyncCapability<
 					capabilityContext,
 				);
 			} catch (err) {
+				if (err instanceof RateLimitError) {
+					if (!options?.concreteOutput) {
+						const envelope: SyncErrorEnvelope = {
+							_tag: "error",
+							error: {
+								_tag: "rate_limit",
+								name: err.name,
+								message: err.message,
+								...(err.retryAfter !== undefined
+									? { retryAfter: err.retryAfter }
+									: {}),
+							},
+						};
+						writeOutput(envelope);
+					}
+					throw 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`,
-					);
+					const envelope: SyncErrorEnvelope = {
+						_tag: "error",
+						error: {
+							_tag: "generic",
+							name: error.name,
+							message: error.message,
+						},
+					};
+					writeOutput(envelope);
 				}
 				throw error;
 			}
@@ -281,70 +312,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 };
-}