@notionhq/custom-blocks 0.0.76 → 0.0.78

package/src/host/queries/querySubscriptions.ts

@@ -1,52 +1,71 @@
 import type { NotionDataSourceId } from "../../bridge/ids.js"
 import type { QueryDataSourceMessage } from "../../bridge/messages/queryDataSource.js"
-import type {
-	CustomBlockHostQueryDataSourceResult,
-	QuerySubscriptionState,
-} from "./types.js"
-
-export type QueryRefreshResult =
-	| {
-			status: "success"
-			requestId: string
-			snapshotId: string
-			response: CustomBlockHostQueryDataSourceResult
-	  }
-	| { status: "missing" }
+import type { CustomBlockHostQueryDataSourceResult } from "./types.js"
+
+export type QueryRefresh = {
+	subscriptionId: string
+	response: CustomBlockHostQueryDataSourceResult
+}
+
+type QuerySubscriptionToken = object
+
+type QuerySubscriptionState = {
+	dataSourceId: NotionDataSourceId
+	limit: number
+	token: QuerySubscriptionToken
+}
 
 export class QuerySubscriptions {
-	private readonly latestByDataSourceId = new Map<
-		NotionDataSourceId,
-		QuerySubscriptionState
-	>()
-
-	track(message: QueryDataSourceMessage) {
-		this.latestByDataSourceId.set(message.dataSourceId, {
-			requestId: message.requestId,
-			snapshotId: message.snapshotId,
+	private readonly bySubscriptionId = new Map<string, QuerySubscriptionState>()
+
+	track(message: QueryDataSourceMessage): QuerySubscriptionToken {
+		const token = {}
+		this.bySubscriptionId.set(message.subscriptionId, {
+			dataSourceId: message.dataSourceId,
 			limit: message.limit,
+			token,
 		})
+		return token
+	}
+
+	isCurrent(subscriptionId: string, token: QuerySubscriptionToken): boolean {
+		return this.bySubscriptionId.get(subscriptionId)?.token === token
 	}
 
-	resolveRefresh(args: {
+	resolveRefreshes(args: {
 		dataSourceId: NotionDataSourceId
 		response: CustomBlockHostQueryDataSourceResult
-	}): QueryRefreshResult {
-		const queryState = this.latestByDataSourceId.get(args.dataSourceId)
-		if (!queryState) {
-			return { status: "missing" }
-		}
-		const items = args.response.items.slice(0, queryState.limit)
-		return {
-			status: "success",
-			requestId: queryState.requestId,
-			snapshotId: queryState.snapshotId,
-			response: {
-				items,
-				hasMore:
-					args.response.hasMore ?? args.response.items.length > items.length,
-				error: args.response.error,
-			},
+	}): QueryRefresh[] {
+		const refreshes: QueryRefresh[] = []
+		for (const [subscriptionId, queryState] of this.bySubscriptionId) {
+			if (queryState.dataSourceId !== args.dataSourceId) {
+				continue
+			}
+			queryState.token = {}
+			refreshes.push({
+				subscriptionId,
+				response: limitResponse(args.response, queryState.limit),
+			})
 		}
+		return refreshes
+	}
+
+	clear() {
+		this.bySubscriptionId.clear()
+	}
+}
+
+function limitResponse(
+	response: CustomBlockHostQueryDataSourceResult,
+	limit: number,
+): CustomBlockHostQueryDataSourceResult {
+	if (response.status === "error") {
+		return response
+	}
+	const items = response.items.slice(0, limit)
+	return {
+		status: "success",
+		items,
+		hasMore: response.hasMore || response.items.length > items.length,
 	}
 }

package/src/host/queries/types.ts

@@ -1,14 +1,13 @@
 import type { NotionDataSourcePageBridge } from "../../bridge/dataSources/dataSourcePage.js"
-import type { QueryDataSourceMessage } from "../../bridge/messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "../../bridge/messages/queryDataSourceResult.js"
 
-export type CustomBlockHostQueryDataSourceResult = {
-	items: NotionDataSourcePageBridge[]
-	hasMore?: boolean
-	error?: CustomBlockQueryDataSourceErrorInfo
-}
-
-export type QuerySubscriptionState = Pick<
-	QueryDataSourceMessage,
-	"requestId" | "snapshotId" | "limit"
->
+export type CustomBlockHostQueryDataSourceResult =
+	| {
+			status: "success"
+			items: NotionDataSourcePageBridge[]
+			hasMore: boolean
+	  }
+	| {
+			status: "error"
+			error: CustomBlockQueryDataSourceErrorInfo
+	  }

package/src/host.ts

@@ -38,6 +38,8 @@ export {
 	notionPageIdSchema,
 } from "./bridge/ids.js"
 export { readIncomingType } from "./bridge/incomingType.js"
+export type { ConnectMessage } from "./bridge/messages/connect.js"
+export { connectMessageSchema } from "./bridge/messages/connect.js"
 export type { CreatePageMessage } from "./bridge/messages/createPage.js"
 export { createPageMessageSchema } from "./bridge/messages/createPage.js"
 export type {
@@ -90,6 +92,16 @@ export {
 	customBlockInitErrorInfoSchema,
 	initMessageSchema,
 } from "./bridge/messages/init.js"
+export type {
+	CustomBlockInitResultErrorCode,
+	CustomBlockInitResultErrorInfo,
+	InitResultMessage,
+} from "./bridge/messages/initResult.js"
+export {
+	customBlockInitResultErrorCodeSchema,
+	customBlockInitResultErrorInfoSchema,
+	initResultMessageSchema,
+} from "./bridge/messages/initResult.js"
 export type { InvalidHostMessage } from "./bridge/messages/invalidHostMessage.js"
 export { invalidHostMessageSchema } from "./bridge/messages/invalidHostMessage.js"
 export type { InvalidSandboxMessage } from "./bridge/messages/invalidSandboxMessage.js"
@@ -122,8 +134,6 @@ export {
 	customBlockQueryDataSourceErrorInfoSchema,
 	queryDataSourceResultMessageSchema,
 } from "./bridge/messages/queryDataSourceResult.js"
-export type { ReadyMessage } from "./bridge/messages/ready.js"
-export { readyMessageSchema } from "./bridge/messages/ready.js"
 export type { ResizeMessage } from "./bridge/messages/resize.js"
 export { resizeMessageSchema } from "./bridge/messages/resize.js"
 export type { SandboxToHostMessage } from "./bridge/messages/sandboxToHost.js"
@@ -151,6 +161,7 @@ export {
 	createCustomBlockHost,
 } from "./host/createCustomBlockHost.js"
 export type {
+	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialDataSources,
 	CustomBlockHostInitialState,

package/src/index.ts

@@ -79,8 +79,10 @@ export type {
 export type {
 	CustomBlockInitErrorCode,
 	CustomBlockInitErrorInfo,
+	CustomBlockInitializationErrorCode,
+	CustomBlockInitializationErrorInfo,
 } from "./bridge/messages/init.js"
-export { CustomBlockInitError } from "./bridge/messages/init.js"
+export { CustomBlockInitializationError } from "./bridge/messages/init.js"
 export type {
 	CustomBlockListUsersErrorCode,
 	CustomBlockListUsersErrorInfo,

package/src/init.ts

@@ -1,19 +1,16 @@
 import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "./bridge/ids.js"
 import { loadManifest } from "./bridge/loadManifest.js"
-import {
-	CustomBlockInitError,
-	type CustomBlockInitErrorCode,
-	type InitMessage,
-} from "./bridge/messages/init.js"
+import { CustomBlockInitializationError } from "./bridge/messages/init.js"
 import type { CustomBlockPage } from "./bridge/pages/page.js"
 import type { NotionParent } from "./bridge/parent.js"
 import { customBlockHost } from "./bridge/sandboxClient.js"
 import type { NotionTheme } from "./bridge/theme.js"
 import type { NotionUser } from "./bridge/users/user.js"
+import { unreachable } from "./utils.js"
 
 /**
- * The payload sent by the host in the `init` message in response to the sandbox's `ready` message.
+ * The payload sent by the host in the `init` message in response to the sandbox's `connect` message.
  */
 export type CustomBlockInitPayload = {
 	theme: NotionTheme
@@ -30,16 +27,17 @@ export type CustomBlockInitPayload = {
  * `<NotionCustomBlock>` catches this specifically and falls back to a standalone preview with a
  * warning banner. Direct callers can `instanceof` it to apply their own policy.
  */
-export class NotInIframeError extends Error {
+export class NotInIframeError extends CustomBlockInitializationError {
 	constructor(message: string = NOT_IN_IFRAME_MESSAGE) {
-		super(message)
+		super({
+			code: "not_in_iframe",
+			message,
+			isRetryable: false,
+		})
 		this.name = "NotInIframeError"
-		this.code = "not_in_iframe"
-		this.isRetryable = false
 	}
 
-	code: CustomBlockInitErrorCode
-	isRetryable: boolean
+	declare code: "not_in_iframe"
 }
 
 /**
@@ -64,9 +62,10 @@ let initPromise: Promise<CustomBlockInitPayload> | undefined
 
 /**
  * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `ready`, then awaits the host's `init` message. Resolves with that payload.
+ * `connect`, then awaits the host's `init` message. Resolves after the sandbox
+ * applies the payload and returns `initResult.success`.
  *
- * Rejects with a `CustomBlockInitError` if the host doesn't respond inside `timeoutMs`.
+ * Rejects with a `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
  * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
@@ -76,61 +75,75 @@ export function initCustomBlock(
 	opts: InitCustomBlockOptions = {},
 ): Promise<CustomBlockInitPayload> {
 	if (initPromise === undefined) {
-		initPromise = (async () => {
-			// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
-			// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
-			// would just hit the same window and never arrive.
-			if (typeof window !== "undefined" && window.parent === window) {
-				throw new NotInIframeError()
-			}
+		initPromise = initializeCustomBlock(opts)
+	}
+	return initPromise
+}
 
-			// Load the manifest and send it to the host.
-			const manifestResult = await loadManifest()
-			customBlockHost.sendReady(manifestResult)
+async function initializeCustomBlock(
+	opts: InitCustomBlockOptions,
+): Promise<CustomBlockInitPayload> {
+	try {
+		// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
+		// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
+		// would just hit the same window and never arrive.
+		if (typeof window !== "undefined" && window.parent === window) {
+			throw new NotInIframeError()
+		}
 
-			const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
-			let message: InitMessage
-			try {
-				message = await customBlockHost.awaitInit(
-					AbortSignal.timeout(timeoutMs),
-				)
-			} catch (error) {
-				if (isTimeoutError(error)) {
-					throw new CustomBlockInitError({
-						code: "init_timeout",
-						message: "Host did not respond to init before the timeout.",
-						isRetryable: true,
-					})
-				}
-				throw error
-			}
-			if (message.status === "error") {
-				console.error(
-					`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`,
-				)
-				throw new CustomBlockInitError(message.error)
-			}
+		// Load the manifest and send it to the host.
+		const manifestResult = await loadManifest()
+		customBlockHost.sendConnect(manifestResult)
 
-			const hostState = customBlockHost.getState()
-			if (hostState.status !== "initialized") {
-				throw new CustomBlockInitError({
+		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
+		await awaitHostInitWithTimeout(timeoutMs)
+
+		const hostState = customBlockHost.getState()
+		switch (hostState.status) {
+			case "initialized":
+				return {
+					theme: hostState.theme,
+					blockId: hostState.blockId,
+					parent: hostState.parent,
+					page: hostState.page,
+					currentUser: hostState.currentUser,
+					dataSources: hostState.dataSources,
+				}
+			case "uninitialized":
+				throw new CustomBlockInitializationError({
 					code: "context_unavailable",
 					message: "Host block payload is unavailable.",
 					isRetryable: true,
 				})
-			}
+			default:
+				return unreachable(hostState)
+		}
+	} catch (error) {
+		if (error instanceof CustomBlockInitializationError) {
+			throw error
+		}
+		const message = error instanceof Error ? error.message : String(error)
+		throw new CustomBlockInitializationError({
+			code: "unknown_error",
+			message,
+			isRetryable: false,
+		})
+	}
+}
 
-			return {
-				theme: message.theme,
-				blockId: hostState.blockId,
-				parent: hostState.parent,
-				page: hostState.page,
-				currentUser: message.currentUser,
-				dataSources: hostState.dataSources,
-			}
-		})()
+async function awaitHostInitWithTimeout(timeoutMs: number): Promise<void> {
+	try {
+		await customBlockHost.awaitInit(AbortSignal.timeout(timeoutMs))
+	} catch (error) {
+		if (isTimeoutError(error)) {
+			throw new CustomBlockInitializationError({
+				code: "init_timeout",
+				message: "Host did not respond to init before the timeout.",
+				isRetryable: true,
+			})
+		}
+		throw error
 	}
-	return initPromise
 }
 
 function isTimeoutError(error: unknown): boolean {

package/src/react/index.ts

@@ -13,7 +13,6 @@ export {
 } from "./NotionCustomBlock.js"
 export { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
 export {
-	type CustomBlockInitFailure,
 	type UseCustomBlockInitResult,
 	useCustomBlockInit,
 } from "./useCustomBlockInit.js"

package/src/react/standalonePreview.ts

@@ -8,11 +8,13 @@ const previewPageId = v.parse(notionPageIdSchema, "")
 export function seedStandalonePreviewState() {
 	customBlockHost.setMockState({
 		type: "init",
+		initializationId: "standalone-preview",
 		status: "success",
 		theme: "light",
 		blockId: previewBlockId,
 		parent: { type: "page_id", page_id: previewPageId },
 		page: { id: previewPageId, parent: { type: "workspace", workspace: true } },
+		manifest: { version: 1, dataSources: {} },
 		dataSources: { bindings: {} },
 		currentUser: {
 			object: "user",

package/src/react/useCustomBlockInit.ts

@@ -1,27 +1,24 @@
 import { useEffect, useState } from "react"
-import { CustomBlockInitError } from "../bridge/messages/init.js"
+import type { CustomBlockInitializationError } from "../bridge/messages/init.js"
 import {
 	type CustomBlockInitPayload,
 	type InitCustomBlockOptions,
 	initCustomBlock,
-	NotInIframeError,
 } from "../init.js"
 
-export type CustomBlockInitFailure = CustomBlockInitError | NotInIframeError
-
 /**
  * Discriminated state returned by {@link useCustomBlockInit}.
  *
  * Branch on `isLoaded`/`error`:
  * - `{ isLoaded: false, error: undefined }` — handshake in progress.
- * - `{ isLoaded: false, error: CustomBlockInitFailure }` — handshake failed (most commonly a
- *   `CustomBlockInitError` with code `init_timeout` because the host never sent `init`).
+ * - `{ isLoaded: false, error: CustomBlockInitializationError }` — handshake failed (most commonly a
+ *   `CustomBlockInitializationError` with code `init_timeout` because the host never sent `init`).
  * - `{ isLoaded: true, initial }` — handshake complete; safe to render
  *   children that call `useTheme`, `useBlockId`, etc.
  */
 export type UseCustomBlockInitResult =
 	| { isLoaded: false; error: undefined }
-	| { isLoaded: false; error: CustomBlockInitFailure }
+	| { isLoaded: false; error: CustomBlockInitializationError }
 	| { isLoaded: true; error: undefined; initial: CustomBlockInitPayload }
 
 /**
@@ -56,12 +53,9 @@ export function useCustomBlockInit(
 					setState({ isLoaded: true, error: undefined, initial })
 				}
 			},
-			err => {
+			error => {
 				if (!cancelled) {
-					setState({
-						isLoaded: false,
-						error: normalizeInitError(err),
-					})
+					setState({ isLoaded: false, error })
 				}
 			},
 		)
@@ -74,18 +68,3 @@ export function useCustomBlockInit(
 	}, [])
 	return state
 }
-
-function normalizeInitError(error: unknown): CustomBlockInitFailure {
-	if (
-		error instanceof CustomBlockInitError ||
-		error instanceof NotInIframeError
-	) {
-		return error
-	}
-	const message = error instanceof Error ? error.message : String(error)
-	return new CustomBlockInitError({
-		code: "unknown_error",
-		message,
-		isRetryable: false,
-	})
-}

package/src/react/useRuntimeState.ts

@@ -72,14 +72,15 @@ export function useCurrentUser(): NotionUser {
 }
 
 /**
- * Returns the author-declared manifest loaded from `custom_blocks.json` — the semantic
+ * Returns the authoritative manifest received from the host — the semantic
  * data-source keys plus their declared `name`, `description`, and property declarations.
- * `null` when the block ships no manifest.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
  *
  * This is the configuration the block declared, not host-resolved bindings: use
  * `useDataSource(key)` for rows and resolved schema. Handy for enumerating the declared
  * data-source keys (e.g. picking a default key, or rendering a key switcher).
  */
-export function useManifest(): CustomBlockManifest | null {
+export function useManifest(): CustomBlockManifest {
 	return useSyncExternalStore(customBlock.subscribe, customBlock.getManifest)
 }

package/dist/bridge/messages/ready.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/ready.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA0B5B;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;IAG7B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BASH,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA"}