@indigoai-us/hq-cli 5.62.2 → 5.64.0

package/dist/utils/billing-gate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Billing gate for paid provisioning (agents & Outposts).
+ *
+ * hq-pro enforces billing server-side: a provision call for a resource whose
+ * payer has no card on file returns `402` with a `billing` payload carrying a
+ * `setup` action that names EXACTLY which checkout endpoint to hit. That
+ * endpoint returns `{ url }` — a Stripe-hosted card-capture link.
+ *
+ * This module wires the client-side experience around that contract:
+ *   1. `confirmChargeOrExit` — print the monthly cost and require `--yes`
+ *      BEFORE any paid provisioning call is made.
+ *   2. `surfaceBillingRequired` — when the backend answers `402 billing_required`,
+ *      mint the card-capture link and print a plain, shareable message instead
+ *      of an opaque failure.
+ *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
+ *      to hand out the same link proactively.
+ *
+ * Prices mirror the console's authoritative constants
+ * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
+ * currency unit (US cents) to match Stripe's wire shape.
+ */
+/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+export declare const AGENT_PRICE_CENTS = 10000;
+/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+export declare const OUTPOST_PRICE_CENTS = 8000;
+/** Render a cents amount as a `$X.YZ` USD string. */
+export declare function formatUsd(cents: number): string;
+/**
+ * The server-supplied "how to add a card" action on a `402 billing_required`.
+ * Mirrors hq-pro `src/billing/activation-billing.ts` `BillingSetupAction` and
+ * the console's `src/lib/billing-setup.ts`.
+ */
+export interface BillingSetupAction {
+    payerType: "company" | "person";
+    path: "/v1/billing/checkout/org" | "/v1/billing/checkout/person";
+    method: "POST";
+    body?: {
+        companyUid?: string;
+    };
+}
+/** The `billing` envelope hq-pro attaches to a billing-blocked provision. */
+export interface BillingErrorPayload {
+    status: string;
+    setup?: BillingSetupAction;
+}
+/** Narrow an unknown value to a usable `BillingSetupAction`. */
+export declare function isBillingSetupAction(value: unknown): value is BillingSetupAction;
+/** Pull a `BillingErrorPayload` out of a decoded hq-pro error body, if present. */
+export declare function parseBillingPayload(body: unknown): BillingErrorPayload | undefined;
+export type PaidResource = "agent" | "Outpost";
+/**
+ * Gate a paid provisioning call behind an explicit, informed `--yes`. Prints the
+ * monthly charge in full prose (this is a paid, outward action — Auto-Clarity)
+ * and exits non-zero when the caller has not passed `--yes`. Returns normally
+ * once approved so the caller proceeds to provision.
+ */
+export declare function confirmChargeOrExit(opts: {
+    resource: PaidResource;
+    unitCents: number;
+    quantity?: number;
+    yes?: boolean;
+}): void;
+/**
+ * Mint a Stripe-hosted card-capture link for a `BillingSetupAction`. Returns the
+ * hosted URL the payer opens to add a card. Throws on a non-2xx (the caller
+ * decides how to surface it) — never swallows.
+ */
+export declare function mintPaymentLink(token: string, setup: BillingSetupAction): Promise<string>;
+/**
+ * The provision was blocked because the payer has no card on file. Mint the
+ * card-capture link the backend pointed us at and print a plain, shareable
+ * message so the user can add a card (or hand the link to whoever owns billing)
+ * and re-run. Returns the URL, or `null` when the server gave no `setup` action
+ * to act on. Never prints tokens or secrets.
+ */
+export declare function surfaceBillingRequired(token: string, billing: BillingErrorPayload): Promise<string | null>;
+//# sourceMappingURL=billing-gate.d.ts.map

package/dist/utils/billing-gate.js

@@ -0,0 +1,127 @@
+/**
+ * Billing gate for paid provisioning (agents & Outposts).
+ *
+ * hq-pro enforces billing server-side: a provision call for a resource whose
+ * payer has no card on file returns `402` with a `billing` payload carrying a
+ * `setup` action that names EXACTLY which checkout endpoint to hit. That
+ * endpoint returns `{ url }` — a Stripe-hosted card-capture link.
+ *
+ * This module wires the client-side experience around that contract:
+ *   1. `confirmChargeOrExit` — print the monthly cost and require `--yes`
+ *      BEFORE any paid provisioning call is made.
+ *   2. `surfaceBillingRequired` — when the backend answers `402 billing_required`,
+ *      mint the card-capture link and print a plain, shareable message instead
+ *      of an opaque failure.
+ *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
+ *      to hand out the same link proactively.
+ *
+ * Prices mirror the console's authoritative constants
+ * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
+ * currency unit (US cents) to match Stripe's wire shape.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89efd1d4-af26-50e1-b94f-72b1b5533e3f")}catch(e){}}();
+import chalk from "chalk";
+import { vaultApiFetch } from "./vault-api.js";
+/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+export const AGENT_PRICE_CENTS = 10_000;
+/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+export const OUTPOST_PRICE_CENTS = 8_000;
+/** Render a cents amount as a `$X.YZ` USD string. */
+export function formatUsd(cents) {
+    return `$${(Math.max(0, Math.round(cents)) / 100).toFixed(2)}`;
+}
+/** Narrow an unknown value to a usable `BillingSetupAction`. */
+export function isBillingSetupAction(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const setup = value;
+    const body = setup.body;
+    return ((setup.payerType === "company" || setup.payerType === "person") &&
+        (setup.path === "/v1/billing/checkout/org" ||
+            setup.path === "/v1/billing/checkout/person") &&
+        setup.method === "POST" &&
+        (body === undefined || (typeof body === "object" && body !== null)));
+}
+/** Pull a `BillingErrorPayload` out of a decoded hq-pro error body, if present. */
+export function parseBillingPayload(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const raw = body.billing;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const status = raw.status;
+    if (typeof status !== "string")
+        return undefined;
+    const setup = raw.setup;
+    return {
+        status,
+        ...(isBillingSetupAction(setup) ? { setup } : {}),
+    };
+}
+/**
+ * Gate a paid provisioning call behind an explicit, informed `--yes`. Prints the
+ * monthly charge in full prose (this is a paid, outward action — Auto-Clarity)
+ * and exits non-zero when the caller has not passed `--yes`. Returns normally
+ * once approved so the caller proceeds to provision.
+ */
+export function confirmChargeOrExit(opts) {
+    const quantity = opts.quantity ?? 1;
+    const total = opts.unitCents * quantity;
+    const each = quantity > 1 ? ` (${formatUsd(opts.unitCents)} each × ${quantity})` : "";
+    const noun = quantity > 1 ? `${opts.resource}s` : opts.resource;
+    const article = /^[aeiou]/i.test(opts.resource) ? "an" : "a";
+    const subject = quantity > 1 ? `${quantity} ${noun}` : `${article} ${noun}`;
+    if (!opts.yes) {
+        console.error(chalk.yellow(`Provisioning ${subject} adds a recurring charge of ` +
+            `${formatUsd(total)}/month${each} to the payer on file. This is a ` +
+            `paid resource.\n` +
+            `Re-run with --yes to confirm you want to incur this charge.`));
+        process.exit(1);
+    }
+    console.log(chalk.dim(`Confirmed: ${formatUsd(total)}/month for ${quantity} ${noun}. Provisioning…`));
+}
+/**
+ * Mint a Stripe-hosted card-capture link for a `BillingSetupAction`. Returns the
+ * hosted URL the payer opens to add a card. Throws on a non-2xx (the caller
+ * decides how to surface it) — never swallows.
+ */
+export async function mintPaymentLink(token, setup) {
+    const res = await vaultApiFetch({
+        token,
+        path: setup.path,
+        method: "POST",
+        body: setup.body?.companyUid ? { companyUid: setup.body.companyUid } : {},
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`Failed to mint a payment link: ${body.error ?? body.message ?? res.statusText}`);
+    }
+    const data = (await res.json());
+    if (!data.url) {
+        throw new Error("Payment link response did not include a checkout URL.");
+    }
+    return data.url;
+}
+/**
+ * The provision was blocked because the payer has no card on file. Mint the
+ * card-capture link the backend pointed us at and print a plain, shareable
+ * message so the user can add a card (or hand the link to whoever owns billing)
+ * and re-run. Returns the URL, or `null` when the server gave no `setup` action
+ * to act on. Never prints tokens or secrets.
+ */
+export async function surfaceBillingRequired(token, billing) {
+    if (!billing.setup) {
+        console.error(chalk.yellow("Provisioning is blocked on billing, but the server didn't return a " +
+            "payment link. Add a card in the console billing page, then re-run."));
+        return null;
+    }
+    const url = await mintPaymentLink(token, billing.setup);
+    console.log(chalk.yellow("No card on file — provisioning is blocked until one is added."));
+    console.log("Add a card here (safe to share with whoever owns billing):\n  " +
+        chalk.cyan(url));
+    console.log(chalk.dim("Once a card is added, re-run the same command."));
+    return url;
+}
+//# sourceMappingURL=billing-gate.js.map
+//# debugId=89efd1d4-af26-50e1-b94f-72b1b5533e3f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.62.2",
+  "version": "5.64.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/agents.test.ts

@@ -295,3 +295,87 @@ describe("hq agents status", () => {
     ).rejects.toThrow("process.exit(1)");
   });
 });
+
+describe("hq agents provision (billing gate)", () => {
+  it("refuses without --yes, prints the cost, and makes NO API call", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot"]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+    const printed = errSpy.mock.calls
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toMatch(/\$100\.00\/month/);
+  });
+
+  it("POSTs /v1/agents with slugified name + idempotency key when --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { uid: "agt_new", slug: "ops-bot" }),
+    );
+    await run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/agents");
+    expect(init?.method).toBe("POST");
+    const sent = JSON.parse(init?.body as string);
+    expect(sent.companyUid).toBe("cmp_acme");
+    expect(sent.name).toBe("Ops Bot");
+    expect(sent.slug).toBe("ops-bot");
+    expect(sent.codexAuthMode).toBe("subscription");
+    expect(typeof sent.idempotencyKey).toBe("string");
+    expect(sent.idempotencyKey.length).toBeGreaterThan(0);
+  });
+
+  it("mints a card-capture link on 402 billing_required and exits 1", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          code: "BILLING_REQUIRED",
+          billing: {
+            status: "billing_required",
+            setup: {
+              payerType: "company",
+              path: "/v1/billing/checkout/org",
+              method: "POST",
+              body: { companyUid: "cmp_acme" },
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/card" }),
+      );
+
+    const logSpyLocal = vi.spyOn(console, "log").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    // Second call mints the checkout link the 402 pointed at.
+    expect(String(fetchSpy.mock.calls[1][0])).toContain(
+      "/v1/billing/checkout/org",
+    );
+    expect(JSON.parse(fetchSpy.mock.calls[1][1]?.body as string)).toEqual({
+      companyUid: "cmp_acme",
+    });
+    const printed = logSpyLocal.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/card");
+  });
+
+  it("requires --api-key-env for --auth-mode apiKey (before any charge)", async () => {
+    await expect(
+      run([
+        "agents",
+        "--company",
+        "acme",
+        "provision",
+        "Ops Bot",
+        "--auth-mode",
+        "apiKey",
+        "--yes",
+      ]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/agents.ts

@@ -24,8 +24,16 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import {
+  AGENT_PRICE_CENTS,
+  confirmChargeOrExit,
+  parseBillingPayload,
+  surfaceBillingRequired,
+  type BillingErrorPayload,
+} from "../utils/billing-gate.js";
 
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -47,11 +55,19 @@ export const VALID_TIERS = new Set(["default", "priority"]);
 export class AgentsHttpError extends Error {
   status: number;
   code?: string;
-  constructor(status: number, message: string, code?: string) {
+  /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+  billing?: BillingErrorPayload;
+  constructor(
+    status: number,
+    message: string,
+    code?: string,
+    billing?: BillingErrorPayload,
+  ) {
     super(message);
     this.name = "AgentsHttpError";
     this.status = status;
     this.code = code;
+    this.billing = billing;
   }
 }
 
@@ -111,11 +127,45 @@ export async function agentsRequest<T>(opts: {
       res.status,
       body.error ?? body.message ?? res.statusText,
       body.code,
+      parseBillingPayload(body),
     );
   }
   return (await res.json()) as T;
 }
 
+/** Slugify an agent name into a lowercase, hyphen-separated slug. */
+export function slugifyAgentName(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export interface ProvisionAgentInput {
+  companyUid: string;
+  name: string;
+  slug: string;
+  codexAuthMode: "subscription" | "apiKey";
+  provider?: "codex" | "grok";
+  codexApiKey?: string;
+  idempotencyKey: string;
+  title?: string;
+  description?: string;
+}
+
+export async function provisionAgent(
+  token: string,
+  input: ProvisionAgentInput,
+): Promise<{ uid?: string; slug?: string; [key: string]: unknown }> {
+  return agentsRequest({
+    token,
+    path: "/v1/agents",
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+  });
+}
+
 export async function listAgents(
   token: string,
   companyUid: string,
@@ -244,6 +294,112 @@ export function registerAgentsCommand(program: Command): void {
     (sub.opts().company as string | undefined) ??
     (agents.opts().company as string | undefined);
 
+  agents
+    .command("provision <name>")
+    .alias("new")
+    .description("Provision a new cloud agent ($100/month — requires --yes)")
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
+    .option("--provider <provider>", "Runtime: codex | grok (default codex)")
+    .option(
+      "--auth-mode <mode>",
+      "Codex auth: subscription | apiKey (default subscription)",
+      "subscription",
+    )
+    .option(
+      "--api-key-env <VAR>",
+      "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)",
+    )
+    .option("--title <title>", "Org-chart job title")
+    .option("--description <text>", "Short description / bio")
+    .option("--yes", "Confirm the $100/month charge (required to provision)")
+    .action(async function (
+      this: Command,
+      name: string,
+      opts: {
+        slug?: string;
+        provider?: string;
+        authMode?: string;
+        apiKeyEnv?: string;
+        title?: string;
+        description?: string;
+        yes?: boolean;
+      },
+    ) {
+      try {
+        const authMode = opts.authMode === "apiKey" ? "apiKey" : "subscription";
+        const provider =
+          opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined;
+
+        // Resolve the API key from the environment (never from a flag value) when
+        // apiKey mode is requested — validated BEFORE the paid gate so we don't
+        // charge and then fail.
+        let codexApiKey: string | undefined;
+        if (authMode === "apiKey") {
+          const envVar = opts.apiKeyEnv;
+          if (!envVar) {
+            console.error(
+              chalk.red(
+                "--auth-mode apiKey requires --api-key-env <VAR> naming the env var that holds the key.",
+              ),
+            );
+            process.exit(1);
+          }
+          codexApiKey = process.env[envVar];
+          if (!codexApiKey) {
+            console.error(
+              chalk.red(`Env var ${envVar} is empty or unset — no API key to use.`),
+            );
+            process.exit(1);
+          }
+        }
+
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(token, companyOf(this));
+
+        // Paid gate: print the monthly cost and require --yes before any call.
+        confirmChargeOrExit({
+          resource: "agent",
+          unitCents: AGENT_PRICE_CENTS,
+          yes: opts.yes,
+        });
+
+        const slug = opts.slug ?? slugifyAgentName(name);
+        try {
+          const result = await provisionAgent(token, {
+            companyUid,
+            name,
+            slug,
+            codexAuthMode: authMode,
+            ...(provider ? { provider } : {}),
+            ...(codexApiKey ? { codexApiKey } : {}),
+            idempotencyKey: `hq-cli-${randomUUID()}`,
+            ...(opts.title ? { title: opts.title } : {}),
+            ...(opts.description ? { description: opts.description } : {}),
+          });
+          const uid = typeof result.uid === "string" ? result.uid : slug;
+          console.log(chalk.green(`Provisioning started for agent "${name}".`));
+          console.log(
+            chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`),
+          );
+        } catch (err) {
+          // No card on file → surface the shareable payment link instead of an
+          // opaque 402, then exit non-zero so scripts can react.
+          if (
+            err instanceof AgentsHttpError &&
+            err.status === 402 &&
+            err.billing
+          ) {
+            await surfaceBillingRequired(token, err.billing);
+            process.exit(1);
+          }
+          throw err;
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   agents
     .command("list")
     .description("List the company's agents")

package/src/commands/billing.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for `hq billing` (billing.ts).
+ *
+ * Mirrors company.test.ts: mock ensureCognitoToken + getCompanyUid, spy on
+ * global fetch, drive through a Commander program, assert the request shape and
+ * rendered output.
+ */
+
+import { Command } from "commander";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("../utils/cognito-session.js")>();
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+vi.mock("../utils/vault-api.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../utils/vault-api.js")>();
+  return {
+    ...original,
+    getCompanyUid: vi.fn(async () => "cmp_acme"),
+  };
+});
+
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { registerBillingCommand } from "./billing.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let logSpy: MockInstance<typeof console.log>;
+let stdoutSpy: MockInstance<typeof process.stdout.write>;
+const mockEnsureCognitoToken = vi.mocked(ensureCognitoToken);
+const mockGetCompanyUid = vi.mocked(getCompanyUid);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  mockEnsureCognitoToken.mockResolvedValue("test-token");
+  mockGetCompanyUid.mockResolvedValue("cmp_acme");
+  vi.spyOn(process, "exit").mockImplementation((code?: number) => {
+    throw new Error(`process.exit(${code})`);
+  });
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.name("hq").exitOverride();
+  registerBillingCommand(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<void> {
+  await buildProgram().parseAsync(["node", "hq", ...args]);
+}
+
+describe("hq billing status", () => {
+  it("GETs /v1/billing/summary and renders card-on-file", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        subscriptionStatus: "active",
+        defaultPaymentMethod: { present: true, brand: "visa", last4: "4242" },
+      }),
+    );
+
+    await run(["billing", "--company", "acme", "status"]);
+
+    const url = String(fetchSpy.mock.calls[0][0]);
+    expect(url).toContain("/v1/billing/summary");
+    expect(url).toContain("companyUid=cmp_acme");
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/active/);
+    expect(printed).toMatch(/visa/);
+    expect(printed).toMatch(/4242/);
+  });
+
+  it("flags no card on file", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        subscriptionStatus: null,
+        defaultPaymentMethod: { present: false, brand: null, last4: null },
+      }),
+    );
+    await run(["billing", "--company", "acme", "status"]);
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/no card on file/i);
+  });
+});
+
+describe("hq billing checkout", () => {
+  it("POSTs /v1/billing/checkout/org with companyUid and prints the url", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/abc" }),
+    );
+
+    await run(["billing", "--company", "acme", "checkout"]);
+
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/billing/checkout/org");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(init?.body as string)).toEqual({ companyUid: "cmp_acme" });
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/abc");
+  });
+
+  it("POSTs /v1/billing/checkout/person with --personal", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/xyz" }),
+    );
+    await run(["billing", "checkout", "--personal"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/billing/checkout/person");
+    expect(init?.method).toBe("POST");
+    // Person checkout resolves the payer from the JWT — no companyUid resolution.
+    expect(mockGetCompanyUid).not.toHaveBeenCalled();
+  });
+
+  it("emits raw JSON with --json", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/j" }),
+    );
+    await run(["billing", "--company", "acme", "checkout", "--json"]);
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/j");
+  });
+
+  it("exits 1 when the checkout response has no url", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await expect(
+      run(["billing", "--company", "acme", "checkout"]),
+    ).rejects.toThrow("process.exit(1)");
+  });
+});