@retasc/cli 1.3.2 → 1.5.0

package/dist/api.js

@@ -19,6 +19,12 @@ const fns = {
     acceptInvite: makeFunctionReference("manage:acceptInvite"),
     listInvites: makeFunctionReference("manage:listInvites"),
     revokeInvite: makeFunctionReference("manage:revokeInvite"),
+    // Billing (RTSC-279). The CLI is a HUMAN surface (device-login JWT), so these are the
+    // very functions the Dash uses — already owner-gated, already org-scoped across every
+    // payment link. No key-based path needed here (that's the `billing_summary` MCP tool).
+    billingStatus: makeFunctionReference("manage:billingStatus"),
+    chargeHistory: makeFunctionReference("manage:chargeHistory"),
+    orgPayments: makeFunctionReference("manage:orgPayments"),
 };
 function client() {
     const cfg = loadConfig();
@@ -27,11 +33,49 @@ function client() {
         c.setAuth(cfg.token);
     return c;
 }
+/**
+ * Read a caught backend error into the parts a command wants to show (RTSC-261).
+ *
+ * `code` is machine-readable, so a command branches on `code === "EXPIRED"`
+ * instead of regex-matching prose that any copy edit would break. `hint` is the
+ * next step, kept separate so callers can dim or indent it.
+ *
+ * Both are optional because the sweep is incremental: a backend site still
+ * throwing a plain Error (or an OLD deployment this CLI is pointed at) yields
+ * `{message}` alone via the same first-line/strip-prefix cleanup used before.
+ * Callers must therefore keep any existing string fallback rather than assuming
+ * `code` is present.
+ */
+export function formatError(e) {
+    const data = e?.data;
+    if (data && typeof data === "object" && typeof data.message === "string") {
+        // Type-guard EVERY field, not just `message`: a foreign error carrying
+        // `{message: "x", code: {…}}` would otherwise print `✗ [object Object]: x`.
+        // And strip control characters — these strings go to `console.error`, so a
+        // future converted site that interpolates user data (issue ids, org names)
+        // must not be able to smuggle ANSI escapes into the terminal. Mirrors
+        // `sanitize` in convex/lib/userError.ts; the two are one wire contract.
+        const clean = (v) => 
+        // eslint-disable-next-line no-control-regex
+        typeof v === "string" ? v.replace(/[\x00-\x1f\x7f]/g, " ").trim() : undefined;
+        return { code: clean(data.code), message: clean(data.message), hint: clean(data.hint) };
+    }
+    const message = String(e?.message ?? e)
+        .split("\n")[0]
+        .replace(/^.*?Uncaught Error:\s*/, "")
+        .trim();
+    return { message };
+}
 // Does this error mean "the access token is missing/expired", i.e. a refresh
 // might fix it? The access-token JWT lives ~1h, so any long-lived login trips
 // this. Two shapes surface: our server functions throw `UNAUTHENTICATED …`
 // (requireUser), and the Convex platform rejects a stale JWT with "Could not
 // verify OIDC token"/"Unauthenticated". Match either, case-insensitively.
+// RTSC-261 deliberately does NOT touch this. It gates the refresh-and-retry
+// loop, no site converted here throws an auth code, and `formatError` truncates
+// to the first line — so routing it through there would add real risk (a missed
+// match means a spurious device-flow re-login) for no gain today. It gets a
+// `code === "UNAUTHENTICATED"` fast path in the PR that converts lib/auth.ts.
 export function isAuthError(e) {
     const msg = String(e?.message ?? e);
     return /unauthenticated|could not verify oidc|oidc token/i.test(msg);
@@ -92,4 +136,7 @@ export const api = {
     acceptInvite: (args) => withAuth(() => client().mutation(fns.acceptInvite, args)),
     listInvites: (args) => withAuth(() => client().query(fns.listInvites, args)),
     revokeInvite: (args) => withAuth(() => client().mutation(fns.revokeInvite, args)),
+    billingStatus: (args) => withAuth(() => client().query(fns.billingStatus, args)),
+    chargeHistory: (args) => withAuth(() => client().query(fns.chargeHistory, args)),
+    orgPayments: (args) => withAuth(() => client().action(fns.orgPayments, args)),
 };

package/dist/commands/billing.js

@@ -0,0 +1,121 @@
+import { api } from "../api.js";
+// RTSC-279 — `retasc billing`: the whole billing picture in the terminal, so you don't
+// have to open the Dash to answer "what do I owe / what have I paid".
+//
+// The CLI is a HUMAN surface (device-login JWT), so this reuses the very functions the
+// Dash renders — already owner-gated, and already ORG-scoped across every payment link
+// the org has ridden (charges: RTSC-254, payments: RTSC-277). A link change therefore
+// never hides prior history here either.
+//
+// Payments are a LIVE Xenarch read fanned per link, so they can be slow or unavailable;
+// they're fetched last and degrade to a note rather than failing the whole command.
+/** Metered billing is micro-USDC, so `toFixed(2)` hides real sub-cent amounts. Show up
+ * to 6 decimals, trim trailing zeros, keep a 2-decimal floor so money still reads right. */
+function usd(n) {
+    if (n == null)
+        return "—";
+    const trimmed = n.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+    const dot = trimmed.indexOf(".");
+    const decimals = dot === -1 ? 0 : trimmed.length - dot - 1;
+    return `$${decimals >= 2 ? trimmed : n.toFixed(2)}`;
+}
+function date(ms) {
+    return ms == null ? "—" : new Date(ms).toISOString().slice(0, 10);
+}
+function isoDate(s) {
+    return s ? s.slice(0, 10) : "—";
+}
+const row = (label, value) => console.log(`  ${label.padEnd(22)}${value}`);
+export async function billingAction(opts) {
+    // Resolve the org: explicit --org-id wins; otherwise use the only one you're in. With
+    // several, ask rather than guess — printing the wrong org's money is worse than an error.
+    let orgId = opts.orgId;
+    let orgLabel = "";
+    const me = await api.me();
+    if (!orgId) {
+        if (me.orgs.length === 0)
+            throw new Error("You're not a member of any org yet.");
+        if (me.orgs.length > 1) {
+            const list = me.orgs.map((o) => `  ${o.id}  ${o.name}${o.slug ? ` (${o.slug})` : ""}`);
+            throw new Error(`Several orgs — pass --org-id <id>:\n${list.join("\n")}`);
+        }
+        orgId = me.orgs[0].id;
+    }
+    const org = me.orgs.find((o) => o.id === orgId);
+    orgLabel = org ? `${org.name}${org.slug ? ` (${org.slug})` : ""}` : String(orgId);
+    // Fail early with the actionable message rather than a raw FORBIDDEN from the server.
+    if (org && org.role !== "owner") {
+        throw new Error(`Billing is owner-only — your role in ${orgLabel} is "${org.role}".`);
+    }
+    const [status, charges] = await Promise.all([
+        api.billingStatus({ orgId: orgId }),
+        api.chargeHistory({ orgId: orgId }),
+    ]);
+    // Live Xenarch fan-out — slowest and most failure-prone, so it's last and non-fatal.
+    let payments = null;
+    let paymentsError = null;
+    try {
+        payments = await api.orgPayments({ orgId: orgId });
+    }
+    catch (e) {
+        paymentsError = String(e?.message ?? e);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ org: orgLabel, status, charges, payments, paymentsError }, null, 2));
+        return;
+    }
+    const s = status;
+    const c = charges;
+    console.log(`\nBilling — ${orgLabel}\n`);
+    console.log("SUBSCRIPTION");
+    row("Status", `${s.status}${s.gated ? " (gated)" : ""}`);
+    row("Subscription", s.subscriptionId ?? "none yet");
+    if (s.spendingCapUsd != null) {
+        row("Budget", `${usd(s.spendingCapUsd)}${s.capPeriod ? ` / ${s.capPeriod.replace("per_", "")}` : ""}`);
+    }
+    if (s.collectionMessage)
+        row("⚠ Collection", s.collectionMessage);
+    console.log("\nMONEY");
+    row("Pending (owed now)", usd(s.accruedUsd));
+    row("Outstanding", usd(c.outstandingUsd));
+    row("Charged (lifetime)", usd(c.chargedUsd));
+    row("Collected (lifetime)", usd(c.collectedUsd));
+    if (s.creditsUsd > 0)
+        row("Credit remaining", usd(s.creditsUsd));
+    // Charges + payments span EVERY link; label the eras so a link change is visible
+    // rather than looking like history that vanished.
+    const eras = c.eras ?? [];
+    console.log(`\nCHARGES (${c.charges.length}${c.capped ? "+, capped" : ""})`);
+    if (c.charges.length === 0) {
+        console.log("  none yet");
+    }
+    else {
+        if (eras.length > 1)
+            console.log(`  across ${eras.length} payment links`);
+        for (const ch of c.charges.slice(0, 10)) {
+            const era = eras.length > 1 ? `  [${ch.subscriptionId.slice(0, 8)}…]` : "";
+            console.log(`  #${String(ch.chargeSeq).padEnd(4)} ${date(ch.bookedAt)}  ${ch.status.padEnd(8)} ${usd(ch.amountUsd)}${era}`);
+        }
+        if (c.charges.length > 10)
+            console.log(`  … ${c.charges.length - 10} more`);
+    }
+    console.log("\nPAYMENTS (confirmed on-chain)");
+    if (paymentsError) {
+        console.log(`  unavailable — ${paymentsError}`);
+    }
+    else if (!payments || payments.payments.length === 0) {
+        console.log("  none yet");
+    }
+    else {
+        const ps = payments.payments;
+        const links = new Set(ps.map((p) => p.subscriptionId)).size;
+        if (links > 1)
+            console.log(`  across ${links} payment links`);
+        for (const p of ps) {
+            const era = links > 1 ? `  [${p.subscriptionId.slice(0, 8)}…]` : "";
+            const block = p.blockNumber != null ? `block ${p.blockNumber}` : "";
+            console.log(`  ${isoDate(p.createdAt)}  ${usd(p.amountUsd).padEnd(10)} ${block}${era}`);
+        }
+    }
+    console.log("");
+}

package/dist/index.js

@@ -9,11 +9,12 @@ import { installGate } from "./commands/gate.js";
 import { claimAction } from "./commands/claim.js";
 import { bindAction } from "./commands/bind.js";
 import { doctorAction } from "./commands/doctor.js";
+import { billingAction } from "./commands/billing.js";
 import { readLocalBinding, resolveBinding } from "./lib/binding.js";
 import { tidyAction, doneAction } from "./commands/tidy.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
-import { api } from "./api.js";
+import { api, formatError } from "./api.js";
 // Single source of truth for the version: read package.json at runtime from the
 // compiled file's location (dist/index.js -> ../package.json). A JSON import won't
 // work here — tsconfig has rootDir "src", so importing ../package.json is outside
@@ -30,9 +31,15 @@ function requireLogin() {
         process.exit(1);
     }
 }
+// RTSC-261: prefer the structured payload, and print `hint` on its own dimmed
+// line — the whole reason it's a separate field is that the fix shouldn't be
+// buried in the middle of the diagnosis. `formatError` falls back to the old
+// string cleanup, so unconverted backend sites print exactly as they did.
 function fail(e) {
-    const msg = String(e?.message ?? e).split("\n")[0].replace(/^.*?Uncaught Error:\s*/, "");
-    console.error(`✗ ${msg}`);
+    const { code, message, hint } = formatError(e);
+    console.error(`✗ ${code ? `${code}: ` : ""}${message}`);
+    if (hint)
+        console.error(`  → ${hint}`);
     process.exit(1);
 }
 // --- auth ------------------------------------------------------------------
@@ -165,6 +172,15 @@ program
     .action(async () => {
     await doctorAction().catch(fail);
 });
+program
+    .command("billing")
+    .description("Show the org's billing: subscription, what's owed now, and the charge + on-chain payment history across every payment link ever used (owner only).")
+    .option("--org-id <id>", "Which org (defaults to your only one).")
+    .option("--json", "Emit the raw payload instead of the summary.")
+    .action(async (opts) => {
+    requireLogin();
+    await billingAction({ orgId: opts.orgId, json: opts.json }).catch(fail);
+});
 // --- org / project ---------------------------------------------------------
 const org = program.command("org").description("Manage orgs.");
 org

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {