@indigoai-us/hq-cli 5.62.2 → 5.63.0

package/src/commands/billing.ts

@@ -0,0 +1,146 @@
+/**
+ * `hq billing` — inspect billing state and mint a card-capture link from the
+ * terminal. Backs the paid-provisioning gate (agents & Outposts): a user can
+ * check whether a card is on file, and proactively hand out the same Stripe
+ * hosted card-capture link that a `402 billing_required` would surface.
+ *
+ * Targets the hq-pro billing control plane on `DEFAULT_VAULT_API_URL` via the
+ * shared `vaultApiFetch` helper — the same routes the console billing surfaces
+ * call.
+ *
+ * Subcommands:
+ *   hq billing status   [--company <slug>]              — subscription + card on file
+ *   hq billing checkout [--company <slug>] [--personal] — mint a card-capture link
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { mintPaymentLink, type BillingSetupAction } from "../utils/billing-gate.js";
+
+/** Shape of `GET /v1/billing/summary` we render. */
+interface BillingSummary {
+  subscriptionStatus: string | null;
+  defaultPaymentMethod: {
+    present: boolean;
+    brand: string | null;
+    last4: string | null;
+  };
+  [key: string]: unknown;
+}
+
+function fail(err: unknown): never {
+  console.error(
+    chalk.red("Error:"),
+    err instanceof Error ? err.message : String(err),
+  );
+  process.exit(1);
+}
+
+async function getBillingSummary(
+  token: string,
+  companyUid: string,
+): Promise<BillingSummary> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/billing/summary",
+    query: { companyUid },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: string;
+      message?: string;
+    };
+    throw new Error(body.error ?? body.message ?? res.statusText);
+  }
+  return (await res.json()) as BillingSummary;
+}
+
+export function registerBillingCommand(program: Command): void {
+  const billing = program
+    .command("billing")
+    .description("Inspect billing and mint a card-capture link")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  const companyOf = (sub: Command): string | undefined =>
+    (sub.opts().company as string | undefined) ??
+    (billing.opts().company as string | undefined);
+
+  billing
+    .command("status")
+    .description("Show subscription status and whether a card is on file")
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (this: Command, opts: { json?: boolean }) {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(token, companyOf(this));
+        const summary = await getBillingSummary(token, companyUid);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+          return;
+        }
+        const sub = summary.subscriptionStatus ?? "none";
+        console.log(`${chalk.bold("Subscription")}: ${sub}`);
+        const pm = summary.defaultPaymentMethod;
+        if (pm?.present) {
+          const detail =
+            pm.brand && pm.last4 ? `${pm.brand} ••••${pm.last4}` : "on file";
+          console.log(`${chalk.bold("Card")}: ${detail}`);
+        } else {
+          console.log(
+            `${chalk.bold("Card")}: ${chalk.yellow("no card on file")} — ` +
+              `run \`hq billing checkout\` to add one before provisioning paid resources.`,
+          );
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  billing
+    .command("checkout")
+    .description("Mint a Stripe card-capture link (shareable) to add a card")
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option(
+      "--personal",
+      "Mint the link for your personal payer (Outposts) instead of a company",
+    )
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { personal?: boolean; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        let setup: BillingSetupAction;
+        if (opts.personal) {
+          setup = {
+            payerType: "person",
+            path: "/v1/billing/checkout/person",
+            method: "POST",
+          };
+        } else {
+          const companyUid = await getCompanyUid(token, companyOf(this));
+          setup = {
+            payerType: "company",
+            path: "/v1/billing/checkout/org",
+            method: "POST",
+            body: { companyUid },
+          };
+        }
+        const url = await mintPaymentLink(token, setup);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify({ url }, null, 2) + "\n");
+          return;
+        }
+        console.log(
+          "Add a card here (safe to share with whoever owns billing):\n  " +
+            chalk.cyan(url),
+        );
+      } catch (err) {
+        fail(err);
+      }
+    });
+}

package/src/commands/members.test.ts

@@ -1194,6 +1194,24 @@ describe("registerMembersCommand promote", () => {
 // ---------------------------------------------------------------------------
 
 describe("resolveRevokeTargetToMembershipKey", () => {
+  it("wraps fleet agent uids as agt_…#companyUid", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey(
+        "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+        "cmp_abc",
+      ),
+    ).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX#cmp_abc");
+  });
+
+  it("maps agent machine emails to agt_…#companyUid (active guest memberships)", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey(
+        "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+        "cmp_abc",
+      ),
+    ).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX#cmp_abc");
+  });
+
   // Regression: `hq members revoke alice@example.com` used to send the raw
   // email straight to /membership/revoke, which the server rejects with 404
   // "Invite not found" because it keys on `email:<email>#<companyUid>`. Live

package/src/commands/members.ts

@@ -494,9 +494,16 @@ export function resolveRevokeTargetToMembershipKey(
   if (arg.includes("#")) return arg;
   const detected = detectTarget(arg);
   if (detected?.type === "email") {
+    // Active agent guest memberships are personUid-keyed (agt_…#cmp_…), not
+    // email-keyed. Map machine emails to that key so revoke works after invite.
+    if (detected.isAgent) {
+      const local = detected.value.split("@")[0] ?? "";
+      const m = local.match(/^agt-(.+)$/i);
+      if (m) return `agt_${m[1].toUpperCase()}#${companyUid}`;
+    }
     return `email:${detected.value}#${companyUid}`;
   }
-  if (detected?.type === "person") {
+  if (detected?.type === "person" || detected?.type === "agent") {
     return `${detected.value}#${companyUid}`;
   }
   return arg;

package/src/commands/outposts.test.ts

@@ -27,6 +27,21 @@ vi.mock("../utils/cognito-session.js", async (importOriginal) => {
   };
 });
 
+// Outpost provision reads the cached refresh token to send to the box. Stub the
+// hq-cloud token store so tests don't need a real session on disk.
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return {
+    ...original,
+    loadCachedTokens: vi.fn(() => ({
+      refreshToken: "rt_test",
+      idToken: "id_test",
+      accessToken: "at_test",
+    })),
+  };
+});
+
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { registerOutpostsCommand } from "./outposts.js";
 
@@ -175,3 +190,58 @@ describe("hq outposts destroy", () => {
     ).rejects.toThrow("process.exit(1)");
   });
 });
+
+describe("hq outposts 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(["outposts", "provision"])).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(/\$80\.00\/month/);
+  });
+
+  it("POSTs /outpost/provision with the refresh token when --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+    await run(["outposts", "provision", "--runtime", "codex", "--yes"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/provision");
+    expect(init?.method).toBe("POST");
+    const sent = JSON.parse(init?.body as string);
+    expect(sent.refreshToken).toBe("rt_test");
+    expect(sent.agentRuntime).toBe("codex");
+  });
+
+  it("mints a card-capture link on 402 billing_required and exits 1", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          billing: {
+            status: "billing_required",
+            setup: {
+              payerType: "person",
+              path: "/v1/billing/checkout/person",
+              method: "POST",
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/outpost" }),
+      );
+
+    await expect(
+      run(["outposts", "provision", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    expect(String(fetchSpy.mock.calls[1][0])).toContain(
+      "/v1/billing/checkout/person",
+    );
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/outpost");
+  });
+});

package/src/commands/outposts.ts

@@ -23,18 +23,34 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import {
+  OUTPOST_PRICE_CENTS,
+  confirmChargeOrExit,
+  parseBillingPayload,
+  surfaceBillingRequired,
+  type BillingErrorPayload,
+} from "../utils/billing-gate.js";
 
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export class OutpostHttpError extends Error {
   status: number;
   step?: string;
-  constructor(status: number, message: string, step?: string) {
+  /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+  billing?: BillingErrorPayload;
+  constructor(
+    status: number,
+    message: string,
+    step?: string,
+    billing?: BillingErrorPayload,
+  ) {
     super(message);
     this.name = "OutpostHttpError";
     this.status = status;
     this.step = step;
+    this.billing = billing;
   }
 }
 
@@ -61,6 +77,7 @@ export async function outpostRequest<T>(opts: {
   token: string;
   path: string;
   method?: string;
+  body?: Record<string, unknown>;
   query?: Record<string, string>;
 }): Promise<T> {
   const res = await vaultApiFetch(opts);
@@ -76,11 +93,45 @@ export async function outpostRequest<T>(opts: {
         : typeof body.error === "string"
           ? body.error
           : res.statusText;
-    throw new OutpostHttpError(res.status, message, body.step);
+    throw new OutpostHttpError(
+      res.status,
+      message,
+      body.step,
+      parseBillingPayload(body),
+    );
   }
   return (await res.json()) as T;
 }
 
+/**
+ * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
+ * box can authenticate AS the caller (the same body the console's
+ * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
+ * per-person cap gets their existing box back rather than a duplicate. The
+ * refresh token is sent over HTTPS and NEVER printed.
+ */
+export async function provisionOutpost(
+  token: string,
+  input: {
+    refreshToken: string;
+    clientIp?: string;
+    diskSizeGb?: number;
+    agentRuntime?: "claude" | "codex";
+  },
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/provision",
+    method: "POST",
+    body: {
+      refreshToken: input.refreshToken,
+      ...(input.clientIp ? { clientIp: input.clientIp } : {}),
+      ...(input.diskSizeGb ? { diskSizeGb: input.diskSizeGb } : {}),
+      ...(input.agentRuntime ? { agentRuntime: input.agentRuntime } : {}),
+    },
+  });
+}
+
 export async function listOutposts(token: string): Promise<OutpostSummary[]> {
   const data = await outpostRequest<{ outposts: OutpostSummary[] }>({
     token,
@@ -165,6 +216,81 @@ export function registerOutpostsCommand(program: Command): void {
     .command("outposts")
     .description("Manage your personal HQ Outposts (EC2 boxes)");
 
+  outposts
+    .command("provision")
+    .alias("create")
+    .description("Provision a new Outpost ($80/month — requires --yes)")
+    .option("--runtime <runtime>", "Agent runtime: claude | codex (default claude)")
+    .option("--disk <gb>", "Root disk size in GB (EC2 only)")
+    .option(
+      "--client-ip <ip>",
+      "Your public IP for the box's SSH ingress (optional; server derives it otherwise)",
+    )
+    .option("--yes", "Confirm the $80/month charge (required to provision)")
+    .action(async function (
+      this: Command,
+      opts: { runtime?: string; disk?: string; clientIp?: string; yes?: boolean },
+    ) {
+      try {
+        const agentRuntime =
+          opts.runtime === "codex"
+            ? "codex"
+            : opts.runtime
+              ? "claude"
+              : undefined;
+        let diskSizeGb: number | undefined;
+        if (opts.disk !== undefined) {
+          diskSizeGb = Number(opts.disk);
+          if (!Number.isFinite(diskSizeGb) || diskSizeGb <= 0) {
+            console.error(chalk.red(`Invalid --disk '${opts.disk}': must be a positive number of GB.`));
+            process.exit(1);
+          }
+        }
+
+        // Paid gate: print the monthly cost and require --yes before any call.
+        confirmChargeOrExit({
+          resource: "Outpost",
+          unitCents: OUTPOST_PRICE_CENTS,
+          yes: opts.yes,
+        });
+
+        // The box authenticates AS the caller using the cached refresh token —
+        // the same body the console sends. Never printed.
+        const refreshToken = loadCachedTokens()?.refreshToken;
+        if (!refreshToken) {
+          console.error(
+            chalk.red("No cached session found — run `hq login` first, then re-run."),
+          );
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        try {
+          await provisionOutpost(token, {
+            refreshToken,
+            ...(opts.clientIp ? { clientIp: opts.clientIp } : {}),
+            ...(diskSizeGb ? { diskSizeGb } : {}),
+            ...(agentRuntime ? { agentRuntime } : {}),
+          });
+          console.log(chalk.green("Provisioning started for your Outpost."));
+          console.log(chalk.dim("Track it: hq outposts status"));
+        } catch (err) {
+          // No card on file → surface the shareable payment link, not an opaque 402.
+          if (
+            err instanceof OutpostHttpError &&
+            err.status === 402 &&
+            err.billing
+          ) {
+            await surfaceBillingRequired(token, err.billing);
+            process.exit(1);
+          }
+          throw err;
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   outposts
     .command("list")
     .description("List every Outpost you own")

package/src/main.ts

@@ -56,6 +56,7 @@ import { registerCrmCommand } from "./commands/crm.js";
 import { registerCompanyCommand } from "./commands/company.js";
 import { registerAgentsCommand } from "./commands/agents.js";
 import { registerOutpostsCommand } from "./commands/outposts.js";
+import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
@@ -258,6 +259,11 @@ registerAgentsCommand(program);
 // /outpost/* control plane.
 registerOutpostsCommand(program);
 
+// Billing (subcommand group — `hq billing …`). Check subscription/card state and
+// mint a shareable Stripe card-capture link — the client side of the paid-
+// provisioning gate for agents & Outposts.
+registerBillingCommand(program);
+
 export async function runCli(): Promise<void> {
   try {
     Sentry.addBreadcrumb({

package/src/utils/billing-gate.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for the billing-gate helpers (pure parsers + price formatting).
+ * The command-level flows are covered in commands/{agents,outposts,billing}.test.ts;
+ * this pins the trust-boundary parsing and the cost string.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  AGENT_PRICE_CENTS,
+  OUTPOST_PRICE_CENTS,
+  formatUsd,
+  isBillingSetupAction,
+  parseBillingPayload,
+} from "./billing-gate.js";
+
+describe("prices", () => {
+  it("match the console's authoritative constants", () => {
+    expect(AGENT_PRICE_CENTS).toBe(10_000);
+    expect(OUTPOST_PRICE_CENTS).toBe(8_000);
+  });
+});
+
+describe("formatUsd", () => {
+  it("renders cents as $X.YZ", () => {
+    expect(formatUsd(10_000)).toBe("$100.00");
+    expect(formatUsd(8_000)).toBe("$80.00");
+    expect(formatUsd(0)).toBe("$0.00");
+  });
+  it("clamps negatives to zero", () => {
+    expect(formatUsd(-500)).toBe("$0.00");
+  });
+});
+
+describe("isBillingSetupAction", () => {
+  it("accepts a valid org setup", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "company",
+        path: "/v1/billing/checkout/org",
+        method: "POST",
+        body: { companyUid: "cmp_x" },
+      }),
+    ).toBe(true);
+  });
+  it("accepts a valid person setup with no body", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "person",
+        path: "/v1/billing/checkout/person",
+        method: "POST",
+      }),
+    ).toBe(true);
+  });
+  it("rejects unknown paths / shapes", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "company",
+        path: "/v1/billing/checkout/evil",
+        method: "POST",
+      }),
+    ).toBe(false);
+    expect(isBillingSetupAction(null)).toBe(false);
+    expect(isBillingSetupAction({ payerType: "company" })).toBe(false);
+  });
+});
+
+describe("parseBillingPayload", () => {
+  it("extracts status + setup from a 402 body", () => {
+    const parsed = parseBillingPayload({
+      error: "payment required",
+      billing: {
+        status: "billing_required",
+        setup: {
+          payerType: "company",
+          path: "/v1/billing/checkout/org",
+          method: "POST",
+          body: { companyUid: "cmp_x" },
+        },
+      },
+    });
+    expect(parsed?.status).toBe("billing_required");
+    expect(parsed?.setup?.path).toBe("/v1/billing/checkout/org");
+  });
+  it("returns status with no setup when the setup is malformed", () => {
+    const parsed = parseBillingPayload({
+      billing: { status: "billing_required", setup: { bogus: true } },
+    });
+    expect(parsed?.status).toBe("billing_required");
+    expect(parsed?.setup).toBeUndefined();
+  });
+  it("returns undefined for a non-billing error body", () => {
+    expect(parseBillingPayload({ error: "forbidden" })).toBeUndefined();
+    expect(parseBillingPayload(null)).toBeUndefined();
+  });
+});