ncblock 0.0.3 → 0.0.5

package/bridge/SandboxBridge.ts

@@ -0,0 +1,659 @@
+import * as v from "valibot"
+import type {
+	CreatePageInput,
+	CreatePageResult,
+	GetPageResult,
+	GetUserResult,
+	ListUsersInput,
+	ListUsersResult,
+	NotionPageId,
+	NotionUserId,
+	UpdatePageInput,
+	UpdatePageResult,
+} from "../types"
+import { unreachable } from "../utils"
+import type { NotionCustomBlockContext } from "./context"
+import type { NotionDataSource } from "./dataSources/dataSource"
+import type {
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+} from "./dataSources/dataSourcePage"
+import { resolveDataSources } from "./dataSources/resolve"
+import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty"
+import {
+	type CustomBlockHostState,
+	createEmptyDataSourceQueryState,
+	type DataSourceQueryState,
+} from "./hostState"
+import { readIncomingType } from "./incomingType"
+import type { CustomBlockManifest } from "./manifest"
+import type {
+	CreatePageMessage,
+	CreatePageMessageParent,
+} from "./messages/createPage"
+import type { GetUserMessage } from "./messages/getUser"
+import { hostToSandboxMessageSchema } from "./messages/hostToSandbox"
+import type { InitMessage } from "./messages/init"
+import type { InvalidHostMessage } from "./messages/invalidHostMessage"
+import type { ListUsersMessage } from "./messages/listUsers"
+import type { ReadyMessage } from "./messages/ready"
+import type { ResizeMessage } from "./messages/resize"
+import type { UpdatePageMessage } from "./messages/updatePage"
+import type { NotionPage } from "./pages/page"
+import { PendingRequests } from "./pendingRequests"
+import type { NotionUser } from "./users/user"
+
+/**
+ * Used to ensure that the host and client are using the same version of the bridge protocol. A
+ * single host needs to support multiple custom blocks built with different versions of the bridge
+ * protocol. Increment this number any time a breaking change is made to the bridge protocol.
+ */
+export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 1
+
+export class SandboxBridge {
+	private hostState: CustomBlockHostState = {
+		status: "uninitialized",
+		theme: "light",
+	}
+	private listeners = new Set<() => void>()
+	private nextRequestId = 1
+	private readonly pendingCreatePage = new PendingRequests<CreatePageResult>(
+		"custom-block-create-page",
+	)
+	private readonly pendingGetPage = new PendingRequests<GetPageResult>(
+		"custom-block-get-page",
+	)
+	private readonly pendingGetUser = new PendingRequests<GetUserResult>(
+		"custom-block-get-user",
+	)
+	private readonly pendingListUsers = new PendingRequests<ListUsersResult>(
+		"custom-block-list-users",
+	)
+	private readonly pendingUpdatePage = new PendingRequests<UpdatePageResult>(
+		"custom-block-update-page",
+	)
+	private resolveInit: ((message: InitMessage) => void) | undefined
+	private readonly initMessage: Promise<InitMessage> = new Promise(resolve => {
+		this.resolveInit = resolve
+	})
+	private manifest: CustomBlockManifest | null = null
+
+	constructor() {
+		// `ready` is sent later by `initCustomBlock` (after the manifest fetch
+		// resolves). Top-level / no-iframe rejection is handled there too, so
+		// the constructor just attaches the listener.
+		if (typeof window !== "undefined") {
+			window.addEventListener("message", this.handleMessage)
+		}
+	}
+
+	awaitInit(signal?: AbortSignal): Promise<InitMessage> {
+		if (!signal) {
+			return this.initMessage
+		}
+		return new Promise((resolve, reject) => {
+			if (signal.aborted) {
+				reject(signal.reason)
+				return
+			}
+			const onAbort = () => reject(signal.reason)
+			signal.addEventListener("abort", onAbort, { once: true })
+			this.initMessage.then(
+				message => {
+					signal.removeEventListener("abort", onAbort)
+					resolve(message)
+				},
+				err => {
+					signal.removeEventListener("abort", onAbort)
+					reject(err)
+				},
+			)
+		})
+	}
+
+	sendReady(manifest: CustomBlockManifest | null) {
+		if (typeof window === "undefined") {
+			return
+		}
+		this.manifest = manifest
+		const readyMessage: ReadyMessage = {
+			type: "ready",
+			bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
+			manifest,
+		}
+		console.debug("[notion-custom-sdk] outbound postMessage", readyMessage)
+		window.parent.postMessage(readyMessage, "*")
+	}
+
+	private notify = () => {
+		for (const listener of this.listeners) {
+			listener()
+		}
+	}
+
+	private handleMessage = (event: MessageEvent) => {
+		console.debug("[notion-custom-sdk] incoming postMessage", {
+			data: event.data,
+			fromParent: event.source === window.parent,
+		})
+		if (event.source !== window.parent) {
+			return
+		}
+
+		const parsed = v.safeParse(hostToSandboxMessageSchema, event.data)
+		if (!parsed.success) {
+			console.warn(
+				"[notion-custom-sdk] ignoring malformed host message",
+				parsed.issues,
+			)
+			const incomingType = readIncomingType(event.data)
+			// Loop guard: never NACK a NACK. Excludes both directions —
+			// `invalidSandboxMessage` is what the host normally sends, but
+			// a buggy host that echoes our own `invalidHostMessage` back
+			// would otherwise spin a NACK feedback loop.
+			if (
+				incomingType !== "invalidSandboxMessage" &&
+				incomingType !== "invalidHostMessage"
+			) {
+				const nack: InvalidHostMessage = {
+					type: "invalidHostMessage",
+					reason: formatInvalidHostReason(incomingType, parsed.issues),
+				}
+				console.debug("[notion-custom-sdk] outbound postMessage", nack)
+				window.parent.postMessage(nack, "*")
+			}
+			return
+		}
+		const message = parsed.output
+
+		// If the host couldn't parse one of our outbound sandbox-to-host messages, it sends back
+		// an `invalidSandboxMessage` NACK with a human-readable `reason`. Log it for developer
+		// visibility and stop. We don't retry as the sandbox can't recover from a host-side parse
+		// failure on its own.
+		if (message.type === "invalidSandboxMessage") {
+			console.warn(
+				"[notion-custom-sdk] host reported invalid sandbox message:",
+				message.reason,
+			)
+			return
+		}
+
+		// `init` is the only message valid before initialization. Handle it up
+		// front so every later case can assume `status === "initialized"`.
+		if (message.type === "init") {
+			this.applyInit(message)
+			return
+		}
+
+		// Alias to keep TS's narrowed `InitializedHostState` across the switch
+		// below. Reading `this.hostState` repeatedly would re-widen it.
+		const hostState = this.hostState
+
+		if (hostState.status !== "initialized") {
+			console.warn(`[notion-custom-sdk] ignoring ${message.type} before init`)
+			return
+		}
+
+		switch (message.type) {
+			case "themeChanged": {
+				this.hostState = {
+					...hostState,
+					theme: message.theme,
+				}
+				this.notify()
+				return
+			}
+
+			case "contextChanged": {
+				this.hostState = {
+					...hostState,
+					context: message.context as NotionCustomBlockContext,
+				}
+				this.notify()
+				return
+			}
+
+			case "dataSourcesChanged": {
+				const dataSources = resolveDataSources({
+					manifest: this.manifest,
+					dataSourceBindings: message.dataSources.bindings,
+				})
+				// Drop cached query state for keys that no longer exist in the mapping.
+				const nextKeys = new Set(dataSources.map(s => s.key))
+				const prunedState: Record<string, DataSourceQueryState> = {}
+				for (const [key, state] of Object.entries(hostState.dataSourceState)) {
+					if (nextKeys.has(key)) {
+						prunedState[key] = state
+					}
+				}
+				this.hostState = {
+					...hostState,
+					dataSources,
+					dataSourceState: prunedState,
+				}
+				this.notify()
+				return
+			}
+
+			case "createPageResult": {
+				const result: CreatePageResult =
+					message.status === "success"
+						? { status: "success", page: message.page as unknown as NotionPage }
+						: { status: "error", error: message.error }
+				if (!this.pendingCreatePage.resolve(message.requestId, result)) {
+					console.warn(
+						`[notion-custom-sdk] createPageResult for unknown requestId ${message.requestId}`,
+					)
+				}
+				return
+			}
+
+			case "getPageResult": {
+				const result: GetPageResult =
+					message.status === "success"
+						? { status: "success", page: message.page as unknown as NotionPage }
+						: { status: "error", error: message.error }
+				if (!this.pendingGetPage.resolve(message.requestId, result)) {
+					console.warn(
+						`[notion-custom-sdk] getPageResult for unknown requestId ${message.requestId}`,
+					)
+				}
+				return
+			}
+
+			case "getUserResult": {
+				const result: GetUserResult =
+					message.status === "success"
+						? { status: "success", user: message.user as unknown as NotionUser }
+						: { status: "error", error: message.error }
+				if (!this.pendingGetUser.resolve(message.requestId, result)) {
+					console.warn(
+						`[notion-custom-sdk] getUserResult for unknown requestId ${message.requestId}`,
+					)
+				}
+				return
+			}
+
+			case "listUsersResult": {
+				const result: ListUsersResult =
+					message.status === "success"
+						? { status: "success", list: message.list }
+						: { status: "error", error: message.error }
+				if (!this.pendingListUsers.resolve(message.requestId, result)) {
+					console.warn(
+						`[notion-custom-sdk] listUsersResult for unknown requestId ${message.requestId}`,
+					)
+				}
+				return
+			}
+
+			case "updatePageResult": {
+				const result: UpdatePageResult =
+					message.status === "success"
+						? { status: "success", page: message.page as unknown as NotionPage }
+						: { status: "error", error: message.error }
+				if (!this.pendingUpdatePage.resolve(message.requestId, result)) {
+					console.warn(
+						`[notion-custom-sdk] updatePageResult for unknown requestId ${message.requestId}`,
+					)
+				}
+				return
+			}
+
+			case "queryDataSourceResult": {
+				const currentState =
+					hostState.dataSourceState[message.key] ??
+					createEmptyDataSourceQueryState()
+				if (currentState.latestRequestId !== message.requestId) {
+					return
+				}
+
+				this.hostState = {
+					...hostState,
+					dataSourceState: {
+						...hostState.dataSourceState,
+						[message.key]: {
+							items: message.items,
+							isLoading: false,
+							hasMore: message.hasMore,
+							error: message.error,
+							// Keep the request ID so later host-pushed refreshes for the
+							// same subscription still match.
+							latestRequestId: message.requestId,
+						},
+					},
+				}
+				this.notify()
+				return
+			}
+
+			default: {
+				unreachable(message)
+			}
+		}
+	}
+
+	subscribe(listener: () => void) {
+		this.listeners.add(listener)
+		return () => this.listeners.delete(listener)
+	}
+
+	getHostState(): CustomBlockHostState {
+		return this.hostState
+	}
+
+	/**
+	 * Apply an `init` payload as if it had arrived from the host. Lets callers
+	 * seed the bridge directly (e.g. the React provider's standalone preview
+	 * fallback) without going through `postMessage`. The bridge stays unaware
+	 * of why it's being seeded.
+	 */
+	setMockState(message: InitMessage) {
+		this.applyInit(message)
+	}
+
+	private applyInit(message: InitMessage) {
+		const dataSources = resolveDataSources({
+			manifest: this.manifest,
+			dataSourceBindings: message.dataSources.bindings,
+		})
+		this.hostState = {
+			status: "initialized",
+			theme: message.theme,
+			context: message.context as NotionCustomBlockContext,
+			dataSources,
+			dataSourceState: {},
+		}
+		this.notify()
+		// Resolve the awaitInit promise once. Subsequent `init` messages
+		// (the host shouldn't send these, but be tolerant) update state but
+		// don't re-resolve.
+		if (this.resolveInit) {
+			this.resolveInit(message)
+			this.resolveInit = undefined
+		}
+	}
+
+	queryDataSource(key: string, limit: number) {
+		if (this.hostState.status !== "initialized") {
+			return
+		}
+
+		const currentState =
+			this.hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+
+		if (currentState.isLoading) {
+			return
+		}
+
+		const requestId = `custom-block-query-${this.nextRequestId}`
+		this.nextRequestId += 1
+
+		this.hostState = {
+			...this.hostState,
+			dataSourceState: {
+				...this.hostState.dataSourceState,
+				[key]: {
+					...currentState,
+					isLoading: true,
+					error: undefined,
+					latestRequestId: requestId,
+				},
+			},
+		}
+		this.notify()
+
+		const outbound = {
+			type: "queryDataSource",
+			requestId,
+			key,
+			limit,
+		}
+		console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+		window.parent.postMessage(outbound, "*")
+	}
+
+	postResize(height: number) {
+		if (typeof window === "undefined") {
+			return
+		}
+		const safeHeight =
+			Number.isFinite(height) && height >= 0 ? Math.ceil(height) : 0
+		const outbound: ResizeMessage = {
+			type: "resize",
+			height: safeHeight,
+		}
+		console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+		window.parent.postMessage(outbound, "*")
+	}
+
+	createPage(input: CreatePageInput): Promise<CreatePageResult> {
+		return new Promise(resolve => {
+			const resolvedParent = this.resolveCreatePageParent(input.parent)
+			if (resolvedParent.status === "error") {
+				resolve(resolvedParent)
+				return
+			}
+			const resolvedProperties = resolvePropertyWriteMapForDataSource({
+				dataSource: resolvedParent.dataSource,
+				properties: input.properties,
+				operationName: "createPage",
+			})
+			if (resolvedProperties.status === "error") {
+				resolve(resolvedProperties)
+				return
+			}
+			const requestId = this.pendingCreatePage.allocate(resolve)
+			const outbound: CreatePageMessage = {
+				type: "createPage",
+				requestId,
+				parent: resolvedParent.parent,
+				properties: resolvedProperties.properties,
+			}
+			if (input.icon !== undefined) {
+				outbound.icon = input.icon
+			}
+			if (input.cover !== undefined) {
+				outbound.cover = input.cover
+			}
+			if (input.position !== undefined) {
+				outbound.position = input.position
+			}
+			console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+			window.parent.postMessage(outbound, "*")
+		})
+	}
+
+	getPage(pageId: NotionPageId): Promise<GetPageResult> {
+		return new Promise(resolve => {
+			const requestId = this.pendingGetPage.allocate(resolve)
+			const outbound = {
+				type: "getPage",
+				requestId,
+				pageId,
+			}
+			console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+			window.parent.postMessage(outbound, "*")
+		})
+	}
+
+	getUser(userId: NotionUserId): Promise<GetUserResult> {
+		return new Promise(resolve => {
+			const requestId = this.pendingGetUser.allocate(resolve)
+			const outbound: GetUserMessage = {
+				type: "getUser",
+				requestId,
+				userId,
+			}
+			console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+			window.parent.postMessage(outbound, "*")
+		})
+	}
+
+	listUsers(input: ListUsersInput = {}): Promise<ListUsersResult> {
+		return new Promise(resolve => {
+			const requestId = this.pendingListUsers.allocate(resolve)
+			const outbound: ListUsersMessage = {
+				type: "listUsers",
+				requestId,
+				startCursor: input.startCursor,
+				pageSize: input.pageSize,
+			}
+			console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+			window.parent.postMessage(outbound, "*")
+		})
+	}
+
+	updatePage(input: UpdatePageInput): Promise<UpdatePageResult> {
+		return new Promise(resolve => {
+			if (
+				(input.properties === undefined ||
+					Object.keys(input.properties).length === 0) &&
+				input.icon === undefined &&
+				input.cover === undefined &&
+				input.archived === undefined
+			) {
+				resolve({
+					status: "error",
+					error:
+						"updatePage requires at least one of: properties, icon, cover, archived.",
+				})
+				return
+			}
+
+			const requestId = this.pendingUpdatePage.allocate(resolve)
+			const outbound: UpdatePageMessage = {
+				type: "updatePage",
+				requestId,
+				pageId: input.pageId,
+			}
+			if (input.properties !== undefined) {
+				outbound.properties = input.properties
+			}
+			if (input.icon !== undefined) {
+				outbound.icon = input.icon
+			}
+			if (input.cover !== undefined) {
+				outbound.cover = input.cover
+			}
+			if (input.archived !== undefined) {
+				outbound.archived = input.archived
+			}
+			console.debug("[notion-custom-sdk] outbound postMessage", outbound)
+			window.parent.postMessage(outbound, "*")
+		})
+	}
+
+	/**
+	 * Updates a page on a known data source, resolving any property keys against the data source's
+	 * `propertyIdsByKey` before sending the bridge message. Used by the per-row `update` callback
+	 * returned from {@link getDataSourceQueryView}.
+	 */
+	updateDataSourcePage(args: {
+		dataSource: NotionDataSource
+		pageId: NotionPageId
+		input: NotionDataSourcePageUpdateInput
+	}): Promise<NotionDataSourcePageUpdateResult> {
+		const { dataSource, pageId, input } = args
+		const resolvedProperties =
+			input.properties === undefined
+				? undefined
+				: resolvePropertyWriteMapForDataSource({
+						dataSource,
+						properties: input.properties,
+						operationName: "dataSourcePage.update",
+					})
+		if (resolvedProperties?.status === "error") {
+			return Promise.resolve(resolvedProperties)
+		}
+
+		return this.updatePage({
+			pageId,
+			properties: resolvedProperties?.properties,
+			icon: input.icon,
+			cover: input.cover,
+			archived: input.archived,
+		})
+	}
+
+	/**
+	 * Translates the public `CreatePageInput["parent"]` into the bridge-native
+	 * `CreatePageMessageParent`. The `data_source_key` variant is resolved sandbox-side against
+	 * the data source mapping the host delivered in `init` / `dataSourcesChanged`.
+	 */
+	private resolveCreatePageParent(parent: CreatePageInput["parent"]):
+		| {
+				status: "ok"
+				parent: CreatePageMessageParent
+				dataSource: NotionDataSource | undefined
+		  }
+		| { status: "error"; error: string } {
+		switch (parent.type) {
+			case "page_id":
+				return { status: "ok", parent, dataSource: undefined }
+			case "data_source_id": {
+				const dataSource =
+					this.hostState.status === "initialized"
+						? this.hostState.dataSources.find(
+								entry => entry.collectionPointer?.id === parent.data_source_id,
+							)
+						: undefined
+				return { status: "ok", parent, dataSource }
+			}
+			case "data_source_key": {
+				if (this.hostState.status !== "initialized") {
+					return {
+						status: "error",
+						error: `Cannot resolve data source key "${parent.key}" before the host has initialized the SDK.`,
+					}
+				}
+				const dataSource = this.hostState.dataSources.find(
+					entry => entry.key === parent.key,
+				)
+				if (dataSource === undefined) {
+					return {
+						status: "error",
+						error: `Unknown data source key "${parent.key}". Known keys: [${this.hostState.dataSources.map(entry => entry.key).join(", ")}].`,
+					}
+				}
+				if (dataSource.collectionPointer === undefined) {
+					return {
+						status: "error",
+						error: `Data source "${parent.key}" has not been mapped to a database yet.`,
+					}
+				}
+				return {
+					status: "ok",
+					parent: {
+						type: "data_source_id",
+						data_source_id: dataSource.collectionPointer.id,
+					},
+					dataSource,
+				}
+			}
+			default:
+				unreachable(parent)
+		}
+	}
+}
+
+function formatInvalidHostReason(
+	incomingType: string | undefined,
+	issues: readonly v.BaseIssue<unknown>[],
+): string {
+	const labelled = incomingType
+		? `host message of type "${incomingType}"`
+		: "host message"
+	const first = issues[0]
+	if (!first) {
+		return `Could not parse ${labelled}: unknown error`
+	}
+	const path =
+		first.path
+			?.map(p => String(p.key ?? ""))
+			.filter(Boolean)
+			.join(".") ?? ""
+	const detail = path ? `${path}: ${first.message}` : first.message
+	const extra = issues.length > 1 ? ` (+${issues.length - 1} more)` : ""
+	return `Could not parse ${labelled}: ${detail}${extra}`
+}

package/bridge/context.ts

@@ -0,0 +1,58 @@
+import * as v from "valibot"
+import type { NotionPageId } from "./pages/page"
+
+/**
+ * Context about the custom block and its location in the block tree.
+ * Delivered as part of the `init` message and then re-sent via `contextChanged`
+ * whenever the host detects a change (e.g. the block moves into a different
+ * container or its enclosing page changes).
+ */
+export const notionCustomBlockContextSchema = v.object({
+	/**
+	 * ID of the custom block itself, the one hosting this sandboxed iframe.
+	 */
+	customBlockId: v.string(),
+
+	/**
+	 * The block that directly parents this custom block.
+	 */
+	parent: v.object({
+		/**
+		 * The ID of the block that directly parents this custom block.
+		 */
+		id: v.string(),
+		/**
+		 * The block type of the block that directly parents this custom block. This could be many
+		 * different types, including: page, toggle, column, and callout.
+		 */
+		type: v.string(),
+	}),
+
+	/**
+	 * The nearest page ancestor to this custom block.
+	 */
+	page: v.object({
+		/**
+		 * The ID of the nearest page ancestor to this custom block.
+		 */
+		id: v.string(),
+	}),
+})
+
+export type NotionCustomBlockContext = Omit<
+	v.InferOutput<typeof notionCustomBlockContextSchema>,
+	"page"
+> & {
+	page: {
+		id: NotionPageId
+	}
+}
+
+export function parseNotionCustomBlockContext(
+	value: unknown,
+): NotionCustomBlockContext | undefined {
+	const parsed = v.safeParse(notionCustomBlockContextSchema, value)
+	return parsed.success
+		? (parsed.output as NotionCustomBlockContext)
+		: undefined
+}