@notionhq/custom-blocks-host 0.3.11 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Notion Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,270 +1,177 @@
 # @notionhq/custom-blocks-host
 
-The shared host connects an embedding application to a custom block sandbox. It loads the manifest,
-prepares initialization, validates messages, routes requests, manages query subscriptions, and
-cleans up the connection.
+The host manages the bridge between your application and a custom block iframe. Your application
+owns the iframe, permissions, data access, persistence, analytics, and UI. Block authors use
+`@notionhq/custom-blocks`.
 
-The embedding application creates the iframe and supplies permissions, record access, bindings,
-persistence, analytics, and UI. Both Notion and the dev shell use this package. Block authors use
-`@notionhq/custom-blocks` instead; they do not need to create a host.
+Create the host before navigating the iframe. Pass the full block URL as `sandboxUrl`, and call
+`stop()` when removing the iframe.
 
-## `createCustomBlockHost()`
+For configuration and lifecycle details, see [Initialization and lifecycle](docs/lifecycle.md).
 
-Create a host before navigating its iframe to the block URL. Set `sandboxOrigin` to that URL's exact
-origin. The host accepts messages only from that iframe and origin, and targets outbound messages to
-the same origin.
+## Create a host
+
+Install `@notionhq/custom-blocks-host` in your embedding application. Run this TypeScript through
+your browser bundler after the document body exists.
+
+This example embeds a block with no data sources and supplies fixed demo context. Replace
+`https://blocks.example.com/hello` with your block's URL. Serve the block from a different origin
+than the embedding application.
 
 ```ts
 import { createCustomBlockHost } from "@notionhq/custom-blocks-host"
 
-const host = createCustomBlockHost({
-  iframe,
-  sandboxOrigin: "https://example.com",
-  manifestSource: "persisted",
-  getPersistedManifest: async ({ signal }) => loadSavedManifest(signal),
-  prepareInitialState: async ({ manifest, signal }) => ({
-    status: "success",
-    initialState: {
-      theme,
-      contrastMode,
-      blockId,
-      parent,
-      page,
-      currentUser,
-      dataSources: {
-        bindings: await loadBindings(manifest, signal),
-      },
-    },
-  }),
-  handlers: {
-    queryDataSource: async message => ({
+function mountCustomBlock(container: HTMLElement, blockUrl: URL): () => void {
+  if (
+    !["http:", "https:"].includes(blockUrl.protocol) ||
+    blockUrl.origin === window.location.origin
+  ) {
+    throw new Error("The block needs an HTTP or HTTPS URL on a separate origin")
+  }
+
+  const wrapper = document.createElement("section")
+  const status = document.createElement("p")
+  status.setAttribute("role", "status")
+  status.textContent = "Loading block…"
+  const iframe = document.createElement("iframe")
+  iframe.title = "Hello custom block"
+  iframe.setAttribute("sandbox", "allow-scripts allow-same-origin")
+  iframe.allow = "clipboard-write"
+  iframe.style.width = "100%"
+  iframe.style.height = "300px"
+  iframe.style.visibility = "hidden"
+  wrapper.append(status, iframe)
+  container.append(wrapper)
+
+  function setHeight(height: number) {
+    iframe.style.height = `${Math.min(1200, Math.max(120, height))}px`
+  }
+
+  const host = createCustomBlockHost({
+    iframe,
+    sandboxUrl: blockUrl.href,
+    manifestSource: "host",
+    getPersistedManifest: async () => ({
       status: "success",
-      items: await queryRows(message),
-      hasMore: false,
+      manifest: { version: 1, dataSources: {} },
     }),
-    resize: message => resizeIframe(message.height),
-  },
-  onInitialized: state => showBlock(state),
-  onConnectionFailure: error => showHostError(error),
-  onQueryUnsubscribed: undefined,
-  onLog: (direction, payload) => console.log(direction, payload),
-})
-```
-
-### Manifest and initial state
-
-The host starts loading the manifest when it is created. `manifestSource` determines where the
-manifest comes from:
-
-- `"persisted"` requires `getPersistedManifest({ signal })`. The callback supplies a saved block
-  definition or a dev-shell worker registry manifest.
-- `"local"` fetches `/manifest` from `sandboxOrigin`. The URL must pass
-  [`isLocalCustomBlockUrl({ url, hostOrigin })`](#local-block-urls), including its origin-isolation
-  check. Requests omit credentials, reject redirects, bypass caches, and time out after five
-  seconds. This source has no callback or persisted fallback. Local refers to the block server, not
-  the host's environment.
-
-A manifest declares data sources by semantic key, with property schemas and optional block metadata
-(`name`, `description`, `slashCommand`, and emoji `icon`). If `dataSources` is omitted, it defaults
-to `{}`. Each data source's `properties` also defaults to `{}` when omitted. Hosts and SDKs use the
-same manifest shape. The host validates and normalizes the manifest, then calls
-`prepareInitialState({ manifest, signal })` once. The embedding application uses that manifest to
-prepare context and bindings, and returns them in `initialState`. The host includes the manifest
-with that state in `init`.
-
-Manifest loading and state preparation do not wait for `connect`. The host listens concurrently and
-sends `init` after both preparation and connection succeed. If preparation fails before `connect`,
-the host retains the failure and sends `init.error` when the sandbox connects.
-
-Manifest failures produce `manifest_unavailable`. Exceptions during state preparation produce
-`unknown_error`. `onLog("warn", payload)` receives diagnostic details. User-facing manifest errors
-remain generic. Stopping the host cancels preparation without logging a cancellation warning.
-
-The embedding application can load saved definitions separately during local preview, for example to
-restore saved bindings after preview ends. Local initialization does not wait for those reads.
-
-### Property compatibility
-
-The host selects page and query property shapes using `connect.bridgeProtocolVersion`. Protocol 7
-receives unique ID, button, formula, location, rollup, and verification property objects with text
-fallbacks. Protocol 6 receives `null` for those properties while retaining supported properties.
-This also applies to recent SDKs that briefly supported the richer values while still reporting
-protocol 6; those blocks must upgrade their SDK and rebuild to regain the values. Protocols 3–5
-retain flat query values and omit unsupported property objects from page responses. The host
-continues accepting older protocols; `sdkVersion` remains analytics metadata.
+    prepareInitialState: async () => ({
+      status: "success",
+      initialState: {
+        theme: "light",
+        contrastMode: "standard",
+        blockId: "11111111-1111-4111-8111-111111111111",
+        parent: {
+          type: "page_id",
+          page_id: "22222222-2222-4222-8222-222222222222",
+        },
+        page: {
+          type: "page",
+          id: "22222222-2222-4222-8222-222222222222",
+          parent: { type: "workspace", workspace: true },
+        },
+        currentUser: {
+          object: "user",
+          id: "33333333-3333-4333-8333-333333333333",
+          name: "Demo viewer",
+          avatar_url: null,
+          type: "person",
+          person: { email: "viewer@example.com" },
+        },
+        dataSources: { bindings: {} },
+      },
+    }),
+    handlers: {
+      queryDataSource: () => ({
+        status: "error",
+        error: {
+          code: "unknown_data_source_key",
+          message: "This demo has no data sources.",
+          isRetryable: false,
+        },
+      }),
+      resize: message => setHeight(message.height),
+    },
+    onStatusChange: state => {
+      if (state.status === "initialized") {
+        setHeight(state.initialHeight ?? 300)
+        status.hidden = true
+        iframe.style.visibility = "visible"
+      } else if (state.status === "failed") {
+        iframe.style.visibility = "hidden"
+        status.hidden = false
+        status.textContent = `Block failed: ${state.error.code}`
+      }
+    },
+    onQueryUnsubscribed: undefined,
+  })
 
-### Connection lifecycle
+  // The host must listen before the block starts its handshake.
+  iframe.src = blockUrl.href
 
-Each host handles one handshake with one iframe:
+  return () => {
+    host.stop()
+    wrapper.remove()
+  }
+}
 
-```text
-sandbox connect → host init → sandbox initResult
+const dispose = mountCustomBlock(document.body, new URL("https://blocks.example.com/hello"))
+window.addEventListener("pagehide", dispose, { once: true })
 ```
 
-The host accepts the first `connect` attempt. Later attempts do not restart initialization. Live
-updates wait for a matching `initResult.success`.
-
-The first observed iframe `load` is allowed. A second load stops the host and reports retryable
-`iframe_reloaded`. Create a new host and iframe to retry initialization or replace the block URL.
-
-Stopping removes listeners, cancels preparation, clears timers, ends query subscriptions, and
-prevents further outbound messages, including pending responses. Call `stop()` when the iframe is
-removed.
-
-Load-event cleanup does not isolate documents before that event. A replacement document at the same
-origin can receive messages and invoke handlers until the host stops.
-
-All handshake timeouts default to five seconds:
-
-| Option                  | Waits for                               | Failure code            |
-| ----------------------- | --------------------------------------- | ----------------------- |
-| `noConnectTimeoutMs`    | `connect` after the iframe's first load | `no_connect`            |
-| `initialStateTimeoutMs` | State preparation after `connect`       | `initial_state_timeout` |
-| `noInitResultTimeoutMs` | `initResult` after `init`               | `no_init_result`        |
-
-The local manifest fetch has its own five-second timeout, starting when the host is created. The SDK
-waits for `init` without its own timeout. Handshake failures abort preparation and suppress late
-results. Asynchronous callbacks must respect their `signal`.
-
-`minBridgeProtocolVersion` defaults to the runtime's minimum supported version. A higher value
-rejects SDKs below that minimum. A lower value cannot enable unsupported versions. The host does not
-enforce a maximum protocol version.
+You should see “Loading block…” until the block completes initialization, then the block iframe. A
+connection failure displays its error code. The example limits the iframe height to 120–1,200 CSS
+pixels.
 
-Unavailable page context requires protocol 5. With protocols 3 and 4, an unavailable page produces
-`context_unavailable` during initialization or ends an active connection.
+Call `dispose()` when your application removes the embed. To retry a failed connection or change the
+block URL, dispose of the current embed and call `mountCustomBlock()` again.
 
-### Callbacks
+For a production integration, replace the demo context and manifest with your application's values.
+Supply data-source bindings and handlers for the APIs your block uses. Your application must enforce
+permissions and record access.
 
-- `onInitialized({ manifest, initialHeight })` runs after the sandbox accepts initialization. The
-  height is optional.
-- `onConnectionFailure(error)` reports a handshake failure, timeout, unavailable page context, or
-  iframe reload. The error contains `{ phase, source, code, message, isRetryable }`. `phase` is
-  `connect`, `init`, `initResult`, or `runtime`. `source` identifies the host or sandbox that
-  reported the failure. This callback can run after initialization succeeds.
-- `onQueryUnsubscribed(subscriptionId)` releases application resources when a subscription ends. The
-  host removes the subscription itself. The callback runs for unsubscribe, replacement, terminal
-  error, or host stop, once per ended subscription.
-- `onLog(direction, payload)` receives bridge messages and warnings. The embedding application
-  chooses where to record them.
+To connect workspace data, see [Connect a data source](docs/handlers.md#connect-a-data-source).
 
-### Request types
+## Guides and reference
 
-`queryDataSource` is required. Other request handlers are optional. Handlers return a result
-synchronously or as a promise. Successful results carry their response payload. Errors carry
-`{ code, message, isRetryable }`; error codes are open strings.
+- [Initialization and lifecycle](docs/lifecycle.md): manifests, context, timeouts, live state, and
+  cleanup.
+- [Handlers and data](docs/handlers.md): application handlers, data-source integration, queries, and
+  navigation.
+- [Host compatibility](docs/compatibility.md): supported versions and response conversions.
 
-TypeScript infers handler request types. Separately defined handlers can import request and
-page-property types from `@notionhq/custom-blocks-host`.
+The runtime handles the wire handshake and message validation. The shared protocol references cover
+payload semantics, version rules, and contract history:
 
-Request types such as `GetPageMessage` describe validated messages. Corresponding `*MessageInput`
-types accept plain string IDs for callers that construct requests. Initial state, live setters, and
-handler results also accept plain string IDs. The runtime validates these values and applies schema
-defaults. ID brands distinguish ID kinds in TypeScript; they do not check record existence or
-access. The embedding application enforces permissions and record access.
+- [Wire protocol](docs/bridge/protocol.md)
+- [Protocol versioning](docs/bridge/versioning.md)
+- [Protocol changelog](docs/bridge/changelog.md)
 
-### Query requests
+## Protocol schemas and types
 
-The SDK resolves semantic data-source and property keys to raw IDs before sending requests. The host
-validates filters and sorts against actual database properties in `collectionSchema.propertiesById`
-before invoking `queryDataSource`. Status group names and option names must match the bound schema.
-Sorts retain their order and contain at most ten unique properties.
+The `/protocol` entrypoint exposes the protocol definitions bundled with this host release. It
+provides message schemas and types, data shapes, IDs, error definitions, and protocol-version
+constants.
 
-### External navigation
-
-The `openExternalUrl` handler receives an `AbortSignal` and a normalized, absolute HTTP or HTTPS URL
-without credentials, limited to 2,048 JavaScript code units before and after normalization. Adapters
-display the exact URL, obtain approval, and navigate only after approval. They may apply additional
-URL restrictions and should dismiss confirmation UI when the signal aborts on stop or iframe reload.
-
-Each iframe permits one pending external-navigation request. A different request receives
-`pending_navigation`; a duplicate of the active request is ignored. Every completed request is
-forgotten, so a subsequent request requires fresh approval. Results are suppressed after stop. The
-runtime redacts `openExternalUrl.url` from `onLog` payloads.
-
-### Initialization and malformed messages
-
-The host validates inbound messages, correlates handshake IDs, and rejects malformed requests.
-Malformed messages do not restart initialization. The host logs and ignores stale valid `initResult`
-messages.
-
-The runtime owns the wire handshake and message validation. Integrators use the callbacks and
-handlers above; they do not need to construct or validate bridge messages themselves.
-
-## Updating live state
-
-The returned handle exposes `setTheme()`, `setContrastMode()`, `setParent()`, `setPage()`,
-`setDataSources()`, `setCurrentUser()`, `refreshQuery()`, and `stop()`.
-
-State updates made during initialization are held until `initResult.success`. Updates after that
-point are sent to the sandbox.
-
-`refreshQuery()` re-runs `queryDataSource` for each active subscription with the supplied data
-source ID, preserving its filter, sorts, and limit. Overlapping refreshes queue one follow-up query.
-The running query delivers its result before the follow-up starts.
-
-Unsubscribe, replacement, and host stop discard queued refreshes and suppress late results.
-Non-retryable query errors also end the subscription. Retryable errors retain it. A failed query can
-end its subscription while the connection stays active.
-
-## Local block URLs
-
-`isLocalCustomBlockUrl({ url, hostOrigin }: { url: URL; hostOrigin: string })` accepts HTTP(S) URLs
-on `localhost`, any `.localhost` subdomain, or `127.0.0.1`, without a username or password. It
-rejects URLs on the embedding page's origin and requires a nonempty `hostOrigin`. Pass the embedding
-page's serialized origin, such as `window.location.origin`.
-
-Both local manifest fetching and the dev shell use this policy. Existing callers must add the
-required `hostOrigin` argument when adopting this version.
-
-## `getAutoBoundPropertyIdsByKey()`
-
-`getAutoBoundPropertyIdsByKey()` matches manifest properties to database properties for initial
-bindings. A candidate must have the same property type and either:
-
-- An ID that exactly equals the manifest key, without trimming or case folding.
-- A display name that equals the manifest display name after trimming and lowercasing.
-
-Exactly one candidate produces a binding. Zero or multiple candidates leave the property unmapped.
+Import these definitions through the host package to use the protocol version shipped with that
+host:
 
 ```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" }
+import {
+  sandboxToHostMessageSchema,
+  type SandboxToHostMessage,
+} from "@notionhq/custom-blocks-host/protocol"
 ```
 
-## Standalone browser module
-
-The published package includes `dist/browser.js`, a single ES module with all dependencies. Load
-this file directly when the browser must not fetch additional modules, such as under an exact-URL
-Content Security Policy.
-
-## Wire protocol
+`LATEST_BRIDGE_PROTOCOL_VERSION` identifies the latest bridge protocol version defined by the
+bundled protocol.
 
-The host package bundles the wire protocol and exposes its public types. Use the host APIs instead
-of posting bridge messages directly or importing protocol implementation files. The protocol is
-included in the package; no separate protocol dependency is needed.
+Host APIs, configuration, handler results, and `*MessageInput` types are available from
+`@notionhq/custom-blocks-host`.
 
-## Date conversion
+These schemas validate wire payloads. Your application still enforces permissions.
 
-`toNotionDateValue()` converts `NotionDateInput` into the four date variants in
-`CustomBlockDateValue`, including reminders. Conversion failures throw `InvalidNotionDateError`.
-
-## Other exports
-
-- `LATEST_BRIDGE_PROTOCOL_VERSION`: the latest bridge protocol version bundled with this host
-  package.
-- `isLocalCustomBlockUrl()`: checks whether a URL can serve a local custom block over HTTP or HTTPS.
+## Standalone browser module
 
-The package also exports types for host configuration, request handlers, messages, and page
-properties.
+`dist/browser.js` is one ES module with all dependencies. Use it when the browser must not fetch
+additional modules, such as under an exact-URL Content Security Policy.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Fabian Hiller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/autoBindProperties.d.ts

@@ -4,8 +4,8 @@ export type AutoBindableProperty = {
     type: NotionPropertyType;
 };
 /**
- * Finds property IDs for a manifest's properties without changing the
- * manifest's semantic keys.
+ * Returns a map from manifest property keys to database property IDs.
+ * Unmapped keys are omitted.
  *
  * For each manifest property:
  * 1. Consider only schema properties of the same type.
@@ -13,6 +13,9 @@ export type AutoBindableProperty = {
  *    (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.
+ *
+ * An ID match has no priority over a display name match. If they identify two
+ * different properties of the same type, the manifest property stays unmapped.
  */
 export declare function getAutoBoundPropertyIdsByKey(args: {
     manifestProperties: Readonly<Record<string, AutoBindableProperty>>;

package/dist/autoBindProperties.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;GAaG;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

@@ -1,6 +1,6 @@
 /**
- * Finds property IDs for a manifest's properties without changing the
- * manifest's semantic keys.
+ * Returns a map from manifest property keys to database property IDs.
+ * Unmapped keys are omitted.
  *
  * For each manifest property:
  * 1. Consider only schema properties of the same type.
@@ -8,6 +8,9 @@
  *    (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.
+ *
+ * An ID match has no priority over a display name match. If they identify two
+ * different properties of the same type, the manifest property stays unmapped.
  */
 export function getAutoBoundPropertyIdsByKey(args) {
     const { manifestProperties, propertySchemasById } = args;