@notionhq/custom-blocks-host 0.0.1

package/README.md

@@ -0,0 +1,204 @@
+# @notionhq/custom-blocks-host
+
+Host runtime for the custom block bridge. This package owns the generic
+`postMessage` protocol loop used by hosts such as the local dev shell. It does
+not own iframe policy, permissions, persistence, analytics, or host UI state.
+Host implementations such as the dev shell and `notion-next` depend on this package.
+
+## `getAutoBoundPropertyIdsByKey()`
+
+`getAutoBoundPropertyIdsByKey()` matches manifest properties to schema
+properties for initial property binding. For each manifest property:
+
+1. Consider only schema properties of the same type.
+2. A schema property is a candidate if its ID equals the manifest key
+   (exact string: no trim, no case folding) or its display name equals the
+   manifest display name after `trim()` and lowercasing.
+3. Bind when there is exactly one candidate. Otherwise leave it unmapped.
+
+Wrong-type properties never enter the candidate set.
+
+```ts
+import { getAutoBoundPropertyIdsByKey } from "@notionhq/custom-blocks-host";
+
+const propertyIdsByKey = getAutoBoundPropertyIdsByKey({
+  manifestProperties: {
+    title: { name: "Task", type: "title" },
+    estimate: { name: "Estimate", type: "number" },
+  },
+  propertySchemasById: {
+    title: { name: "Different label", type: "title" },
+    "property-1": { name: " estimate ", type: "number" },
+  },
+});
+
+// { title: "title", estimate: "property-1" }
+```
+
+## `createCustomBlockHost()`
+
+`createCustomBlockHost()` attaches a message listener, performs the
+`connect` / `init` / `initResult` handshake, validates sandbox messages, routes
+requests to handlers, manages query subscriptions, and emits live state
+updates.
+
+```ts
+import { createCustomBlockHost } from "@notionhq/custom-blocks-host";
+
+const host = createCustomBlockHost({
+  iframe,
+  sandboxOrigin: "https://example.com",
+  minBridgeProtocolVersion: 3,
+  initialState: {
+    theme,
+    contrastMode,
+    blockId,
+    parent,
+    page,
+    currentUser,
+    manifest,
+    dataSources: { bindings },
+  },
+  handlers: {
+    queryDataSource: async (message) => ({
+      status: "success",
+      items: await queryRows(message),
+      hasMore: false,
+    }),
+    createPage: async (message) => createPage(message),
+    getPage: async (message) => getPage(message),
+    updatePage: async (message) => updatePage(message),
+    getUser: async (message) => getUser(message),
+    listUsers: async (message) => listUsers(message),
+    resize: (message) => resizeIframe(message.height),
+  },
+  onConnect: (message) => {
+    console.log("Connected SDK", message.sdkVersion);
+  },
+  onIgnoredConnect: () => {
+    remountHostAndIframe();
+  },
+  onLog: (direction, payload) => {
+    console.log(direction, payload);
+  },
+});
+```
+
+The host runs one initialization per instance. `onIgnoredConnect` fires when a
+`connect` arrives that the settled host cannot serve: the iframe document was
+replaced, or the document's first `connect` came after the no-connect timeout.
+Recreate the host and the iframe together so the document runs a fresh
+handshake against current host state.
+
+`queryDataSource` is required. Other request handlers are optional. Every
+request handler may return its result synchronously or as a promise. Results
+use a `status` discriminator: successful results carry their response payload,
+while errors carry `{ code, message, isRetryable }`.
+
+The `queryDataSource` handler receives raw data source and property IDs. Its
+optional `filter` and `sorts` fields have already been resolved by the SDK.
+The host validates that sorts contain at most 10 unique property IDs, checks
+property IDs and currently supported property types against the bound
+collection schema when available, and applies valid sorts in the order provided
+by the array.
+
+When a data source binding includes `collectionSchema`, the runtime validates
+select, multi-select, and status option names before invoking `queryDataSource`.
+Bindings without a collection schema cannot perform this check, so their query
+handlers remain responsible for validating option names.
+
+`initialState.dataSources` may also be a function of the successful `connect`
+message. This lets a host derive bindings from the sandbox-provided manifest.
+
+Set `sandboxOrigin` to the iframe's exact origin. The runtime targets outbound
+messages to that origin and rejects inbound messages from any other origin.
+The runtime also accepts `noConnectTimeoutMs` and `noInitResultTimeoutMs`; both
+default to five seconds.
+
+### Initialization and malformed messages
+
+`createCustomBlockHost()` performs one handshake for each host and iframe pair:
+
+```text
+sandbox connect → host init → sandbox initResult
+```
+
+The sandbox creates the `initializationId`. The host copies that ID into `init`.
+The sandbox copies it into `initResult`. The host sends live state changes only
+after it receives a matching `initResult.success`.
+
+The host must check that the `initializationId` in `initResult` exactly matches
+the ID in the `init` message. The host ignores a result with a different ID.
+If no result arrives, or only a stale valid result arrives, before the timeout,
+initialization ends with `no_init_result`.
+
+Hosts validate each inbound sandbox message with `sandboxToHostMessageSchema`
+before acting on it. If validation fails, the host uses `readIncomingType()` to
+identify the message and applies these rules:
+
+- A malformed `connect` with a readable `initializationId` gets `init.error`
+  with code `invalid_connect_payload`.
+- A malformed `initResult` gets one `invalidSandboxMessage` NACK. The host then
+  cancels the handshake and fails with the host-only `invalid_init_result_payload`
+  error. The host does not wait for the `no_init_result` timeout.
+- Any other malformed sandbox message gets one `invalidSandboxMessage` NACK.
+  The sandbox logs this NACK and does not reply.
+- Never reply to a sandbox-sent NACK with a host-sent NACK. The host should
+  not respond to `invalidHostMessage` or `invalidSandboxMessage` messages.
+
+The host accepts a valid `initResult.error` as a terminal initialization
+failure. It logs and ignores a valid `initResult` with a stale
+`initializationId` or an unexpected state.
+
+Hosts do not retry malformed messages. A host that receives a `connect` after
+initialization has settled must use `onIgnoredConnect` to recreate the host
+and iframe together.
+
+## Updating live state
+
+The returned handle exposes:
+
+- `setTheme()`
+- `setContrastMode()`
+- `setParent()`
+- `setPage()`
+- `setDataSources()`
+- `setCurrentUser()`
+- `refreshQuery()`
+- `post()`
+- `stop()`
+
+State updates are sent after `initResult.success`. Updates made earlier are
+held until initialization completes. `refreshQuery()` re-runs
+`queryDataSource` for every active subscription with the supplied data source
+ID, preserving each subscription's filter, sorts, and limit.
+
+Call `stop()` when the iframe is removed. It detaches listeners, clears
+timeouts, and discards active query subscriptions.
+
+## Wire protocol
+
+`createCustomBlockHost()` implements the protocol: it validates inbound
+messages, runs the initialization handshake, correlates requests, manages query
+subscriptions, and emits bridge NACKs. Use its state-update methods and
+handlers instead of posting bridge messages directly.
+
+The bridge protocol is maintained in this repository's `protocol/` package.
+The published host package includes a compiled copy of that protocol and does
+not expose it as a public subpath. Consumers should use the host APIs above
+instead of importing protocol implementation files.
+
+Host source in this repository imports protocol schemas and types from the
+workspace package. The publish build rewrites those imports to the bundled
+copy.
+
+Handler implementations must preserve message identity: one-shot operations
+return one result with the request's `requestId`, while `queryDataSource` is a
+long-lived subscription keyed by `subscriptionId`. The runtime handles the
+`connect` → `init` → `initResult` lifecycle, including waiting for
+`initResult.success` before live updates.
+
+Error payloads use `{ code, message, isRetryable }`. The runtime accepts any
+string for `code`, including codes that this package does not know yet. Host
+code should preserve unknown codes and use `isRetryable` to decide whether a
+retry is appropriate.

package/dist/autoBindProperties.d.ts

@@ -0,0 +1,21 @@
+import type { NotionPropertyType } from "./protocol/dataSources/propertySchema.js";
+export type AutoBindableProperty = {
+    name: string;
+    type: NotionPropertyType;
+};
+/**
+ * Finds property IDs for a manifest's properties without changing the
+ * manifest's semantic keys.
+ *
+ * For each manifest property:
+ * 1. Consider only schema properties of the same type.
+ * 2. A schema property is a candidate if its ID equals the manifest key
+ *    (exact string: no trim, no case folding) or its display name equals
+ *    the manifest display name after `trim()` and lowercasing.
+ * 3. Bind when there is exactly one candidate. Otherwise leave it unmapped.
+ */
+export declare function getAutoBoundPropertyIdsByKey(args: {
+    manifestProperties: Readonly<Record<string, AutoBindableProperty>>;
+    propertySchemasById: Readonly<Record<string, AutoBindableProperty>>;
+}): Record<string, string>;
+//# sourceMappingURL=autoBindProperties.d.ts.map

package/dist/autoBindProperties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoBindProperties.d.ts","sourceRoot":"","sources":["../src/autoBindProperties.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gEAAgE,CAAA;AAExG,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,kBAAkB,CAAA;CACxB,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IAClD,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAA;IAClE,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAA;CACnE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBzB"}

package/dist/autoBindProperties.js

@@ -0,0 +1,38 @@
+/**
+ * Finds property IDs for a manifest's properties without changing the
+ * manifest's semantic keys.
+ *
+ * For each manifest property:
+ * 1. Consider only schema properties of the same type.
+ * 2. A schema property is a candidate if its ID equals the manifest key
+ *    (exact string: no trim, no case folding) or its display name equals
+ *    the manifest display name after `trim()` and lowercasing.
+ * 3. Bind when there is exactly one candidate. Otherwise leave it unmapped.
+ */
+export function getAutoBoundPropertyIdsByKey(args) {
+    const { manifestProperties, propertySchemasById } = args;
+    const mappings = [];
+    for (const [propertyKey, manifestProperty] of Object.entries(manifestProperties)) {
+        const propertyId = getAutoBoundPropertyId({
+            propertyKey,
+            manifestProperty,
+            propertySchemasById,
+        });
+        if (propertyId !== undefined) {
+            mappings.push([propertyKey, propertyId]);
+        }
+    }
+    return Object.fromEntries(mappings);
+}
+function getAutoBoundPropertyId(args) {
+    const { propertyKey, manifestProperty, propertySchemasById } = args;
+    const normalizedManifestName = normalizePropertyDisplayName(manifestProperty.name);
+    const candidates = Object.entries(propertySchemasById).filter(([schemaId, propertySchema]) => propertySchema.type === manifestProperty.type &&
+        (schemaId === propertyKey ||
+            normalizePropertyDisplayName(propertySchema.name) ===
+                normalizedManifestName));
+    return candidates.length === 1 ? candidates[0][0] : undefined;
+}
+function normalizePropertyDisplayName(value) {
+    return value.trim().toLowerCase();
+}

package/dist/createCustomBlockHost.d.ts

@@ -0,0 +1,46 @@
+import { type NotionContrastMode } from "./protocol/contrast.js";
+import type { NotionDataSourceId } from "./protocol/ids.js";
+import type { ConnectMessage } from "./protocol/messages/connect.js";
+import type { HostToSandboxMessage } from "./protocol/messages/hostToSandbox.js";
+import type { InitResultMessage } from "./protocol/messages/initResult.js";
+import type { CustomBlockPage } from "./protocol/pages/page.js";
+import type { NotionParent } from "./protocol/parent.js";
+import type { NotionTheme } from "./protocol/theme.js";
+import type { NotionUser } from "./protocol/users/user.js";
+import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
+import type { CustomBlockHostHandlers, CustomBlockHostLogDirection } from "./messages/types.js";
+export type CustomBlockHostOptions = {
+    iframe: HTMLIFrameElement;
+    sandboxOrigin: string;
+    minBridgeProtocolVersion: number;
+    noConnectTimeoutMs?: number;
+    noInitResultTimeoutMs?: number;
+    initialState: CustomBlockHostInitialState;
+    handlers: CustomBlockHostHandlers;
+    onConnect?: (message: ConnectSuccessMessage) => void;
+    onInitResult?: (message: InitResultMessage) => void;
+    /**
+     * A `connect` arrived after this host's initialization settled — the
+     * document was replaced, or its first `connect` came after the host
+     * stopped waiting. Either way the host cannot serve it: the embedder
+     * should recreate host and iframe together so the document can run a
+     * fresh handshake.
+     */
+    onIgnoredConnect?: (message: ConnectMessage) => void;
+    onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;
+};
+export type CustomBlockHostHandle = {
+    stop: () => void;
+    post: (message: HostToSandboxMessage) => void;
+    setTheme: (theme: NotionTheme) => void;
+    setContrastMode: (contrastMode: NotionContrastMode) => void;
+    setParent: (parent: NotionParent) => void;
+    setPage: (page: CustomBlockPage) => void;
+    setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void;
+    setCurrentUser: (currentUser: NotionUser) => void;
+    refreshQuery: (args: {
+        dataSourceId: NotionDataSourceId;
+    }) => void;
+};
+export declare function createCustomBlockHost(options: CustomBlockHostOptions): CustomBlockHostHandle;
+//# sourceMappingURL=createCustomBlockHost.d.ts.map

package/dist/createCustomBlockHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAa1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAEtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAahG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IACpD,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,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,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;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA+cvB"}