@notionhq/workers 0.5.0 → 0.6.0

package/src/alpha/builder.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+
+import { Builder } from "./builder.js";
+
+/**
+ * Helper to extract the DateValue from a date token.
+ * Date tokens have the shape [["\u2023", [["d", dateValue]]]].
+ */
+function extractDateValue(token: unknown): any {
+	const arr = token as any;
+	return arr[0][1][0][1];
+}
+
+describe("Builder.date", () => {
+	it("creates a date token from YYYY-MM-DD", () => {
+		expect(extractDateValue(Builder.date("2024-01-15"))).toEqual({
+			type: "date",
+			start_date: "2024-01-15",
+		});
+	});
+
+	it("rejects non-YYYY-MM-DD strings", () => {
+		expect(() => Builder.date("01-15-2024")).toThrow("Expected YYYY-MM-DD");
+		expect(() => Builder.date("2024/01/15")).toThrow("Expected YYYY-MM-DD");
+		expect(() => Builder.date("2024-1-5")).toThrow("Expected YYYY-MM-DD");
+	});
+
+	it("rejects invalid calendar dates", () => {
+		expect(() => Builder.date("2024-13-01")).toThrow();
+		// Note: "2024-02-30" is silently coerced by JS Date (rolls to March 1st),
+		// so the current validator does not catch it.
+	});
+});
+
+describe("Builder.dateTime", () => {
+	it("parses minimal ISO 8601 (YYYY-MM-DDTHH:mm)", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("parses ISO 8601 with seconds", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:45"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("parses ISO 8601 with Z suffix", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00Z"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("parses ISO 8601 with positive timezone offset", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00+05:30"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("parses ISO 8601 with negative timezone offset", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00-08:00"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("parses ISO 8601 with milliseconds", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30:00.000Z"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+		});
+	});
+
+	it("includes timeZone when provided", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T10:30", "America/New_York"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+			time_zone: "America/New_York",
+		});
+	});
+
+	it("handles midnight", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T00:00"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "00:00",
+		});
+	});
+
+	it("handles end of day", () => {
+		expect(extractDateValue(Builder.dateTime("2024-01-15T23:59"))).toEqual({
+			type: "datetime",
+			start_date: "2024-01-15",
+			start_time: "23:59",
+		});
+	});
+
+	it("rejects date-only strings", () => {
+		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");
+	});
+
+	it("rejects empty string", () => {
+		expect(() => Builder.dateTime("")).toThrow("Invalid ISO 8601 datetime");
+	});
+
+	it("rejects date with space instead of T", () => {
+		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({
+			type: "daterange",
+			start_date: "2024-01-15",
+			end_date: "2024-01-20",
+		});
+	});
+
+	it("rejects invalid start date", () => {
+		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");
+	});
+});
+
+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",
+			},
+		);
+	});
+
+	it("parses mixed ISO formats", () => {
+		expect(
+			extractDateValue(
+				Builder.dateTimeRange("2024-01-15T10:30:00Z", "2024-01-16T14:00:00.000+05:00"),
+			),
+		).toEqual({
+			type: "datetimerange",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+			end_date: "2024-01-16",
+			end_time: "14:00",
+		});
+	});
+
+	it("includes timeZone when provided", () => {
+		expect(
+			extractDateValue(
+				Builder.dateTimeRange("2024-01-15T10:30", "2024-01-16T14:00", "Europe/London"),
+			),
+		).toEqual({
+			type: "datetimerange",
+			start_date: "2024-01-15",
+			start_time: "10:30",
+			end_date: "2024-01-16",
+			end_time: "14:00",
+			time_zone: "Europe/London",
+		});
+	});
+
+	it("rejects invalid start 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",
+		);
+	});
+});

package/src/alpha/builder.ts

@@ -0,0 +1,338 @@
+import type { NoticonName } from "./icon-names.js";
+import type {
+	Cover,
+	DateValue,
+	Icon,
+	NoticonColor,
+	PeopleValue,
+	PlaceValue,
+	RelationReference,
+	TextValue,
+} from "./types.js";
+
+/**
+ * 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 [["‣", [["d", dateValue]]]];
+}
+
+/**
+ * Parses an ISO 8601 datetime string into date and time components.
+ * Accepts formats like "2024-01-15T10:30", "2024-01-15T10:30:00Z",
+ * "2024-01-15T10:30:00.000+05:00", etc.
+ */
+function parseISODateTime(isoString: string): { date: string; time: string } {
+	if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(isoString)) {
+		throw new Error(
+			`Invalid ISO 8601 datetime: ${isoString}. Expected format like 2024-01-15T10:30 or 2024-01-15T10:30:00Z`,
+		);
+	}
+
+	const date = isoString.slice(0, 10);
+	const time = isoString.slice(11, 16);
+
+	if (Number.isNaN(new Date(isoString).getTime())) {
+		throw new Error(`Invalid datetime: ${isoString}`);
+	}
+
+	return { date, time };
+}
+
+/**
+ * Builders for property values in sync changes.
+ *
+ * @example
+ * ```ts
+ * import { Builder } from "@notionhq/workers/alpha/builder";
+ *
+ * const change = {
+ *   type: "upsert",
+ *   key: "task-1",
+ *   properties: {
+ *     "Task Name": Builder.title("Write docs"),
+ *     Status: Builder.select("Open"),
+ *     Due: Builder.date("2026-08-01"),
+ *     Assignees: Builder.people("alice@example.com"),
+ *   },
+ * };
+ * ```
+ */
+export const Builder = {
+	/**
+	 * Creates a rich text value.
+	 */
+	richText(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates a URL value.
+	 */
+	url(url: string): TextValue {
+		return [[url]];
+	},
+
+	/**
+	 * Creates a title value.
+	 */
+	title(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates a text value.
+	 */
+	text(content: string): TextValue {
+		return [[content]];
+	},
+
+	/**
+	 * Creates an email value.
+	 */
+	email(email: string): TextValue {
+		return [[email]];
+	},
+
+	/**
+	 * Creates a phone number value.
+	 */
+	phoneNumber(phone: string): TextValue {
+		return [[phone]];
+	},
+
+	/**
+	 * Creates a checkbox value.
+	 */
+	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)
+	 */
+	file(fileUrl: string, fileName?: string): TextValue {
+		return [[fileName ?? fileUrl, [["a", fileUrl]]]];
+	},
+
+	/**
+	 * Creates a number value.
+	 */
+	number(value: number): TextValue {
+		if (Number.isNaN(value)) {
+			return [];
+		}
+		return [[value.toString()]];
+	},
+
+	/**
+	 * Creates a date value from a date string (YYYY-MM-DD).
+	 */
+	date(dateString: string): TextValue {
+		validateDateString(dateString);
+
+		return createDateToken({
+			type: "date",
+			start_date: dateString,
+		});
+	},
+
+	/**
+	 * Creates a datetime value from an ISO 8601 datetime string.
+	 * @param isoString - An ISO 8601 datetime string (e.g., "2024-01-15T10:30", "2024-01-15T10:30:00Z")
+	 * @param timeZone - Optional IANA timezone name (e.g., "America/New_York")
+	 */
+	dateTime(isoString: string, timeZone?: string): TextValue {
+		const { date, time } = parseISODateTime(isoString);
+
+		const dateValue: DateValue = {
+			type: "datetime",
+			start_date: date,
+			start_time: time,
+		};
+
+		if (timeZone) {
+			dateValue.time_zone = timeZone;
+		}
+
+		return createDateToken(dateValue);
+	},
+
+	/**
+	 * Creates a date range value from date strings.
+	 */
+	dateRange(startDate: string, endDate: string): TextValue {
+		validateDateString(startDate);
+		validateDateString(endDate);
+
+		return createDateToken({
+			type: "daterange",
+			start_date: startDate,
+			end_date: endDate,
+		});
+	},
+
+	/**
+	 * Creates a datetime range value from ISO 8601 datetime strings.
+	 * @param startDateTime - An ISO 8601 datetime string for the range start
+	 * @param endDateTime - An ISO 8601 datetime string for the range end
+	 * @param timeZone - Optional IANA timezone name (e.g., "America/New_York")
+	 */
+	dateTimeRange(startDateTime: string, endDateTime: string, timeZone?: string): TextValue {
+		const start = parseISODateTime(startDateTime);
+		const end = parseISODateTime(endDateTime);
+
+		const dateValue: DateValue = {
+			type: "datetimerange",
+			start_date: start.date,
+			start_time: start.time,
+			end_date: end.date,
+			end_time: end.time,
+		};
+
+		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
+	 */
+	link(displayText: string, url: string): TextValue {
+		return [[displayText, [["a", url]]]];
+	},
+
+	/**
+	 * Creates a select value from a single option.
+	 */
+	select(value: string): TextValue {
+		return [[value]];
+	},
+
+	/**
+	 * Creates a multi-select value from multiple options.
+	 * @param values - Array of option names to select
+	 */
+	multiSelect(...values: string[]): TextValue {
+		if (values.length === 0) {
+			return [];
+		}
+		return [[values.join(",")]];
+	},
+
+	/**
+	 * Creates a status value from a status option name.
+	 */
+	status(value: string): TextValue {
+		return [[value]];
+	},
+
+	/**
+	 * Creates a people value from email addresses.
+	 * @param emails - Array of email addresses for people to include
+	 */
+	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
+	 */
+	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")] }
+	 * ```
+	 */
+	relation(primaryKey: string): RelationReference {
+		return { type: "primaryKey", value: primaryKey };
+	},
+
+	/**
+	 * Creates an emoji icon.
+	 * @param emoji - An emoji string (e.g., "🎯", "✨", "🚀")
+	 */
+	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")
+	 */
+	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")
+	 */
+	imageIcon(url: string): Icon {
+		return {
+			type: "image",
+			url,
+		};
+	},
+
+	/**
+	 * Creates an image cover from an external URL.
+	 * @param url - The URL of the image (e.g., "https://example.com/cover.png")
+	 * @param position - Vertical image position, from 0 (top) to 1 (bottom). Defaults to 0.5.
+	 */
+	imageCover(url: string, position = 0.5): Cover {
+		if (!Number.isFinite(position) || position < 0 || position > 1) {
+			throw new Error(`Invalid cover position: ${position}. Expected a number between 0 and 1.`);
+		}
+
+		return {
+			type: "image",
+			url,
+			position,
+		};
+	},
+};