@notionhq/workers 0.0.82

package/src/json-schema.ts

@@ -0,0 +1,179 @@
+/**
+ * JSON Schema types compatible with both Anthropic and OpenAI structured
+ * output APIs.
+ *
+ * Constraints enforced by this type (intersection of both providers):
+ * - Objects must have `additionalProperties: false`
+ * - All object properties should be listed in `required`
+ *   (use `anyOf` with `null` for optional fields)
+ * - No recursive schemas
+ * - No `allOf`, `not`, `if/then/else`
+ * - No string constraints (`minLength`, `maxLength`, `pattern`)
+ * - No number constraints (`minimum`, `maximum`, `multipleOf`)
+ * - Array `minItems` limited to 0 or 1; no `maxItems`
+ * - String `format` limited to: date-time, time, date, duration,
+ *   email, hostname, ipv4, ipv6, uuid
+ * - `$ref` and `$defs` supported (no external refs)
+ */
+
+/**
+ * String formats supported by both Anthropic and OpenAI structured outputs.
+ */
+export type JSONSchemaStringFormat =
+	| "date-time"
+	| "time"
+	| "date"
+	| "duration"
+	| "email"
+	| "hostname"
+	| "ipv4"
+	| "ipv6"
+	| "uuid";
+
+// ---- Unsupported composition keywords ----
+// Explicitly typed as `never` on concrete schema defs to produce clear
+// errors when someone accidentally adds them.
+
+interface ForbiddenCompositionKeywords {
+	anyOf?: never;
+	allOf?: never;
+	not?: never;
+	if?: never;
+	then?: never;
+	else?: never;
+}
+
+// ---- Individual schema definitions ----
+
+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 {
+	type: "number" | "integer";
+	description?: string;
+	enum?: readonly T[];
+}
+
+export interface JSONSchemaBooleanDef extends ForbiddenCompositionKeywords {
+	type: "boolean";
+	description?: string;
+}
+
+export interface JSONSchemaNullDef extends ForbiddenCompositionKeywords {
+	type: "null";
+	description?: string;
+}
+
+export interface JSONSchemaArrayDef<E = unknown>
+	extends ForbiddenCompositionKeywords {
+	type: "array";
+	description?: string;
+	items: JSONSchema<E>;
+	minItems?: 0 | 1;
+}
+
+export interface JSONSchemaObjectDef<
+	T extends Record<string, unknown> = Record<string, unknown>,
+> extends ForbiddenCompositionKeywords {
+	type: "object";
+	description?: string;
+	properties: { [K in keyof T]-?: JSONSchema<T[K]> };
+	required: readonly (keyof T & string)[];
+	additionalProperties: false;
+	$defs?: Record<string, AnyJSONSchema>;
+}
+
+export interface JSONSchemaRefDef extends ForbiddenCompositionKeywords {
+	$ref: string;
+	description?: string;
+}
+
+// Note: JSONSchemaAnyOfDef intentionally does NOT extend
+// ForbiddenCompositionKeywords — it IS the composition keyword.
+export interface JSONSchemaAnyOfDef<T = unknown> {
+	anyOf: readonly JSONSchema<T>[];
+	description?: string;
+}
+
+// ---- Unconstrained schema (when T is unknown) ----
+
+export type AnyJSONSchema =
+	| JSONSchemaStringDef
+	| JSONSchemaNumberDef
+	| JSONSchemaBooleanDef
+	| JSONSchemaNullDef
+	| JSONSchemaArrayDef
+	| JSONSchemaObjectDef
+	| JSONSchemaRefDef
+	| JSONSchemaAnyOfDef;
+
+// ---- Internal type resolution ----
+
+/**
+ * Maps a TypeScript type T to its corresponding JSON Schema definition.
+ *
+ * Uses `[T] extends [X]` (non-distributing) so that union types like
+ * `string | number` fall through to `AnyJSONSchema` instead of distributing
+ * into `JSONSchemaStringDef | JSONSchemaNumberDef`.
+ *
+ * The `T & X` intersections (e.g. `T & string`) satisfy the generic
+ * constraints on each def without widening T.
+ *
+ * A `$ref` is always valid in any schema position, so `JSONSchemaRefDef`
+ * is unioned in at the end.
+ */
+type JSONSchemaFor<T> =
+	| JSONSchemaRefDef
+	| ([T] extends [string]
+			? JSONSchemaStringDef<T & string>
+			: [T] extends [number]
+				? JSONSchemaNumberDef<T & number>
+				: [T] extends [boolean]
+					? JSONSchemaBooleanDef
+					: [T] extends [readonly (infer E)[]]
+						? JSONSchemaArrayDef<E>
+						: [T] extends [Record<string, unknown>]
+							? JSONSchemaObjectDef<T & Record<string, unknown>>
+							: AnyJSONSchema);
+
+/**
+ * Wraps a non-null schema in an `anyOf` with `{ type: "null" }` for
+ * nullable types (e.g. `string | null`).
+ */
+type JSONSchemaNullable<T> = {
+	anyOf: readonly [JSONSchemaFor<T>, JSONSchemaNullDef];
+	description?: string;
+};
+
+// ---- Main exported type ----
+
+/**
+ * A JSON Schema definition compatible with both Anthropic and OpenAI
+ * structured output APIs.
+ *
+ * When the generic parameter `T` is provided, the schema structure is
+ * constrained at compile time to match `T`:
+ *
+ * ```ts
+ * // Schema is checked against the type:
+ * const schema: JSONSchema<{ name: string }> = {
+ *   type: "object",
+ *   properties: { name: { type: "string" } },
+ *   required: ["name"],
+ *   additionalProperties: false,
+ * };
+ * ```
+ *
+ * @template T - The TypeScript type the schema should describe.
+ */
+export type JSONSchema<T = unknown> = unknown extends T
+	? AnyJSONSchema
+	: null extends T
+		? JSONSchemaNullable<NonNullable<T>>
+		: JSONSchemaFor<T>;

package/src/schema.ts

@@ -0,0 +1,241 @@
+import type {
+	DateFormat,
+	Icon,
+	NumberFormat,
+	SelectOption,
+	StatusGroup,
+} from "./types.js";
+
+/**
+ * Supported property types for sync schemas.
+ */
+export type PropertyType =
+	| "title"
+	| "rich_text"
+	| "url"
+	| "email"
+	| "phone_number"
+	| "checkbox"
+	| "file"
+	| "number"
+	| "date"
+	| "select"
+	| "multi_select"
+	| "status"
+	| "people"
+	| "place";
+
+/**
+ * Definition of a single property in a sync schema.
+ */
+export type PropertyDefinition = {
+	type: PropertyType;
+};
+
+/**
+ * A schema defining the structure a single property in a data source.
+ */
+export type PropertyConfiguration =
+	| { type: "title" }
+	| { type: "text" }
+	| { type: "url" }
+	| { type: "email" }
+	| { type: "phone_number" }
+	| { type: "checkbox" }
+	| { type: "file" }
+	| {
+			type: "number";
+			format?: NumberFormat;
+	  }
+	| {
+			type: "date";
+			date_format?: DateFormat;
+	  }
+	| {
+			type: "select";
+			options: SelectOption[];
+	  }
+	| {
+			type: "multi_select";
+			options: SelectOption[];
+	  }
+	| {
+			type: "status";
+			groups: StatusGroup[];
+	  }
+	| { type: "people" }
+	| { type: "place" }
+	| {
+			type: "relation";
+			/**
+			 * The export name of the sync capability that defines the related collection.
+			 * This must match the export name used when defining the related sync capability.
+			 */
+			relatedSyncKey: string;
+			config: { twoWay: false } | { twoWay: true; relatedPropertyName: string };
+	  };
+
+export type Schema<PK extends string> = {
+	/**
+	 * The default name for the database when it is first created.
+	 *
+	 * Updating this after the database has been created will not change the
+	 * name of the database.
+	 */
+	defaultName: string;
+	/**
+	 * Optional icon to use as the icon for the database page.
+	 * If not provided, defaults to 📋.
+	 * Use the `icon()` builder to create an icon value.
+	 */
+	databaseIcon?: Icon;
+	properties: PropertySchema<PK>;
+	/**
+	 * Optional configuration for sub-item relations.
+	 * If provided, the parent and child properties must be part of a two-way self-relation.
+	 */
+	subItems?: {
+		parentPropertyName: string;
+		childPropertyName: string;
+	};
+};
+
+/**
+ * A schema defining the structure of properties in a data source.
+ */
+export type PropertySchema<PK extends string> = {
+	[PrimaryKey in PK]: PropertyConfiguration;
+} & {
+	[propertyName: string]: PropertyConfiguration;
+};
+
+/**
+ * Creates a title property definition.
+ */
+export function title(): PropertyConfiguration {
+	return { type: "title" };
+}
+
+/**
+ * Creates a rich text property definition.
+ */
+export function richText(): PropertyConfiguration {
+	return { type: "text" };
+}
+
+/**
+ * Creates a URL property definition.
+ */
+export function url(): PropertyConfiguration {
+	return { type: "url" };
+}
+
+/**
+ * Creates an email property definition.
+ */
+export function email(): PropertyConfiguration {
+	return { type: "email" };
+}
+
+/**
+ * Creates a phone number property definition.
+ */
+export function phoneNumber(): PropertyConfiguration {
+	return { type: "phone_number" };
+}
+
+/**
+ * Creates a checkbox property definition.
+ */
+export function checkbox(): PropertyConfiguration {
+	return { type: "checkbox" };
+}
+
+/**
+ * Creates a file property definition.
+ */
+export function file(): PropertyConfiguration {
+	return { type: "file" };
+}
+
+/**
+ * Creates a number property definition with optional formatting.
+ */
+export function number(format?: NumberFormat): PropertyConfiguration {
+	return format ? { type: "number", format } : { type: "number" };
+}
+
+/**
+ * Creates a date property definition with optional formatting.
+ */
+export function date(date_format?: DateFormat): PropertyConfiguration {
+	return date_format ? { type: "date", date_format } : { type: "date" };
+}
+
+/**
+ * Creates a select property definition with predefined options.
+ */
+export function select(options: SelectOption[]): PropertyConfiguration {
+	return { type: "select", options };
+}
+
+/**
+ * Creates a multi-select property definition with predefined options.
+ */
+export function multiSelect(options: SelectOption[]): PropertyConfiguration {
+	return { type: "multi_select", options };
+}
+
+/**
+ * Creates a status property definition with groups.
+ */
+export function status(config: {
+	groups: StatusGroup[];
+}): PropertyConfiguration {
+	return { type: "status", groups: config.groups };
+}
+
+/**
+ * Creates a people property definition.
+ */
+export function people(): PropertyConfiguration {
+	return { type: "people" };
+}
+
+/**
+ * Creates a place property definition for storing geographic locations.
+ */
+export function place(): PropertyConfiguration {
+	return { type: "place" };
+}
+
+/**
+ * Creates a relation property definition that references another sync capability.
+ * The related collection must be defined by a sync capability in the same worker.
+ *
+ * @param relatedSyncKey - The export name of the sync capability that defines the related collection.
+ * @example
+ * ```typescript
+ * export const projectsSync = sync({...});
+ *
+ * export const tasksSync = sync({
+ *   schema: {
+ *     properties: {
+ *       "Task Title": Schema.title(),
+ *       "Project": Schema.relation("projectsSync"),
+ *     },
+ *   },
+ *   ...
+ * });
+ * ```
+ */
+export function relation(
+	relatedSyncKey: string,
+	config?: { twoWay: false } | { twoWay: true; relatedPropertyName: string },
+): PropertyConfiguration {
+	return {
+		type: "relation",
+		relatedSyncKey,
+		config: config ?? { twoWay: false },
+	};
+}

package/src/types.ts

@@ -0,0 +1,272 @@
+/**
+ * A JSON value is a string, number, boolean, null, array, or object.
+ */
+export type JSONValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JSONValue[]
+	| { [key: string]: JSONValue };
+
+/**
+ * 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>;
+
+/**
+ * Select option color types supported by Notion
+ */
+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[];
+}
+
+/**
+ * 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;
+
+/**
+ * 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";
+
+import type { NoticonName } from "./icon-names.js";
+
+/**
+ * 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;
+
+/**
+ * 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[];
+
+export type { NoticonName } from "./icon-names.js";
+
+/**
+ * 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 collection.
+ */
+export type RelationValue = RelationReference[];
+
+/**
+ * Time units for schedule intervals.
+ * - "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
+ * - IntervalString: Run at specified intervals, e.g. "30m", "1h", "1d"
+ */
+export type Schedule = "continuous" | IntervalString;
+
+/**
+ * Normalized schedule representation stored in the backend.
+ */
+export type SyncSchedule =
+	| { type: "continuous" }
+	| { type: "interval"; intervalMs: number };
+
+export type HandlerOptions = {
+	concreteOutput?: true;
+};