requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/commands/agent-setup.mjs

@@ -0,0 +1,195 @@
+// @ts-check
+
+import { cp, lstat, mkdir, readFile, realpath, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { CliError } from "../errors.mjs";
+import { detectAgents } from "../agent-detector.mjs";
+import { agentSkillPath } from "./agent-status.mjs";
+import { rendererFor } from "../terminal.mjs";
+
+/**
+ * @param {{ agent?: "codex" | "claude", force: boolean, json?: boolean }} options
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude">, terminal?: import('../terminal.mjs').TerminalContext }} deps
+ */
+export async function setupAgent(options, deps) {
+  const agent = await resolveAgent(options.agent, deps, !options.json);
+  const destination = agentSkillPath(agent, deps);
+  const skillsRoot = path.dirname(destination);
+  await mkdir(skillsRoot, { recursive: true });
+
+  const exists = await pathExists(destination);
+  if (exists && !options.force) {
+    throw new CliError(`RequestShield skill already exists at ${destination}; use --force to replace it`, {
+      code: "SKILL_EXISTS",
+      exitCode: 2,
+    });
+  }
+
+  // Copy into a staging directory so an interrupted copy cannot leave a
+  // partially installed skill at the final destination.
+  const staging = path.join(skillsRoot, `.requestshield-${randomUUID()}.tmp`);
+  const backup = `${destination}.${randomUUID()}.backup`;
+  try {
+    const source = deps.sourceDir ?? await resolveSkillSource(deps.executablePath);
+    await cp(source, staging, {
+      recursive: true,
+      errorOnExist: true,
+    });
+
+    // Keep the old installation recoverable until the staged copy is in place.
+    if (exists) await rename(destination, backup);
+    await rename(staging, destination);
+    if (exists) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    if (await pathExists(backup)) {
+      await rm(destination, { recursive: true, force: true });
+      await rename(backup, destination);
+    }
+    throw error;
+  }
+  const agentLabel = agent === "codex" ? "Codex" : "Claude";
+  const result = { agent, path: destination, status: /** @type {const} */ ("installed") };
+  if (options.json) deps.log(JSON.stringify({ data: result }, null, 2));
+  else {
+    const renderer = rendererFor(deps);
+    deps.log([
+      renderer.heading("Agent setup", "🤖"),
+      renderer.message("success", `Installed RequestShield skill for ${agentLabel}.`),
+      renderer.fields([["Path", destination]]),
+      renderer.paragraph(`Restart ${agentLabel} or start a new task before using the skill.`),
+    ].join("\n\n"));
+  }
+  return result;
+}
+
+/** @param {string} [executablePath] */
+async function resolveSkillSource(executablePath) {
+  // Resolve from this module, not the user's cwd or the shell's argv. Following
+  // the executable also supports explicitly supplied npm-link test fixtures.
+  const executable = await realpath(
+    executablePath ?? fileURLToPath(new URL("../main.mjs", import.meta.url)),
+  );
+  const packageRoot = path.resolve(path.dirname(executable), "..");
+  const bundled = path.join(packageRoot, "skills", "requestshield");
+  if (await pathExists(path.join(bundled, "SKILL.md"))) return bundled;
+
+  // Only a source checkout has both the private runner manifest and packaging
+  // script. Installed packages must never pick up an unrelated sibling skill.
+  const devManifestPath = path.join(packageRoot, "dev", "package.json");
+  if (await pathExists(devManifestPath)
+    && await pathExists(path.join(packageRoot, "scripts", "package-skill.mjs"))) {
+    const devManifest = JSON.parse(await readFile(devManifestPath, "utf8"));
+    const canonical = path.resolve(packageRoot, "../skills/requestshield");
+    if (devManifest.private === true
+      && devManifest.name === "@intellifend/requestshield-dev"
+      && await pathExists(path.join(canonical, "SKILL.md"))) return canonical;
+  }
+  throw new CliError("The RequestShield skill is missing. Reinstall the CLI and try again. If the problem continues, contact support.", {
+    code: "SKILL_SOURCE_MISSING",
+  });
+}
+
+/**
+ * Explicit selection bypasses detection. Automatic setup selects a single
+ * detected agent or asks the user when both agents are present.
+ *
+ * @param {"codex" | "claude" | undefined} requested
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
+ * @param {boolean} allowPrompt
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function resolveAgent(requested, deps, allowPrompt) {
+  // A command-line choice is authoritative and avoids probing the machine.
+  if (requested) return requested;
+
+  const detected = deps.detectAgents
+    ? await deps.detectAgents()
+    : await detectAgents({ env: deps.env, homeDir: deps.homeDir });
+
+  if (detected.length === 1) return detected[0];
+  if (detected.length === 0) {
+    throw new CliError(
+      [
+        "No supported coding agent detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "AGENT_NOT_FOUND", exitCode: 2 },
+    );
+  }
+
+  // Never choose silently when both agents are present. Interactive users get
+  // a prompt; non-interactive callers receive a stable conflict error.
+  if (!allowPrompt) {
+    throw new CliError("Multiple coding agents detected. Choose --codex or --claude explicitly when using --json.", {
+      code: "INSTALL_CONFLICT",
+      exitCode: 2,
+    });
+  }
+  const selectAgent = deps.selectAgent ?? promptForAgent;
+  const selected = await selectAgent(detected);
+  if (!detected.includes(selected)) {
+    throw new CliError(`Selected agent is not available: ${selected}`, {
+      code: "INVALID_AGENT",
+      exitCode: 2,
+    });
+  }
+  return selected;
+}
+
+/**
+ * Ask an interactive user which detected agent should receive the skill.
+ *
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function promptForAgent() {
+  if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+    throw new CliError(
+      [
+        "Multiple coding agents detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "INSTALL_CONFLICT", exitCode: 2 },
+    );
+  }
+
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    process.stderr.write(
+      "Multiple coding agents detected.\n\n  1. Codex\n  2. Claude\n\n",
+    );
+    while (true) {
+      const answer = (await prompt.question("Select an agent [1-2]: "))
+        .trim()
+        .toLowerCase();
+      if (answer === "1" || answer === "codex") return "codex";
+      if (answer === "2" || answer === "claude") return "claude";
+      process.stderr.write("Enter 1 for Codex or 2 for Claude.\n");
+    }
+  } finally {
+    prompt.close();
+  }
+}
+
+/** @param {string} target */
+async function pathExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/commands/agent-status.mjs

@@ -0,0 +1,65 @@
+// @ts-check
+
+import { lstat, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { rendererFor } from "../terminal.mjs";
+
+/** @typedef {"codex" | "claude"} Agent */
+/** @typedef {{ agent: Agent, path: string, status: "installed" | "missing" | "invalid" }} AgentInstallation */
+
+/** @param {Agent} agent @param {{ homeDir?: string }} [deps] */
+export function agentSkillPath(agent, deps = {}) {
+  return path.join(deps.homeDir ?? os.homedir(), agent === "codex" ? ".agents" : ".claude", "skills", "requestshield");
+}
+
+/**
+ * Inspect the personal Skill installation only; this does not prove an agent
+ * has loaded the Skill, and never probes executables or creates directories.
+ * @param {Agent} agent
+ * @param {{ homeDir?: string }} [deps]
+ * @returns {Promise<AgentInstallation>}
+ */
+export async function inspectAgent(agent, deps = {}) {
+  const destination = agentSkillPath(agent, deps);
+  try {
+    await lstat(destination);
+  } catch (error) {
+    return { agent, path: destination, status: /** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT" ? "missing" : "invalid" };
+  }
+
+  try {
+    // stat follows an intentional directory symlink; broken links are invalid.
+    if (!(await stat(destination)).isDirectory()) return { agent, path: destination, status: "invalid" };
+    const contents = await readFile(path.join(destination, "SKILL.md"), "utf8");
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(contents);
+    const valid = frontmatter !== null
+      && /^name:\s*(?:requestshield|"requestshield"|'requestshield')\s*$/m.test(frontmatter[1])
+      && frontmatter[2].trim().length > 0;
+    return { agent, path: destination, status: valid ? "installed" : "invalid" };
+  } catch {
+    return { agent, path: destination, status: "invalid" };
+  }
+}
+
+/**
+ * @param {{ agent?: Agent, json?: boolean }} options
+ * @param {{ homeDir?: string, log: (message: string) => void, terminal?: import('../terminal.mjs').TerminalContext }} deps
+ */
+export async function showAgentStatus(options, deps) {
+  const agents = options.agent ? [options.agent] : /** @type {Agent[]} */ (["codex", "claude"]);
+  const result = await Promise.all(agents.map((agent) => inspectAgent(agent, deps)));
+  if (options.json) {
+    deps.log(JSON.stringify({ data: result }, null, 2));
+  } else {
+    const renderer = rendererFor(deps);
+    deps.log([
+      renderer.heading("Agent Skills", "🤖"),
+      renderer.table(["AGENT", "STATUS", "PATH"], result.map(installation => [
+        installation.agent === "codex" ? "Codex" : "Claude", installation.status, installation.path,
+      ])),
+      renderer.muted(renderer.paragraph("This checks installed Skill files, not whether an agent has loaded them.")),
+    ].join("\n\n"));
+  }
+  return result;
+}

package/src/commands/application-mutations.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+import { parseApplicationResponse } from "./application-response.mjs";
+import { outputContext, printApplication } from "./output.mjs";
+import { confirmAction, mutationKey, parseAccepted, printAccepted, validateHttpStatus, withMutationRecovery } from "./mutation-support.mjs";
+
+/** @typedef {import('./mutation-support.mjs').MutationResponse} MutationResponse */
+/** @typedef {import('./mutation-support.mjs').CommandOutput & {sessions: {loadToken(): Promise<string>}}} Dependencies */
+
+/** @param {{appKey: string, name: string, json?: boolean, yes?: boolean, idempotencyKey?: string}} options
+ * @param {Dependencies & {api: {renameApp(token: string, appKey: string, options: {name: string, idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function renameApp(options, deps) {
+  deps = outputContext(options, deps);
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  const token = await deps.sessions.loadToken();
+  const application = await withMutationRecovery(idempotencyKey, deps, async () => {
+    const result = await deps.api.renameApp(token, options.appKey, {name: options.name, idempotencyKey});
+    validateHttpStatus(result, 200);
+    return parseApplicationResponse(result.body, options.appKey);
+  });
+  printApplication(application, options, deps);
+  return application;
+}
+
+/** @param {{appKey: string, enabled: boolean, json?: boolean, yes?: boolean, idempotencyKey?: string}} options
+ * @param {Dependencies & {api: {setAppEnabled(token: string, appKey: string, options: {enabled: boolean, idempotencyKey: string}): Promise<MutationResponse>}}} deps
+ */
+export async function setAppEnabled(options, deps) {
+  deps = outputContext(options, deps);
+  if (!options.enabled) await confirmAction(options, deps, `Disable application ${options.appKey}?`, "DISABLE");
+  const idempotencyKey = mutationKey(options.idempotencyKey);
+  const token = await deps.sessions.loadToken();
+  await withMutationRecovery(idempotencyKey, deps, async () => {
+    parseAccepted(await deps.api.setAppEnabled(token, options.appKey, {enabled: options.enabled, idempotencyKey}));
+  });
+  return printAccepted(options.enabled ? "Application enable" : "Application disable", options.appKey, deps, options);
+}

package/src/commands/application-response.mjs

@@ -0,0 +1,55 @@
+// @ts-check
+import { CliError } from "../errors.mjs";
+
+export const APPLICATION_STATUSES = new Set(["attention_required", "pending", "disabled", "revoked", "enabled"]);
+
+/** @typedef {{appKey: string, name: string, status: string, createdAt: string, updatedAt: string}} Application */
+
+/** Construct metadata from the implemented API schema; never relay extra fields.
+ * @param {unknown} value @param {string} [requestedAppKey] @returns {Application}
+ */
+export function parseApplication(value, requestedAppKey) {
+  const data = responseObject(value);
+  const {appKey, name, status, createdAt, updatedAt} = data;
+  if (typeof appKey !== "string" || !/^[A-Za-z0-9._~-]{1,128}$/.test(appKey)) {
+    throw invalidResponse("The application response contained an invalid App Key");
+  }
+  if (requestedAppKey !== undefined && appKey !== requestedAppKey) {
+    throw invalidResponse("The application response did not match the requested App Key");
+  }
+  if (typeof name !== "string" || !name.trim() || [...name].length > 100 || /[\p{Cc}\p{Cs}]/u.test(name)) {
+    throw invalidResponse("The application response contained an invalid name");
+  }
+  if (typeof status !== "string" || !APPLICATION_STATUSES.has(status)) {
+    throw invalidResponse("The application response contained an unsupported status");
+  }
+  if (!isTimestamp(createdAt) || !isTimestamp(updatedAt)) {
+    throw invalidResponse("The application response contained invalid timestamps");
+  }
+  return {appKey, name, status, createdAt, updatedAt};
+}
+
+/** @param {unknown} body @param {string} requestedAppKey */
+export function parseApplicationResponse(body, requestedAppKey) {
+  return parseApplication(responseObject(body).data, requestedAppKey);
+}
+
+/** @param {unknown} value @returns {Record<string, unknown>} */
+export function responseObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidResponse("The API response did not contain the expected object");
+  }
+  return /** @type {Record<string, unknown>} */ (value);
+}
+
+/** @param {unknown} value @returns {value is string} */
+function isTimestamp(value) {
+  return typeof value === "string"
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+/** @param {string} message */
+export function invalidResponse(message) {
+  return new CliError(message, {code: "INVALID_RESPONSE"});
+}

package/src/commands/apps-get.mjs

@@ -0,0 +1,28 @@
+// @ts-check
+
+import { parseApplicationResponse } from "./application-response.mjs";
+import { printApplication } from "./output.mjs";
+
+/**
+ * @param {{ appKey: string, json?: boolean }} options
+ * @param {{ api: { getApp(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void, terminal?: import('../terminal.mjs').TerminalContext }} deps
+ */
+export async function getApp(options, deps) {
+  const app = await fetchApp(options.appKey, deps);
+  printApplication(app, options, deps);
+  return app;
+}
+
+/** @param {string} appKey @param {Pick<Parameters<typeof getApp>[1], 'api' | 'sessions'>} deps */
+export async function fetchApp(appKey, deps) {
+  const accessToken =
+    await deps.sessions.loadToken();
+  
+  const result =
+    await deps.api.getApp(accessToken, appKey);
+  
+  const app =
+    parseApplicationResponse(result.body, appKey);
+  
+  return app;
+}

package/src/commands/apps-list.mjs

@@ -0,0 +1,93 @@
+// @ts-check
+
+import { CliError } from "../errors.mjs";
+import { getCommandInvocation } from "../config.mjs";
+import { rendererFor } from "../terminal.mjs";
+import { invalidResponse, parseApplication, responseObject } from "./application-response.mjs";
+
+const HEADERS = ["APP KEY", "NAME", "STATUS"];
+const MAX_PAGES = 100;
+
+/** @typedef {{ appKey: string, name: string, status: string, createdAt: string, updatedAt: string }} App */
+
+/**
+ * @param {{json: boolean, limit?: number, cursor?: string, all?: boolean}} options
+ * @param {{api: {listApps(accessToken: string, options: {limit?: number, cursor?: string}): Promise<{body: unknown}>}, sessions: {loadToken(): Promise<string>}, log: (message: string) => void, profile?: import('../config.mjs').Profile, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function listApps(options, deps) {
+  const result = await collectApps(options, deps);
+  const {data: apps, nextCursor} = result;
+  if (options.json) deps.log(JSON.stringify(result, null, 2));
+  else {
+    const renderer = rendererFor(deps);
+    const sections = [renderer.heading("Applications", "📦")];
+    if (apps.length === 0) {
+      sections.push(renderer.paragraph(nextCursor === null && !options.cursor
+        ? "No applications are available to this account."
+        : "No applications were returned on this page."));
+    } else {
+      sections.push(renderer.table(HEADERS, apps.map(app => [app.appKey, app.name, app.status])));
+    }
+    if (nextCursor !== null) sections.push(
+      renderer.paragraph("More applications are available. Continue with this command or use --all:"),
+      renderer.command(`  ${getCommandInvocation(deps.profile)} app list --cursor ${nextCursor}`),
+    );
+    deps.log(sections.join("\n\n"));
+  }
+  return result;
+}
+
+/** @param {{limit?: number, cursor?: string, all?: boolean}} options
+ * @param {Pick<Parameters<typeof listApps>[1], 'api' | 'sessions'>} deps */
+export async function collectApps(options, deps) {
+  /** @type {App[]} */
+  const apps = [];
+  let cursor = options.cursor;
+  let nextCursor = null;
+  const seen = new Set(cursor ? [cursor] : []);
+  for (let page = 0; page < MAX_PAGES; page++) {
+    // Long traversals can cross token expiry; each page may refresh safely.
+    const accessToken = await deps.sessions.loadToken();
+    const result = await deps.api.listApps(accessToken, {
+      ...(options.limit !== undefined ? {limit: options.limit} : {}),
+      ...(cursor !== undefined ? {cursor} : {}),
+    });
+    const parsed = parseApps(result.body);
+    if (parsed.data.length > (options.limit ?? 50)) throw invalidResponse("The applications response exceeded the requested page size");
+    apps.push(...parsed.data);
+    nextCursor = parsed.nextCursor;
+    if (nextCursor !== null && seen.has(nextCursor)) {
+      throw new CliError("The API repeated an application cursor; pagination stopped without returning partial results", {code: "PAGINATION_STALLED"});
+    }
+    if (!options.all || nextCursor === null) break;
+    seen.add(nextCursor);
+    cursor = nextCursor;
+    if (page === MAX_PAGES - 1) {
+      throw new CliError("Application pagination exceeded 100 pages; use --limit and --cursor to retrieve individual pages", {code: "PAGINATION_LIMIT"});
+    }
+  }
+
+  return {data: apps, nextCursor};
+}
+
+/** @param {unknown} body @returns {{ data: App[], nextCursor: string | null }} */
+function parseApps(body) {
+  const {data, nextCursor} = responseObject(body);
+
+  if (!Array.isArray(data)) {
+    throw new CliError("The applications response did not contain a data array", {
+      code: "INVALID_RESPONSE",
+    });
+  }
+
+  if (nextCursor !== null && (typeof nextCursor !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(nextCursor))) {
+    throw new CliError("The applications response contained an invalid nextCursor", {
+      code: "INVALID_RESPONSE",
+    });
+  }
+
+  // Rebuild every item from approved metadata so unexpected API fields never reach output.
+  const apps = data.map(entry => parseApplication(entry));
+
+  return { data: apps, nextCursor };
+}

package/src/commands/auth-status.mjs

@@ -0,0 +1,42 @@
+// @ts-check
+
+import { rendererFor } from "../terminal.mjs";
+
+/** @param {{json?: boolean}} options
+ * @param {{sessions: {status(): Promise<import('../session-store.mjs').SessionStatus>}, log: (message: string) => void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function showAuthStatus({ json = false }, deps) {
+  const status = await deps.sessions.status();
+  // Rebuild the output so future storage fields can never expose credentials.
+  const result = {
+    state: status.state, localOnly: true,
+    ...(["valid", "expired", "refresh_uncertain"].includes(status.state) ? {
+      expiresAt: status.expiresAt, scopes: status.scopes ? [...status.scopes] : [],
+    } : {}),
+  };
+  if (json) {
+    deps.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const descriptions = {
+    signed_out: "signed out",
+    valid: "locally valid",
+    expired: "continue with your next command to renew sign-in",
+    refresh_uncertain: "sign in again to continue",
+    config_mismatch: "saved session belongs to different configuration; sign in again",
+    invalid: "saved session is invalid; sign in again",
+    configuration_error: "sign-in is unavailable; update the CLI or contact support",
+  };
+  const renderer = rendererFor(deps);
+  /** @type {Array<[string, string]>} */
+  const fields = [
+    ["Session (local)", descriptions[result.state]],
+  ];
+  if (result.expiresAt !== undefined) fields.push(["Access token expires at", new Date(result.expiresAt).toUTCString()]);
+  if (result.scopes) fields.push(["Granted scopes", result.scopes.join(" ")]);
+  deps.log([
+    renderer.heading("Authentication", "👤"),
+    renderer.fields(fields),
+    renderer.muted(renderer.paragraph("This is local status; online session validity was not checked.")),
+  ].join("\n\n"));
+}

package/src/commands/billing.mjs

@@ -0,0 +1,106 @@
+// @ts-check
+import { validateAppKey } from "../args.mjs";
+import { utcTimestamp } from "../usage-time.mjs";
+import { rendererFor } from "../terminal.mjs";
+import { invalidResponse, responseObject } from "./application-response.mjs";
+import { printData } from "./output.mjs";
+
+const STATUSES = new Set(["unsubscribed", "creating", "checkout_pending", "active", "past_due", "canceled", "failed", "customer_pending", "customer_failed"]);
+const STATUS_LABELS = new Map([
+  ["unsubscribed", "Not subscribed"], ["creating", "Setting up"], ["checkout_pending", "Checkout pending"],
+  ["active", "Active"], ["past_due", "Past due"], ["canceled", "Canceled"], ["failed", "Setup failed"],
+  ["customer_pending", "Account setup pending"], ["customer_failed", "Account setup failed"],
+]);
+
+/** @param {{appKey: string, json?: boolean}} options
+ * @param {{api: {getBilling(token: string, appKey: string): Promise<{body: unknown}>}, sessions: {loadToken(): Promise<string>}, log(message: string): void, terminal?: import('../terminal.mjs').TerminalContext}} deps
+ */
+export async function showBilling(options, deps) {
+  validateAppKey(options.appKey);
+  const token = await deps.sessions.loadToken();
+  const result = await deps.api.getBilling(token, options.appKey);
+  const data = parseBillingResponse(result.body, options.appKey);
+  if (options.json) printData(data, deps);
+  else {
+    const renderer = rendererFor(deps);
+    deps.log([renderer.heading("Account billing"), renderer.fields([
+      ["App Key", data.appKey], ["Plan", data.plan === null ? "Unavailable" : data.plan === "free" ? "Express" : "Pro"],
+      ["Status", STATUS_LABELS.get(data.status) ?? data.status],
+      ["Billing period", data.billingPeriod === null ? "Unavailable" : `${data.billingPeriod.start} to ${data.billingPeriod.end}`],
+      ["Usage (approximate)", data.usage === null ? "Unavailable" : `${quantity(data.usage)} / ${quantity(data.includedAllowance)} included calls`],
+      ["Remaining quota", `${quantity(data.remainingQuota)}${data.remainingQuota === null ? "" : " calls"}`],
+      ["Overage", `${quantity(data.overage)}${data.overage === null ? "" : " calls"}`],
+      ["Estimated cost", data.estimatedCost === null ? "Unavailable" : `${money(data.estimatedCost.totalAmountMinor, data.estimatedCost.currency)} before taxes`],
+      ["Base charge", data.estimatedCost === null ? "Unavailable" : money(data.estimatedCost.baseAmountMinor, data.estimatedCost.currency)],
+      ["Estimated overage cost", data.estimatedCost === null ? "Unavailable" : money(data.estimatedCost.overageAmountMinor, data.estimatedCost.currency)],
+      ["Reported at", data.reportedAt], ["Usage through", data.usageThrough ?? "Unavailable"],
+    ]), renderer.paragraph("Totals cover all applications in your account. Calls are authenticated API v2 token verification requests, including rejected requests and retries. API v1 and service errors are excluded."),
+    renderer.paragraph("Usage, remaining quota and overage are approximate. Data may be delayed or incomplete; the usage cutoff is not a guarantee of complete reporting."),
+    renderer.paragraph("Estimated cost includes the period's base charge and usage reported so far, before taxes. This is not a final invoice.")].join("\n\n"));
+  }
+  return data;
+}
+
+/** Validate and copy only the public billing contract; the server owns all billing calculations.
+ * @param {unknown} body @param {string} appKey
+ */
+export function parseBillingResponse(body, appKey) {
+  const data = responseObject(responseObject(body).data);
+  const {status, plan} = data;
+  if (data.appKey !== appKey || data.scope !== "account" || typeof status !== "string" || !STATUSES.has(status)
+    || (plan !== null && plan !== "free" && plan !== "pro") || data.unit !== "token_verification_requests" || data.approximate !== true) throw invalidBilling();
+  const reportedAt = timestamp(data.reportedAt);
+  const usageThrough = data.usageThrough === null ? null : timestamp(data.usageThrough);
+  const billingPeriod = parsePeriod(data.billingPeriod);
+  const includedAllowance = nullableQuantity(data.includedAllowance), usage = nullableQuantity(data.usage);
+  const remainingQuota = nullableQuantity(data.remainingQuota), overage = nullableQuantity(data.overage);
+  const estimatedCost = parseCost(data.estimatedCost);
+  if (usageThrough !== null && (billingPeriod === null || usageThrough < billingPeriod.start || usageThrough > billingPeriod.end || usageThrough > reportedAt)) throw invalidBilling();
+  if (plan === null && [billingPeriod, includedAllowance, usage, remainingQuota, overage, usageThrough, estimatedCost].some(value => value !== null)) throw invalidBilling();
+  if (plan !== null && (!["active", "past_due"].includes(status) || [billingPeriod, includedAllowance, usage, remainingQuota, overage, usageThrough, estimatedCost].some(value => value === null))) throw invalidBilling();
+  return {appKey, scope: /** @type {const} */ ("account"), status, plan, billingPeriod, includedAllowance, usage,
+    remainingQuota, overage, unit: /** @type {const} */ ("token_verification_requests"), approximate: /** @type {const} */ (true),
+    reportedAt, usageThrough, estimatedCost};
+}
+
+/** @param {unknown} value */
+function parsePeriod(value) {
+  if (value === null) return null;
+  const period = responseObject(value), start = timestamp(period.start), end = timestamp(period.end);
+  if (start >= end) throw invalidBilling();
+  return {start, end};
+}
+
+/** @param {unknown} value */
+function parseCost(value) {
+  if (value === null) return null;
+  const cost = responseObject(value);
+  if (cost.currency !== "USD") throw invalidBilling();
+  return {currency: /** @type {const} */ ("USD"), baseAmountMinor: integer(cost.baseAmountMinor),
+    overageAmountMinor: integer(cost.overageAmountMinor), totalAmountMinor: integer(cost.totalAmountMinor)};
+}
+
+/** @param {unknown} value */
+function timestamp(value) {
+  const time = utcTimestamp(value);
+  if (time === undefined) throw invalidBilling();
+  return new Date(time).toISOString();
+}
+
+/** @param {unknown} value */
+function integer(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw invalidBilling();
+  return value;
+}
+
+/** @param {unknown} value */
+function nullableQuantity(value) { return value === null ? null : integer(value); }
+/** @param {number | null} value */
+function quantity(value) { return value === null ? "Unavailable" : value.toLocaleString("en-US"); }
+/** Decimal placement only: never calculate a price or derive a total in the CLI.
+ * @param {number} minor @param {string} currency */
+function money(minor, currency) {
+  const digits = String(minor).padStart(3, "0");
+  return `${currency} ${digits.slice(0, -2).replace(/\B(?=(\d{3})+(?!\d))/g, ",")}.${digits.slice(-2)}`;
+}
+function invalidBilling() { return invalidResponse("The billing response did not match the requested app or billing schema"); }