@notionhq/workers 0.5.0 → 0.7.0

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({

package/src/capabilities/workflow.test.ts

@@ -1,19 +1,7 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	expectTypeOf,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
+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 CapabilityContext, Worker, type WorkflowConfiguration } from "../index.js";
 import {
 	type NotionPageCreatedEvent,
 	type NotionPageCreatedTrigger,
@@ -66,9 +54,7 @@ describe("createWorkflowCapability", () => {
 	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(() => {
@@ -82,13 +68,8 @@ describe("createWorkflowCapability", () => {
 	});
 
 	it("requires trigger declarations in workflow configuration", () => {
-		type PageAddedConfiguration = WorkflowConfiguration<
-			readonly [NotionPageCreatedTrigger]
-		>;
-		type ConfigurationWithoutTriggers = Omit<
-			PageAddedConfiguration,
-			"triggers"
-		>;
+		type PageAddedConfiguration = WorkflowConfiguration<readonly [NotionPageCreatedTrigger]>;
+		type ConfigurationWithoutTriggers = Omit<PageAddedConfiguration, "triggers">;
 
 		expectTypeOf<ConfigurationWithoutTriggers>().not.toMatchTypeOf<PageAddedConfiguration>();
 	});
@@ -137,9 +118,9 @@ describe("createWorkflowCapability", () => {
 			execute,
 		});
 
-		await expect(
-			capability.handler(pageCreatedEvent, { concreteOutput: true }),
-		).resolves.toEqual({ status: "success" });
+		await expect(capability.handler(pageCreatedEvent, { concreteOutput: true })).resolves.toEqual({
+			status: "success",
+		});
 		expect(execute).toHaveBeenCalledWith(
 			pageCreatedEvent,
 			expect.objectContaining({ notion: expect.any(Object) }),
@@ -172,9 +153,7 @@ describe("createWorkflowCapability", () => {
 			},
 		});
 
-		await expect(capability.handler(pageCreatedEvent)).rejects.toThrow(
-			ExecutionError,
-		);
+		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"',

package/src/capabilities/workflow.ts

@@ -1,8 +1,5 @@
 import { ExecutionError } from "../error.js";
-import type {
-	WorkflowEventMap,
-	WorkflowTrigger,
-} from "../triggers.generated.js";
+import type { WorkflowEventMap, WorkflowTrigger } from "../triggers.generated.js";
 import type { HandlerOptions } from "../types.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
@@ -10,8 +7,7 @@ import { writeOutput } from "./output.js";
 
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
-export type WorkflowEventForTrigger<T extends WorkflowTrigger> =
-	WorkflowEventMap[T["type"]];
+export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
 
 export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
 	WorkflowEventForTrigger<T[number]>;
@@ -46,10 +42,10 @@ export type WorkflowConfiguration<
 };
 
 export type WorkflowCapability<
-	TTriggers extends readonly [
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]] = readonly [
 		WorkflowTrigger,
 		...WorkflowTrigger[],
-	] = readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+	],
 > = {
 	_tag: "workflow";
 	key: string;
@@ -73,10 +69,7 @@ export type WorkflowCapability<
  */
 export function createWorkflowCapability<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
->(
-	key: string,
-	config: WorkflowConfiguration<TTriggers>,
-): WorkflowCapability<TTriggers> {
+>(key: string, config: WorkflowConfiguration<TTriggers>): WorkflowCapability<TTriggers> {
 	return {
 		_tag: "workflow",
 		key,

package/src/index.ts

@@ -1,10 +1,4 @@
-export {
-	emojiIcon,
-	imageCover,
-	imageIcon,
-	notionIcon,
-	place,
-} from "./builder.js";
+export { emojiIcon, imageCover, imageIcon, notionIcon, place } from "./builder.js";
 export type {
 	AiConnectorArchetype,
 	AiConnectorCapability,
@@ -43,11 +37,7 @@ export type {
 	SyncExecutionResult,
 	SyncMode,
 } from "./capabilities/sync.js";
-export type {
-	ToolCapability,
-	ToolConfiguration,
-	ToolHints,
-} from "./capabilities/tool.js";
+export type { ToolCapability, ToolConfiguration, ToolHints } from "./capabilities/tool.js";
 export type {
 	WebhookCapability,
 	WebhookConfiguration,

package/src/json-schema.test.ts

@@ -12,6 +12,7 @@
  * This ensures tsc sees the error on the line immediately after the directive.
  */
 import { describe, expect, it } from "vitest";
+
 import type {
 	AnyJSONSchema,
 	JSONSchema,
@@ -671,10 +672,7 @@ describe("JSONSchema — complex schemas", () => {
 
 describe("JSONSchema — structural type assertions", () => {
 	it("JSONSchemaObjectDef requires additionalProperties to be false", () => {
-		type _Proof = Assert<
-			JSONSchemaObjectDef<{ x: number }>["additionalProperties"],
-			false
-		>;
+		type _Proof = Assert<JSONSchemaObjectDef<{ x: number }>["additionalProperties"], false>;
 	});
 
 	it("JSONSchemaArrayDef minItems is restricted to 0 | 1", () => {