@notionhq/workers 0.0.82

package/src/builder.ts

@@ -0,0 +1,299 @@
+import type { NoticonName } from "./icon-names.js";
+import type {
+	DateValue,
+	Icon,
+	NoticonColor,
+	PeopleValue,
+	PlaceValue,
+	RelationReference,
+	TextValue,
+} from "./types.js";
+
+/**
+ * Creates a rich text value.
+ */
+export function richText(content: string): TextValue {
+	return [[content]];
+}
+
+/**
+ * Creates a URL value.
+ */
+export function url(url: string): TextValue {
+	return [[url]];
+}
+
+/**
+ * Creates a title value.
+ */
+export function title(content: string): TextValue {
+	return [[content]];
+}
+
+/**
+ * Creates a text value.
+ */
+export function text(content: string): TextValue {
+	return [[content]];
+}
+
+/**
+ * Creates an email value.
+ */
+export function email(email: string): TextValue {
+	return [[email]];
+}
+
+/**
+ * Creates a phone number value.
+ */
+export function phoneNumber(phone: string): TextValue {
+	return [[phone]];
+}
+
+/**
+ * Creates a checkbox value.
+ */
+export function checkbox(checked: boolean): TextValue {
+	return checked ? [["Yes"]] : [["No"]];
+}
+
+/**
+ * Creates a file URL value.
+ * @param fileUrl - The URL of the file
+ * @param fileName - Optional display name for the file (defaults to URL)
+ */
+export function file(fileUrl: string, fileName?: string): TextValue {
+	return [[fileName ?? fileUrl, [["a", fileUrl]]]];
+}
+
+/**
+ * Creates a number value.
+ */
+export function number(value: number): TextValue {
+	if (Number.isNaN(value)) {
+		return [];
+	}
+	return [[value.toString()]];
+}
+
+/**
+ * Creates a date value from a date string (YYYY-MM-DD).
+ */
+export function date(dateString: string): TextValue {
+	validateDateString(dateString);
+
+	const dateValue: DateValue = {
+		type: "date",
+		start_date: dateString,
+	};
+
+	return createDateToken(dateValue);
+}
+
+/**
+ * Creates a datetime value from a Date object.
+ */
+export function dateTime(date: Date, timeZone?: string): TextValue {
+	const dateValue: DateValue = {
+		type: "datetime",
+		start_date: formatDate(date),
+		start_time: formatTime(date),
+	};
+
+	if (timeZone) {
+		dateValue.time_zone = timeZone;
+	}
+
+	return createDateToken(dateValue);
+}
+
+/**
+ * Creates a date range value from date strings.
+ */
+export function dateRange(startDate: string, endDate: string): TextValue {
+	validateDateString(startDate);
+	validateDateString(endDate);
+
+	const dateValue: DateValue = {
+		type: "daterange",
+		start_date: startDate,
+		end_date: endDate,
+	};
+
+	return createDateToken(dateValue);
+}
+
+/**
+ * Creates a datetime range value from Date objects.
+ */
+export function dateTimeRange(
+	startDate: Date,
+	endDate: Date,
+	timeZone?: string,
+): TextValue {
+	const dateValue: DateValue = {
+		type: "datetimerange",
+		start_date: formatDate(startDate),
+		start_time: formatTime(startDate),
+		end_date: formatDate(endDate),
+		end_time: formatTime(endDate),
+	};
+
+	if (timeZone) {
+		dateValue.time_zone = timeZone;
+	}
+
+	return createDateToken(dateValue);
+}
+
+/**
+ * Creates a link with custom display text.
+ * @param displayText - The text to display
+ * @param url - The URL to link to
+ */
+export function link(displayText: string, url: string): TextValue {
+	return [[displayText, [["a", url]]]];
+}
+
+/**
+ * Creates a select value from a single option.
+ */
+export function select(value: string): TextValue {
+	return [[value]];
+}
+
+/**
+ * Creates a multi-select value from multiple options.
+ * @param values - Array of option names to select
+ */
+export function multiSelect(...values: string[]): TextValue {
+	if (values.length === 0) {
+		return [];
+	}
+	return [[values.join(",")]];
+}
+
+/**
+ * Creates a status value from a status option name.
+ */
+export function status(value: string): TextValue {
+	return [[value]];
+}
+
+/**
+ * Creates a people value from email addresses.
+ * @param emails - Array of email addresses for people to include
+ */
+export function people(...emails: string[]): PeopleValue {
+	return emails.map((email) => ({ email }));
+}
+
+/**
+ * Creates a place value for a geographic location.
+ * @param value - The place value with lat/lon coordinates and optional name/address
+ */
+export function place(value: PlaceValue): PlaceValue {
+	if (typeof value.lat !== "number" || typeof value.lon !== "number") {
+		throw new Error("Place value must have numeric lat and lon coordinates");
+	}
+	return value;
+}
+
+/**
+ * Creates a relation reference from a primary key of a related record.
+ * Use an array of relation references as the property value.
+ *
+ * @param primaryKey - The primary key of the related record
+ * @example
+ * ```typescript
+ * // Single relation
+ * { Project: [Builder.relation("project-123")] }
+ *
+ * // Multiple relations
+ * { Projects: [Builder.relation("project-123"), Builder.relation("project-456")] }
+ * ```
+ */
+export function relation(primaryKey: string): RelationReference {
+	return { type: "primaryKey", value: primaryKey };
+}
+
+/**
+ * Validates a date string is in YYYY-MM-DD format and represents a valid date.
+ */
+function validateDateString(dateString: string): void {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
+		throw new Error(
+			`Invalid date format: ${dateString}. Expected YYYY-MM-DD format.`,
+		);
+	}
+
+	const date = new Date(dateString);
+	if (Number.isNaN(date.getTime())) {
+		throw new Error(`Invalid date: ${dateString}`);
+	}
+}
+
+/**
+ * Internal helper to create a date mention token from a DateValue object.
+ */
+function createDateToken(dateValue: DateValue): TextValue {
+	return [["\u2023", [["d", dateValue]]]];
+}
+
+/**
+ * Formats a Date object to YYYY-MM-DD string.
+ */
+function formatDate(date: Date): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+/**
+ * Formats a Date object to HH:mm string.
+ */
+function formatTime(date: Date): string {
+	const hours = String(date.getHours()).padStart(2, "0");
+	const minutes = String(date.getMinutes()).padStart(2, "0");
+	return `${hours}:${minutes}`;
+}
+
+/**
+ * Creates an emoji icon.
+ * @param emoji - An emoji string (e.g., "🎯", "✨", "🚀")
+ */
+export function emojiIcon(emoji: string): Icon {
+	return {
+		type: "emoji",
+		value: emoji,
+	};
+}
+
+/**
+ * Creates a Notion icon with a specific color.
+ * @param icon - The name of the Notion icon (e.g., "checkmark", "pizza", "rocket")
+ * @param color - The color variant (defaults to "gray")
+ */
+export function notionIcon(
+	icon: NoticonName,
+	color: NoticonColor = "gray",
+): Icon {
+	return {
+		type: "notion",
+		icon,
+		color,
+	};
+}
+
+/**
+ * Creates an image icon from an external URL.
+ * @param url - The URL of the image (e.g., "https://example.com/icon.png")
+ */
+export function imageIcon(url: string): Icon {
+	return {
+		type: "image",
+		url,
+	};
+}

package/src/capabilities/automation.test.ts

@@ -0,0 +1,152 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import { ExecutionError } from "../error.js";
+import type { PageObjectResponse } from "./automation.js";
+import { createAutomationCapability } from "./automation.js";
+
+describe("createAutomationCapability", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("creates automation capability with correct structure", () => {
+		const capability = createAutomationCapability("testAutomation", {
+			title: "Test Automation",
+			description: "Test automation description",
+			execute: () => {},
+		});
+
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("automation");
+		expect(capability.config.title).toBe("Test Automation");
+		expect(capability.config.description).toBe("Test automation description");
+	});
+
+	it("executes automation without page data", async () => {
+		const executeFn = vi.fn();
+		const capability = createAutomationCapability("syncAutomation", {
+			title: "Sync Automation",
+			description: "Executes synchronously",
+			execute: executeFn,
+		});
+
+		const event = {
+			pageId: "page-123",
+			actionType: "test_action",
+		};
+
+		await capability.handler(event);
+
+		expect(executeFn).toHaveBeenCalledWith(
+			event,
+			expect.objectContaining({
+				notion: expect.any(Object),
+			}),
+		);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"success"}</output>\n`,
+		);
+	});
+
+	it("executes automation with page data", async () => {
+		const executeFn = vi.fn();
+		const capability = createAutomationCapability("pageAutomation", {
+			title: "Page Automation",
+			description: "Processes page data",
+			execute: executeFn,
+		});
+
+		const pageData: PageObjectResponse = {
+			object: "page",
+			id: "page-789",
+			created_time: "2023-01-01T00:00:00.000Z",
+			last_edited_time: "2023-01-02T00:00:00.000Z",
+			created_by: { id: "user-1" },
+			last_edited_by: { id: "user-2" },
+			cover: null,
+			icon: null,
+			parent: { type: "database_id", database_id: "db-123" },
+			archived: false,
+			properties: {
+				Name: { id: "title", type: "title", title: [] },
+				Status: { id: "status", type: "status", status: { name: "Done" } },
+			},
+			url: "https://notion.so/page-789",
+			public_url: null,
+		};
+
+		const event = {
+			pageId: "page-789",
+			actionType: "process_page",
+			pageData,
+		};
+
+		await capability.handler(event);
+
+		expect(executeFn).toHaveBeenCalledWith(
+			event,
+			expect.objectContaining({
+				notion: expect.any(Object),
+			}),
+		);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"success"}</output>\n`,
+		);
+	});
+
+	it("handles execution error from function", async () => {
+		const capability = createAutomationCapability("errorAutomation", {
+			title: "Error Automation",
+			description: "Throws an error",
+			execute: () => {
+				throw new Error("Something went wrong");
+			},
+		});
+
+		const event = {
+			pageId: "page-error",
+			actionType: "error_action",
+		};
+
+		await expect(capability.handler(event)).rejects.toThrow(ExecutionError);
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: Error: Something went wrong"}}</output>\n`,
+		);
+	});
+
+	it("handles execution error with non-Error object", async () => {
+		const capability = createAutomationCapability("nonErrorAutomation", {
+			title: "Non-Error Automation",
+			description: "Throws a non-Error object",
+			execute: () => {
+				throw "String error";
+			},
+		});
+
+		const event = {
+			actionType: "string_error_action",
+		};
+
+		await expect(capability.handler(event)).rejects.toThrow(ExecutionError);
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: String error"}}</output>\n`,
+		);
+	});
+});

package/src/capabilities/automation.ts

@@ -0,0 +1,130 @@
+import { ExecutionError } from "../error.js";
+import type { HandlerOptions } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+
+/**
+ * Event provided to automation execute functions
+ */
+export interface AutomationEvent {
+	/**
+	 * The ID of the page that triggered the automation (if applicable)
+	 */
+	pageId?: string;
+	/**
+	 * The type of automation action that was triggered
+	 */
+	actionType: string;
+	/**
+	 * The full page object from Notion's Public API (if triggered by a database page)
+	 */
+	pageData?: PageObjectResponse;
+}
+
+/**
+ * Page object from Notion's Public API
+ * This represents a database page with all its properties.
+ * Properties are in Notion's Public API format.
+ * See: https://developers.notion.com/reference/page
+ */
+export interface PageObjectResponse {
+	object: "page";
+	id: string;
+	created_time: string;
+	last_edited_time: string;
+	created_by: { id: string };
+	last_edited_by: { id: string };
+	cover: unknown;
+	icon: unknown;
+	parent: unknown;
+	archived: boolean;
+	properties: Record<string, unknown>;
+	url: string;
+	public_url?: string | null;
+}
+
+/**
+ * Configuration for an automation capability
+ */
+export interface AutomationConfiguration {
+	/**
+	 * Title of the automation - shown in the UI when selecting automations
+	 */
+	title: string;
+
+	/**
+	 * Description of what this automation does - shown in the UI
+	 */
+	description: string;
+
+	/**
+	 * The function that executes when the automation is triggered
+	 * @param event - Event data about the automation trigger, including page data if applicable
+	 * @param context - The capability execution context (Notion client, etc.)
+	 * @returns A promise that resolves when the automation completes
+	 */
+	execute: (
+		event: AutomationEvent,
+		context: CapabilityContext,
+	) => Promise<void> | void;
+}
+
+/**
+ * Result returned from automation execution
+ */
+export interface AutomationHandlerResult {
+	title: string;
+	description: string;
+}
+
+export type AutomationCapability = ReturnType<
+	typeof createAutomationCapability
+>;
+
+/**
+ * Creates an automation capability from configuration.
+ *
+ * @param key - The unique name for this capability.
+ * @param config - The automation configuration.
+ * @returns The capability object.
+ */
+export function createAutomationCapability(
+	key: string,
+	config: AutomationConfiguration,
+) {
+	return {
+		_tag: "automation" as const,
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+		},
+		async handler(
+			event: AutomationEvent,
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext();
+				await config.execute(event, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				} else {
+					process.stdout.write(
+						`\n<output>${JSON.stringify({ status: "success" })}</output>\n`,
+					);
+				}
+			} catch (err) {
+				const error = new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					process.stdout.write(
+						`\n<output>${JSON.stringify({ status: "error", error: { name: error.name, message: error.message } })}</output>\n`,
+					);
+				}
+
+				throw error;
+			}
+		},
+	};
+}

package/src/capabilities/context.ts

@@ -0,0 +1,23 @@
+import { Client } from "@notionhq/client";
+import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
+export type CapabilityContext = {
+	/** Notion API SDK client for this execution. */
+	notion: Client;
+};
+
+export function createCapabilityContext(): CapabilityContext {
+	const options: ClientOptions = {};
+
+	if (process.env.NOTION_API_BASE_URL) {
+		options.baseUrl = process.env.NOTION_API_BASE_URL;
+	}
+
+	if (process.env.NOTION_API_TOKEN) {
+		options.auth = process.env.NOTION_API_TOKEN;
+	}
+
+	const notion = new Client(options);
+
+	return { notion };
+}

package/src/capabilities/oauth.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createOAuthCapability } from "./oauth.js";
+
+describe("oauth", () => {
+	afterEach(() => {
+		// Clean up env changes between tests
+		delete process.env.OAUTH_676F6F676C6541757468_ACCESS_TOKEN;
+		delete process.env.OAUTH_676F6F676C652D63616C656E646172_ACCESS_TOKEN;
+	});
+
+	it("creates notion-managed oauth capability with accessToken helper", async () => {
+		const capability = createOAuthCapability("googleAuth", {
+			name: "googleAuth",
+			provider: "google",
+			accessTokenExpireMs: 60_000,
+		});
+
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("oauth");
+		expect(capability.config.type).toBe("notion_managed");
+		expect(capability.config.accessTokenExpireMs).toBe(60_000);
+
+		expect(typeof capability.accessToken).toBe("function");
+
+		process.env.OAUTH_676F6F676C6541757468_ACCESS_TOKEN = "token-123";
+		await expect(capability.accessToken()).resolves.toBe("token-123");
+	});
+
+	it("normalizes non-alphanumeric characters in the identifier", () => {
+		const capability = createOAuthCapability("googleCalendar", {
+			name: "google-calendar",
+			provider: "google",
+			accessTokenExpireMs: 3600_000,
+		});
+
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("oauth");
+		expect(capability.config.type).toBe("notion_managed");
+		expect(capability.config.accessTokenExpireMs).toBe(3600_000);
+	});
+
+	it("throws a helpful error when the token env var is missing", async () => {
+		const capability = createOAuthCapability("googleAuthMissing", {
+			name: "googleAuth",
+			provider: "google",
+		});
+
+		await expect(capability.accessToken()).rejects.toThrow(
+			/Missing OAuth access token env var "OAUTH_676F6F676C6541757468_ACCESS_TOKEN"/,
+		);
+	});
+});