@notionhq/custom-blocks 0.0.65 → 0.0.67

package/HOST.md

@@ -104,6 +104,8 @@ Every bridge error payload uses the same `{ code, message, isRetryable }` shape.
 
 `code` is any string on the wire. Schemas validate only the error _shape_ (`code`/`message`/`isRetryable` types); per-API code unions are TypeScript open-enums for autocomplete. Receivers MUST accept well-shaped errors with unknown codes so newer senders can add codes without breaking older receivers.
 
+Hosts should emit the most specific stable code available. Unexpected or unclassified request failures use the universal `unknown_error` code with `isRetryable: false`. Future hosts and sandboxes may introduce a new error code, so both sides should accept any string, even if it does not match a known code.
+
 Host implementers can use the API-specific aliases and schemas when shaping outbound failures: `CustomBlockCreatePageErrorCode` / `CustomBlockCreatePageErrorInfo` / `customBlockCreatePageErrorCodeSchema` / `customBlockCreatePageErrorInfoSchema`, `CustomBlockGetPageErrorCode` / `CustomBlockGetPageErrorInfo` / `customBlockGetPageErrorCodeSchema` / `customBlockGetPageErrorInfoSchema`, `CustomBlockGetUserErrorCode` / `CustomBlockGetUserErrorInfo` / `customBlockGetUserErrorCodeSchema` / `customBlockGetUserErrorInfoSchema`, `CustomBlockListUsersErrorCode` / `CustomBlockListUsersErrorInfo` / `customBlockListUsersErrorCodeSchema` / `customBlockListUsersErrorInfoSchema`, `CustomBlockQueryDataSourceErrorCode` / `CustomBlockQueryDataSourceErrorInfo` / `customBlockQueryDataSourceErrorCodeSchema` / `customBlockQueryDataSourceErrorInfoSchema`, and `CustomBlockUpdatePageErrorCode` / `CustomBlockUpdatePageErrorInfo` / `customBlockUpdatePageErrorCodeSchema` / `customBlockUpdatePageErrorInfoSchema`. Shared categories are exported as `CustomBlockPropertyErrorCode` / `CustomBlockPropertyErrorInfo` / `customBlockPropertyErrorCodeSchema` and `CustomBlockDataSourceResolutionErrorCode` / `CustomBlockDataSourceResolutionErrorInfo` / `customBlockDataSourceResolutionErrorCodeSchema`. The broad fallback schema remains `customBlockErrorInfoSchema`.
 
 `queryDataSource` carries the resolved raw `dataSourceId` and a sandbox-generated `snapshotId`; semantic data-source keys never cross the bridge for queries. `createPage` arrives with `parent` already resolved to `page_id` or `data_source_id`.

package/README.md

@@ -46,6 +46,7 @@ API surface, one page per category. Import framework-neutral APIs from `@notionh
 - [`docs/data-sources.md`](./docs/data-sources.md) — `useDataSource`, `useManifest`, `customBlock.getManifest`, the row, property, and date-value types, plus a worked example.
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.
+- [`docs/errors.md`](./docs/errors.md) — request results, error format, error codes, retries, and initialization failures.
 - [`docs/manifest.md`](./docs/manifest.md) — `custom_blocks.json`, the Vite plugin, manifest types.
 
 ## Forbidden APIs

package/dist/bridge/errors.d.ts

@@ -1,4 +1,5 @@
 import * as v from "valibot";
+export type CustomBlockErrorCode<KnownCode extends string> = KnownCode | "unknown_error" | (string & {});
 export type CustomBlockErrorInfo<TCode extends string = string> = {
     code: TCode;
     message: string;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACjE,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,0BAA0B;;;;aAIrC,CAAA"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,oBAAoB,CAAC,SAAS,SAAS,MAAM,IAEtD,SAAS,GAET,eAAe,GAEf,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI;IACjE,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,0BAA0B;;;;aAIrC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockCreatePageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockCreatePageErrorCode = "create_page_failed" | "invalid_page_parent" | "page_access_failed" | "collection_access_failed" | "unknown_data_source_key" | "unmapped_data_source" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value" | (string & {});
+export type CustomBlockCreatePageErrorCode = CustomBlockErrorCode<"create_page_failed" | "invalid_page_parent" | "page_access_failed" | "collection_access_failed" | "unknown_data_source_key" | "unmapped_data_source" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value">;
 export type CustomBlockCreatePageErrorInfo = CustomBlockErrorInfo<CustomBlockCreatePageErrorCode>;
 export declare const customBlockCreatePageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"createPageResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/createPageResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAKxD,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GACvC,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,GACtB,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,GACxB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;IAKxC,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAS9B,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAClD,OAAO,6BAA6B,CACpC,CAAA"}
+{"version":3,"file":"createPageResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/createPageResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAK9E,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAC9D,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,GACtB,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,CAC1B,CAAA;AAED,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;IAKxC,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAS9B,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAClD,OAAO,6BAA6B,CACpC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockGetPageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockGetPageErrorCode = "get_page_failed" | "page_access_failed" | (string & {});
+export type CustomBlockGetPageErrorCode = CustomBlockErrorCode<"get_page_failed" | "page_access_failed">;
 export type CustomBlockGetPageErrorInfo = CustomBlockErrorInfo<CustomBlockGetPageErrorCode>;
 export declare const customBlockGetPageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"getPage.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/getPage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAMxD,eAAO,MAAM,iCAAiC,2BAAa,CAAA;AAE3D,MAAM,MAAM,2BAA2B,GACpC,iBAAiB,GACjB,oBAAoB,GACpB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,2BAA2B,GACtC,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAElD,eAAO,MAAM,iCAAiC;;;;aAI5C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;aAI/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAarC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}
+{"version":3,"file":"getPage.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/getPage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAM9E,eAAO,MAAM,iCAAiC,2BAAa,CAAA;AAE3D,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,CAC7D,iBAAiB,GAAG,oBAAoB,CACxC,CAAA;AAED,MAAM,MAAM,2BAA2B,GACtC,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAElD,eAAO,MAAM,iCAAiC;;;;aAI5C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;aAI/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAarC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockGetUserErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockGetUserErrorCode = "get_user_failed" | (string & {});
+export type CustomBlockGetUserErrorCode = CustomBlockErrorCode<"get_user_failed">;
 export type CustomBlockGetUserErrorInfo = CustomBlockErrorInfo<CustomBlockGetUserErrorCode>;
 export declare const customBlockGetUserErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"getUser.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/getUser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAKxD,eAAO,MAAM,iCAAiC,2BAAa,CAAA;AAE3D,MAAM,MAAM,2BAA2B,GAAG,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAE3E,MAAM,MAAM,2BAA2B,GACtC,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAElD,eAAO,MAAM,iCAAiC;;;;aAI5C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;aAI/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;0BAarC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}
+{"version":3,"file":"getUser.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/getUser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAK9E,eAAO,MAAM,iCAAiC,2BAAa,CAAA;AAE3D,MAAM,MAAM,2BAA2B,GACtC,oBAAoB,CAAC,iBAAiB,CAAC,CAAA;AAExC,MAAM,MAAM,2BAA2B,GACtC,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAElD,eAAO,MAAM,iCAAiC;;;;aAI5C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;aAI/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;0BAarC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockInitErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockInitErrorCode = "no_ready" | "invalid_ready" | "manifest_unavailable" | "manifest_invalid" | "invalid_protocol_version" | "unsupported_protocol_version" | "context_unavailable" | "current_user_unavailable" | "missing_data_source_binding" | "data_source_unavailable" | "missing_property_binding" | "invalid_property_binding" | "not_in_iframe" | "init_timeout" | "unknown_error" | (string & {});
+export type CustomBlockInitErrorCode = CustomBlockErrorCode<"no_ready" | "invalid_ready" | "manifest_unavailable" | "manifest_invalid" | "invalid_protocol_version" | "unsupported_protocol_version" | "context_unavailable" | "current_user_unavailable" | "missing_data_source_binding" | "data_source_unavailable" | "missing_property_binding" | "invalid_property_binding" | "not_in_iframe" | "init_timeout">;
 export type CustomBlockInitErrorInfo = CustomBlockErrorInfo<CustomBlockInitErrorCode>;
 export declare const customBlockInitErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AASxD,eAAO,MAAM,8BAA8B,2BAAa,CAAA;AAExD,MAAM,MAAM,wBAAwB,GACjC,UAAU,GACV,eAAe,GACf,sBAAsB,GACtB,kBAAkB,GAClB,0BAA0B,GAC1B,8BAA8B,GAC9B,qBAAqB,GACrB,0BAA0B,GAC1B,6BAA6B,GAC7B,yBAAyB,GACzB,0BAA0B,GAC1B,0BAA0B,GAC1B,eAAe,GACf,cAAc,GACd,eAAe,GACf,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,wBAAwB,GACnC,oBAAoB,CAAC,wBAAwB,CAAC,CAAA;AAE/C,eAAO,MAAM,8BAA8B;;;;aAIzC,CAAA;AAEF,qBAAa,oBACZ,SAAQ,KACR,YAAW,oBAAoB;gBAEnB,KAAK,EAAE,wBAAwB;IAO3C,IAAI,EAAE,wBAAwB,CAAA;IAC9B,WAAW,EAAE,OAAO,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAkB5B,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAS9E,eAAO,MAAM,8BAA8B,2BAAa,CAAA;AAExD,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,CACxD,UAAU,GACV,eAAe,GACf,sBAAsB,GACtB,kBAAkB,GAClB,0BAA0B,GAC1B,8BAA8B,GAC9B,qBAAqB,GACrB,0BAA0B,GAC1B,6BAA6B,GAC7B,yBAAyB,GACzB,0BAA0B,GAC1B,0BAA0B,GAC1B,eAAe,GACf,cAAc,CAChB,CAAA;AAED,MAAM,MAAM,wBAAwB,GACnC,oBAAoB,CAAC,wBAAwB,CAAC,CAAA;AAE/C,eAAO,MAAM,8BAA8B;;;;aAIzC,CAAA;AAEF,qBAAa,oBACZ,SAAQ,KACR,YAAW,oBAAoB;gBAEnB,KAAK,EAAE,wBAAwB;IAO3C,IAAI,EAAE,wBAAwB,CAAA;IAC9B,WAAW,EAAE,OAAO,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAkB5B,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockListUsersErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockListUsersErrorCode = "list_users_failed" | (string & {});
+export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<"list_users_failed">;
 export type CustomBlockListUsersErrorInfo = CustomBlockErrorInfo<CustomBlockListUsersErrorCode>;
 export declare const customBlockListUsersErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"listUsers.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/listUsers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAKxD,eAAO,MAAM,mCAAmC,2BAAa,CAAA;AAE7D,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAE/E,MAAM,MAAM,6BAA6B,GACxC,oBAAoB,CAAC,6BAA6B,CAAC,CAAA;AAEpD,eAAO,MAAM,mCAAmC;;;;aAI9C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;aAKjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAavC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CACjD,OAAO,4BAA4B,CACnC,CAAA"}
+{"version":3,"file":"listUsers.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/listUsers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAK9E,eAAO,MAAM,mCAAmC,2BAAa,CAAA;AAE7D,MAAM,MAAM,6BAA6B,GACxC,oBAAoB,CAAC,mBAAmB,CAAC,CAAA;AAE1C,MAAM,MAAM,6BAA6B,GACxC,oBAAoB,CAAC,6BAA6B,CAAC,CAAA;AAEpD,eAAO,MAAM,mCAAmC;;;;aAI9C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;aAKjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAavC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CACjD,OAAO,4BAA4B,CACnC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockQueryDataSourceErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockQueryDataSourceErrorCode = "query_data_source_failed" | "unknown_data_source_key" | "unmapped_data_source" | (string & {});
+export type CustomBlockQueryDataSourceErrorCode = CustomBlockErrorCode<"query_data_source_failed" | "unknown_data_source_key" | "unmapped_data_source">;
 export type CustomBlockQueryDataSourceErrorInfo = CustomBlockErrorInfo<CustomBlockQueryDataSourceErrorCode>;
 export declare const customBlockQueryDataSourceErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"queryDataSourceResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/queryDataSourceResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAIxD,eAAO,MAAM,yCAAyC,2BAAa,CAAA;AAEnE,MAAM,MAAM,mCAAmC,GAC5C,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,GACtB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,mCAAmC,GAC9C,oBAAoB,CAAC,mCAAmC,CAAC,CAAA;AAE1D,eAAO,MAAM,yCAAyC;;;;aAIpD,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOnD,CAAA;AAEF,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAgBnD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAG7C,CAAA;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CACvD,OAAO,kCAAkC,CACzC,CAAA"}
+{"version":3,"file":"queryDataSourceResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/queryDataSourceResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAI9E,eAAO,MAAM,yCAAyC,2BAAa,CAAA;AAEnE,MAAM,MAAM,mCAAmC,GAAG,oBAAoB,CACnE,0BAA0B,GAC1B,yBAAyB,GACzB,sBAAsB,CACxB,CAAA;AAED,MAAM,MAAM,mCAAmC,GAC9C,oBAAoB,CAAC,mCAAmC,CAAC,CAAA;AAE1D,eAAO,MAAM,yCAAyC;;;;aAIpD,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOnD,CAAA;AAEF,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAgBnD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAG7C,CAAA;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CACvD,OAAO,kCAAkC,CACzC,CAAA"}

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

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockUpdatePageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockUpdatePageErrorCode = "update_page_failed" | "invalid_page_update" | "page_access_failed" | "collection_access_failed" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value" | (string & {});
+export type CustomBlockUpdatePageErrorCode = CustomBlockErrorCode<"update_page_failed" | "invalid_page_update" | "page_access_failed" | "collection_access_failed" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value">;
 export type CustomBlockUpdatePageErrorInfo = CustomBlockErrorInfo<CustomBlockUpdatePageErrorCode>;
 export declare const customBlockUpdatePageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"updatePageResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/updatePageResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAKxD,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GACvC,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,0BAA0B,GAC1B,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,GACxB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAaxC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAClD,OAAO,6BAA6B,CACpC,CAAA"}
+{"version":3,"file":"updatePageResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/updatePageResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAK9E,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAC9D,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,0BAA0B,GAC1B,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,CAC1B,CAAA;AAED,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAaxC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAClD,OAAO,6BAA6B,CACpC,CAAA"}

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.65"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.0.67"

package/docs/data-sources.md

@@ -50,7 +50,7 @@ type UseDataSourceResult = {
 };
 ```
 
-Reads the data source mapped to `key`. `limit` defaults to 20 and is capped at 999. To show more rows, keep the desired limit in your own component state and pass the larger value back into `useDataSource(key, { limit })`. `propertySchemasByKey` is `undefined` for declared-but-unbound slots. When the host reports a query failure, `error` is `{ code, message, isRetryable }` with `code` narrowed to `CustomBlockQueryDataSourceErrorCode`.
+Reads the data source mapped to `key`. `limit` defaults to 20 and is capped at 999. To show more rows, keep the desired limit in your own component state and pass the larger value back into `useDataSource(key, { limit })`. `propertySchemasByKey` is `undefined` for declared-but-unbound slots. Query failures follow the SDK's [error-handling contract](./errors.md).
 
 ### `useManifest()`
 

package/docs/errors.md

@@ -0,0 +1,48 @@
+# Error handling
+
+Request-style SDK APIs resolve to a result with `status: "success"` or `status: "error"`. Conceptually, success payloads vary by API while error results contain an `error` object with a consistent structure:
+
+```ts
+type Result<T> =
+  | { status: "success"; value: T }
+  | { status: "error"; error: CustomBlockErrorInfo };
+```
+
+## Error format
+
+SDK errors use `CustomBlockErrorInfo`:
+
+```ts
+type CustomBlockErrorInfo<TCode extends string = string> = {
+  code: TCode;
+  message: string;
+  isRetryable: boolean;
+};
+```
+
+- `code` is a stable identifier intended for application logic.
+- `message` provides developer-facing details and is not a stable identifier.
+- `isRetryable` indicates whether retrying the operation could plausibly succeed.
+
+Each API narrows `code` to its own open string union. The known literals provide autocomplete, but newer hosts may send codes that an older SDK does not list.
+
+## API-specific error types
+
+- Pages: `CustomBlockCreatePageErrorCode` / `CustomBlockCreatePageErrorInfo`, `CustomBlockGetPageErrorCode` / `CustomBlockGetPageErrorInfo`, and `CustomBlockUpdatePageErrorCode` / `CustomBlockUpdatePageErrorInfo`.
+- Users: `CustomBlockGetUserErrorCode` / `CustomBlockGetUserErrorInfo` and `CustomBlockListUsersErrorCode` / `CustomBlockListUsersErrorInfo`.
+- Data sources: `CustomBlockQueryDataSourceErrorCode` / `CustomBlockQueryDataSourceErrorInfo`.
+- Shared resolution failures: `CustomBlockPropertyErrorCode` / `CustomBlockPropertyErrorInfo` and `CustomBlockDataSourceResolutionErrorCode` / `CustomBlockDataSourceResolutionErrorInfo`.
+
+## Initialization errors
+
+Unlike request helpers, `initCustomBlock` rejects with `CustomBlockInitError` when the host rejects initialization. Use `error instanceof CustomBlockInitError`, then inspect its `code` and `isRetryable` fields. Its structured payload is available as `CustomBlockInitErrorInfo`, with `code` narrowed to `CustomBlockInitErrorCode`.
+
+See [Lifecycle and initialization](./lifecycle.md) for initialization-specific error codes.
+
+## Handling errors
+
+- Branch on `code` and `isRetryable`, never on `message`.
+- Keep a default branch when switching on `code`. The known literals provide autocomplete, but newer hosts may send codes that an older SDK does not list.
+- Treat `isRetryable` as advisory when deciding whether to offer or schedule a retry.
+- Use `message` for developer-facing details, not as a stable identifier.
+- `"unknown_error"` means the host encountered an unexpected or unclassified failure.

package/docs/lifecycle.md

@@ -79,14 +79,6 @@ class CustomBlockInitError extends Error {
   isRetryable: boolean;
 }
 
-type CustomBlockErrorInfo<TCode extends string = string> = {
-  code: TCode;
-  message: string;
-  isRetryable: boolean;
-};
-
-type CustomBlockInitErrorInfo = CustomBlockErrorInfo<CustomBlockInitErrorCode>;
-
 type CustomBlockInitErrorCode =
   | "no_ready"
   | "invalid_ready"
@@ -105,11 +97,7 @@ type CustomBlockInitErrorCode =
   | "unknown_error";
 ```
 
-Thrown when the host rejects initialization instead of returning the initial theme, block location, current user, and data sources. `CustomBlockInitErrorInfo` uses the same structured error payload as every other API, with `code` narrowed to `CustomBlockInitErrorCode`. Use `error instanceof CustomBlockInitError`, `error.code`, and `error.isRetryable` to branch on host-reported setup failures.
-
-Runtime APIs use the same `CustomBlockErrorInfo<TCode>` envelope with their own code unions, such as `CustomBlockCreatePageErrorCode`, `CustomBlockUpdatePageErrorCode`, and `CustomBlockQueryDataSourceErrorCode`.
-
-The public API-specific runtime aliases are `CustomBlockCreatePageErrorInfo`, `CustomBlockGetPageErrorInfo`, `CustomBlockGetUserErrorInfo`, `CustomBlockListUsersErrorInfo`, `CustomBlockQueryDataSourceErrorInfo`, and `CustomBlockUpdatePageErrorInfo`. Their `code` fields are narrowed by `CustomBlockCreatePageErrorCode`, `CustomBlockGetPageErrorCode`, `CustomBlockGetUserErrorCode`, `CustomBlockListUsersErrorCode`, `CustomBlockQueryDataSourceErrorCode`, and `CustomBlockUpdatePageErrorCode`. Shared categories include `CustomBlockPropertyErrorCode` / `CustomBlockPropertyErrorInfo` and `CustomBlockDataSourceResolutionErrorCode` / `CustomBlockDataSourceResolutionErrorInfo`.
+Thrown when the host rejects initialization instead of returning the initial theme, block location, current user, and data sources. Use `error instanceof CustomBlockInitError`, `error.code`, and `error.isRetryable` to branch on host-reported setup failures. See [Error handling](./errors.md) for the shared structured error contract.
 
 ### `customBlock`
 

package/docs/pages.md

@@ -6,18 +6,7 @@ Helpers for creating, reading, updating, and archiving Notion pages from inside
 import { pages } from "@notionhq/custom-blocks";
 ```
 
-Every helper returns a discriminated result instead of throwing:
-
-```ts
-const result = await pages.get(pageId);
-if (result.status === "success") {
-  // result.page is a NotionPage
-} else {
-  // result.error is a human-readable string
-}
-```
-
-Always check `result.status` before reading `result.page`.
+Every helper follows the SDK's [error-handling contract](./errors.md). Check `result.status` before reading the success payload.
 
 ## Creating pages
 

package/docs/users.md

@@ -12,18 +12,7 @@ import {
 import { useCurrentUser } from "@notionhq/custom-blocks/react";
 ```
 
-Every helper returns a discriminated result instead of throwing:
-
-```ts
-const result = await users.get(userId);
-if (result.status === "success") {
-  // result.user is a NotionUser
-} else {
-  // result.error is a human-readable string
-}
-```
-
-Always check `result.status` before reading `result.user` / `result.list`.
+Every helper follows the SDK's [error-handling contract](./errors.md). Check `result.status` before reading `result.user` or `result.list`.
 
 ## Reading the current user
 

package/package.json

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

package/src/bridge/errors.ts

@@ -1,5 +1,13 @@
 import * as v from "valibot"
 
+export type CustomBlockErrorCode<KnownCode extends string> =
+	// Accept a list of known codes for auto-completion.
+	| KnownCode
+	// Hosts send this for any errors that are not covered by an error code known by that host.
+	| "unknown_error"
+	// Hosts may introduce new codes in the future, so allow any string as a catch-all.
+	| (string & {})
+
 export type CustomBlockErrorInfo<TCode extends string = string> = {
 	code: TCode
 	message: string

package/src/bridge/messages/createPageResult.ts

@@ -1,12 +1,12 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionPageSchema } from "../pages/page.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockCreatePageErrorCodeSchema = v.string()
 
-export type CustomBlockCreatePageErrorCode =
+export type CustomBlockCreatePageErrorCode = CustomBlockErrorCode<
 	| "create_page_failed"
 	| "invalid_page_parent"
 	| "page_access_failed"
@@ -17,7 +17,7 @@ export type CustomBlockCreatePageErrorCode =
 	| "property_id_mismatch"
 	| "duplicate_property"
 	| "invalid_property_value"
-	| (string & {})
+>
 
 export type CustomBlockCreatePageErrorInfo =
 	CustomBlockErrorInfo<CustomBlockCreatePageErrorCode>

package/src/bridge/messages/getPage.ts

@@ -1,5 +1,5 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionPageIdSchema } from "../ids.js"
 import { notionPageSchema } from "../pages/page.js"
 
@@ -7,10 +7,9 @@ import { notionPageSchema } from "../pages/page.js"
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockGetPageErrorCodeSchema = v.string()
 
-export type CustomBlockGetPageErrorCode =
-	| "get_page_failed"
-	| "page_access_failed"
-	| (string & {})
+export type CustomBlockGetPageErrorCode = CustomBlockErrorCode<
+	"get_page_failed" | "page_access_failed"
+>
 
 export type CustomBlockGetPageErrorInfo =
 	CustomBlockErrorInfo<CustomBlockGetPageErrorCode>

package/src/bridge/messages/getUser.ts

@@ -1,12 +1,13 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionUserSchema } from "../users/user.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockGetUserErrorCodeSchema = v.string()
 
-export type CustomBlockGetUserErrorCode = "get_user_failed" | (string & {})
+export type CustomBlockGetUserErrorCode =
+	CustomBlockErrorCode<"get_user_failed">
 
 export type CustomBlockGetUserErrorInfo =
 	CustomBlockErrorInfo<CustomBlockGetUserErrorCode>

package/src/bridge/messages/init.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot"
 import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionBlockIdSchema } from "../ids.js"
 import { customBlockPageSchema } from "../pages/page.js"
 import { notionParentSchema } from "../parent.js"
@@ -11,7 +11,7 @@ import { notionUserSchema } from "../users/user.js"
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockInitErrorCodeSchema = v.string()
 
-export type CustomBlockInitErrorCode =
+export type CustomBlockInitErrorCode = CustomBlockErrorCode<
 	| "no_ready"
 	| "invalid_ready"
 	| "manifest_unavailable"
@@ -26,8 +26,7 @@ export type CustomBlockInitErrorCode =
 	| "invalid_property_binding"
 	| "not_in_iframe"
 	| "init_timeout"
-	| "unknown_error"
-	| (string & {})
+>
 
 export type CustomBlockInitErrorInfo =
 	CustomBlockErrorInfo<CustomBlockInitErrorCode>

package/src/bridge/messages/listUsers.ts

@@ -1,12 +1,13 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionUserListSchema } from "../users/user.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockListUsersErrorCodeSchema = v.string()
 
-export type CustomBlockListUsersErrorCode = "list_users_failed" | (string & {})
+export type CustomBlockListUsersErrorCode =
+	CustomBlockErrorCode<"list_users_failed">
 
 export type CustomBlockListUsersErrorInfo =
 	CustomBlockErrorInfo<CustomBlockListUsersErrorCode>

package/src/bridge/messages/queryDataSourceResult.ts

@@ -1,16 +1,16 @@
 import * as v from "valibot"
 import { notionDataSourcePageBridgeSchema } from "../dataSources/dataSourcePage.js"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockQueryDataSourceErrorCodeSchema = v.string()
 
-export type CustomBlockQueryDataSourceErrorCode =
+export type CustomBlockQueryDataSourceErrorCode = CustomBlockErrorCode<
 	| "query_data_source_failed"
 	| "unknown_data_source_key"
 	| "unmapped_data_source"
-	| (string & {})
+>
 
 export type CustomBlockQueryDataSourceErrorInfo =
 	CustomBlockErrorInfo<CustomBlockQueryDataSourceErrorCode>

package/src/bridge/messages/updatePageResult.ts

@@ -1,12 +1,12 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionPageSchema } from "../pages/page.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockUpdatePageErrorCodeSchema = v.string()
 
-export type CustomBlockUpdatePageErrorCode =
+export type CustomBlockUpdatePageErrorCode = CustomBlockErrorCode<
 	| "update_page_failed"
 	| "invalid_page_update"
 	| "page_access_failed"
@@ -15,7 +15,7 @@ export type CustomBlockUpdatePageErrorCode =
 	| "property_id_mismatch"
 	| "duplicate_property"
 	| "invalid_property_value"
-	| (string & {})
+>
 
 export type CustomBlockUpdatePageErrorInfo =
 	CustomBlockErrorInfo<CustomBlockUpdatePageErrorCode>