@notionhq/custom-blocks 0.0.64 → 0.0.66

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/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.
@@ -21,7 +14,7 @@ export async function loadManifest() {
         console.warn(`[custom-blocks-sdk] ${message}`);
         return {
             manifest: null,
-            error: { code: "manifest_unavailable", message },
+            error: { code: "manifest_unavailable", message, isRetryable: true },
         };
     }
     let response;
@@ -33,7 +26,10 @@ export async function loadManifest() {
         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) {
@@ -46,7 +42,11 @@ export async function loadManifest() {
         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;
@@ -56,13 +56,31 @@ export async function loadManifest() {
     catch (error) {
         const message = `Manifest at ${MANIFEST_URL} was not valid JSON.`;
         console.warn(`[custom-blocks-sdk] ${message}`, error);
-        return { manifest: null, error: { code: "manifest_invalid", message } };
+        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(`[custom-blocks-sdk] ${message}`, parsed.issues);
-        return { manifest: null, error: { code: "manifest_invalid", message } };
+        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/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.0.64"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.0.66"

package/docs/manifest.md

@@ -18,7 +18,7 @@ A custom block declares its required data sources in `custom_blocks.json` at the
 }
 ```
 
-`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.
+`initCustomBlock()` fetches the manifest 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. Hosts should reject `init` by forwarding that full error payload unchanged.
 
 ## Vite plugin
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.0.64",
+	"version": "0.0.66",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/loadManifest.ts

@@ -1,25 +1,16 @@
 import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "./errors.js"
 import { type CustomBlockManifest, 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 type CustomBlockReadyErrorCode =
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| (string & {})
 
-export const customBlockReadyErrorSchema = v.object({
-	code: customBlockReadyErrorCodeSchema,
-	message: v.string(),
-})
-
-export type CustomBlockReadyError = v.InferOutput<
-	typeof customBlockReadyErrorSchema
->
+export type CustomBlockReadyError =
+	CustomBlockErrorInfo<CustomBlockReadyErrorCode>
 
 export type ManifestLoadResult =
 	| {
@@ -44,7 +35,7 @@ export async function loadManifest(): Promise<ManifestLoadResult> {
 		console.warn(`[custom-blocks-sdk] ${message}`)
 		return {
 			manifest: null,
-			error: { code: "manifest_unavailable", message },
+			error: { code: "manifest_unavailable", message, isRetryable: true },
 		}
 	}
 	let response: Response
@@ -55,7 +46,10 @@ export async function loadManifest(): Promise<ManifestLoadResult> {
 		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) {
@@ -68,22 +62,49 @@ export async function loadManifest(): Promise<ManifestLoadResult> {
 		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: unknown
 	try {
 		json = await response.json()
 	} catch (error) {
 		const message = `Manifest at ${MANIFEST_URL} was not valid JSON.`
 		console.warn(`[custom-blocks-sdk] ${message}`, error)
-		return { manifest: null, error: { code: "manifest_invalid", message } }
+		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(`[custom-blocks-sdk] ${message}`, parsed.issues)
-		return { manifest: null, error: { code: "manifest_invalid", message } }
+		return {
+			manifest: null,
+			// Consider invalid manifests as unrecoverable errors.
+			error: { code: "manifest_invalid", message, isRetryable: false },
+		}
 	}
+
 	return { manifest: parsed.output }
 }
+
+function isRetryableManifestHttpStatus(status: number): boolean {
+	// 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/src/bridge/messages/ready.ts

@@ -1,5 +1,4 @@
 import * as v from "valibot"
-import { customBlockReadyErrorSchema } from "../loadManifest.js"
 import { manifestSchema } from "../manifest.js"
 
 const readyMessageCommonEntries = {
@@ -17,6 +16,14 @@ 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`.
@@ -33,7 +40,7 @@ export const readyMessageSchema = v.union([
 	}),
 	v.object({
 		status: v.literal("error"),
-		error: customBlockReadyErrorSchema,
+		error: readyErrorSchema,
 		...readyMessageCommonEntries,
 	}),
 ])

package/src/host/createCustomBlockHost.ts

@@ -13,7 +13,7 @@ import type {
 } from "../bridge/messages/getUser.js"
 import type { HostToSandboxMessage } from "../bridge/messages/hostToSandbox.js"
 import type {
-	CustomBlockInitErrorCode,
+	CustomBlockInitErrorInfo,
 	InitMessage,
 } from "../bridge/messages/init.js"
 import type {
@@ -35,7 +35,7 @@ import type { NotionTheme } from "../bridge/theme.js"
 import type { NotionUser } from "../bridge/users/user.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 type {
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
@@ -161,27 +161,24 @@ export function createCustomBlockHost(
 		return true
 	}
 
-	function sendInitError(code: CustomBlockInitErrorCode, message?: string) {
+	function sendInitError(error: CustomBlockInitErrorInfo) {
 		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)
 	}
 
@@ -261,14 +258,32 @@ export function createCustomBlockHost(
 	}
 
 	function handleReady(message: ReadyMessage) {
-		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.status !== "success") {
+		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+			const initError = initErrorForFailureReason(
+				"unsupported_protocol_version",
+				{
+					currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+					minBridgeProtocolVersion,
+				},
+			)
+			sendInitError(initError)
 			return
 		}
+
+		// 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)) {
 			onReady?.(message)
 		}
@@ -286,7 +301,8 @@ export function createCustomBlockHost(
 		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/src/host/lifecycle/initErrors.ts

@@ -15,6 +15,10 @@ const UNKNOWN_ERROR_MESSAGE =
  */
 export function initErrorForFailureReason(
 	reason: CustomBlockInitErrorCode,
+	data: {
+		minBridgeProtocolVersion?: number
+		currentBridgeProtocolVersion?: number
+	} = {},
 ): CustomBlockInitErrorInfo {
 	switch (reason) {
 		case "no_ready":
@@ -43,20 +47,31 @@ export function initErrorForFailureReason(
 				// 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/src/host/lifecycle/ready.ts

@@ -1,36 +1,3 @@
-import type { CustomBlockInitErrorCode } from "../../bridge/messages/init.js"
-import type { ReadyMessage } from "../../bridge/messages/ready.js"
-
-export type ReadyInitFailure = {
-	code: CustomBlockInitErrorCode
-	message?: string
-}
-
-export function getReadyInitFailure(
-	message: ReadyMessage,
-	minBridgeProtocolVersion: number,
-): ReadyInitFailure | undefined {
-	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: number): boolean {
+export function isValidBridgeProtocolVersion(version: number): boolean {
 	return Number.isFinite(version) && Number.isInteger(version) && version >= 1
 }