@notionhq/custom-blocks 0.0.58

package/bin/cli/create.js

@@ -0,0 +1,106 @@
+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 *view* under a collection. 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 view under a collection isn't supported yet.\n`);
+            console.error("  The public API has no `custom` view type; the backend does the parent nesting. Create the view 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

@@ -0,0 +1,255 @@
+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"));
+    }
+}

package/bin/cli/deploy.js

@@ -0,0 +1,109 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { extractId, formatUuid } from "./ids.js";
+import { mergeTarget, readTarget, writeTarget } from "./target.js";
+/**
+ * The `ntn custom deploy` endpoint is feature-gated. When the gate is off,
+ * the API returns a 403 with `code: "restricted_resource"` and message
+ * `"Endpoint unavailable."` — but the user sees a raw blob and no actionable
+ * hint. Match any of the wire fingerprints so we can nudge regardless of
+ * which surface ntn echoed.
+ */
+const FEATURE_GATE_PATTERN = /restricted_resource|Endpoint unavailable|403\s*Forbidden/i;
+const FEATURE_GATE_HINT = "Please ensure that the feature gate custom_blocks is enabled.";
+/**
+ * Run `ntn custom deploy --block <id> <dist>` for each block. Block IDs come
+ * from --block flags if any, otherwise from `.notion/target.json`. On
+ * success, --block IDs (and --env) are merged back into target.json so it
+ * accumulates deploy targets across runs.
+ *
+ * This wrapper does NOT build — the package manager is the user's choice.
+ */
+export function deploy(options) {
+    const existingTarget = readTarget();
+    const flagBlockIds = (options.blockIds ?? []).map(id => formatUuid(extractId(id)));
+    const blockIds = flagBlockIds.length > 0 ? flagBlockIds : (existingTarget?.block_id ?? []);
+    if (blockIds.length === 0) {
+        console.error("Error: no blocks to deploy to — pass --block <id>, or run 'ncblock connect --block <id>' first to populate .notion/target.json.\n");
+        process.exit(1);
+    }
+    const distPath = resolvePath(process.cwd(), options.distPath);
+    if (!existsSync(distPath) || !statSync(distPath).isDirectory()) {
+        console.error(`Error: <dist-path> '${options.distPath}' does not exist or is not a directory.\n`);
+        console.error("Run your project's build script first (e.g. `npm run build`), then pass the resulting directory.");
+        process.exit(1);
+    }
+    const env = options.env ?? existingTarget?.env ?? "production";
+    if (options.dryRun) {
+        const payload = {
+            action: "deploy",
+            env,
+            dist_path: distPath,
+            commands: blockIds.map(id => buildDeployCommand(env, id, distPath)),
+        };
+        if (options.jsonOutput) {
+            console.log(JSON.stringify(payload, null, "\t"));
+        }
+        else {
+            console.log("\nDry run — would run:\n");
+            for (const cmd of payload.commands) {
+                console.log(`  ${cmd}`);
+            }
+            console.log("");
+        }
+        return;
+    }
+    const results = [];
+    for (const id of blockIds) {
+        const cmd = buildDeployCommand(env, id, distPath);
+        if (!options.jsonOutput) {
+            console.log(`\n→ ${cmd}\n`);
+        }
+        // Capture both streams (rather than inherit) so we can scan for the
+        // feature-gate fingerprint and print an actionable hint. We still echo
+        // everything back to the user so the live output looks the same.
+        const result = spawnSync(cmd, {
+            shell: true,
+            stdio: ["inherit", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        const childStdout = result.stdout ?? "";
+        const childStderr = result.stderr ?? "";
+        if (!options.jsonOutput) {
+            if (childStdout) {
+                process.stdout.write(childStdout);
+            }
+            if (childStderr) {
+                process.stderr.write(childStderr);
+            }
+        }
+        if (result.status !== 0) {
+            if (FEATURE_GATE_PATTERN.test(childStdout + childStderr)) {
+                process.stderr.write(`\n${FEATURE_GATE_HINT}\n\n`);
+            }
+            process.exit(result.status ?? 1);
+        }
+        results.push({ block_id: id, command: cmd });
+    }
+    // Record the successful deploy back into target.json so subsequent
+    // `connect` / `deploy` calls remember where this got shipped.
+    const merged = mergeTarget(existingTarget, {
+        env: options.env ?? existingTarget?.env,
+        block_id: blockIds,
+    });
+    writeTarget(merged);
+    if (options.jsonOutput) {
+        console.log(JSON.stringify({ action: "deploy", env, deployed: results, target: merged }, null, "\t"));
+    }
+}
+function buildDeployCommand(env, blockId, distPath) {
+    const prefix = env && env !== "production" ? `NOTION_KEYRING=0 ntn --env ${env}` : "ntn";
+    return `${prefix} custom deploy --block ${blockId} ${shellQuote(distPath)}`;
+}
+function shellQuote(s) {
+    if (!/[\s"'`$\\]/.test(s)) {
+        return s;
+    }
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/bin/cli/ids.js

@@ -0,0 +1,13 @@
+/** Extract a 32-char hex ID from a Notion URL or raw UUID. */
+export function extractId(input) {
+    const match = input.match(/([a-f0-9]{32}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})/);
+    if (match) {
+        return match[1].replace(/-/g, "");
+    }
+    return input.replace(/-/g, "");
+}
+/** Format a 32-char hex string as a dashed UUID. */
+export function formatUuid(raw) {
+    const h = raw.replace(/-/g, "");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}

package/bin/cli/ntn.js

@@ -0,0 +1,95 @@
+import { execSync } from "node:child_process";
+import { readTarget } from "./target.js";
+/**
+ * Resolve the active Notion env. An explicit `ENV=` always wins — that's the
+ * escape hatch for "I know what target.json says, but run this one against X".
+ * Otherwise target.json is the source of truth (every command merges into it,
+ * and it's checked in alongside the project).
+ */
+function resolveEnv() {
+    return process.env.ENV ?? readTarget()?.env;
+}
+/**
+ * Shell command we nudge users toward when an `ntn api` call fails in a way
+ * that suggests they're not logged in (404 on a known-public resource, missing
+ * data sources on a real database). Mirrors `buildCommand`'s env handling.
+ */
+export function loginHintCommand() {
+    const env = resolveEnv();
+    if (env && env !== "production") {
+        return `NOTION_KEYRING=0 ntn --env ${env} login`;
+    }
+    return "ntn login";
+}
+/**
+ * The `ntn` invocation prefix with correct ENV handling.
+ *
+ * - env is unset or "production" → `ntn` (no keyring override)
+ * - Any other env value          → `NOTION_KEYRING=0 ntn --env <env>`
+ */
+function ntnPrefix() {
+    const env = resolveEnv();
+    if (env && env !== "production") {
+        return `NOTION_KEYRING=0 ntn --env ${env}`;
+    }
+    return "ntn";
+}
+/**
+ * Build the `ntn api` command with correct ENV handling.
+ *
+ * - env is unset or "production" → `ntn api <path>` (no keyring override)
+ * - Any other env value          → `NOTION_KEYRING=0 ntn --env <env> api <path>`
+ */
+function buildCommand(apiPath) {
+    return `${ntnPrefix()} api ${apiPath}`;
+}
+/**
+ * Call `ntn api <path>` and return the parsed JSON response.
+ * Throws on non-zero exit or invalid JSON.
+ */
+export function ntnApi(apiPath) {
+    const cmd = buildCommand(apiPath);
+    return run(cmd, apiPath);
+}
+/**
+ * Call `ntn api -X PATCH <path> -d <json>` and return the parsed JSON response.
+ * Throws on non-zero exit or invalid JSON.
+ */
+export function ntnApiPatch(apiPath, body) {
+    const base = buildCommand(apiPath);
+    const cmd = `${base} -X PATCH -d ${shellEscape(JSON.stringify(body))}`;
+    return run(cmd, apiPath);
+}
+/**
+ * Call `ntn api -X POST <path> -d <json>` and return the parsed JSON response.
+ * Throws on non-zero exit or invalid JSON.
+ */
+export function ntnApiPost(apiPath, body) {
+    const base = buildCommand(apiPath);
+    const cmd = `${base} -X POST -d ${shellEscape(JSON.stringify(body))}`;
+    return run(cmd, apiPath);
+}
+/**
+ * Call `ntn workers capabilities list --json` and return the parsed JSON.
+ * Throws on non-zero exit or invalid JSON. Reads the worker ID from the local
+ * workers.json (same as the bare `ntn` command would).
+ */
+export function ntnWorkersCapabilities() {
+    const cmd = `${ntnPrefix()} workers capabilities list --json`;
+    return run(cmd, "workers capabilities list");
+}
+function shellEscape(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function run(cmd, label) {
+    try {
+        const output = execSync(cmd, { encoding: "utf-8", stdio: "pipe" });
+        return JSON.parse(output);
+    }
+    catch (error) {
+        const stderr = error instanceof Error && "stderr" in error
+            ? error.stderr
+            : "";
+        throw new Error(`ntn api ${label} failed${stderr ? `:\n${stderr.toString().trim()}` : ""}`);
+    }
+}

package/bin/cli/pullData.js

@@ -0,0 +1,76 @@
+import { writeFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { extractId, formatUuid } from "./ids.js";
+import { loginHintCommand, ntnApi, ntnApiPost } from "./ntn.js";
+const DEFAULT_LIMIT = 25;
+// The public data source query endpoint caps page_size at 100.
+const MAX_PAGE_SIZE = 100;
+function is404(error) {
+    return error instanceof Error && error.message.includes("404");
+}
+function plainText(items) {
+    if (!items?.length) {
+        return "Data source";
+    }
+    return items.map(t => t.plain_text ?? "").join("") || "Data source";
+}
+/**
+ * Resolve an ID/URL to a data source ID. Tries `/v1/databases/<id>` first
+ * (walks to its first data source), falling back to treating the ID as a data
+ * source directly. Mirrors the resolution `pullManifest`/`classifyId` use.
+ */
+function resolveDataSourceId(uuid) {
+    try {
+        console.error(`  Resolving database ${uuid}…`);
+        const db = ntnApi(`/v1/databases/${uuid}`);
+        if (db.object === "database") {
+            if (!db.data_sources?.length) {
+                throw new Error(`Database ${uuid} has no data sources. Confirm you're logged in to the right workspace with \`${loginHintCommand()}\`.`);
+            }
+            return formatUuid(db.data_sources[0].id);
+        }
+    }
+    catch (error) {
+        if (!is404(error)) {
+            throw error;
+        }
+    }
+    // Not a database — assume it already points at a data source. We don't GET
+    // it here; the schema fetch below will 404 clearly if it isn't one.
+    return uuid;
+}
+/**
+ * Resolve an ID/URL to a data source, then emit its property schema plus the
+ * first N rows as JSON. JSON goes to stdout (pipeable) unless `--out` is set;
+ * progress chatter goes to stderr so it never pollutes the payload.
+ */
+export function pullData(options) {
+    const uuid = formatUuid(extractId(options.idOrUrl));
+    const limit = Math.min(Math.max(1, options.limit ?? DEFAULT_LIMIT), MAX_PAGE_SIZE);
+    console.error(`\nResolving ${options.idOrUrl}…`);
+    const dataSourceId = resolveDataSourceId(uuid);
+    console.error(`  Fetching schema for data source ${dataSourceId}…`);
+    const schema = ntnApi(`/v1/data_sources/${dataSourceId}`);
+    const properties = schema.properties ?? {};
+    console.error(`  Querying ${limit} row(s)…`);
+    const query = ntnApiPost(`/v1/data_sources/${dataSourceId}/query`, {
+        page_size: limit,
+    });
+    const rows = query.results ?? [];
+    const payload = {
+        data_source_id: dataSourceId,
+        name: plainText(schema.title),
+        properties,
+        row_count: rows.length,
+        has_more: query.has_more ?? false,
+        rows,
+    };
+    const json = JSON.stringify(payload, null, "\t") + "\n";
+    if (options.out) {
+        const outPath = resolvePath(process.cwd(), options.out);
+        writeFileSync(outPath, json);
+        console.error(`\n✓ Wrote ${rows.length} row(s) from "${payload.name}" to ${options.out}\n`);
+        return;
+    }
+    process.stdout.write(json);
+}