@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/sync.ts

@@ -0,0 +1,340 @@
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import type { Database } from "./database.js";
+import { ExecutionError, RateLimitError } from "./error.js";
+import { writeOutput } from "./output.js";
+import { initPacerState, pacerStates, type PacerEntry } from "./pacer.js";
+import { parseSchedule } from "./schedule.js";
+import type { PropertyConfiguration, PropertySchema, Schema } from "./schema.js";
+import type {
+	Cover,
+	HandlerOptions,
+	Icon,
+	NormalizedSchedule,
+	PeopleValue,
+	PlaceValue,
+	RelationValue,
+	Schedule,
+	TextValue,
+} from "./types.js";
+
+/**
+ * Maps a property configuration to its corresponding value type.
+ */
+type PropertyValueType<T extends PropertyConfiguration> = T extends {
+	type: "people";
+}
+	? PeopleValue
+	: T extends { type: "place" }
+		? PlaceValue
+		: T extends { type: "relation" }
+			? RelationValue
+			: TextValue;
+
+/**
+ * Sync mode determines how the sync handles data lifecycle.
+ */
+export type SyncMode = "replace" | "incremental";
+
+/**
+ * A change representing a record to be created or updated.
+ */
+export type SyncChangeUpsert<S extends PropertySchema = PropertySchema> = {
+	/** The type of change. Use `"upsert"` to create or update a record. */
+	type: "upsert";
+	/** A unique identifier for this record, used to match against existing pages. */
+	key: string;
+	/**
+	 * The property values for this record.
+	 * Keys must match the property names defined in the schema.
+	 * Use the Builder helpers (e.g. `Builder.title()`, `Builder.richText()`)
+	 * to create values.
+	 */
+	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.
+	 */
+	icon?: Icon;
+	/**
+	 * Optional cover to use as the cover for this row's page.
+	 * Use the `Builder.imageCover()` helper.
+	 */
+	cover?: Cover;
+	/**
+	 * Optional markdown content to add to the page body.
+	 * This will be converted to Notion blocks and added as page content.
+	 */
+	pageContentMarkdown?: string;
+};
+
+/**
+ * A change representing a record to be deleted.
+ * Only applicable when using `mode: "incremental"`.
+ */
+export type SyncChangeDelete = {
+	/** The type of change. Use `"delete"` to remove a record. */
+	type: "delete";
+	/** The unique identifier of the record to delete. */
+	key: string;
+};
+
+/**
+ * A change to be applied to the synced database.
+ */
+export type SyncChange<S extends PropertySchema = PropertySchema> =
+	| SyncChangeUpsert<S>
+	| SyncChangeDelete;
+
+/**
+ * Result returned from a sync handler.
+ */
+export type SyncHandlerResult<S extends PropertySchema = PropertySchema, State = unknown> = {
+	/** The batch of changes to apply in this execution. */
+	changes: SyncChange<S>[];
+	/**
+	 * Indicates whether there is more data to fetch. When `true`, the
+	 * handler is called again with `nextState`.
+	 *
+	 * @default false
+	 */
+	hasMore?: boolean;
+	/**
+	 * Optional state data to pass to the next execution.
+	 * Required if `hasMore` is `true`, ignored otherwise.
+	 * This can be any type of data (cursor, page number, timestamp, etc.);
+	 * the same data is provided as `state` in the next execution.
+	 */
+	nextState?: State;
+};
+
+/**
+ * Configuration passed to {@link createSync}.
+ */
+export type SyncConfiguration<S extends PropertySchema = PropertySchema, State = unknown> = {
+	/**
+	 * The database to sync data into, declared with `createDatabase(...)`.
+	 * Declare it inline for a database private to this sync, or import a
+	 * shared instance that other syncs (and `Schema.relation(...)`) also
+	 * reference.
+	 */
+	database: Database<S>;
+
+	/**
+	 * How the sync handles data lifecycle:
+	 * - "replace": Each run returns the complete dataset; unseen pages are deleted.
+	 * - "incremental": Each run returns changes only; use delete markers to remove pages.
+	 *
+	 * @default "replace"
+	 */
+	mode?: SyncMode;
+
+	/**
+	 * 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"
+	 *
+	 * @default "30m"
+	 */
+	schedule?: Schedule;
+
+	/**
+	 * Fetches the data to sync from the third-party service.
+	 *
+	 * This function can return all data at once, or implement pagination by
+	 * returning a batch of changes with `hasMore: true` and a `nextState`;
+	 * the runtime calls it again with that state until `hasMore` is `false`.
+	 *
+	 * @param state - User-defined state from the previous execution (undefined on first call)
+	 * @param context - Runtime context, including the Notion client
+	 */
+	handler: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<SyncHandlerResult<S, State>>;
+};
+
+/**
+ * The pre-manifest configuration of a sync: everything from
+ * {@link SyncConfiguration} except the handler, with the schedule
+ * normalized for the backend and the database's schema type erased.
+ *
+ * The `database` here is still an object reference; the build resolves it
+ * to the database's *name* when emitting the manifest.
+ */
+export type SyncManifestConfig = {
+	database: {
+		_tag: "database";
+		name: string;
+		config: { type: "managed"; initialTitle?: string; primaryKey: string; schema: Schema };
+	};
+	mode: SyncMode | undefined;
+	schedule: NormalizedSchedule | undefined;
+};
+
+/**
+ * The runtime context the platform passes when invoking a sync.
+ */
+export type SyncRuntimeContext = {
+	/** The user-defined state (cursor, pagination state, etc.). */
+	state?: unknown;
+	/** Legacy field for user-defined state. */
+	userContext?: unknown;
+	/** Pacer state from the server for rate limiting. */
+	pacers?: Record<string, PacerEntry>;
+};
+
+/**
+ * The result a sync run reports to the platform, via the notion_output
+ * envelope on stdout (or directly, under `concreteOutput`). This is the
+ * same wire shape v1 syncs produce.
+ */
+export type SyncRunResult = {
+	changes: (SyncChange & { targetDatabaseKey: string })[];
+	hasMore: boolean;
+	nextUserContext?: unknown;
+	nextPacerStates: Record<string, PacerEntry>;
+};
+
+type SyncErrorEnvelope =
+	| { _tag: "error"; error: { _tag: "generic"; name: string; message: string } }
+	| {
+			_tag: "error";
+			error: { _tag: "rate_limit"; name: string; message: string; retryAfter?: number };
+	  };
+
+/**
+ * A sync capability as returned by {@link createSync}.
+ *
+ * Note that a sync carries no key of its own — the build tool derives the
+ * capability key from the file the sync is default-exported from.
+ */
+export type Sync = {
+	_tag: "sync";
+	config: SyncManifestConfig;
+	handler: (
+		runtimeContext?: SyncRuntimeContext,
+		options?: HandlerOptions,
+	) => Promise<SyncRunResult>;
+};
+
+/**
+ * Create a sync capability.
+ *
+ * Default-export the result from a file directly under `src/syncs/` —
+ * the file's basename becomes the sync's key.
+ *
+ * @example
+ * ```ts
+ * // src/syncs/tasks.ts
+ * import { createDatabase } from "@notionhq/workers/alpha/database";
+ * import { Schema } from "@notionhq/workers/alpha/schema";
+ * import { createSync } from "@notionhq/workers/alpha/sync";
+ *
+ * export default createSync({
+ *   database: createDatabase("tasks", {
+ *     type: "managed",
+ *     primaryKey: "Task ID",
+ *     schema: {
+ *       properties: {
+ *         Title: Schema.title(),
+ *         "Task ID": Schema.richText(),
+ *       },
+ *     },
+ *   }),
+ *   mode: "replace",
+ *   schedule: "24h",
+ *   handler: async () => ({
+ *     changes: [
+ *       {
+ *         type: "upsert",
+ *         key: "1",
+ *         properties: { Title: [["Item 1"]], "Task ID": [["1"]] },
+ *       },
+ *     ],
+ *   }),
+ * });
+ * ```
+ */
+export function createSync<S extends PropertySchema, State = unknown>(
+	configuration: SyncConfiguration<S, State>,
+): Sync {
+	return {
+		_tag: "sync",
+		config: {
+			database: configuration.database,
+			mode: configuration.mode,
+			schedule: configuration.schedule ? parseSchedule(configuration.schedule) : undefined,
+		},
+		async handler(runtimeContext?: SyncRuntimeContext, options?: HandlerOptions) {
+			// The platform guarantees the state it passes back is whatever the
+			// previous run returned as nextState.
+			const state = (runtimeContext?.state ?? runtimeContext?.userContext) as State | undefined;
+
+			initPacerState(runtimeContext?.pacers);
+
+			let handlerResult: SyncHandlerResult<S, State>;
+			try {
+				handlerResult = await configuration.handler(state, createCapabilityContext("sync"));
+			} 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) {
+					const envelope: SyncErrorEnvelope = {
+						_tag: "error",
+						error: {
+							_tag: "generic",
+							name: error.name,
+							message: error.message,
+						},
+					};
+					writeOutput(envelope);
+				}
+				throw error;
+			}
+
+			const changes = handlerResult.changes.map((change) => ({
+				...change,
+				targetDatabaseKey: configuration.database.name,
+			}));
+
+			const result: SyncRunResult = {
+				changes,
+				hasMore: handlerResult.hasMore ?? false,
+				nextUserContext: handlerResult.nextState,
+				nextPacerStates: pacerStates(),
+			};
+
+			if (options?.concreteOutput) {
+				return result;
+			}
+
+			writeOutput({ _tag: "success", value: result });
+			return result;
+		},
+	};
+}

package/src/alpha/tool.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+
+import { j } from "./schema-builder.js";
+import { createTool, InvalidToolInputError, ToolExecutionError } from "./tool.js";
+
+let stdoutSpy: Mock<typeof process.stdout.write>;
+
+beforeEach(() => {
+	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+	stdoutSpy.mockRestore();
+});
+
+const sayHello = createTool({
+	title: "Say Hello",
+	description: "Say hello to the user",
+	schema: j.object({ name: j.string() }),
+	execute: ({ name }) => `Hello, ${name}!`,
+});
+
+describe("createTool", () => {
+	it("is tagged and exposes resolved schemas in config", () => {
+		expect(sayHello._tag).toBe("tool");
+		expect(sayHello.config).toEqual({
+			title: "Say Hello",
+			description: "Say hello to the user",
+			schema: {
+				type: "object",
+				properties: { name: { type: "string" } },
+				required: ["name"],
+				additionalProperties: false,
+			},
+			outputSchema: undefined,
+			hints: undefined,
+		});
+	});
+
+	it("writes a success envelope and returns the tagged result", async () => {
+		const result = await sayHello.handler({ name: "Alice" });
+
+		expect(result).toEqual({ _tag: "success", value: "Hello, Alice!" });
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"success","value":"Hello, Alice!"}</__notion_output__>\n`,
+		);
+	});
+
+	it("returns the raw result under concreteOutput", async () => {
+		const result = await sayHello.handler({ name: "Alice" }, { concreteOutput: true });
+
+		expect(result).toBe("Hello, Alice!");
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("rejects input that does not match the schema", async () => {
+		const result = await sayHello.handler({ name: 42 } as never);
+
+		expect(result).toMatchObject({
+			_tag: "error",
+			error: { name: "InvalidToolInputError" },
+		});
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"name":"InvalidToolInputError"`,
+			),
+		);
+
+		await expect(
+			sayHello.handler({ name: 42 } as never, { concreteOutput: true }),
+		).rejects.toBeInstanceOf(InvalidToolInputError);
+	});
+
+	it("rejects output that does not match the output schema", async () => {
+		const badOutput = createTool({
+			title: "Bad Output",
+			description: "Returns output that fails validation",
+			schema: j.object({ id: j.number() }),
+			outputSchema: j.object({ data: j.string() }),
+			execute: () => ({ data: 42 }) as never,
+		});
+
+		const result = await badOutput.handler({ id: 1 });
+		expect(result).toMatchObject({
+			_tag: "error",
+			error: { name: "InvalidToolOutputError" },
+		});
+
+		// Mirrors v1: under concreteOutput the output-validation throw happens
+		// inside the try block, so it surfaces wrapped in ToolExecutionError.
+		await expect(badOutput.handler({ id: 1 }, { concreteOutput: true })).rejects.toBeInstanceOf(
+			ToolExecutionError,
+		);
+	});
+
+	it("wraps execution failures in ToolExecutionError", async () => {
+		const explodes = createTool({
+			title: "Explodes",
+			description: "Always throws",
+			schema: j.object({}),
+			execute: () => {
+				throw new Error("boom");
+			},
+		});
+
+		const result = await explodes.handler({});
+		expect(result).toMatchObject({
+			_tag: "error",
+			error: { name: "ToolExecutionError", message: "boom" },
+		});
+
+		await expect(explodes.handler({}, { concreteOutput: true })).rejects.toBeInstanceOf(
+			ToolExecutionError,
+		);
+	});
+});