@notionhq/workers 0.4.0 → 0.6.0

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

@@ -0,0 +1,163 @@
+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"',
+			),
+		);
+	});
+});

package/src/capabilities/workflow.ts

@@ -0,0 +1,112 @@
+import { ExecutionError } from "../error.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";
+import { writeOutput } from "./output.js";
+
+export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
+
+export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
+
+export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
+	WorkflowEventForTrigger<T[number]>;
+
+/**
+ * Configuration for a workflow capability
+ */
+export type WorkflowConfiguration<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+> = {
+	/**
+	 * A human-readable title for the workflow, shown in the UI when viewing workflows
+	 */
+	title: string;
+
+	/**
+	 * A human-readable description of what the workflow does, shown in the UI when viewing workflows
+	 */
+	description: string;
+
+	/**
+	 * An array of triggers that can invoke this workflow.
+	 *
+	 * Each trigger defines a specific event or condition that causes the workflow to run.
+	 */
+	triggers: TTriggers;
+
+	execute: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		context: CapabilityContext,
+	) => Promise<void> | void;
+};
+
+export type WorkflowCapability<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]] = readonly [
+		WorkflowTrigger,
+		...WorkflowTrigger[],
+	],
+> = {
+	_tag: "workflow";
+	key: string;
+	config: {
+		title: string;
+		description: string;
+		triggers: TTriggers;
+	};
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		options?: HandlerOptions,
+	) => Promise<{ status: "success" } | undefined>;
+};
+
+/**
+ * Creates a workflow capability from configuration.
+ *
+ * @param key - The unique name for this capability.
+ * @param config - The workflow configuration.
+ * @returns The capability object.
+ */
+export function createWorkflowCapability<
+	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+>(key: string, config: WorkflowConfiguration<TTriggers>): WorkflowCapability<TTriggers> {
+	return {
+		_tag: "workflow",
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+			triggers: config.triggers,
+		},
+		async handler(
+			event: WorkflowEventForTriggers<TTriggers>,
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext("workflow");
+				await config.execute(event, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				}
+
+				writeOutput({ _tag: "success", value: { status: "success" } });
+			} catch (err) {
+				const error = new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
+				}
+
+				throw error;
+			}
+		},
+	};
+}

package/src/index.ts

@@ -1,4 +1,11 @@
-export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+export type {
+	CustomBlockCapability,
+	CustomBlockCapabilityConfig,
+	CustomBlockConfiguration,
+	CustomBlockManifest,
+	CustomBlockManifestDataSource,
+} from "./capabilities/custom-block.js";
+export { emojiIcon, imageCover, imageIcon, notionIcon, place } from "./builder.js";
 export type {
 	AiConnectorArchetype,
 	AiConnectorCapability,
@@ -37,23 +44,28 @@ 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,
 	WebhookEvent,
 } from "./capabilities/webhook.js";
 export { WebhookVerificationError } from "./capabilities/webhook.js";
+export type {
+	WorkflowCapability,
+	WorkflowConfiguration,
+	WorkflowEvent,
+	WorkflowEventForTrigger,
+	WorkflowEventForTriggers,
+} from "./capabilities/workflow.js";
 export { RateLimitError } from "./error.js";
 export type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
 export type { Infer, SchemaBuilder } from "./schema-builder.js";
 export { getSchema, j } from "./schema-builder.js";
 export type {
+	Cover,
 	Icon,
+	ImageCover,
 	ImageIcon,
 	NoticonColor,
 	NoticonName,

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", () => {

package/src/json-schema.ts

@@ -45,16 +45,18 @@ interface ForbiddenCompositionKeywords {
 
 // ---- Individual schema definitions ----
 
-export interface JSONSchemaStringDef<T extends string = string>
-	extends ForbiddenCompositionKeywords {
+export interface JSONSchemaStringDef<
+	T extends string = string,
+> extends ForbiddenCompositionKeywords {
 	type: "string";
 	description?: string;
 	format?: JSONSchemaStringFormat;
 	enum?: readonly T[];
 }
 
-export interface JSONSchemaNumberDef<T extends number = number>
-	extends ForbiddenCompositionKeywords {
+export interface JSONSchemaNumberDef<
+	T extends number = number,
+> extends ForbiddenCompositionKeywords {
 	type: "number" | "integer";
 	description?: string;
 	enum?: readonly T[];
@@ -70,8 +72,7 @@ export interface JSONSchemaNullDef extends ForbiddenCompositionKeywords {
 	description?: string;
 }
 
-export interface JSONSchemaArrayDef<E = unknown>
-	extends ForbiddenCompositionKeywords {
+export interface JSONSchemaArrayDef<E = unknown> extends ForbiddenCompositionKeywords {
 	type: "array";
 	description?: string;
 	items: JSONSchema<E>;

package/src/pacer.test.ts

@@ -83,9 +83,7 @@ describe("pacerWait", () => {
 	it("throws when pacer key not found in runtime context", async () => {
 		setPacerState({ pacers: {} });
 
-		await expect(pacerWait("unknown")).rejects.toThrow(
-			'Pacer "unknown" not found',
-		);
+		await expect(pacerWait("unknown")).rejects.toThrow('Pacer "unknown" not found');
 	});
 
 	it("preserves allowedRequests and intervalMs across calls", async () => {

package/src/pacer_internal.ts

@@ -39,11 +39,7 @@ export function initPacerState(
 	declarations?: readonly PacerDeclaration[],
 ): void {
 	const pacers = runtimePacers ?? {};
-	if (
-		Object.keys(pacers).length === 0 &&
-		declarations &&
-		declarations.length > 0
-	) {
+	if (Object.keys(pacers).length === 0 && declarations && declarations.length > 0) {
 		const localPacers: Record<string, PacerEntry> = {};
 		for (const decl of declarations) {
 			localPacers[decl.key] = {

package/src/schema-builder.test.ts

@@ -1,11 +1,7 @@
 import { describe, expect, it } from "vitest";
+
 import type { JSONSchema } from "./json-schema.js";
-import {
-	getSchema,
-	type Infer,
-	j,
-	type SchemaBuilder,
-} from "./schema-builder.js";
+import { getSchema, type Infer, j, type SchemaBuilder } from "./schema-builder.js";
 
 // ---------------------------------------------------------------------------
 // 1. Primitives
@@ -188,9 +184,7 @@ describe("json-schema-builder — array", () => {
 	});
 
 	it("array of objects", () => {
-		const schema = getSchema(
-			j.array(j.object({ name: j.string(), age: j.number() })),
-		);
+		const schema = getSchema(j.array(j.object({ name: j.string(), age: j.number() })));
 		expect(schema).toEqual({
 			type: "array",
 			items: {
@@ -351,9 +345,7 @@ describe("json-schema-builder — anyOf", () => {
 	});
 
 	it("anyOf with description", () => {
-		expect(
-			getSchema(j.anyOf(j.string(), j.number()).describe("string or number")),
-		).toEqual({
+		expect(getSchema(j.anyOf(j.string(), j.number()).describe("string or number"))).toEqual({
 			anyOf: [{ type: "string" }, { type: "number" }],
 			description: "string or number",
 		});
@@ -463,12 +455,8 @@ describe("json-schema-builder — discriminated unions", () => {
 
 	it("discriminated union with descriptions on individual variants", () => {
 		const schema = j.anyOf(
-			j
-				.object({ type: j.enum("text"), value: j.string() })
-				.describe("A text node"),
-			j
-				.object({ type: j.enum("image"), url: j.string() })
-				.describe("An image node"),
+			j.object({ type: j.enum("text"), value: j.string() }).describe("A text node"),
+			j.object({ type: j.enum("image"), url: j.string() }).describe("An image node"),
 		);
 
 		const raw = getSchema(schema) as unknown as {
@@ -497,9 +485,7 @@ describe("json-schema-builder — discriminated unions", () => {
 		expect(raw.properties.content.anyOf).toHaveLength(2);
 
 		// The content field is in required
-		expect(
-			(getSchema(schema) as unknown as Record<string, unknown>).required,
-		).toContain("content");
+		expect((getSchema(schema) as unknown as Record<string, unknown>).required).toContain("content");
 	});
 
 	it("nullable discriminated union", () => {
@@ -614,15 +600,7 @@ describe("json-schema-builder — integration", () => {
 				},
 				createdAt: { type: "string", format: "date-time" },
 			},
-			required: [
-				"foo",
-				"bar",
-				"count",
-				"tags",
-				"address",
-				"nickname",
-				"createdAt",
-			],
+			required: ["foo", "bar", "count", "tags", "address", "nickname", "createdAt"],
 			additionalProperties: false,
 		});
 	});
@@ -634,9 +612,7 @@ describe("json-schema-builder — integration", () => {
 
 describe("json-schema-builder — constraint enforcement", () => {
 	it("object always has required matching properties keys", () => {
-		const schema = getSchema(
-			j.object({ x: j.number(), y: j.string(), z: j.boolean() }),
-		);
+		const schema = getSchema(j.object({ x: j.number(), y: j.string(), z: j.boolean() }));
 		const raw = schema as unknown as Record<string, unknown>;
 		expect(raw.required).toEqual(["x", "y", "z"]);
 		expect(raw.additionalProperties).toBe(false);
@@ -669,8 +645,7 @@ describe("json-schema-builder — constraint enforcement", () => {
 			}),
 		);
 		const raw = schema as unknown as Record<string, unknown>;
-		const outer = (raw as { properties: { outer: Record<string, unknown> } })
-			.properties.outer;
+		const outer = (raw as { properties: { outer: Record<string, unknown> } }).properties.outer;
 		expect(outer.required).toEqual(["inner"]);
 		expect(outer.additionalProperties).toBe(false);
 	});