@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/schema-builder.ts

@@ -0,0 +1,193 @@
+/**
+ * Zod-like builder for JSONSchema objects.
+ *
+ * Guarantees output always complies with the model provider constraints
+ * enforced by `json-schema.ts` — all object properties in `required`,
+ * `additionalProperties: false`, no forbidden composition keywords, etc.
+ *
+ * @example
+ * ```ts
+ * import { j } from "@notionhq/workers/alpha/schema-builder";
+ *
+ * const schema = j.object({
+ *   foo: j.enum("a", "b", "c").describe("The foo field"),
+ *   bar: j.string(),
+ *   count: j.number(),
+ *   tags: j.array(j.string()),
+ *   nickname: j.string().nullable(),
+ *   createdAt: j.datetime(),
+ * });
+ * ```
+ */
+
+import type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
+
+const SCHEMA: unique symbol = Symbol("schema");
+
+export interface SchemaBuilder<T> {
+	readonly [SCHEMA]: AnyJSONSchema;
+	/** Set the JSONSchema description field. Chainable. */
+	describe(text: string): SchemaBuilder<T>;
+	/** Wrap in anyOf with null. Chainable. */
+	nullable(): SchemaBuilder<T | null>;
+}
+
+/** Extracts `T` from `SchemaBuilder<T>` (type-level only). */
+export type Infer<S> = S extends SchemaBuilder<infer T> ? T : never;
+
+/** Extract the plain JSONSchema from a builder. */
+export function getSchema<T>(builder: SchemaBuilder<T>): JSONSchema<T> {
+	return builder[SCHEMA] as JSONSchema<T>;
+}
+
+function makeBuilder<T>(schema: AnyJSONSchema): SchemaBuilder<T> {
+	return {
+		[SCHEMA]: schema,
+		describe(text: string) {
+			return makeBuilder<T>({ ...schema, description: text });
+		},
+		nullable() {
+			const { description: desc, ...rest } = schema as unknown as Record<string, unknown>;
+			const inner = desc !== undefined ? (rest as unknown as AnyJSONSchema) : schema;
+			const wrapper: Record<string, unknown> = {
+				anyOf: [inner, { type: "null" }],
+			};
+			if (desc !== undefined) wrapper.description = desc;
+			return makeBuilder<T | null>(wrapper as unknown as AnyJSONSchema);
+		},
+	};
+}
+
+// ---- Primitives ----
+
+export function string(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string" });
+}
+
+export function number(): SchemaBuilder<number> {
+	return makeBuilder<number>({ type: "number" });
+}
+
+export function integer(): SchemaBuilder<number> {
+	return makeBuilder<number>({ type: "integer" });
+}
+
+export function boolean(): SchemaBuilder<boolean> {
+	return makeBuilder<boolean>({ type: "boolean" });
+}
+
+// ---- Enum ----
+
+function enumBuilder<T extends string>(...values: readonly T[]): SchemaBuilder<T>;
+function enumBuilder<T extends number>(...values: readonly T[]): SchemaBuilder<T>;
+function enumBuilder(...values: readonly (string | number)[]): SchemaBuilder<unknown> {
+	const type = typeof values[0] === "string" ? "string" : "number";
+	return makeBuilder({ type, enum: values } as AnyJSONSchema);
+}
+
+export { enumBuilder as enum };
+
+// ---- String format shorthands ----
+
+export function datetime(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "date-time" });
+}
+
+export function date(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "date" });
+}
+
+export function time(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "time" });
+}
+
+export function duration(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "duration" });
+}
+
+export function email(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "email" });
+}
+
+export function hostname(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "hostname" });
+}
+
+export function ipv4(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "ipv4" });
+}
+
+export function ipv6(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "ipv6" });
+}
+
+export function uuid(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "uuid" });
+}
+
+// ---- Composites ----
+
+export function array<T>(
+	items: SchemaBuilder<T>,
+	options?: { minItems?: 0 | 1 },
+): SchemaBuilder<T[]> {
+	const schema: Record<string, unknown> = {
+		type: "array",
+		items: getSchema(items),
+	};
+	if (options?.minItems !== undefined) schema.minItems = options.minItems;
+	return makeBuilder<T[]>(schema as unknown as AnyJSONSchema);
+}
+
+export function object<P extends Record<string, SchemaBuilder<unknown>>>(
+	properties: P,
+): SchemaBuilder<{ [K in keyof P]: Infer<P[K]> }> {
+	const schemaProps: Record<string, AnyJSONSchema> = {};
+	const keys = Object.keys(properties);
+	for (const key of keys) {
+		schemaProps[key] = getSchema(properties[key]!);
+	}
+	return makeBuilder({
+		type: "object",
+		properties: schemaProps,
+		required: keys,
+		additionalProperties: false,
+	} as AnyJSONSchema);
+}
+
+export function anyOf<S extends SchemaBuilder<unknown>[]>(
+	...schemas: S
+): SchemaBuilder<Infer<S[number]>> {
+	return makeBuilder({
+		anyOf: schemas.map(getSchema),
+	} as AnyJSONSchema);
+}
+
+// ---- Reference ----
+
+export function ref(path: string): SchemaBuilder<unknown> {
+	return makeBuilder({ $ref: path });
+}
+
+// ---- Namespace export ----
+
+export const j = {
+	string,
+	number,
+	integer,
+	boolean,
+	enum: enumBuilder,
+	datetime,
+	date,
+	time,
+	duration,
+	email,
+	hostname,
+	ipv4,
+	ipv6,
+	uuid,
+	array,
+	object,
+	anyOf,
+	ref,
+};

package/src/alpha/schema.ts

@@ -0,0 +1,222 @@
+import type { Database } from "./database.js";
+import type { DateFormat, Icon, NumberFormat, SelectOption, StatusGroup } from "./types.js";
+
+/**
+ * A schema defining the structure of a single property in a data source.
+ */
+export type PropertyConfiguration =
+	| { type: "title" }
+	| { type: "text" }
+	| { type: "url" }
+	| { type: "email" }
+	| { type: "phone_number" }
+	| { type: "checkbox" }
+	| { type: "file" }
+	| {
+			type: "number";
+			format?: NumberFormat;
+	  }
+	| {
+			type: "date";
+			date_format?: DateFormat;
+	  }
+	| {
+			type: "select";
+			options: SelectOption[];
+	  }
+	| {
+			type: "multi_select";
+			options: SelectOption[];
+	  }
+	| {
+			type: "status";
+			groups: StatusGroup[];
+	  }
+	| { type: "people" }
+	| { type: "place" }
+	| {
+			type: "relation";
+			/**
+			 * The related database, referenced by identity. It must be declared
+			 * under `src/databases/`; the build resolves the reference to the
+			 * database's key when emitting the manifest.
+			 */
+			database: Database;
+			config: { twoWay: false } | { twoWay: true; relatedPropertyName: string };
+	  };
+
+/**
+ * The property definitions for a database, keyed by property name.
+ */
+export type PropertySchema = Record<string, PropertyConfiguration>;
+
+/**
+ * A database schema.
+ */
+export type Schema<S extends PropertySchema = PropertySchema> = {
+	/**
+	 * Optional icon to use as the icon for the database page.
+	 * If not provided, defaults to 📋.
+	 */
+	databaseIcon?: Icon;
+	properties: S;
+	/**
+	 * Optional configuration for sub-item relations.
+	 * If provided, the parent and child properties must be part of a two-way self-relation.
+	 */
+	subItems?: {
+		parentPropertyName: string;
+		childPropertyName: string;
+	};
+};
+
+/**
+ * Builders for property definitions in a database schema.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "@notionhq/workers/alpha/schema";
+ *
+ * const schema = {
+ *   properties: {
+ *     "Task Name": Schema.title(),
+ *     "Task ID": Schema.richText(),
+ *     Status: Schema.select([
+ *       { name: "Open", color: "default" },
+ *       { name: "Done", color: "green" },
+ *     ]),
+ *   },
+ * };
+ * ```
+ */
+export const Schema = {
+	/**
+	 * Creates a title property definition.
+	 */
+	title(): PropertyConfiguration {
+		return { type: "title" };
+	},
+
+	/**
+	 * Creates a rich text property definition.
+	 */
+	richText(): PropertyConfiguration {
+		return { type: "text" };
+	},
+
+	/**
+	 * Creates a URL property definition.
+	 */
+	url(): PropertyConfiguration {
+		return { type: "url" };
+	},
+
+	/**
+	 * Creates an email property definition.
+	 */
+	email(): PropertyConfiguration {
+		return { type: "email" };
+	},
+
+	/**
+	 * Creates a phone number property definition.
+	 */
+	phoneNumber(): PropertyConfiguration {
+		return { type: "phone_number" };
+	},
+
+	/**
+	 * Creates a checkbox property definition.
+	 */
+	checkbox(): PropertyConfiguration {
+		return { type: "checkbox" };
+	},
+
+	/**
+	 * Creates a file property definition.
+	 */
+	file(): PropertyConfiguration {
+		return { type: "file" };
+	},
+
+	/**
+	 * Creates a number property definition with optional formatting.
+	 */
+	number(format?: NumberFormat): PropertyConfiguration {
+		return format ? { type: "number", format } : { type: "number" };
+	},
+
+	/**
+	 * Creates a date property definition with optional formatting.
+	 */
+	date(date_format?: DateFormat): PropertyConfiguration {
+		return date_format ? { type: "date", date_format } : { type: "date" };
+	},
+
+	/**
+	 * Creates a select property definition with predefined options.
+	 */
+	select(options: SelectOption[]): PropertyConfiguration {
+		return { type: "select", options };
+	},
+
+	/**
+	 * Creates a multi-select property definition with predefined options.
+	 */
+	multiSelect(options: SelectOption[]): PropertyConfiguration {
+		return { type: "multi_select", options };
+	},
+
+	/**
+	 * Creates a status property definition with groups.
+	 */
+	status(config: { groups: StatusGroup[] }): PropertyConfiguration {
+		return { type: "status", groups: config.groups };
+	},
+
+	/**
+	 * Creates a people property definition.
+	 */
+	people(): PropertyConfiguration {
+		return { type: "people" };
+	},
+
+	/**
+	 * Creates a place property definition for storing geographic locations.
+	 */
+	place(): PropertyConfiguration {
+		return { type: "place" };
+	},
+
+	/**
+	 * Creates a relation property definition that references another database.
+	 * The related database must be declared under `src/databases/` and is
+	 * referenced by importing it:
+	 *
+	 * @example
+	 * ```ts
+	 * // src/databases/tasks.ts
+	 * import projects from "./projects.js";
+	 *
+	 * export default createDatabase({
+	 *   type: "managed",
+	 *   primaryKey: "Task ID",
+	 *   schema: {
+	 *     properties: {
+	 *       Title: Schema.title(),
+	 *       "Task ID": Schema.richText(),
+	 *       Project: Schema.relation(projects),
+	 *     },
+	 *   },
+	 * });
+	 * ```
+	 */
+	relation(
+		// `Database<any>` so a database with any concrete schema is accepted;
+		// `keyof S` in the config makes `Database` invariant in its schema.
+		database: Database<any>,
+		config?: { twoWay: false } | { twoWay: true; relatedPropertyName: string },
+	): PropertyConfiguration {
+		return { type: "relation", database, config: config ?? { twoWay: false } };
+	},
+};

package/src/alpha/sync.test.ts

@@ -0,0 +1,191 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+
+import { createDatabase } from "./database.js";
+import { ExecutionError, RateLimitError } from "./error.js";
+import { createPacer } from "./pacer.js";
+import { createSync } from "./sync.js";
+
+const database = createDatabase("tasks", {
+	type: "managed",
+	primaryKey: "ID",
+	schema: { properties: { ID: { type: "text" } } },
+});
+
+let stdoutSpy: Mock<typeof process.stdout.write>;
+
+beforeEach(() => {
+	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+	stdoutSpy.mockRestore();
+});
+
+describe("createSync", () => {
+	it("returns a tagged capability with normalized config", () => {
+		const sync = createSync({
+			database,
+			mode: "replace",
+			schedule: "1h",
+			handler: async () => ({ changes: [] }),
+		});
+
+		expect(sync._tag).toBe("sync");
+		expect(sync.config).toEqual({
+			database,
+			mode: "replace",
+			schedule: { type: "interval", intervalMs: 60 * 60 * 1000 },
+		});
+		expect(sync.config.database).toBe(database);
+	});
+
+	it("rejects invalid schedules at creation time", () => {
+		expect(() =>
+			createSync({
+				database,
+				schedule: "30d",
+				handler: async () => ({ changes: [] }),
+			}),
+		).toThrow(/at most 7 days/);
+	});
+});
+
+describe("sync handler", () => {
+	it("writes a success envelope and returns the run result", async () => {
+		const sync = createSync({
+			database,
+			handler: async () => ({
+				changes: [{ type: "upsert", key: "1", properties: { ID: [["1"]] } }],
+			}),
+		});
+
+		const result = await sync.handler();
+
+		expect(result).toEqual({
+			changes: [
+				{ type: "upsert", key: "1", properties: { ID: [["1"]] }, targetDatabaseKey: "tasks" },
+			],
+			hasMore: false,
+			nextUserContext: undefined,
+			nextPacerStates: {},
+		});
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"success","value":{"changes":[{"type":"upsert","key":"1","properties":{"ID":[["1"]]},"targetDatabaseKey":"tasks"}],"hasMore":false,"nextPacerStates":{}}}</__notion_output__>\n`,
+		);
+	});
+
+	it("passes state (or legacy userContext) and the context to the user handler", async () => {
+		const handler = vi.fn(async (_state: unknown, _context: { notion: unknown }) => ({
+			changes: [],
+		}));
+		const sync = createSync({ database, handler });
+
+		await sync.handler({ state: { cursor: "abc" } });
+		expect(handler).toHaveBeenLastCalledWith({ cursor: "abc" }, expect.anything());
+
+		await sync.handler({ userContext: { cursor: "legacy" } });
+		expect(handler).toHaveBeenLastCalledWith({ cursor: "legacy" }, expect.anything());
+
+		// The context carries the Notion client.
+		expect(handler.mock.lastCall?.[1]?.notion).toBeDefined();
+	});
+
+	it("threads nextState and hasMore through to the run result", async () => {
+		const sync = createSync({
+			database,
+			handler: async () => ({ changes: [], hasMore: true, nextState: { cursor: "next" } }),
+		});
+
+		const result = await sync.handler(undefined, { concreteOutput: true });
+		expect(result.hasMore).toBe(true);
+		expect(result.nextUserContext).toEqual({ cursor: "next" });
+	});
+
+	it("types pagination state end to end", async () => {
+		const sync = createSync({
+			database,
+			// State is inferred as { cursor: string } from the handler.
+			handler: async (state: { cursor: string } | undefined) => ({
+				changes: [],
+				hasMore: state === undefined,
+				nextState: { cursor: `${state?.cursor ?? ""}x` },
+			}),
+		});
+
+		const result = await sync.handler({ state: { cursor: "a" } }, { concreteOutput: true });
+		expect(result.nextUserContext).toEqual({ cursor: "ax" });
+	});
+
+	it("threads pacer state from the runtime context to nextPacerStates", async () => {
+		const pacer = createPacer("sync-test-pacer", { allowedRequests: 10, intervalMs: 1000 });
+		const sync = createSync({
+			database,
+			handler: async () => {
+				await pacer.wait();
+				return { changes: [] };
+			},
+		});
+
+		const result = await sync.handler(
+			{ pacers: { [pacer.name]: { lastScheduledAtMs: 0, allowedRequests: 5, intervalMs: 500 } } },
+			{ concreteOutput: true },
+		);
+
+		// The run reports back the apportioned entry with an updated schedule.
+		expect(result.nextPacerStates[pacer.name]).toMatchObject({
+			allowedRequests: 5,
+			intervalMs: 500,
+		});
+		expect(result.nextPacerStates[pacer.name]?.lastScheduledAtMs).toBeGreaterThan(0);
+	});
+
+	it("skips the envelope under concreteOutput", async () => {
+		const sync = createSync({
+			database,
+			handler: async () => ({ changes: [] }),
+		});
+
+		await sync.handler(undefined, { concreteOutput: true });
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("writes a rate_limit envelope and rethrows RateLimitError", async () => {
+		const sync = createSync({
+			database,
+			handler: async () => {
+				throw new RateLimitError({ retryAfter: 30 });
+			},
+		});
+
+		await expect(sync.handler()).rejects.toBeInstanceOf(RateLimitError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"error","error":{"_tag":"rate_limit","name":"RateLimitError","message":"Error during worker execution: Rate limited by external API","retryAfter":30}}</__notion_output__>\n`,
+		);
+	});
+
+	it("writes a generic error envelope and throws ExecutionError", async () => {
+		const sync = createSync({
+			database,
+			handler: async () => {
+				throw new Error("boom");
+			},
+		});
+
+		await expect(sync.handler()).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"error","error":{"_tag":"generic","name":"ExecutionError","message":"Error during worker execution: Error: boom"}}</__notion_output__>\n`,
+		);
+	});
+});
+
+describe("createDatabase", () => {
+	it("rejects empty names", () => {
+		expect(() =>
+			createDatabase("", {
+				type: "managed",
+				primaryKey: "ID",
+				schema: { properties: { ID: { type: "text" } } },
+			}),
+		).toThrow(/non-empty string/);
+	});
+});