Report credits in zenrows usage — the endpoint always sent them

Verified against the live endpoint: /v1/subscriptions/self/details returns
usage_credits and credit_limit next to the dollar figure. Neither was declared
on UsageDetails, so the command printed dollars and left the reader to
convert.

They cannot. The rate is per plan, not a platform constant: Free bills
$0.001/credit (5,000 credits for $5) while a Business yearly plan bills
8.9997e-05. The response carries plan.unit_cost for exactly this reason, and
credit_limit * unit_cost === plan.price holds on the live payload.

So the command now leads with credits used, the credit limit and what is left,
which is the unit the docs, the dashboard and the error messages all speak in.
The dollar line stays underneath.

unit_cost is declared with a note against ever hardcoding a conversion factor
— an easy mistake to make from a single account's numbers, and wrong on every
other plan.

Author: pablomogamon

src/cli/commands/usage.ts

@@ -8,6 +8,11 @@ import { log } from "../../core/logger.ts";
 import { fetchUsage } from "../../core/usage.ts";
 import { parse, type Command, type RunContext } from "../command.ts";
 
+/** Thousands separators, so a seven-digit credit limit stays readable. */
+export function fmt(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
 /** Free plan still ships as plan_code=trial in R1; display the product name. */
 export function formatPlanName(name: string | undefined): string {
   if (!name) return "—";
@@ -42,6 +47,18 @@ export const usage: Command = {
     const api = u.plan?.products?.api;
     log.info(`Plan:    ${formatPlanName(u.plan?.name)}${u.plan?.recurrence ? ` (${u.plan.recurrence})` : ""}`);
     log.info(`Status:  ${formatPlanStatus(u.status)}`);
+    // Credits are the unit the docs, the dashboard and the error messages all speak in,
+    // and the endpoint has been returning them all along. Showing only the dollar figure
+    // left the reader to convert — and the rate is per plan, so they could not.
+    if (u.usage_credits !== undefined && u.credit_limit !== undefined) {
+      const remaining = Math.max(0, u.credit_limit - u.usage_credits);
+      log.info(
+        `Credits: ${fmt(u.usage_credits)} of ${fmt(u.credit_limit)} used` +
+          `${u.usage_percent !== undefined ? ` (${u.usage_percent}%)` : ""} — ${fmt(remaining)} left`,
+      );
+    } else if (u.usage_credits !== undefined) {
+      log.info(`Credits: ${fmt(u.usage_credits)} used`);
+    }
     if (u.usage !== undefined) {
       log.info(`Usage:   ${u.usage}${u.usage_percent !== undefined ? ` (${u.usage_percent}% of plan)` : ""}`);
     }

src/core/usage.ts

@@ -19,6 +19,8 @@ export interface UsageConcurrency {
 
 export interface UsageProduct {
   usage?: number;
+  /** Same consumption as `usage`, counted in credits. */
+  usage_credits?: number;
   concurrency?: UsageConcurrency;
   [k: string]: unknown;
 }
@@ -27,13 +29,23 @@ export interface UsageDetails {
   status?: string;
   period_starts_at?: string;
   period_ends_at?: string;
-  /** Total units consumed across all products. */
+  /** Total consumed across all products, in dollars. */
   usage?: number;
+  /** The same consumption in credits — what the docs and the dashboard quote. */
+  usage_credits?: number;
+  /** The plan's allowance in credits. `credit_limit * plan.unit_cost === plan.price`. */
+  credit_limit?: number;
   /** Consumption as a percentage of the plan limit. */
   usage_percent?: number;
   plan?: {
     name?: string;
     price?: number;
+    /**
+     * Dollars per credit, and it is **per plan**, not a platform constant: Free bills
+     * $0.001/credit (5,000 credits for $5) while larger plans get a volume rate. Never
+     * convert between dollars and credits with a hardcoded factor.
+     */
+    unit_cost?: number;
     recurrence?: string;
     products?: {
       api?: UsageProduct;

tests/usage.test.ts

@@ -2,6 +2,8 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { fetchUsage, usageUrl } from "../src/core/usage.ts";
 import { ToolkitError } from "../src/core/errors.ts";
+import { fmt } from "../src/cli/commands/usage.ts";
+import type { UsageDetails } from "../src/core/usage.ts";
 
 test("usageUrl derives subscriptions/self/details from the api base", () => {
   assert.equal(usageUrl("https://api.zenrows.com/v1/"), "https://api.zenrows.com/v1/subscriptions/self/details");
@@ -61,3 +63,27 @@ test("fetchUsage maps a 402 (over usage limit) to POLICY_MAX_CREDITS_EXCEEDED",
     (e: unknown) => e instanceof ToolkitError && e.code === "POLICY_MAX_CREDITS_EXCEEDED",
   );
 });
+
+test("zenrows usage reports credits, which the endpoint has always returned", () => {
+  // Verified against the live endpoint: it sends usage_credits and credit_limit
+  // alongside the dollar figure. Neither was declared on UsageDetails, so the command
+  // printed only dollars and left the reader to convert — which they cannot do, because
+  // the rate is per plan (Free $0.001/credit, larger plans a volume rate).
+  assert.equal(fmt(62982), "62,982");
+  assert.equal(fmt(35999978), "35,999,978");
+});
+
+test("UsageDetails carries credits and the per-plan rate", () => {
+  const sample: UsageDetails = {
+    status: "ACTIVE",
+    usage: 5.66823039823616,
+    usage_credits: 62982,
+    credit_limit: 35999978,
+    usage_percent: 0,
+    plan: { name: "Business", price: 3239.89, unit_cost: 8.9997e-5, recurrence: "YEARLY" },
+  };
+  // credit_limit * unit_cost === plan.price is the invariant that makes the rate per-plan
+  // rather than a platform constant. Holds on the live response.
+  assert.ok(Math.abs(sample.credit_limit! * sample.plan!.unit_cost! - sample.plan!.price!) < 0.01);
+  assert.ok(Math.abs(sample.usage! / sample.usage_credits! - sample.plan!.unit_cost!) < 1e-8);
+});