@notionhq/workers 0.1.0 → 0.3.0

package/src/capabilities/sync.test.ts

@@ -9,7 +9,9 @@ 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";
 
 describe("Worker.sync", () => {
@@ -27,34 +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",
-				config: { twoWay: false },
-			});
-		});
-
-		it("can be used in a schema definition", () => {
-			const capability = createSyncCapability("tasksSync", {
-				primaryKeyProperty: "Task ID",
-				schema: {
-					defaultName: "Tasks",
-					properties: {
-						"Task ID": Schema.title(),
-						Project: Schema.relation("projectsSync"),
-					},
-				},
-				execute: async () => ({
-					changes: [],
-					hasMore: false,
-				}),
-			});
-
-			expect(capability.config.schema.properties.Project).toEqual({
-				type: "relation",
-				relatedSyncKey: "projectsSync",
+				relatedDatabaseKey: "projects",
 				config: { twoWay: false },
 			});
 		});
@@ -82,15 +61,21 @@ describe("Worker.sync", () => {
 
 	describe("SyncedObject with relation properties", () => {
 		it("allows relation values in synced objects", async () => {
-			const capability = createSyncCapability("tasksSync", {
+			const worker = new Worker();
+			const tasks = worker.database("tasks", {
+				type: "managed",
+				initialTitle: "Tasks",
 				primaryKeyProperty: "Task ID",
 				schema: {
-					defaultName: "Tasks",
 					properties: {
 						"Task ID": Schema.title(),
-						Project: Schema.relation("projectsSync"),
+						Project: Schema.relation("projects"),
 					},
 				},
+			});
+
+			const capability = createSyncCapability("tasksSync", {
+				database: tasks,
 				execute: async () => ({
 					changes: [
 						{
@@ -117,22 +102,112 @@ describe("Worker.sync", () => {
 				}),
 			});
 
-			// Verify the capability is properly configured
 			expect(capability._tag).toBe("sync");
-			expect(capability.config.primaryKeyProperty).toBe("Task ID");
+			expect(capability.config.databaseKey).toBe("tasks");
+		});
+	});
+
+	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 capability = createSyncCapability("testSync", {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
 				primaryKeyProperty: "ID",
 				schema: {
-					defaultName: "Test",
 					properties: {
 						ID: Schema.title(),
 					},
 				},
+			});
+
+			const capability = createSyncCapability("testSync", {
+				database: db,
 				execute: async () => ({
 					changes: [],
 					hasMore: false,
@@ -142,19 +217,25 @@ describe("Worker.sync", () => {
 			await capability.handler();
 
 			expect(stdoutSpy).toHaveBeenCalledWith(
-				`\n<output>${JSON.stringify({ _tag: "success", value: { changes: [], hasMore: false, nextUserContext: undefined } })}</output>\n`,
+				`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: { changes: [], hasMore: false, nextUserContext: undefined, nextPacerStates: {} } })}</__notion_output__>\n`,
 			);
 		});
 
 		it("wraps error in error envelope", async () => {
-			const capability = createSyncCapability("errorSync", {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
 				primaryKeyProperty: "ID",
 				schema: {
-					defaultName: "Test",
 					properties: {
 						ID: Schema.title(),
 					},
 				},
+			});
+
+			const capability = createSyncCapability("errorSync", {
+				database: db,
 				execute: async () => {
 					throw new Error("sync failed");
 				},
@@ -169,5 +250,67 @@ describe("Worker.sync", () => {
 				expect.stringContaining(`"name":"ExecutionError"`),
 			);
 		});
+
+		it("emits sync output with key and default targetDatabaseKey", async () => {
+			const worker = new Worker();
+			const tasks = worker.database("tasks", {
+				type: "managed",
+				initialTitle: "Tasks",
+				primaryKeyProperty: "Name",
+				schema: {
+					properties: {
+						Name: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("tasksSync", {
+				database: tasks,
+				execute: async () => ({
+					changes: [
+						{
+							type: "upsert" as const,
+							key: "task-1",
+							properties: {
+								Name: Builder.title("Write docs"),
+							},
+						},
+						{
+							type: "delete" as const,
+							key: "task-2",
+						},
+					],
+					hasMore: false,
+				}),
+			});
+
+			await capability.handler();
+
+			expect(stdoutSpy).toHaveBeenCalledWith(
+				`\n<__notion_output__>${JSON.stringify({
+					_tag: "success",
+					value: {
+						changes: [
+							{
+								type: "upsert",
+								key: "task-1",
+								properties: {
+									Name: Builder.title("Write docs"),
+								},
+								targetDatabaseKey: "tasks",
+							},
+							{
+								type: "delete",
+								key: "task-2",
+								targetDatabaseKey: "tasks",
+							},
+						],
+						hasMore: false,
+						nextUserContext: undefined,
+						nextPacerStates: {},
+					},
+				})}</__notion_output__>\n`,
+			);
+		});
 	});
 });

package/src/capabilities/sync.ts

@@ -1,4 +1,9 @@
-import { ExecutionError, unreachable } from "../error.js";
+import { ExecutionError } from "../error.js";
+import {
+	getPacerState,
+	initPacerState,
+	type PacerDeclaration,
+} from "../pacer_internal.js";
 import type {
 	PropertyConfiguration,
 	PropertySchema,
@@ -11,12 +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.
@@ -34,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.
@@ -49,9 +59,13 @@ export type SyncChangeUpsert<
 	type: "upsert";
 	/**
 	 * A unique identifier for this record, used to match against existing pages.
-	 * This value will be stored in the property specified by `primaryKeyProperty`.
 	 */
 	key: string;
+	/**
+	 * The key of the database to write to. If omitted, defaults to
+	 * the database associated with the sync capability.
+	 */
+	targetDatabaseKey?: string;
 	/**
 	 * The property values for this record.
 	 * Keys must match the property names defined in the schema.
@@ -60,6 +74,13 @@ export type SyncChangeUpsert<
 	properties: {
 		[Property in keyof S]: PropertyValueType<S[Property]>;
 	};
+	/**
+	 * When this record was last updated in the upstream system.
+	 * ISO 8601 string (e.g. `"2026-03-19T12:00:00Z"`).
+	 * Used for conflict resolution when multiple syncs write to the same database.
+	 * Recommended, but optional.
+	 */
+	upstreamUpdatedAt?: string;
 	/**
 	 * Optional icon to use as the icon for this row's page.
 	 * Use the `Builder.emojiIcon()`, `Builder.notionIcon()`, or `Builder.imageIcon()` helpers.
@@ -83,9 +104,13 @@ export type SyncChangeDelete = {
 	type: "delete";
 	/**
 	 * The unique identifier of the record to delete.
-	 * Must match the `key` of a previously upserted record.
 	 */
 	key: string;
+	/**
+	 * The key of the database to delete from. If omitted, defaults to
+	 * the database associated with the sync capability.
+	 */
+	targetDatabaseKey?: string;
 };
 
 /**
@@ -123,8 +148,7 @@ export type SyncExecutionResult<PK extends string, State = unknown> = {
 };
 
 /**
- * A configuration object that enables synchronization between a data
- * source and a third-party source.
+ * Configuration for a sync capability that syncs data to a database.
  */
 export type SyncConfiguration<
 	PK extends string,
@@ -132,16 +156,9 @@ export type SyncConfiguration<
 	State = unknown,
 > = {
 	/**
-	 * The property of the data source that maps to a "primary key" in the
-	 * third-party data. This is used to match existing pages to
-	 * records in the third-party service. Must be a property defined in the schema.
+	 * The database to sync data into.
 	 */
-	primaryKeyProperty: PK;
-
-	/**
-	 * The schema defining the structure of properties in the collection.
-	 */
-	schema: S;
+	database: DatabaseHandle<PK, S>;
 
 	/**
 	 * How the sync handles data lifecycle:
@@ -158,6 +175,7 @@ export type SyncConfiguration<
 	/**
 	 * How often the sync should run.
 	 * - "continuous": Run as frequently as the system allows
+	 * - "manual": Only run when explicitly triggered
 	 * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
 	 *
 	 * Minimum interval: 1 minute ("1m")
@@ -191,17 +209,7 @@ 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;
-};
-
-/**
- * Creates a special handler for syncing third-party data to a collection.
+ * Creates a special handler for syncing third-party data to a database.
  *
  * @param syncConfiguration - The configuration for the sync.
  * @returns A handler function that executes the sync function, and passes data
@@ -211,22 +219,31 @@ 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,
 		config: {
-			primaryKeyProperty: syncConfiguration.primaryKeyProperty,
-			schema: syncConfiguration.schema,
+			databaseKey: syncConfiguration.database.key,
+			primaryKeyProperty: syncConfiguration.database.config.primaryKeyProperty,
 			mode: syncConfiguration.mode,
-			schedule: parseSchedule(syncConfiguration.schedule),
+			schedule: syncConfiguration.schedule
+				? parseSchedule(syncConfiguration.schedule)
+				: undefined,
 		},
 		async handler(
-			runtimeContext?: RuntimeContext<Context>,
+			runtimeContext?: StatefulRuntimeContext<Context>,
 			options?: HandlerOptions,
 		) {
 			const capabilityContext = createCapabilityContext();
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
+
+			initPacerState(runtimeContext?.pacers, pacerDeclarations);
+
 			let executionResult: SyncExecutionResult<PK, Context>;
 			try {
 				executionResult = await syncConfiguration.execute(
@@ -236,88 +253,34 @@ export function createSyncCapability<
 			} catch (err) {
 				const error = new ExecutionError(err);
 				if (!options?.concreteOutput) {
-					process.stdout.write(
-						`\n<output>${JSON.stringify({ _tag: "error", error: { name: error.name, message: error.message } })}</output>\n`,
-					);
+					writeOutput({
+						_tag: "error",
+						error: { name: error.name, message: error.message },
+					});
 				}
 				throw error;
 			}
 
+			const changes = executionResult.changes.map((change) => ({
+				...change,
+				targetDatabaseKey:
+					change.targetDatabaseKey ?? syncConfiguration.database.key,
+			}));
+
 			const result = {
-				changes: executionResult.changes,
+				changes,
 				hasMore: executionResult.hasMore,
 				nextUserContext: executionResult.nextState,
+				nextPacerStates: getPacerState().pacers,
 			};
 
 			if (options?.concreteOutput) {
 				return result;
 			} else {
-				process.stdout.write(
-					`\n<output>${JSON.stringify({ _tag: "success", value: result })}</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
-
-const DEFAULT_INTERVAL_MS = 30 * MS_PER_MINUTE; // 30m
-
-/**
- * Parses a user-friendly schedule string into the normalized backend format.
- */
-function parseSchedule(schedule: Schedule | undefined): SyncSchedule {
-	if (schedule === "continuous") {
-		return { type: "continuous" };
-	}
-
-	if (!schedule) {
-		return { type: "interval", intervalMs: DEFAULT_INTERVAL_MS };
-	}
-
-	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.test.ts

@@ -41,7 +41,7 @@ describe("Worker.tool", () => {
 		expect(result).toEqual({ _tag: "success", value: "Hello, Alice!" });
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
-			`\n<output>{"_tag":"success","value":"Hello, Alice!"}</output>\n`,
+			`\n<__notion_output__>{"_tag":"success","value":"Hello, Alice!"}</__notion_output__>\n`,
 		);
 	});
 
@@ -68,7 +68,7 @@ describe("Worker.tool", () => {
 		});
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
-			`\n<output>{"_tag":"success","value":{"data":"Data for ID 42"}}</output>\n`,
+			`\n<__notion_output__>{"_tag":"success","value":{"data":"Data for ID 42"}}</__notion_output__>\n`,
 		);
 	});
 
@@ -125,7 +125,7 @@ describe("Worker.tool", () => {
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			expect.stringContaining(
-				`\n<output>{"_tag":"error","error":{"name":"InvalidToolInputError"`,
+				`\n<__notion_output__>{"_tag":"error","error":{"name":"InvalidToolInputError"`,
 			),
 		);
 	});
@@ -161,6 +161,50 @@ describe("Worker.tool", () => {
 		);
 	});
 
+	it("accepts schema with format string types (date, datetime, etc.)", () => {
+		const capability = createToolCapability<
+			{ due: string; createdAt: string },
+			string
+		>("dateFormats", {
+			title: "Date Formats",
+			description: "Uses date and datetime format strings",
+			schema: j.object({
+				due: j.date(),
+				createdAt: j.datetime(),
+			}),
+			execute: ({ due, createdAt }) => `${due} ${createdAt}`,
+		});
+
+		expect(capability.config.schema).toBeDefined();
+	});
+
+	it("rejects invalid date-time format at runtime", async () => {
+		const capability = createToolCapability<{ ts: string }, string>(
+			"datetimeValidation",
+			{
+				title: "Datetime Validation",
+				description: "Validates datetime input",
+				schema: j.object({
+					ts: j.datetime(),
+				}),
+				execute: ({ ts }) => ts,
+			},
+		);
+
+		const valid = await capability.handler({ ts: "2024-01-01T00:00:00Z" });
+		expect(valid).toEqual({
+			_tag: "success",
+			value: "2024-01-01T00:00:00Z",
+		});
+
+		const invalid = (await capability.handler({ ts: "not-a-date" })) as {
+			_tag: "error";
+			error: { name: string; message: string };
+		};
+		expect(invalid._tag).toBe("error");
+		expect(invalid.error.name).toBe("InvalidToolInputError");
+	});
+
 	it("accepts schema with nullable (string | null) properties", () => {
 		const capability = createToolCapability<
 			{ name: string; nickname: string | null },

package/src/capabilities/tool.ts

@@ -1,10 +1,12 @@
 import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
 import type { AnyJSONSchema } from "../json-schema.js";
 import type { SchemaBuilder } from "../schema-builder.js";
 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`
@@ -160,6 +162,7 @@ export function createToolCapability<
 	}
 
 	const ajv = new Ajv();
+	addFormats(ajv);
 	const validateInput = ajv.compile(inputSchema);
 	const validateOutput = outputSchema ? ajv.compile(outputSchema) : null;
 
@@ -209,7 +212,7 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+			writeOutput(result);
 
 			return result;
 		}
@@ -235,7 +238,7 @@ export function createToolCapability<
 					},
 				};
 
-				process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+				writeOutput(result);
 
 				return result;
 			}
@@ -244,9 +247,7 @@ export function createToolCapability<
 				return result;
 			}
 
-			process.stdout.write(
-				`\n<output>${JSON.stringify({ _tag: "success", value: result })}</output>\n`,
-			);
+			writeOutput({ _tag: "success", value: result });
 
 			return {
 				_tag: "success" as const,
@@ -266,7 +267,7 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+			writeOutput(result);
 
 			return result;
 		}