@notionhq/custom-blocks 0.0.63 → 0.0.65

package/HOST.md

@@ -49,7 +49,7 @@ Related types: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomB
 
 The bridge is established with a handshake: the sandbox posts a `ready` when `initCustomBlock()` starts, and the host validates it and replies exactly once with `init`. Hosts should log and ignore duplicate `ready` messages instead of re-running the handshake. After that, narrower messages stream live state updates.
 
-The sandbox starts by sending `ready`. It declares the bridge protocol version, includes the custom blocks package semver as `sdkVersion` when available, and tells the host whether manifest discovery produced a usable manifest. Hosts should reject init when `ready` reports a manifest error, echoing the sandbox's error code:
+The sandbox starts by sending `ready`. It declares the bridge protocol version, includes the custom blocks package semver as `sdkVersion` when available, and tells the host whether manifest discovery produced a usable manifest. Hosts should reject init when `ready` reports a manifest error, forwarding the sandbox's full error payload unchanged:
 
 ```ts
 // sandbox → host
@@ -59,7 +59,7 @@ The sandbox starts by sending `ready`. It declares the bridge protocol version,
 { type: "ready", status: "success", bridgeProtocolVersion, sdkVersion, manifest: null }
 
 // sandbox → host, manifest failed to load or validate
-{ type: "ready", status: "error", bridgeProtocolVersion, sdkVersion, error: { code: "manifest_invalid", message: "..." } }
+{ type: "ready", status: "error", bridgeProtocolVersion, sdkVersion, error: { code: "manifest_invalid", message: "...", isRetryable: false } }
 ```
 
 The host replies with exactly one `init`, which has two statuses. On success it carries the full initial state — `theme`, `blockId`, `parent`, `page`, `currentUser` (the `NotionUser` shape from the user result messages), and `dataSources: { bindings }`:
@@ -150,21 +150,21 @@ Messages sent from the sandbox to the host. Parse `window` `message` events with
 
 Messages sent from the host to the sandbox. Same `{ wire type, type / schema, behavior }` shape; the type / schema column points to the payload shape.
 
-| Wire type               | Type / schema                                                         | Behavior                                                                                                                  |
-| ----------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `init`                  | `InitMessage` / `initMessageSchema`                                   | Sent exactly once in response to `ready`; carries the success/error payload described under [Lifecycle](#lifecycle).      |
-| `themeChanged`          | `ThemeChangedMessage` / `themeChangedMessageSchema`                   | Replaces the current theme.                                                                                               |
-| `parentChanged`         | `ParentChangedMessage` / `parentChangedMessageSchema`                 | Replaces the custom block parent without disturbing theme, block ID, page ID, user, or query state.                       |
-| `pageChanged`           | `PageChangedMessage` / `pageChangedMessageSchema`                     | Replaces the nearest page ancestor without disturbing theme, block ID, parent, user, or query state.                      |
-| `currentUserChanged`    | `CurrentUserChangedMessage` / `currentUserChangedMessageSchema`       | Replaces the current viewer record. Send when any viewer field changes (name, avatar, email).                             |
-| `dataSourcesChanged`    | `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`       | Replaces data-source bindings; the sandbox preserves cached query state for keys that still exist and drops removed keys. |
+| Wire type               | Type / schema                                                         | Behavior                                                                                                                      |
+| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `init`                  | `InitMessage` / `initMessageSchema`                                   | Sent exactly once in response to `ready`; carries the success/error payload described under [Lifecycle](#lifecycle).          |
+| `themeChanged`          | `ThemeChangedMessage` / `themeChangedMessageSchema`                   | Replaces the current theme.                                                                                                   |
+| `parentChanged`         | `ParentChangedMessage` / `parentChangedMessageSchema`                 | Replaces the custom block parent without disturbing theme, block ID, page ID, user, or query state.                           |
+| `pageChanged`           | `PageChangedMessage` / `pageChangedMessageSchema`                     | Replaces the nearest page ancestor without disturbing theme, block ID, parent, user, or query state.                          |
+| `currentUserChanged`    | `CurrentUserChangedMessage` / `currentUserChangedMessageSchema`       | Replaces the current viewer record. Send when any viewer field changes (name, avatar, email).                                 |
+| `dataSourcesChanged`    | `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`       | Replaces data-source bindings; the sandbox preserves cached query state for keys that still exist and drops removed keys.     |
 | `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `requestId` / `snapshotId`-keyed response with `status: "success"`, `items`, and `hasMore`, or `status: "error"` and `error`. |
-| `createPageResult`      | `CreatePageResultMessage` / `createPageResultMessageSchema`           | `requestId`-keyed page response with `status: "success"` or `status: "error"`.                                            |
-| `getPageResult`         | `GetPageResultMessage` / `getPageResultMessageSchema`                 | Same success/error shape as `createPageResult`.                                                                           |
-| `updatePageResult`      | `UpdatePageResultMessage` / `updatePageResultMessageSchema`           | Same success/error shape as `createPageResult`.                                                                           |
-| `getUserResult`         | `GetUserResultMessage` / `getUserResultMessageSchema`                 | `requestId`-keyed user response with `status: "success"` or `status: "error"`.                                            |
-| `listUsersResult`       | `ListUsersResultMessage` / `listUsersResultMessageSchema`             | Same success/error shape as `getUserResult`.                                                                              |
-| `invalidSandboxMessage` | `InvalidSandboxMessage` / `invalidSandboxMessageSchema`               | Host-side NACK for a sandbox message it could not parse.                                                                  |
+| `createPageResult`      | `CreatePageResultMessage` / `createPageResultMessageSchema`           | `requestId`-keyed page response with `status: "success"` or `status: "error"`.                                                |
+| `getPageResult`         | `GetPageResultMessage` / `getPageResultMessageSchema`                 | Same success/error shape as `createPageResult`.                                                                               |
+| `updatePageResult`      | `UpdatePageResultMessage` / `updatePageResultMessageSchema`           | Same success/error shape as `createPageResult`.                                                                               |
+| `getUserResult`         | `GetUserResultMessage` / `getUserResultMessageSchema`                 | `requestId`-keyed user response with `status: "success"` or `status: "error"`.                                                |
+| `listUsersResult`       | `ListUsersResultMessage` / `listUsersResultMessageSchema`             | Same success/error shape as `getUserResult`.                                                                                  |
+| `invalidSandboxMessage` | `InvalidSandboxMessage` / `invalidSandboxMessageSchema`               | Host-side NACK for a sandbox message it could not parse.                                                                      |
 
 `HostToSandboxMessage` / `hostToSandboxMessageSchema` is the discriminated union over all of the above.
 

package/README.md

@@ -3,9 +3,9 @@
 > [!NOTE]
 > Nothing to see here. This is **extreme** alpha and currently only works for an unreleased product.
 
-SDK for building Notion custom view blocks.
+SDK for building Notion custom blocks.
 
-A custom view runs as a sandboxed `<iframe>` inside a Notion block on iOS, Android, and desktop. The only channel between your view and Notion is a `postMessage` bridge — this SDK wraps it in typed React hooks plus a small framework-neutral runtime API for non-React renderers.
+A custom block runs as a sandboxed `<iframe>` inside a Notion block on iOS, Android, and desktop. The only channel between your block and Notion is a `postMessage` bridge — this SDK wraps it in typed React hooks plus a small framework-neutral runtime API for non-React renderers.
 
 > **Pre-release.** Breaking changes may land at any time before 1.0.
 

package/bin/cli/create.js

@@ -69,7 +69,7 @@ function createCustomBlock(pageId) {
  *
  * - No `--parent`  → create a private page, then a block under it.
  * - Page `--parent` → create a block under that page.
- * - Database/data source `--parent` → a custom *view* under a collection. The
+ * - Database/data source `--parent` → a custom block as a collection view. The
  *   public API has no `custom` view type and the parent-nesting the backend
  *   uses isn't derivable from this repo, so we error rather than guess.
  */
@@ -82,8 +82,8 @@ export function create(options) {
         const parentUuid = formatUuid(extractId(options.parent));
         const kind = classifyParent(parentUuid);
         if (kind === "database" || kind === "data_source") {
-            console.error(`Error: --parent ${parentUuid} is a ${kind.replace("_", " ")}. Creating a custom view under a collection isn't supported yet.\n`);
-            console.error("  The public API has no `custom` view type; the backend does the parent nesting. Create the view in Notion, then run `ncblock attach <block-id-or-url>`.");
+            console.error(`Error: --parent ${parentUuid} is a ${kind.replace("_", " ")}. Creating a custom block as a collection view isn't supported yet.\n`);
+            console.error("  The public API has no `custom` view type; the backend does the parent nesting. Create the custom block in Notion, then run `ncblock attach <block-id-or-url>`.");
             process.exit(1);
         }
         pageId = parentUuid;

package/dist/bridge/SandboxBridge.js

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { unreachable } from "../utils.js";
-import { NCBLOCK_SDK_VERSION } from "../version.js";
+import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js";
 import { resolveDataSources } from "./dataSources/resolve.js";
 import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty.js";
 import { createEmptyDataSourceQueryState, } from "./hostState.js";
@@ -43,7 +43,7 @@ export class SandboxBridge {
             }
         };
         this.handleMessage = (event) => {
-            console.debug("[notion-custom-sdk] incoming postMessage", {
+            console.debug("[custom-blocks-sdk] incoming postMessage", {
                 data: event.data,
                 fromParent: event.source === window.parent,
             });
@@ -53,7 +53,7 @@ export class SandboxBridge {
             this.logMessage("received", event.data);
             const parsed = v.safeParse(hostToSandboxMessageSchema, event.data);
             if (!parsed.success) {
-                console.warn("[notion-custom-sdk] ignoring malformed host message", parsed.issues);
+                console.warn("[custom-blocks-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
@@ -75,7 +75,7 @@ export class SandboxBridge {
             // 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);
+                console.warn("[custom-blocks-sdk] host reported invalid sandbox message:", message.reason);
                 return;
             }
             // `init` is the only message valid before initialization. Handle it up
@@ -88,7 +88,7 @@ export class SandboxBridge {
             // 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`);
+                console.warn(`[custom-blocks-sdk] ignoring ${message.type} before init`);
                 return;
             }
             switch (message.type) {
@@ -157,7 +157,7 @@ export class SandboxBridge {
                         ? { status: "success", page: message.page }
                         : { status: "error", error: message.error };
                     if (!this.pendingCreatePage.resolve(message.requestId, result)) {
-                        console.warn(`[notion-custom-sdk] createPageResult for unknown requestId ${message.requestId}`);
+                        console.warn(`[custom-blocks-sdk] createPageResult for unknown requestId ${message.requestId}`);
                     }
                     return;
                 }
@@ -166,7 +166,7 @@ export class SandboxBridge {
                         ? { status: "success", page: message.page }
                         : { status: "error", error: message.error };
                     if (!this.pendingGetPage.resolve(message.requestId, result)) {
-                        console.warn(`[notion-custom-sdk] getPageResult for unknown requestId ${message.requestId}`);
+                        console.warn(`[custom-blocks-sdk] getPageResult for unknown requestId ${message.requestId}`);
                     }
                     return;
                 }
@@ -175,7 +175,7 @@ export class SandboxBridge {
                         ? { status: "success", user: message.user }
                         : { status: "error", error: message.error };
                     if (!this.pendingGetUser.resolve(message.requestId, result)) {
-                        console.warn(`[notion-custom-sdk] getUserResult for unknown requestId ${message.requestId}`);
+                        console.warn(`[custom-blocks-sdk] getUserResult for unknown requestId ${message.requestId}`);
                     }
                     return;
                 }
@@ -184,7 +184,7 @@ export class SandboxBridge {
                         ? { 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}`);
+                        console.warn(`[custom-blocks-sdk] listUsersResult for unknown requestId ${message.requestId}`);
                     }
                     return;
                 }
@@ -193,7 +193,7 @@ export class SandboxBridge {
                         ? { status: "success", page: message.page }
                         : { status: "error", error: message.error };
                     if (!this.pendingUpdatePage.resolve(message.requestId, result)) {
-                        console.warn(`[notion-custom-sdk] updatePageResult for unknown requestId ${message.requestId}`);
+                        console.warn(`[custom-blocks-sdk] updatePageResult for unknown requestId ${message.requestId}`);
                     }
                     return;
                 }
@@ -300,7 +300,7 @@ export class SandboxBridge {
             return;
         }
         if (this.hasSentReady) {
-            console.warn("[notion-custom-sdk] ignoring duplicate ready message");
+            console.warn("[custom-blocks-sdk] ignoring duplicate ready message");
             return;
         }
         const { manifest, error } = manifestResult;
@@ -311,20 +311,20 @@ export class SandboxBridge {
                 type: "ready",
                 status: "error",
                 bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
-                sdkVersion: NCBLOCK_SDK_VERSION,
+                sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
                 error,
             }
             : {
                 type: "ready",
                 status: "success",
                 bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
-                sdkVersion: NCBLOCK_SDK_VERSION,
+                sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
                 manifest,
             };
         this.postToHost(readyMessage);
     }
     postToHost(message) {
-        console.debug("[notion-custom-sdk] outbound postMessage", message);
+        console.debug("[custom-blocks-sdk] outbound postMessage", message);
         this.logMessage("sent", message);
         window.parent.postMessage(message, "*");
     }
@@ -361,7 +361,7 @@ export class SandboxBridge {
             // because not every consumer renders the error UI, and we want the failure visible in
             // the browser console either way. We deliberately don't NACK the host or post anything
             // back over the bridge since the host has already given up.
-            console.error(`[notion-custom-sdk] host reported init error (${message.error.code}): ${message.error.message}`);
+            console.error(`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`);
             if (this.rejectInit) {
                 this.rejectInit(new CustomBlockInitError(message.error));
                 this.resolveInit = undefined;
@@ -705,11 +705,11 @@ function resolveDataSourceQueryLimit(limit) {
         return DEFAULT_DATA_SOURCE_QUERY_LIMIT;
     }
     if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1) {
-        console.warn(`[notion-custom-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`);
+        console.warn(`[custom-blocks-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`);
         return DEFAULT_DATA_SOURCE_QUERY_LIMIT;
     }
     if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
-        console.warn(`[notion-custom-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`);
+        console.warn(`[custom-blocks-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`);
         return MAX_DATA_SOURCE_QUERY_LIMIT;
     }
     return limit;

package/dist/bridge/loadManifest.d.ts

@@ -1,12 +1,7 @@
-import * as v from "valibot";
+import type { CustomBlockErrorInfo } from "./errors.js";
 import { type CustomBlockManifest } from "./manifest.js";
-export declare const customBlockReadyErrorCodeSchema: v.StringSchema<undefined>;
 export type CustomBlockReadyErrorCode = "manifest_unavailable" | "manifest_invalid" | (string & {});
-export declare const customBlockReadyErrorSchema: v.ObjectSchema<{
-    readonly code: v.StringSchema<undefined>;
-    readonly message: v.StringSchema<undefined>;
-}, undefined>;
-export type CustomBlockReadyError = v.InferOutput<typeof customBlockReadyErrorSchema>;
+export type CustomBlockReadyError = CustomBlockErrorInfo<CustomBlockReadyErrorCode>;
 export type ManifestLoadResult = {
     manifest: CustomBlockManifest | null;
     error?: undefined;

package/dist/bridge/loadManifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,eAAe,CAAA;AAMxE,eAAO,MAAM,+BAA+B,2BAAa,CAAA;AAEzD,MAAM,MAAM,yBAAyB,GAClC,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,eAAO,MAAM,2BAA2B;;;aAGtC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAChD,OAAO,2BAA2B,CAClC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,qBAAqB,CAAA;CAC3B,CAAA;AAEJ;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAgDhE"}
+{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,eAAe,CAAA;AAIxE,MAAM,MAAM,yBAAyB,GAClC,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,qBAAqB,GAChC,oBAAoB,CAAC,yBAAyB,CAAC,CAAA;AAEhD,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,qBAAqB,CAAA;CAC3B,CAAA;AAEJ;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAkEhE"}

package/dist/bridge/loadManifest.js

@@ -1,13 +1,6 @@
 import * as v from "valibot";
 import { manifestSchema } from "./manifest.js";
 const MANIFEST_URL = "custom_blocks.json";
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockReadyErrorCodeSchema = v.string();
-export const customBlockReadyErrorSchema = v.object({
-    code: customBlockReadyErrorCodeSchema,
-    message: v.string(),
-});
 /**
  * Attempts to load a `custom_blocks.json` manifest co-located with the bundle.
  * A missing manifest means the block has no declared data requirements.
@@ -18,10 +11,10 @@ export const customBlockReadyErrorSchema = v.object({
 export async function loadManifest() {
     if (typeof fetch !== "function") {
         const message = `No fetch API available; cannot load ${MANIFEST_URL}.`;
-        console.warn(`[notion-custom-sdk] ${message}`);
+        console.warn(`[custom-blocks-sdk] ${message}`);
         return {
             manifest: null,
-            error: { code: "manifest_unavailable", message },
+            error: { code: "manifest_unavailable", message, isRetryable: true },
         };
     }
     let response;
@@ -30,23 +23,30 @@ export async function loadManifest() {
     }
     catch (error) {
         const message = `Could not fetch ${MANIFEST_URL}.`;
-        console.warn(`[notion-custom-sdk] ${message}`, error);
+        console.warn(`[custom-blocks-sdk] ${message}`, error);
         return {
             manifest: null,
-            error: { code: "manifest_unavailable", message },
+            // Consider this retryable because it may have just been a network issue. Because `init`
+            // errors are considered terminal, the host should "retry" by reloading the iframe and
+            // sending another `ready` message.
+            error: { code: "manifest_unavailable", message, isRetryable: true },
         };
     }
     if (response.status === 404) {
         const message = `No manifest found at ${MANIFEST_URL} (status ${response.status}).`;
-        console.warn(`[notion-custom-sdk] ${message}`);
+        console.warn(`[custom-blocks-sdk] ${message}`);
         return { manifest: null };
     }
     if (!response.ok) {
         const message = `Could not fetch ${MANIFEST_URL} (status ${response.status}).`;
-        console.warn(`[notion-custom-sdk] ${message}`);
+        console.warn(`[custom-blocks-sdk] ${message}`);
         return {
             manifest: null,
-            error: { code: "manifest_unavailable", message },
+            error: {
+                code: "manifest_unavailable",
+                message,
+                isRetryable: isRetryableManifestHttpStatus(response.status),
+            },
         };
     }
     let json;
@@ -55,14 +55,32 @@ export async function loadManifest() {
     }
     catch (error) {
         const message = `Manifest at ${MANIFEST_URL} was not valid JSON.`;
-        console.warn(`[notion-custom-sdk] ${message}`, error);
-        return { manifest: null, error: { code: "manifest_invalid", message } };
+        console.warn(`[custom-blocks-sdk] ${message}`, error);
+        return {
+            manifest: null,
+            // Consider invalid manifests as unrecoverable errors.
+            error: { code: "manifest_invalid", message, isRetryable: false },
+        };
     }
     const parsed = v.safeParse(manifestSchema, json);
     if (!parsed.success) {
         const message = `Manifest at ${MANIFEST_URL} did not match schema.`;
-        console.warn(`[notion-custom-sdk] ${message}`, parsed.issues);
-        return { manifest: null, error: { code: "manifest_invalid", message } };
+        console.warn(`[custom-blocks-sdk] ${message}`, parsed.issues);
+        return {
+            manifest: null,
+            // Consider invalid manifests as unrecoverable errors.
+            error: { code: "manifest_invalid", message, isRetryable: false },
+        };
     }
     return { manifest: parsed.output };
 }
+function isRetryableManifestHttpStatus(status) {
+    // Consider these statuses retryable because they may reflect transient failures.
+    return (status === 408 || // Request Timeout
+        status === 425 || // Too Early
+        status === 500 || // Internal Server Error
+        status === 502 || // Bad Gateway
+        status === 503 || // Service Unavailable
+        status === 504 // Gateway Timeout
+    );
+}

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

@@ -39,6 +39,7 @@ export declare const readyMessageSchema: v.UnionSchema<[v.ObjectSchema<{
     readonly error: v.ObjectSchema<{
         readonly code: v.StringSchema<undefined>;
         readonly message: v.StringSchema<undefined>;
+        readonly isRetryable: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     }, undefined>;
 }, undefined>], undefined>;
 export type ReadyMessage = v.InferOutput<typeof readyMessageSchema>;

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

@@ -1 +1 @@
-{"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;AAmB5B;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;IAG7B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BASH,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA"}
+{"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"}

package/dist/bridge/messages/ready.js

@@ -1,5 +1,4 @@
 import * as v from "valibot";
-import { customBlockReadyErrorSchema } from "../loadManifest.js";
 import { manifestSchema } from "../manifest.js";
 const readyMessageCommonEntries = {
     type: v.literal("ready"),
@@ -15,6 +14,13 @@ const readyMessageCommonEntries = {
      */
     sdkVersion: v.string(),
 };
+// TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
+// once min supported bridge protocol version is bumped to 3.
+const readyErrorSchema = v.object({
+    code: v.string(),
+    message: v.string(),
+    isRetryable: v.optional(v.boolean(), false),
+});
 /**
  * First message the sandbox sends after mount, kicking off the bridge handshake. The host replies
  * with `init`.
@@ -31,7 +37,7 @@ export const readyMessageSchema = v.union([
     }),
     v.object({
         status: v.literal("error"),
-        error: customBlockReadyErrorSchema,
+        error: readyErrorSchema,
         ...readyMessageCommonEntries,
     }),
 ]);

package/dist/bridge/messages/sandboxToHost.d.ts

@@ -35,6 +35,7 @@ export declare const sandboxToHostMessageSchema: v.UnionSchema<[v.UnionSchema<[v
     readonly error: v.ObjectSchema<{
         readonly code: v.StringSchema<undefined>;
         readonly message: v.StringSchema<undefined>;
+        readonly isRetryable: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     }, undefined>;
 }, undefined>], undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"queryDataSource", undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"sandboxToHost.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/sandboxToHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAW5B;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAUrC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}
+{"version":3,"file":"sandboxToHost.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/sandboxToHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAW5B;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAUrC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}

package/dist/host/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/createCustomBlockHost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAY1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAkB/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAE3B,mBAAmB,EACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA;AAE9E,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAChD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,kBAAkB,CAAA;QAChC,QAAQ,EAAE,oCAAoC,CAAA;KAC9C,KAAK,IAAI,CAAA;CACV,CAAA;AAKD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAuTvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/createCustomBlockHost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAY1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAkB/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAE3B,mBAAmB,EACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA;AAE9E,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAChD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,kBAAkB,CAAA;QAChC,QAAQ,EAAE,oCAAoC,CAAA;KAC9C,KAAK,IAAI,CAAA;CACV,CAAA;AAKD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAuUvB"}

package/dist/host/createCustomBlockHost.js

@@ -2,7 +2,7 @@ import * as v from "valibot";
 import { sandboxToHostMessageSchema } from "../bridge/messages/sandboxToHost.js";
 import { unreachable } from "../utils.js";
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js";
-import { getReadyInitFailure } from "./lifecycle/ready.js";
+import { isValidBridgeProtocolVersion } from "./lifecycle/ready.js";
 import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js";
 import { QuerySubscriptions } from "./queries/querySubscriptions.js";
 const DEFAULT_NO_READY_TIMEOUT_MS = 5000;
@@ -65,26 +65,23 @@ export function createCustomBlockHost(options) {
         post(message);
         return true;
     }
-    function sendInitError(code, message) {
+    function sendInitError(error) {
         if (initStatus !== "pending") {
             return;
         }
         initStatus = "error";
         clearNoReadyTimeout();
-        const error = initErrorForFailureReason(code);
         post({
             type: "init",
             status: "error",
-            error: {
-                ...error,
-                message: message ?? error.message,
-            },
+            error,
         });
     }
     function onIframeLoad() {
         clearNoReadyTimeout();
         noReadyTimeoutId = window.setTimeout(() => {
-            sendInitError("no_ready");
+            const initError = initErrorForFailureReason("no_ready");
+            sendInitError(initError);
         }, noReadyTimeoutMs);
     }
     async function handleQuery(message) {
@@ -157,12 +154,25 @@ export function createCustomBlockHost(options) {
         post(result);
     }
     function handleReady(message) {
-        const failure = getReadyInitFailure(message, minBridgeProtocolVersion);
-        if (failure !== undefined) {
-            sendInitError(failure.code, failure.message);
+        // Verify the bridge protocol version is valid.
+        if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
+            const initError = initErrorForFailureReason("invalid_protocol_version", {
+                currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+            });
+            sendInitError(initError);
+            return;
+        }
+        if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+            const initError = initErrorForFailureReason("unsupported_protocol_version", {
+                currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+                minBridgeProtocolVersion,
+            });
+            sendInitError(initError);
             return;
         }
-        if (message.status !== "success") {
+        // If the sandbox reported an error during `ready`, return it as an `init` error.
+        if (message.status === "error") {
+            sendInitError(message.error);
             return;
         }
         if (sendInit(message)) {
@@ -177,7 +187,8 @@ export function createCustomBlockHost(options) {
         });
         const response = getInvalidSandboxMessageResponse(data);
         if (initStatus === "pending" && response.incomingType === "ready") {
-            sendInitError("invalid_ready");
+            const initError = initErrorForFailureReason("invalid_ready");
+            sendInitError(initError);
         }
         else if (response.nack !== undefined) {
             post(response.nack);

package/dist/host/lifecycle/initErrors.d.ts

@@ -6,5 +6,8 @@ import type { CustomBlockInitErrorCode, CustomBlockInitErrorInfo } from "../../b
  * `ready` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
  * without changing block code or host configuration.
  */
-export declare function initErrorForFailureReason(reason: CustomBlockInitErrorCode): CustomBlockInitErrorInfo;
+export declare function initErrorForFailureReason(reason: CustomBlockInitErrorCode, data?: {
+    minBridgeProtocolVersion?: number;
+    currentBridgeProtocolVersion?: number;
+}): CustomBlockInitErrorInfo;
 //# sourceMappingURL=initErrors.d.ts.map

package/dist/host/lifecycle/initErrors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,+BAA+B,CAAA;AAKtC;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,wBAAwB,GAC9B,wBAAwB,CAkH1B"}
+{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,+BAA+B,CAAA;AAKtC;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,wBAAwB,EAChC,IAAI,GAAE;IACL,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAA;CAChC,GACJ,wBAAwB,CA6H1B"}

package/dist/host/lifecycle/initErrors.js

@@ -6,7 +6,7 @@ const UNKNOWN_ERROR_MESSAGE = "Unexpected error while initializing custom block.
  * `ready` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
  * without changing block code or host configuration.
  */
-export function initErrorForFailureReason(reason) {
+export function initErrorForFailureReason(reason, data = {}) {
     switch (reason) {
         case "no_ready":
             return {
@@ -34,20 +34,31 @@ export function initErrorForFailureReason(reason) {
                 // The sandbox must be updated to a valid manifest.
                 isRetryable: false,
             };
-        case "invalid_protocol_version":
+        case "invalid_protocol_version": {
+            const versionText = data.currentBridgeProtocolVersion
+                ? `: ${data.currentBridgeProtocolVersion}`
+                : ".";
             return {
                 code: reason,
-                message: "Sandbox reported an invalid bridge protocol version.",
+                message: `Sandbox reported an invalid bridge protocol version ${versionText}`,
                 // The sandbox must be updated to a supported protocol version.
                 isRetryable: false,
             };
-        case "unsupported_protocol_version":
+        }
+        case "unsupported_protocol_version": {
+            const currentVersionText = data.currentBridgeProtocolVersion
+                ? `${data.currentBridgeProtocolVersion} `
+                : "";
+            const minVersionText = data.minBridgeProtocolVersion
+                ? ` Minimum supported version is ${data.minBridgeProtocolVersion}.`
+                : "";
             return {
                 code: reason,
-                message: "Sandbox bridge protocol version is not supported.",
+                message: `Sandbox bridge protocol version ${currentVersionText}is not supported.${minVersionText}`,
                 // The sandbox must be updated to a supported protocol version.
                 isRetryable: false,
             };
+        }
         case "context_unavailable":
             return {
                 code: reason,

package/dist/host/lifecycle/ready.d.ts

@@ -1,8 +1,2 @@
-import type { CustomBlockInitErrorCode } from "../../bridge/messages/init.js";
-import type { ReadyMessage } from "../../bridge/messages/ready.js";
-export type ReadyInitFailure = {
-    code: CustomBlockInitErrorCode;
-    message?: string;
-};
-export declare function getReadyInitFailure(message: ReadyMessage, minBridgeProtocolVersion: number): ReadyInitFailure | undefined;
+export declare function isValidBridgeProtocolVersion(version: number): boolean;
 //# sourceMappingURL=ready.d.ts.map

package/dist/host/lifecycle/ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/ready.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAElE,MAAM,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,wBAAwB,CAAA;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,YAAY,EACrB,wBAAwB,EAAE,MAAM,GAC9B,gBAAgB,GAAG,SAAS,CAoB9B"}
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/ready.ts"],"names":[],"mappings":"AAAA,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/host/lifecycle/ready.js

@@ -1,24 +1,3 @@
-export function getReadyInitFailure(message, minBridgeProtocolVersion) {
-    if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
-        return {
-            code: "invalid_protocol_version",
-            message: `Sandbox reported invalid bridge protocol version ${message.bridgeProtocolVersion}.`,
-        };
-    }
-    if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
-        return {
-            code: "unsupported_protocol_version",
-            message: `Sandbox bridge protocol version ${message.bridgeProtocolVersion} is below the host minimum ${minBridgeProtocolVersion}.`,
-        };
-    }
-    if (message.status === "error") {
-        return {
-            code: message.error.code,
-            message: message.error.message,
-        };
-    }
-    return undefined;
-}
-function isValidBridgeProtocolVersion(version) {
+export function isValidBridgeProtocolVersion(version) {
     return Number.isFinite(version) && Number.isInteger(version) && version >= 1;
 }

package/dist/init.js

@@ -56,7 +56,7 @@ export function initCustomBlock(opts = {}) {
                 throw error;
             }
             if (message.status === "error") {
-                console.error(`[notion-custom-sdk] host reported init error (${message.error.code}): ${message.error.message}`);
+                console.error(`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`);
                 throw new CustomBlockInitError(message.error);
             }
             const hostState = customBlockHost.getState();