@notionhq/custom-blocks 0.0.58

package/src/bridge/dataSources/dataSource.ts

@@ -0,0 +1,63 @@
+import * as v from "valibot"
+import { notionDataSourceIdSchema, notionSpaceIdSchema } from "../ids.js"
+import { notionPropertySchemaSchema } from "./propertySchema.js"
+
+const collectionPointerValidator = v.object({
+	id: notionDataSourceIdSchema,
+	table: v.string(),
+	spaceId: v.optional(notionSpaceIdSchema),
+})
+
+export type NotionCollectionPointer = v.InferOutput<
+	typeof collectionPointerValidator
+>
+
+export const notionCollectionSchemaValidator = v.object({
+	id: v.optional(notionDataSourceIdSchema),
+	propertiesById: v.record(v.string(), notionPropertySchemaSchema),
+})
+
+export type NotionCollectionSchema = v.InferOutput<
+	typeof notionCollectionSchemaValidator
+>
+
+/**
+ * Bridge shape for a single data source: a semantic key bound (optionally) to a collection,
+ * its property name → ID mapping, and its column schemas.
+ */
+export const notionDataSourceSchema = v.object({
+	key: v.string(),
+	collectionPointer: v.optional(collectionPointerValidator),
+	collectionSchema: v.optional(notionCollectionSchemaValidator),
+	/**
+	 * Keyed mapping of user-defined keys to a raw property ID. A key mapped to `undefined`
+	 * is a declared-but-unbound slot.
+	 */
+	propertyIdsByKey: v.record(v.string(), v.optional(v.string())),
+	/**
+	 * Keyed mapping of raw property IDs to their schema. Always includes the four built-ins
+	 * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+	 */
+	propertySchemasById: v.record(v.string(), notionPropertySchemaSchema),
+})
+
+export type NotionDataSource = v.InferOutput<typeof notionDataSourceSchema>
+
+export const notionDataSourceBindingSchema = v.object({
+	collectionPointer: v.optional(collectionPointerValidator),
+	collectionSchema: v.optional(notionCollectionSchemaValidator),
+	propertyIdsByKey: v.optional(v.record(v.string(), v.optional(v.string()))),
+})
+
+export type NotionDataSourceBinding = v.InferOutput<
+	typeof notionDataSourceBindingSchema
+>
+
+export const notionDataSourceBindingsSchema = v.record(
+	v.string(),
+	notionDataSourceBindingSchema,
+)
+
+export type NotionDataSourceBindings = v.InferOutput<
+	typeof notionDataSourceBindingsSchema
+>

package/src/bridge/dataSources/dataSourcePage.ts

@@ -0,0 +1,71 @@
+import * as v from "valibot"
+import { notionPageIdSchema } from "../ids.js"
+import type { CustomBlockUpdatePageErrorInfo } from "../messages/updatePageResult.js"
+import type {
+	NotionPage,
+	NotionPageCover,
+	NotionPageIcon,
+	NotionPageId,
+	NotionPagePropertyInputMap,
+} from "../pages/page.js"
+import {
+	type NotionDataSourceValue,
+	notionDataSourceValueSchema,
+} from "./dataSourceValue.js"
+
+/**
+ * Bridge shape for a data source page, as parsed from inbound host messages. The host keys
+ * properties by raw property ID. The four built-ins (`created_time`, `last_edited_time`,
+ * `created_by`, `last_edited_by`) are normally present, possibly with `undefined` values.
+ *
+ * Internal to the SDK. The consumer-facing shape is {@link NotionDataSourcePage}.
+ */
+export const notionDataSourcePageBridgeSchema = v.object({
+	id: notionPageIdSchema,
+	propertiesById: v.record(v.string(), v.optional(notionDataSourceValueSchema)),
+})
+
+/** Internal SDK type for a parsed bridge page. */
+export type NotionDataSourcePageBridge = v.InferOutput<
+	typeof notionDataSourcePageBridgeSchema
+>
+
+export type NotionDataSourcePageUpdateInput = {
+	properties?: NotionPagePropertyInputMap
+	icon?: NotionPageIcon
+	cover?: NotionPageCover
+	archived?: boolean
+}
+
+export type NotionDataSourcePageUpdateResult =
+	| {
+			status: "success"
+			page: NotionPage
+	  }
+	| { status: "error"; error: CustomBlockUpdatePageErrorInfo }
+
+/**
+ * Consumer-facing page shape returned from {@link useDataSource}. Derived from the bridge payload
+ * plus the data source's `propertyIdsByKey`.
+ */
+export type NotionDataSourcePage = {
+	id: NotionPageId
+	/**
+	 * Keyed mapping of raw property IDs to their value. Includes all properties on the data source,
+	 * including the four built-ins (`created_time`, `last_edited_time`, `created_by`,
+	 * `last_edited_by`).
+	 */
+	propertiesById: { [propertyId: string]: NotionDataSourceValue | undefined }
+	/**
+	 * Keyed mapping of user-defined keys to their value. Only includes properties that are mapped
+	 * to a raw property ID in the data source's `propertyIdsByKey`.
+	 */
+	propertiesByKey: { [key: string]: NotionDataSourceValue | undefined }
+	/**
+	 * Updates this page using the data source's property-key bindings. The SDK resolves property
+	 * keys to raw property IDs before sending the bridge message to the host.
+	 */
+	update: (
+		input: NotionDataSourcePageUpdateInput,
+	) => Promise<NotionDataSourcePageUpdateResult>
+}

package/src/bridge/dataSources/dataSourceValue.ts

@@ -0,0 +1,19 @@
+import * as v from "valibot"
+import { notionDateValueSchema } from "./dateValue.js"
+import { notionRecordPointerSchema } from "./recordPointer.js"
+
+/**
+ * Possible types for a data source value.
+ */
+export const notionDataSourceValueSchema = v.union([
+	v.string(),
+	v.number(),
+	v.boolean(),
+	notionDateValueSchema,
+	v.array(v.string()),
+	v.array(notionRecordPointerSchema),
+])
+
+export type NotionDataSourceValue = v.InferOutput<
+	typeof notionDataSourceValueSchema
+>

package/src/bridge/dataSources/dateValue.ts

@@ -0,0 +1,96 @@
+import * as v from "valibot"
+
+export const notionDateReminderSchema = v.object({
+	unit: v.picklist(["year", "month", "week", "day"]),
+	value: v.number(),
+	time: v.string(),
+	defaultTimeZone: v.optional(v.string()),
+})
+
+export type NotionDateReminder = v.InferOutput<typeof notionDateReminderSchema>
+
+export const notionTimeReminderSchema = v.object({
+	unit: v.picklist(["hour", "minute"]),
+	value: v.number(),
+})
+
+export type NotionTimeReminder = v.InferOutput<typeof notionTimeReminderSchema>
+
+export const notionNoReminderSchema = v.object({
+	unit: v.literal("none"),
+})
+
+export type NotionNoReminder = v.InferOutput<typeof notionNoReminderSchema>
+
+/**
+ * Possible types for a Notion `datetime` reminder.
+ */
+export const notionDateTimeReminderSchema = v.union([
+	notionDateReminderSchema,
+	notionTimeReminderSchema,
+])
+
+export type NotionDateTimeReminder = v.InferOutput<
+	typeof notionDateTimeReminderSchema
+>
+
+const dateOrNoReminder = v.optional(
+	v.union([notionDateReminderSchema, notionNoReminderSchema]),
+)
+
+const dateTimeOrNoReminder = v.optional(
+	v.union([notionDateTimeReminderSchema, notionNoReminderSchema]),
+)
+
+export const notionDateSchema = v.object({
+	type: v.literal("date"),
+	start_date: v.string(),
+	reminder: dateOrNoReminder,
+})
+export type NotionDate = v.InferOutput<typeof notionDateSchema>
+
+export const notionDateRangeSchema = v.object({
+	type: v.literal("daterange"),
+	start_date: v.string(),
+	end_date: v.string(),
+	reminder: dateOrNoReminder,
+})
+export type NotionDateRange = v.InferOutput<typeof notionDateRangeSchema>
+
+export const notionDateTimeSchema = v.object({
+	type: v.literal("datetime"),
+	start_date: v.string(),
+	start_time: v.string(),
+	time_zone: v.optional(v.string()),
+	reminder: dateTimeOrNoReminder,
+})
+
+export type NotionDateTime = v.InferOutput<typeof notionDateTimeSchema>
+
+export const notionDateTimeRangeSchema = v.object({
+	type: v.literal("datetimerange"),
+	start_date: v.string(),
+	start_time: v.string(),
+	end_date: v.string(),
+	end_time: v.string(),
+	time_zone: v.optional(v.string()),
+	reminder: dateTimeOrNoReminder,
+})
+
+export type NotionDateTimeRange = v.InferOutput<
+	typeof notionDateTimeRangeSchema
+>
+
+/**
+ * Possible types for a Notion `date` value.
+ */
+export const notionDateValueSchema = v.variant("type", [
+	notionDateSchema,
+	notionDateRangeSchema,
+	notionDateTimeSchema,
+	notionDateTimeRangeSchema,
+])
+
+export type NotionDateValue = Readonly<
+	v.InferOutput<typeof notionDateValueSchema>
+>

package/src/bridge/dataSources/errors.ts

@@ -0,0 +1,14 @@
+import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "../errors"
+
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockDataSourceResolutionErrorCodeSchema = v.string()
+
+export type CustomBlockDataSourceResolutionErrorCode =
+	| "unknown_data_source_key"
+	| "unmapped_data_source"
+	| (string & {})
+
+export type CustomBlockDataSourceResolutionErrorInfo =
+	CustomBlockErrorInfo<CustomBlockDataSourceResolutionErrorCode>

package/src/bridge/dataSources/propertySchema.ts

@@ -0,0 +1,186 @@
+import * as v from "valibot"
+
+/**
+ * Hex-token identifiers for Notion's named colors. Mirrors the public API's
+ * `select.options[].color` enum
+ * (https://developers.notion.com/reference/property-object#select).
+ */
+export const notionPropertyColorSchema = v.picklist([
+	"default",
+	"gray",
+	"brown",
+	"orange",
+	"yellow",
+	"green",
+	"blue",
+	"purple",
+	"pink",
+	"red",
+	"gray_background",
+	"brown_background",
+	"orange_background",
+	"yellow_background",
+	"green_background",
+	"blue_background",
+	"purple_background",
+	"pink_background",
+	"red_background",
+	"default_background",
+])
+
+export type NotionPropertyColor = v.InferOutput<
+	typeof notionPropertyColorSchema
+>
+
+export const notionPropertyOptionSchema = v.object({
+	id: v.string(),
+	name: v.string(),
+	color: v.optional(notionPropertyColorSchema),
+	description: v.optional(v.string()),
+})
+
+export type NotionPropertyOption = v.InferOutput<
+	typeof notionPropertyOptionSchema
+>
+
+export const notionStatusGroupSchema = v.object({
+	id: v.string(),
+	name: v.string(),
+	color: v.optional(notionPropertyColorSchema),
+	option_ids: v.array(v.string()),
+})
+
+export type NotionStatusGroup = v.InferOutput<typeof notionStatusGroupSchema>
+
+export const notionDualPropertySchema = v.object({
+	synced_property_id: v.string(),
+	synced_property_name: v.string(),
+})
+
+export type NotionDualProperty = v.InferOutput<typeof notionDualPropertySchema>
+
+const baseProp = v.object({
+	name: v.string(),
+	description: v.optional(v.string()),
+})
+
+/**
+ * Every Notion property type the bridge speaks, in a single readable list.
+ * Mirrors the Notion public API
+ * [property object](https://developers.notion.com/reference/property-object)
+ * type field. Internal-only types (`button`, `verification`,
+ * `last_visited_time`, `location`) and the four built-ins (`created_time`,
+ * `last_edited_time`, `created_by`, `last_edited_by`) are included under their
+ * bridge-native names.
+ */
+export const NOTION_PROPERTY_TYPES = [
+	"title",
+	"rich_text",
+	"number",
+	"checkbox",
+	"url",
+	"email",
+	"phone_number",
+	"select",
+	"multi_select",
+	"status",
+	"date",
+	"people",
+	"files",
+	"unique_id",
+	"relation",
+	"place",
+	"formula",
+	"rollup",
+	"button",
+	"verification",
+	"last_visited_time",
+	"location",
+	"created_time",
+	"last_edited_time",
+	"created_by",
+	"last_edited_by",
+] as const
+
+export const notionPropertyTypeSchema = v.picklist(NOTION_PROPERTY_TYPES)
+
+/**
+ * String literal union of every supported Notion property type. Same set as
+ * the discriminator in `NotionPropertySchema` — split out so the manifest
+ * can declare expected property types without dragging in the per-type
+ * payload shapes.
+ */
+export type NotionPropertyType = v.InferOutput<typeof notionPropertyTypeSchema>
+
+/**
+ * Per-property schema as exposed by the host over the custom-block bridge.
+ * The `type` discriminator must be one of {@link NOTION_PROPERTY_TYPES}.
+ */
+export const notionPropertySchemaSchema = v.variant("type", [
+	v.object({ ...baseProp.entries, type: v.literal("title") }),
+	v.object({ ...baseProp.entries, type: v.literal("rich_text") }),
+	v.object({ ...baseProp.entries, type: v.literal("number") }),
+	v.object({ ...baseProp.entries, type: v.literal("checkbox") }),
+	v.object({ ...baseProp.entries, type: v.literal("url") }),
+	v.object({ ...baseProp.entries, type: v.literal("email") }),
+	v.object({ ...baseProp.entries, type: v.literal("phone_number") }),
+	v.object({
+		...baseProp.entries,
+		type: v.literal("select"),
+		options: v.array(notionPropertyOptionSchema),
+	}),
+	v.object({
+		...baseProp.entries,
+		type: v.literal("multi_select"),
+		options: v.array(notionPropertyOptionSchema),
+	}),
+	v.object({
+		...baseProp.entries,
+		type: v.literal("status"),
+		options: v.array(notionPropertyOptionSchema),
+		groups: v.array(notionStatusGroupSchema),
+	}),
+	v.object({ ...baseProp.entries, type: v.literal("date") }),
+	v.object({ ...baseProp.entries, type: v.literal("people") }),
+	v.object({ ...baseProp.entries, type: v.literal("files") }),
+	v.object({ ...baseProp.entries, type: v.literal("unique_id") }),
+	v.object({
+		...baseProp.entries,
+		type: v.literal("relation"),
+		data_source_id: v.optional(v.string()),
+		dual_property: v.optional(notionDualPropertySchema),
+	}),
+	v.object({ ...baseProp.entries, type: v.literal("place") }),
+	v.object({ ...baseProp.entries, type: v.literal("formula") }),
+	v.object({ ...baseProp.entries, type: v.literal("rollup") }),
+
+	// Internal-only types passed through under their bridge-native names.
+	v.object({ ...baseProp.entries, type: v.literal("button") }),
+	v.object({ ...baseProp.entries, type: v.literal("verification") }),
+	v.object({ ...baseProp.entries, type: v.literal("last_visited_time") }),
+	v.object({ ...baseProp.entries, type: v.literal("location") }),
+
+	// Synthetic built-ins. The host always emits one of each per data source.
+	v.object({ ...baseProp.entries, type: v.literal("created_time") }),
+	v.object({ ...baseProp.entries, type: v.literal("last_edited_time") }),
+	v.object({ ...baseProp.entries, type: v.literal("created_by") }),
+	v.object({ ...baseProp.entries, type: v.literal("last_edited_by") }),
+])
+
+export type NotionPropertySchema = v.InferOutput<
+	typeof notionPropertySchemaSchema
+>
+
+/**
+ * The four synthetic built-in property IDs the host always includes in every
+ * data source's `propertySchemasById` and every row's `propertiesById`.
+ */
+export const NOTION_BUILTIN_PROPERTY_IDS = [
+	"created_time",
+	"last_edited_time",
+	"created_by",
+	"last_edited_by",
+] as const
+
+export type NotionBuiltinPropertyId =
+	(typeof NOTION_BUILTIN_PROPERTY_IDS)[number]

package/src/bridge/dataSources/recordPointer.ts

@@ -0,0 +1,13 @@
+import * as v from "valibot"
+
+/**
+ * A pointer to a record in a database.
+ */
+export const notionRecordPointerSchema = v.object({
+	id: v.string(),
+	table: v.string(),
+})
+
+export type NotionRecordPointer = v.InferOutput<
+	typeof notionRecordPointerSchema
+>

package/src/bridge/dataSources/resolve.ts

@@ -0,0 +1,99 @@
+import type { CustomBlockManifest } from "../manifest.js"
+import type {
+	NotionDataSource,
+	NotionDataSourceBindings,
+} from "./dataSource.js"
+import type { NotionPropertySchema } from "./propertySchema.js"
+
+type ResolveDataSourcesArgs = {
+	manifest: CustomBlockManifest | null
+	dataSourceBindings: NotionDataSourceBindings
+}
+
+/**
+ * Builds the public {@link NotionDataSource} list the SDK exposes to consumers.
+ *
+ * Combines the host-supplied bindings (collection pointers + schemas) with the
+ * manifest's declared data-source keys. When the manifest names a property
+ * that isn't in `propertyIdsByKey`, falls back to {@link findPropertyIdByManifestProperty}
+ * so renames in Notion still resolve as long as the schema name matches.
+ */
+export function resolveDataSources(
+	args: ResolveDataSourcesArgs,
+): NotionDataSource[] {
+	if (args.manifest === null) {
+		return Object.entries(args.dataSourceBindings).map(([key, binding]) => ({
+			key,
+			collectionPointer: binding.collectionPointer,
+			collectionSchema: binding.collectionSchema,
+			propertyIdsByKey: { ...(binding.propertyIdsByKey ?? {}) },
+			propertySchemasById: binding.collectionSchema?.propertiesById ?? {},
+		}))
+	}
+
+	return Object.entries(args.manifest.dataSources).map(
+		([key, manifestDataSource]) => {
+			const binding = args.dataSourceBindings[key]
+			const propertySchemasById =
+				binding?.collectionSchema?.propertiesById ?? {}
+
+			const bindingPropertyIdsByKey = binding?.propertyIdsByKey ?? {}
+			const propertyIdsByKey: Record<string, string | undefined> = {}
+			const manifestProperties = Object.entries(
+				manifestDataSource.properties ?? {},
+			)
+			for (const [propertyKey, manifestProperty] of manifestProperties) {
+				const propertyId =
+					propertyKey in bindingPropertyIdsByKey
+						? bindingPropertyIdsByKey[propertyKey]
+						: findPropertyIdByManifestProperty(propertySchemasById, {
+								key: propertyKey,
+								type: manifestProperty.type,
+							})
+				const propertySchema =
+					propertyId === undefined ? undefined : propertySchemasById[propertyId]
+				propertyIdsByKey[propertyKey] =
+					propertySchema?.type === manifestProperty.type
+						? propertyId
+						: undefined
+			}
+
+			return {
+				key,
+				collectionPointer: binding?.collectionPointer,
+				collectionSchema: binding?.collectionSchema,
+				propertyIdsByKey,
+				propertySchemasById,
+			}
+		},
+	)
+}
+
+export function findPropertyIdByManifestProperty(
+	propertySchemasById: Record<string, NotionPropertySchema>,
+	manifestProperty: { key: string; type: NotionPropertySchema["type"] },
+): string | undefined {
+	// `ManifestProperty.name` is display copy for setup UI. Binding fallback is based
+	// on the stable semantic key so copy changes don't affect property resolution.
+	const propertySchemaForKey = propertySchemasById[manifestProperty.key]
+	if (propertySchemaForKey?.type === manifestProperty.type) {
+		return manifestProperty.key
+	}
+
+	const normalizedKey = normalizePropertyName(manifestProperty.key)
+	for (const [propertyId, propertySchema] of Object.entries(
+		propertySchemasById,
+	)) {
+		if (
+			propertySchema.type === manifestProperty.type &&
+			normalizePropertyName(propertySchema.name) === normalizedKey
+		) {
+			return propertyId
+		}
+	}
+	return undefined
+}
+
+function normalizePropertyName(value: string): string {
+	return value.trim().toLowerCase()
+}

package/src/bridge/dataSources/resolveProperty.ts

@@ -0,0 +1,130 @@
+import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "../errors"
+import type {
+	NotionPagePropertyInputMap,
+	NotionPagePropertyWriteMap,
+} from "../pages/page.js"
+import { notionPagePropertyValueSchema } from "../pages/page.js"
+import type { NotionDataSource } from "./dataSource.js"
+
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockPropertyErrorCodeSchema = v.string()
+
+export type CustomBlockPropertyErrorCode =
+	| "unmapped_property"
+	| "property_id_mismatch"
+	| "duplicate_property"
+	| "invalid_property_value"
+	| (string & {})
+
+export type CustomBlockPropertyErrorInfo =
+	CustomBlockErrorInfo<CustomBlockPropertyErrorCode>
+
+export type PropertyWriteMapResolutionResult =
+	| { status: "success"; properties: NotionPagePropertyWriteMap }
+	| { status: "error"; error: CustomBlockPropertyErrorInfo }
+
+function makePropertyError(
+	code: CustomBlockPropertyErrorCode,
+	message: string,
+): CustomBlockPropertyErrorInfo {
+	return { code, message, isRetryable: false }
+}
+
+/**
+ * Resolves a public SDK property write map into the ID-keyed bridge shape.
+ *
+ * Identifiers in `properties` may be raw property IDs or data-source property keys; the latter
+ * are looked up in the `dataSource`'s `propertyIdsByKey`. Each value is re-parsed through
+ * `notionPagePropertyValueSchema` with its `id` rewritten to the resolved property ID.
+ */
+export function resolvePropertyWriteMapForDataSource(args: {
+	dataSource: NotionDataSource | undefined
+	properties: NotionPagePropertyInputMap
+	operationName: string
+}): PropertyWriteMapResolutionResult {
+	const { dataSource, properties, operationName } = args
+
+	const resolvedProperties: NotionPagePropertyWriteMap = {}
+	for (const [identifier, value] of Object.entries(properties)) {
+		const propertyIdResult = resolvePropertyIdentifierForDataSource({
+			dataSource,
+			identifier,
+			operationName,
+		})
+		if (propertyIdResult.status === "error") {
+			return propertyIdResult
+		}
+
+		const propertyId = propertyIdResult.propertyId
+		if (
+			value.id !== undefined &&
+			value.id !== identifier &&
+			value.id !== propertyId
+		) {
+			return {
+				status: "error",
+				error: makePropertyError(
+					"property_id_mismatch",
+					`Property ${identifier} resolved to ${propertyId} but value id was ${value.id}.`,
+				),
+			}
+		}
+		if (resolvedProperties[propertyId] !== undefined) {
+			return {
+				status: "error",
+				error: makePropertyError(
+					"duplicate_property",
+					`Cannot set property ${propertyId} more than once.`,
+				),
+			}
+		}
+
+		const parsedValue = v.safeParse(notionPagePropertyValueSchema, {
+			...value,
+			id: propertyId,
+		})
+		if (!parsedValue.success) {
+			return {
+				status: "error",
+				error: makePropertyError(
+					"invalid_property_value",
+					`Invalid value for property ${identifier}.`,
+				),
+			}
+		}
+
+		resolvedProperties[propertyId] = parsedValue.output
+	}
+
+	return { status: "success", properties: resolvedProperties }
+}
+
+/**
+ * Treats matching data-source keys as aliases for property IDs; all other identifiers are raw IDs.
+ */
+export function resolvePropertyIdentifierForDataSource(args: {
+	dataSource: NotionDataSource | undefined
+	identifier: string
+	operationName: string
+}):
+	| { status: "success"; propertyId: string }
+	| { status: "error"; error: CustomBlockPropertyErrorInfo } {
+	const { dataSource, identifier, operationName } = args
+	if (dataSource !== undefined && identifier in dataSource.propertyIdsByKey) {
+		const propertyId = dataSource.propertyIdsByKey[identifier]
+		if (propertyId === undefined) {
+			return {
+				status: "error",
+				error: makePropertyError(
+					"unmapped_property",
+					`${operationName} cannot resolve property key "${identifier}" because it is not bound to a Notion property.`,
+				),
+			}
+		}
+		return { status: "success", propertyId }
+	}
+
+	return { status: "success", propertyId: identifier }
+}