@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/domains.js

@@ -0,0 +1,604 @@
+import { readDetailsNumber } from "../cli-output.js";
+import { readRecordString } from "../cli-values.js";
+import { readCount, readJsonFileValue, readRecord, shellQuote, splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { resolveCliBinaryName } from "../runtime.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { sleep } from "@oxygen/shared/timing";
+import { Command } from "commander";
+import { resolve } from "node:path";
+// Cloudflare domain sync returns partial pages under the request budget; the
+// CLI auto-continues up to this many follow-up POSTs before handing back a
+// still-partial summary.
+const DOMAINS_SYNC_MAX_CONTINUATIONS = 20;
+// Cloudflare's domain-check endpoint accepts at most 20 domains per call.
+const DOMAINS_CHECK_MAX_DOMAINS = 20;
+const DOMAIN_REGISTRATION_WAIT_TIMEOUT_SECONDS = 600;
+const DOMAIN_REGISTRATION_WAIT_INTERVAL_SECONDS = 10;
+// Domain sync is paginated under the server's Cloudflare request budget; the
+// CLI re-POSTs the same body while the server reports a partial sweep with a
+// next page, then prints one aggregated summary.
+async function runDomainsSync(options) {
+    const body = options.full ? { full: true } : {};
+    let totalSynced = 0;
+    let totalPagesFetched = 0;
+    let totalRdapResolved = 0;
+    let totalDnsChecked = 0;
+    let sawRdapResolved = false;
+    let sawDnsChecked = false;
+    let requestCount = 0;
+    for (;;) {
+        requestCount += 1;
+        const latest = await requestOxygen("/api/cli/domains/sync", {
+            method: "POST",
+            body,
+        });
+        // `full` means "restart from page 1" server-side; only the first request may
+        // carry it. Continuations must drop it so the server advances the saved
+        // cursor instead of re-sweeping the first pages every iteration.
+        delete body.full;
+        totalSynced += readCount(latest.synced);
+        totalPagesFetched += readCount(latest.pages_fetched);
+        if (typeof latest.rdap_resolved === "number") {
+            sawRdapResolved = true;
+            totalRdapResolved += readCount(latest.rdap_resolved);
+        }
+        if (typeof latest.dns_checked === "number") {
+            sawDnsChecked = true;
+            totalDnsChecked += readCount(latest.dns_checked);
+        }
+        const hasNextPage = latest.next_page !== undefined && latest.next_page !== null;
+        const shouldContinue = latest.partial === true
+            && hasNextPage
+            && requestCount <= DOMAINS_SYNC_MAX_CONTINUATIONS;
+        if (!shouldContinue) {
+            return {
+                ...latest,
+                synced: totalSynced,
+                pages_fetched: totalPagesFetched,
+                ...(sawRdapResolved ? { rdap_resolved: totalRdapResolved } : {}),
+                ...(sawDnsChecked ? { dns_checked: totalDnsChecked } : {}),
+                requests: requestCount,
+            };
+        }
+        // A 429 mid-sync keeps completed pages and reports a pushback window.
+        const retryAfterSeconds = readCount(latest.retry_after_seconds);
+        if (retryAfterSeconds > 0)
+            await sleep(retryAfterSeconds * 1000);
+    }
+}
+async function runDomainsBuy(domains, options) {
+    const quoteId = readOption(options.quote);
+    if (options.approved && !quoteId) {
+        throw new Error("--quote <id> is required with --approved. Run the same command without --approved first to get the preview and its quote_id.");
+    }
+    const billingPath = readOption(options.billing);
+    const billing = billingPath ? readJsonFileValue(resolve(billingPath), "--billing") : undefined;
+    const redirectUrl = readOption(options.redirectUrl);
+    const data = await requestOxygen("/api/cli/domains/buy", {
+        method: "POST",
+        body: {
+            domains,
+            ...(options.autoRenew === true ? { auto_renew: true } : {}),
+            ...(options.autoRenew === false ? { auto_renew: false } : {}),
+            ...(billing ? { billing } : {}),
+            ...(redirectUrl ? { redirect_url: redirectUrl } : {}),
+            ...(options.privacy === false ? { privacy: false } : {}),
+            ...(options.approved ? { approved: true, quote_id: quoteId } : {}),
+            ...(options.acceptPremium ? { accept_premium_pricing: true } : {}),
+        },
+    });
+    if (!options.approved) {
+        const previewQuoteId = readRecordString(data, "quote_id");
+        return previewQuoteId
+            ? { ...data, rerun_command: domainsBuyRerunCommand(domains, previewQuoteId, options, data) }
+            : data;
+    }
+    if (!options.wait)
+        return data;
+    const pendingDomains = Array.isArray(data.results)
+        ? data.results
+            .filter((entry) => {
+            const status = readRecordString(entry, "status");
+            return status === "submitting" || status === "in_progress";
+        })
+            .map((entry) => readRecordString(entry, "domain"))
+            .filter((entry) => entry !== null)
+        : [];
+    if (pendingDomains.length === 0)
+        return data;
+    const waitResults = [];
+    for (const domain of pendingDomains) {
+        waitResults.push(await waitForDomainRegistration(domain));
+    }
+    return { ...data, wait: { waited: pendingDomains.length, results: waitResults } };
+}
+function domainsBuyRerunCommand(domains, quoteId, options, data) {
+    // The buy preview returns items and requires_accept_premium_pricing at the
+    // TOP level of data (there is no preview wrapper); reading data.preview here
+    // drops the premium ack flag and makes a copy-paste of the rerun command 422.
+    const items = Array.isArray(data.items) ? data.items : [];
+    const needsPremiumAck = options.acceptPremium === true
+        || data.requires_accept_premium_pricing === true
+        || items.some((item) => readRecordString(item, "tier") === "premium");
+    const billingPath = readOption(options.billing)
+        ?? (data.registrant_on_file === false ? "registrant.json" : null);
+    const flags = [
+        "--approved",
+        `--quote ${quoteId}`,
+        ...(needsPremiumAck ? ["--accept-premium"] : []),
+        ...(options.autoRenew === false ? ["--no-auto-renew"] : []),
+        ...(billingPath ? [`--billing ${shellQuote(billingPath)}`] : []),
+        ...(readOption(options.redirectUrl) ? [`--redirect-url ${readOption(options.redirectUrl)}`] : []),
+        ...(options.privacy === false ? ["--no-privacy"] : []),
+    ];
+    return `${resolveCliBinaryName()} domains buy ${domains.join(" ")} ${flags.join(" ")}`;
+}
+function readDnsDkimOption(value) {
+    let records;
+    try {
+        records = JSON.parse(value);
+    }
+    catch {
+        throw new OxygenError("invalid_request", "--dkim-json must be a JSON array of DKIM records.", { exitCode: 2 });
+    }
+    if (!Array.isArray(records) || records.some((record) => !isRecord(record) || !["TXT", "CNAME"].includes(String(record.type).toUpperCase()) || !readRecordString(record, "name") || !readRecordString(record, "content"))) {
+        throw new OxygenError("invalid_request", "Each --dkim-json record requires type TXT or CNAME, name, and content.", { exitCode: 2 });
+    }
+    return records;
+}
+function dnsPlanBody(options) {
+    const provider = readOption(options.provider);
+    if (!provider) {
+        throw new Error("--provider <google|microsoft> is required so the correct SPF/MX/DKIM records can be planned.");
+    }
+    return {
+        provider,
+        ...(readOption(options.dmarcPolicy) ? { dmarc_policy: readOption(options.dmarcPolicy) } : {}),
+        ...(readOption(options.dmarcRua) ? { dmarc_rua: readOption(options.dmarcRua) } : {}),
+        ...(readOption(options.trackingHost) ? { tracking_host: readOption(options.trackingHost) } : {}),
+        ...(options.autoDkim === false ? { auto_dkim: false } : {}),
+        ...(options.dkimJson !== undefined ? { dkim: readDnsDkimOption(options.dkimJson) } : {}),
+    };
+}
+// Preview the cold-email DNS plan for a domain (free — no writes). Appends a
+// copy-paste rerun command carrying the plan_hash, mirroring the buy quote flow.
+async function runDomainsDnsPlan(domain, options) {
+    const data = await requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/dns/plan`, { method: "POST", body: dnsPlanBody(options) });
+    const planHash = readRecordString(data, "plan_hash");
+    const provider = readOption(options.provider);
+    return planHash && provider
+        ? { ...data, rerun_command: [resolveCliBinaryName(), "domains dns apply", shellQuote(domain), "--provider", shellQuote(provider), "--approved --plan", shellQuote(planHash),
+                ...(options.dkimJson !== undefined ? ["--dkim-json", shellQuote(options.dkimJson)] : []),
+                ...(readOption(options.dmarcPolicy) ? ["--dmarc-policy", shellQuote(options.dmarcPolicy)] : []),
+                ...(readOption(options.dmarcRua) ? ["--dmarc-rua", shellQuote(options.dmarcRua)] : []),
+                ...(readOption(options.trackingHost) ? ["--tracking-host", shellQuote(options.trackingHost)] : []),
+                ...(options.autoDkim === false ? ["--no-auto-dkim"] : []),].join(" ") }
+        : data;
+}
+// Apply an approved DNS plan (writes records). Requires --plan <hash> with
+// --approved, mirroring `domains buy --quote`.
+function runDomainsDnsApply(domain, options) {
+    if (!options.approved)
+        return runDomainsDnsPlan(domain, options);
+    const planHash = readOption(options.plan);
+    if (options.approved && !planHash) {
+        throw new Error("--plan <hash> is required with --approved. Run `domains dns plan` first to get the plan and its hash.");
+    }
+    return requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/dns/apply`, {
+        method: "POST",
+        body: {
+            ...dnsPlanBody(options),
+            ...(options.approved ? { approved: true, plan_hash: planHash } : {}),
+        },
+    });
+}
+// Staff import of pre-existing managed-account domains. Exactly one of an explicit
+// list or --all; without --yes the server returns a preview and the CLI appends a
+// copy-paste rerun command to execute it.
+async function runDomainsAdopt(domains, options) {
+    const hasExplicit = domains.length > 0;
+    if (hasExplicit === Boolean(options.all)) {
+        throw new Error("Pass exactly one of <domains...> or --all. Use --all to adopt every domain in the managed account, or list specific domains.");
+    }
+    const organizationId = readOption(options.organizationId);
+    const data = await requestOxygen("/api/cli/domains/adopt", {
+        method: "POST",
+        body: {
+            ...(options.all ? { all: true } : {}),
+            ...(hasExplicit ? { domains } : {}),
+            ...(organizationId ? { organization_id: organizationId } : {}),
+            ...(options.yes ? { approved: true } : {}),
+        },
+    });
+    if (options.yes)
+        return data;
+    return { ...data, rerun_command: domainsAdoptRerunCommand(domains, options) };
+}
+function domainsAdoptRerunCommand(domains, options) {
+    const organizationId = readOption(options.organizationId);
+    const flags = [
+        ...(options.all ? ["--all"] : []),
+        ...(organizationId ? [`--organization-id ${organizationId}`] : []),
+        "--yes",
+    ];
+    const args = domains.length > 0 ? ` ${domains.join(" ")}` : "";
+    return `${resolveCliBinaryName()} domains adopt${args} ${flags.join(" ")}`;
+}
+// succeeded/failed are terminal; action_required stops the wait too because
+// only the user (in the Cloudflare dashboard) can move it forward.
+function isSettledDomainRegistrationStatus(status) {
+    return status === "succeeded"
+        || status === "failed"
+        || status === "action_required";
+}
+async function waitForDomainRegistration(domain) {
+    const startedAt = Date.now();
+    const deadline = startedAt + DOMAIN_REGISTRATION_WAIT_TIMEOUT_SECONDS * 1000;
+    let polls = 0;
+    let lastStatus = null;
+    let lastRegistration = null;
+    for (;;) {
+        let delayMs = DOMAIN_REGISTRATION_WAIT_INTERVAL_SECONDS * 1000;
+        try {
+            polls += 1;
+            const latest = await requestOxygen(`/api/cli/domains/registrations/${encodeURIComponent(domain)}`);
+            lastRegistration = readRecord(latest, "registration");
+            lastStatus = readRecordString(lastRegistration, "status");
+            if (isSettledDomainRegistrationStatus(lastStatus)) {
+                if (lastStatus === "action_required") {
+                    process.stderr.write(`hint: ${domain} needs action in the Cloudflare dashboard before registration can finish.\n`);
+                }
+                return {
+                    domain,
+                    status: lastStatus,
+                    terminal: true,
+                    polls,
+                    elapsedMs: Date.now() - startedAt,
+                    ...(lastRegistration ? { registration: lastRegistration } : {}),
+                    ...(readRecordString(latest, "deepLink") ? { deepLink: readRecordString(latest, "deepLink") } : {}),
+                };
+            }
+        }
+        catch (error) {
+            // Honor the server's rate-limit pushback instead of failing the wait.
+            const retryAfterSeconds = error instanceof OxygenError
+                ? readDetailsNumber(error.details, "retry_after_seconds")
+                : null;
+            if (retryAfterSeconds === null)
+                throw error;
+            delayMs = Math.max(delayMs, retryAfterSeconds * 1000);
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            process.stderr.write(`hint: registration for ${domain} is still ${lastStatus ?? "pending"}; the background worker keeps polling — re-run \`${resolveCliBinaryName()} domains registration-status ${domain} --wait\` later.\n`);
+            return {
+                domain,
+                status: lastStatus,
+                terminal: false,
+                timed_out: true,
+                polls,
+                elapsedMs: Date.now() - startedAt,
+                ...(lastRegistration ? { registration: lastRegistration } : {}),
+            };
+        }
+        await sleep(Math.min(delayMs, remainingMs));
+    }
+}
+export function registerDomainsFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("domains")
+        .description("Cold-email domains: sync zones from your own Cloudflare account (BYOK), inspect age/warmup/DNS health, check availability and pricing, buy domains, and archive or delete domains with their inboxes (OXYGEN-bought domains included). Your own Cloudflare account bills purchases to its payment method; domains registered by OXYGEN cost credits at the vendor price. Preview `domains buy` before approval.")
+        .addCommand(new Command("list")
+        .description("List the org's cached Cloudflare domains with cold-email metadata (age, mailboxes, warmup, sending volume, DNS health). Each row's `dns` object explains the status (ok, issues, not checked, check failed, partial check, no zone) with a reason and fix path; `managed_domains` lists InboxKit-managed bundle domains (vendor-registered + vendor-DNS'd — manage via `managed-inboxes`), each carrying `internal_billing_status` (ok|past_due) and `last_billed_cycle_key` — a domain the vendor keeps live can still be one OXYGEN could not renew. summary.by_dns_state gives all DNS-state counts in one read. volume.outbound_30d counts outbound email messages in the synced inbox ledger, including mail outside Sequences. Reads the cache only — run `domains sync` to refresh.")
+        .option("--status <status>", "Filter by zone status: unknown, initializing, pending, active, moved, or deleted.")
+        .option("--registrar <registrar>", "Filter by registrar name.")
+        .option("--q <text>", "Filter by domain substring.")
+        .option("--dns <state>", "Filter by one derived DNS state: ok, issues, not_checked, check_failed, check_incomplete, or no_zone; summary.by_dns_state gives all state counts.")
+        .option("--expiring", "Only non-deleted domains expiring within 60 days.")
+        .option("--has-mailboxes <bool>", "true → only domains with sending mailboxes; false → only domains without.")
+        .option("--include-archived", "Include archived domains (hidden by default).")
+        .option("--tag <tags>", "Comma-separated workspace tags — matches domains carrying ANY of these tags (see `oxygen tags list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("domains list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const registrar = readOption(options.registrar);
+            if (registrar)
+                params.set("registrar", registrar);
+            const queryText = readOption(options.q);
+            if (queryText)
+                params.set("q", queryText);
+            const dns = readOption(options.dns);
+            if (dns)
+                params.set("dns", dns);
+            if (options.expiring)
+                params.set("expiring", "true");
+            const hasMailboxes = readOption(options.hasMailboxes);
+            if (hasMailboxes)
+                params.set("has_mailboxes", hasMailboxes);
+            if (options.includeArchived)
+                params.set("include_archived", "true");
+            const tags = splitCommaList(options.tag);
+            if (tags.length > 0)
+                params.set("tag", tags.join(","));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/domains${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("archive")
+        .description("Hide a domain from the default list — an Oxygen-side declutter flag only. Nothing changes at Cloudflare, DNS and mailbox governance are untouched, syncs never resurrect it, and `domains unarchive` fully reverses it.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains archive", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/archive`, {
+            method: "POST",
+            body: { archived: true },
+        }));
+    }))
+        .addCommand(new Command("unarchive")
+        .description("Restore an archived domain to the default list.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains unarchive", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/archive`, {
+            method: "POST",
+            body: { archived: false },
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete domains and every inbox on them: cancels OXYGEN inbox orders; a domain bought through Oxygen on its own (`domains buy`) stops renewing and leaves the workspace, staying registered until expiry; archives your own (DNS and registrar untouched). The preview lists every inbox, each domain's action and the recurring credits that stop; 0 credits, and the current period is not refunded.")
+        .argument("<domains...>", "Domain names, space- or comma-separated.")
+        .option("--approved", "Execute the fresh preview. Requires --plan-hash and --confirmation.")
+        .option("--plan-hash <hash>", "Fresh preview plan_hash.")
+        .option("--confirmation <phrase>", "Exact confirmation_phrase returned by the fresh preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domainArgs, options) => {
+        await handleAsyncAction("domains delete", options, () => {
+            const domains = domainArgs.flatMap((value) => splitCommaList(value));
+            if (domains.length === 0) {
+                throw new OxygenError("invalid_request", "Name at least one domain, such as acme.com. `oxygen domains list` shows your domains.", { exitCode: 2 });
+            }
+            const planHash = readOption(options.planHash);
+            const confirmation = readOption(options.confirmation);
+            if (options.approved === true && (!planHash || !confirmation)) {
+                throw new OxygenError("invalid_request", "--approved requires --plan-hash and --confirmation from a fresh deletion preview.", { exitCode: 2 });
+            }
+            return requestOxygen("/api/cli/domains/delete", {
+                method: "POST",
+                body: {
+                    domains,
+                    ...(options.approved === true ? { approved: true } : {}),
+                    ...(planHash ? { plan_hash: planHash } : {}),
+                    ...(confirmation ? { confirmation } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("tag")
+        .description("Replace a domain's workspace tags (whole set; `--tags \"\"` clears) — e.g. pool the domains behind one campaign tag. See `oxygen tags list` for the vocabulary. A later `domains sync` never clobbers them.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .requiredOption("--tags <tags>", "Comma-separated workspace tags (replaces the whole set; empty clears).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains tag", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/tags`, {
+            method: "POST",
+            body: { tags: splitCommaList(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("forwarding")
+        .description("Read or change where an Oxygen-managed domain's WEB root forwards visitors (not mail — MX/SPF/DKIM/DMARC are untouched). Only domains Oxygen manages are editable; domains in your own Cloudflare zone are redirected there.")
+        .addCommand(new Command("get")
+        .description("Show the domain's current web-root forwarding destination. Read-only, 0 credits.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains forwarding get", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/forwarding`));
+    }))
+        .addCommand(new Command("set")
+        .description("Point the domain's web root at a URL. WITHOUT --approved this previews current -> new and writes nothing. Free (0 credits), but it changes what every visitor to the domain sees.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .requiredOption("--url <url>", "Destination http(s) URL. Pass an empty string to REMOVE the forward. Cannot point the domain at itself.")
+        .option("--approved", "Apply the change. Without it, a preview is returned.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains forwarding set", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/forwarding`, {
+            method: "POST",
+            body: {
+                // readOption() collapses "" to undefined, which would drop the
+                // field entirely and read as a malformed request. Clearing is an
+                // explicit null, so the empty string is mapped here.
+                forwarding_url: readOption(options.url) ?? null,
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    })))
+        .addCommand(new Command("sync")
+        .description("Refresh Cloudflare-backed domains only: zone pages, registrar metadata, RDAP age backfill, and DNS health. Vendor-managed bundle domains are skipped here and read live with `domains get` / `domains dns`. Partial (paginated) syncs auto-continue until complete.")
+        .option("--full", "Restart the sweep from the first zone page instead of resuming the cursor.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("domains sync", options, () => runDomainsSync(options));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one domain's infrastructure/readiness detail: zone state, age with provenance, mailboxes, cached sending volume, and the last DNS health check. This is not Sequence/campaign attribution; use `oxygen sequences analytics` for native sent/replied/bounced results by mailbox/domain. For an Oxygen-managed (vendor-registered) domain it returns the vendor's rail instead — subscription, registration and renewal, nameservers and delegation, catch-all, DMARC, and a live DNS verdict. For a domain hosted OUTSIDE Oxygen that you send from (bought from an inbox provider, DNS elsewhere), rail=external answers from public DNS + the RDAP registry: SPF/DKIM/DMARC/MX verdict, nameservers, MX provider, registrar, domain age, web root, plus your own capacity, sending volume and readiness. Free — no credits, no provider keys.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains get", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}`));
+    }))
+        .addCommand(new Command("dns")
+        .description("Run a live read-only DNS health check (SPF, DKIM, DMARC, MX) against the domain's Cloudflare zone and persist the result. Add --deep for content-level checks (SPF DNS-lookup budget, DMARC enforcement, MX provider) plus an external DNS-over-HTTPS nameserver-authority check. An Oxygen-managed domain reads its vendor-held records and verdict instead (--deep ignored). A domain hosted outside Oxygen that you send from returns rail=external: the records public DNS resolves — the mail set, delegation, policy records and web root — with health.enumerable=false, because public DNS cannot list a zone (a DKIM key is probed at common selectors, so dkim=unknown means unproven, never missing). `dns plan`/`dns apply` edit your own Cloudflare zones only. DNS editing is unavailable for Oxygen-bought domains; keep their nameservers and contact support.")
+        .argument("[domain]", "Domain name, such as acme.com.")
+        // NOT --provider: commander parses parent options greedily by default,
+        // so a --provider here would swallow the `dns plan`/`dns apply`
+        // subcommands' required --provider flag.
+        .option("--mx-provider <provider>", "With --deep: report whether the live MX matches this mailbox provider (google or microsoft).")
+        .option("--deep", "Add content-level DNS analysis (SPF lookup budget, DMARC enforcement, MX provider) and an external DoH nameserver-authority check.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        if (!domain) {
+            throw new Error("Provide a domain (oxygen domains dns <domain>) or use a subcommand: `dns plan` / `dns apply`.");
+        }
+        const query = new URLSearchParams();
+        if (options.deep)
+            query.set("deep", "true");
+        if (options.mxProvider)
+            query.set("provider", options.mxProvider);
+        const suffix = query.size > 0 ? `?${query.toString()}` : "";
+        await handleAsyncAction("domains dns", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/dns${suffix}`));
+    })
+        .addCommand(new Command("plan")
+        .description("Preview the cold-email DNS records a domain should hold for its mailbox provider (SPF, per-provider DKIM, DMARC, MX, optional tracking) as a create/update/keep/conflict diff plus a plan_hash. FREE — nothing is written. Own Cloudflare zones only; DNS editing for Oxygen-bought domains is unavailable. Keep their nameservers and contact support.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .requiredOption("--provider <provider>", "Mailbox provider: google or microsoft (determines SPF/MX/DKIM).")
+        .option("--dmarc-policy <policy>", "DMARC policy: none (default), quarantine, or reject.")
+        .option("--dmarc-rua <mailbox>", "DMARC aggregate-report mailbox (rua=mailto:...).")
+        .option("--tracking-host <host>", "Open/click tracking CNAME host (only planned when tracking is configured).")
+        .option("--dkim-json <json>", "DKIM records as [{type:TXT|CNAME,name,content}]. Use identical records when applying the preview.")
+        .option("--no-auto-dkim", "Skip auto-deriving Microsoft DKIM selector1/selector2 CNAMEs (default: auto-derive them for microsoft when no DKIM is supplied).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options, command) => {
+        await handleAsyncAction("domains dns plan", { ...options, json: command.optsWithGlobals().json === true }, () => runDomainsDnsPlan(domain, options));
+    }))
+        .addCommand(new Command("apply")
+        .description("Write the planned cold-email DNS records into your own Cloudflare zone. Requires a fresh plan_hash from `dns plan`. No Oxygen credits. Without --approved, re-previews the plan. DNS editing for Oxygen-bought domains is unavailable; keep their nameservers and contact support.")
+        .argument("<domain>", "Domain name, such as acme.com.")
+        .requiredOption("--provider <provider>", "Mailbox provider: google or microsoft (must match the plan).")
+        .option("--approved", "Write the records. Without this flag, returns a plan preview only.")
+        .option("--plan <hash>", "plan_hash from a fresh `dns plan` (required with --approved).")
+        .option("--dmarc-policy <policy>", "DMARC policy: none (default), quarantine, or reject.")
+        .option("--dmarc-rua <mailbox>", "DMARC aggregate-report mailbox (rua=mailto:...).")
+        .option("--tracking-host <host>", "Open/click tracking CNAME host (only applied when tracking is configured).")
+        .option("--dkim-json <json>", "DKIM records as [{type:TXT|CNAME,name,content}]. Use identical records when applying the preview.")
+        .option("--no-auto-dkim", "Skip auto-deriving Microsoft DKIM (must match the value used in `dns plan` so the plan_hash matches).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options, command) => {
+        await handleAsyncAction("domains dns apply", { ...options, json: command.optsWithGlobals().json === true }, () => runDomainsDnsApply(domain, options));
+    })))
+        .addCommand(new Command("tracking")
+        .description("Open/click tracking domain for native cold email: provision the tracking CNAME on the domain's Cloudflare zone and check its verification status. 0 Oxygen credits.")
+        .addCommand(new Command("setup")
+        .description("Provision the open/click tracking CNAME (<track-host> CNAME <tracking target>) on the domain's Cloudflare zone. Without --approve, previews the exact record. GATE: needs EMAIL_TRACKING_CNAME_TARGET configured + the tracking hostname attached on Vercel; send-time injection stays off until EMAIL_TRACKING_SECRET is set.")
+        .argument("<domain>", "Sending domain, such as acme.com.")
+        .option("--host <host>", "Tracking subdomain (default track.<domain>); must be a subdomain of the domain.")
+        .option("--approve", "Write the CNAME. Without this flag, returns a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains tracking setup", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/tracking`, {
+            method: "POST",
+            body: { ...(options.host ? { host: options.host } : {}), ...(options.approve ? { approved: true } : {}) },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Show the open/click tracking status for a domain (configured host, verification status, CNAME target, whether the tracking secret is set). Reads the cache — 0 Oxygen credits.")
+        .argument("<domain>", "Sending domain, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains tracking status", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/tracking`));
+    })))
+        .addCommand(new Command("add")
+        .description("BYOK CLOUDFLARE: onboard a domain registered elsewhere by creating a zone in your connected Cloudflare account. For managed domain + inbox provisioning use `managed-inboxes subscribe`.")
+        .argument("<domain>", "Apex domain to add, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains add", options, () => requestOxygen("/api/cli/domains/add", { method: "POST", body: { domain } }));
+    }))
+        .addCommand(new Command("search")
+        .description("Search available domains with their first-year registration price. Free; nothing is purchased. With your own Cloudflare account connected it searches your Registrar (USD, your card); otherwise it lists names Oxygen can register, priced in credits at the registrar's cost (a .com is 1,250 for the first year). Renewal pricing is separate and unknown in search; check an exact name for its estimate.")
+        .argument("<query>", "Search text, such as a brand or keyword.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (query, options) => {
+        await handleAsyncAction("domains search", options, () => {
+            const params = new URLSearchParams({ q: query });
+            return requestOxygen(`/api/cli/domains/search?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("check")
+        .description("Check availability and first-year registration price for up to 20 exact domains. Free; nothing is purchased. With your own Cloudflare account connected it checks your Registrar (USD, your card); otherwise the names Oxygen can register, in credits at the registrar's cost (a .com is 1,250 for the first year). The separate renewal estimate may be unknown. A null tier means unknown, not non-premium. A domain you already own through Oxygen comes back with reason `owned`.")
+        .argument("<domains...>", "Domain names to check (max 20).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domains, options) => {
+        await handleAsyncAction("domains check", options, () => {
+            if (domains.length > DOMAINS_CHECK_MAX_DOMAINS) {
+                throw new Error(`domains check takes at most ${DOMAINS_CHECK_MAX_DOMAINS} domains per call (got ${domains.length}). Split the list and re-run.`);
+            }
+            return requestOxygen("/api/cli/domains/check", {
+                method: "POST",
+                body: { domains },
+            });
+        });
+    }))
+        .addCommand(new Command("buy")
+        .description("Buy sending domains. NON-REFUNDABLE. Without --approved, returns a free priced preview plus quote_id. A null tier means unknown, not non-premium. Without your own Cloudflare account, Oxygen registers the domain and charges credits at the registrar's cost for one year (a .com is 1,250), then renews it yearly at the renewal cost, charged 30 days before expiry (turn off with `domains renewal <domain> --off`). With your own Cloudflare account connected, it buys through your Registrar on your Cloudflare card for 0 credits. For a domain with inboxes use `managed-inboxes subscribe`.")
+        .argument("<domains...>", "Domain names to buy.")
+        .option("--approved", "Execute the purchase. Without this flag, returns a preview only.")
+        .option("--quote <id>", "Quote id from the preview (required with --approved).")
+        .option("--accept-premium", "Acknowledge premium-tier pricing for premium domains.")
+        .option("--auto-renew", "Renew the new registrations yearly (the default).")
+        .option("--no-auto-renew", "Do not renew: the domain lapses when its year ends.")
+        .option("--billing <path>", "JSON file with the registrant (WHOIS) contact: first_name, last_name, phone, country, city, state, address_line_one, postal_code. Needed once, when the workspace has none on file.")
+        .option("--redirect-url <url>", "Where the domain's web root forwards visitors. Defaults to your company website.")
+        .option("--no-privacy", "Disable WHOIS privacy/redaction on the new registrations.")
+        .option("--wait", "After an approved purchase, poll each pending registration to a terminal state (up to 10 minutes per domain).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domains, options) => {
+        await handleAsyncAction("domains buy", options, () => runDomainsBuy(domains, options));
+    }))
+        .addCommand(new Command("renewal")
+        .description("Turn the yearly renewal of a domain bought through Oxygen on or off. No charge. On: the registrar's renewal cost is charged in credits 30 days before expiry. Off: the domain lapses when it expires.")
+        .argument("<domain>", "A domain from `domains list` (registered_domains).")
+        .option("--on", "Renew yearly.")
+        .option("--off", "Stop renewing; the domain lapses at expiry.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains renewal", options, () => {
+            if (Boolean(options.on) === Boolean(options.off)) {
+                throw new Error("Pass exactly one of --on or --off.");
+            }
+            return requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/renewal`, {
+                method: "POST",
+                body: { auto_renew: options.on === true },
+            });
+        });
+    }))
+        .addCommand(new Command("adopt")
+        .description("STAFF LEGACY RECOVERY: attach domains that already exist in the shared Oxygen-managed Cloudflare account to their workspace. FREE; no purchase. New managed domain + inbox bundles use InboxKit. Without --yes, previews only.")
+        .argument("[domains...]", "Specific domains to adopt. Omit and pass --all to adopt every zone in the managed account.")
+        .option("--all", "Adopt every zone discovered in the managed Cloudflare account.")
+        .option("--organization-id <id>", "STAFF override: adopt into this workspace instead of the calling org.")
+        .option("--yes", "Execute the adoption. Without this flag, prints a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domains, options) => {
+        await handleAsyncAction("domains adopt", options, () => runDomainsAdopt(domains, options));
+    }))
+        .addCommand(new Command("registrations")
+        .description("List the org's domain purchase ledger: every registration attempt with status and price snapshot.")
+        .option("--status <status>", "Filter by ledger status: submitting, in_progress, succeeded, failed, action_required, or blocked.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("domains registrations", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/domains/registrations${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("registration-status")
+        .description("Get one domain registration's ledger state (the server performs a gated live poll when due — safe to call repeatedly). Pass --wait to poll until it settles.")
+        .argument("<domain>", "Domain name from a previous `domains buy`.")
+        .option("--wait", "Poll every 10s (up to 10 minutes) until the registration reaches a terminal state.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains registration-status", options, () => {
+            if (options.wait)
+                return waitForDomainRegistration(domain);
+            return requestOxygen(`/api/cli/domains/registrations/${encodeURIComponent(domain)}`);
+        });
+    })));
+}

package/dist/commands/egress.d.ts

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