@notionhq/workers 0.3.0 → 0.5.0

package/src/capabilities/sync.test.ts

@@ -8,7 +8,7 @@ import {
 	vi,
 } from "vitest";
 import * as Builder from "../builder.js";
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import { getPacerState } from "../pacer_internal.js";
 import * as Schema from "../schema.js";
 import { Worker } from "../worker.js";
@@ -59,6 +59,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();
@@ -107,6 +135,42 @@ describe("Worker.sync", () => {
 		});
 	});
 
+	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,
+				}),
+			});
+
+			expect(capability._tag).toBe("sync");
+			expect(capability.config.databaseKey).toBe("tasks");
+		});
+	});
+
 	describe("pacer local fallback", () => {
 		it("seeds pacer state from declarations when runtime context has no pacers", async () => {
 			const worker = new Worker();
@@ -251,6 +315,113 @@ describe("Worker.sync", () => {
 			);
 		});
 
+		it("wraps RateLimitError in error envelope with _tag rate_limit", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(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 () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError({ retryAfter: 30 });
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.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",
+				),
+			);
+			expect(parsed).toEqual({
+				_tag: "error",
+				error: {
+					_tag: "rate_limit",
+					name: "RateLimitError",
+					message:
+						"Error during worker execution: Rate limited by external API",
+					retryAfter: 30,
+				},
+			});
+		});
+
+		it("wraps RateLimitError without retryAfter correctly", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.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",
+				),
+			);
+			expect(parsed.error.retryAfter).toBeUndefined();
+		});
+
 		it("emits sync output with key and default targetDatabaseKey", async () => {
 			const worker = new Worker();
 			const tasks = worker.database("tasks", {

package/src/capabilities/sync.ts

@@ -1,4 +1,4 @@
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import {
 	getPacerState,
 	initPacerState,
@@ -10,6 +10,7 @@ import type {
 	Schema,
 } from "../schema.js";
 import type {
+	Cover,
 	HandlerOptions,
 	Icon,
 	PeopleValue,
@@ -28,6 +29,18 @@ import {
 	type RuntimeContext as StatefulRuntimeContext,
 } from "./stateful-capability.js";
 
+type SyncErrorEnvelope =
+	| { _tag: "error"; error: { _tag: "generic"; name: string; message: string } }
+	| {
+			_tag: "error";
+			error: {
+				_tag: "rate_limit";
+				name: string;
+				message: string;
+				retryAfter?: number;
+			};
+	  };
+
 /**
  * Maps a property configuration to its corresponding value type.
  */
@@ -86,6 +99,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.
@@ -239,7 +257,7 @@ export function createSyncCapability<
 			runtimeContext?: StatefulRuntimeContext<Context>,
 			options?: HandlerOptions,
 		) {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("sync");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
 			initPacerState(runtimeContext?.pacers, pacerDeclarations);
@@ -251,12 +269,35 @@ export function createSyncCapability<
 					capabilityContext,
 				);
 			} 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) {
-					writeOutput({
+					const envelope: SyncErrorEnvelope = {
 						_tag: "error",
-						error: { name: error.name, message: error.message },
-					});
+						error: {
+							_tag: "generic",
+							name: error.name,
+							message: error.message,
+						},
+					};
+					writeOutput(envelope);
 				}
 				throw error;
 			}

package/src/capabilities/tool.test.ts

@@ -222,6 +222,69 @@ describe("Worker.tool", () => {
 		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}`,
+				},
+			);
+
+			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,
+				},
+			);
+
+			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,
+				},
+			);
+
+			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 result = await capability.handler({ x: 7 });
+
+			expect(result).toEqual({ _tag: "success", value: 14 });
+		});
+	});
+
 	it("invalid output with custom output schema", async () => {
 		const capability = createToolCapability<
 			{ value: number },

package/src/capabilities/tool.ts

@@ -70,6 +70,26 @@ function validateRequiredProperties(
 	}
 }
 
+/**
+ * Hints describing a tool's behavior. Advisory metadata read by the platform
+ * (not the model) to decide whether a call is safe to auto-execute or
+ * requires user confirmation.
+ *
+ * Field names mirror the MCP tool annotation shape
+ * (`McpServerToolAnnotations`) so worker tools flow through the same
+ * confirmation / auto-execute machinery as MCP tools.
+ *
+ * Only hints with active consumers in the Notion client are included.
+ */
+export interface ToolHints {
+	/**
+	 * The tool only reads state and has no side effects. Safe to call
+	 * repeatedly; safe to auto-execute under default policy. Tools without
+	 * this hint are treated as write tools and prompt for confirmation.
+	 */
+	readOnlyHint?: boolean;
+}
+
 export interface ToolConfiguration<
 	I extends JSONValue,
 	O extends JSONValue = JSONValue,
@@ -78,6 +98,7 @@ export interface ToolConfiguration<
 	description: string;
 	schema: SchemaBuilder<I>;
 	outputSchema?: SchemaBuilder<O>;
+	hints?: ToolHints;
 	execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 
@@ -218,7 +239,7 @@ export function createToolCapability<
 		}
 
 		try {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("tool");
 			const result = await config.execute(input, capabilityContext);
 			if (validateOutput && !validateOutput(result)) {
 				const error = new InvalidToolOutputError(
@@ -281,6 +302,7 @@ export function createToolCapability<
 			description: config.description,
 			schema: inputSchema,
 			outputSchema: outputSchema,
+			hints: config.hints,
 		},
 		handler,
 	};

package/src/capabilities/webhook.ts

@@ -118,7 +118,7 @@ export function createWebhookCapability(
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext();
+				const capabilityContext = createCapabilityContext("webhook");
 				await config.execute(events, capabilityContext);
 
 				if (options?.concreteOutput) {

package/src/capabilities/workflow.test.ts

@@ -0,0 +1,184 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	expectTypeOf,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import { ExecutionError } from "../error.js";
+import {
+	type CapabilityContext,
+	Worker,
+	type WorkflowConfiguration,
+} from "../index.js";
+import {
+	type NotionPageCreatedEvent,
+	type NotionPageCreatedTrigger,
+	triggers,
+} from "../triggers.generated.js";
+import { createWorkflowCapability } from "./workflow.js";
+
+const pageCreatedEvent: NotionPageCreatedEvent = {
+	type: "notion.page.created",
+	vendor: "notion",
+	message: "Page created",
+	actor: {
+		id: "user-1",
+		displayName: "Ada Lovelace",
+		email: "ada@example.com",
+		vendorActor: {
+			vendor: "notion",
+			id: "user-1",
+			displayName: "Ada Lovelace",
+			handle: null,
+			type: "user",
+			url: null,
+		},
+	},
+	url: "https://www.notion.so/page-1",
+	timestamp: "2026-06-26T12:00:00.000Z",
+	page: {
+		id: "page-1",
+		Name: "Welcome",
+		Status: "New",
+	},
+	content: "# Welcome\n\nHello, world!",
+	edits: [
+		{
+			before: null,
+			after: {
+				id: "page-1",
+				Name: "Welcome",
+				Status: "New",
+			},
+			afterContent: "# Welcome\n\nHello, world!",
+			contentChanged: true,
+			timestamp: 1_782_477_600_000,
+			editedBy: null,
+		},
+	],
+};
+
+describe("createWorkflowCapability", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("declares a page-created trigger without a database", () => {
+		expect(triggers.notionPageCreated()).toEqual({
+			type: "notion.page.created",
+		});
+	});
+
+	it("requires trigger declarations in workflow configuration", () => {
+		type PageAddedConfiguration = WorkflowConfiguration<
+			readonly [NotionPageCreatedTrigger]
+		>;
+		type ConfigurationWithoutTriggers = Omit<
+			PageAddedConfiguration,
+			"triggers"
+		>;
+
+		expectTypeOf<ConfigurationWithoutTriggers>().not.toMatchTypeOf<PageAddedConfiguration>();
+	});
+
+	it("infers the canonical page-created event and capability context", () => {
+		createWorkflowCapability("pageAdded", {
+			title: "Page Added",
+			description: "Runs when a page is added",
+			triggers: [triggers.notionPageCreated()],
+			execute: (event, context) => {
+				expectTypeOf(event).toEqualTypeOf<NotionPageCreatedEvent>();
+				expectTypeOf(event.type).toEqualTypeOf<"notion.page.created">();
+				expectTypeOf(context).toEqualTypeOf<CapabilityContext>();
+			},
+		});
+	});
+
+	it("includes triggers in capability config and the worker manifest", () => {
+		const worker = new Worker();
+		worker.workflow("pageAdded", {
+			title: "Page Added",
+			description: "Runs when a page is added",
+			triggers: [triggers.notionPageCreated()],
+			execute: () => {},
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "workflow",
+				key: "pageAdded",
+				config: {
+					title: "Page Added",
+					description: "Runs when a page is added",
+					triggers: [{ type: "notion.page.created" }],
+				},
+			},
+		]);
+	});
+
+	it("executes with the public event and capability context", async () => {
+		const execute = vi.fn();
+		const capability = createWorkflowCapability("pageAdded", {
+			title: "Page Added",
+			description: "Runs when a page is added",
+			triggers: [triggers.notionPageCreated()],
+			execute,
+		});
+
+		await expect(
+			capability.handler(pageCreatedEvent, { concreteOutput: true }),
+		).resolves.toEqual({ status: "success" });
+		expect(execute).toHaveBeenCalledWith(
+			pageCreatedEvent,
+			expect.objectContaining({ notion: expect.any(Object) }),
+		);
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("writes the success envelope by default", async () => {
+		const capability = createWorkflowCapability("pageAdded", {
+			title: "Page Added",
+			description: "Runs when a page is added",
+			triggers: [triggers.notionPageCreated()],
+			execute: () => {},
+		});
+
+		await capability.handler(pageCreatedEvent);
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			'\n<__notion_output__>{"_tag":"success","value":{"status":"success"}}</__notion_output__>\n',
+		);
+	});
+
+	it("writes and throws an execution error", async () => {
+		const capability = createWorkflowCapability("pageAdded", {
+			title: "Page Added",
+			description: "Runs when a page is added",
+			triggers: [triggers.notionPageCreated()],
+			execute: () => {
+				throw new Error("Something went wrong");
+			},
+		});
+
+		await expect(capability.handler(pageCreatedEvent)).rejects.toThrow(
+			ExecutionError,
+		);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				'"_tag":"error","error":{"name":"ExecutionError","message":"Error during worker execution: Error: Something went wrong"',
+			),
+		);
+	});
+});