@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/json-schema.ts

@@ -0,0 +1,180 @@
+/**
+ * JSON Schema types compatible with both Anthropic and OpenAI structured
+ * output APIs.
+ *
+ * Constraints enforced by this type (intersection of both providers):
+ * - Objects must have `additionalProperties: false`
+ * - All object properties should be listed in `required`
+ *   (use `anyOf` with `null` for optional fields)
+ * - No recursive schemas
+ * - No `allOf`, `not`, `if/then/else`
+ * - No string constraints (`minLength`, `maxLength`, `pattern`)
+ * - No number constraints (`minimum`, `maximum`, `multipleOf`)
+ * - Array `minItems` limited to 0 or 1; no `maxItems`
+ * - String `format` limited to: date-time, time, date, duration,
+ *   email, hostname, ipv4, ipv6, uuid
+ * - `$ref` and `$defs` supported (no external refs)
+ */
+
+/**
+ * String formats supported by both Anthropic and OpenAI structured outputs.
+ */
+export type JSONSchemaStringFormat =
+	| "date-time"
+	| "time"
+	| "date"
+	| "duration"
+	| "email"
+	| "hostname"
+	| "ipv4"
+	| "ipv6"
+	| "uuid";
+
+// ---- Unsupported composition keywords ----
+// Explicitly typed as `never` on concrete schema defs to produce clear
+// errors when someone accidentally adds them.
+
+interface ForbiddenCompositionKeywords {
+	anyOf?: never;
+	allOf?: never;
+	not?: never;
+	if?: never;
+	then?: never;
+	else?: never;
+}
+
+// ---- Individual schema definitions ----
+
+export interface JSONSchemaStringDef<
+	T extends string = string,
+> extends ForbiddenCompositionKeywords {
+	type: "string";
+	description?: string;
+	format?: JSONSchemaStringFormat;
+	enum?: readonly T[];
+}
+
+export interface JSONSchemaNumberDef<
+	T extends number = number,
+> extends ForbiddenCompositionKeywords {
+	type: "number" | "integer";
+	description?: string;
+	enum?: readonly T[];
+}
+
+export interface JSONSchemaBooleanDef extends ForbiddenCompositionKeywords {
+	type: "boolean";
+	description?: string;
+}
+
+export interface JSONSchemaNullDef extends ForbiddenCompositionKeywords {
+	type: "null";
+	description?: string;
+}
+
+export interface JSONSchemaArrayDef<E = unknown> extends ForbiddenCompositionKeywords {
+	type: "array";
+	description?: string;
+	items: JSONSchema<E>;
+	minItems?: 0 | 1;
+}
+
+export interface JSONSchemaObjectDef<
+	T extends Record<string, unknown> = Record<string, unknown>,
+> extends ForbiddenCompositionKeywords {
+	type: "object";
+	description?: string;
+	properties: { [K in keyof T]-?: JSONSchema<T[K]> };
+	required: readonly (keyof T & string)[];
+	additionalProperties: false;
+	$defs?: Record<string, AnyJSONSchema>;
+}
+
+export interface JSONSchemaRefDef extends ForbiddenCompositionKeywords {
+	$ref: string;
+	description?: string;
+}
+
+// Note: JSONSchemaAnyOfDef intentionally does NOT extend
+// ForbiddenCompositionKeywords — it IS the composition keyword.
+export interface JSONSchemaAnyOfDef<T = unknown> {
+	anyOf: readonly JSONSchema<T>[];
+	description?: string;
+}
+
+// ---- Unconstrained schema (when T is unknown) ----
+
+export type AnyJSONSchema =
+	| JSONSchemaStringDef
+	| JSONSchemaNumberDef
+	| JSONSchemaBooleanDef
+	| JSONSchemaNullDef
+	| JSONSchemaArrayDef
+	| JSONSchemaObjectDef
+	| JSONSchemaRefDef
+	| JSONSchemaAnyOfDef;
+
+// ---- Internal type resolution ----
+
+/**
+ * Maps a TypeScript type T to its corresponding JSON Schema definition.
+ *
+ * Uses `[T] extends [X]` (non-distributing) so that union types like
+ * `string | number` fall through to `AnyJSONSchema` instead of distributing
+ * into `JSONSchemaStringDef | JSONSchemaNumberDef`.
+ *
+ * The `T & X` intersections (e.g. `T & string`) satisfy the generic
+ * constraints on each def without widening T.
+ *
+ * A `$ref` is always valid in any schema position, so `JSONSchemaRefDef`
+ * is unioned in at the end.
+ */
+type JSONSchemaFor<T> =
+	| JSONSchemaRefDef
+	| ([T] extends [string]
+			? JSONSchemaStringDef<T & string>
+			: [T] extends [number]
+				? JSONSchemaNumberDef<T & number>
+				: [T] extends [boolean]
+					? JSONSchemaBooleanDef
+					: [T] extends [readonly (infer E)[]]
+						? JSONSchemaArrayDef<E>
+						: [T] extends [Record<string, unknown>]
+							? JSONSchemaObjectDef<T & Record<string, unknown>>
+							: AnyJSONSchema);
+
+/**
+ * Wraps a non-null schema in an `anyOf` with `{ type: "null" }` for
+ * nullable types (e.g. `string | null`).
+ */
+type JSONSchemaNullable<T> = {
+	anyOf: readonly [JSONSchemaFor<T>, JSONSchemaNullDef];
+	description?: string;
+};
+
+// ---- Main exported type ----
+
+/**
+ * A JSON Schema definition compatible with both Anthropic and OpenAI
+ * structured output APIs.
+ *
+ * When the generic parameter `T` is provided, the schema structure is
+ * constrained at compile time to match `T`:
+ *
+ * ```ts
+ * // Schema is checked against the type:
+ * const schema: JSONSchema<{ name: string }> = {
+ *   type: "object",
+ *   properties: { name: { type: "string" } },
+ *   required: ["name"],
+ *   additionalProperties: false,
+ * };
+ * ```
+ *
+ * @template T - The TypeScript type the schema should describe.
+ */
+export type JSONSchema<T = unknown> = unknown extends T
+	? AnyJSONSchema
+	: null extends T
+		? JSONSchemaNullable<NonNullable<T>>
+		: JSONSchemaFor<T>;

package/src/alpha/manifest.ts

@@ -0,0 +1,47 @@
+/**
+ * A capability type identifier (e.g. "sync", "tool"). The set of types the
+ * build tool can discover is defined by `CAPABILITY_TYPES` in the CLI; the
+ * manifest treats the type as an opaque string.
+ */
+export type CapabilityType = string;
+
+/**
+ * One capability in the manifest: its type, its key (derived from its
+ * filename), and its handler-free configuration.
+ */
+export type CapabilityManifestEntry = {
+	type: CapabilityType;
+	key: string;
+	config: unknown;
+};
+
+/**
+ * One database in the manifest: its key (derived from its filename under
+ * `src/databases/`, or from the owning sync's key for inline databases)
+ * and its configuration, with `relation` properties resolved to
+ * `relatedDatabaseKey` references.
+ */
+export type DatabaseManifestEntry = {
+	key: string;
+	config: unknown;
+};
+
+/**
+ * One pacer in the manifest: its stable name and its rate-limit config.
+ */
+export type PacerManifestEntry = {
+	key: string;
+	config: unknown;
+};
+
+/**
+ * The full worker manifest, emitted by `notion-workers build` as
+ * `dist/manifest.json` and read by the platform at deploy time. This is a
+ * complete, static description of the worker.
+ */
+export type WorkerManifest = {
+	sdkVersion: string;
+	databases: DatabaseManifestEntry[];
+	pacers: PacerManifestEntry[];
+	capabilities: CapabilityManifestEntry[];
+};

package/src/alpha/output.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes a notion_output envelope to stdout using the shared wire format.
+ * The platform runner scans a run's log stream for this envelope to
+ * recover the capability's result.
+ */
+export function writeOutput(value: unknown): void {
+	process.stdout.write(`\n<__notion_output__>${JSON.stringify(value)}</__notion_output__>\n`);
+}

package/src/alpha/pacer.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createPacer, initPacerState, pacerStates } from "./pacer.js";
+
+let pacerCount = 0;
+
+/** Each test gets a uniquely named pacer; the creation registry is global. */
+function testPacer(config = { allowedRequests: 2, intervalMs: 1000 }) {
+	return createPacer(`test-pacer-${pacerCount++}`, config);
+}
+
+beforeEach(() => {
+	vi.useFakeTimers();
+	initPacerState(undefined);
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe("pacer wait", () => {
+	it("spaces requests evenly over the interval window", async () => {
+		const pacer = testPacer({ allowedRequests: 2, intervalMs: 1000 });
+
+		// First wait: nothing scheduled yet, proceeds immediately.
+		await pacer.wait();
+
+		// Second wait: must be paced 500ms (1000ms / 2 requests) after the first.
+		let resolved = false;
+		const second = pacer.wait().then(() => {
+			resolved = true;
+		});
+
+		await vi.advanceTimersByTimeAsync(499);
+		expect(resolved).toBe(false);
+		await vi.advanceTimersByTimeAsync(1);
+		await second;
+		expect(resolved).toBe(true);
+	});
+
+	it("paces against server-provided (apportioned) state over declared config", async () => {
+		const pacer = testPacer({ allowedRequests: 10, intervalMs: 1000 });
+
+		// The server apportioned this pacer down to 1 request per second and
+		// says a request was just scheduled.
+		initPacerState({
+			[pacer.name]: {
+				lastScheduledAtMs: Date.now(),
+				allowedRequests: 1,
+				intervalMs: 1000,
+			},
+		});
+
+		let resolved = false;
+		const wait = pacer.wait().then(() => {
+			resolved = true;
+		});
+
+		// Declared config would allow a request after 100ms; apportioned
+		// state requires the full 1000ms.
+		await vi.advanceTimersByTimeAsync(999);
+		expect(resolved).toBe(false);
+		await vi.advanceTimersByTimeAsync(1);
+		await wait;
+		expect(resolved).toBe(true);
+	});
+
+	it("reports updated state for the platform to persist", async () => {
+		const pacer = testPacer({ allowedRequests: 2, intervalMs: 1000 });
+
+		await pacer.wait();
+
+		expect(pacerStates()).toEqual({
+			[pacer.name]: {
+				lastScheduledAtMs: Date.now(),
+				allowedRequests: 2,
+				intervalMs: 1000,
+			},
+		});
+	});
+});

package/src/alpha/pacer.ts

@@ -0,0 +1,181 @@
+/**
+ * Configuration for a pacer that rate-limits requests to an external API.
+ * When multiple syncs share a pacer, the platform apportions the budget
+ * across them.
+ */
+export type PacerConfig = {
+	/** Maximum number of requests allowed per interval. */
+	allowedRequests: number;
+	/** The interval window in milliseconds. */
+	intervalMs: number;
+};
+
+/**
+ * Runtime pacing state for one pacer, as exchanged with the platform: the
+ * server sends entries with the *apportioned* budget (the declared budget
+ * divided across the syncs sharing the pacer), and the SDK returns the
+ * updated entries after a run so the server can persist `lastScheduledAtMs`.
+ * The wire shape matches v1.
+ */
+export type PacerEntry = {
+	lastScheduledAtMs: number;
+	/** Server-provided (apportioned) request budget. */
+	allowedRequests: number;
+	/** Server-provided interval window in milliseconds. */
+	intervalMs: number;
+};
+
+// Pacers register themselves at creation, keyed on globalThis so the
+// registry is shared even if multiple copies of this module are loaded
+// (e.g. the CLI's instance vs. the one the worker bundle resolves).
+const REGISTRY_KEY = Symbol.for("@notionhq/workers/alpha/pacer-registry");
+
+// Per-run pacing state, keyed on globalThis for the same reason.
+const STATE_KEY = Symbol.for("@notionhq/workers/alpha/pacer-state");
+
+function registry(): Map<string, Pacer> {
+	const holder = globalThis as { [REGISTRY_KEY]?: Map<string, Pacer> };
+	holder[REGISTRY_KEY] ??= new Map();
+	return holder[REGISTRY_KEY];
+}
+
+function state(): Map<string, PacerEntry> {
+	const holder = globalThis as { [STATE_KEY]?: Map<string, PacerEntry> };
+	holder[STATE_KEY] ??= new Map();
+	return holder[STATE_KEY];
+}
+
+/**
+ * A pacer as returned by {@link createPacer}.
+ */
+export type Pacer = {
+	_tag: "pacer";
+	name: string;
+	config: PacerConfig;
+	/**
+	 * Wait until a request can proceed under this pacer's rate limit.
+	 * Call this before every API request the pacer covers.
+	 *
+	 * Requests are evenly spaced over the interval window. Inside a sync
+	 * run, pacing continues from the server-provided state (which carries
+	 * the budget apportioned across the syncs sharing this pacer); outside
+	 * one, pacing starts fresh from the declared config.
+	 */
+	wait(): Promise<void>;
+};
+
+/**
+ * Declare a pacer for rate-limiting requests to an external API.
+ *
+ * Like databases, a pacer is a named resource that can live anywhere —
+ * typically in a shared module next to the API client it paces. Unlike
+ * databases, a pacer is not attached to sync config: handlers use as many
+ * pacers as they need by importing them and calling `wait()`. Creating a
+ * pacer registers it, so every pacer in a module the worker imports is
+ * included in the manifest automatically.
+ *
+ * The `name` is the pacer's stable identity across deploys — the platform
+ * uses it to persist pacing state. Two `createPacer(...)` calls sharing a
+ * name fail the build; share one instance via import instead.
+ *
+ * @example
+ * ```ts
+ * // src/lib/jira.ts
+ * import { createPacer } from "@notionhq/workers/alpha/pacer";
+ *
+ * export const jiraPacer = createPacer("jira", {
+ *   allowedRequests: 10,
+ *   intervalMs: 1000,
+ * });
+ *
+ * // src/syncs/issues.ts — inside the handler:
+ * //   await jiraPacer.wait();
+ * //   const issues = await fetchIssues();
+ * ```
+ */
+export function createPacer(name: string, config: PacerConfig): Pacer {
+	if (!name || typeof name !== "string") {
+		throw new Error("Pacer name must be a non-empty string");
+	}
+
+	if (registry().has(name)) {
+		throw new Error(
+			`Two distinct pacers are named "${name}". A name identifies one pacer — ` +
+				`share a single createPacer(...) instance via import instead of declaring it twice`,
+		);
+	}
+
+	const pacer: Pacer = {
+		_tag: "pacer",
+		name,
+		config,
+		async wait(): Promise<void> {
+			// Fall back to the declared (unapportioned) config when the
+			// platform hasn't provided state — local runs, tools.
+			const entry = state().get(name) ?? {
+				lastScheduledAtMs: 0,
+				allowedRequests: config.allowedRequests,
+				intervalMs: config.intervalMs,
+			};
+
+			const paceMs = Math.ceil(entry.intervalMs / entry.allowedRequests);
+			const now = Date.now();
+
+			// Schedule at the later of: (last scheduled + pace) or now.
+			const scheduledAtMs = Math.max(entry.lastScheduledAtMs + paceMs, now);
+			const delayMs = scheduledAtMs - now;
+
+			state().set(name, { ...entry, lastScheduledAtMs: scheduledAtMs });
+
+			if (delayMs > 0) {
+				await new Promise((resolve) => setTimeout(resolve, delayMs));
+			}
+		},
+	};
+
+	registry().set(name, pacer);
+	return pacer;
+}
+
+/**
+ * Initialize per-run pacing state from the platform-provided entries.
+ * Entries carry the apportioned budget; pacers absent from the map pace
+ * against their declared config (see `wait()`).
+ *
+ * @internal Called by capability handlers at the start of a run.
+ */
+export function initPacerState(runtimePacers: Record<string, PacerEntry> | undefined): void {
+	state().clear();
+	for (const [name, entry] of Object.entries(runtimePacers ?? {})) {
+		state().set(name, entry);
+	}
+}
+
+/**
+ * The pacing state accumulated during this run, to report back to the
+ * platform as `nextPacerStates`.
+ *
+ * @internal Called by capability handlers at the end of a run.
+ */
+export function pacerStates(): Record<string, PacerEntry> {
+	return Object.fromEntries(state());
+}
+
+/**
+ * The pacers registered so far, in creation order.
+ *
+ * @internal Used by the build to collect pacers after importing the bundle.
+ */
+export function registeredPacers(): Pacer[] {
+	return Array.from(registry().values());
+}
+
+/**
+ * Clear the pacer registry.
+ *
+ * @internal Used by the build before importing a bundle, so repeated builds
+ * in one process (tests, watch mode) don't see stale registrations.
+ */
+export function clearRegisteredPacers(): void {
+	registry().clear();
+}

package/src/alpha/schedule.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+import { parseSchedule } from "./schedule.js";
+
+describe("parseSchedule", () => {
+	it("parses continuous", () => {
+		expect(parseSchedule("continuous")).toEqual({ type: "continuous" });
+	});
+
+	it("parses manual", () => {
+		expect(parseSchedule("manual")).toEqual({ type: "manual" });
+	});
+
+	it("parses interval strings", () => {
+		expect(parseSchedule("30m")).toEqual({ type: "interval", intervalMs: 30 * 60 * 1000 });
+		expect(parseSchedule("2h")).toEqual({ type: "interval", intervalMs: 2 * 60 * 60 * 1000 });
+		expect(parseSchedule("1d")).toEqual({ type: "interval", intervalMs: 24 * 60 * 60 * 1000 });
+	});
+
+	it("rejects malformed schedules", () => {
+		// @ts-expect-error deliberately malformed
+		expect(() => parseSchedule("5s")).toThrow(/Invalid schedule format/);
+		// @ts-expect-error deliberately malformed
+		expect(() => parseSchedule("daily")).toThrow(/Invalid schedule format/);
+	});
+
+	it("rejects out-of-range intervals", () => {
+		expect(() => parseSchedule("0m")).toThrow(/at least 1 minute/);
+		expect(() => parseSchedule("8d")).toThrow(/at most 7 days/);
+	});
+});

package/src/alpha/schedule.ts

@@ -0,0 +1,53 @@
+import type { NormalizedSchedule, Schedule, TimeUnit } from "./types.js";
+
+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): NormalizedSchedule {
+	if (schedule === "continuous") {
+		return { type: "continuous" };
+	}
+
+	if (schedule === "manual") {
+		return { type: "manual" };
+	}
+
+	const match = schedule.match(/^(\d+)(m|h|d)$/);
+	if (!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;
+	}
+
+	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 };
+}