@notionhq/workers 0.4.0 → 0.5.0

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"',
+			),
+		);
+	});
+});

package/src/capabilities/workflow.ts

@@ -0,0 +1,119 @@
+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,10 @@
-export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+export {
+	emojiIcon,
+	imageCover,
+	imageIcon,
+	notionIcon,
+	place,
+} from "./builder.js";
 export type {
 	AiConnectorArchetype,
 	AiConnectorCapability,
@@ -48,12 +54,21 @@ export type {
 	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/schema-builder.ts

@@ -94,6 +94,7 @@ function enumBuilder(
 	const type = typeof values[0] === "string" ? "string" : "number";
 	return makeBuilder({ type, enum: values } as AnyJSONSchema);
 }
+
 export { enumBuilder as enum };
 
 // ---- String format shorthands ----