@notionhq/custom-blocks 0.1.33 → 0.1.35

package/src/bridge/dataSources/query.ts

@@ -0,0 +1,694 @@
+import type { NotionDataSource } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
+import { CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
+import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
+import {
+	CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS,
+	customBlockCheckboxFilterOperatorSchema,
+	customBlockContainsFilterOperatorSchema,
+	customBlockDateFilterOperatorSchema,
+	customBlockNumberFilterOperatorSchema,
+	customBlockOptionFilterOperatorSchema,
+	customBlockTextFilterOperatorSchema,
+	type ResolvedCustomBlockDataSourceFilter,
+	type ResolvedCustomBlockDataSourcePropertyFilter,
+	type ResolvedCustomBlockDataSourceSort,
+} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
+import * as v from "valibot"
+import type { UseDataSourceOptions } from "../../types.js"
+import { unreachable } from "../../utils.js"
+
+const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
+const MAX_DATA_SOURCE_QUERY_LIMIT = 999
+const MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN = 25
+const supportedDataSourceSortPropertyTypes = new Set<string>(
+	CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES,
+)
+
+export type ResolvedDataSourceQuery = {
+	dataSourceId: NotionDataSourceId
+	limit: number
+	filter?: ResolvedCustomBlockDataSourceFilter
+	sorts?: ResolvedCustomBlockDataSourceSort[]
+	identity: string
+}
+
+export type ResolveDataSourceQueryResult =
+	| { status: "error"; error: string }
+	| {
+			status: "ok"
+			dataSource: NotionDataSource
+			query: ResolvedDataSourceQuery
+	  }
+
+type DataSourceQueryOptions = {
+	limit?: unknown
+	filter?: unknown
+	sorts?: unknown
+}
+
+type ResolvePropertyFilterResult =
+	| { status: "ok"; filter: ResolvedCustomBlockDataSourcePropertyFilter }
+	| { status: "error"; error: string }
+
+export function resolveDataSourceQuery(args: {
+	dataSources: NotionDataSource[]
+	key: string
+	options?: unknown
+	warn?: (message: string) => void
+}): ResolveDataSourceQueryResult {
+	const { dataSources, key, options, warn } = args
+	const resolvedOptions = resolveDataSourceQueryOptions(options)
+	if (resolvedOptions.status === "error") {
+		return resolvedOptions
+	}
+	const queryOptions = resolvedOptions.options
+	const dataSource = dataSources.find(entry => entry.key === key)
+	if (dataSource === undefined) {
+		return {
+			status: "error",
+			error: `Unknown data source key "${key}". Known keys: [${dataSources.map(entry => entry.key).join(", ")}].`,
+		}
+	}
+	if (dataSource.collectionPointer === undefined) {
+		return {
+			status: "error",
+			error: `Data source "${key}" has not been mapped to a database yet.`,
+		}
+	}
+
+	const limit = resolveDataSourceQueryLimit(queryOptions?.limit, warn)
+	if (limit.status === "error") {
+		return limit
+	}
+	const filter = resolveFilter(queryOptions?.filter, dataSource)
+	if (filter.status === "error") {
+		return filter
+	}
+	const sorts = resolveSorts(queryOptions?.sorts, dataSource)
+	if (sorts.status === "error") {
+		return sorts
+	}
+
+	const identity = stableJsonStringify({
+		dataSourceId: dataSource.collectionPointer.id,
+		limit: limit.limit,
+		filter: filter.filter ?? null,
+		sorts: sorts.sorts ?? [],
+	})
+	return {
+		status: "ok",
+		dataSource,
+		query: {
+			dataSourceId: dataSource.collectionPointer.id,
+			limit: limit.limit,
+			filter: filter.filter,
+			sorts: sorts.sorts,
+			identity,
+		},
+	}
+}
+
+function resolveDataSourceQueryOptions(
+	options: unknown,
+):
+	| { status: "ok"; options?: DataSourceQueryOptions }
+	| { status: "error"; error: string } {
+	if (options === undefined) {
+		return { status: "ok" }
+	}
+	if (
+		typeof options !== "object" ||
+		options === null ||
+		Array.isArray(options)
+	) {
+		return {
+			status: "error",
+			error: "Data source query options must be an object.",
+		}
+	}
+	const prototype = Object.getPrototypeOf(options)
+	if (prototype !== Object.prototype && prototype !== null) {
+		return {
+			status: "error",
+			error: "Data source query options must be an object.",
+		}
+	}
+	const optionsObject = options as Record<string, unknown>
+	if (
+		Object.keys(optionsObject).some(
+			key => !["limit", "filter", "sorts"].includes(key),
+		)
+	) {
+		return {
+			status: "error",
+			error: "Data source query options contain unsupported fields.",
+		}
+	}
+	return {
+		status: "ok",
+		options: {
+			limit: Object.prototype.hasOwnProperty.call(optionsObject, "limit")
+				? optionsObject.limit
+				: undefined,
+			filter: Object.prototype.hasOwnProperty.call(optionsObject, "filter")
+				? optionsObject.filter
+				: undefined,
+			sorts: Object.prototype.hasOwnProperty.call(optionsObject, "sorts")
+				? optionsObject.sorts
+				: undefined,
+		},
+	}
+}
+
+function resolveDataSourceQueryLimit(
+	limit: unknown,
+	warn: ((message: string) => void) | undefined = console.warn,
+): { status: "ok"; limit: number } | { status: "error"; error: string } {
+	if (limit === undefined) {
+		return { status: "ok", limit: DEFAULT_DATA_SOURCE_QUERY_LIMIT }
+	}
+	if (
+		typeof limit !== "number" ||
+		!Number.isFinite(limit) ||
+		!Number.isInteger(limit) ||
+		limit < 1
+	) {
+		return {
+			status: "error",
+			error: `Data source query limit must be a positive integer between 1 and ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
+		}
+	}
+	if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
+		warn?.(
+			`Data source query limit ${limit} exceeds the maximum of ${MAX_DATA_SOURCE_QUERY_LIMIT}; clamping to ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
+		)
+		return { status: "ok", limit: MAX_DATA_SOURCE_QUERY_LIMIT }
+	}
+	return { status: "ok", limit }
+}
+
+export function getDataSourceQueryOptionsIdentity(
+	options: UseDataSourceOptions | undefined,
+): string {
+	try {
+		return stableJsonStringify(options ?? {})
+	} catch {
+		return "invalid-data-source-query-options"
+	}
+}
+
+function stableJsonStringify(value: unknown): string {
+	return JSON.stringify(normalizeJsonValue(value))
+}
+
+function resolveFilter(
+	filter: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; filter?: ResolvedCustomBlockDataSourceFilter }
+	| { status: "error"; error: string } {
+	if (filter === undefined) {
+		return { status: "ok" }
+	}
+	if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+		return {
+			status: "error",
+			error: "Data source query filter must be an object.",
+		}
+	}
+	const filterObject = filter as Record<string, unknown>
+	if (Object.prototype.hasOwnProperty.call(filterObject, "and")) {
+		if (
+			Object.keys(filterObject).length !== 1 ||
+			!Array.isArray(filterObject.and)
+		) {
+			return {
+				status: "error",
+				error: 'Data source query filter "and" must be an array.',
+			}
+		}
+		if (filterObject.and.length > MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN) {
+			return {
+				status: "error",
+				error: `Data source query filter "and" may contain at most ${MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN} children.`,
+			}
+		}
+		const and: ResolvedCustomBlockDataSourcePropertyFilter[] = []
+		for (const child of filterObject.and) {
+			const resolved = resolvePropertyFilter(child, dataSource)
+			if (resolved.status === "error") {
+				return resolved
+			}
+			and.push(resolved.filter)
+		}
+		return { status: "ok", filter: { and } }
+	}
+	return resolvePropertyFilter(filterObject, dataSource)
+}
+
+function resolveSorts(
+	sorts: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; sorts?: ResolvedCustomBlockDataSourceSort[] }
+	| { status: "error"; error: string } {
+	if (sorts === undefined) {
+		return { status: "ok" }
+	}
+	if (!Array.isArray(sorts)) {
+		return {
+			status: "error",
+			error: "Data source query sorts must be an array.",
+		}
+	}
+	if (sorts.length === 0) {
+		return { status: "ok" }
+	}
+	if (sorts.length > CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS) {
+		return {
+			status: "error",
+			error: `Data source query sorts may contain at most ${CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS} entries.`,
+		}
+	}
+
+	const resolvedSorts: ResolvedCustomBlockDataSourceSort[] = []
+	const seenPropertyIds = new Set<string>()
+	for (const sort of sorts) {
+		const resolved = resolveSort(sort, dataSource)
+		if (resolved.status === "error") {
+			return resolved
+		}
+		if (seenPropertyIds.has(resolved.sort.propertyId)) {
+			return {
+				status: "error",
+				error: `Data source query sorts cannot contain duplicate property ID "${resolved.sort.propertyId}".`,
+			}
+		}
+		seenPropertyIds.add(resolved.sort.propertyId)
+		resolvedSorts.push(resolved.sort)
+	}
+	return { status: "ok", sorts: resolvedSorts }
+}
+
+function resolveSort(
+	sort: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; sort: ResolvedCustomBlockDataSourceSort }
+	| { status: "error"; error: string } {
+	if (typeof sort !== "object" || sort === null || Array.isArray(sort)) {
+		return {
+			status: "error",
+			error: "Data source query sort must be an object.",
+		}
+	}
+	const sortObject = sort as Record<string, unknown>
+	if (
+		Object.keys(sortObject).some(
+			key => !["key", "propertyId", "direction"].includes(key),
+		)
+	) {
+		return {
+			status: "error",
+			error: "Data source query sort contains unsupported fields.",
+		}
+	}
+	const property = resolvePropertyAddress(sortObject, dataSource)
+	if (property.status === "error") {
+		return property
+	}
+	if (!supportedDataSourceSortPropertyTypes.has(property.propertyType)) {
+		return {
+			status: "error",
+			error: `Data source query sorts do not yet support property type "${property.propertyType}".`,
+		}
+	}
+	const direction = sortObject.direction
+	if (
+		!Object.prototype.hasOwnProperty.call(sortObject, "direction") ||
+		(direction !== "ascending" && direction !== "descending")
+	) {
+		return {
+			status: "error",
+			error:
+				'Data source query sort direction must be "ascending" or "descending".',
+		}
+	}
+	return {
+		status: "ok",
+		sort: { propertyId: property.propertyId, direction },
+	}
+}
+
+function resolvePropertyFilter(
+	filter: unknown,
+	dataSource: NotionDataSource,
+): ResolvePropertyFilterResult {
+	if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+		return {
+			status: "error",
+			error: "Data source query property filter must be an object.",
+		}
+	}
+	const filterObject = filter as Record<string, unknown>
+	const property = resolvePropertyAddress(filterObject, dataSource)
+	if (property.status === "error") {
+		return property
+	}
+	const branchKeys = Object.keys(filterObject).filter(
+		key => key !== "key" && key !== "propertyId",
+	)
+	if (branchKeys.length !== 1) {
+		return {
+			status: "error",
+			error:
+				"Data source query property filter must contain exactly one property branch.",
+		}
+	}
+	const branch = branchKeys[0]
+	const value = filterObject[branch]
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		Array.isArray(value) ||
+		Object.keys(value).length !== 1
+	) {
+		return invalidOperator(branch)
+	}
+	if (property.propertyType !== branch) {
+		return {
+			status: "error",
+			error: `Data source query filter branch "${branch}" does not match property type "${property.propertyType}".`,
+		}
+	}
+
+	return resolvePropertyFilterBranch({
+		propertyId: property.propertyId,
+		branch,
+		value: value as Record<string, unknown>,
+	})
+}
+
+function resolvePropertyFilterBranch(args: {
+	propertyId: string
+	branch: string
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	switch (args.branch) {
+		case "title":
+		case "rich_text":
+		case "url":
+		case "email":
+		case "phone_number":
+			return resolveTextPropertyFilter({
+				propertyId: args.propertyId,
+				branch: args.branch,
+				value: args.value,
+			})
+		case "number":
+			return resolveNumberPropertyFilter(args.propertyId, args.value)
+		case "checkbox":
+			return resolveCheckboxPropertyFilter(args.propertyId, args.value)
+		case "select":
+		case "status":
+			return resolveOptionPropertyFilter({
+				propertyId: args.propertyId,
+				branch: args.branch,
+				value: args.value,
+			})
+		case "multi_select":
+			return resolveMultiSelectPropertyFilter(args.propertyId, args.value)
+		case "date":
+			return resolveDatePropertyFilter(args.propertyId, args.value)
+		default:
+			return {
+				status: "error",
+				error: `Data source query filter branch "${args.branch}" is not supported.`,
+			}
+	}
+}
+
+function resolveTextPropertyFilter(args: {
+	propertyId: string
+	branch: "title" | "rich_text" | "url" | "email" | "phone_number"
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockTextFilterOperatorSchema, args.value)
+	if (!parsed.success) {
+		return invalidOperator(args.branch)
+	}
+	switch (args.branch) {
+		case "title":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, title: parsed.output },
+			}
+		case "rich_text":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, rich_text: parsed.output },
+			}
+		case "url":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, url: parsed.output },
+			}
+		case "email":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, email: parsed.output },
+			}
+		case "phone_number":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, phone_number: parsed.output },
+			}
+		default:
+			return unreachable(args.branch)
+	}
+}
+
+function resolveNumberPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockNumberFilterOperatorSchema, value)
+	if (
+		!parsed.success ||
+		!Object.values(parsed.output).every(
+			entry => typeof entry !== "number" || Number.isFinite(entry),
+		)
+	) {
+		return invalidOperator("number")
+	}
+	return {
+		status: "ok",
+		filter: { propertyId, number: parsed.output },
+	}
+}
+
+function resolveCheckboxPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockCheckboxFilterOperatorSchema, value)
+	return parsed.success
+		? { status: "ok", filter: { propertyId, checkbox: parsed.output } }
+		: invalidOperator("checkbox")
+}
+
+function resolveOptionPropertyFilter(args: {
+	propertyId: string
+	branch: "select" | "status"
+	value: Record<string, unknown>
+}): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, args.value)
+	if (!parsed.success) {
+		return invalidOperator(args.branch)
+	}
+	switch (args.branch) {
+		case "select":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, select: parsed.output },
+			}
+		case "status":
+			return {
+				status: "ok",
+				filter: { propertyId: args.propertyId, status: parsed.output },
+			}
+		default:
+			return unreachable(args.branch)
+	}
+}
+
+function resolveMultiSelectPropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockContainsFilterOperatorSchema, value)
+	return parsed.success
+		? { status: "ok", filter: { propertyId, multi_select: parsed.output } }
+		: invalidOperator("multi_select")
+}
+
+function resolveDatePropertyFilter(
+	propertyId: string,
+	value: Record<string, unknown>,
+): ResolvePropertyFilterResult {
+	const parsed = v.safeParse(customBlockDateFilterOperatorSchema, value)
+	if (
+		!parsed.success ||
+		!Object.values(parsed.output).every(
+			entry => entry === true || isValidIsoDate(entry),
+		)
+	) {
+		return invalidOperator("date")
+	}
+	return {
+		status: "ok",
+		filter: { propertyId, date: parsed.output },
+	}
+}
+
+function resolvePropertyAddress(
+	value: Record<string, unknown>,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; propertyId: string; propertyType: string }
+	| { status: "error"; error: string } {
+	const hasKey = Object.prototype.hasOwnProperty.call(value, "key")
+	const hasPropertyId = Object.prototype.hasOwnProperty.call(
+		value,
+		"propertyId",
+	)
+	if (hasKey === hasPropertyId) {
+		return {
+			status: "error",
+			error:
+				"Data source query filters and sorts must use exactly one of key or propertyId.",
+		}
+	}
+	let propertyId: string
+	if (hasKey) {
+		if (typeof value.key !== "string") {
+			return {
+				status: "error",
+				error: "Data source query property key must be a string.",
+			}
+		}
+		if (
+			!Object.prototype.hasOwnProperty.call(
+				dataSource.propertyIdsByKey,
+				value.key,
+			)
+		) {
+			return {
+				status: "error",
+				error: `Unknown property key "${value.key}" for data source "${dataSource.key}".`,
+			}
+		}
+		const resolvedPropertyId = dataSource.propertyIdsByKey[value.key]
+		if (resolvedPropertyId === undefined) {
+			return {
+				status: "error",
+				error: `Property key "${value.key}" for data source "${dataSource.key}" is not bound.`,
+			}
+		}
+		propertyId = resolvedPropertyId
+	} else {
+		if (typeof value.propertyId !== "string") {
+			return {
+				status: "error",
+				error: "Data source query propertyId must be a string.",
+			}
+		}
+		propertyId = value.propertyId
+	}
+	if (
+		!Object.prototype.hasOwnProperty.call(
+			dataSource.propertySchemasById,
+			propertyId,
+		)
+	) {
+		return {
+			status: "error",
+			error: `Unknown property ID "${propertyId}" for data source "${dataSource.key}".`,
+		}
+	}
+	const propertySchema = dataSource.propertySchemasById[propertyId]
+	return {
+		status: "ok",
+		propertyId,
+		propertyType: propertySchema.type,
+	}
+}
+
+function invalidOperator(branch: string): { status: "error"; error: string } {
+	return {
+		status: "error",
+		error: `Data source query filter branch "${branch}" has an invalid operator or value.`,
+	}
+}
+
+function normalizeJsonValue(value: unknown): unknown {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "boolean"
+	) {
+		return value
+	}
+	if (typeof value === "number") {
+		return normalizeJsonNumber(value)
+	}
+	if (Array.isArray(value)) {
+		return value.map(entry => normalizeJsonValue(entry))
+	}
+	if (typeof value === "object") {
+		return normalizeJsonObject(value)
+	}
+	throw new Error("Data source query values must be JSON-compatible.")
+}
+
+function normalizeJsonNumber(value: number): number {
+	if (!Number.isFinite(value)) {
+		throw new Error("Data source query values must be finite JSON numbers.")
+	}
+	return value
+}
+
+function normalizeJsonObject(value: object): Record<string, unknown> {
+	const prototype = Object.getPrototypeOf(value)
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new Error("Data source query values must be JSON-compatible.")
+	}
+	const objectValue = value as Record<string, unknown>
+	const normalized: Record<string, unknown> = {}
+	for (const key of Object.keys(objectValue).sort()) {
+		const child = objectValue[key]
+		if (child !== undefined) {
+			normalized[key] = normalizeJsonValue(child)
+		}
+	}
+	return normalized
+}
+
+function isValidIsoDate(value: unknown): boolean {
+	if (typeof value !== "string") {
+		return false
+	}
+	const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value)
+	if (dateOnly !== null) {
+		const [, year, month, day] = dateOnly
+		const date = new Date(
+			Date.UTC(Number(year), Number(month) - 1, Number(day)),
+		)
+		return date.toISOString().slice(0, 10) === value
+	}
+	return (
+		/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+			value,
+		) && Number.isFinite(Date.parse(value))
+	)
+}