@notionhq/workers 0.5.0 → 0.6.0

package/src/capabilities/sync.ts

@@ -1,14 +1,6 @@
 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,
@@ -62,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.
 	 */
@@ -168,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.
 	 */
@@ -233,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[],
@@ -249,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;
 
@@ -264,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) {
@@ -277,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);
@@ -304,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"`),
 		);
 	});
 });

package/src/capabilities/tool.ts

@@ -1,5 +1,6 @@
 import { Ajv } from "ajv";
 import addFormats from "ajv-formats";
+
 import type { AnyJSONSchema } from "../json-schema.js";
 import type { SchemaBuilder } from "../schema-builder.js";
 import { getSchema } from "../schema-builder.js";
@@ -15,10 +16,7 @@ import { writeOutput } from "./output.js";
  * Throws a descriptive error at tool registration time (not request time)
  * so the developer sees it immediately.
  */
-function validateRequiredProperties(
-	schema: AnyJSONSchema,
-	path: string = "",
-): void {
+function validateRequiredProperties(schema: AnyJSONSchema, path: string = ""): void {
 	if ("type" in schema && schema.type === "object" && "properties" in schema) {
 		const propKeys = Object.keys(schema.properties).sort();
 		const required = [...(schema.required ?? [])].sort();
@@ -43,20 +41,14 @@ function validateRequiredProperties(
 		// Recurse into $defs
 		if ("$defs" in schema && schema.$defs) {
 			for (const [key, defSchema] of Object.entries(schema.$defs)) {
-				validateRequiredProperties(
-					defSchema,
-					path ? `${path}.$defs.${key}` : `$defs.${key}`,
-				);
+				validateRequiredProperties(defSchema, path ? `${path}.$defs.${key}` : `$defs.${key}`);
 			}
 		}
 	}
 
 	// Recurse into array items
 	if ("type" in schema && schema.type === "array" && "items" in schema) {
-		validateRequiredProperties(
-			schema.items as AnyJSONSchema,
-			path ? `${path}.items` : "items",
-		);
+		validateRequiredProperties(schema.items as AnyJSONSchema, path ? `${path}.items` : "items");
 	}
 
 	// Recurse into anyOf branches
@@ -90,10 +82,7 @@ export interface ToolHints {
 	readOnlyHint?: boolean;
 }
 
-export interface ToolConfiguration<
-	I extends JSONValue,
-	O extends JSONValue = JSONValue,
-> {
+export interface ToolConfiguration<I extends JSONValue, O extends JSONValue = JSONValue> {
 	title: string;
 	description: string;
 	schema: SchemaBuilder<I>;
@@ -156,10 +145,9 @@ export class ToolExecutionError extends Error {
 	}
 }
 
-export type ToolCapability<
-	I extends JSONValue,
-	O extends JSONValue = JSONValue,
-> = ReturnType<typeof createToolCapability<I, O>>;
+export type ToolCapability<I extends JSONValue, O extends JSONValue = JSONValue> = ReturnType<
+	typeof createToolCapability<I, O>
+>;
 
 /**
  * Creates a capability definition for a tool to be used by an agent.
@@ -167,16 +155,14 @@ export type ToolCapability<
  * @param config - The configuration for the tool.
  * @returns A capability definition for the tool.
  */
-export function createToolCapability<
-	I extends JSONValue,
-	O extends JSONValue = JSONValue,
->(key: string, config: ToolConfiguration<I, O>) {
+export function createToolCapability<I extends JSONValue, O extends JSONValue = JSONValue>(
+	key: string,
+	config: ToolConfiguration<I, O>,
+) {
 	const inputSchema = getSchema(config.schema);
 	validateRequiredProperties(inputSchema as AnyJSONSchema);
 
-	const outputSchema = config.outputSchema
-		? getSchema(config.outputSchema)
-		: undefined;
+	const outputSchema = config.outputSchema ? getSchema(config.outputSchema) : undefined;
 
 	if (outputSchema) {
 		validateRequiredProperties(outputSchema as AnyJSONSchema);
@@ -215,14 +201,10 @@ export function createToolCapability<
 		if (!validateInput(input)) {
 			// ajv resets the "errors" property on each validation call.
 			if (validateInput.errors == null) {
-				throw new Error(
-					"Unexpected: No validation errors after failed validation",
-				);
+				throw new Error("Unexpected: No validation errors after failed validation");
 			}
 
-			const error = new InvalidToolInputError(
-				JSON.stringify(validateInput.errors, null, 2),
-			);
+			const error = new InvalidToolInputError(JSON.stringify(validateInput.errors, null, 2));
 
 			if (options?.concreteOutput) {
 				throw error;
@@ -242,9 +224,7 @@ export function createToolCapability<
 			const capabilityContext = createCapabilityContext("tool");
 			const result = await config.execute(input, capabilityContext);
 			if (validateOutput && !validateOutput(result)) {
-				const error = new InvalidToolOutputError(
-					JSON.stringify(validateOutput.errors, null, 2),
-				);
+				const error = new InvalidToolOutputError(JSON.stringify(validateOutput.errors, null, 2));
 
 				if (options?.concreteOutput) {
 					throw error;
@@ -275,9 +255,7 @@ export function createToolCapability<
 				value: result,
 			};
 		} catch (err) {
-			const error = new ToolExecutionError(
-				err instanceof Error ? err.message : String(err),
-			);
+			const error = new ToolExecutionError(err instanceof Error ? err.message : String(err));
 
 			if (options?.concreteOutput) {
 				throw error;

package/src/capabilities/webhook.ts

@@ -94,18 +94,12 @@ export interface WebhookConfiguration {
 	 * @param context - The capability execution context (Notion client, etc.)
 	 * @returns A promise that resolves when the webhook processing completes
 	 */
-	execute: (
-		events: WebhookEvent[],
-		context: CapabilityContext,
-	) => Promise<void> | void;
+	execute: (events: WebhookEvent[], context: CapabilityContext) => Promise<void> | void;
 }
 
 export type WebhookCapability = ReturnType<typeof createWebhookCapability>;
 
-export function createWebhookCapability(
-	key: string,
-	config: WebhookConfiguration,
-) {
+export function createWebhookCapability(key: string, config: WebhookConfiguration) {
 	return {
 		_tag: "webhook" as const,
 		key,
@@ -127,8 +121,7 @@ export function createWebhookCapability(
 					writeOutput({ _tag: "success", value: { status: "success" } });
 				}
 			} catch (err) {
-				const error =
-					err instanceof ExecutionError ? err : new ExecutionError(err);
+				const error = err instanceof ExecutionError ? err : new ExecutionError(err);
 
 				if (!options?.concreteOutput) {
 					writeOutput({