@notionhq/workers 0.5.0 → 0.6.0

package/src/alpha/types.ts

@@ -0,0 +1,284 @@
+import type { NoticonName } from "./icon-names.js";
+
+export type { NoticonName } from "./icon-names.js";
+
+/**
+ * Valid colors for select options.
+ */
+export type SelectColor =
+	| "default"
+	| "gray"
+	| "brown"
+	| "orange"
+	| "yellow"
+	| "green"
+	| "blue"
+	| "purple"
+	| "pink"
+	| "red";
+
+/**
+ * A select option with an optional color.
+ */
+export interface SelectOption {
+	name: string;
+	color?: SelectColor;
+}
+
+/**
+ * Status group types in Notion.
+ */
+export type StatusGroupType = "To-do" | "In progress" | "Complete";
+
+/**
+ * Status group configuration.
+ */
+export interface StatusGroup {
+	name: StatusGroupType;
+	options: SelectOption[];
+}
+
+/**
+ * A text token is a tuple where the first element is the text content
+ * and optional subsequent elements are formatting annotations.
+ */
+type TextToken = [string, ...unknown[]];
+
+/**
+ * A TextValue is an array of text tokens, representing rich text content.
+ */
+export type TextValue = Array<TextToken>;
+
+/**
+ * Date object representing a single date without time.
+ */
+export interface NotionDate {
+	type: "date";
+	start_date: string; // Format: "YYYY-MM-DD"
+}
+
+/**
+ * Date object representing a date with time.
+ */
+export interface NotionDateTime {
+	type: "datetime";
+	start_date: string; // Format: "YYYY-MM-DD"
+	start_time: string; // Format: "HH:mm"
+	time_zone?: string; // e.g., "America/Los_Angeles"
+}
+
+/**
+ * Date object representing a date range.
+ */
+export interface DateRange {
+	type: "daterange";
+	start_date: string; // Format: "YYYY-MM-DD"
+	end_date: string; // Format: "YYYY-MM-DD"
+}
+
+/**
+ * Date object representing a date-time range.
+ */
+export interface DateTimeRange {
+	type: "datetimerange";
+	start_date: string; // Format: "YYYY-MM-DD"
+	start_time: string; // Format: "HH:mm"
+	end_date: string; // Format: "YYYY-MM-DD"
+	end_time: string; // Format: "HH:mm"
+	time_zone?: string;
+}
+
+/**
+ * All possible date value types.
+ */
+export type DateValue = NotionDate | NotionDateTime | DateRange | DateTimeRange;
+
+/**
+ * Person reference - represents a user in a people property.
+ */
+export interface PersonReference {
+	/**
+	 * The email address of the user
+	 */
+	email: string;
+}
+
+/**
+ * A PeopleValue is an array of person references.
+ */
+export type PeopleValue = PersonReference[];
+
+/**
+ * Place value representing a geographic location.
+ * Used for place properties in databases.
+ */
+export interface PlaceValue {
+	/**
+	 * Latitude coordinate (required)
+	 */
+	lat: number;
+	/**
+	 * Longitude coordinate (required)
+	 */
+	lon: number;
+	/**
+	 * Optional display name for the location
+	 */
+	name?: string;
+	/**
+	 * Optional street address
+	 */
+	address?: string;
+	/**
+	 * Optional Google Place ID for the location
+	 */
+	googlePlaceId?: string;
+}
+
+/**
+ * A reference to a related record by its primary key.
+ */
+export type RelationReference = {
+	type: "primaryKey";
+	value: string;
+};
+
+/**
+ * Relation value representing references to related records.
+ * Each reference identifies a record in the target database.
+ */
+export type RelationValue = RelationReference[];
+
+/**
+ * Number format types.
+ */
+export type NumberFormat =
+	| "number"
+	| "number_with_commas"
+	| "percent"
+	| "dollar"
+	| "euro"
+	| "pound"
+	| "yen"
+	| "rupee"
+	| "won"
+	| "yuan";
+
+/**
+ * Date format types.
+ */
+export type DateFormat = "relative" | "MM/DD/YYYY" | "DD/MM/YYYY" | "YYYY/MM/DD" | "ll" | "MMM d";
+
+/**
+ * Icon representing an emoji.
+ */
+export interface EmojiIcon {
+	type: "emoji";
+	value: string;
+}
+
+/**
+ * Valid colors for Notion icons.
+ */
+export type NoticonColor =
+	| "gray"
+	| "lightgray"
+	| "brown"
+	| "yellow"
+	| "orange"
+	| "green"
+	| "blue"
+	| "purple"
+	| "pink"
+	| "red";
+
+/**
+ * Icon representing a Notion built-in icon.
+ */
+export interface NoticonIcon {
+	type: "notion";
+	/**
+	 * The name of the Notion icon (e.g., "checkmark", "pizza", "rocket")
+	 */
+	icon: NoticonName;
+	/**
+	 * The color variant of the icon
+	 */
+	color: NoticonColor;
+}
+
+/**
+ * Icon representing an external image URL.
+ */
+export interface ImageIcon {
+	type: "image";
+	/**
+	 * The URL of the image (must be a valid http/https URL)
+	 */
+	url: string;
+}
+
+/**
+ * All possible icon types.
+ */
+export type Icon = EmojiIcon | NoticonIcon | ImageIcon;
+
+/**
+ * Cover image for a Notion page.
+ */
+export interface ImageCover {
+	type: "image";
+	/**
+	 * The URL of the image (must be a valid http/https URL)
+	 */
+	url: string;
+	/**
+	 * Vertical image position, from 0 (top) to 1 (bottom).
+	 */
+	position?: number;
+}
+
+/**
+ * All possible cover types.
+ */
+export type Cover = ImageCover;
+
+/**
+ * A unit of time used in interval strings.
+ * - "m": minutes
+ * - "h": hours
+ * - "d": days
+ */
+export type TimeUnit = "m" | "h" | "d";
+
+/**
+ * A string representing an interval, e.g. "30m", "1h", "7d".
+ */
+export type IntervalString = `${number}${TimeUnit}`;
+
+/**
+ * Schedule configuration for sync capabilities.
+ * - "continuous": Run as frequently as the system allows
+ * - "manual": Only run when explicitly triggered
+ * - IntervalString: Run at specified intervals, e.g. "30m", "1h", "1d"
+ */
+export type Schedule = "continuous" | "manual" | IntervalString;
+
+/**
+ * Normalized schedule representation stored in the backend.
+ */
+export type NormalizedSchedule =
+	| { type: "continuous" }
+	| { type: "manual" }
+	| { type: "interval"; intervalMs: number };
+
+/**
+ * Options for invoking a capability handler.
+ */
+export type HandlerOptions = {
+	/**
+	 * Return the concrete result instead of writing the notion_output
+	 * envelope to stdout. Used by tests.
+	 */
+	concreteOutput?: true;
+};

package/src/alpha/workflow.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+
+import { ExecutionError } from "./error.js";
+import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
+import { createWorkflow } from "./workflow.js";
+
+let stdoutSpy: Mock<typeof process.stdout.write>;
+
+beforeEach(() => {
+	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+	stdoutSpy.mockRestore();
+});
+
+const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
+
+describe("createWorkflow", () => {
+	it("is tagged and exposes triggers in config", () => {
+		const workflow = createWorkflow({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {},
+		});
+
+		expect(workflow._tag).toBe("workflow");
+		expect(workflow.config).toEqual({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [{ type: "notion.page.created" }],
+		});
+	});
+
+	it("writes a success envelope after the handler runs", async () => {
+		const handler = vi.fn();
+		const workflow = createWorkflow({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler,
+		});
+
+		await workflow.handler(event);
+
+		expect(handler).toHaveBeenCalledWith(event, expect.anything());
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"success","value":{"status":"success"}}</__notion_output__>\n`,
+		);
+	});
+
+	it("returns the status without an envelope under concreteOutput", async () => {
+		const workflow = createWorkflow({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {},
+		});
+
+		await expect(workflow.handler(event, { concreteOutput: true })).resolves.toEqual({
+			status: "success",
+		});
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("writes an error envelope and throws ExecutionError on failure", async () => {
+		const workflow = createWorkflow({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {
+				throw new Error("boom");
+			},
+		});
+
+		await expect(workflow.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"name":"ExecutionError","message":"Error during worker execution: Error: boom"`,
+			),
+		);
+	});
+});

package/src/alpha/workflow.ts

@@ -0,0 +1,131 @@
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import { ExecutionError } from "./error.js";
+import { writeOutput } from "./output.js";
+import type { WorkflowEventMap, WorkflowTrigger } from "./triggers.generated.js";
+import type { HandlerOptions } from "./types.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 passed to {@link createWorkflow}.
+ */
+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;
+
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		context: CapabilityContext,
+	) => Promise<void> | void;
+};
+
+/**
+ * A workflow capability as returned by {@link createWorkflow}.
+ *
+ * Note that a workflow carries no key of its own — the build tool derives
+ * the capability key from the file the workflow is default-exported from.
+ */
+export type Workflow<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]] = readonly [
+		WorkflowTrigger,
+		...WorkflowTrigger[],
+	],
+> = {
+	_tag: "workflow";
+	config: {
+		title: string;
+		description: string;
+		triggers: TTriggers;
+	};
+	handler: (
+		event: WorkflowEventForTriggers<TTriggers>,
+		options?: HandlerOptions,
+	) => Promise<{ status: "success" } | undefined>;
+};
+
+/**
+ * Create a workflow capability.
+ *
+ * Default-export the result from a file directly under `src/workflows/` —
+ * the file's basename becomes the workflow's key.
+ *
+ * @example
+ * ```ts
+ * // src/workflows/onPageCreated.ts
+ * import { triggers } from "@notionhq/workers/alpha/triggers";
+ * import { createWorkflow } from "@notionhq/workers/alpha/workflow";
+ *
+ * export default createWorkflow({
+ *   title: "Send Welcome Email",
+ *   description: "Sends a welcome email when a new page is added",
+ *   triggers: [triggers.notionPageCreated()],
+ *   handler: async (event) => {
+ *     console.log(event.page);
+ *   },
+ * });
+ * ```
+ */
+export function createWorkflow<
+	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+>(configuration: WorkflowConfiguration<TTriggers>): Workflow<TTriggers> {
+	return {
+		_tag: "workflow",
+		config: {
+			title: configuration.title,
+			description: configuration.description,
+			triggers: configuration.triggers,
+		},
+		async handler(
+			event: WorkflowEventForTriggers<TTriggers>,
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext("workflow");
+				await configuration.handler(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/builder.test.ts

@@ -1,13 +1,12 @@
 import { describe, expect, it } from "vitest";
+
 import * as Builder from "./builder.js";
 
 /**
  * Helper to extract the DateValue from a date token.
  * Date tokens have the shape [["\u2023", [["d", dateValue]]]].
  */
-// biome-ignore lint/suspicious/noExplicitAny: test helper
 function extractDateValue(token: unknown): any {
-	// biome-ignore lint/suspicious/noExplicitAny: test helper
 	const arr = token as any;
 	return arr[0][1][0][1];
 }
@@ -59,9 +58,7 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("parses ISO 8601 with positive timezone offset", () => {
-		expect(
-			extractDateValue(Builder.dateTime("2024-01-15T10:30:00+05:30")),
-		).toEqual({
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00+05:30"))).toEqual({
 			type: "datetime",
 			start_date: "2024-01-15",
 			start_time: "10:30",
@@ -69,9 +66,7 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("parses ISO 8601 with negative timezone offset", () => {
-		expect(
-			extractDateValue(Builder.dateTime("2024-01-15T10:30:00-08:00")),
-		).toEqual({
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00-08:00"))).toEqual({
 			type: "datetime",
 			start_date: "2024-01-15",
 			start_time: "10:30",
@@ -79,9 +74,7 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("parses ISO 8601 with milliseconds", () => {
-		expect(
-			extractDateValue(Builder.dateTime("2024-01-15T10:30:00.000Z")),
-		).toEqual({
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00.000Z"))).toEqual({
 			type: "datetime",
 			start_date: "2024-01-15",
 			start_time: "10:30",
@@ -89,11 +82,7 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("includes timeZone when provided", () => {
-		expect(
-			extractDateValue(
-				Builder.dateTime("2024-01-15T10:30", "America/New_York"),
-			),
-		).toEqual({
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30", "America/New_York"))).toEqual({
 			type: "datetime",
 			start_date: "2024-01-15",
 			start_time: "10:30",
@@ -118,15 +107,11 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("rejects date-only strings", () => {
-		expect(() => Builder.dateTime("2024-01-15")).toThrow(
-			"Invalid ISO 8601 datetime",
-		);
+		expect(() => Builder.dateTime("2024-01-15")).toThrow("Invalid ISO 8601 datetime");
 	});
 
 	it("rejects plain text", () => {
-		expect(() => Builder.dateTime("not a date")).toThrow(
-			"Invalid ISO 8601 datetime",
-		);
+		expect(() => Builder.dateTime("not a date")).toThrow("Invalid ISO 8601 datetime");
 	});
 
 	it("rejects empty string", () => {
@@ -134,17 +119,13 @@ describe("Builder.dateTime", () => {
 	});
 
 	it("rejects date with space instead of T", () => {
-		expect(() => Builder.dateTime("2024-01-15 10:30")).toThrow(
-			"Invalid ISO 8601 datetime",
-		);
+		expect(() => Builder.dateTime("2024-01-15 10:30")).toThrow("Invalid ISO 8601 datetime");
 	});
 });
 
 describe("Builder.dateRange", () => {
 	it("creates a date range token", () => {
-		expect(
-			extractDateValue(Builder.dateRange("2024-01-15", "2024-01-20")),
-		).toEqual({
+		expect(extractDateValue(Builder.dateRange("2024-01-15", "2024-01-20"))).toEqual({
 			type: "daterange",
 			start_date: "2024-01-15",
 			end_date: "2024-01-20",
@@ -152,40 +133,31 @@ describe("Builder.dateRange", () => {
 	});
 
 	it("rejects invalid start date", () => {
-		expect(() => Builder.dateRange("bad", "2024-01-20")).toThrow(
-			"Expected YYYY-MM-DD",
-		);
+		expect(() => Builder.dateRange("bad", "2024-01-20")).toThrow("Expected YYYY-MM-DD");
 	});
 
 	it("rejects invalid end date", () => {
-		expect(() => Builder.dateRange("2024-01-15", "bad")).toThrow(
-			"Expected YYYY-MM-DD",
-		);
+		expect(() => Builder.dateRange("2024-01-15", "bad")).toThrow("Expected YYYY-MM-DD");
 	});
 });
 
 describe("Builder.dateTimeRange", () => {
 	it("creates a datetime range token from ISO strings", () => {
-		expect(
-			extractDateValue(
-				Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16T14:00"),
-			),
-		).toEqual({
-			type: "datetimerange",
-			start_date: "2024-01-15",
-			start_time: "10:30",
-			end_date: "2024-01-16",
-			end_time: "14:00",
-		});
+		expect(extractDateValue(Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16T14:00"))).toEqual(
+			{
+				type: "datetimerange",
+				start_date: "2024-01-15",
+				start_time: "10:30",
+				end_date: "2024-01-16",
+				end_time: "14:00",
+			},
+		);
 	});
 
 	it("parses mixed ISO formats", () => {
 		expect(
 			extractDateValue(
-				Builder.dateTimeRange(
-					"2024-01-15T10:30:00Z",
-					"2024-01-16T14:00:00.000+05:00",
-				),
+				Builder.dateTimeRange("2024-01-15T10:30:00Z", "2024-01-16T14:00:00.000+05:00"),
 			),
 		).toEqual({
 			type: "datetimerange",
@@ -199,11 +171,7 @@ describe("Builder.dateTimeRange", () => {
 	it("includes timeZone when provided", () => {
 		expect(
 			extractDateValue(
-				Builder.dateTimeRange(
-					"2024-01-15T10:30",
-					"2024-01-16T14:00",
-					"Europe/London",
-				),
+				Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16T14:00", "Europe/London"),
 			),
 		).toEqual({
 			type: "datetimerange",
@@ -216,14 +184,14 @@ describe("Builder.dateTimeRange", () => {
 	});
 
 	it("rejects invalid start datetime", () => {
-		expect(() =>
-			Builder.dateTimeRange("2024-01-15", "2024-01-16T14:00"),
-		).toThrow("Invalid ISO 8601 datetime");
+		expect(() => Builder.dateTimeRange("2024-01-15", "2024-01-16T14:00")).toThrow(
+			"Invalid ISO 8601 datetime",
+		);
 	});
 
 	it("rejects invalid end datetime", () => {
-		expect(() =>
-			Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16"),
-		).toThrow("Invalid ISO 8601 datetime");
+		expect(() => Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16")).toThrow(
+			"Invalid ISO 8601 datetime",
+		);
 	});
 });