ncblock 0.0.4 → 0.0.5

package/HOST.md

@@ -0,0 +1,68 @@
+# ncblock/host
+
+Host-side entrypoint. Use this when implementing the host end of the custom block bridge — the Notion app, the dev shell, tests, mocks, anything that talks to a sandboxed custom block over `postMessage`. Nothing here is meant for use inside a custom block and everything here should be considered a private API that may change without a version bump. That main API surface lives in `ncblock`.
+
+Every export here is a thin re-export of an internal `bridge/*` module. Hosts validate inbound sandbox traffic against the same valibot schemas the SDK uses on the sandbox side, so both ends of the bridge agree on shape.
+
+```ts
+import {
+  parseNotionCustomBlockContext,
+  sandboxToHostMessageSchema,
+  type SandboxToHostMessage,
+} from "ncblock/host";
+```
+
+## Context
+
+- `parseNotionCustomBlockContext(value)` — best-effort parser which returns `NotionCustomBlockContext | undefined`. Used by shells that ingest user-edited context JSON.
+- `notionCustomBlockContextSchema` — the underlying valibot schema, for stricter integration.
+
+## Data sources
+
+Types:
+
+- `NotionDataSourceBinding` — a single binding (collection pointer + schema + property mapping).
+- `NotionDataSourceBindings` — keyed-by-semantic-key map of bindings, the shape carried in `init` and `dataSourcesChanged`.
+- `NotionDataSourcePageBridge` — wire shape for a single page (raw property IDs in `propertiesById`). The SDK derives the consumer-facing `NotionDataSourcePage` from it.
+
+Schemas:
+
+- `notionDataSourceBindingSchema`
+- `notionDataSourceBindingsSchema`
+- `notionDataSourcePageBridgeSchema`
+
+## Sandbox → host messages
+
+Messages sent from the sandbox to the host.
+
+Hosts parse these out of `window` `message` events. Each message ships as a `{ FooMessage, fooMessageSchema }` pair:
+
+- `ReadyMessage` / `readyMessageSchema`
+- `QueryDataSourceMessage` / `queryDataSourceMessageSchema`
+- `CreatePageMessage` / `createPageMessageSchema`
+- `GetPageMessage` / `getPageMessageSchema`
+- `UpdatePageMessage` / `updatePageMessageSchema`
+- `ResizeMessage` / `resizeMessageSchema`
+- `InvalidHostMessage` / `invalidHostMessageSchema`
+
+`SandboxToHostMessage` / `sandboxToHostMessageSchema` is the discriminated union over all of the above.
+
+## Host → sandbox messages
+
+Messages sent from the host to the sandbox. Follows the same `{ FooMessage, fooMessageSchema }` convention:
+
+- `InitMessage` / `initMessageSchema`
+- `ThemeChangedMessage` / `themeChangedMessageSchema`
+- `ContextChangedMessage` / `contextChangedMessageSchema`
+- `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`
+- `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema`
+- `CreatePageResultMessage` / `createPageResultMessageSchema`
+- `GetPageResultMessage` / `getPageResultMessageSchema`
+- `UpdatePageResultMessage` / `updatePageResultMessageSchema`
+- `InvalidSandboxMessage` / `invalidSandboxMessageSchema`
+
+`HostToSandboxMessage` / `hostToSandboxMessageSchema` is the discriminated union over all of the above.
+
+## Utilities
+
+- `readIncomingType(data)` — best-effort `string | undefined` lookup of the `type` field on an arbitrary `unknown` payload. Used after schema validation fails, so a host can still distinguish (and avoid NACK-looping on) `invalidHostMessage` and surface a useful reason in `invalidSandboxMessage`.