@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/register-external-imports.js

@@ -0,0 +1,293 @@
+import { readPositiveInt } from "../../cli-values.js";
+import { readPositiveNumber } from "../../command-support.js";
+import { addContractFlags, readContractFlags } from "../../contract-flags.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { PIPEDRIVE_CATALOG_QUERY_CONTRACT, pipedriveCatalogQueryParams } from "@oxygen/shared/contracts/pipedrive-catalog";
+import { Command } from "commander";
+export function registerExternalImports({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(new Command("sources")
+        .description("List every way a table can start — imports, company/people/signal sources, webhooks, functions — with the provider count and per-row credit estimate behind each. Free; nothing is called or written. The same catalog the web New table picker shows.")
+        .option("--group <group>", "Only one group: Companies, People, \"Professional Network\" (or linkedin), Imports, CRM, Signals, or Tables.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables sources", options, () => {
+            const params = new URLSearchParams();
+            const group = readOption(options.group);
+            if (group)
+                params.set("group", group);
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/tables/sources${qs}`);
+        });
+    }));
+    tablesCommand.addCommand(new Command("records")
+        .description("Copy a Records object or saved view into a working Table, once or kept in sync. One-way: Records stay unchanged, the Table is keyed by record_id, cells edited in the Table are kept, and records that leave the source stay as rows with in_records=false.")
+        .addCommand(new Command("import")
+        .description("Create a Table from a Records object or saved view. --dry-run counts the records and lists the columns without creating anything. --refresh sync also arms a schedule (a Workflow you can pause) that repeats the copy. The copy costs 0 credits and calls no provider; each scheduled sync bills one workflow step (credits_per_scheduled_sync).")
+        .requiredOption("--object <slug>", "Records object slug, such as companies, people or deals (`crm objects`).")
+        .option("--view <id|name>", "Saved view on that object, by id or exact name (`tables views list <object table>`). Omit for every record.")
+        .option("--name <table>", "Name for the new Table. Defaults to the object and view name.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--refresh <once|sync>", "once (default) copies now; sync also keeps it in sync (needs --approved).")
+        .option("--every <cadence>", "With --refresh sync: hourly, every_6h, daily@<hour> or weekly@<day><hour> (UTC). Default daily@6.")
+        .option("--dry-run", "Preview without creating the Table.")
+        .option("--approved", "Approve the standing per-sync charge that --refresh sync arms.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables records import", options, () => requestOxygen("/api/cli/tables/records-import", {
+            method: "POST",
+            body: {
+                object: options.object,
+                ...(readOption(options.view) ? { view: readOption(options.view) } : {}),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                ...(readOption(options.refresh) ? { refresh: readOption(options.refresh) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("sync")
+        .description("Copy a Records-imported Table's source again now: new records are added, changed cells updated, edited cells kept, and departed records marked in_records=false (they flip back if they return). Without --refresh the schedule stays as it is; --refresh sync --approved arms or retimes it, --refresh once removes it. preserved_cells counts copied-field cells left as someone edited them in the Table; columns you added are never touched and not counted. Running it now costs 0 credits; each scheduled sync bills one workflow step (credits_per_scheduled_sync in an import dry run).")
+        .argument("<table>", "Table id, slug or URL.")
+        .option("--refresh <once|sync>", "Omit to keep the schedule; sync (with --approved) arms or retimes it; once removes it.")
+        .option("--every <cadence>", "With --refresh sync: hourly, every_6h, daily@<hour> or weekly@<day><hour> (UTC). Default daily@6.")
+        .option("--dry-run", "Count what would change without writing.")
+        .option("--approved", "Approve the standing per-sync charge that --refresh sync arms.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables records sync", options, () => requestOxygen("/api/cli/tables/records-sync", {
+            method: "POST",
+            body: {
+                table,
+                ...(readOption(options.refresh) ? { refresh: readOption(options.refresh) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Show a Records-imported Table's source object and view, the last sync's counts and its schedule. Read-only, 0 credits.")
+        .argument("<table>", "Table id, slug or URL.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables records status", options, () => requestOxygen(`/api/cli/tables/records-sync?table=${encodeURIComponent(table)}`));
+    })));
+    tablesCommand.addCommand(new Command("hubspot")
+        .description("Import HubSpot contacts or companies into a new table or Records, optionally from a saved list and with do-not-contact suppression.")
+        .addCommand(new Command("lists")
+        .description("List the connected portal's saved contact/company segments and readable identity properties. Reads definitions only; no memberships, rows, or writes. Free — 0 Oxygen credits, uses your HubSpot API quota.")
+        .option("--query <text>", "Optional list-name search.")
+        .option("--connection <id>", "HubSpot connection id; defaults to the first connected account.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables hubspot lists", options, () => {
+            const params = new URLSearchParams();
+            const query = readOption(options.query);
+            if (query)
+                params.set("query", query);
+            const connection = readOption(options.connection);
+            if (connection)
+                params.set("connection_id", connection);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tables/hubspot-import${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Preview or import HubSpot contacts/companies into a new table or Records. Named do-not-contact lists must synchronize before any import. Nothing is enrolled or sent. Live requires the exact dry-run fingerprint and approval.")
+        .option("--list <id>", "HubSpot saved-list id. Omit with --object to import all records; discover ids with `oxygen tables hubspot lists`.")
+        .option("--object <object>", "HubSpot object: contacts or companies. Required without --list; defaults to contacts for a saved list.")
+        .option("--destination <destination>", "Import into table (default) or records.")
+        .option("--connection <id>", "HubSpot connection id; defaults to the first connected account.")
+        .option("--sample", "Read up to 50 real records during the dry-run preview; uses HubSpot API quota and makes no writes.")
+        .option("--dnc-list <id>", "HubSpot contact-list id to suppress into do-not-contact before importing.")
+        .option("--company-dnc-list <id>", "Optional HubSpot company-list id to suppress organization-wide.")
+        .option("--no-dnc", "Import without suppressing anything. Required if you pass no --dnc-list, so an unsuppressed import is never accidental.")
+        .option("--name <table>", "Display name for the new table.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--contact-linkedin-property <name>", "Optional contact property holding a public LinkedIn /in/ URL.")
+        .option("--contact-company-domain-property <name>", "Optional contact property copied to company_domain.")
+        .option("--contact-company-linkedin-property <name>", "Optional contact property copied to company_linkedin_url.")
+        .option("--company-domain-property <name>", "Company domain property (default domain).", "domain")
+        .option("--company-linkedin-property <name>", "Optional company LinkedIn URL property.")
+        .option("--contact-properties <list>", "Comma-separated extra HubSpot contact properties to hydrate (max 50).")
+        .option("--max-records-per-list <n>", "Optional record limit; omit to import all selected records.")
+        .option("--max-credits <n>", "Hard credits cap per delivery.", "10")
+        .option("--once", "Import once instead of refreshing on a schedule.")
+        .option("--cron <expression>", "Refresh schedule; default every 15 minutes.")
+        .option("--timezone <iana>", "Schedule timezone; default UTC.")
+        .option("--reviewed-fingerprint <hash>", "Exact dry-run fingerprint, required for live.")
+        .option("--idempotency-key <key>", "Optional first-run idempotency key.")
+        .option("--live", "Create the import and queue the first durable run.")
+        .option("--approved", "Approve the reviewed reads, DNC writes, and destination upserts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables hubspot import", options, () => {
+            const list = readOption(options.list);
+            const object = readOption(options.object);
+            const destination = readOption(options.destination);
+            if (!list && !object)
+                throw new OxygenError("invalid_request", "Pass --list or --object contacts|companies to select what to import.", { exitCode: 1 });
+            if (object && object !== "contacts" && object !== "companies")
+                throw new OxygenError("invalid_request", "--object must be contacts or companies.", { exitCode: 1 });
+            if (destination && destination !== "table" && destination !== "records")
+                throw new OxygenError("invalid_request", "--destination must be table or records.", { exitCode: 1 });
+            const dncList = readOption(options.dncList);
+            const companyDncList = readOption(options.companyDncList);
+            // Commander maps `--no-dnc` to `dnc: false`; the default is
+            // `true`, so an unset flag is indistinguishable from an opt-in.
+            // Requiring one of the two means an import that suppresses
+            // nothing is always something the operator typed, which is the
+            // same guarantee the web lane gets from its preview fingerprint.
+            const optedOut = options.dnc === false;
+            if (!dncList && !companyDncList && !optedOut) {
+                // invalid_request, not a bare Error: handleAsyncAction reports
+                // an uncoded throw as `unexpected_error`, which tells a calling
+                // agent that OXYGEN broke when the caller simply omitted a flag.
+                throw new OxygenError("invalid_request", "Pass --dnc-list (and/or --company-dnc-list) to suppress a HubSpot list, or --no-dnc to import without suppressing anything. Run `oxygen tables hubspot lists` to see the ids your portal exposes.", { exitCode: 1 });
+            }
+            if (optedOut && (dncList || companyDncList)) {
+                throw new OxygenError("invalid_request", "--no-dnc cannot be combined with --dnc-list or --company-dnc-list.", { exitCode: 1 });
+            }
+            const maxRecords = readPositiveInt(options.maxRecordsPerList);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (options.maxRecordsPerList !== undefined && (maxRecords === undefined || !Number.isSafeInteger(maxRecords)))
+                throw new OxygenError("invalid_request", "--max-records-per-list must be a positive integer.", { exitCode: 1 });
+            if (maxCredits === undefined)
+                throw new OxygenError("spend_cap_required", "--max-credits must be positive.", { exitCode: 1 });
+            const fingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !fingerprint)
+                throw new OxygenError("approval_required", "Live import requires --reviewed-fingerprint from the exact dry-run. Run the same command without --live first.", { exitCode: 1 });
+            const contactProperties = readOption(options.contactProperties)
+                ?.split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean) ?? [];
+            return requestOxygen("/api/cli/tables/hubspot-import", {
+                method: "POST",
+                body: {
+                    lead_list_id: list ?? null,
+                    ...(object ? { object } : {}),
+                    ...(destination ? { destination } : {}),
+                    ...(readOption(options.connection) ? { connection_id: readOption(options.connection) } : {}),
+                    ...(options.sample ? { sample: true } : {}),
+                    dnc_list_id: dncList ?? null,
+                    company_dnc_list_id: companyDncList ?? null,
+                    table_name: readOption(options.name) ?? null,
+                    project: readOption(options.project) ?? null,
+                    contact_linkedin_property: readOption(options.contactLinkedinProperty) ?? null,
+                    contact_company_domain_property: readOption(options.contactCompanyDomainProperty) ?? null,
+                    contact_company_linkedin_property: readOption(options.contactCompanyLinkedinProperty) ?? null,
+                    company_domain_property: readOption(options.companyDomainProperty) ?? "domain",
+                    company_linkedin_property: readOption(options.companyLinkedinProperty) ?? null,
+                    contact_properties: contactProperties,
+                    max_records_per_list: maxRecords ?? null,
+                    refresh: options.once ? "once" : "scheduled",
+                    cron: readOption(options.cron) ?? undefined,
+                    timezone: readOption(options.timezone) ?? undefined,
+                    max_credits: maxCredits,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(fingerprint ? { reviewed_fingerprint: fingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                },
+            });
+        });
+    })));
+    tablesCommand.addCommand(new Command("pipedrive")
+        .description("Import a Pipedrive saved people filter into a new Oxygen table, optionally suppressing a Pipedrive do-not-contact filter first. Connect Pipedrive with an API token first: `oxygen integrations connect pipedrive --api-key <token>`.")
+        .addCommand(addContractFlags(new Command("filters")
+        .description("Read connected Pipedrive saved filters and custom-field definitions; no people imported. Four BYOK fees may apply. Use --approved with --max-credits to authorize this read; refusal returns the required cap without provider calls."), PIPEDRIVE_CATALOG_QUERY_CONTRACT, {
+        query: { valueName: "<text>" },
+        approved: { noNegate: true },
+        max_credits: { valueName: "<n>" },
+    })
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables pipedrive filters", options, () => {
+            const params = pipedriveCatalogQueryParams(readContractFlags(options, PIPEDRIVE_CATALOG_QUERY_CONTRACT, { approved: { noNegate: true } }));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tables/pipedrive-import${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Preview or run a Pipedrive saved people filter into a NEW table. Any do-not-contact filter you name is synchronized first and no row lands unless it fully succeeds. Nothing is ever enrolled or sent. Live requires the exact dry-run fingerprint and approval.")
+        .requiredOption("--filter <id>", "Pipedrive people-filter id whose persons become rows. Run `oxygen tables pipedrive filters` to see the ids your account exposes.")
+        .option("--dnc-filter <id>", "Pipedrive people-filter id to suppress into do-not-contact before importing (a filter on Marketing status = Unsubscribed is the usual choice).")
+        .option("--org-dnc-filter <id>", "Optional Pipedrive organization-filter id to suppress organization-wide.")
+        .option("--no-dnc", "Import without suppressing anything. Required if you pass no --dnc-filter, so an unsuppressed import is never accidental.")
+        .option("--name <table>", "Display name for the new table.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--person-linkedin-field <key>", "Optional person field key holding a public LinkedIn /in/ URL (custom keys are 40-character hex; see `tables pipedrive filters`).")
+        .option("--person-title-field <key>", "Optional person field key copied to title. Pipedrive has no native job-title field.")
+        .option("--org-domain-field <key>", "Optional organization field key holding the website or domain. Pipedrive has no native domain field; never inferred from email.")
+        .option("--org-linkedin-field <key>", "Optional organization field key holding its LinkedIn company page.")
+        .option("--person-fields <list>", "Comma-separated extra Pipedrive person field keys to hydrate into pipedrive_fields (max 15).")
+        .option("--no-hydrate-organizations", "Skip reading each person's organization; company columns stay empty.")
+        .option("--max-records-per-filter <n>", "Complete-snapshot cap (1-5000), enforced while the filter is read.", "5000")
+        .option("--max-credits <n>", "Hard credits cap per delivery.", "10")
+        .option("--once", "Import once instead of refreshing on a schedule.")
+        .option("--cron <expression>", "Refresh schedule; default every 15 minutes.")
+        .option("--timezone <iana>", "Schedule timezone; default UTC.")
+        .option("--reviewed-fingerprint <hash>", "Exact dry-run fingerprint, required for live.")
+        .option("--idempotency-key <key>", "Optional first-run idempotency key.")
+        .option("--live", "Create the table and queue the first durable run.")
+        .option("--approved", "Approve the reviewed bounded reads, DNC writes, and table upserts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables pipedrive import", options, () => {
+            const dncFilter = readOption(options.dncFilter);
+            const orgDncFilter = readOption(options.orgDncFilter);
+            // Same affirmative contract as `tables hubspot import`: an import
+            // that suppresses nothing is always something the operator typed.
+            const optedOut = options.dnc === false;
+            if (!dncFilter && !orgDncFilter && !optedOut) {
+                throw new OxygenError("invalid_request", "Pass --dnc-filter (and/or --org-dnc-filter) to suppress a Pipedrive filter, or --no-dnc to import without suppressing anything. Run `oxygen tables pipedrive filters` to see the ids your account exposes.", { exitCode: 1 });
+            }
+            if (optedOut && (dncFilter || orgDncFilter)) {
+                throw new OxygenError("invalid_request", "--no-dnc cannot be combined with --dnc-filter or --org-dnc-filter.", { exitCode: 1 });
+            }
+            const maxRecords = readPositiveInt(options.maxRecordsPerFilter);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxRecords === undefined || maxRecords > 5000)
+                throw new OxygenError("invalid_request", "--max-records-per-filter must be between 1 and 5000.", { exitCode: 1 });
+            if (maxCredits === undefined)
+                throw new OxygenError("spend_cap_required", "--max-credits must be positive.", { exitCode: 1 });
+            const fingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !fingerprint)
+                throw new OxygenError("approval_required", "Live import requires --reviewed-fingerprint from the exact dry-run. Run the same command without --live first.", { exitCode: 1 });
+            const personFields = readOption(options.personFields)
+                ?.split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean) ?? [];
+            const hydrateOrganizations = options.hydrateOrganizations !== false;
+            return requestOxygen("/api/cli/tables/pipedrive-import", {
+                method: "POST",
+                body: {
+                    filter_id: readOption(options.filter),
+                    dnc_filter_id: dncFilter ?? null,
+                    org_dnc_filter_id: orgDncFilter ?? null,
+                    table_name: readOption(options.name) ?? null,
+                    project: readOption(options.project) ?? null,
+                    person_linkedin_field: readOption(options.personLinkedinField) ?? null,
+                    person_title_field: readOption(options.personTitleField) ?? null,
+                    org_domain_field: readOption(options.orgDomainField) ?? null,
+                    org_linkedin_field: readOption(options.orgLinkedinField) ?? null,
+                    person_fields: personFields,
+                    hydrate_organizations: hydrateOrganizations,
+                    max_records_per_filter: maxRecords,
+                    refresh: options.once ? "once" : "scheduled",
+                    cron: readOption(options.cron) ?? undefined,
+                    timezone: readOption(options.timezone) ?? undefined,
+                    max_credits: maxCredits,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(fingerprint ? { reviewed_fingerprint: fingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/command-families/tables/register-files.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerFiles({ tablesCommand, handleAsyncAction, binaryName }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-files.js

@@ -0,0 +1,72 @@
+import { emitCliFailure } from "../../cli-output.js";
+import { Command } from "commander";
+import { IMPORT_FILE_LIMIT_HELP, LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD, formatJsonBodyLimit } from "./import-values.js";
+import { importRows } from "./imports.js";
+import { exportRows, exportTableBundle } from "./bundle-export.js";
+import { importTableBundle } from "./bundle-import.js";
+export function registerFiles({ tablesCommand, handleAsyncAction, binaryName }) {
+    tablesCommand.addCommand(new Command("import")
+        .description(`Import JSON, JSONL, CSV, or XLSX rows into a workspace table. The table write is free — 0 Oxygen credits. Files over ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows load durably in the background: the command returns a queued envelope and rows keep landing after it exits, so wait with the printed 'table-ingestions wait <id>' before reading row counts. ${IMPORT_FILE_LIMIT_HELP}`)
+        .argument("[table]", "Table id or slug. Omit when using --create.")
+        .option("--file <path>", "Input file path. Pass this or --url.")
+        .option("--url <https-link>", "Public link to fetch instead of a local file: a CSV, TSV, JSON, JSONL or XLSX file, or a Google Sheet shared with anyone-with-the-link or published to the web. Fetched server-side, up to 10 MB, 0 credits.")
+        .option("--preview", "With --url: fetch and show the columns, a row sample and the row count without creating or writing anything.")
+        .option("--format <format>", "json, jsonl, csv, or xlsx. Defaults from file extension.")
+        .option("--sheet <name>", "Worksheet name for XLSX imports. Defaults to the first sheet.")
+        .option("--create <name>", "Create a new table with columns inferred from the file before importing.")
+        .option("--project <project>", "Project id or slug for --create. Defaults to General.")
+        .option("--upsert-key <key>", "Column key used to upsert instead of inserting.")
+        .option("--skip-blank-cells", "Leave a row's existing value where the file's cell is blank instead of clearing it, so a partial update needs one file.")
+        .option("--batch-size <n>", `Requested rows per import chunk, not a limit on the file. Defaults to 500; values up to 5000 are accepted, but Oxygen splits writes to at most 500 rows (and smaller for wide rows, about ${formatJsonBodyLimit()} of JSON per request) so they fit request and worker lease budgets.`)
+        .option("--background", "Enqueue durable import chunks for the background worker.")
+        .option("--sync", `Force foreground import even for files above ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows. That threshold picks foreground vs background; it does not cap how many rows a file may hold.`)
+        .option("--max-concurrency <n>", "Maximum concurrent import chunks for background mode. Defaults to 5.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables import", options, () => importRows(table, options));
+    }));
+    tablesCommand.addCommand(new Command("export")
+        .description("Export workspace table rows as JSON, JSONL, CSV, or a human-readable table. Rows only, capped at 1000; to copy a whole table including its columns and every row, use `tables export-bundle`.")
+        .argument("<table>", "Table id or slug.")
+        .option("--format <format>", "json, jsonl, csv, or table. Defaults to json. Use table for a typed, human-readable rendering with thousands grouping.")
+        .option("--output <path>", "Write export content to a file.")
+        .option("--limit <n>", "Maximum rows to export. Defaults to 100; hard cap is 1000.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        if (!options.json && !options.output && options.format?.trim().toLowerCase() === "table") {
+            // The human-readable table itself, not a JSON object holding it as one
+            // escaped string (blind user evals, 2026-09-30). --json keeps the envelope.
+            try {
+                const { content } = await exportRows(table, options);
+                const text = typeof content === "string" ? content : "";
+                process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+            }
+            catch (error) {
+                emitCliFailure("tables export", error);
+            }
+            return;
+        }
+        await handleAsyncAction("tables export", options, () => exportRows(table, options));
+    }));
+    tablesCommand.addCommand(new Command("export-bundle")
+        .description("Export a workspace table as a portable bundle (schema + every row) for cross-environment / cross-org copies. Effect: reads the table and writes only a local file — 0 credits, nothing changes in the workspace. With --output the bundle streams to the file one row per line, so a table of any size exports; without it the whole bundle prints as one JSON document, which only fits a small table.")
+        .argument("<table>", "Table id or slug to export.")
+        .option("--output <path>", "Write the bundle to this file as line-delimited JSON: a header line with the table and columns, then one {\"row\":{…}} line per row carrying every column value plus the source _row_id, _created_at and _updated_at (import-bundle drops those three), then a {\"totals\":{…}} trailer. Streams, so memory stays flat at any row count. Defaults to stdout as a single JSON document.")
+        .option("--page-size <n>", "Rows per cursor-paginated request. Defaults to 500; hard cap is 1000.")
+        .option("--json", "Print a JSON envelope (omit row payload — use --output to keep the rows).")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables export-bundle", options, () => exportTableBundle(table, options));
+    }));
+    tablesCommand.addCommand(new Command("import-bundle")
+        .description("Recreate a workspace table from an export-bundle file in this org. Effect: creates one new table in this workspace and inserts every bundled row — 0 credits, no provider calls, nothing runs. Reads both bundle formats and streams a line-delimited bundle row by row, so a multi-GB file imports without loading into memory. Restores columns (incl. enrichment/tool definitions). Pass --key to make the import idempotent (re-runnable), and --into to resume a failed import into the table it already created.")
+        .requiredOption("--file <path>", "Bundle JSON file produced by `tables export-bundle`.")
+        .option("--name <name>", "Override the table display name. Defaults to the bundle's table name. Ignored with --into.")
+        .option("--project <project>", "Project id or slug for the new table. Defaults to General. Ignored with --into.")
+        .option("--into <table>", "Resume into an existing table (id or slug) instead of creating a new one. Requires --key. Use the table id printed by the failed run.")
+        .option("--key <column>", "Upsert key column. When set, rows are matched by this key instead of blindly inserted, so re-running the import is idempotent (no duplicates). Required with --into.")
+        .option("--batch-size <n>", "Requested rows per write group. Defaults to 500; values up to 5000 are accepted and split into safe writes of at most 500 rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables import-bundle", options, () => importTableBundle(options, binaryName));
+    }));
+}

package/dist/command-families/tables/register-followers.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerFollowers({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-followers.js

@@ -0,0 +1,73 @@
+import { readPositiveNumber } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+export function registerFollowers({ tablesCommand, handleAsyncAction }) {
+    const followersCommand = tablesCommand.command("followers")
+        .description("Order a LinkedIn company page's followers as a table of leads — a competitor's audience. `check` is free and quotes the order; fee-positive own-key previews leave the follower count unknown. `order` places it. The order is fulfilled by ScrapeLi, so the table is created immediately and its rows land later; there is no published delivery time.");
+    followersCommand.command("check")
+        .description("Free order preview. Managed quotes the follower cost; your own key quotes placement and later check fees, with a total ceiling you choose. No spend or table; `orderable: false` means the order is unavailable.")
+        .requiredOption("--company <url>", "LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot.")
+        .option("--records <n>", "How many followers to price. Minimum 100; defaults to 1000.")
+        .option("--package <package>", "Basic (default): profile, job title, location, employer. Advanced (10x the credits): also a verified work email and region.")
+        .option("--credential-mode <mode>", "managed (default): Oxygen credits. user_api_key: your saved ScrapeLi key, billed by ScrapeLi, plus Oxygen placement/recovery platform fees.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers check", options, () => requestOxygen("/api/cli/tables/linkedin-company-followers", {
+            method: "POST",
+            body: {
+                action: "preview",
+                company_url: readOption(options.company),
+                ...(options.records !== undefined ? { records: readPositiveNumber(options.records) } : {}),
+                ...(readOption(options.package) ? { package: readOption(options.package) } : {}),
+                ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+            },
+        }));
+    });
+    followersCommand.command("order")
+        .description("Place the follower order after checking it. Requires --approved and --max-credits: managed uses the quoted order cost; own-key uses a TOTAL placement/recovery platform-fee ceiling. A ceiling equal to placement cannot recover rows. Budget exhaustion lands no partial rows; refetched pages consume the same ceiling. Creates the Table now; rows arrive later.")
+        .requiredOption("--approved", "Approve this purchase. Required, as on every command that buys data.")
+        .requiredOption("--company <url>", "LinkedIn company page URL whose followers to order.")
+        .option("--max-credits <credits>", "Approved order ceiling. On your key, TOTAL platform fees for placement and later checks; exhaustion stops recovery. At least the quoted placement fee. ScrapeLi charges separately.")
+        .requiredOption("--request-id <uuid>", "One stable UUID and identical order payload for retries. A new ID can buy the audience again.")
+        .option("--records <n>", "How many followers to buy. Minimum 100; defaults to 1000.")
+        .option("--package <package>", "Basic (default) or Advanced (10x the credits; adds a verified work email and region).")
+        .option("--name <name>", "Table name. Defaults to \"<Company> Followers\".")
+        .option("--project <project>", "Project id or slug; defaults to General.")
+        .option("--credential-mode <mode>", "managed (default): Oxygen credits. user_api_key: your saved ScrapeLi key, billed by ScrapeLi, plus Oxygen placement/recovery platform fees.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers order", options, () => requestOxygen("/api/cli/tables/linkedin-company-followers", {
+            method: "POST",
+            body: {
+                action: "create",
+                approved: true,
+                company_url: readOption(options.company),
+                ...(options.records !== undefined ? { records: readPositiveNumber(options.records) } : {}),
+                ...(readOption(options.package) ? { package: readOption(options.package) } : {}),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                ...(options.maxCredits !== undefined ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+                ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
+                ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+            },
+        }));
+    });
+    followersCommand.command("status")
+        .description("Read a fee-budgeted own-key follower order's total fee ceiling, allocated attempts, recorded fees and recovery outcome by its original request ID, including interrupted setup. Optional --table-id verifies the saved Table binding. Recorded fees may settle later. Makes no provider call.")
+        .requiredOption("--request-id <uuid>", "Original order request ID.")
+        .option("--table-id <id>", "Optional saved Table ID; verifies the order belongs to that Table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers status", options, () => {
+            const requestId = readOption(options.requestId);
+            if (!requestId)
+                throw new OxygenError("invalid_input", "--request-id must be the original nonblank order request ID.", { exitCode: 2 });
+            const query = new URLSearchParams({ request_id: requestId });
+            const tableId = readOption(options.tableId);
+            if (tableId)
+                query.set("table_id", tableId);
+            return requestOxygen(`/api/cli/tables/linkedin-company-followers?${query}`, { method: "GET" });
+        });
+    });
+}

package/dist/command-families/tables/register-lifecycle.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerLifecycle({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-lifecycle.js

@@ -0,0 +1,114 @@
+import { readCsvOption, splitCommaList } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+export function registerLifecycle({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(new Command("rename")
+        .description("Rename a workspace table display name and slug.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--name <name>", "New table display name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables rename", options, () => requestOxygen("/api/cli/tables/rename", {
+            method: "POST",
+            body: { table, name: options.name },
+        }));
+    }));
+    tablesCommand.addCommand(new Command("tag")
+        .description("Replace a table's workspace tags (Tags primitive; \"\" clears). Tags link the table to sequences, wiki pages, and workflows carrying the same tag — browse with `oxygen tags get <tag>`.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--tags <csv>", "Comma-separated tags; \"\" clears them.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables tag", options, () => requestOxygen("/api/cli/tables/tags", {
+            method: "POST",
+            body: { table, tags: readCsvOption(options.tags) },
+        }));
+    }));
+    tablesCommand.addCommand(new Command("archive")
+        .description("Archive a workspace table without dropping physical data. Hides it indefinitely with no purge timer; for cleanup with a restorable deadline use `tables delete`.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables archive", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}`, {
+            method: "DELETE",
+        }));
+    }));
+    tablesCommand.addCommand(new Command("delete")
+        .description("Delete workspace tables: archives now and schedules the physical purge (default 14 days; restorable via `tables restore` until then). --now purges immediately and permanently — it previews and refuses without --yes. A table with a large history answers `purging` and finishes in the background. Free — 0 Oxygen credits.")
+        .argument("<tables...>", "Table ids or slugs.")
+        .option("--now", "Purge immediately instead of scheduling. Irreversible; single table only. A large table finishes in the background.")
+        .option("--yes", "Approve the immediate purge previewed by --now.")
+        .option("--purge-after <days>", "Days until the scheduled purge runs. Defaults to 14; 0 purges on the next background sweep (sweeps visit each workspace every few minutes).")
+        .option("--reason <text>", "Recorded with the delete for the audit trail.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tables, options) => {
+        await handleAsyncAction("tables delete", options, () => {
+            const purgeAfter = readOption(options.purgeAfter) ?? undefined;
+            const purgeAfterDays = purgeAfter === undefined ? undefined : Number.parseInt(purgeAfter, 10);
+            if (purgeAfterDays !== undefined && (!Number.isFinite(purgeAfterDays) || purgeAfterDays < 0)) {
+                throw new OxygenError("invalid_request", "--purge-after must be a non-negative number of days.", {
+                    exitCode: 2,
+                });
+            }
+            return requestOxygen("/api/cli/tables/delete", {
+                method: "POST",
+                body: {
+                    ...(tables.length === 1 ? { table: tables[0] } : { tables }),
+                    ...(options.now ? { now: true } : {}),
+                    ...(options.yes ? { approved: true } : {}),
+                    ...(purgeAfterDays !== undefined ? { purge_after_days: purgeAfterDays } : {}),
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            });
+        });
+    }));
+    tablesCommand.addCommand(new Command("restore")
+        .description("Restore an archived or delete-scheduled table: cancels the purge timer and reclaims its slug. A table whose purge has begun (lifecycle.purgeStartedAt) can no longer be restored.")
+        .argument("[table]", "Table id or slug (the pre-delete slug works).")
+        .option("--tables <refs>", "Restore a comma-separated batch; alternative to the table argument.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables restore", options, () => {
+            const refs = splitCommaList(options.tables);
+            if ((!table && refs.length === 0) || (table && refs.length > 0))
+                throw new OxygenError("invalid_selection", "Pass one table argument or --tables, not both.", { exitCode: 2 });
+            return requestOxygen("/api/cli/tables/restore", {
+                method: "POST",
+                body: { ...(options.tables !== undefined ? { tables: splitCommaList(options.tables) } : { table }) },
+            });
+        });
+    }));
+    tablesCommand.addCommand(new Command("move")
+        .description("Move one or more workspace tables into a project (folder) in one call. Rows, columns, runs, and provenance are preserved. Free; reverse it by moving the table back.")
+        .argument("<tables...>", "Table ids or slugs; several move together, each reported separately.")
+        .requiredOption("--project <project>", "Destination project id or slug (see `oxygen projects list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tables, options) => {
+        await handleAsyncAction("tables move", options, () => requestOxygen("/api/cli/tables/move", {
+            method: "POST",
+            body: {
+                ...(tables.length === 1 ? { table: tables[0] } : { tables }),
+                project: options.project,
+            },
+        }));
+    }));
+    tablesCommand.addCommand(new Command("recover-pending")
+        .description("Recover existing BetterContact email or phone requests and inspect terminal verification blockers; no new orders.")
+        .argument("<table>", "Table id or slug.")
+        .option("--max-items <n>", "Max pending cache rows to poll in this run. Defaults to 1000.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables recover-pending", options, () => {
+            const maxItems = options.maxItems ? Number.parseInt(options.maxItems, 10) : undefined;
+            return requestOxygen("/api/cli/tables/recover-pending", {
+                method: "POST",
+                body: {
+                    table,
+                    ...(Number.isFinite(maxItems) ? { max_items: maxItems } : {}),
+                },
+            });
+        });
+    }));
+}

package/dist/command-families/tables/register-reads.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerReads({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;