@notionhq/custom-blocks 0.0.58

package/docs/manifest.md

@@ -0,0 +1,42 @@
+# Manifest
+
+A custom view declares its required data sources in `custom_blocks.json` at the project root. Notion uses the manifest to know what semantic keys the block expects, what shape each property should be, and what to show when an admin is configuring the block.
+
+```json
+{
+  "version": 1,
+  "dataSources": {
+    "tasks": {
+      "name": "Tasks",
+      "description": "The collection of tasks to render",
+      "properties": {
+        "title": { "name": "Title", "type": "title" },
+        "dueDate": { "name": "Due date", "type": "date" }
+      }
+    }
+  }
+}
+```
+
+`initCustomBlock()` fetches `custom_blocks.json` and forwards it with `ready`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK sends `ready` with `status: "success"` and `manifest: null`, which means the block has no declared data requirements. If the file is unavailable for another reason or invalid, the SDK sends `ready` with `status: "error"` and an `error` payload, and hosts should reject init by echoing the sandbox-reported error code back.
+
+## Vite plugin
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { notionCustomBlock } from "@notionhq/custom-blocks/vite";
+
+export default defineConfig({
+  plugins: [react(), notionCustomBlock()],
+});
+```
+
+In dev, the plugin serves `custom_blocks.json` from the project root so HMR + the SDK handshake see the same file. On `vite build`, it emits `custom_blocks.json` into `dist/` as a separate asset alongside the bundled HTML and JS.
+
+## Types
+
+- `CustomBlockManifest` — the parsed shape of `custom_blocks.json`.
+- `ManifestDataSource` — a single entry in `dataSources` (name, description, properties).
+- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
+- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.

package/docs/pages.md

@@ -0,0 +1,143 @@
+# `pages` API
+
+Helpers for creating, reading, updating, and archiving Notion pages from inside a custom block. The SDK forwards each call to Notion on your behalf.
+
+```ts
+import { pages } from "@notionhq/custom-blocks";
+```
+
+Every helper returns a discriminated result instead of throwing:
+
+```ts
+const result = await pages.get(pageId);
+if (result.status === "success") {
+  // result.page is a NotionPage
+} else {
+  // result.error is a human-readable string
+}
+```
+
+Always check `result.status` before reading `result.page`.
+
+## Creating pages
+
+`pages.create` mirrors Notion's [`POST /v1/pages`](https://developers.notion.com/reference/post-page). Pass a parent, a property map, and (optionally) an `icon`, `cover`, or `position`:
+
+```ts
+const result = await pages.create({
+  parent: { type: "data_source_key", key: "tasks" },
+  properties: {
+    title: {
+      type: "title",
+      title: [{ type: "text", text: { content: "New task" } }],
+    },
+    dueDate: { type: "date", date: { start: "2026-06-01" } },
+  },
+  icon: { type: "emoji", emoji: "📝" },
+  position: { type: "end" },
+});
+
+if (result.status === "success") {
+  console.log("created", result.page.id);
+}
+```
+
+### Choosing a parent
+
+`parent` is a `CreatePageParent`:
+
+```ts
+type CreatePageParent =
+  | { type: "page_id"; page_id: NotionPageId }
+  | { type: "data_source_id"; data_source_id: NotionDataSourceId }
+  | { type: "data_source_key"; key: string };
+```
+
+`type: "data_source_key"` is the recommended form inside a custom view. Pass the semantic key you declared in `custom_blocks.json` (e.g. `"tasks"`) and the SDK looks up the corresponding data source for you. The other two variants exist for the rarer case where you already have a raw Notion ID in hand.
+
+### Property keys
+
+`properties` is a `NotionPagePropertyInputMap`. Two niceties versus the raw API when the create parent resolves to a configured data source:
+
+- **Keys** can be either raw Notion property IDs _or_ the data-source property keys you declared in the manifest. The SDK resolves keys → IDs before forwarding the request. Semantic keys work for `parent.type: "data_source_key"` and for `parent.type: "data_source_id"` when that ID matches a data source delivered by `init` / `dataSourcesChanged`; use raw property IDs for `page_id` parents or unmapped data sources.
+- **Values** (`NotionPagePropertyInputValue`) may omit `id` — the SDK fills in the final raw ID for you.
+
+So if your manifest declares `title` and `dueDate`, you can write them by name (as in the example above) instead of looking up the raw IDs.
+
+### Where the new page lands
+
+`position` is a `NotionCreatePagePosition` and controls placement inside the parent:
+
+- `{ type: "start" }` / `{ type: "end" }` — prepend or append (default).
+- `{ type: "before", blockId }` / `{ type: "after", blockId }` — insert as a sibling of the given block (which can be nested anywhere under the parent).
+
+## Reading pages
+
+`pages.get(pageId)` fetches a single page by ID:
+
+```ts
+const result = await pages.get(pageId);
+if (result.status === "error") return;
+
+const page = result.page; // NotionPage
+console.log(page.properties);
+```
+
+`page` mirrors Notion's public API shape, with `id`, `parent`, `properties`, optional `icon` / `cover`, etc. — see `NotionPage` in the types list below.
+
+## Updating pages
+
+`pages.update` writes back to a page. The optional fields (`properties`, `icon`, `cover`, `archived`) are independent — supply only what you want to change:
+
+```ts
+const result = await pages.update({
+  pageId,
+  properties: {
+    "%5C%3FX%3D": {
+      id: "%5C%3FX%3D",
+      type: "checkbox",
+      checkbox: true,
+    },
+  },
+  icon: { type: "emoji", emoji: "✅" },
+});
+```
+
+The `properties` map (a `NotionPagePropertyWriteMap`) is keyed by **raw Notion property ID**, and each value must repeat that ID as its own `id` field — semantic data-source keys aren't accepted here. To update a row by configured custom-block key without writing out the raw IDs, use the `update` helper on the row returned from `useDataSource` instead; the SDK handles the key → ID resolution for you.
+
+If you call `pages.update` with no fields to change, it short-circuits and resolves with `{ status: "error", error: { code: "invalid_page_update", message: "updatePage requires at least one of: properties, icon, cover, archived.", isRetryable: false } }` — no request is sent.
+
+## Deleting (archiving) pages
+
+`pages.delete(pageId)` is a thin wrapper around `pages.update({ pageId, archived: true })`. Notion treats archive and trash the same way for pages:
+
+```ts
+await pages.delete(pageId);
+```
+
+To restore a page, call `pages.update({ pageId, archived: false })`.
+
+## Icons, covers, and file uploads
+
+File-upload references aren't enabled for custom blocks yet. For icons, covers, and file properties, use one of:
+
+- An emoji icon — `{ type: "emoji", emoji: "🟢" }`
+- An external URL — `{ type: "external", external: { url: "https://example.com/cover.png" } }`
+- An existing hosted file URL returned by Notion — `{ type: "file", file: { url: existingUrl } }`
+
+Do **not** send `{ type: "file_upload", file_upload: { id } }`; the host will reject it.
+
+## Types
+
+- `NotionPage` — the page record returned by every successful call.
+- `NotionPageId` — branded string ID for a page.
+- `NotionPageIcon` / `NotionPageCover` — icon and cover variants Notion supports.
+- `NotionParent` — a block's parent reference (`page_id` / `block_id` / `data_source_id` / `workspace`), as returned on `NotionPage.parent` and by `useParent()`.
+- `NotionPagePropertyValue` — a single property value as returned on a `NotionPage`.
+- `NotionPagePropertyInputValue` — a single property value as accepted by `pages.create` / `pages.update` (may omit `id` for `create`).
+- `NotionPagePropertyInputMap` — input map for `pages.create` (keys can be raw property IDs, or semantic keys when creating into a mapped data source).
+- `NotionPagePropertyWriteMap` — input map for `pages.update` (raw property IDs only).
+- `NotionCreatePagePosition` — `start` / `end` / `before` / `after` insertion variants.
+- `CreatePageInput` / `CreatePageParent` / `CreatePageResult`.
+- `GetPageResult`.
+- `UpdatePageInput` / `UpdatePageResult`.

package/docs/users.md

@@ -0,0 +1,92 @@
+# `users` API
+
+Helpers for reading workspace users from inside a custom block. The SDK forwards each call to Notion on your behalf.
+
+```ts
+import {
+  customBlock,
+  initCustomBlock,
+  users,
+  type NotionUserId,
+} from "@notionhq/custom-blocks";
+import { useCurrentUser } from "@notionhq/custom-blocks/react";
+```
+
+Every helper returns a discriminated result instead of throwing:
+
+```ts
+const result = await users.get(userId);
+if (result.status === "success") {
+  // result.user is a NotionUser
+} else {
+  // result.error is a human-readable string
+}
+```
+
+Always check `result.status` before reading `result.user` / `result.list`.
+
+## Reading the current user
+
+`useCurrentUser()` returns the viewing user's `NotionUser` from the initial host payload, so your first render can personalize or filter without a separate `users.get` request.
+
+```ts
+const me = useCurrentUser();
+// me.id, me.name, me.person.email
+```
+
+The hook updates when the host sends `currentUserChanged`, so renders stay in sync if the viewer's profile changes.
+
+For non-React renderers, read the same state through `customBlock` after initialization:
+
+```ts
+await initCustomBlock()
+const me = customBlock.getCurrentUser()
+
+const unsubscribe = customBlock.subscribe(() => {
+	const nextMe = customBlock.getCurrentUser()
+	// Update your renderer with nextMe.
+})
+```
+
+## Listing users
+
+`users.list(input?)` returns workspace users visible to the current custom block, mirroring Notion's [`GET /v1/users`](https://developers.notion.com/reference/get-users) shape.
+
+```ts
+const result = await users.list({ pageSize: 50 });
+if (result.status === "error") return;
+
+for (const user of result.list.results) {
+  console.log(user.id, user.name, user.person.email);
+}
+
+if (result.list.has_more && result.list.next_cursor) {
+  const next = await users.list({ startCursor: result.list.next_cursor });
+  // ...
+}
+```
+
+`ListUsersInput` accepts `pageSize` and `startCursor`; both are optional. `ListUsersResult` resolves to either `{ status: "success", list }` or `{ status: "error", error }`, where `list` is a `NotionUserList` (with `results`, `next_cursor`, `has_more`).
+
+## Reading a single user
+
+`users.get(userId)` fetches one `NotionUser` by `NotionUserId`:
+
+```ts
+const result = await users.get(userId);
+if (result.status === "success") {
+  console.log(result.user.name);
+}
+```
+
+`GetUserResult` follows the same success/error shape and returns `{ status: "success", user }` when the host resolves the user.
+
+## Types
+
+- `NotionUser` — the user record returned by `users.get` and inside `NotionUserList.results`.
+- `NotionUserId` — branded string ID for a user.
+- `NotionUserList` — paginated list shape returned by `users.list`.
+- `useCurrentUser()` — hook that returns the viewer's `NotionUser`.
+- `customBlock.getCurrentUser()` — framework-neutral getter for the viewer's `NotionUser`.
+- `ListUsersInput` / `ListUsersResult`.
+- `GetUserResult`.

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@notionhq/custom-blocks",
+	"version": "0.0.58",
+	"license": "MIT",
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/makenotion/custom-blocks",
+		"directory": "sdk"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./react": {
+			"import": "./dist/react/index.js",
+			"types": "./dist/react/index.d.ts"
+		},
+		"./host": {
+			"import": "./dist/host.js",
+			"types": "./dist/host.d.ts"
+		},
+		"./vite": {
+			"import": "./vite-plugin/index.js",
+			"types": "./vite-plugin/index.d.ts"
+		}
+	},
+	"bin": {
+		"ncblock": "./bin/cli/cli.js"
+	},
+	"scripts": {
+		"test": "vitest run --environment jsdom",
+		"typecheck": "tsc --project tsconfig.json"
+	},
+	"files": [
+		"src",
+		"bin",
+		"HOST.md",
+		"docs",
+		"vite-plugin",
+		"dist"
+	],
+	"peerDependencies": {
+		"react": "^19.2.5"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.2",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"jsdom": "^29.1.0",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5",
+		"vitest": "^4.1.5"
+	},
+	"dependencies": {
+		"valibot": "^1.3.1"
+	}
+}

package/src/autoResize.ts

@@ -0,0 +1,84 @@
+import { customBlockHost } from "./bridge/sandboxClient.js"
+
+/** Limits host resize messages to 10 per second while preserving the latest height. */
+const AUTO_RESIZE_THROTTLE_MS = 100
+
+export function autoResize(args: {
+	target: HTMLElement | null | undefined
+}): () => void {
+	const { target } = args
+	if (target === null || target === undefined) {
+		return () => {}
+	}
+
+	// Use a leading/trailing throttle: send the first changed height immediately, then retain only
+	// the latest height observed and send it when the throttling period ends.
+	let lastHeightReportedToHost = -1
+	let pendingHeight: number | undefined
+	let throttleTimeout: ReturnType<typeof setTimeout> | undefined
+
+	/** Sends a height immediately and records it as the deduplication baseline. */
+	const sendHeightToHost = (height: number) => {
+		lastHeightReportedToHost = height
+		customBlockHost.postResize(height)
+	}
+
+	/** Sends the latest height queued during the throttling period, if one exists. */
+	const flushPendingHeight = () => {
+		if (throttleTimeout !== undefined) {
+			clearTimeout(throttleTimeout)
+			throttleTimeout = undefined
+		}
+		if (pendingHeight === undefined) {
+			return
+		}
+		const height = pendingHeight
+		pendingHeight = undefined
+		sendHeightToHost(height)
+		throttleTimeout = setTimeout(flushPendingHeight, AUTO_RESIZE_THROTTLE_MS)
+	}
+
+	/** Measures the target and either sends, queues, or deduplicates its height. */
+	const measureAndScheduleResize = () => {
+		const next = Math.ceil(target.getBoundingClientRect().height)
+		if (next === lastHeightReportedToHost) {
+			// The height has not changed since the last measurement. Do nothing.
+			pendingHeight = undefined
+			return
+		}
+		if (throttleTimeout !== undefined) {
+			// The height has changed since the last measurement, but the throttling period has not
+			// ended. Queue the new height for later.
+			pendingHeight = next
+			return
+		}
+
+		// The height has changed since the last measurement and the throttling period has ended.
+		// Send the new height immediately and start a new throttling period.
+		sendHeightToHost(next)
+		throttleTimeout = setTimeout(flushPendingHeight, AUTO_RESIZE_THROTTLE_MS)
+	}
+
+	// Measure the initial height and schedule the first throttling period.
+	measureAndScheduleResize()
+
+	// If the ResizeObserver API is not available, return a function that cleans up the throttling
+	// period started by the initial measurement.
+	if (typeof ResizeObserver === "undefined") {
+		return () => {
+			clearTimeout(throttleTimeout)
+			throttleTimeout = undefined
+		}
+	}
+
+	// Observe the target and schedule subsequent measurements and throttling periods.
+	const observer = new ResizeObserver(measureAndScheduleResize)
+	observer.observe(target)
+
+	// Clean up the observer and the throttling period.
+	return () => {
+		observer.disconnect()
+		clearTimeout(throttleTimeout)
+		throttleTimeout = undefined
+	}
+}