@notionhq/workers 0.4.0 → 0.6.0

package/src/capabilities/sync.test.ts

@@ -1,12 +1,5 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+
 import * as Builder from "../builder.js";
 import { ExecutionError, RateLimitError } from "../error.js";
 import { getPacerState } from "../pacer_internal.js";
@@ -18,9 +11,7 @@ describe("Worker.sync", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
-		stdoutSpy = vi
-			.spyOn(process.stdout, "write")
-			.mockImplementation(() => true);
+		stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 	});
 
 	afterEach(() => {
@@ -47,10 +38,7 @@ describe("Worker.sync", () => {
 		});
 
 		it("can be used to build relation arrays", () => {
-			const value = [
-				Builder.relation("project-123"),
-				Builder.relation("project-456"),
-			];
+			const value = [Builder.relation("project-123"), Builder.relation("project-456")];
 
 			expect(value).toEqual([
 				{ type: "primaryKey", value: "project-123" },
@@ -59,6 +47,34 @@ describe("Worker.sync", () => {
 		});
 	});
 
+	describe("Builder.imageCover", () => {
+		it("creates an image cover with the default position", () => {
+			const value = Builder.imageCover("https://example.com/cover.jpg");
+
+			expect(value).toEqual({
+				type: "image",
+				url: "https://example.com/cover.jpg",
+				position: 0.5,
+			});
+		});
+
+		it("creates an image cover with a custom position", () => {
+			const value = Builder.imageCover("https://example.com/cover.jpg", 0.25);
+
+			expect(value).toEqual({
+				type: "image",
+				url: "https://example.com/cover.jpg",
+				position: 0.25,
+			});
+		});
+
+		it("rejects cover positions outside the supported range", () => {
+			expect(() => Builder.imageCover("https://example.com/cover.jpg", 1.5)).toThrow(
+				"Expected a number between 0 and 1",
+			);
+		});
+	});
+
 	describe("SyncedObject with relation properties", () => {
 		it("allows relation values in synced objects", async () => {
 			const worker = new Worker();
@@ -91,11 +107,44 @@ describe("Worker.sync", () => {
 							key: "task-2",
 							properties: {
 								"Task ID": Builder.title("TASK-002"),
-								Project: [
-									Builder.relation("project-123"),
-									Builder.relation("project-456"),
-								],
+								Project: [Builder.relation("project-123"), Builder.relation("project-456")],
+							},
+						},
+					],
+					hasMore: false,
+				}),
+			});
+
+			expect(capability._tag).toBe("sync");
+			expect(capability.config.databaseKey).toBe("tasks");
+		});
+	});
+
+	describe("SyncedObject with page covers", () => {
+		it("allows cover values in synced objects", async () => {
+			const worker = new Worker();
+			const tasks = worker.database("tasks", {
+				type: "managed",
+				initialTitle: "Tasks",
+				primaryKeyProperty: "Task ID",
+				schema: {
+					properties: {
+						"Task ID": Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("tasksSync", {
+				database: tasks,
+				execute: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "task-1",
+							properties: {
+								"Task ID": Builder.title("TASK-001"),
 							},
+							cover: Builder.imageCover("https://example.com/cover.jpg"),
 						},
 					],
 					hasMore: false,
@@ -243,12 +292,8 @@ describe("Worker.sync", () => {
 
 			await expect(capability.handler()).rejects.toThrow(ExecutionError);
 
-			expect(stdoutSpy).toHaveBeenCalledWith(
-				expect.stringContaining(`"_tag":"error"`),
-			);
-			expect(stdoutSpy).toHaveBeenCalledWith(
-				expect.stringContaining(`"name":"ExecutionError"`),
-			);
+			expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"_tag":"error"`));
+			expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"name":"ExecutionError"`));
 		});
 
 		it("wraps RateLimitError in error envelope with _tag rate_limit", async () => {
@@ -273,12 +318,8 @@ describe("Worker.sync", () => {
 
 			await expect(capability.handler()).rejects.toThrow(RateLimitError);
 
-			expect(stdoutSpy).toHaveBeenCalledWith(
-				expect.stringContaining(`"_tag":"rate_limit"`),
-			);
-			expect(stdoutSpy).toHaveBeenCalledWith(
-				expect.stringContaining(`"name":"RateLimitError"`),
-			);
+			expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"_tag":"rate_limit"`));
+			expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"name":"RateLimitError"`));
 		});
 
 		it("includes retryAfter in rate_limit error envelope when provided", async () => {
@@ -307,18 +348,14 @@ describe("Worker.sync", () => {
 				.map((call) => String(call[0]))
 				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
 			const parsed = JSON.parse(
-				output.replace(
-					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
-					"$1",
-				),
+				output.replace(/\n<__notion_output__>(.*)<\/__notion_output__>\n/, "$1"),
 			);
 			expect(parsed).toEqual({
 				_tag: "error",
 				error: {
 					_tag: "rate_limit",
 					name: "RateLimitError",
-					message:
-						"Error during worker execution: Rate limited by external API",
+					message: "Error during worker execution: Rate limited by external API",
 					retryAfter: 30,
 				},
 			});
@@ -350,10 +387,7 @@ describe("Worker.sync", () => {
 				.map((call) => String(call[0]))
 				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
 			const parsed = JSON.parse(
-				output.replace(
-					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
-					"$1",
-				),
+				output.replace(/\n<__notion_output__>(.*)<\/__notion_output__>\n/, "$1"),
 			);
 			expect(parsed.error.retryAfter).toBeUndefined();
 		});

package/src/capabilities/sync.ts

@@ -1,15 +1,8 @@
 import { ExecutionError, RateLimitError } from "../error.js";
-import {
-	getPacerState,
-	initPacerState,
-	type PacerDeclaration,
-} from "../pacer_internal.js";
-import type {
-	PropertyConfiguration,
-	PropertySchema,
-	Schema,
-} from "../schema.js";
+import { getPacerState, initPacerState, type PacerDeclaration } from "../pacer_internal.js";
+import type { PropertyConfiguration, PropertySchema, Schema } from "../schema.js";
 import type {
+	Cover,
 	HandlerOptions,
 	Icon,
 	PeopleValue,
@@ -61,10 +54,7 @@ export type SyncMode = StatefulCapabilityMode;
 /**
  * A change representing a record to be created or updated.
  */
-export type SyncChangeUpsert<
-	PK extends string,
-	S extends PropertySchema<PK>,
-> = {
+export type SyncChangeUpsert<PK extends string, S extends PropertySchema<PK>> = {
 	/**
 	 * The type of change. Use `"upsert"` to create or update a record.
 	 */
@@ -98,6 +88,11 @@ export type SyncChangeUpsert<
 	 * 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.
@@ -162,11 +157,7 @@ export type SyncExecutionResult<PK extends string, State = unknown> = {
 /**
  * Configuration for a sync capability that syncs data to a database.
  */
-export type SyncConfiguration<
-	PK extends string,
-	S extends Schema<PK>,
-	State = unknown,
-> = {
+export type SyncConfiguration<PK extends string, S extends Schema<PK>, State = unknown> = {
 	/**
 	 * The database to sync data into.
 	 */
@@ -227,11 +218,7 @@ export type SyncCapability = ReturnType<typeof createSyncCapability>;
  * @returns A handler function that executes the sync function, and passes data
  * needed to complete the sync back to the platform.
  */
-export function createSyncCapability<
-	PK extends string,
-	S extends Schema<PK>,
-	Context = unknown,
->(
+export function createSyncCapability<PK extends string, S extends Schema<PK>, Context = unknown>(
 	key: string,
 	syncConfiguration: SyncConfiguration<PK, S, Context>,
 	pacerDeclarations?: readonly PacerDeclaration[],
@@ -243,14 +230,9 @@ export function createSyncCapability<
 			databaseKey: syncConfiguration.database.key,
 			primaryKeyProperty: syncConfiguration.database.config.primaryKeyProperty,
 			mode: syncConfiguration.mode,
-			schedule: syncConfiguration.schedule
-				? parseSchedule(syncConfiguration.schedule)
-				: undefined,
+			schedule: syncConfiguration.schedule ? parseSchedule(syncConfiguration.schedule) : undefined,
 		},
-		async handler(
-			runtimeContext?: StatefulRuntimeContext<Context>,
-			options?: HandlerOptions,
-		) {
+		async handler(runtimeContext?: StatefulRuntimeContext<Context>, options?: HandlerOptions) {
 			const capabilityContext = createCapabilityContext("sync");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
@@ -258,10 +240,7 @@ export function createSyncCapability<
 
 			let executionResult: SyncExecutionResult<PK, Context>;
 			try {
-				executionResult = await syncConfiguration.execute(
-					state,
-					capabilityContext,
-				);
+				executionResult = await syncConfiguration.execute(state, capabilityContext);
 			} catch (err) {
 				if (err instanceof RateLimitError) {
 					if (!options?.concreteOutput) {
@@ -271,9 +250,7 @@ export function createSyncCapability<
 								_tag: "rate_limit",
 								name: err.name,
 								message: err.message,
-								...(err.retryAfter !== undefined
-									? { retryAfter: err.retryAfter }
-									: {}),
+								...(err.retryAfter !== undefined ? { retryAfter: err.retryAfter } : {}),
 							},
 						};
 						writeOutput(envelope);
@@ -298,8 +275,7 @@ export function createSyncCapability<
 
 			const changes = executionResult.changes.map((change) => ({
 				...change,
-				targetDatabaseKey:
-					change.targetDatabaseKey ?? syncConfiguration.database.key,
+				targetDatabaseKey: change.targetDatabaseKey ?? syncConfiguration.database.key,
 			}));
 
 			const result = {

package/src/capabilities/tool.test.ts

@@ -1,12 +1,5 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+
 import { j } from "../schema-builder.js";
 import { createToolCapability } from "./tool.js";
 
@@ -14,9 +7,7 @@ describe("Worker.tool", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
-		stdoutSpy = vi
-			.spyOn(process.stdout, "write")
-			.mockImplementation(() => true);
+		stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 	});
 
 	afterEach(() => {
@@ -24,17 +15,14 @@ describe("Worker.tool", () => {
 	});
 
 	it("sync execution", async () => {
-		const capability = createToolCapability<{ name: string }, string>(
-			"sayHello",
-			{
-				title: "Say Hello",
-				description: "Greet a user",
-				schema: j.object({ name: j.string() }),
-				execute: (input: { name: string }) => {
-					return `Hello, ${input.name}!`;
-				},
+		const capability = createToolCapability<{ name: string }, string>("sayHello", {
+			title: "Say Hello",
+			description: "Greet a user",
+			schema: j.object({ name: j.string() }),
+			execute: (input: { name: string }) => {
+				return `Hello, ${input.name}!`;
 			},
-		);
+		});
 
 		const result = await capability.handler({ name: "Alice" });
 
@@ -46,19 +34,16 @@ describe("Worker.tool", () => {
 	});
 
 	it("async execution", async () => {
-		const capability = createToolCapability<{ id: number }, { data: string }>(
-			"fetchData",
-			{
-				title: "Fetch Data",
-				description: "Fetch data asynchronously",
-				schema: j.object({ id: j.number() }),
-				execute: async (input: { id: number }) => {
-					// Simulate async operation
-					await new Promise((resolve) => setTimeout(resolve, 10));
-					return { data: `Data for ID ${input.id}` };
-				},
+		const capability = createToolCapability<{ id: number }, { data: string }>("fetchData", {
+			title: "Fetch Data",
+			description: "Fetch data asynchronously",
+			schema: j.object({ id: j.number() }),
+			execute: async (input: { id: number }) => {
+				// Simulate async operation
+				await new Promise((resolve) => setTimeout(resolve, 10));
+				return { data: `Data for ID ${input.id}` };
 			},
-		);
+		});
 
 		const result = await capability.handler({ id: 42 });
 
@@ -73,17 +58,14 @@ describe("Worker.tool", () => {
 	});
 
 	it("execution error", async () => {
-		const capability = createToolCapability<Record<string, never>, string>(
-			"throwError",
-			{
-				title: "Throw Error",
-				description: "Throws an error",
-				schema: j.object({}),
-				execute: () => {
-					throw new Error("Something went wrong");
-				},
+		const capability = createToolCapability<Record<string, never>, string>("throwError", {
+			title: "Throw Error",
+			description: "Throws an error",
+			schema: j.object({}),
+			execute: () => {
+				throw new Error("Something went wrong");
 			},
-		);
+		});
 
 		const result = (await capability.handler({})) as {
 			_tag: "error";
@@ -102,17 +84,14 @@ describe("Worker.tool", () => {
 	});
 
 	it("invalid input", async () => {
-		const capability = createToolCapability<{ name: string }, string>(
-			"sayHelloStrict",
-			{
-				title: "Say Hello",
-				description: "Requires a name property",
-				schema: j.object({ name: j.string() }),
-				execute: (input: { name: string }) => {
-					return `Hello, ${input.name}!`;
-				},
+		const capability = createToolCapability<{ name: string }, string>("sayHelloStrict", {
+			title: "Say Hello",
+			description: "Requires a name property",
+			schema: j.object({ name: j.string() }),
+			execute: (input: { name: string }) => {
+				return `Hello, ${input.name}!`;
 			},
-		);
+		});
 
 		const result = (await capability.handler({ age: 25 })) as {
 			_tag: "error";
@@ -131,19 +110,19 @@ describe("Worker.tool", () => {
 	});
 
 	it("invalid output", async () => {
-		const capability = createToolCapability<
-			Record<string, never>,
-			{ result: string }
-		>("invalidOutput", {
-			title: "Return Invalid Output",
-			description: "Returns output that doesn't match schema",
-			schema: j.object({}),
-			outputSchema: j.object({ result: j.string() }),
-			// @ts-expect-error Testing invalid output - intentionally returning number instead of string
-			execute: () => {
-				return { result: 123 };
+		const capability = createToolCapability<Record<string, never>, { result: string }>(
+			"invalidOutput",
+			{
+				title: "Return Invalid Output",
+				description: "Returns output that doesn't match schema",
+				schema: j.object({}),
+				outputSchema: j.object({ result: j.string() }),
+				// @ts-expect-error Testing invalid output - intentionally returning number instead of string
+				execute: () => {
+					return { result: 123 };
+				},
 			},
-		});
+		);
 
 		const result = (await capability.handler({})) as {
 			_tag: "error";
@@ -155,42 +134,37 @@ describe("Worker.tool", () => {
 		expect(result.error.message).toContain("result");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
-			expect.stringContaining(
-				`"_tag":"error","error":{"name":"InvalidToolOutputError"`,
-			),
+			expect.stringContaining(`"_tag":"error","error":{"name":"InvalidToolOutputError"`),
 		);
 	});
 
 	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",
+		const capability = createToolCapability<{ due: string; createdAt: string }, string>(
+			"dateFormats",
 			{
-				title: "Datetime Validation",
-				description: "Validates datetime input",
+				title: "Date Formats",
+				description: "Uses date and datetime format strings",
 				schema: j.object({
-					ts: j.datetime(),
+					due: j.date(),
+					createdAt: j.datetime(),
 				}),
-				execute: ({ ts }) => ts,
+				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",
@@ -206,78 +180,66 @@ describe("Worker.tool", () => {
 	});
 
 	it("accepts schema with nullable (string | null) properties", () => {
-		const capability = createToolCapability<
-			{ name: string; nickname: string | null },
-			string
-		>("nullable", {
-			title: "Nullable",
-			description: "Has nullable properties",
-			schema: j.object({
-				name: j.string(),
-				nickname: j.string().nullable(),
-			}),
-			execute: ({ name, nickname }) => `${name} (${nickname ?? "no nickname"})`,
-		});
+		const capability = createToolCapability<{ name: string; nickname: string | null }, string>(
+			"nullable",
+			{
+				title: "Nullable",
+				description: "Has nullable properties",
+				schema: j.object({
+					name: j.string(),
+					nickname: j.string().nullable(),
+				}),
+				execute: ({ name, nickname }) => `${name} (${nickname ?? "no nickname"})`,
+			},
+		);
 
 		expect(capability.config.schema).toBeDefined();
 	});
 
 	describe("hints", () => {
 		it("omits hints from config when not specified (existing tools unchanged)", () => {
-			const capability = createToolCapability<{ name: string }, string>(
-				"noHints",
-				{
-					title: "No Hints",
-					description: "A tool without hints",
-					schema: j.object({ name: j.string() }),
-					execute: ({ name }) => `Hello, ${name}`,
-				},
-			);
+			const capability = createToolCapability<{ name: string }, string>("noHints", {
+				title: "No Hints",
+				description: "A tool without hints",
+				schema: j.object({ name: j.string() }),
+				execute: ({ name }) => `Hello, ${name}`,
+			});
 
 			expect(capability.config.hints).toBeUndefined();
 		});
 
 		it("flows readOnlyHint=true through to config", () => {
-			const capability = createToolCapability<{ query: string }, string>(
-				"readOnly",
-				{
-					title: "Read Only",
-					description: "A read-only tool",
-					schema: j.object({ query: j.string() }),
-					hints: { readOnlyHint: true },
-					execute: ({ query }) => query,
-				},
-			);
+			const capability = createToolCapability<{ query: string }, string>("readOnly", {
+				title: "Read Only",
+				description: "A read-only tool",
+				schema: j.object({ query: j.string() }),
+				hints: { readOnlyHint: true },
+				execute: ({ query }) => query,
+			});
 
 			expect(capability.config.hints).toEqual({ readOnlyHint: true });
 		});
 
 		it("flows readOnlyHint=false through to config", () => {
-			const capability = createToolCapability<{ pageId: string }, string>(
-				"writeTool",
-				{
-					title: "Write Tool",
-					description: "A write tool",
-					schema: j.object({ pageId: j.string() }),
-					hints: { readOnlyHint: false },
-					execute: ({ pageId }) => pageId,
-				},
-			);
+			const capability = createToolCapability<{ pageId: string }, string>("writeTool", {
+				title: "Write Tool",
+				description: "A write tool",
+				schema: j.object({ pageId: j.string() }),
+				hints: { readOnlyHint: false },
+				execute: ({ pageId }) => pageId,
+			});
 
 			expect(capability.config.hints).toEqual({ readOnlyHint: false });
 		});
 
 		it("does not affect execution behavior", async () => {
-			const capability = createToolCapability<{ x: number }, number>(
-				"doubleReadOnly",
-				{
-					title: "Double",
-					description: "Doubles a number",
-					schema: j.object({ x: j.number() }),
-					hints: { readOnlyHint: true },
-					execute: ({ x }) => x * 2,
-				},
-			);
+			const capability = createToolCapability<{ x: number }, number>("doubleReadOnly", {
+				title: "Double",
+				description: "Doubles a number",
+				schema: j.object({ x: j.number() }),
+				hints: { readOnlyHint: true },
+				execute: ({ x }) => x * 2,
+			});
 
 			const result = await capability.handler({ x: 7 });
 
@@ -315,9 +277,7 @@ describe("Worker.tool", () => {
 		expect(result.error.message).toContain("message");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
-			expect.stringContaining(
-				`"_tag":"error","error":{"name":"InvalidToolOutputError"`,
-			),
+			expect.stringContaining(`"_tag":"error","error":{"name":"InvalidToolOutputError"`),
 		);
 	});
 });