ncblock 0.0.3 → 0.0.5

package/bridge/messages/ready.ts

@@ -0,0 +1,25 @@
+import * as v from "valibot"
+import { manifestSchema } from "../manifest"
+
+/**
+ * First message the sandbox sends after mount, kicking off the bridge handshake. The host replies
+ * with `init`.
+ */
+export const readyMessageSchema = v.object({
+	type: v.literal("ready"),
+	/**
+	 * 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.
+	 */
+	bridgeProtocolVersion: v.optional(v.number()),
+	/**
+	 * The data sources and settings the custom block expects. A sandbox sends `null` if it has no
+	 * manifest-declared data requirements. `null` is used (rather than `undefined`) so the
+	 * wire-level distinction between "explicitly no manifest" and "field omitted" survives
+	 * `postMessage` serialization and runtime validation on the host.
+	 */
+	manifest: v.union([manifestSchema, v.null_()]),
+})
+
+export type ReadyMessage = v.InferOutput<typeof readyMessageSchema>

package/bridge/messages/resize.ts

@@ -0,0 +1,13 @@
+import * as v from "valibot"
+
+/**
+ * Message sent by the sandbox whenever its measured content height changes, so the host can resize
+ * the surrounding iframe to match. The host is free to clamp the value or ignore it. The sandbox
+ * always reports the most recent measurement.
+ */
+export const resizeMessageSchema = v.object({
+	type: v.literal("resize"),
+	height: v.pipe(v.number(), v.finite(), v.minValue(0)),
+})
+
+export type ResizeMessage = v.InferOutput<typeof resizeMessageSchema>

package/bridge/messages/sandboxToHost.ts

@@ -0,0 +1,30 @@
+import * as v from "valibot"
+import { createPageMessageSchema } from "./createPage"
+import { getPageMessageSchema } from "./getPage"
+import { getUserMessageSchema } from "./getUser"
+import { invalidHostMessageSchema } from "./invalidHostMessage"
+import { listUsersMessageSchema } from "./listUsers"
+import { queryDataSourceMessageSchema } from "./queryDataSource"
+import { readyMessageSchema } from "./ready"
+import { resizeMessageSchema } from "./resize"
+import { updatePageMessageSchema } from "./updatePage"
+
+/**
+ * Discriminated union of every message the sandbox is allowed to send the host. Useful for hosts
+ * to validate inbound traffic from sandboxes without re-implementing validation logic.
+ */
+export const sandboxToHostMessageSchema = v.variant("type", [
+	readyMessageSchema,
+	queryDataSourceMessageSchema,
+	createPageMessageSchema,
+	getPageMessageSchema,
+	getUserMessageSchema,
+	listUsersMessageSchema,
+	updatePageMessageSchema,
+	resizeMessageSchema,
+	invalidHostMessageSchema,
+])
+
+export type SandboxToHostMessage = v.InferOutput<
+	typeof sandboxToHostMessageSchema
+>

package/bridge/messages/themeChanged.ts

@@ -0,0 +1,15 @@
+import * as v from "valibot"
+import { notionThemeSchema } from "../theme"
+
+/**
+ * Message sent by the host every time the theme changes after the initial
+ * `init` handshake.
+ */
+export const themeChangedMessageSchema = v.object({
+	type: v.literal("themeChanged"),
+	theme: notionThemeSchema,
+})
+
+export type ThemeChangedMessage = v.InferOutput<
+	typeof themeChangedMessageSchema
+>

package/bridge/messages/updatePage.ts

@@ -0,0 +1,21 @@
+import * as v from "valibot"
+import {
+	notionPageCoverSchema,
+	notionPageIconSchema,
+	notionPagePropertyWriteMapSchema,
+} from "../pages/page"
+
+/**
+ * Sandbox -> host: patch an existing page.
+ */
+export const updatePageMessageSchema = v.object({
+	type: v.literal("updatePage"),
+	requestId: v.string(),
+	pageId: v.string(),
+	properties: v.optional(notionPagePropertyWriteMapSchema),
+	icon: v.optional(notionPageIconSchema),
+	cover: v.optional(notionPageCoverSchema),
+	archived: v.optional(v.boolean()),
+})
+
+export type UpdatePageMessage = v.InferOutput<typeof updatePageMessageSchema>

package/bridge/messages/updatePageResult.ts

@@ -0,0 +1,24 @@
+import * as v from "valibot"
+import { notionPageSchema } from "../pages/page"
+
+/**
+ * Host -> sandbox: result for a page update request.
+ */
+export const updatePageResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("updatePageResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		page: notionPageSchema,
+	}),
+	v.object({
+		type: v.literal("updatePageResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: v.string(),
+	}),
+])
+
+export type UpdatePageResultMessage = v.InferOutput<
+	typeof updatePageResultMessageSchema
+>

package/bridge/pages/page.ts

@@ -0,0 +1,314 @@
+/**
+ * Notion page shapes exchanged over the custom block bridge.
+ *
+ * These mirror a narrow subset of Notion's public `POST /v1/pages` API, since that's the bridge
+ * shape the host delivers for messages like `createPageResult`.
+ */
+
+import * as v from "valibot"
+import type { NotionDataSourceId } from "../ids"
+
+declare const notionPageIdBrand: unique symbol
+
+/**
+ * Branded Notion page ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps page IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export type NotionPageId = string & {
+	readonly [notionPageIdBrand]: "NotionPageId"
+}
+
+/**
+ * Parent reference accepted by `pages.create` / `pages.update` inputs.
+ *
+ * Mirrors the parent shape Notion's public `POST /v1/pages` API accepts: `page_id` for a
+ * page-parented child, `data_source_id` for a database row. `data_source_id` is the internal
+ * collection ID.
+ */
+export const notionPageParentInputSchema = 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 NotionPageParentInput =
+	| { type: "page_id"; page_id: NotionPageId }
+	| { type: "data_source_id"; data_source_id: NotionDataSourceId }
+
+/**
+ * Parent reference returned on a `Page` object from the host.
+ *
+ * Wider than the input shape: in addition to `page_id` / `data_source_id`, this includes
+ * `workspace` (for top-level/team-rooted pages) and `block_id` (for pages nested under a
+ * non-page block, e.g. a column or toggle). This mirrors the parent variants the public API
+ * surfaces on `Page` responses.
+ */
+export const notionPageParentSchema = 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(),
+	}),
+	v.object({ type: v.literal("workspace"), workspace: v.literal(true) }),
+	v.object({ type: v.literal("block_id"), block_id: v.string() }),
+])
+export type NotionPageParent =
+	| { type: "page_id"; page_id: NotionPageId }
+	| { type: "data_source_id"; data_source_id: NotionDataSourceId }
+	| { type: "workspace"; workspace: true }
+	| { type: "block_id"; block_id: string }
+
+export const notionEmojiIconSchema = v.object({
+	type: v.literal("emoji"),
+	emoji: v.string(),
+})
+export const notionCustomEmojiIconSchema = v.object({
+	type: v.literal("custom_emoji"),
+	custom_emoji: v.object({
+		id: v.string(),
+		name: v.optional(v.string()),
+		url: v.optional(v.string()),
+	}),
+})
+export const notionExternalFileSchema = v.object({
+	type: v.literal("external"),
+	external: v.object({ url: v.string() }),
+})
+export const notionHostedFileSchema = v.object({
+	type: v.literal("file"),
+	file: v.object({
+		url: v.string(),
+		expiry_time: v.optional(v.string()),
+	}),
+})
+
+// TODO: Add file upload support.
+export const notionPageIconSchema = v.variant("type", [
+	notionEmojiIconSchema,
+	notionCustomEmojiIconSchema,
+	notionExternalFileSchema,
+	notionHostedFileSchema,
+])
+export type NotionPageIcon = v.InferOutput<typeof notionPageIconSchema>
+
+export const notionPageCoverSchema = v.variant("type", [
+	notionExternalFileSchema,
+	notionHostedFileSchema,
+])
+export type NotionPageCover = v.InferOutput<typeof notionPageCoverSchema>
+
+const nullableStringSchema = v.nullable(v.string())
+
+const notionRichTextItemSchema = v.record(v.string(), v.unknown())
+export type NotionRichTextItem = v.InferOutput<typeof notionRichTextItemSchema>
+
+const notionSelectOptionInputSchema = v.union([
+	v.object({
+		id: v.string(),
+		name: v.optional(v.string()),
+		color: v.optional(v.string()),
+		description: v.optional(nullableStringSchema),
+	}),
+	v.object({
+		name: v.string(),
+		id: v.optional(v.string()),
+		color: v.optional(v.string()),
+		description: v.optional(nullableStringSchema),
+	}),
+])
+export type NotionSelectOptionInput = v.InferOutput<
+	typeof notionSelectOptionInputSchema
+>
+
+const notionDateInputSchema = v.object({
+	start: v.string(),
+	end: v.optional(nullableStringSchema),
+	time_zone: v.optional(nullableStringSchema),
+})
+export type NotionDateInput = v.InferOutput<typeof notionDateInputSchema>
+
+const notionUserInputSchema = v.union([
+	v.object({
+		object: v.optional(v.literal("user")),
+		id: v.string(),
+	}),
+	v.object({
+		object: v.literal("group"),
+		id: v.string(),
+		name: v.optional(nullableStringSchema),
+	}),
+])
+export type NotionUserInput = v.InferOutput<typeof notionUserInputSchema>
+
+const notionRelationInputSchema = v.object({ id: v.string() })
+export type NotionRelationInput = v.InferOutput<
+	typeof notionRelationInputSchema
+>
+
+const notionFileInputSchema = v.union([
+	v.object({
+		type: v.literal("external"),
+		name: v.string(),
+		external: v.object({ url: v.string() }),
+	}),
+	v.object({
+		type: v.literal("file"),
+		name: v.string(),
+		file: v.object({
+			url: v.string(),
+			expiry_time: v.optional(v.string()),
+		}),
+	}),
+])
+export type NotionFileInput = v.InferOutput<typeof notionFileInputSchema>
+
+const notionPlaceInputSchema = v.object({
+	lat: v.number(),
+	lon: v.number(),
+	name: v.optional(nullableStringSchema),
+	address: v.optional(nullableStringSchema),
+	aws_place_id: v.optional(nullableStringSchema),
+	google_place_id: v.optional(nullableStringSchema),
+})
+export type NotionPlaceInput = v.InferOutput<typeof notionPlaceInputSchema>
+
+const pagePropertyBaseSchema = {
+	id: v.string(),
+}
+
+/**
+ * A page property value.
+ */
+export const notionPagePropertyValueSchema = v.variant("type", [
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("title"),
+		title: v.array(notionRichTextItemSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("rich_text"),
+		rich_text: v.array(notionRichTextItemSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("number"),
+		number: v.nullable(v.number()),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("url"),
+		url: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("email"),
+		email: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("phone_number"),
+		phone_number: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("checkbox"),
+		checkbox: v.boolean(),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("select"),
+		select: v.nullable(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("status"),
+		status: v.nullable(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("multi_select"),
+		multi_select: v.array(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("date"),
+		date: v.nullable(notionDateInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("people"),
+		people: v.array(notionUserInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("relation"),
+		has_more: v.optional(v.boolean()),
+		relation: v.array(notionRelationInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("files"),
+		files: v.array(notionFileInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("place"),
+		place: v.nullable(notionPlaceInputSchema),
+	}),
+])
+export type NotionPagePropertyValue = v.InferOutput<
+	typeof notionPagePropertyValueSchema
+>
+
+type WithOptionalPropertyId<T> = T extends { id: string }
+	? Omit<T, "id"> & { id?: string }
+	: never
+
+/**
+ * Public SDK page property write input. Keys may be raw property IDs or data-source
+ * property keys. `id` is optional because the SDK resolves the final raw property ID
+ * from the map key before sending the bridge message.
+ */
+export type NotionPagePropertyInputValue =
+	WithOptionalPropertyId<NotionPagePropertyValue>
+
+export type NotionPagePropertyInputMap = {
+	[propertyIdOrKey: string]: NotionPagePropertyInputValue
+}
+
+export const notionPagePropertyWriteMapSchema = v.record(
+	v.string(),
+	notionPagePropertyValueSchema,
+)
+export type NotionPagePropertyWriteMap = v.InferOutput<
+	typeof notionPagePropertyWriteMapSchema
+>
+
+/**
+ * The `Page` object returned in `createPageResult` messages.
+ */
+export const notionPageSchema = v.object({
+	object: v.literal("page"),
+	id: v.string(),
+	parent: notionPageParentSchema,
+	properties: notionPagePropertyWriteMapSchema,
+	created_time: v.optional(v.string()),
+	last_edited_time: v.optional(v.string()),
+	icon: v.optional(notionPageIconSchema),
+	cover: v.optional(notionPageCoverSchema),
+	url: v.optional(v.string()),
+	public_url: v.optional(v.string()),
+	in_trash: v.optional(v.boolean()),
+})
+export type NotionPage = Omit<
+	v.InferOutput<typeof notionPageSchema>,
+	"id" | "parent" | "properties" | "icon" | "cover"
+> & {
+	id: NotionPageId
+	parent: NotionPageParent
+	properties: NotionPagePropertyWriteMap
+	icon?: NotionPageIcon
+	cover?: NotionPageCover
+}

package/bridge/pendingRequests.ts

@@ -0,0 +1,28 @@
+/**
+ * Tracks one-shot request/response pairs over the `postMessage` bridge. Each `allocate` reserves a
+ * unique `requestId` and stores its resolver. `resolve` finds the pending resolver by `requestId`
+ * and calls it, then removes the entry so the same `requestId` cannot be resolved twice.
+ */
+export class PendingRequests<T> {
+	private nextId = 1
+	private readonly entries = new Map<string, (value: T) => void>()
+
+	constructor(private readonly prefix: string) {}
+
+	allocate(resolver: (value: T) => void): string {
+		const requestId = `${this.prefix}-${this.nextId}`
+		this.nextId += 1
+		this.entries.set(requestId, resolver)
+		return requestId
+	}
+
+	resolve(requestId: string, value: T): boolean {
+		const resolver = this.entries.get(requestId)
+		if (resolver === undefined) {
+			return false
+		}
+		this.entries.delete(requestId)
+		resolver(value)
+		return true
+	}
+}

package/bridge/sandboxClient.ts

@@ -0,0 +1,112 @@
+import type {
+	CreatePageInput,
+	CreatePageResult,
+	GetPageResult,
+	GetUserResult,
+	ListUsersInput,
+	ListUsersResult,
+	NotionPageId,
+	NotionUserId,
+	UpdatePageInput,
+	UpdatePageResult,
+} from "../types"
+import {
+	type CustomBlockHostState,
+	type DataSourceQueryView,
+	getDataSourceQueryView as getDataSourceQueryViewWithBridge,
+} from "./hostState"
+import type { CustomBlockManifest } from "./manifest"
+import type { InitMessage } from "./messages/init"
+import { SandboxBridge } from "./SandboxBridge"
+
+const bridge = new SandboxBridge()
+
+export function sendCustomBlockReady(manifest: CustomBlockManifest | null) {
+	bridge.sendReady(manifest)
+}
+
+export function awaitCustomBlockInit(
+	signal?: AbortSignal,
+): Promise<InitMessage> {
+	return bridge.awaitInit(signal)
+}
+
+export function subscribeToCustomBlockHost(listener: () => void) {
+	return bridge.subscribe(listener)
+}
+
+export function getCustomBlockHostState(): CustomBlockHostState {
+	return bridge.getHostState()
+}
+
+export function queryCustomBlockDataSource(key: string, limit: number) {
+	bridge.queryDataSource(key, limit)
+}
+
+/**
+ * Apply an `init` payload to the bridge directly, bypassing the postMessage
+ * handshake. Used by the React provider when it needs to seed placeholder
+ * state (e.g. the standalone preview fallback when not embedded in Notion).
+ * The bridge applies the payload through the same code path as a real host.
+ */
+export function setMockCustomBlockState(message: InitMessage) {
+	bridge.setMockState(message)
+}
+
+export function postCustomBlockResize(height: number) {
+	bridge.postResize(height)
+}
+
+export function getUser(userId: NotionUserId): Promise<GetUserResult> {
+	return bridge.getUser(userId)
+}
+
+export function listUsers(input?: ListUsersInput): Promise<ListUsersResult> {
+	return bridge.listUsers(input)
+}
+
+/**
+ * Resolves the host state for a given data-source key into the public {@link DataSourceQueryView},
+ * baking in the singleton bridge so per-row `update` calls flow through it.
+ */
+export function getDataSourceQueryView(
+	hostState: CustomBlockHostState,
+	key: string,
+): DataSourceQueryView {
+	return getDataSourceQueryViewWithBridge(hostState, key, args =>
+		bridge.updateDataSourcePage(args),
+	)
+}
+
+/**
+ * Page-related SDK APIs exposed under `sdk.pages.*`.
+ */
+export const pages = {
+	/**
+	 * Creates a new Notion page.
+	 */
+	create(input: CreatePageInput): Promise<CreatePageResult> {
+		return bridge.createPage(input)
+	},
+
+	/**
+	 * Fetches a page by id.
+	 */
+	get(pageId: NotionPageId): Promise<GetPageResult> {
+		return bridge.getPage(pageId)
+	},
+
+	/**
+	 * Updates an existing page.
+	 */
+	update(input: UpdatePageInput): Promise<UpdatePageResult> {
+		return bridge.updatePage(input)
+	},
+
+	/**
+	 * Soft-delete a page by archiving it.
+	 */
+	delete(pageId: NotionPageId): Promise<UpdatePageResult> {
+		return bridge.updatePage({ pageId, archived: true })
+	},
+}

package/bridge/theme.ts

@@ -0,0 +1,5 @@
+import * as v from "valibot"
+
+export const notionThemeSchema = v.picklist(["light", "dark"])
+
+export type NotionTheme = v.InferOutput<typeof notionThemeSchema>

package/bridge/users/user.ts

@@ -0,0 +1,31 @@
+import * as v from "valibot"
+
+declare const notionUserIdBrand: unique symbol
+
+export type NotionUserId = string & {
+	readonly [notionUserIdBrand]: "NotionUserId"
+}
+
+export const notionUserSchema = v.object({
+	object: v.literal("user"),
+	id: v.string(),
+	name: v.optional(v.string()),
+	avatar_url: v.nullable(v.string()),
+	type: v.literal("person"),
+	person: v.object({
+		email: v.string(),
+	}),
+})
+
+export type NotionUser = v.InferOutput<typeof notionUserSchema>
+
+export const notionUserListSchema = v.object({
+	object: v.literal("list"),
+	results: v.array(notionUserSchema),
+	next_cursor: v.nullable(v.string()),
+	has_more: v.boolean(),
+	type: v.literal("user"),
+	user: v.record(v.string(), v.unknown()),
+})
+
+export type NotionUserList = v.InferOutput<typeof notionUserListSchema>

package/docs/context.md

@@ -0,0 +1,45 @@
+# Context & theme
+
+Every custom block runs inside a larger Notion document. These hooks expose that environment: the block itself, the containers it sits inside, and how the surrounding Notion app is currently presented (e.g. light vs. dark theme).
+
+## API
+
+### `useCustomBlockContext()`
+
+Returns the block's location in the document tree:
+
+- `customBlockId` — the block's own ID.
+- `parent` — the immediate container (e.g., toggle, column, callout, the page itself).
+- `page` — the closest enclosing `page` / `collection_view_page` ancestor.
+
+Re-renders on `contextChanged` (e.g. the block moves containers).
+
+```ts
+function useCustomBlockContext(): NotionCustomBlockContext;
+
+type NotionCustomBlockContext = {
+  customBlockId: string;
+  parent: { id: string; type: string };
+  page: { id: string; type: string };
+};
+```
+
+### `useTheme()`
+
+Returns the host's current theme.
+
+Re-renders on every `themeChanged` message.
+
+```ts
+function useTheme(): NotionTheme; // "light" | "dark"
+```
+
+```tsx
+import { useCustomBlockContext, useTheme } from "ncblock";
+
+export function Header() {
+  const { page } = useCustomBlockContext();
+  const theme = useTheme();
+  return <header data-theme={theme}>Page: {page.id}</header>;
+}
+```