@indigoai-us/hq-cli 5.62.1 → 5.63.0

package/src/utils/billing-gate.ts

@@ -0,0 +1,182 @@
+/**
+ * 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.
+ */
+
+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: number): string {
+  return `$${(Math.max(0, Math.round(cents)) / 100).toFixed(2)}`;
+}
+
+/**
+ * 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 function isBillingSetupAction(value: unknown): value is BillingSetupAction {
+  if (!value || typeof value !== "object") return false;
+  const setup = value as Partial<BillingSetupAction>;
+  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: unknown): BillingErrorPayload | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const raw = (body as { billing?: unknown }).billing;
+  if (!raw || typeof raw !== "object") return undefined;
+  const status = (raw as { status?: unknown }).status;
+  if (typeof status !== "string") return undefined;
+  const setup = (raw as { setup?: unknown }).setup;
+  return {
+    status,
+    ...(isBillingSetupAction(setup) ? { setup } : {}),
+  };
+}
+
+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 function confirmChargeOrExit(opts: {
+  resource: PaidResource;
+  unitCents: number;
+  quantity?: number;
+  yes?: boolean;
+}): void {
+  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: string,
+  setup: BillingSetupAction,
+): Promise<string> {
+  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(() => ({}))) as {
+      error?: string;
+      message?: string;
+    };
+    throw new Error(
+      `Failed to mint a payment link: ${body.error ?? body.message ?? res.statusText}`,
+    );
+  }
+  const data = (await res.json()) as { url?: string };
+  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: string,
+  billing: BillingErrorPayload,
+): Promise<string | null> {
+  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;
+}