@notionhq/custom-blocks 0.0.78 → 0.1.0

package/bin/cli/cli.js

@@ -1,248 +0,0 @@
-#!/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);
-}

package/bin/cli/create.js

@@ -1,106 +0,0 @@
-import { attach } from "./attach.js";
-import { extractId, formatUuid } from "./ids.js";
-import { ntnApi, ntnApiPatch, ntnApiPost } from "./ntn.js";
-const DEFAULT_PAGE_TITLE = "Custom block";
-function is404(error) {
-    return error instanceof Error && error.message.includes("404");
-}
-/**
- * Classify a `--parent` ID/URL. A database or data source means the user wants
- * a custom *view* under a collection (the parental-nesting flow), which the
- * public API can't express today — see `create` below. Anything else is
- * treated as a page/block to host the new block.
- */
-function classifyParent(uuid) {
-    try {
-        const db = ntnApi(`/v1/databases/${uuid}`);
-        if (db.object === "database") {
-            return "database";
-        }
-    }
-    catch (error) {
-        if (!is404(error)) {
-            throw error;
-        }
-    }
-    try {
-        const ds = ntnApi(`/v1/data_sources/${uuid}`);
-        if (ds.object === "data_source") {
-            return "data_source";
-        }
-    }
-    catch (error) {
-        if (!is404(error)) {
-            throw error;
-        }
-    }
-    return "page";
-}
-/** Create a private (workspace-level) page to host the new block. */
-function createPrivatePage() {
-    console.log("\nCreating a private page to host the block…");
-    const page = ntnApiPost("/v1/pages", {
-        parent: { workspace: true },
-        properties: {
-            title: { title: [{ text: { content: DEFAULT_PAGE_TITLE } }] },
-        },
-    });
-    if (!page.id) {
-        throw new Error("Page creation returned no id.");
-    }
-    const id = formatUuid(page.id);
-    console.log(`  Created page ${id}`);
-    return id;
-}
-/** Append an empty custom block under `pageId` and return its dashed UUID. */
-function createCustomBlock(pageId) {
-    console.log(`  Creating custom block under ${pageId}…`);
-    const result = ntnApiPatch(`/v1/blocks/${pageId}/children`, {
-        children: [{ type: "custom_block", custom_block: {} }],
-    });
-    const created = result.results?.[0];
-    if (!created?.id) {
-        throw new Error("Custom block creation returned no block id.");
-    }
-    return formatUuid(created.id);
-}
-/**
- * Create a new custom block and attach it to the worker's definition.
- *
- * - No `--parent`  → create a private page, then a block under it.
- * - Page `--parent` → create a block under that page.
- * - Database/data source `--parent` → a custom block as a collection view. The
- *   public API has no `custom` view type and the parent-nesting the backend
- *   uses isn't derivable from this repo, so we error rather than guess.
- */
-export function create(options) {
-    let pageId;
-    if (!options.parent) {
-        pageId = createPrivatePage();
-    }
-    else {
-        const parentUuid = formatUuid(extractId(options.parent));
-        const kind = classifyParent(parentUuid);
-        if (kind === "database" || kind === "data_source") {
-            console.error(`Error: --parent ${parentUuid} is a ${kind.replace("_", " ")}. Creating a custom block as a collection view isn't supported yet.\n`);
-            console.error("  The public API has no `custom` view type; the backend does the parent nesting. Create the custom block in Notion, then run `ncblock attach <block-id-or-url>`.");
-            process.exit(1);
-        }
-        pageId = parentUuid;
-    }
-    const blockId = createCustomBlock(pageId);
-    // Hand off to attach for definition resolution + the PATCH. It re-fetches
-    // the block (verifying type) and prints its own success line.
-    const attached = attach({
-        idOrUrl: blockId,
-        capability: options.capability,
-        jsonOutput: options.jsonOutput,
-        emitResult: false,
-    });
-    if (options.jsonOutput) {
-        console.log(JSON.stringify({ action: "create", page_id: pageId, block_id: attached }, null, "\t"));
-    }
-    else {
-        console.log(`✓ Created custom block ${attached} on page ${pageId}\n`);
-    }
-}

package/bin/cli/datasources.js

@@ -1,255 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
-import { extractId, formatUuid } from "./ids.js";
-import { ntnApi, ntnApiPatch } from "./ntn.js";
-import { pullManifest } from "./pullManifest.js";
-import { mergeTarget, readTarget, writeTarget } from "./target.js";
-// ── get ─────────────────────────────────────────────────────────
-export function getDataSources(idOrUrl) {
-    const uuid = formatUuid(extractId(idOrUrl));
-    console.log(`\nFetching block ${uuid}…\n`);
-    const block = ntnApi(`/v1/blocks/${uuid}`);
-    if (block.type !== "custom_block") {
-        console.error(`Error: block ${uuid} is type "${block.type}", not "custom_block".`);
-        process.exit(1);
-    }
-    const dataSources = block.custom_block?.data_sources ?? [];
-    if (dataSources.length === 0) {
-        console.log("No data sources bound to this custom block.\n");
-        return;
-    }
-    console.log(JSON.stringify(dataSources, null, "\t"));
-    console.log("");
-}
-function patchBlock(idOrUrl, dataSources, jsonOutput) {
-    const uuid = formatUuid(extractId(idOrUrl));
-    if (!jsonOutput) {
-        console.log(`\nUpdating block ${uuid}…\n`);
-    }
-    const result = ntnApiPatch(`/v1/blocks/${uuid}`, {
-        custom_block: { data_sources: dataSources },
-    });
-    const updated = result.custom_block?.data_sources ?? [];
-    if (jsonOutput) {
-        console.log(JSON.stringify({ block_id: uuid, data_sources: updated }, null, "\t"));
-    }
-    else if (updated.length === 0) {
-        console.log("✓ Cleared all data source bindings.\n");
-    }
-    else {
-        console.log(`✓ Set ${updated.length} data source binding(s):\n`);
-        console.log(JSON.stringify(updated, null, "\t"));
-        console.log("");
-    }
-    return result;
-}
-function targetToMappings(dataSources) {
-    return Object.entries(dataSources).map(([key, ds]) => {
-        const mapping = {
-            key,
-            data_source_id: ds.data_source_id,
-        };
-        if (Object.keys(ds.property_ids_by_key).length > 0) {
-            mapping.property_ids_by_key = ds.property_ids_by_key;
-        }
-        return mapping;
-    });
-}
-function emitDryRun(jsonOutput, payload) {
-    if (jsonOutput) {
-        console.log(JSON.stringify(payload, null, "\t"));
-    }
-    else {
-        console.log("\nDry run — would PATCH:\n");
-        console.log(JSON.stringify(payload, null, "\t"));
-        console.log("");
-    }
-}
-export function loadManifest(manifestPath) {
-    const path = resolvePath(process.cwd(), manifestPath ?? "custom_blocks.json");
-    if (!existsSync(path)) {
-        console.error(`Error: manifest not found at ${path}\n`);
-        console.error("Run 'ncblock connect <database-url-or-id>' to generate it, or pass --manifest <path>.");
-        process.exit(1);
-    }
-    let manifest;
-    try {
-        manifest = JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        console.error(`Error: failed to parse ${path}\n`);
-        console.error("custom_blocks.json must be valid JSON.");
-        process.exit(1);
-    }
-    return { path, manifest };
-}
-/**
- * Resolve a manifest data source entry's property IDs by querying the live
- * data source schema and matching declared `name` fields.
- *
- * Notion column names are case-sensitive. Property IDs are URL-encoded in
- * API responses (e.g. `%3EPdk` → `>Pdk`); we decode before storing them.
- */
-export function resolvePropertyIdsByKey(args) {
-    const { dataSourceId, manifestKey, manifestProps } = args;
-    const uuid = formatUuid(extractId(dataSourceId));
-    const schema = ntnApi(`/v1/data_sources/${uuid}`);
-    const schemaProps = schema.properties ?? {};
-    // Build a name-keyed index. The API map is keyed by name already, but be
-    // defensive and use the `name` field on each entry so we don't depend on
-    // the map's key shape.
-    const byName = new Map();
-    for (const prop of Object.values(schemaProps)) {
-        byName.set(prop.name, prop);
-    }
-    const out = {};
-    for (const [propKey, manifestProp] of Object.entries(manifestProps)) {
-        const match = byName.get(manifestProp.name);
-        if (!match) {
-            console.error(`Error: column '${manifestProp.name}' (${manifestProp.type}) not found in data source ${uuid} (manifest key '${manifestKey}').\n` +
-                `  Either rename a column in Notion to '${manifestProp.name}', or edit .notion/target.json's data_sources.${manifestKey}.property_ids_by_key manually.`);
-            process.exit(1);
-        }
-        if (match.type !== manifestProp.type) {
-            console.error(`Error: column '${manifestProp.name}' is type '${match.type}' in the data source, but the manifest declares '${manifestProp.type}'.\n` +
-                `  Change the Notion column type, or update custom_blocks.json so the types line up.`);
-            process.exit(1);
-        }
-        out[propKey] = decodeURIComponent(match.id);
-    }
-    return out;
-}
-function buildFromManifest(manifestPath, bindings) {
-    const { manifest } = loadManifest(manifestPath);
-    const keys = Object.keys(manifest.dataSources ?? {});
-    if (keys.length === 0) {
-        console.error("Error: manifest has no data source keys.\n");
-        console.error("Run 'ncblock connect <database-url-or-id>' to populate custom_blocks.json.");
-        process.exit(1);
-    }
-    const missing = keys.filter(k => !bindings[k]);
-    if (missing.length > 0) {
-        console.error(`Error: missing --bind for manifest key(s): ${missing.join(", ")}\n`);
-        console.error("Use --bind <key>=<data-source-id> for each data source in the manifest.");
-        process.exit(1);
-    }
-    return keys.map(key => {
-        const entry = {
-            key,
-            data_source_id: bindings[key],
-        };
-        const props = manifest.dataSources[key]?.properties;
-        if (props && Object.keys(props).length > 0) {
-            entry.property_ids_by_key = resolvePropertyIdsByKey({
-                dataSourceId: bindings[key],
-                manifestKey: key,
-                manifestProps: props,
-            });
-        }
-        return entry;
-    });
-}
-export function connect(options) {
-    // When a positional database URL/ID is supplied, pull the schema first.
-    // `pullManifest` writes both custom_blocks.json and `.notion/target.json`,
-    // so the connect step below just reads from target.json as usual.
-    if (options.idOrUrl) {
-        pullManifest({
-            idOrUrl: options.idOrUrl,
-            key: options.key,
-            out: options.out,
-            dryRun: options.dryRun,
-            quiet: options.quiet,
-        });
-        if (options.dryRun) {
-            return;
-        }
-    }
-    const existingTarget = readTarget();
-    // Bindings come from --bind flags OR from target.json's data_sources
-    // (where `manifest pull` stashes the resolved data_source_id). Flags win.
-    const bindings = { ...options.bindings };
-    if (Object.keys(bindings).length === 0 && existingTarget) {
-        for (const [key, ds] of Object.entries(existingTarget.data_sources)) {
-            bindings[key] = ds.data_source_id;
-        }
-    }
-    if (Object.keys(bindings).length === 0) {
-        console.error("Error: no data sources to connect — pass a database URL/ID as a positional argument, --bind <key>=<data-source-id>, or wire one up with 'ncblock connect <database-url-or-id>'.\n");
-        process.exit(1);
-    }
-    // Blocks: --block flags + whatever's already in target.json. Flags don't
-    // "win" here, they accumulate — same as how deploy treats blocks.
-    const blockIds = Array.from(new Set([
-        ...(existingTarget?.block_id ?? []),
-        ...options.blockIds.map(id => formatUuid(extractId(id))),
-    ]));
-    if (blockIds.length === 0) {
-        // When a positional was given, pull already ran and recorded the data
-        // source — that's useful on its own (e.g. for a view ID where no
-        // custom_block is associated yet). Exit cleanly so init doesn't bail
-        // the scaffold; the user wires a block later with --block.
-        if (options.idOrUrl) {
-            if (!options.jsonOutput) {
-                console.log("\nData source recorded. Wire a custom block later with `ncblock connect --block <block-id>`.\n");
-            }
-            return;
-        }
-        console.error("Error: no blocks to connect — pass --block <id>, or run 'ncblock connect --block <id>' to add one to target.json.\n");
-        process.exit(1);
-    }
-    const { manifest } = loadManifest(options.manifest);
-    const manifestKeys = Object.keys(manifest.dataSources ?? {});
-    const unknown = Object.keys(bindings).filter(k => !manifestKeys.includes(k));
-    if (unknown.length > 0) {
-        console.error(`Error: binding key(s) not declared in the manifest: ${unknown.join(", ")}\n`);
-        console.error(`Manifest keys: ${manifestKeys.join(", ") || "(none)"}. Add the key to custom_blocks.json or fix the --bind key.`);
-        process.exit(1);
-    }
-    const resolvedBindings = {};
-    for (const [key, dataSourceId] of Object.entries(bindings)) {
-        const props = manifest.dataSources[key]?.properties ?? {};
-        const property_ids_by_key = Object.keys(props).length > 0
-            ? resolvePropertyIdsByKey({
-                dataSourceId,
-                manifestKey: key,
-                manifestProps: props,
-            })
-            : {};
-        resolvedBindings[key] = {
-            data_source_id: formatUuid(extractId(dataSourceId)),
-            property_ids_by_key,
-        };
-    }
-    const merged = mergeTarget(existingTarget, {
-        env: options.env,
-        block_id: blockIds,
-        data_sources: resolvedBindings,
-    });
-    const mappings = targetToMappings(merged.data_sources);
-    if (options.dryRun) {
-        emitDryRun(options.jsonOutput, {
-            action: "connect",
-            target: merged,
-            block_patches: blockIds.map(id => ({
-                block_id: id,
-                data_sources: mappings,
-            })),
-        });
-        return;
-    }
-    writeTarget(merged);
-    if (!options.jsonOutput) {
-        console.log(`\n✓ Wrote .notion/target.json`);
-    }
-    for (const id of blockIds) {
-        patchBlock(id, mappings, options.jsonOutput);
-    }
-    if (options.jsonOutput) {
-        console.log(JSON.stringify({
-            action: "connect",
-            target: merged,
-            blocks_updated: blockIds,
-        }, null, "\t"));
-    }
-}