@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/egress.js

@@ -0,0 +1,130 @@
+import { readNonNegativeInt } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerEgressFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("egress")
+        .description("Native email egress: status, shared/dedicated IP inventory, the dedicated-IP add-on, policy assignments, and a fail-closed retired rotation shim.")
+        .addCommand(new Command("status")
+        .description("Show this workspace's configured native email routing, active IP, transport readiness, health counts, dedicated add-on, and one bounded page of the mailbox policy ledger. Configuration and readiness do not prove observed traffic. Native Gmail/Microsoft sends, reply reads and token refreshes are configured for the workspace email proxy; Zapmail-connected (Zapbox) mailboxes send through Zapmail. Read-only, 0 credits.")
+        .option("--assignment-offset <number>", "Continue the policy ledger from open_assignments_next_offset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const assignmentOffset = readNonNegativeInt(options.assignmentOffset);
+        const query = assignmentOffset === undefined
+            ? ""
+            : `?assignment_offset=${encodeURIComponent(String(assignmentOffset))}`;
+        await handleAsyncAction("egress status", options, () => requestOxygen(`/api/cli/egress${query}`));
+    }))
+        .addCommand(new Command("ips")
+        .description("List the configured shared email-proxy IP and this workspace's dedicated IP history. A configured address does not prove observed traffic; inspect readiness and verification fields with `egress status`. Read-only, 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress ips", options, () => requestOxygen("/api/cli/egress?view=ips"));
+    }))
+        .addCommand(new Command("dedicated")
+        .description("Dedicated native egress add-on (2,500 credits per 30-day period): one static IP only this workspace uses, which IT can allowlist; workspace tenant isolation and account safety, not a deliverability or inbox-placement lever. Preview the quote, order with `request --approved`, cancel with `cancel --approve`, or check status.")
+        .addCommand(new Command("request")
+        .description("Preview the dedicated native egress add-on (2,500 credits per 30-day period, $25 face value). With --approved, ORDER it: OXYGEN provisions one isolated email proxy plus one static egress IP for the workspace, captures the first period only after the proxy is ready, and debits the next 30 days later — not on the 1st. Every current inbox is assigned to that IP, every future inbox joins it automatically, and after the guarded handoff every native send, reply read and token refresh for the workspace's mailboxes uses that one IP, so IT can allowlist it in Microsoft Conditional Access or Google context-aware access. Recipients of Gmail API and Microsoft Graph sends still see Google/Microsoft relay IPs; a Microsoft mailbox on the SMTP transport may show the sending IP, shared or dedicated, in its headers. This is workspace tenant isolation and account safety, not a deliverability or inbox-placement lever. Without --approved nothing is ordered or charged. While native provisioning is unavailable, ordering fails closed and the preview says so.")
+        // --approved (not --approve): the credit-spending approval flag,
+        // which is also what derives spends_credits in the self-index.
+        .option("--approved", "Execute the order (a real recurring credit charge). Omit for a no-side-effect preview.")
+        // Deliberately NOT named like an approval flag: the self-index
+        // derives spends_credits from --approved/--max-credits/--budget-credits
+        // appearing in a command's flag strings, so an approval-shaped name
+        // here would mislabel every command that carries it.
+        .option("--move-existing", "Deprecated compatibility flag. Existing inboxes now move to the dedicated IP automatically, so old scripts may keep passing this safely.")
+        .option("--country <code>", "ISO 3166-1 alpha-2 country the dedicated IP should sit in (e.g. US, DE). Match it to where your mailboxes' owners plausibly sign in from — the IP's job is making the sign-in look ordinary, and an account that suddenly authenticates from another country is what gets it challenged. Omitted uses the default region. An unserviceable or out-of-stock country fails before anything is ordered or charged.")
+        .option("--idempotency-key <key>", "Stable key for safely retrying the same order after a timeout. Reuse the key shown in a timeout error; use a new key only for an intentionally new purchase.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const idempotencyKey = readOption(options.idempotencyKey);
+        await handleAsyncAction("egress dedicated request", options, () => requestOxygen("/api/cli/egress/dedicated", {
+            method: "POST",
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+            body: {
+                ...(options.approved ? { approve: true } : {}),
+                ...(options.moveExisting ? { move_existing: true } : {}),
+                ...(readOption(options.country) ? { country: readOption(options.country) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel the dedicated sending-IP add-on. Approval-gated: without --approve it previews. Cancellation takes effect at the END of the 30-day period already paid for: the dedicated IP remains active until then, and only at period end does it retire, the workspace returns to the shared email proxy, and credit billing stops. No refund, no early cutoff.")
+        .option("--approve", "Execute the cancellation. Omit for a no-side-effect preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress dedicated cancel", options, () => requestOxygen("/api/cli/egress/dedicated", {
+            method: "POST",
+            body: { cancel: true, ...(options.approve ? { approve: true } : {}) },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Show this org's dedicated sending-IP add-on state (status, quantity, activation, price). Read-only, 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress dedicated status", options, () => requestOxygen("/api/cli/egress/dedicated"));
+    })))
+        .addCommand(new Command("rotate")
+        .description("RETIRED compatibility command. Native egress is workspace-scoped, so OXYGEN cannot rotate one mailbox without violating the workspace's shared-or-one-dedicated routing contract. The API always fails closed with no provider call or change.")
+        .requiredOption("--mailbox <id>", "Mailbox id to rotate.")
+        .option("--vendor <vendor>", "Retired compatibility input; never used for a provider call.")
+        .option("--approve", "Retired compatibility flag; no rotation is executed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress rotate", options, () => requestOxygen("/api/cli/egress/rotate", {
+            method: "POST",
+            body: {
+                mailbox_id: readOption(options.mailbox),
+                ...(readOption(options.vendor) ? { vendor: readOption(options.vendor) } : {}),
+                ...(options.approve ? { approve: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("register")
+        .description("STAFF RECOVERY: register legacy/manual logical policy inventory for this environment. This does not configure native send transport; dedicated email proxies are created only by `egress dedicated request`. Secrets never pass here — --credential-ref names the Doppler family EGRESS_CRED_<REF>_USERNAME/_PASSWORD, set separately in Doppler.")
+        .requiredOption("--host <host>", "Proxy hostname or IP — bare, no scheme/port/credentials.")
+        .requiredOption("--port <port>", "Proxy port (1-65535).")
+        .requiredOption("--credential-ref <ref>", "Doppler credential-family name (A-Z, 0-9, _).")
+        .requiredOption("--vendor <vendor>", "Vendor slug for inventory provenance.")
+        .option("--protocol <protocol>", "Proxy protocol: http (default), https, or socks5.")
+        .option("--tier <tier>", "shared (default) or dedicated (requires --dedicated-org).")
+        .option("--dedicated-org <orgId>", "Organization id a dedicated-tier IP is reserved for.")
+        .option("--session-label <label>", "Optional vendor session/order label for provenance.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress register", options, () => requestOxygen("/api/cli/egress/register", {
+            method: "POST",
+            body: {
+                host: readOption(options.host),
+                port: Number(readOption(options.port)),
+                credential_ref: readOption(options.credentialRef),
+                vendor: readOption(options.vendor),
+                ...(readOption(options.protocol) ? { protocol: readOption(options.protocol) } : {}),
+                ...(readOption(options.tier) ? { tier: readOption(options.tier) } : {}),
+                ...(readOption(options.dedicatedOrg) ? { dedicated_organization_id: readOption(options.dedicatedOrg) } : {}),
+                ...(readOption(options.sessionLabel) ? { session_label: readOption(options.sessionLabel) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("assign")
+        .description("Converge mailbox policy assignments: managed/shared by default, or the workspace's dedicated IP for every current and future inbox once that add-on is active. Existing pins stay stable within their tier; --ip cannot override an active dedicated tier. Admin/owner role; no spend, 0 credits.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to assign.")
+        .option("--all", "Converge every sending mailbox to the workspace's current shared or dedicated tier.")
+        .option("--ip <egressIpId>", "Pin the targeted mailboxes to this egress IP id (must be active and org-visible).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("egress assign", options, () => {
+            const list = readOption(options.mailboxes);
+            const mailboxes = list ? list.split(",").map((entry) => entry.trim()).filter(Boolean) : [];
+            return requestOxygen("/api/cli/egress/assign", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(options.all ? { all: true } : {}),
+                    ...(readOption(options.ip) ? { egress_ip_id: readOption(options.ip) } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/commands/email.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerEmailFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/email.js

@@ -0,0 +1,49 @@
+import { readCsvOption } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function registerEmailFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("email")
+        .description("Ad-hoc email from the org's sending fleet: one-off sends with no sequence, enrollment, or contact sync. Zapbox-connected mailboxes send through Zapmail's API (no Google/Microsoft consent); BYOK — 0 Oxygen credits.")
+        .addCommand(new Command("send")
+        .description("Send ONE email right now. Without --approved, returns a preview naming the exact mailbox + transport. --from pins a mailbox; otherwise the pool's LRU rotation picks one.")
+        .requiredOption("--to <email>", "Recipient email address (exactly one).")
+        .requiredOption("--subject <text>", "Subject line.")
+        .option("--body <text>", "Plain-text body (sent verbatim, no templating).")
+        .option("--body-file <path>", "Read the body from a file instead of --body.")
+        .option("--html <html>", "Optional HTML body — sends multipart/alternative with --body as the plain-text part.")
+        .option("--html-file <path>", "Read the HTML body from a file instead of --html.")
+        .option("--display-name <name>", "From display name for this send (overrides the mailbox's stored display name).")
+        .option("--cc <list>", "Comma-separated Cc addresses.")
+        .option("--bcc <list>", "Comma-separated Bcc addresses.")
+        .option("--from <mailbox>", "Sending mailbox (address or id). Defaults to the pool rotation.")
+        .option("--approved", "Approve and send. Without this flag, returns a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("email send", options, async () => {
+            const bodyText = readOption(options.body) ?? (options.bodyFile ? readFileSync(resolve(options.bodyFile), "utf8") : undefined);
+            if (!bodyText || !bodyText.trim()) {
+                throw new Error("Provide --body or --body-file.");
+            }
+            const htmlBody = readOption(options.html) ?? (options.htmlFile ? readFileSync(resolve(options.htmlFile), "utf8") : undefined);
+            const cc = readCsvOption(options.cc);
+            const bcc = readCsvOption(options.bcc);
+            return requestOxygen("/api/cli/email/send", {
+                method: "POST",
+                body: {
+                    to: readOption(options.to),
+                    subject: readOption(options.subject),
+                    body: bodyText,
+                    ...(htmlBody?.trim() ? { html: htmlBody } : {}),
+                    ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
+                    ...(cc.length > 0 ? { cc } : {}),
+                    ...(bcc.length > 0 ? { bcc } : {}),
+                    ...(readOption(options.from) ? { from: readOption(options.from) } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/commands/engagement.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerEngagementFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/engagement.js

@@ -0,0 +1,189 @@
+import { parseJsonArray, readFileIfPresent, readPositiveInteger, readPositiveNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { Command } from "commander";
+// A post's engagers list is the one payload in this tree that is routinely
+// thousands of lines long, and the field that decides whether you may act on it
+// — `truncated` — is one boolean inside it. Printed raw, a partial audience
+// looks exactly like a whole one until you scroll past every person in it. So
+// lead with the receipt on stderr (the same stdout/stderr split the dry-run and
+// credits notices use, leaving stdout a clean envelope) and say plainly what to
+// do about a short read. `--json` callers are untouched: they read the fields.
+function writeEngagersReceipt(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const pages = isRecord(record.pages_read) ? record.pages_read : {};
+    const line = (text) => process.stderr.write(`${text}\n`);
+    line(`Post ${String(record.post ?? "?")}`);
+    line(`  ${String(record.total_engagers ?? 0)} engagers`
+        + ` (${String(record.reactors_count ?? 0)} reactions, ${String(record.commenters_count ?? 0)} comments)`
+        + ` from ${String(pages.reactions ?? 0)}+${String(pages.comments ?? 0)} pages`);
+    if (record.truncated === true) {
+        const reason = typeof record.partial_reason === "string" ? record.partial_reason : "unknown";
+        line(`  PARTIAL (${reason}) — this post has more engagers than were read.`);
+        line(reason === "max_pages"
+            ? "  Raise --max-pages (max 20), or run `oxygen engagement harvest` to walk the whole post into a table."
+            : "  Retry, or run `oxygen engagement harvest` to walk the whole post into a table.");
+    }
+    if (typeof record.web_url === "string")
+        line(`  ${record.web_url}`);
+}
+export function registerEngagementFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("engagement")
+        .description("For a LinkedIn audience campaign, find the matching play with `oxygen recipes list \"post engagers\" --view summary --json`: own, competitor, creator or keyword post engagers, company followers, or own followers. The Recipe and shared guide prepare qualified recipients and a disabled ongoing router. For one known post, read its engagers or harvest into a durable Table using its public URL or composite social_id from `oxygen posts get`; harvesting runs as a paced background drip. Existing intent captures are managed with `oxygen feeds list|pause|resume|run`; existing profile watchers use `oxygen tables watcher get`. To have teammates react to or comment on the workspace's own posts, use `oxygen publishing amplification --help`.")
+        .addCommand(new Command("engagers")
+        .description("Read one post's reactors and commenters right now as a de-duplicated people list ready to enroll. Pages both sources up to --max-pages (default 5, max 20) x 100 per page; `truncated: true` in the envelope means a cap stopped a source that still had more — raise --max-pages, or use `oxygen engagement harvest` for a post too big to read in one request. Nothing is sent and no credits are spent, but every page is one LinkedIn read against the sender account. --post is the composite social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .option("--account <ref>", "Sender account that reads (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--limit <n>", "Engagers per PAGE (default 100, which is also the provider maximum). Per source you get --limit x --max-pages.")
+        .option("--max-pages <n>", "Pages to walk per source, 1-20 (default 5, so 500 reactors + 500 commenters).")
+        .option("--no-reactions", "Skip reactors.")
+        .option("--no-comments", "Skip commenters.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement engagers", options, async () => {
+            const post = readOption(options.post);
+            if (!post)
+                throw new Error("--post is required (the composite social_id from `oxygen posts get`).");
+            const account = readOption(options.account);
+            const limit = readPositiveInteger(options.limit);
+            const maxPages = readPositiveInteger(options.maxPages);
+            const params = new URLSearchParams({ post });
+            if (account)
+                params.set("account", account);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            // Forwarded as-is: the route owns the 1-20 range so an
+            // out-of-range value fails loudly instead of silently reading
+            // fewer pages than the caller asked for.
+            if (maxPages !== undefined)
+                params.set("max_pages", String(maxPages));
+            if (options.reactions === false)
+                params.set("include_reactions", "false");
+            if (options.comments === false)
+                params.set("include_comments", "false");
+            const data = await requestOxygen(`/api/cli/linkedin/engagement?${params.toString()}`);
+            // Ahead of the payload, and only for a human: a machine caller
+            // reads truncated/partial_reason off the envelope itself.
+            if (!options.json)
+                writeEngagersReceipt(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("harvest")
+        .description("Start (or re-arm) a harvest of a post's engagers into a workspace table you can enroll into a sequence. Engagers drip into the table over many ticks; poll `engagement status` to watch it fill. No messages are sent. Cookieless harvests spend Oxygen credits per scraper page and require --max-credits.")
+        .requiredOption("--post <social_id_or_url>", "Composite post social_id from `oxygen posts get` (NOT the activity URN), or the public LinkedIn post URL for cookieless.")
+        .option("--source <source>", "cookieless|unipile. Defaults to cookieless when a public post URL is supplied.")
+        .option("--post-url <url>", "Public LinkedIn post URL for cookieless harvesting when --post is a social id.")
+        .option("--max-credits <credits>", "Required for cookieless harvesting; caps managed scraper spend for this armed run.")
+        .option("--recurring", "Keep re-polling the newest pages for new engagers (default: one walk).")
+        .option("--account <ref>", "Sender account that reads (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--no-reactions", "Skip reactors.")
+        .option("--no-comments", "Skip commenters.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement harvest", options, () => {
+            const post = readOption(options.post);
+            const account = readOption(options.account);
+            const source = readOption(options.source);
+            const postUrl = readOption(options.postUrl);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return requestOxygen("/api/cli/linkedin/engagement/harvest", {
+                method: "POST",
+                body: {
+                    ...(post ? { post } : {}),
+                    ...(source ? { source } : {}),
+                    ...(postUrl ? { post_url: postUrl } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(options.recurring ? { recurring: true } : {}),
+                    ...(account ? { account } : {}),
+                    // commander sets reactions/comments=false for --no-* flags.
+                    ...(options.reactions === false ? { include_reactions: false } : {}),
+                    ...(options.comments === false ? { include_comments: false } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("status")
+        .description("Show an engagement harvest's progress (drip status, engagers ingested, last error) plus the workspace table it fills and a preview of harvested engagers.")
+        .option("--account <ref>", "Scope to one sender account (sender id, connection id, or Unipile account id).")
+        .option("--post <social_id>", "Scope to one harvested post.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement status", options, () => {
+            const account = readOption(options.account);
+            const post = readOption(options.post);
+            const params = new URLSearchParams();
+            if (account)
+                params.set("account", account);
+            if (post)
+                params.set("post", post);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/linkedin/engagement/harvest${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("react")
+        .description("React to a LinkedIn post (or to a comment with --comment-id). A real external LinkedIn write that everyone can see and that counts against the sender account's daily action quota, gated behind approval: prints a preview by default and only reacts when you pass --approved. --post is the composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .option("--reaction-type <type>", "Reaction kind: like, celebrate, support, love, insightful, or funny (default like).")
+        .option("--comment-id <id>", "React to this comment id instead of the post itself.")
+        .option("--as-organization <org>", "LinkedIn organization id to react as a company page.")
+        .option("--account <ref>", "Sender account that reacts (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--approved", "Actually add the reaction. Omit to preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement react", options, () => {
+            const post = readOption(options.post);
+            const reactionType = readOption(options.reactionType);
+            const commentId = readOption(options.commentId);
+            const asOrganization = readOption(options.asOrganization);
+            const account = readOption(options.account);
+            return requestOxygen("/api/cli/linkedin/engagement/react", {
+                method: "POST",
+                body: {
+                    ...(post ? { post } : {}),
+                    ...(reactionType ? { reaction_type: reactionType } : {}),
+                    ...(commentId ? { comment_id: commentId } : {}),
+                    ...(asOrganization ? { as_organization: asOrganization } : {}),
+                    ...(account ? { account } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("comment")
+        .description("Comment on a LinkedIn post (or reply to a comment with --comment-id). A real external LinkedIn write that everyone can see and that counts against the sender account's daily action quota, gated behind approval: prints a preview by default and only posts when you pass --approved. --post is the composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--text <text>", "Comment text to post.")
+        .option("--mentions-json <json-or-file>", "Provider comment mention objects.")
+        .option("--comment-id <id>", "Reply under this comment id instead of commenting on the post.")
+        .option("--as-organization <org>", "LinkedIn organization id to comment as a company page.")
+        .option("--external-link <url>", "URL to attach as a link preview on the comment.")
+        .option("--account <ref>", "Sender account that comments (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--approved", "Actually post the comment. Omit to preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement comment", options, () => {
+            const post = readOption(options.post);
+            const text = readOption(options.text);
+            const commentId = readOption(options.commentId);
+            const asOrganization = readOption(options.asOrganization);
+            const externalLink = readOption(options.externalLink);
+            const account = readOption(options.account);
+            return requestOxygen("/api/cli/linkedin/engagement/comment", {
+                method: "POST",
+                body: {
+                    ...(post ? { post } : {}),
+                    ...(options.mentionsJson !== undefined ? { mentions: parseJsonArray(readFileIfPresent(options.mentionsJson)) } : {}),
+                    ...(text ? { text } : {}),
+                    ...(commentId ? { comment_id: commentId } : {}),
+                    ...(asOrganization ? { as_organization: asOrganization } : {}),
+                    ...(externalLink ? { external_link: externalLink } : {}),
+                    ...(account ? { account } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/commands/enrich-column.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerEnrichColumnFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/enrich-column.js

@@ -0,0 +1,149 @@
+import { readJsonObjectOption, readPositiveInt } from "../cli-values.js";
+import { readCsvOption, readFilterSelectionOption, readPositiveNumber } 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";
+function buildEnrichColumnBody(// skipcq: JS-R1005 -- CLI body builder maps enrichment aliases, selection, provider order, and safety caps.
+table, options) {
+    const limit = readPositiveInt(options.limit);
+    const filterSelection = readFilterSelectionOption(options.filterJson);
+    const explicitSelection = readJsonObjectOption(options.selectionJson);
+    const selectedModes = [
+        Boolean(options.all),
+        limit !== undefined,
+        Boolean(filterSelection),
+        Boolean(explicitSelection),
+    ].filter(Boolean).length;
+    if (selectedModes > 1) {
+        throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --filter-json, or --selection-json.", {
+            exitCode: 1,
+        });
+    }
+    return {
+        table,
+        ...(readOption(options.sourceColumn) ? { source_column: readOption(options.sourceColumn) } : {}),
+        ...(readOption(options.fullNameColumn) ? { full_name_column: readOption(options.fullNameColumn) } : {}),
+        ...(readOption(options.firstNameColumn) ? { first_name_column: readOption(options.firstNameColumn) } : {}),
+        ...(readOption(options.lastNameColumn) ? { last_name_column: readOption(options.lastNameColumn) } : {}),
+        ...(readOption(options.linkedinUrlColumn) ? { linkedin_url_column: readOption(options.linkedinUrlColumn) } : {}),
+        ...(readOption(options.emailColumn) ? { email_column: readOption(options.emailColumn) } : {}),
+        ...(readOption(options.companyDomainColumn) ? { company_domain_column: readOption(options.companyDomainColumn) } : {}),
+        ...(readOption(options.companyNameColumn) ? { company_name_column: readOption(options.companyNameColumn) } : {}),
+        ...(readOption(options.companyLinkedinUrlColumn)
+            ? { company_linkedin_url_column: readOption(options.companyLinkedinUrlColumn) }
+            : {}),
+        ...(readOption(options.capability) ? { capability: readOption(options.capability) } : {}),
+        ...(readOption(options.targetColumn) ? { target_column: readOption(options.targetColumn) } : {}),
+        ...(readOption(options.onExistingManualColumn)
+            ? { on_existing_manual_column: readOption(options.onExistingManualColumn) }
+            : {}),
+        ...(readOption(options.providerOrder) ? { provider_order: readCsvOption(options.providerOrder) } : {}),
+        ...(readOption(options.emailWaterfallProfile)
+            ? { email_waterfall_profile: readOption(options.emailWaterfallProfile) }
+            : {}),
+        ...(readOption(options.emailPatternValidation)
+            ? { email_pattern_validation: readOption(options.emailPatternValidation) }
+            : {}),
+        ...(readOption(options.phoneWaterfallProfile)
+            ? { phone_waterfall_profile: readOption(options.phoneWaterfallProfile) }
+            : {}),
+        ...(options.verifyPhone ? { verify_phone: true } : {}),
+        ...(options.allowPremiumLanes ? { allow_premium_lanes: true } : {}),
+        ...(options.includePersonalEmail ? { include_personal_email: true } : {}),
+        ...(readOption(options.phoneVerificationCredentialMode)
+            ? { phone_verification_credential_mode: readOption(options.phoneVerificationCredentialMode) }
+            : {}),
+        ...(options.all ? { selection: { mode: "all" } } : {}),
+        ...(filterSelection ? { selection: filterSelection } : {}),
+        ...(explicitSelection ? { selection: explicitSelection } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(options.onlyMissing ? { only_missing: true } : {}),
+    };
+}
+export function registerEnrichColumnFamily(program, handleAsyncAction) {
+    program
+        .command("enrich-column")
+        .description("High-level table enrichment helpers. To see every enrichment a table's columns support, with per-row prices, before choosing one, run `tools search --for-table <table>` (0 credits).")
+        .addCommand(new Command("preview")
+        .description("Preflight an enrichment column without provider calls or credit usage. A lane on your own key (BYOK) is quoted at OXYGEN's platform fee per successful call, including a successful miss; vendor charges follow your provider's terms (provider_cost_breakdown[].byok_platform_fee_credits_per_call).")
+        .argument("<table>", "Table id or slug.")
+        .option("--source-column <column>", "Source column key or id. For mobile_phone this is the LinkedIn URL column.")
+        .option("--full-name-column <column>", "Column key or id containing the person's full name for work_email. Pair with company-domain/name for Prospeo, LeadMagic, Hunter, Dropleads, ContactOut, BetterContact, or People Data Labs.")
+        .option("--first-name-column <column>", "Column key or id containing the person's first name for work_email.")
+        .option("--last-name-column <column>", "Column key or id containing the person's last name for work_email.")
+        .option("--linkedin-url-column <column>", "Column key or id containing the person's LinkedIn URL. Required by BlitzAPI and enough for Prospeo, Hunter, ContactOut, BetterContact, People Data Labs, or Crustdata on your own key.")
+        .option("--email-column <column>", "Column key or id containing a known work email for providers that accept email as an identity fallback.")
+        .option("--company-domain-column <column>", "Column key or id containing the company domain for work_email. Pair with full-name/first+last for name+company providers.")
+        .option("--company-name-column <column>", "Column key or id containing the company name for work_email when no domain is available.")
+        .option("--company-linkedin-url-column <column>", "Column key or id containing the company's LinkedIn URL for company identity fallback.")
+        .option("--capability <capability>", "What to run: mobile_phone, work_email, linkedin_url (find a missing value), or verify_email (grade an email the row already has). For a personal email add --include-personal-email to work_email (personal_email alone still works). Defaults to mobile_phone.")
+        .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
+        .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
+        .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default cost-aware waterfall profile.")
+        .option("--email-waterfall-profile <profile>", "Work-email waterfall profile: auto, name_domain, linkedin_url, or first_last_domain. Defaults route by cost and coverage for whichever inputs are mapped.")
+        .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
+        .option("--phone-waterfall-profile <profile>", "Phone waterfall profile: auto (input-aware), linkedin_url, email, or name_domain. Auto picks the cheapest cost-ordered provider set for each row's inputs (mobile match rate ~30-60%).")
+        .option("--verify-phone", "Validate found phone numbers with ClearoutPhone (adds phone_line_type + phone_carrier; filter phone_line_type=mobile for mobile-only).")
+        .option("--allow-premium-lanes", "Opt in to managed lanes billing over 50 credits per call. Only linkedin_url has one (LeadMagic email_to_profile, 122.5cr), until the 2026-09 repricing date, when a LinkedIn URL starts billing only on a hit; it is off by default so an unattended run can't bill-shock. No effect on mobile_phone, work_email or verify_email.")
+        .option("--include-personal-email", "work_email only: also find the personal (non-work) email from the LinkedIn URL column, billed only on a hit; the preview adds its price and the address lands in the cell's personal_email.")
+        .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
+        .option("--limit <n>", "Rows to estimate. Defaults to 10.")
+        .option("--all", "Estimate all rows.")
+        .option("--filter-json <json>", "Filter object or array, e.g. '{\"column\":\"mobile_phone_e164\",\"op\":\"is_null\"}'.")
+        .option("--selection-json <json>", "Full row selection object, e.g. '{\"mode\":\"filter\",\"filters\":[{\"column\":\"mobile_phone_e164\",\"op\":\"is_null\"}],\"limit\":100}'.")
+        .option("--only-missing", "Estimate rows missing the capability's normalized output when no explicit selection is passed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("enrich-column preview", options, () => requestOxygen("/api/cli/enrich-column/preview", {
+            method: "POST",
+            body: buildEnrichColumnBody(table, options),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Create or reuse an enrichment column and queue a background run.")
+        .argument("<table>", "Table id or slug.")
+        .option("--source-column <column>", "Source column key or id. For mobile_phone this is the LinkedIn URL column.")
+        .option("--full-name-column <column>", "Column key or id containing the person's full name for work_email. Pair with company-domain/name for Prospeo, LeadMagic, Hunter, Dropleads, ContactOut, BetterContact, or People Data Labs.")
+        .option("--first-name-column <column>", "Column key or id containing the person's first name for work_email.")
+        .option("--last-name-column <column>", "Column key or id containing the person's last name for work_email.")
+        .option("--linkedin-url-column <column>", "Column key or id containing the person's LinkedIn URL. Required by BlitzAPI and enough for Prospeo, Hunter, ContactOut, BetterContact, People Data Labs, or Crustdata on your own key.")
+        .option("--email-column <column>", "Column key or id containing a known work email for providers that accept email as an identity fallback.")
+        .option("--company-domain-column <column>", "Column key or id containing the company domain for work_email. Pair with full-name/first+last for name+company providers.")
+        .option("--company-name-column <column>", "Column key or id containing the company name for work_email when no domain is available.")
+        .option("--company-linkedin-url-column <column>", "Column key or id containing the company's LinkedIn URL for company identity fallback.")
+        .requiredOption("--max-credits <credits>", "Required credit ceiling for the queued run.")
+        .option("--capability <capability>", "What to run: mobile_phone, work_email, linkedin_url (find a missing value), or verify_email (grade an email the row already has). For a personal email add --include-personal-email to work_email (personal_email alone still works). Defaults to mobile_phone.")
+        .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
+        .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
+        .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default cost-aware waterfall profile.")
+        .option("--email-waterfall-profile <profile>", "Work-email waterfall profile: auto, name_domain, linkedin_url, or first_last_domain. Defaults route by cost and coverage for whichever inputs are mapped.")
+        .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
+        .option("--phone-waterfall-profile <profile>", "Phone waterfall profile: auto (input-aware), linkedin_url, email, or name_domain. Auto picks the cheapest cost-ordered provider set for each row's inputs (mobile match rate ~30-60%).")
+        .option("--verify-phone", "Validate found phone numbers with ClearoutPhone (adds phone_line_type + phone_carrier; filter phone_line_type=mobile for mobile-only).")
+        .option("--allow-premium-lanes", "Opt in to managed lanes billing over 50 credits per call. Only linkedin_url has one (LeadMagic email_to_profile, 122.5cr), until the 2026-09 repricing date, when a LinkedIn URL starts billing only on a hit; it is off by default so an unattended run can't bill-shock. No effect on mobile_phone, work_email or verify_email.")
+        .option("--include-personal-email", "work_email only: also find the personal (non-work) email from the LinkedIn URL column, billed only on a hit; the preview adds its price and the address lands in the cell's personal_email.")
+        .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
+        .option("--limit <n>", "Rows to queue.")
+        .option("--all", "Queue all rows.")
+        .option("--filter-json <json>", "Filter object or array for server-side row selection.")
+        .option("--selection-json <json>", "Full row selection object for server-side row selection.")
+        .option("--only-missing", "Queue rows missing the capability's normalized output when no explicit selection is passed.")
+        .option("--force", "Re-run rows with an existing target enrichment value.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for this enrichment run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 20.")
+        .option("--json", "Print a JSON envelope.")
+        .option("--approved", "Approve THIS run after inspecting `enrich-column preview` (free). Paid enrichment runs fail with approval_required (exit 7) without it.")
+        .action(async (table, options) => {
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        await handleAsyncAction("enrich-column run", options, () => requestOxygen("/api/cli/enrich-column/run", {
+            method: "POST",
+            body: {
+                ...buildEnrichColumnBody(table, options),
+                max_credits: readPositiveNumber(options.maxCredits),
+                ...(options.approved ? { approved: true } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+                ...(options.force ? { force: true } : {}),
+            },
+        }));
+    }));
+}

package/dist/commands/enrichment.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerEnrichmentFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/enrichment.js

@@ -0,0 +1,49 @@
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerEnrichmentFamily(program, handleAsyncAction) {
+    program
+        .command("enrichment")
+        .description("The enrichment catalogue: name the DATA (work email, phone, headcount, funding, tech stack, decision makers), see its status, expected vs up-to credits per row, coverage and the exact add command — never pick a provider by hand.")
+        .addCommand(new Command("catalog")
+        .description("Name the DATA, not the provider: list every data type you can ask a table to fill (person profile, work email, phone, headcount, funding, tech stack, hiring, competitors, news, decision makers, signals ...) as `intents`, each with its status (default | selectable | no_default | coming_soon | rejected), the inputs it needs, the fields it fills, region coverage bands (vendor claims until measured), the provider order behind it as metadata, a per-row credit estimate (expected on measured-or-assumed hit rates, plus the up-to ceiling) and the exact add command on CLI, MCP and web. `entries` keeps the column presets, capabilities and recipes. Read this before `columns add --preset` or `--capability`; 0 credits. (Extract column templates have their own `columns catalog`.)")
+        .option("--intent <id>", "One intent id, e.g. find_work_email, enrich_company:funding, people_search:account_contacts.")
+        .option("--group <group>", "Filter intents to one group: person, contact, company, decision_maker, or signal.")
+        .option("--region <region>", "Show the coverage band for one region and hide rows the vendors exclude there: US, UK, DACH, EU_REST, or APAC.")
+        .option("--status <status>", "Filter intents to one status: default, selectable, no_default, coming_soon, or rejected.")
+        .option("--category <category>", "Filter the column entries to one category: Person, Contact, Company, or Ads.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("enrichment catalog", options, async () => {
+            const params = new URLSearchParams();
+            for (const key of ["intent", "group", "region", "status"]) {
+                const value = readOption(options[key]);
+                if (value)
+                    params.set(key, value);
+            }
+            const query = params.toString();
+            const envelope = await requestOxygen(`/api/cli/enrichment/catalog${query ? `?${query}` : ""}`, { method: "GET" });
+            const wanted = readOption(options.category)?.toLowerCase();
+            if (!wanted || !Array.isArray(envelope.entries))
+                return envelope;
+            const entries = envelope.entries.filter((entry) => String(entry.category ?? "").toLowerCase() === wanted);
+            return { ...envelope, entries, category: wanted };
+        });
+    }))
+        .addCommand(new Command("apply-default-cascade")
+        .description("Patch an existing enrichment column to the server-side default provider cascade for its intent.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Enrichment column id or key.")
+        .option("--dry-run", "Return the would-be merged definition without writing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("enrichment apply-default-cascade", options, () => requestOxygen("/api/cli/enrichment/apply-default-cascade", {
+            method: "POST",
+            body: {
+                table,
+                column,
+                ...(options.dryRun ? { dry_run: true } : {}),
+            },
+        }));
+    }));
+}

package/dist/commands/feedback.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerFeedbackFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;