@notionhq/custom-blocks 0.0.58

package/HOST.md

@@ -0,0 +1,171 @@
+# @notionhq/custom-blocks/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. The main author-facing API surface lives in `@notionhq/custom-blocks`.
+
+Most exports here are thin re-exports of internal `bridge/*` modules. 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 {
+  pageChangedMessageSchema,
+  parentChangedMessageSchema,
+  readIncomingType,
+  sandboxToHostMessageSchema,
+  type PageChangedMessage,
+  type ParentChangedMessage,
+  type SandboxToHostMessage,
+} from "@notionhq/custom-blocks/host";
+```
+
+`readIncomingType()` is intentionally best-effort. Use it after validation fails so the host can avoid NACK loops and include a useful reason in `invalidSandboxMessage`.
+
+`createCustomBlockHost()` is an optional protocol loop for lightweight hosts. It owns iframe message listener setup, `ready` / `init`, protocol version checks, malformed-message NACKs, request routing, auto-resize callbacks, state-change messages, cleanup, and latest-query refresh bookkeeping. It deliberately does not know about any host's data model, permissions, iframe policy, analytics, or UI state.
+
+```ts
+import { createCustomBlockHost } from "@notionhq/custom-blocks/host";
+
+const host = createCustomBlockHost({
+  iframe,
+  initialState: {
+    theme,
+    blockId,
+    parent,
+    page,
+    currentUser,
+    dataSources: { bindings },
+  },
+  handlers: {
+    queryDataSource: async (message) => ({ items: [], hasMore: false }),
+  },
+});
+```
+
+Use it when the generic protocol loop is helpful. Hosts with more specialized runtime needs can keep using the schemas and message types directly.
+
+Related types: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomBlockHostInitialDataSources`, `CustomBlockHostDataSourcesPayload`, `CustomBlockHostHandlers`, `CustomBlockHostHandle`, `CustomBlockHostLogDirection`, `CustomBlockHostQueryDataSourceResult`, `CustomBlockHostCreatePageResult`, `CustomBlockHostGetPageResult`, `CustomBlockHostUpdatePageResult`, `CustomBlockHostGetUserResult`, and `CustomBlockHostListUsersResult`.
+
+## Bridge protocol
+
+### Lifecycle
+
+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:
+
+```ts
+// sandbox → host
+{ type: "ready", status: "success", bridgeProtocolVersion, sdkVersion, manifest: { /* custom_blocks.json */ } }
+
+// sandbox → host, no manifest / no declared data requirements
+{ 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: "..." } }
+```
+
+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 }`:
+
+```ts
+// host → sandbox
+{ type: "init", status: "success", theme, blockId, parent, page: { id }, currentUser, dataSources: { bindings } }
+```
+
+On failure it carries `error: { code, message, isRetryable }` (`CustomBlockInitErrorInfo` / `customBlockInitErrorInfoSchema`, with `code` drawn from `CustomBlockInitErrorCode` / `customBlockInitErrorCodeSchema`). The SDK surfaces this as a `CustomBlockInitError`:
+
+```ts
+// host → sandbox
+{ type: "init", status: "error", error: { code: "context_unavailable", message: "...", isRetryable: true } }
+```
+
+After `init`, narrower messages update live state without re-running the handshake — `themeChanged`, `parentChanged`, `pageChanged`, `currentUserChanged`, and `dataSourcesChanged`. Each replaces just its slice of state:
+
+```ts
+// host → sandbox, any time after init
+{ type: "themeChanged", theme }
+{ type: "parentChanged", parent }
+{ type: "pageChanged", page: { id } }
+{ type: "dataSourcesChanged", dataSources: { bindings } }
+```
+
+### Versioning
+
+`ready` includes `bridgeProtocolVersion` (the host <-> sandbox version) and `sdkVersion` (the package semver). Hosts should reject or fail `init` when the sandbox reports a `bridgeProtocolVersion` the host does not implement, but should treat `sdkVersion` as purely analytics metadata.
+
+If the sandbox reports a version below the host's supported minimum, reply with `init.status: "error"` and `error.code: "unsupported_protocol_version"`. If the reported version is structurally invalid (not a positive integer — e.g. `0`, negative, fractional, `NaN`, or `Infinity`), reply with `error.code: "invalid_protocol_version"` instead.
+
+### Conventions
+
+Every request/response pair uses a string `requestId`. The sender tracks pending requests by id; the receiver echoes the id on the matching result. The sandbox drops stale results that no longer match the latest outstanding request for that operation.
+
+Both sides validate inbound messages with valibot schemas. Failed parses are logged and NACKed with `invalidHostMessage` or `invalidSandboxMessage`. Never answer a NACK with another NACK.
+
+Block-author APIs use semantic data-source keys, but sandbox-to-host object references are resolved to raw IDs before posting.
+
+Every bridge error payload uses the same `{ code, message, isRetryable }` shape. `CustomBlockErrorInfo<TCode>` is generic so each bridge API can expose its own code union while preserving one wire format. Hosts should pick stable codes and put user/developer-readable detail in `message`; sandboxes should branch on `code` and `isRetryable`, not message text.
+
+`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.
+
+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`.
+
+## Data sources
+
+Types:
+
+- `CustomBlockPage` — the current page slice carried in `init.page` and `pageChanged`.
+- `NotionDataSourceBinding` — a single binding (collection pointer + schema + property mapping).
+- `NotionDataSourceBindings` — keyed-by-semantic-key map of bindings, the shape carried in `init.dataSources` and `dataSourcesChanged`.
+- `NotionDataSourcePageBridge` — wire shape for a single page (raw property IDs in `propertiesById`). The SDK derives the consumer-facing `NotionDataSourcePage` from it.
+
+Schemas:
+
+- `notionBlockIdSchema`
+- `customBlockPageSchema`
+- `notionDataSourceIdSchema`
+- `notionDataSourceBindingSchema`
+- `notionDataSourceBindingsSchema`
+- `notionDataSourcePageBridgeSchema`
+- `notionPageIdSchema`
+- `notionParentSchema`
+
+## Sandbox → host messages
+
+Messages sent from the sandbox to the host. Parse `window` `message` events with `sandboxToHostMessageSchema` (or per-message schemas). The type / schema column points to the payload shape.
+
+| Wire type            | Type / schema                                             | Behavior                                                                                                                                                                                                                                |
+| -------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`              | `ReadyMessage` / `readyMessageSchema`                     | One-shot handshake; carries `bridgeProtocolVersion`, `sdkVersion`, and the manifest.                                                                                                                                                     |
+| `queryDataSource`    | `QueryDataSourceMessage` / `queryDataSourceMessageSchema` | `requestId`-keyed request for the current rows in a raw `dataSourceId`. `snapshotId` names the SDK result slot to update, so later refreshes for the same `useDataSource` call replace the same snapshot instead of creating a new one. |
+| `createPage`         | `CreatePageMessage` / `createPageMessageSchema`           | `requestId`-keyed page creation; parent is `page_id` or `data_source_id`.                                                                                                                                                               |
+| `getPage`            | `GetPageMessage` / `getPageMessageSchema`                 | `requestId`-keyed page fetch by page id.                                                                                                                                                                                                |
+| `updatePage`         | `UpdatePageMessage` / `updatePageMessageSchema`           | `requestId`-keyed patch (properties, icon, cover, or `archived`).                                                                                                                                                                       |
+| `getUser`            | `GetUserMessage` / `getUserMessageSchema`                 | `requestId`-keyed user fetch by user id.                                                                                                                                                                                                |
+| `listUsers`          | `ListUsersMessage` / `listUsersMessageSchema`             | `requestId`-keyed user list with optional `startCursor` and `pageSize`.                                                                                                                                                                 |
+| `resize`             | `ResizeMessage` / `resizeMessageSchema`                   | Latest measured content height from auto-resize.                                                                                                                                                                                        |
+| `invalidHostMessage` | `InvalidHostMessage` / `invalidHostMessageSchema`         | Sandbox-side NACK for a host message it could not parse.                                                                                                                                                                                |
+
+`SandboxToHostMessage` / `sandboxToHostMessageSchema` is the discriminated union over all of the above.
+
+## Host → sandbox messages
+
+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. |
+| `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `requestId` / `snapshotId`-keyed response with `items`, `hasMore`, and optional `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.                                                                  |
+
+`HostToSandboxMessage` / `hostToSandboxMessageSchema` is the discriminated union over all of the above.
+
+For result messages with `status: "error"` and for `queryDataSourceResult.error`, `error` always has the `CustomBlockErrorInfo<TCode>` shape. The concrete result types narrow `TCode` to the API-specific union, such as `CustomBlockCreatePageErrorCode`, `CustomBlockUpdatePageErrorCode`, or `CustomBlockQueryDataSourceErrorCode`.

package/README.md

@@ -0,0 +1,57 @@
+# @notionhq/custom-blocks
+
+> [!NOTE]
+> Nothing to see here. This is **extreme** alpha and currently only works for an unreleased product.
+
+SDK for building Notion custom view blocks.
+
+A custom view runs as a sandboxed `<iframe>` inside a Notion block on iOS, Android, and desktop. The only channel between your view and Notion is a `postMessage` bridge — this SDK wraps it in typed React hooks plus a small framework-neutral runtime API for non-React renderers.
+
+> **Pre-release.** Breaking changes may land at any time before 1.0.
+
+## Quick start
+
+```tsx
+// src/index.tsx
+import { NotionCustomBlock } from "@notionhq/custom-blocks/react";
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <NotionCustomBlock>
+    <App />
+  </NotionCustomBlock>,
+);
+```
+
+```tsx
+// src/App.tsx
+import { useBlockId, useTheme } from "@notionhq/custom-blocks/react";
+
+export function App() {
+  const blockId = useBlockId();
+  const theme = useTheme();
+  return <div data-theme={theme}>Hello from {blockId}.</div>;
+}
+```
+
+`<NotionCustomBlock>` runs the SDK ↔ host handshake (sends `ready` with the manifest, awaits `init`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
+
+## Reference
+
+API surface, one page per category. Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. Hover docs in your editor cover the per-field detail; these pages cover usage shape and the gotchas.
+
+- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `customBlock.autoResize`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
+- [`docs/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`. Where the block sits in the document tree and the host's color scheme.
+- [`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/manifest.md`](./docs/manifest.md) — `custom_blocks.json`, the Vite plugin, manifest types.
+
+## Forbidden APIs
+
+No top-level navigation, `window.open`, or auth redirects. No direct network requests — cross-origin work goes through the host (and is exposed via SDK hooks).
+
+## Bridge protocol
+
+The bridge speaks a versioned `postMessage` protocol. You shouldn't need protocol-level details to build a view. If you're implementing a host, see [`HOST.md`](./HOST.md).

package/bin/cli/attach.js

@@ -0,0 +1,180 @@
+import { extractId, formatUuid } from "./ids.js";
+import { ntnApi, ntnApiPatch, ntnWorkersCapabilities } from "./ntn.js";
+// ── Capability resolution ───────────────────────────────────────
+function normalizeCapabilities(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        for (const field of ["capabilities", "results", "data"]) {
+            if (Array.isArray(obj[field])) {
+                return obj[field];
+            }
+        }
+    }
+    return [];
+}
+function capabilityKey(cap) {
+    for (const field of ["key", "name", "id"]) {
+        const value = cap[field];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function capabilityType(cap) {
+    // `ntn` reports the capability kind under `_tag`; accept `type` too in case
+    // the wire shape shifts.
+    for (const field of ["_tag", "type"]) {
+        const value = cap[field];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function isCustomBlockCapability(cap) {
+    const type = capabilityType(cap);
+    // When no type field is present we can't filter — keep it and let the
+    // count-based selection below decide.
+    if (type === undefined) {
+        return true;
+    }
+    return type === "customBlock" || type === "custom_block";
+}
+function firstString(obj, fields) {
+    for (const field of fields) {
+        const value = obj[field];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function capabilityDefinitionId(cap) {
+    const top = firstString(cap, ["definition_id", "definitionId"]);
+    if (top) {
+        return top;
+    }
+    // The real `ntn` shape nests it under `state.definitionId`.
+    const state = cap.state;
+    if (state && typeof state === "object") {
+        const nested = firstString(state, [
+            "definitionId",
+            "definition_id",
+        ]);
+        if (nested) {
+            return nested;
+        }
+    }
+    // Some shapes nest the definition under a `definition` object.
+    const definition = cap.definition;
+    if (definition && typeof definition === "object") {
+        const id = definition.id;
+        if (typeof id === "string" && id.length > 0) {
+            return id;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a worker's custom-block capability to a `definition_id`.
+ *
+ * - Filters `ntn workers capabilities list` down to customBlock capabilities.
+ * - With `capability` set, picks the entry with that key.
+ * - With exactly one candidate, uses it.
+ * - With more than one and no `capability`, errors with the available keys.
+ */
+export function resolveDefinitionId(capability) {
+    const raw = ntnWorkersCapabilities();
+    const all = normalizeCapabilities(raw);
+    if (all.length === 0) {
+        console.error("Error: no worker capabilities found. Deploy the worker first with `ntn workers deploy`.\n");
+        console.error("  Raw `ntn workers capabilities list --json` output:");
+        console.error(JSON.stringify(raw, null, "\t"));
+        process.exit(1);
+    }
+    const customBlocks = all.filter(isCustomBlockCapability);
+    if (customBlocks.length === 0) {
+        console.error("Error: this worker exposes no customBlock capability to attach.\n");
+        process.exit(1);
+    }
+    let selected;
+    if (capability) {
+        const match = customBlocks.find(c => capabilityKey(c) === capability);
+        if (!match) {
+            const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
+            console.error(`Error: no customBlock capability named '${capability}'.\n`);
+            console.error(`  Available: ${keys.join(", ")}`);
+            process.exit(1);
+        }
+        selected = match;
+    }
+    else if (customBlocks.length > 1) {
+        const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
+        console.error(`Error: this worker exposes ${customBlocks.length} customBlock capabilities. Pick one with --capability <key>.\n`);
+        console.error(`  Available: ${keys.join(", ")}`);
+        process.exit(1);
+    }
+    else {
+        selected = customBlocks[0];
+    }
+    const definitionId = capabilityDefinitionId(selected);
+    if (!definitionId) {
+        console.error("Error: could not read a definition_id from the selected capability.\n");
+        console.error("  Raw capability entry:");
+        console.error(JSON.stringify(selected, null, "\t"));
+        process.exit(1);
+    }
+    return { definitionId, capabilityKey: capabilityKey(selected) };
+}
+/**
+ * Body for pointing a custom block at a worker's definition. The update-block
+ * endpoint requires the payload be keyed by block type — a top-level
+ * `definition_id` is rejected (`should be not present`). So it nests under
+ * `custom_block`, matching how `patchBlock` (datasources.ts) sets data_sources.
+ */
+function definitionPatchBody(definitionId) {
+    return { custom_block: { definition_id: definitionId } };
+}
+/**
+ * Point an existing custom block at a worker's customBlock definition.
+ *
+ * Resolves the block, verifies it's a `custom_block`, resolves the worker's
+ * definition_id (erroring on ambiguity), then PATCHes the block. Returns the
+ * dashed block UUID so callers (e.g. `create`) can chain.
+ */
+export function attach(options) {
+    const uuid = formatUuid(extractId(options.idOrUrl));
+    if (!options.jsonOutput) {
+        console.log(`\nFetching block ${uuid}…`);
+    }
+    const block = ntnApi(`/v1/blocks/${uuid}`);
+    if (block.type !== "custom_block") {
+        console.error(`Error: block ${uuid} is type "${block.type}", not "custom_block".\n`);
+        console.error("  Pass a custom block's ID/URL, or create one with `ncblock create`.");
+        process.exit(1);
+    }
+    const { definitionId, capabilityKey: key } = resolveDefinitionId(options.capability);
+    if (!options.jsonOutput) {
+        console.log(`Attaching definition ${definitionId}${key ? ` (capability "${key}")` : ""}…`);
+    }
+    ntnApiPatch(`/v1/blocks/${uuid}`, definitionPatchBody(definitionId));
+    const emitResult = options.emitResult ?? true;
+    if (options.jsonOutput) {
+        if (emitResult) {
+            console.log(JSON.stringify({
+                action: "attach",
+                block_id: uuid,
+                definition_id: definitionId,
+                capability: key,
+            }, null, "\t"));
+        }
+    }
+    else {
+        console.log(`\n✓ Attached block ${uuid} to definition ${definitionId}\n`);
+    }
+    return uuid;
+}

package/bin/cli/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { attach } from "./attach.js";
+import { create } from "./create.js";
+import { connect, getDataSources } from "./datasources.js";
+import { deploy } from "./deploy.js";
+import { pullData } from "./pullData.js";
+import { pullManifest } from "./pullManifest.js";
+const HELP = `
+ncblock — Notion Custom Block SDK CLI
+
+Usage:
+  ncblock connect <database-url-or-id> [options]
+  ncblock connect [--block <id>] [--bind <key>=<ds-id>] [options]
+  ncblock data_sources get <block-id-or-url>
+  ncblock deploy <dist-path> [--block <id>] [options]
+  ncblock pull_data <id-or-url> [--limit <n>] [--out <path>]
+  ncblock attach <block-id-or-url> [--capability <key>]
+  ncblock create [--parent <id-or-url>] [--capability <key>]
+
+Commands:
+  connect            Pull the data source schema and PATCH the block(s) in .notion/target.json
+  data_sources get   Read data source bindings from a custom block
+  deploy             Run \`ntn custom deploy\` for each block; appends --block IDs into target.json on success
+  pull_data          Resolve an ID/URL to a data source; print its schema + N rows as JSON to stdout
+  attach             Point a custom block at the worker's definition (from \`ntn workers capabilities\`)
+  create             Create a custom block (private page parent by default) and attach it
+
+Options:
+  --block <id>       Block ID/URL (repeatable; accumulates into target.json's block_id[])
+  --bind <key>=<id>  Bind a manifest key to a data source ID (repeatable)
+  --capability <key> customBlock capability key to attach (required if the worker has more than one)
+  --parent <id>      Parent ID/URL for \`create\` (a page hosts the block; omit for a new private page)
+  --limit <n>        Rows to pull for \`pull_data\` (default: 25, max: 100)
+  --env <name>       Notion env (defaults to target.json's env, or "production")
+  --key <key>        Data source key in manifest (default: "default") — for connect <id> only
+  --out <path>       Output path — manifest for connect, JSON file for pull_data
+  --manifest <path>  Path to custom_blocks.json (default: "./custom_blocks.json")
+  --dry-run          Print the intended action without performing it
+  --json             Emit machine-parseable JSON output
+  --help, -h         Show this help message
+
+Examples:
+  ncblock connect <db-url>
+  ncblock connect --block <block-id> --bind default=<db-id>
+  ncblock data_sources get <block-id>
+  ncblock deploy dist/
+  ncblock pull_data <db-url> --limit 50 --out sample.json
+  ncblock attach <block-url> --capability hello
+  ncblock create
+`;
+function parseArgs(argv) {
+    const flags = {};
+    const bindings = {};
+    const blocks = [];
+    const positional = [];
+    let i = 2;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "--key") {
+            flags.key = argv[++i];
+        }
+        else if (arg === "--out") {
+            flags.out = argv[++i];
+        }
+        else if (arg === "--dry-run") {
+            flags.dryRun = true;
+        }
+        else if (arg === "--json") {
+            flags.jsonOutput = true;
+        }
+        else if (arg === "--quiet") {
+            flags.quiet = true;
+        }
+        else if (arg === "--manifest") {
+            flags.manifest = argv[++i];
+        }
+        else if (arg === "--capability") {
+            flags.capability = argv[++i];
+        }
+        else if (arg === "--parent") {
+            flags.parent = argv[++i];
+        }
+        else if (arg === "--limit") {
+            flags.limit = argv[++i];
+        }
+        else if (arg === "--env") {
+            flags.env = argv[++i];
+        }
+        else if (arg === "--block") {
+            const value = argv[++i];
+            if (!value) {
+                console.error("Error: --block requires a value.\n");
+                console.error("Usage: --block <id-or-url>");
+                process.exit(1);
+            }
+            blocks.push(value);
+        }
+        else if (arg === "--bind") {
+            const pair = argv[++i];
+            const eq = pair?.indexOf("=");
+            if (!pair || eq === undefined || eq < 1) {
+                console.error(`Error: invalid --bind value: ${pair}\n`);
+                console.error("Expected format: --bind <key>=<data-source-id>");
+                process.exit(1);
+            }
+            bindings[pair.slice(0, eq)] = pair.slice(eq + 1);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            flags.help = true;
+        }
+        else if (!arg.startsWith("-")) {
+            positional.push(arg);
+        }
+        i++;
+    }
+    return { flags, bindings, blocks, positional };
+}
+function main() {
+    const { flags, bindings, blocks, positional } = parseArgs(process.argv);
+    if (flags.help || positional.length === 0) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const [command, subcommand, ...rest] = positional;
+    // `manifest pull` is kept as an internal/advanced command — not advertised
+    // in HELP, but still callable for users who want pull without the PATCH
+    // step. Prefer `ncblock connect <id>`.
+    if (command === "manifest" && subcommand === "pull") {
+        const idOrUrl = rest[0];
+        if (!idOrUrl) {
+            console.error("Error: missing <id-or-url> argument.\n");
+            console.error("Usage: ncblock manifest pull <id-or-url> [options]");
+            process.exit(1);
+        }
+        pullManifest({
+            idOrUrl,
+            key: flags.key,
+            out: flags.out,
+            dryRun: flags.dryRun,
+            quiet: flags.quiet,
+        });
+        return;
+    }
+    if (command === "connect") {
+        // `ncblock connect <database-url-or-id>` pulls the schema first then
+        // runs the binding/PATCH flow against target.json. The positional
+        // must point at a database (or a data source); ID-kind classification
+        // (block vs view vs wrong-workspace) happens upstream in `init.ts`.
+        connect({
+            idOrUrl: subcommand,
+            blockIds: blocks,
+            bindings,
+            key: flags.key,
+            out: flags.out,
+            manifest: flags.manifest,
+            env: flags.env,
+            dryRun: flags.dryRun,
+            jsonOutput: flags.jsonOutput,
+            quiet: flags.quiet,
+        });
+        return;
+    }
+    if (command === "data_sources" && subcommand === "get") {
+        const idOrUrl = rest[0];
+        if (!idOrUrl) {
+            console.error("Error: missing <block-id-or-url> argument.\n");
+            console.error("Usage: ncblock data_sources get <block-id-or-url>");
+            process.exit(1);
+        }
+        getDataSources(idOrUrl);
+        return;
+    }
+    if (command === "deploy") {
+        const distPath = subcommand;
+        if (!distPath) {
+            console.error("Error: missing <dist-path> argument.\n");
+            console.error("Usage: ncblock deploy <dist-path> [--block <id>...] [--env <name>]");
+            process.exit(1);
+        }
+        deploy({
+            distPath,
+            blockIds: blocks,
+            env: flags.env,
+            dryRun: flags.dryRun,
+            jsonOutput: flags.jsonOutput,
+        });
+        return;
+    }
+    // The commands below route their API calls through ntn.ts, which resolves
+    // the env from `process.env.ENV` (falling back to target.json). Honor an
+    // explicit --env by setting it here so every ntn call inherits it.
+    if (flags.env) {
+        process.env.ENV = flags.env;
+    }
+    if (command === "pull_data") {
+        const idOrUrl = subcommand;
+        if (!idOrUrl) {
+            console.error("Error: missing <id-or-url> argument.\n");
+            console.error("Usage: ncblock pull_data <id-or-url> [--limit <n>] [--out <path>]");
+            process.exit(1);
+        }
+        const limitRaw = flags.limit;
+        const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+        if (limit !== undefined && !Number.isFinite(limit)) {
+            console.error(`Error: --limit must be a number, got '${limitRaw}'.`);
+            process.exit(1);
+        }
+        pullData({
+            idOrUrl,
+            limit,
+            out: flags.out,
+        });
+        return;
+    }
+    if (command === "attach") {
+        const idOrUrl = subcommand;
+        if (!idOrUrl) {
+            console.error("Error: missing <block-id-or-url> argument.\n");
+            console.error("Usage: ncblock attach <block-id-or-url> [--capability <key>]");
+            process.exit(1);
+        }
+        attach({
+            idOrUrl,
+            capability: flags.capability,
+            jsonOutput: flags.jsonOutput,
+        });
+        return;
+    }
+    if (command === "create") {
+        create({
+            parent: flags.parent,
+            capability: flags.capability,
+            jsonOutput: flags.jsonOutput,
+        });
+        return;
+    }
+    console.error(`Unknown command: ${positional.join(" ")}\n`);
+    console.log(HELP);
+    process.exit(1);
+}
+try {
+    main();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`\nError: ${message}\n`);
+    process.exit(1);
+}