@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/auth.js

@@ -0,0 +1,230 @@
+import { emitCliFailure, writeJson } from "../cli-output.js";
+import { ansi, buildPostLoginHint, createCredentialFingerprint, formatFingerprint, formatLoginSuccessForResolved, pickProfileForLogin, readEnvProfileName, resolveActiveProfileWithSource, resolveLoginIdentity } from "../command-support.js";
+import { defaultApiUrl, normalizeApiUrl, saveCredentials } from "../credentials.js";
+import { ensureFreshCliForApiUrl, requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { exitCodeForOxygenError, OxygenError, success, toFailure } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+import { stdout as output } from "node:process";
+async function handleAuthUseTokenAction(options) {
+    try {
+        const data = await applyAuthToken(options);
+        if (options.json) {
+            writeJson(success("auth use-token", {
+                logged_in: true,
+                profile: data.profile,
+                api_url: data.credentials.apiUrl,
+                user: data.loginIdentity.user,
+                organization: data.loginIdentity.activeOrganization,
+                organizations: data.loginIdentity.organizations,
+                selection_required: data.loginIdentity.selectionRequired,
+                renamed: data.renamed,
+            }));
+            return;
+        }
+        process.stdout.write(formatLoginSuccessForResolved(data.loginIdentity, data.profile, { renamed: data.renamed }));
+        const hint = await buildPostLoginHint(data.profile);
+        if (hint)
+            process.stdout.write(hint);
+    }
+    catch (error) {
+        const failure = toFailure("auth use-token", error);
+        if (options.json)
+            writeJson(failure);
+        else
+            process.stderr.write(`${failure.error.message}\n`);
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
+    }
+}
+async function handleAuthDoctorAction(options) {
+    try {
+        const data = await runAuthDoctor();
+        if (options.json) {
+            writeJson(success("auth doctor", data));
+            return;
+        }
+        process.stdout.write(formatAuthDoctor(data));
+    }
+    catch (error) {
+        emitCliFailure("auth doctor", error);
+    }
+}
+async function runAuthDoctor() {
+    let context = null;
+    let profileError = null;
+    try {
+        context = await resolveActiveProfileWithSource();
+    }
+    catch (error) {
+        const failure = toFailure("profiles current", error);
+        profileError = {
+            code: failure.error.code,
+            message: failure.error.message,
+            ...(failure.error.details !== undefined ? { details: failure.error.details } : {}),
+        };
+    }
+    const credentials = context?.resolution.credentials ?? null;
+    const apiUrl = credentials?.apiUrl ?? defaultApiUrl();
+    const healthCredentials = credentials ?? { token: "", apiUrl };
+    const health = await runAuthDoctorCheck(() => requestOxygen("/api/health", {
+        credentials: healthCredentials,
+        requireAuth: false,
+        enforceMinimumCliVersion: false,
+    }));
+    const identity = credentials
+        ? await runAuthDoctorCheck(() => requestOxygen("/api/cli/whoami", {
+            credentials,
+            enforceMinimumCliVersion: false,
+        }))
+        : { ok: false, skipped: true, reason: "no_credentials" };
+    const cachedIdentity = credentials?.identity ?? null;
+    const cachedOrganization = credentials?.activeOrganization ?? cachedIdentity?.organization ?? null;
+    // The live read wins over the stored `authKind`: a profile written by an older
+    // CLI can carry no kind at all, and the server always knows.
+    const liveAuthType = "ok" in identity && identity.ok && typeof identity.data.authType === "string"
+        ? identity.data.authType
+        : null;
+    return {
+        profile: context?.resolution.exists ? context.resolution.name : null,
+        profile_source: context?.source ?? null,
+        stored: Boolean(context?.resolution.exists),
+        api_url: apiUrl,
+        auth_kind: credentials?.authKind ?? null,
+        token_fingerprint: credentials ? formatFingerprint(createCredentialFingerprint(credentials.token)) : null,
+        cached_organization: cachedOrganization,
+        cached_user: cachedIdentity?.user ?? null,
+        profile_error: profileError,
+        org_switching: {
+            switchable: resolveOrgSwitchability(liveAuthType ?? credentials?.authKind ?? null),
+            current_organization: cachedOrganization,
+        },
+        health,
+        identity,
+    };
+}
+function resolveOrgSwitchability(authKind) {
+    if (authKind === "user_session" || authKind === "oauth")
+        return true;
+    if (authKind === "org_api_key")
+        return false;
+    return null;
+}
+async function runAuthDoctorCheck(fn) {
+    try {
+        return { ok: true, data: await fn() };
+    }
+    catch (error) {
+        const failure = toFailure("auth doctor", error);
+        return {
+            ok: false,
+            error: {
+                code: failure.error.code,
+                message: failure.error.message,
+                ...(failure.error.details !== undefined ? { details: failure.error.details } : {}),
+            },
+        };
+    }
+}
+async function applyAuthToken(options) {
+    const token = readOption(options.token);
+    if (!token) {
+        throw new OxygenError("missing_token", "Pass a CLI API token with --token.", {
+            exitCode: 1,
+        });
+    }
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    await ensureFreshCliForApiUrl(apiUrl);
+    const credentials = {
+        token,
+        apiUrl,
+    };
+    const loginIdentity = await resolveLoginIdentity(token, credentials.apiUrl);
+    const explicitProfile = readOption(options.profile) ?? readEnvProfileName();
+    let chosenProfile;
+    let renamed = false;
+    if (explicitProfile) {
+        chosenProfile = explicitProfile;
+    }
+    else {
+        const picked = await pickProfileForLogin(loginIdentity);
+        chosenProfile = picked.name;
+        renamed = picked.renamed;
+    }
+    const profile = await saveCredentials(loginIdentity.credentials, process.env, {
+        profile: chosenProfile,
+        allowHostChange: options.force === true,
+    });
+    return {
+        identity: loginIdentity.whoami,
+        loginIdentity,
+        credentials: loginIdentity.credentials,
+        api_url: loginIdentity.credentials.apiUrl,
+        profile,
+        renamed,
+    };
+}
+function formatAuthDoctor(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const lines = [
+        "",
+        styles.bold("Oxygen Auth Doctor"),
+        "",
+        `  ${styles.dim("Profile")}       ${data.profile ?? "(none)"}${data.profile_source ? ` (${data.profile_source})` : ""}`,
+        `  ${styles.dim("API")}           ${data.api_url}`,
+        `  ${styles.dim("Stored")}        ${data.stored ? "yes" : "no"}`,
+    ];
+    if (data.auth_kind)
+        lines.push(`  ${styles.dim("Auth kind")}     ${data.auth_kind}`);
+    if (data.token_fingerprint)
+        lines.push(`  ${styles.dim("Fingerprint")}   ${data.token_fingerprint}`);
+    if (data.cached_organization) {
+        const org = data.cached_organization.slug ?? data.cached_organization.id;
+        lines.push(`  ${styles.dim("Cached org")}    ${data.cached_organization.name} (${org})`);
+    }
+    lines.push(`  ${styles.dim("Org switching")} ${formatOrgSwitching(data.org_switching)}`);
+    if (data.profile_error) {
+        lines.push(`  ${styles.dim("Profile error")} ${data.profile_error.code}: ${data.profile_error.message}`);
+    }
+    lines.push(`  ${styles.dim("Health")}        ${data.health.ok ? "ok" : `failed (${data.health.error.code})`}`);
+    if ("skipped" in data.identity) {
+        lines.push(`  ${styles.dim("Identity")}      skipped (${data.identity.reason})`);
+    }
+    else {
+        lines.push(`  ${styles.dim("Identity")}      ${data.identity.ok ? "ok" : `failed (${data.identity.error.code})`}`);
+        if (!data.identity.ok) {
+            lines.push(`  ${styles.dim("Identity error")} ${data.identity.error.message}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function formatOrgSwitching(orgSwitching) {
+    if (orgSwitching.switchable === true)
+        return "available — `oxygen orgs use <organization>`";
+    if (orgSwitching.switchable === false) {
+        const name = orgSwitching.current_organization?.name;
+        return `locked to ${name ?? "this workspace"} — \`oxygen login\` for a switchable user key`;
+    }
+    return "unknown";
+}
+export function registerAuthFamily(program, handleAsyncAction) {
+    program
+        .command("auth")
+        .description("Authentication helpers for scripts and agents (non-interactive token use). Day to day, `oxygen login` and `oxygen whoami` are all you need.")
+        .addCommand(new Command("use-token")
+        .description("Store a CLI API token non-interactively.")
+        .requiredOption("--token <token>", "CLI API token.")
+        .option("--api-url <url>", "Oxygen API URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--profile <name>", "Store credentials under a named CLI profile and make it active.")
+        .option("--force", "Repoint an existing profile at a different API host. Refused without this flag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAuthUseTokenAction(options);
+    }))
+        .addCommand(new Command("doctor")
+        .description("Diagnose the active Oxygen CLI credentials without printing token material.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAuthDoctorAction(options);
+    }));
+}

package/dist/commands/billing.d.ts

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

package/dist/commands/billing.js

@@ -0,0 +1,357 @@
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { collectRepeatable, readPositiveNumber } from "../command-support.js";
+import { defaultApiUrl } from "../credentials.js";
+import { oxygenAppUrl } from "../help.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { PURCHASABLE_PLAN_KEYS, planVolumeBonusPercent, resolveBasePricingPlan } from "@oxygen/shared/billing";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command, Option } from "commander";
+function buildBillingLedgerParams(options) {
+    const params = new URLSearchParams();
+    const days = readPositiveInt(options.days);
+    const limit = readPositiveInt(options.limit);
+    if (days)
+        params.set("days", String(days));
+    if (limit)
+        params.set("limit", String(limit));
+    if (readOption(options.meter))
+        params.set("meter", readOption(options.meter));
+    if (readOption(options.from))
+        params.set("from", readOption(options.from));
+    if (readOption(options.to))
+        params.set("to", readOption(options.to));
+    if (readOption(options.cursor))
+        params.set("cursor", readOption(options.cursor));
+    if (readOption(options.type))
+        params.set("type", readOption(options.type));
+    if (readOption(options.category))
+        params.set("category", readOption(options.category));
+    if (readOption(options.provider))
+        params.set("provider", readOption(options.provider));
+    const sourceId = readOption(options.sourceId) ?? readOption(options.source);
+    if (sourceId)
+        params.set("source_id", sourceId);
+    if (readOption(options.runId))
+        params.set("run_id", readOption(options.runId));
+    if (options.nonzero)
+        params.set("nonzero", "true");
+    return params;
+}
+/**
+ * A whole seat count. Unlike readPositiveNumber, ZERO IS VALID and meaningful:
+ * `--quantity 0` is how a customer gives back every seat of a channel, and
+ * rejecting it would leave the only way to stop paying being a support ticket.
+ */
+function readPositiveNumberOrZero(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a whole number of 0 or more.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+export function registerBillingFamily(program, handleAsyncAction, billingDocsUrl) {
+    program
+        .command("billing")
+        .description("Plan and managed credit commands. Credits reserved but not yet charged are listed hold by hold with `billing usage --meter holds`. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`. THREE CLOCKS, deliberately different: the CREDIT CYCLE that `billing allowance` reports against (your plan's monthly grant window); each resource's own COMMITMENT RENEWAL, anchored to the day you connected it, so `billing commitments --json` next_due_at rarely matches the cycle end; and your SUBSCRIPTION PERIOD in `billing balance` (annual plans span many credit cycles). A number from one clock will not reconcile against another. On a plan that pays for several workspaces, `billing usage --group-by workspace` totals what each one spent. To price a month of outreach before building it (leads, enrichment, sequence steps, senders), run `billing estimate`. Failed-payment grace, suspension, and recovery: " + billingDocsUrl + ".")
+        .addCommand(new Command("change")
+        .description("Create an approval link (`approval_url`) to start or change a plan; no charge or plan change until confirmation. First purchase needs an admin/owner; existing-plan changes allow any unrestricted member. Compare all six prices, credits and yearly terms with `billing balance` first. Use --interval month --term year for twelve discounted monthly payments, renewing for another year: the $99 plan costs $82.50 per month before tax, not $990 upfront. Credits arrive monthly after successful payment. On a workspace that has never had a plan, the Checkout for any monthly plan from $99 up carries the first-month offer, half its first month, while its 24-hour window is open (`offer`; `billing balance` lists every size under `first_month_offer.plans`): `amount_due_now` is then the discounted first month and `next_invoice_total` the regular price, both before tax. Creating that Checkout starts the window if nothing has started it yet. Upgrades during an annual commitment apply immediately with proration and keep its end date; downgrades and switching to a monthly commitment wait for the term end. Switching from a monthly commitment to yearly starts at the next monthly boundary. Legacy prepaid yearly upgrades that keep their cadence apply immediately with proration; downgrades and term or cadence changes wait until the paid year ends. Omit interval and term to preserve the current contract. For an existing subscription, a yearly preview returns charges, start and term-end dates; nothing changes until separate confirmation.")
+        .requiredOption("--to <plan>", 
+    // Derived from the catalog, never retyped: this help text is the only
+    // place a customer's agent learns which plans exist, and it named
+    // three retired ones for as long as it was a literal. The price sits
+    // beside each key because nothing else on the CLI prints a
+    // plan-to-price table (blind baseline, 2026-09-22). The credits sit
+    // there too, bonus included, because the $499+ rungs are no longer
+    // price x 100 (repricing 2026-09, decision 1.3).
+    `Target plan: ${PURCHASABLE_PLAN_KEYS.map((key) => {
+        const plan = resolveBasePricingPlan(key);
+        const cents = plan?.monthlyPriceCents;
+        if (typeof cents !== "number")
+            return key;
+        const credits = plan?.monthlyCredits;
+        const bonus = planVolumeBonusPercent(key);
+        const creditText = typeof credits === "number"
+            ? `, ${credits.toLocaleString("en-US")} credits${bonus > 0 ? ` incl. a ${bonus}% volume bonus` : ""}`
+            : "";
+        return `${key} ($${cents / 100}/mo${creditText})`;
+    }).join(", ")}.`)
+        .option("--interval <interval>", "Payment cadence. Use month for new plans; choose --term year for a yearly commitment paid monthly. Omit to preserve an existing subscription's cadence, including prepaid yearly plans.")
+        .option("--term <term>", "Commitment: month or year. Year means twelve discounted monthly payments, renewing annually. Downgrades wait for the term end; omit to preserve the current term.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing change", options, () => requestOxygen("/api/cli/billing/change", {
+            method: "POST",
+            // Sent only when asked: the server keeps the subscriber's interval otherwise.
+            body: { tier: options.to, ...(options.interval ? { interval: options.interval } : {}), ...(options.term ? { term: options.term } : {}) },
+        }));
+    }))
+        .addCommand(new Command("balance")
+        .description("May apply due plan grants or credit expiry. Compare all six subscription sizes in `available_plans`: monthly prices, yearly paid-monthly prices, credit allowances and savings. `annual_monthly_billing_available` says whether yearly paid monthly is offered; `annual_monthly_terms` explains the 12-month commitment, annual renewal, remaining payments after cancellation and plan-change timing. `first_month_offer` is the first-month offer this workspace can still claim: every size it applies to (`plans`, from `minimum_plan` up) with its first-month and regular price before tax, and `ends_at`, null until its 24-hour window starts. The window starts the first time the workspace meets the offer: the app showing it, signup from a browser that saw it on the website, or creating its Checkout with `billing change`. Also show the current plan, commitment, subscription entitlement, and managed credit balance: available and reserved credits, FIXED credits committed to recurring per-resource charges, and the FLEXIBLE free-to-spend remainder. `next_renewal` answers \"will I be charged?\": read `will_charge` first — true only when this workspace's own Stripe plan is going to charge its card, in which case `charge_at` and the subscription's recurring amount in money say when and roughly how much (the exact amount, with any promotion code or tax, is on the invoice); `period_ends_at` is the trial or period end either way, `cancellation_scheduled` says whether a cancellation is already set, and `stop_command` names the one command that changes it (`billing cancel`, undone by `billing resume`) or is null when nothing here can stop it (staff-invoiced, billed through another workspace, not active). `billing_interval` is payment cadence; `commitment` distinguishes yearly paid monthly from monthly and legacy prepaid yearly plans. Credits are granted monthly; `next_credit_grant_at` is the next grant. For a yearly commitment, cancellation stops annual renewal but remaining monthly payments continue until commitment.ends_at. `renewals_past_due` lists infrastructure renewals (managed-inbox domains, warm-ups) OXYGEN could NOT charge this month, what they cost, and the exact top-up that clears them — nothing is cancelled and billing retries automatically after a top-up. `warnings` also flags a recurring_shortfall when your connected infrastructure costs more per month than the plan grants. `partner_bonus` says whether this workspace earns the agency partner bonus (+15% credits a month for a published directory partner on $99 or above), how many credits, and why not when it does not; the bonus arrives as its own ledger line (`billing usage --category partner_bonus`), never inside plan.monthly_credits. Its basis is the plan face value; `first_grant_timing` explains unknown processing time separately from the next scheduled grant. PARTNERS2026 ends on cancellation or effective plan change; `partner_bonus.conditions` and `coupon_authority` describe the separate prospective exclusion when it applies. See the agency-partner-bonus section of the billing policy. A workspace linked to another organization (`orgs billing-link`) reads its billing at that owner: the balance is the owner's pool, `shared_billing` is true and `billing_owner_organization_id` names the owner. After failed-payment grace expires, mutations stop while read/export and billing recovery remain available. Recovery: " + oxygenAppUrl(defaultApiUrl(), "/billing") + ". Policy: " + billingDocsUrl + ". 0 credits; reserves nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing balance", options, () => requestOxygen("/api/cli/billing/balance"));
+    }))
+        .addCommand(new Command("commitments")
+        .description("List recurring commitments, or inspect monthly connection prices and first-debit timing with --view connection-prices without creating authorization. Default: list the fixed monthly credit commitments — per connected sending mailbox, OXYGEN-sold mailbox, warm-up, deliverability, connected LinkedIn, WhatsApp and X account, and rented phone number — with unit price, quantity, and next-due date. When your balance cannot cover an account's renewal, sending from that account pauses at once and it disconnects 7 days later (a phone number is released after 30): paused_quantity, past_due_since, disconnects_at and topup_url say which kind, since when and by when to top up; a top-up resumes it within minutes. This is the FORWARD run-rate: what your currently-connected resources will cost at their next renewal. It is NOT this cycle's charges — compare `billing allowance` fixed_spent_credits for that, and expect the two to differ. Each resource renews on its OWN anchor (the day it was connected), so next_due_at is per-resource and rarely lines up with the credit cycle. The top-level count is the number of individual resource rows; the commitments list groups them by kind. A past next_due_at is an unpaid renewal still due. To stop all infrastructure renewals while retaining records, preview `workspace infrastructure-exit`; plan cancellation alone does not stop these resources. Read-only, 0 Oxygen credits.")
+        .addOption(new Option("--view <view>", "Inspect connection-prices before authorizing a new account, or current commitments (default).").choices(["commitments", "connection-prices"]))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing commitments", options, () => requestOxygen(`/api/cli/billing/commitments${options.view ? `?view=${encodeURIComponent(options.view)}` : ""}`));
+    }))
+        .addCommand(new Command("estimate")
+        .description("Quote prospective enrichment, senders, X/WhatsApp, EmailGuard tests and an unsaved Workflow without provider calls, writes or reservations. Work-email figures are labelled conservative ceilings until matching measured populations exist; LinkedIn finder prices distinguish found results, misses and declared averages. Current workspace plan_fit uses stored spendable balance and balance-only months; --plan selects a hypothetical monthly allowance instead. Unknown/floor costs suppress complete plan recommendations. Workflow quotes include step floors, 30-day cadence and a separate declared ceiling; no execution authority. Own-key test vendor charges are separate. Prices are in force; opening the quote costs 0 credits. Example: oxygen billing estimate --leads 50 --enrich linkedin_url --whatsapp-accounts 2 --x-accounts 1 --json.")
+        .option("--leads <n>", "Leads you work through a month.")
+        .option("--enrich <id>", "An enrichment run on every lead, by id from `oxygen enrichment catalog --json` (work_email, mobile_phone, person_enrich, capability:verify_email …). Repeat for several.", collectRepeatable, [])
+        .option("--email-steps <n>", "Email steps per lead (only the email ones; LinkedIn steps go in --linkedin-steps).")
+        .option("--linkedin-steps <n>", "LinkedIn steps per lead; the first is a connection invite, later ones messages.")
+        .option("--mailboxes <n>", "Mailboxes you connect yourself (Google, Microsoft, SMTP).")
+        .option("--managed-mailboxes <n>", "Mailboxes you buy from OXYGEN.")
+        .option("--linkedin-accounts <n>", "LinkedIn accounts you connect.")
+        .option("--x-accounts <n>", "X accounts; prospective scenario quantity.")
+        .option("--whatsapp-accounts <n>", "WhatsApp accounts; prospective scenario quantity.")
+        .option("--emailguard-inboxes <n>", "Managed EmailGuard inboxes; prospective scenario quantity.")
+        .option("--emailguard-tests-per-inbox <n>", "Managed tests per inbox per cycle; prospective scenario quantity.")
+        .option("--emailguard-byok-inboxes <n>", "Own-key EmailGuard inboxes; prospective scenario quantity.")
+        .option("--emailguard-byok-tests-per-inbox <n>", "Own-key tests per inbox per cycle; prospective scenario quantity.")
+        .option("--workflow-manifest <json>", "Unsaved oxygen-workflows-v2 draft JSON. Saves nothing.")
+        .option("--workflow-cron <cron>", "Five-field schedule for a 30-day step-cost floor; arms nothing.")
+        .option("--workflow-max-credits <n>", "Declared ceiling for comparison only; grants no approval or authority.")
+        .option("--plan <plan>", `Check against this plan instead of your own: free, ${PURCHASABLE_PLAN_KEYS.join(", ")}.`)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing estimate", options, () => requestOxygen("/api/cli/billing/estimate", {
+            method: "POST",
+            body: {
+                leads_per_month: readPositiveNumberOrZero(options.leads) ?? 0,
+                enrichments: options.enrich.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean),
+                email_steps: readPositiveNumberOrZero(options.emailSteps) ?? 0,
+                linkedin_steps: readPositiveNumberOrZero(options.linkedinSteps) ?? 0,
+                mailboxes: readPositiveNumberOrZero(options.mailboxes) ?? 0,
+                managed_mailboxes: readPositiveNumberOrZero(options.managedMailboxes) ?? 0,
+                linkedin_accounts: readPositiveNumberOrZero(options.linkedinAccounts) ?? 0,
+                x_accounts: options.xAccounts === undefined ? 0 : Number(options.xAccounts),
+                whatsapp_accounts: options.whatsappAccounts === undefined ? 0 : Number(options.whatsappAccounts),
+                emailguard_inboxes: options.emailguardInboxes === undefined ? 0 : Number(options.emailguardInboxes),
+                emailguard_tests_per_inbox: options.emailguardTestsPerInbox === undefined ? 0 : Number(options.emailguardTestsPerInbox),
+                emailguard_byok_inboxes: options.emailguardByokInboxes === undefined ? 0 : Number(options.emailguardByokInboxes),
+                emailguard_byok_tests_per_inbox: options.emailguardByokTestsPerInbox === undefined ? 0 : Number(options.emailguardByokTestsPerInbox),
+                ...(options.workflowManifest ? { workflow_manifest: parseJsonObject(options.workflowManifest) } : {}),
+                ...(options.workflowCron ? { workflow_cron: options.workflowCron } : {}),
+                ...(options.workflowMaxCredits === undefined ? {} : { workflow_max_credits: Number(options.workflowMaxCredits) }),
+                ...(readOption(options.plan) ? { plan: readOption(options.plan) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("seats")
+        .description("Show sending seats, current billing-period end and next-connection eligibility (null: unknown, with a reason). Includes purchased, grandfathered (null: unlimited), connected and left per channel. Seats belong to the billing owner. Email mailbox allocation is workspace-scoped; unreadable mailbox data leaves allocated/available/can_connect null. When retired, held_seats_end_at_reason and held_seats_end_at_message distinguish no paying subscription from an unknown end date; after_seats_end gives monthly credit prices (null: unconfirmed). connect_eligibility explains a single new connection's credit affordability, sponsorship and attachment capacity; paying-seat coverage may remain unknown. Existing accounts and reconnects differ. Charges 0 credits and creates no reservation; like billing balance, it may apply a due plan grant or already-due sponsored-credit expiry.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing seats", options, () => requestOxygen("/api/cli/billing/seats"));
+    })
+        .addCommand(new Command("set")
+        .description("Manage legacy dollar sending seats for one channel; check `billing seats` for retirement status. The quantity is ABSOLUTE, not a delta: `--quantity 3` means you end up with three, so a retried command cannot buy extra. Increasing charges the card pro rata immediately; decreasing credits you pro rata. Reducing below the number of senders you have connected is REFUSED and names how many to disconnect first, because an orphaned sender is one you keep paying a provider for while Oxygen has stopped honouring it. An email_sender reduction is refused with `seat_allocation_unavailable` (503) while the workspace's mailbox count cannot be read; retry it in a moment. Once seats are retired, any increase is refused with `seats_retired` and lowering held seats still works. Charges real money.")
+        .requiredOption("--seat-key <kind>", "linkedin, whatsapp, phone_number, or email_sender.")
+        .requiredOption("--quantity <n>", "Total seats to hold for this channel, 0 or more.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing seats set", options, () => requestOxygen("/api/cli/billing/seats", {
+            method: "POST",
+            body: {
+                seat_key: readOption(options.seatKey),
+                quantity: readPositiveNumberOrZero(options.quantity),
+            },
+        }));
+    })))
+        .addCommand(new Command("invoices")
+        .description("List every invoice Stripe has issued for this workspace, newest first, each with a direct PDF link. Covers ALL charges, not just the plan — sending seats, managed inboxes, and credit top-ups appear here too, which is why this works on the free tier: a workspace with no plan can still be a paying customer. A workspace linked to another organization (`orgs billing-link`) reads its billing at that owner, so it sees an empty list and shared_billing=true; switch to the billing owner to read its invoices. pdf_url and hosted_url are Stripe's own links. VAT or tax ID: open the web_url this command returns and choose VAT or tax ID on the Invoices card (top-up checkout also asks for it); Stripe prints it on every invoice issued after you save it, never on an earlier one. Read-only, 0 Oxygen credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing invoices", options, () => requestOxygen("/api/cli/billing/invoices"));
+    }))
+        .addCommand(new Command("allowance")
+        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total, with ONE deliberate exception: `renewals_past_due` (and its region=past_due segment) reports renewals that FAILED to charge, which is money not taken and therefore outside total_credits. fixed_spent_credits is what has ALREADY been charged this cycle, NOT your monthly run-rate — for the forward figure billed at the next renewal see `billing commitments`, which is normally much larger. For organization wallet scope, reserved_credits is in-flight spend already removed from the available balance: do not subtract it again from free_to_spend_credits. Reserved credits can exceed the remaining free balance without implying an overdraft. For workspace_cap scope, free_to_spend_credits is remaining allowance, not the billing owner's wallet; live execution still checks that wallet and spend policies. Every segment carries region=fixed|flexible. 0 credits; reserves nothing. Due plan grants or credit expiry may apply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing allowance", options, () => requestOxygen("/api/cli/billing/allowance"));
+    }))
+        .addCommand(new Command("usage")
+        .description("Credit-ledger and BYOK views may apply due plan grants or credit expiry. 0 credits. Show credit ledger events (each tagged with its FIXED/FLEXIBLE spend_class), workflow step usage (automation_actions: credits per step, credits billed; writing rows is free), calls with your own API keys (byok_calls: the platform fee per successful call and the fee credits this month; vendor charges follow your provider's terms), or connected LinkedIn and WhatsApp accounts (provider_seats: the rolling-30d peak and its implied connectivity cost; what each account is charged is its credit reservation in `billing commitments`). On a plan that pays for several workspaces (an agency covering client workspaces), `--group-by workspace` totals the credits each workspace spent (`by_workspace`) and `--workspace <id|slug>` narrows the ledger to one of them; a linked client workspace sees only its own spend. managed_credits_used counts captured credits; for where credits went by category, provider or tool, with shares, run `billing audit`.")
+        .option("--meter <meter>", "credits, automation_actions, byok_calls, provider_seats (rolling-30d peak connected accounts and the flat per-account charge; each account's reservation is listed by `billing commitments`), or holds (each held reservation behind reserved_credits in this workspace: credits, run, why it is held (an unmarked LinkedIn lookup hold cannot say whether its result was unknown or delivered), and automatic_return: LinkedIn lookup holds from 24 hours to 30 days old and explicitly unknown LeadMagic email-validation holds older than 24 hours are eligible while automatic return is switched on, and an hourly release returns it on a later pass with no fixed deadline; read-only, newest first, --days up to 365 and --limit apply). Defaults to credits.")
+        .option("--days <n>", "Lookback window in days. Defaults to 30.")
+        .option("--from <iso>", "Only include ledger events at or after this ISO timestamp.")
+        .option("--to <iso>", "Only include ledger events at or before this ISO timestamp.")
+        .option("--limit <n>", "Maximum events to return. Defaults to 50.")
+        .option("--cursor <cursor>", "Opaque cursor from a previous usage response.")
+        .option("--type <type>", "Filter by transaction type, such as reserve, capture, release, grant, or byok_usage (alias byok).")
+        .option("--category <category>", "Filter by transaction category, such as managed_enrichment, managed_ai, byok, subscription, partner_bonus (the agency partner bonus), or admin.")
+        .option("--provider <provider>", "Filter by provider id. With --meter provider_seats, selects the seat provider: linkedin (default) or whatsapp.")
+        .option("--source <source_id>", "Filter by source_id/provider operation.")
+        .option("--source-id <source_id>", "Alias for --source.")
+        .option("--run-id <run_id>", "Filter by run id recorded in ledger metadata. New settlements preserve the reserve's run id; historical settled charges can omit it. For those older runs, use `table-runs get <run>` (creditsUsed) or `table-runs items`.")
+        .option("--nonzero", "Only include events that changed available or reserved credits.")
+        .option("--workspace <id|slug>", "Only one workspace's spend on a plan that pays for several (credits meter).")
+        .option("--group-by <key>", "workspace: credits spent per workspace on a pooled plan, in by_workspace, for the same filters (credits meter).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing usage", options, () => {
+            const params = buildBillingLedgerParams(options);
+            if (readOption(options.workspace))
+                params.set("workspace", readOption(options.workspace));
+            if (readOption(options.groupBy))
+                params.set("group_by", readOption(options.groupBy));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/billing/usage${suffix}`);
+        });
+    }))
+        .addCommand(new Command("audit")
+        .description("Summarize where managed credits were granted, reserved, captured, released, or spent. Every result lists spend_by_category (each spend area's credits and share of the window's spend, largest first) and totals fixed_credits_spent/flexible_credits_spent over the whole window, whatever --group-by is. groups_truncated says when --limit cut grouped rows, and managed_credits_spent_outside_groups how much they carried. Spent is reserved minus released in the window, so it differs from totals.managed_credits_captured (`billing usage`'s managed_credits_used) because of holds at the window edges and adjustments to reserved credits. Historical events retain their original credit units; windows spanning a re-denomination can mix units. totals.grant_credits is gross grants, excluding refunds and adjustments. byok_usage_events counts only nonzero rows unless --type byok. 0 credits; reserves nothing. Due plan grants or credit expiry may apply.")
+        .option("--days <n>", "Lookback window in days. Defaults to 365.")
+        .option("--from <iso>", "Only include ledger events at or after this ISO timestamp.")
+        .option("--to <iso>", "Only include ledger events at or before this ISO timestamp.")
+        .option("--limit <n>", "Maximum grouped rows to return. Defaults to 100.")
+        .option("--group-by <keys>", "Comma-separated grouping keys (day, type, category, provider, source, tool, model, run, workspace). Defaults to provider,source.")
+        .option("--type <type>", "Filter by transaction type, such as reserve, capture, release, grant, or byok_usage (alias byok).")
+        .option("--category <category>", "Filter by transaction category, such as managed_enrichment, managed_ai, byok, subscription, partner_bonus (the agency partner bonus), or admin.")
+        .option("--provider <provider>", "Filter by provider id.")
+        .option("--source <source_id>", "Filter by source_id/provider operation.")
+        .option("--source-id <source_id>", "Alias for --source.")
+        .option("--run-id <run_id>", "Filter by run id recorded in ledger metadata. New settlements preserve the reserve's run id; historical settled charges can omit it. For those older runs, use `table-runs get <run>` (creditsUsed) or `table-runs items`.")
+        .option("--nonzero", "Only include events that changed available or reserved credits. Default for audit except BYOK filters.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing audit", options, () => {
+            const params = buildBillingLedgerParams(options);
+            if (readOption(options.groupBy))
+                params.set("group_by", readOption(options.groupBy));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/billing/audit${suffix}`);
+        });
+    }))
+        .addCommand(new Command("grant")
+        .description("Grant managed credits to the current organization (staff only).")
+        .requiredOption("--credits <credits>", "Managed credits to grant.")
+        .requiredOption("--idempotency-key <key>", "Stable key that makes retries safe.")
+        .option("--organization-id <id>", "Organization id to credit. Defaults to the current organization.")
+        .option("--org-id <id>", "Alias for --organization-id.")
+        .option("--description <text>", "Ledger description for the admin grant.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing grant", options, () => requestOxygen("/api/cli/billing/grant", {
+            method: "POST",
+            body: {
+                credits: readPositiveNumber(options.credits),
+                idempotency_key: readOption(options.idempotencyKey),
+                ...(readOption(options.organizationId) || readOption(options.orgId)
+                    ? { organization_id: readOption(options.organizationId) ?? readOption(options.orgId) }
+                    : {}),
+                ...(readOption(options.description) ? { description: readOption(options.description) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("reconcile-paid-period")
+        .description("Find active subscriptions whose current billing period was paid in Stripe but never had its plan credits minted, and restore them (staff only). Detect-only unless --apply: every repair is proven by a Stripe paid invoice covering that exact period, so it can only return credits the customer already bought. Re-running is safe — an already-granted period is never granted twice.")
+        .option("--organization-id <id>", "Restrict the sweep to one organization. Defaults to every active subscription.")
+        .option("--org-id <id>", "Alias for --organization-id.")
+        .option("--apply", "Mint the missing grants. Without it, report what would be repaired and change nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing reconcile-paid-period", options, () => requestOxygen("/api/cli/billing/reconcile-paid-period", {
+            method: "POST",
+            body: {
+                apply: Boolean(options.apply),
+                ...(readOption(options.organizationId) || readOption(options.orgId)
+                    ? { organization_id: readOption(options.organizationId) ?? readOption(options.orgId) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("set-plan")
+        .description("Create or update an off-Stripe custom plan for an organization (staff only).")
+        .requiredOption("--organization-id <id>", "Organization id to put on the custom plan.")
+        .requiredOption("--credits <n>", "Monthly managed credits included in the plan.")
+        .option("--org-id <id>", "Alias for --organization-id.")
+        .option("--name <text>", "Display name for the plan, e.g. \"Custom Contract - $250/mo\".")
+        .option("--price <usd>", "Monthly contract price in USD (recorded for display; not charged off-Stripe).")
+        .option("--weekly-credits <n>", "Weekly spend throttle. Defaults to the monthly credits (no throttle).")
+        .option("--rollover <n>", "Max balance credits roll over to. Defaults to the monthly credits.")
+        .option("--base-tier <tier>", "Base pricing tier to inherit feature flags from. Defaults to growth_250.")
+        .option("--byok", "Enable bring-your-own-key integrations for the plan.")
+        .option("--note <text>", "Internal note stored on the contract.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing set-plan", options, () => requestOxygen("/api/cli/billing/set-plan", {
+            method: "POST",
+            body: {
+                organization_id: readOption(options.organizationId) ?? readOption(options.orgId),
+                monthly_credits: readPositiveNumber(options.credits),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.price) ? { price: readPositiveNumber(options.price) } : {}),
+                ...(readOption(options.weeklyCredits)
+                    ? { weekly_credits_limit: readPositiveNumber(options.weeklyCredits) }
+                    : {}),
+                ...(readOption(options.rollover)
+                    ? { rollover_cap: readPositiveNumber(options.rollover) }
+                    : {}),
+                ...(readOption(options.baseTier) ? { base_tier: readOption(options.baseTier) } : {}),
+                ...(options.byok ? { byok: true } : {}),
+                ...(readOption(options.note) ? { note: readOption(options.note) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Turn off subscription renewal. For a yearly commitment paid monthly, remaining monthly payments continue through commitment_ends_at; the plan stays usable until then. Other plans end at their paid period or trial end with no further subscription renewal charge. This command costs no Oxygen credits. Separately funded external resources keep renewing; preview `workspace infrastructure-exit` to end those too. Prints the end date; undo before then with billing resume.")
+        .option("--comment <text>", "Written cancellation feedback (1–2,000 characters).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing cancel", options, () => requestOxygen("/api/cli/billing/cancel", {
+            method: "POST",
+            body: { action: "cancel", ...(options.comment !== undefined ? { comment: options.comment } : {}) },
+        }));
+    }))
+        .addCommand(new Command("resume")
+        .description("Remove a scheduled cancellation so the subscription renews (or the trial converts) normally. Free (no fee, no credits). Prints the next charge date and amount.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing resume", options, () => requestOxygen("/api/cli/billing/cancel", {
+            method: "POST",
+            body: { action: "resume" },
+        }));
+    }))
+        .addCommand(new Command("retention-offer")
+        .description("Preview a one-month discount before cancelling your monthly subscription. Reports eligibility, the next invoice price and normal price. Reads only; no discount is applied.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing retention-offer", options, () => requestOxygen("/api/cli/billing/cancel", { method: "POST", body: { action: "offer" } }));
+    }))
+        .addCommand(new Command("retain")
+        .description("Stay subscribed with the one-month retention discount from billing retention-offer. Restores renewal if cancellation was scheduled. No charge today; the normal price returns afterwards.")
+        .requiredOption("--offer <id>", "The offer_id from the retention offer preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("billing retain", options, () => requestOxygen("/api/cli/billing/cancel", { method: "POST", body: { action: "retain", offer_id: options.offer } }));
+    }))
+        .addCommand(new Command("topup")
+        .description("No amount: read-only price quote, no checkout. With --credits or a pack: create Stripe Checkout and possibly billing resources; no charge until payment. Read tax_basis and review tax and the final total in Checkout. Prices are per 100 credits (`usd_per_100_credits`); credits arrive after confirmed payment and never expire. Plan credits cost less. `usd_per_1k_credits` is a deprecated name for the same per-100 price, not a price per 1,000 credits. `default_credits` is the web form's initial custom selection, not a purchase or minimum.")
+        .argument("[pack]", "A pack id from the list shown when you run without an amount.")
+        .option("--credits <n>", "Credits to buy (800-100,000 in 100-credit increments).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (pack, options) => {
+        const credits = readOption(options.credits);
+        await handleAsyncAction("billing topup", options, () => pack || credits
+            ? requestOxygen("/api/cli/billing/topup", {
+                method: "POST",
+                body: {
+                    ...(pack ? { pack } : {}),
+                    ...(credits ? { credits: readPositiveNumber(credits) } : {}),
+                },
+            })
+            : requestOxygen("/api/cli/billing/topup"));
+    }));
+}

package/dist/commands/blueprints.d.ts

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