@notionhq/workers 0.1.0 → 0.2.0

package/src/capabilities/sync.ts

@@ -1,4 +1,9 @@
 import { ExecutionError, unreachable } from "../error.js";
+import {
+	getPacerState,
+	type PacerEntry,
+	setPacerState,
+} from "../pacer_internal.js";
 import type {
 	PropertyConfiguration,
 	PropertySchema,
@@ -15,6 +20,7 @@ import type {
 	TextValue,
 	TimeUnit,
 } from "../types.js";
+import type { DatabaseHandle } from "../worker.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
 
@@ -49,9 +55,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 +70,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 +100,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 +144,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 +152,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 +171,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")
@@ -198,10 +212,12 @@ type RuntimeContext<UserContext = unknown> = {
 	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 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
@@ -216,10 +232,12 @@ export function createSyncCapability<
 		_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>,
@@ -227,6 +245,10 @@ export function createSyncCapability<
 		) {
 			const capabilityContext = createCapabilityContext();
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
+
+			// Initialize pacer state from runtime context
+			setPacerState({ pacers: runtimeContext?.pacers ?? {} });
+
 			let executionResult: SyncExecutionResult<PK, Context>;
 			try {
 				executionResult = await syncConfiguration.execute(
@@ -237,23 +259,30 @@ export function createSyncCapability<
 				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`,
+						`\n<__notion_output__>${JSON.stringify({ _tag: "error", error: { name: error.name, message: error.message } })}</__notion_output__>\n`,
 					);
 				}
 				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`,
+					`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: result })}</__notion_output__>\n`,
 				);
 			}
 
@@ -269,18 +298,16 @@ 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 {
+function parseSchedule(schedule: Schedule): SyncSchedule {
 	if (schedule === "continuous") {
 		return { type: "continuous" };
 	}
 
-	if (!schedule) {
-		return { type: "interval", intervalMs: DEFAULT_INTERVAL_MS };
+	if (schedule === "manual") {
+		return { type: "manual" };
 	}
 
 	const match = schedule.match(/^(\d+)(m|h|d)$/);

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,4 +1,5 @@
 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";
@@ -160,6 +161,7 @@ export function createToolCapability<
 	}
 
 	const ajv = new Ajv();
+	addFormats(ajv);
 	const validateInput = ajv.compile(inputSchema);
 	const validateOutput = outputSchema ? ajv.compile(outputSchema) : null;
 
@@ -209,7 +211,9 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+			process.stdout.write(
+				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
+			);
 
 			return result;
 		}
@@ -235,7 +239,9 @@ export function createToolCapability<
 					},
 				};
 
-				process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+				process.stdout.write(
+					`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
+				);
 
 				return result;
 			}
@@ -245,7 +251,7 @@ export function createToolCapability<
 			}
 
 			process.stdout.write(
-				`\n<output>${JSON.stringify({ _tag: "success", value: result })}</output>\n`,
+				`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: result })}</__notion_output__>\n`,
 			);
 
 			return {
@@ -266,7 +272,9 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+			process.stdout.write(
+				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
+			);
 
 			return result;
 		}

package/src/index.ts

@@ -33,4 +33,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,60 @@
+/**
+ * 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>;
+};
+
+let pacerState: PacerState = { pacers: {} };
+
+export function setPacerState(state: PacerState): void {
+	pacerState = state;
+}
+
+export function getPacerState(): PacerState {
+	return pacerState;
+}
+
+/**
+ * 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,7 +68,7 @@ export type PropertyConfiguration =
 	| {
 			type: "relation";
 			/**
-			 * The export name of the sync capability that defines the related collection.
+			 * 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.
 			 */
 			relatedSyncKey: string;
@@ -76,13 +76,6 @@ export type PropertyConfiguration =
 	  };
 
 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 📋.
@@ -211,9 +204,9 @@ 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.
+ * The related database must be defined by a sync capability in the same worker.
  *
- * @param relatedSyncKey - The export name of the sync capability that defines the related collection.
+ * @param relatedSyncKey - The export name of the sync capability that defines the related database.
  * @example
  * ```typescript
  * export const projectsSync = sync({...});

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 = {