ncblock 0.0.4 → 0.0.5

package/bridge/hostState.ts

@@ -0,0 +1,146 @@
+import type { NotionCustomBlockContext } from "./context"
+import type { NotionDataSource } from "./dataSources/dataSource"
+import type {
+	NotionDataSourcePage,
+	NotionDataSourcePageBridge,
+	NotionDataSourcePageUpdateInput,
+	NotionDataSourcePageUpdateResult,
+} from "./dataSources/dataSourcePage"
+import type { NotionDataSourceValue } from "./dataSources/dataSourceValue"
+import type { NotionPropertySchema } from "./dataSources/propertySchema"
+import type { NotionPageId } from "./pages/page"
+import type { NotionTheme } from "./theme"
+
+export type CustomBlockHostState = UninitializedHostState | InitializedHostState
+
+export type UninitializedHostState = {
+	status: "uninitialized"
+	theme: NotionTheme
+}
+
+export type InitializedHostState = {
+	status: "initialized"
+	theme: NotionTheme
+	context: NotionCustomBlockContext
+	dataSources: NotionDataSource[]
+	dataSourceState: Record<string, DataSourceQueryState>
+}
+
+export type DataSourceQueryState = {
+	/** Latest pages from the host as parsed from the bridge. `propertiesByKey` is derived lazily. */
+	items: NotionDataSourcePageBridge[]
+	isLoading: boolean
+	hasMore: boolean
+	error?: string
+	latestRequestId?: string
+}
+
+export function createEmptyDataSourceQueryState(): DataSourceQueryState {
+	return {
+		items: [],
+		isLoading: false,
+		hasMore: false,
+	}
+}
+
+/**
+ * Resolved page + schema views for a single data source, keyed by raw property
+ * ID and by user-defined key. Re-derived from `propertyIdsByKey` on every read so
+ * renames don't require a re-query.
+ */
+export type DataSourceQueryView = {
+	items: NotionDataSourcePage[]
+	collectionSchema?: NotionDataSource["collectionSchema"]
+	propertySchemasById: { [propertyId: string]: NotionPropertySchema }
+	propertySchemasByKey: { [key: string]: NotionPropertySchema | undefined }
+	isLoading: boolean
+	hasMore: boolean
+	error?: string
+}
+
+const EMPTY_QUERY_VIEW: DataSourceQueryView = {
+	items: [],
+	propertySchemasById: {},
+	propertySchemasByKey: {},
+	isLoading: false,
+	hasMore: false,
+}
+
+/**
+ * Per-row callback that resolves property keys against the data source and forwards the
+ * resulting write to the bridge. Injected by callers (typically the SDK singleton in `init.ts`)
+ * so this module stays free of bridge-instance dependencies.
+ */
+export type UpdateDataSourcePageFn = (args: {
+	dataSource: NotionDataSource
+	pageId: NotionPageId
+	input: NotionDataSourcePageUpdateInput
+}) => Promise<NotionDataSourcePageUpdateResult>
+
+export function getDataSourceQueryView(
+	hostState: CustomBlockHostState,
+	key: string,
+	updateDataSourcePage: UpdateDataSourcePageFn,
+): DataSourceQueryView {
+	if (hostState.status !== "initialized") {
+		return EMPTY_QUERY_VIEW
+	}
+
+	const dataSource = hostState.dataSources.find(entry => entry.key === key)
+	const queryState =
+		hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+
+	if (dataSource === undefined) {
+		return {
+			items: [],
+			collectionSchema: undefined,
+			propertySchemasById: {},
+			propertySchemasByKey: {},
+			isLoading: queryState.isLoading,
+			hasMore: queryState.hasMore,
+			error: queryState.error,
+		}
+	}
+
+	const propertyIdsByKey = dataSource.propertyIdsByKey
+	const propertySchemasById = dataSource.propertySchemasById
+
+	const resolvedItems: NotionDataSourcePage[] = queryState.items.map(entry => {
+		const propertiesByKey: {
+			[key: string]: NotionDataSourceValue | undefined
+		} = {}
+		for (const [key, propertyId] of Object.entries(propertyIdsByKey)) {
+			propertiesByKey[key] =
+				propertyId === undefined ? undefined : entry.propertiesById[propertyId]
+		}
+		return {
+			id: entry.id as NotionPageId,
+			propertiesById: entry.propertiesById,
+			propertiesByKey,
+			update: input =>
+				updateDataSourcePage({
+					dataSource,
+					pageId: entry.id as NotionPageId,
+					input,
+				}),
+		}
+	})
+
+	const propertySchemasByKey: {
+		[key: string]: NotionPropertySchema | undefined
+	} = {}
+	for (const [key, propertyId] of Object.entries(propertyIdsByKey)) {
+		propertySchemasByKey[key] =
+			propertyId === undefined ? undefined : propertySchemasById[propertyId]
+	}
+
+	return {
+		items: resolvedItems,
+		collectionSchema: dataSource.collectionSchema,
+		propertySchemasById,
+		propertySchemasByKey,
+		isLoading: queryState.isLoading,
+		hasMore: queryState.hasMore,
+		error: queryState.error,
+	}
+}

package/bridge/ids.ts

@@ -0,0 +1,30 @@
+import * as v from "valibot"
+
+declare const notionDataSourceIdBrand: unique symbol
+declare const notionSpaceIdBrand: unique symbol
+
+/**
+ * Branded Notion data source ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps data source IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export type NotionDataSourceId = string & {
+	readonly [notionDataSourceIdBrand]: "NotionDataSourceId"
+}
+
+export const notionDataSourceIdSchema = v.custom<NotionDataSourceId>(
+	value => typeof value === "string",
+	"Expected a Notion data source ID",
+)
+
+/**
+ * Branded Notion workspace/space ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps space IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export type NotionSpaceId = string & {
+	readonly [notionSpaceIdBrand]: "NotionSpaceId"
+}
+
+export const notionSpaceIdSchema = v.custom<NotionSpaceId>(
+	value => typeof value === "string",
+	"Expected a Notion space ID",
+)

package/bridge/incomingType.ts

@@ -0,0 +1,19 @@
+/**
+ * Reads the `type` field off an inbound bridge message, if any.
+ *
+ * Used by both sides of the bridge after the canonical message schema rejects a payload. We still
+ * want to know what type the sender claimed to be sending so we can (a) avoid NACK loops on
+ * `invalidHostMessage` / `invalidSandboxMessage` and (b) include the type in the failure reason
+ * for debugging.
+ */
+export function readIncomingType(data: unknown): string | undefined {
+	if (
+		typeof data === "object" &&
+		data !== null &&
+		"type" in data &&
+		typeof data.type === "string"
+	) {
+		return data.type
+	}
+	return undefined
+}

package/bridge/loadManifest.ts

@@ -0,0 +1,54 @@
+import * as v from "valibot"
+import { type CustomBlockManifest, manifestSchema } from "./manifest"
+
+const MANIFEST_URL = "custom_blocks.json"
+
+/**
+ * Attempts to load a `custom_blocks.json` manifest co-located with the bundle. Treats
+ * any non-200 response as "no manifest". Warns on every failure path —
+ * templates are expected to ship a manifest, so a missing one is worth
+ * surfacing.
+ */
+export async function loadManifest(): Promise<CustomBlockManifest | null> {
+	if (typeof fetch !== "function") {
+		console.warn(
+			`[notion-custom-sdk] no \`fetch\` available; cannot load ${MANIFEST_URL}`,
+		)
+		return null
+	}
+	let response: Response
+	try {
+		response = await fetch(MANIFEST_URL, { credentials: "omit" })
+	} catch (error) {
+		console.warn(
+			`[notion-custom-sdk] no manifest fetched from ${MANIFEST_URL}`,
+			error,
+		)
+		return null
+	}
+	if (!response.ok) {
+		console.warn(
+			`[notion-custom-sdk] no manifest at ${MANIFEST_URL} (status ${response.status})`,
+		)
+		return null
+	}
+	let json: unknown
+	try {
+		json = await response.json()
+	} catch (error) {
+		console.warn(
+			`[notion-custom-sdk] manifest at ${MANIFEST_URL} was not valid JSON`,
+			error,
+		)
+		return null
+	}
+	const parsed = v.safeParse(manifestSchema, json)
+	if (!parsed.success) {
+		console.warn(
+			`[notion-custom-sdk] manifest at ${MANIFEST_URL} did not match schema`,
+			parsed.issues,
+		)
+		return null
+	}
+	return parsed.output
+}

package/bridge/manifest.ts

@@ -0,0 +1,53 @@
+import * as v from "valibot"
+import { notionPropertyTypeSchema } from "./dataSources/propertySchema"
+
+/**
+ * User-authored manifest declaring the data sources the custom block expects.
+ * Lives at `custom_blocks.json` in the project root and is forwarded to the host with
+ * the bridge `ready` message so the host can pre-bind data sources, surface
+ * configuration UI, etc. The `notionCustomBlock` Vite plugin from
+ * `ncblock/vite` wires the JSON file into the dev server and
+ * the build output.
+ */
+
+/**
+ * Decorative icon attached to a manifest data source. Mirrors the
+ * `emoji` / `external` icon variants the public Notion API uses, so the host
+ * can render a recognizable affordance next to the slot in setup UI.
+ */
+export const manifestIconSchema = v.variant("type", [
+	v.object({
+		type: v.literal("emoji"),
+		emoji: v.string(),
+	}),
+	v.object({
+		type: v.literal("external"),
+		url: v.string(),
+	}),
+])
+
+export type ManifestIcon = v.InferOutput<typeof manifestIconSchema>
+
+export const manifestPropertySchema = v.object({
+	name: v.string(),
+	description: v.optional(v.string()),
+	type: notionPropertyTypeSchema,
+})
+
+export type ManifestProperty = v.InferOutput<typeof manifestPropertySchema>
+
+export const manifestDataSourceSchema = v.object({
+	name: v.string(),
+	description: v.optional(v.string()),
+	icon: v.optional(manifestIconSchema),
+	properties: v.optional(v.record(v.string(), manifestPropertySchema), {}),
+})
+
+export type ManifestDataSource = v.InferOutput<typeof manifestDataSourceSchema>
+
+export const manifestSchema = v.object({
+	version: v.literal(1),
+	dataSources: v.record(v.string(), manifestDataSourceSchema),
+})
+
+export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>

package/bridge/messages/contextChanged.ts

@@ -0,0 +1,15 @@
+import * as v from "valibot"
+import { notionCustomBlockContextSchema } from "../context"
+
+/**
+ * Message sent by the host whenever the custom block's position in the block tree changes (e.g. it
+ * is moved into a different parent block, or its enclosing page changes).
+ */
+export const contextChangedMessageSchema = v.object({
+	type: v.literal("contextChanged"),
+	context: notionCustomBlockContextSchema,
+})
+
+export type ContextChangedMessage = v.InferOutput<
+	typeof contextChangedMessageSchema
+>

package/bridge/messages/createPage.ts

@@ -0,0 +1,64 @@
+import * as v from "valibot"
+import type { NotionDataSourceId } from "../ids"
+import type { NotionPageId } from "../pages/page"
+import {
+	notionPageCoverSchema,
+	notionPageIconSchema,
+	notionPagePropertyWriteMapSchema,
+} from "../pages/page"
+
+/**
+ * Describes where the newly created page should be inserted.
+ * - `start` / `end` (default): prepend / append to the request's `parent`
+ *   page's children.
+ * - `before` / `after`: insert as a sibling of the anchor block identified by
+ *   `blockId`, using the anchor's own structural parent. The anchor can be
+ *   nested anywhere below the page (inside a toggle, column, callout, etc.).
+ */
+export const notionCreatePagePositionSchema = v.variant("type", [
+	v.object({ type: v.literal("start") }),
+	v.object({ type: v.literal("end") }),
+	v.object({ type: v.literal("before"), blockId: v.string() }),
+	v.object({ type: v.literal("after"), blockId: v.string() }),
+])
+
+export type NotionCreatePagePosition = v.InferOutput<
+	typeof notionCreatePagePositionSchema
+>
+
+/**
+ * Parent accepted by the outbound `createPage` bridge message.
+ *
+ * Mirrors Notion's public API `POST /v1/pages` parent shape: `page_id` for a page-parented child,
+ * `data_source_id` for a database row. `data_source_id` is the internal collection ID.
+ *
+ * The SDK additionally accepts a higher-level `data_source_key` variant that resolves to
+ * `data_source_id` locally, using the `dataSources` mapping.
+ */
+export const createPageParentSchema = v.variant("type", [
+	v.object({ type: v.literal("page_id"), page_id: v.string() }),
+	v.object({
+		type: v.literal("data_source_id"),
+		data_source_id: v.string(),
+	}),
+])
+
+export type CreatePageMessageParent =
+	| { type: "page_id"; page_id: NotionPageId }
+	| { type: "data_source_id"; data_source_id: NotionDataSourceId }
+
+/**
+ * Message sent by the sandbox to ask the host to create a new page on its behalf.
+ * The payload mirrors Notion's public `POST /v1/pages` API.
+ */
+export const createPageMessageSchema = v.object({
+	type: v.literal("createPage"),
+	requestId: v.string(),
+	parent: createPageParentSchema,
+	properties: notionPagePropertyWriteMapSchema,
+	icon: v.optional(notionPageIconSchema),
+	cover: v.optional(notionPageCoverSchema),
+	position: v.optional(notionCreatePagePositionSchema),
+})
+
+export type CreatePageMessage = v.InferOutput<typeof createPageMessageSchema>

package/bridge/messages/createPageResult.ts

@@ -0,0 +1,25 @@
+import * as v from "valibot"
+import { notionPageSchema } from "../pages/page"
+
+/**
+ * Message sent by the host in response to a sandbox `createPage` request.
+ */
+export const createPageResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("createPageResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		/** The newly created page. */
+		page: notionPageSchema,
+	}),
+	v.object({
+		type: v.literal("createPageResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: v.string(),
+	}),
+])
+
+export type CreatePageResultMessage = v.InferOutput<
+	typeof createPageResultMessageSchema
+>

package/bridge/messages/dataSourcesChanged.ts

@@ -0,0 +1,18 @@
+import * as v from "valibot"
+import { notionDataSourceBindingsSchema } from "../dataSources/dataSource"
+
+/**
+ * Message sent by the host whenever the custom block's data-source mapping changes (e.g. a key is
+ * added, removed, or remapped). The SDK replaces its list of configured data sources but keeps any
+ * in-flight `useDataSource` query state for keys that still exist.
+ */
+export const dataSourcesChangedMessageSchema = v.object({
+	type: v.literal("dataSourcesChanged"),
+	dataSources: v.object({
+		bindings: notionDataSourceBindingsSchema,
+	}),
+})
+
+export type DataSourcesChangedMessage = v.InferOutput<
+	typeof dataSourcesChangedMessageSchema
+>

package/bridge/messages/getPage.ts

@@ -0,0 +1,32 @@
+import * as v from "valibot"
+import { notionPageSchema } from "../pages/page"
+
+/**
+ * Sandbox -> host: fetch a page by ID.
+ */
+export const getPageMessageSchema = v.object({
+	type: v.literal("getPage"),
+	requestId: v.string(),
+	pageId: v.string(),
+})
+
+export type GetPageMessage = v.InferOutput<typeof getPageMessageSchema>
+
+export const getPageResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("getPageResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		page: notionPageSchema,
+	}),
+	v.object({
+		type: v.literal("getPageResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: v.string(),
+	}),
+])
+
+export type GetPageResultMessage = v.InferOutput<
+	typeof getPageResultMessageSchema
+>

package/bridge/messages/getUser.ts

@@ -0,0 +1,32 @@
+import * as v from "valibot"
+import { notionUserSchema } from "../users/user"
+
+/**
+ * Sandbox -> host: fetch a user by ID.
+ */
+export const getUserMessageSchema = v.object({
+	type: v.literal("getUser"),
+	requestId: v.string(),
+	userId: v.string(),
+})
+
+export type GetUserMessage = v.InferOutput<typeof getUserMessageSchema>
+
+export const getUserResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("getUserResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		user: notionUserSchema,
+	}),
+	v.object({
+		type: v.literal("getUserResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: v.string(),
+	}),
+])
+
+export type GetUserResultMessage = v.InferOutput<
+	typeof getUserResultMessageSchema
+>

package/bridge/messages/hostToSandbox.ts

@@ -0,0 +1,33 @@
+import * as v from "valibot"
+import { contextChangedMessageSchema } from "./contextChanged"
+import { createPageResultMessageSchema } from "./createPageResult"
+import { dataSourcesChangedMessageSchema } from "./dataSourcesChanged"
+import { getPageResultMessageSchema } from "./getPage"
+import { getUserResultMessageSchema } from "./getUser"
+import { initMessageSchema } from "./init"
+import { invalidSandboxMessageSchema } from "./invalidSandboxMessage"
+import { listUsersResultMessageSchema } from "./listUsers"
+import { queryDataSourceResultMessageSchema } from "./queryDataSourceResult"
+import { themeChangedMessageSchema } from "./themeChanged"
+import { updatePageResultMessageSchema } from "./updatePageResult"
+
+/**
+ * Discriminated union of every message the host is allowed to send the sandbox.
+ */
+export const hostToSandboxMessageSchema = v.variant("type", [
+	initMessageSchema,
+	themeChangedMessageSchema,
+	contextChangedMessageSchema,
+	dataSourcesChangedMessageSchema,
+	queryDataSourceResultMessageSchema,
+	createPageResultMessageSchema,
+	getPageResultMessageSchema,
+	getUserResultMessageSchema,
+	listUsersResultMessageSchema,
+	updatePageResultMessageSchema,
+	invalidSandboxMessageSchema,
+])
+
+export type HostToSandboxMessage = v.InferOutput<
+	typeof hostToSandboxMessageSchema
+>

package/bridge/messages/init.ts

@@ -0,0 +1,20 @@
+import * as v from "valibot"
+import { notionCustomBlockContextSchema } from "../context"
+import { notionDataSourceBindingsSchema } from "../dataSources/dataSource"
+import { notionThemeSchema } from "../theme"
+
+/**
+ * Initialization message sent by the host to the sandbox exactly once, in response to the
+ * sandbox's `ready` message. After init, live updates flow through narrower messages
+ * (`themeChanged`, `contextChanged`, `dataSourcesChanged`).
+ */
+export const initMessageSchema = v.object({
+	type: v.literal("init"),
+	theme: notionThemeSchema,
+	context: notionCustomBlockContextSchema,
+	dataSources: v.object({
+		bindings: notionDataSourceBindingsSchema,
+	}),
+})
+
+export type InitMessage = v.InferOutput<typeof initMessageSchema>

package/bridge/messages/invalidHostMessage.ts

@@ -0,0 +1,16 @@
+import * as v from "valibot"
+
+/**
+ * Sent by the sandbox back to the host when an inbound host-to-sandbox message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The host should never reply to an `invalidHostMessage`
+ * with another bridge error message.
+ */
+export const invalidHostMessageSchema = v.object({
+	type: v.literal("invalidHostMessage"),
+	/**
+	 * A human-readable string intended for sandbox-side logging. It has no structured contract.
+	 */
+	reason: v.string(),
+})
+
+export type InvalidHostMessage = v.InferOutput<typeof invalidHostMessageSchema>

package/bridge/messages/invalidSandboxMessage.ts

@@ -0,0 +1,18 @@
+import * as v from "valibot"
+
+/**
+ * Sent by the host back to the sandbox when an inbound sandbox-to-host message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The sandbox should never reply to an
+ * `invalidSandboxMessage` with another bridge error message.
+ */
+export const invalidSandboxMessageSchema = v.object({
+	type: v.literal("invalidSandboxMessage"),
+	/**
+	 * A human-readable string intended for sandbox-side logging. It has no structured contract.
+	 */
+	reason: v.string(),
+})
+
+export type InvalidSandboxMessage = v.InferOutput<
+	typeof invalidSandboxMessageSchema
+>

package/bridge/messages/listUsers.ts

@@ -0,0 +1,33 @@
+import * as v from "valibot"
+import { notionUserListSchema } from "../users/user"
+
+/**
+ * Sandbox -> host: list users visible in the custom block's workspace.
+ */
+export const listUsersMessageSchema = v.object({
+	type: v.literal("listUsers"),
+	requestId: v.string(),
+	startCursor: v.optional(v.string()),
+	pageSize: v.optional(v.number()),
+})
+
+export type ListUsersMessage = v.InferOutput<typeof listUsersMessageSchema>
+
+export const listUsersResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("listUsersResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		list: notionUserListSchema,
+	}),
+	v.object({
+		type: v.literal("listUsersResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: v.string(),
+	}),
+])
+
+export type ListUsersResultMessage = v.InferOutput<
+	typeof listUsersResultMessageSchema
+>

package/bridge/messages/queryDataSource.ts

@@ -0,0 +1,16 @@
+import * as v from "valibot"
+
+/**
+ * Message sent by the sandbox to ask the host to load (or reload) a data
+ * source with a given page size.
+ */
+export const queryDataSourceMessageSchema = v.object({
+	type: v.literal("queryDataSource"),
+	requestId: v.string(),
+	key: v.string(),
+	limit: v.number(),
+})
+
+export type QueryDataSourceMessage = v.InferOutput<
+	typeof queryDataSourceMessageSchema
+>

package/bridge/messages/queryDataSourceResult.ts

@@ -0,0 +1,18 @@
+import * as v from "valibot"
+import { notionDataSourcePageBridgeSchema } from "../dataSources/dataSourcePage"
+
+/**
+ * Message sent by the host to the sandbox in response to a `queryDataSource` request.
+ */
+export const queryDataSourceResultMessageSchema = v.object({
+	type: v.literal("queryDataSourceResult"),
+	requestId: v.string(),
+	key: v.string(),
+	items: v.array(notionDataSourcePageBridgeSchema),
+	hasMore: v.boolean(),
+	error: v.optional(v.string()),
+})
+
+export type QueryDataSourceResultMessage = v.InferOutput<
+	typeof queryDataSourceResultMessageSchema
+>