@skrr-ai/cli 0.1.8

package/dist/commands/balance/show.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const balance_1 = require("../../lib/balance");
+const workspaces_1 = require("../../lib/workspaces");
+/**
+ * YOUR hosted usage balance — the personal account, and only that one.
+ *
+ * Distinct from `skrr payments wallet`, which is the x402 crypto wallet in USDC.
+ *
+ * It is also distinct from a WORKSPACE's balance, and that distinction is the
+ * one that costs people time. A session carrying a workspace bills the
+ * workspace's account, so `admitRefusal` says "this session needs more credit
+ * than this workspace's balance has available". The reader comes here to look
+ * at that pot — and `GET /api/balance` only ever answers for the caller, so
+ * they were shown a personal balance under the heading "Hosted usage balance"
+ * and could not tell it was the wrong account. On 2026-08-20 that meant a
+ * session refused against an empty workspace account while its owner held
+ * $999,999 personally.
+ *
+ * So the heading names the owner, and `--workspace` now SELECTS the account
+ * rather than being quietly ignored. `GET /api/balance` is user-scoped and can
+ * never answer for a workspace, so this reads a different endpoint —
+ * `/api/workspaces/:id/billing/balance`, member-readable precisely because the
+ * refusal that sends people here is addressed to any member.
+ *
+ * The failure mode this replaces is worth remembering: the flag was accepted
+ * on every command because it is global, so `--workspace <anything>` — a
+ * workspace that does not exist, a string that is not an id — printed the
+ * personal balance and exited 0. A flag that silently means nothing is worse
+ * than one that is rejected, because the exit code says it worked.
+ */
+class BalanceShow extends base_command_1.BaseCommand {
+    static description = 'Show your hosted usage balance — or a workspace’s, with --workspace';
+    static examples = [
+        '<%= config.bin %> balance show',
+        '<%= config.bin %> balance show --json',
+        '<%= config.bin %> balance show --workspace <workspace-id>',
+    ];
+    static flags = { json: core_1.Flags.boolean({ description: 'Output as JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(BalanceShow);
+        // `--workspace` selects the ACCOUNT, so it is answered by a different
+        // endpoint entirely rather than by relabelling the personal one.
+        const workspaceId = flags.workspace;
+        if (workspaceId) {
+            await this.showWorkspaceBalance(workspaceId, Boolean(flags.json));
+            return;
+        }
+        let balance;
+        try {
+            balance = await (0, balance_1.getBalance)();
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(balance, null, 2));
+            return;
+        }
+        if (!balance) {
+            this.error('No balance record for this account.', { exit: 1 });
+        }
+        // Name the account. "Hosted usage balance" alone reads as "the balance
+        // that matters here", which is exactly the wrong reading for someone sent
+        // by a workspace refusal.
+        this.log('Hosted usage balance — your personal account');
+        // Credits AND dollars, because a credit is a micro-dollar and nothing on
+        // this surface said so. Four spend screens reported four units with no
+        // stated relationship between them (OSK-4664).
+        this.log(`  Credits:        ${(0, balance_1.formatCreditsWithUsd)(balance.tokenCredits)}`);
+        // Held money is why "there is a balance" and "a session can start" are
+        // different answers. Printed only when there is some — a permanent `$0.00`
+        // teaches the reader to stop reading the line. Say what holds it, so the
+        // figure is not a number with no cause (OSK-4832).
+        if (balance.heldMicros) {
+            // Credits AND dollars, like every other row here — Held was the one line
+            // printed in dollars only, so it read as a different quantity from the
+            // Credits above it (OSK-4827).
+            this.log(`  Held:           ${(0, balance_1.formatCreditsWithUsd)(balance.heldMicros)}`);
+            this.log('                  (committed to sessions in flight; each hold is a');
+            this.log('                  `hold` entry in `skrr balance statement`)');
+        }
+        if (balance.balanceSource === 'legacy') {
+            // The unified account is missing for this user, so the figure above is
+            // the retired row. Say so rather than presenting it as the live balance.
+            this.log('  Source:         legacy balance row (no unified billing account yet)');
+        }
+        if (balance.tokenLimit != null) {
+            const used = balance.periodTokensUsed ?? 0;
+            const remaining = Math.max(0, balance.tokenLimit - used);
+            // "10,000,000 per daily" — `tokenLimitPeriod` is an adjective and `per`
+            // wants a noun. Map the ones the server sends; anything else falls back
+            // to the raw word rather than guessing at a plural.
+            const PERIOD_NOUNS = {
+                daily: 'day',
+                weekly: 'week',
+                monthly: 'month',
+                hourly: 'hour',
+            };
+            const periodWord = balance.tokenLimitPeriod ? String(balance.tokenLimitPeriod) : '';
+            const period = periodWord ? ` per ${PERIOD_NOUNS[periodWord] ?? periodWord}` : '';
+            // Same unit as the credits above, despite the `token` in the field
+            // names: `balanceMethods.check` compares these against the very cost it
+            // subtracts from the balance. So "10,000,000 per day" is $10.00 a day —
+            // the most misleading number on this screen until it said so.
+            //
+            // It is a per-period RATE LIMIT, not money, and it is the one thing the
+            // legacy `Balance` row is still authoritative for. Labelled as a cap so
+            // it cannot be mistaken for a second balance.
+            this.log(`  Spend cap:      ${(0, balance_1.formatCreditsWithUsd)(balance.tokenLimit)}${period}`);
+            this.log(`  Spent:          ${(0, balance_1.formatCreditsWithUsd)(used)} this period`);
+            this.log(`  Cap remaining:  ${(0, balance_1.formatCreditsWithUsd)(remaining)}`);
+            if (balance.periodStartDate) {
+                // Same `YYYY-MM-DD HH:MM:SS` shape as every other WHEN on this surface,
+                // not a raw ISO string with a `Z` and milliseconds (OSK-4832).
+                this.log(`  Period began:   ${(0, balance_1.formatBalanceTimestamp)(balance.periodStartDate)}`);
+            }
+        }
+        else {
+            // Say so rather than printing a limit line with a blank in it: no limit
+            // and an unreported limit are different states.
+            this.log('  Spend cap:      none set');
+        }
+        // The server strips every refill field when auto-refill is off, so their
+        // absence is the answer — do not render them as zeros.
+        if (balance.autoRefillEnabled) {
+            const every = balance.refillIntervalValue != null && balance.refillIntervalUnit
+                ? `every ${balance.refillIntervalValue} ${balance.refillIntervalUnit}`
+                : 'on a schedule';
+            this.log(`  Auto-refill:    ${(0, balance_1.formatCreditsWithUsd)(balance.refillAmount)} ${every}`);
+            if (balance.lastRefill) {
+                // Same timestamp shape as `Period began` and every WHEN column, not a
+                // raw ISO string (OSK-4832).
+                this.log(`  Last refill:    ${(0, balance_1.formatBalanceTimestamp)(balance.lastRefill)}`);
+            }
+        }
+        else {
+            this.log('  Auto-refill:    off');
+        }
+        this.log('');
+        this.log('A credit is a micro-dollar: 1,000,000 credits = $1.00. The spend cap');
+        this.log('is a per-period ceiling, not a second balance. `skrr balance statement`');
+        this.log('itemises this same account and says what each charge was for.');
+        this.log('');
+        this.log('This is the ceiling that refuses a turn for work you own. A session');
+        this.log("carrying a workspace is refused against the WORKSPACE's balance —");
+        this.log('see `skrr balance show --workspace <id>`. `skrr payments wallet` is the');
+        this.log('separate x402 crypto wallet, in USDC — not this balance.');
+    }
+    /**
+     * The workspace account, which is the one a workspace-carrying session is
+     * funded from. Rendered in the SAME credits-plus-dollars unit and row labels
+     * as the personal view above (OSK-4827): it read "Available: $24.85" in
+     * dollars only while the personal view said "Credits: … ($…)" for the
+     * identical `availableMicros`, so the one account looked like a different
+     * quantity than the other.
+     */
+    async showWorkspaceBalance(workspaceId, asJson) {
+        let balance;
+        try {
+            balance = await (0, balance_1.getWorkspaceBalance)(workspaceId);
+        }
+        catch (err) {
+            // A 403 here is a real answer, not a glitch: membership is what grants
+            // this read, and `handleApiError` already renders the server's message.
+            this.handleApiError(err);
+        }
+        if (asJson) {
+            this.log(JSON.stringify(balance, null, 2));
+            return;
+        }
+        if (!balance) {
+            this.error('No balance reported for this workspace.', { exit: 1 });
+        }
+        // Name the workspace in the heading rather than showing the raw id alone —
+        // `skrr workspaces list` knows the name, and a member sent here by a refusal
+        // needs to confirm it is the right account (OSK-4827). Best-effort: the
+        // same membership that granted the balance grants this read, but a hiccup
+        // resolving the name must not cost the reader the balance, so it falls back
+        // to the id-only heading.
+        let name;
+        try {
+            name = (await (0, workspaces_1.getWorkspace)(workspaceId)).name;
+        }
+        catch {
+            name = undefined;
+        }
+        this.log((0, balance_1.workspaceBalanceHeading)(workspaceId, name));
+        if (!balance.exists) {
+            // Distinct from an empty account, and admission refuses differently for
+            // it ('billing-account-missing' vs 'balance-exhausted').
+            this.log('  No billing account yet — nothing has ever been funded or spent here.');
+            this.log('');
+            this.log('A managed session carrying this workspace cannot be funded until');
+            this.log('billing is set up for it by a workspace owner.');
+            return;
+        }
+        for (const line of (0, balance_1.workspaceBalanceLines)(balance)) {
+            this.log(line);
+        }
+        this.log('');
+        this.log('This is the account a session carrying this workspace bills against —');
+        this.log('the balance named by "this session needs more credit than this');
+        this.log('workspace\'s balance has available". Your personal balance is separate:');
+        this.log('`skrr balance show`.');
+    }
+}
+exports.default = BalanceShow;

package/dist/commands/balance/statement.d.ts

@@ -0,0 +1,89 @@
+import { BaseCommand } from '../../base-command';
+import { type BalanceStatementEntry } from '../../lib/balance';
+/**
+ * The canonical stored-value ledger — what a charge was FOR, and what incurred it.
+ *
+ * `skrr balance history` reads the LEGACY token transaction view, and that is
+ * why the ledger appeared to explain nothing: every row printed `gateway-usd`
+ * under a MODEL heading (it is not a model), CONTEXT held an internal
+ * accounting term, and the newest row could be a week old while `balance show`
+ * reported usage today (OSK-4664).
+ *
+ * None of that was missing from the product. `/api/balance/statement` — the
+ * unified ledger, which holds the CURRENT period and includes holds, captures
+ * and refunds — carries the service, the real provider and model, and
+ * `sourceType`/`sourceId`, the run that incurred the charge. The CLI simply
+ * never called it. This command is the read surface for it.
+ *
+ * Denominated in money, because the account is. `balance show` is in credits;
+ * this deliberately does not translate between the two, since nothing in the
+ * codebase establishes that rate for the hosted usage balance and inventing one
+ * would be exactly the confident wrong answer this whole surface suffers from.
+ *
+ * `--workspace` selects the ACCOUNT, exactly as it does on `balance show`. It
+ * is a global flag, so before OSK-4820 it parsed cleanly and was then ignored:
+ * a member sent here by "see the workspace's balance" read their own personal
+ * ledger as the workspace's, under no heading at all. The heading now names
+ * the account on every run, because a ledger that does not say whose it is
+ * cannot be read correctly even when it is the right one (OSK-4822).
+ */
+export default class BalanceStatement extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        after: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        desc: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        before: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * The "More rows" footer, pointing at the cursor that matches the direction the
+ * reader asked for: `--before` continues a newest-first page back through older
+ * rows, `--after` walks an oldest-first page forward. Suggesting the wrong
+ * cursor for the direction — the failure this replaces — sends the reader in a
+ * circle (OSK-4823 / OSK-4907).
+ */
+export declare function statementMoreRowsHint(args: {
+    bin: string;
+    workspaceId: string | undefined;
+    wantNewestFirst: boolean;
+    nextAfterEntryId: string | null;
+    nextBeforeEntryId: string | null;
+}): string | null;
+/**
+ * What a row did to the reader's money.
+ *
+ * The column printed `availableDeltaMicros`, on the theory that the ledger
+ * signs it "by construction". It does — but for a CAPTURE that delta is
+ * `quote − actual`, the unreserved remainder the hold gave back, so a charge
+ * of $0.005 printed as `+$1.43` directly under its `-$1.43` hold and read as a
+ * refund, and the amount actually taken appeared nowhere (OSK-4821).
+ *
+ * The money truth for a settled event is the POSTED movement: `-actual` for a
+ * capture or debit, `+amount` for a credit or refund. A hold or release moves
+ * no posted money, only a reservation, and is labelled as one so it can never
+ * be mistaken for a charge.
+ */
+export declare function statementAmount(entry: Pick<BalanceStatementEntry, 'eventType' | 'amountMicros' | 'postedBalanceDeltaMicros'>, currency: string): string;
+/**
+ * Which account the rows below belong to. Printed on EVERY run: the personal
+ * and workspace ledgers look identical row for row, and a heading is the only
+ * thing that stops one being read as the other.
+ */
+export declare function statementAccountHeading(workspaceId: string | undefined): string;
+/**
+ * Is this 403 the server saying "you are a member, but not the owner"?
+ *
+ * `requireWorkspaceOwner` answers three different 403s: no workspace, not a
+ * member, not the owner. Only the last one is the case the hint below is
+ * written for.
+ */
+export declare function isOwnerOnlyRefusal(err: unknown): boolean;
+/**
+ * What a non-owner member is told instead of a bare 403: the ledger is
+ * owner-only, but the balance the refusal pointed them at is not.
+ */
+export declare function workspaceStatementOwnerOnlyMessage(workspaceId: string, bin: string): string;

package/dist/commands/balance/statement.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statementMoreRowsHint = statementMoreRowsHint;
+exports.statementAmount = statementAmount;
+exports.statementAccountHeading = statementAccountHeading;
+exports.isOwnerOnlyRefusal = isOwnerOnlyRefusal;
+exports.workspaceStatementOwnerOnlyMessage = workspaceStatementOwnerOnlyMessage;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const format_1 = require("../../lib/format");
+const balance_1 = require("../../lib/balance");
+/**
+ * The canonical stored-value ledger — what a charge was FOR, and what incurred it.
+ *
+ * `skrr balance history` reads the LEGACY token transaction view, and that is
+ * why the ledger appeared to explain nothing: every row printed `gateway-usd`
+ * under a MODEL heading (it is not a model), CONTEXT held an internal
+ * accounting term, and the newest row could be a week old while `balance show`
+ * reported usage today (OSK-4664).
+ *
+ * None of that was missing from the product. `/api/balance/statement` — the
+ * unified ledger, which holds the CURRENT period and includes holds, captures
+ * and refunds — carries the service, the real provider and model, and
+ * `sourceType`/`sourceId`, the run that incurred the charge. The CLI simply
+ * never called it. This command is the read surface for it.
+ *
+ * Denominated in money, because the account is. `balance show` is in credits;
+ * this deliberately does not translate between the two, since nothing in the
+ * codebase establishes that rate for the hosted usage balance and inventing one
+ * would be exactly the confident wrong answer this whole surface suffers from.
+ *
+ * `--workspace` selects the ACCOUNT, exactly as it does on `balance show`. It
+ * is a global flag, so before OSK-4820 it parsed cleanly and was then ignored:
+ * a member sent here by "see the workspace's balance" read their own personal
+ * ledger as the workspace's, under no heading at all. The heading now names
+ * the account on every run, because a ledger that does not say whose it is
+ * cannot be read correctly even when it is the right one (OSK-4822).
+ */
+class BalanceStatement extends base_command_1.BaseCommand {
+    static description = 'Canonical billing statement: what each charge was for, and what incurred it — yours, or a workspace’s with --workspace (owner)';
+    static examples = [
+        '<%= config.bin %> balance statement',
+        '<%= config.bin %> balance statement --limit 100 --json',
+        '<%= config.bin %> balance statement --workspace <workspace-id>',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        // The server clamps `limit` to 1..200 silently, so `--limit 300` returned
+        // 200 rows and `--limit 0` fell back to the default with nothing said —
+        // the help promised "(1-200)" but nothing enforced it. `min`/`max` make
+        // oclif reject an out-of-range value with that exact bound in the message,
+        // instead of passing it through to be quietly clamped (OSK-4830).
+        limit: core_1.Flags.integer({ description: 'Rows to return (1-200)', default: 50, min: 1, max: 200 }),
+        after: core_1.Flags.string({ description: 'entryId from a previous page (oldest-first)' }),
+        // The ledger is oldest-first by default, so the row you most want — the
+        // turn you just ran — is the last one on the last page. `--desc` puts it
+        // first (OSK-4823 / OSK-4907). `--before` pages newest-first into older
+        // rows, the reverse of `--after`.
+        desc: core_1.Flags.boolean({ description: 'Show newest entries first' }),
+        before: core_1.Flags.string({
+            description: 'entryId from a previous page, paging newest-first (implies --desc)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(BalanceStatement);
+        // `--workspace` selects the ACCOUNT, so it is answered by a different
+        // endpoint entirely rather than by relabelling the personal one.
+        const workspaceId = flags.workspace;
+        // `--before` names the far end of a newest-first page, so it only makes
+        // sense with descending order; asking for both cursors at once is a
+        // contradiction, not a paging instruction.
+        if (flags.after && flags.before) {
+            this.error('Use --after (oldest-first) or --before (newest-first), not both.', { exit: 1 });
+        }
+        const wantNewestFirst = flags.desc || Boolean(flags.before);
+        // The workspace ledger endpoint is oldest-first only; refusing here beats
+        // silently ignoring the flag and printing ascending rows under a heading
+        // that gave no hint it did so — the exact silent-ignore this command's
+        // --workspace handling was built to stop.
+        if (workspaceId && wantNewestFirst) {
+            this.error('Newest-first paging (--desc/--before) is not available for a workspace statement. ' +
+                'Page it oldest-first with --after, or drop --workspace to read your personal ledger newest-first.', { exit: 1 });
+        }
+        let statement;
+        try {
+            statement = workspaceId
+                ? await (0, balance_1.getWorkspaceBalanceStatement)(workspaceId, flags.limit, flags.after)
+                : await (0, balance_1.getBalanceStatement)(flags.limit, {
+                    after: flags.after,
+                    before: flags.before,
+                    order: wantNewestFirst ? 'desc' : 'asc',
+                });
+        }
+        catch (err) {
+            if (workspaceId && isOwnerOnlyRefusal(err)) {
+                // Membership grants the balance; only ownership grants the ledger. A
+                // bare "Workspace owner access required" leaves a member with no idea
+                // that the thing the refusal told them to look at IS readable. Only
+                // THAT refusal gets the hint: a non-member (or a workspace that does
+                // not exist) is told so by the server's own message, since pointing
+                // them at `balance show` would just refuse them again (OSK-4893).
+                this.failWithCliError({
+                    message: workspaceStatementOwnerOnlyMessage(workspaceId, this.config.bin),
+                    code: 'FORBIDDEN',
+                    status: 403,
+                    exit: 3,
+                    retryable: false,
+                });
+            }
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(statement, null, 2));
+            return;
+        }
+        if (!statement) {
+            this.error('No statement returned.', { exit: 1 });
+        }
+        this.log(statementAccountHeading(workspaceId));
+        const currency = statement.balance.currency;
+        this.log(`Available:  ${(0, balance_1.formatMicros)(statement.balance.availableMicros, currency)}`);
+        // Held is money committed to work in flight — the gap between "there is
+        // money" and "a new session can start".
+        this.log(`Held:       ${(0, balance_1.formatMicros)(statement.balance.heldMicros, currency)}`);
+        this.log(`Posted:     ${(0, balance_1.formatMicros)(statement.balance.postedBalanceMicros, currency)}`);
+        this.log('');
+        const entries = statement.entries ?? [];
+        if (entries.length === 0) {
+            this.log('No ledger entries.');
+            return;
+        }
+        (0, format_1.renderTable)(entries.map((entry) => ({
+            when: entry.createdAt ? String(entry.createdAt).slice(0, 19).replace('T', ' ') : '-',
+            event: (0, format_1.formatCell)(entry.eventType),
+            service: (0, format_1.formatCell)(entry.service),
+            model: (0, balance_1.displayModel)(entry.model),
+            // Which skrr product/harness billed it (sky-code, hosted, …). It was
+            // in --json but never printed, so a human could not tell a code session
+            // from a hosted run (OSK-4825).
+            provider: (0, format_1.formatCell)(entry.provider),
+            // The answer to "which session was this?" — the thing the legacy view
+            // could never name, and the reason that view read as unexplainable. The
+            // compound sourceId already encodes the source type in its first
+            // segment, so it is shown in FULL here: capping it at 34 chars cut the
+            // id off before it began, leaving every row an identical prefix.
+            source: entry.sourceId ? entry.sourceId : (0, format_1.formatCell)(entry.sourceType),
+            amount: statementAmount(entry, currency),
+        })), [
+            { key: 'when', header: 'WHEN' },
+            { key: 'event', header: 'EVENT', maxWidth: 14 },
+            { key: 'service', header: 'SERVICE', maxWidth: 20 },
+            { key: 'model', header: 'MODEL', maxWidth: 26 },
+            { key: 'provider', header: 'PROVIDER', maxWidth: 16 },
+            { key: 'source', header: 'SOURCE' },
+            { key: 'amount', header: 'AMOUNT' },
+        ], (line) => this.log(line));
+        const hint = statementMoreRowsHint({
+            bin: this.config.bin,
+            workspaceId,
+            wantNewestFirst,
+            nextAfterEntryId: statement.nextAfterEntryId,
+            nextBeforeEntryId: statement.nextBeforeEntryId,
+        });
+        if (hint) {
+            this.log('');
+            this.log(hint);
+        }
+    }
+}
+exports.default = BalanceStatement;
+/**
+ * The "More rows" footer, pointing at the cursor that matches the direction the
+ * reader asked for: `--before` continues a newest-first page back through older
+ * rows, `--after` walks an oldest-first page forward. Suggesting the wrong
+ * cursor for the direction — the failure this replaces — sends the reader in a
+ * circle (OSK-4823 / OSK-4907).
+ */
+function statementMoreRowsHint(args) {
+    if (args.wantNewestFirst) {
+        return args.nextBeforeEntryId
+            ? `More rows — \`${args.bin} balance statement --desc --before ${args.nextBeforeEntryId}\``
+            : null;
+    }
+    return args.nextAfterEntryId
+        ? `More rows — \`${args.bin} balance statement${args.workspaceId ? ` --workspace ${args.workspaceId}` : ''} --after ${args.nextAfterEntryId}\``
+        : null;
+}
+/**
+ * What a row did to the reader's money.
+ *
+ * The column printed `availableDeltaMicros`, on the theory that the ledger
+ * signs it "by construction". It does — but for a CAPTURE that delta is
+ * `quote − actual`, the unreserved remainder the hold gave back, so a charge
+ * of $0.005 printed as `+$1.43` directly under its `-$1.43` hold and read as a
+ * refund, and the amount actually taken appeared nowhere (OSK-4821).
+ *
+ * The money truth for a settled event is the POSTED movement: `-actual` for a
+ * capture or debit, `+amount` for a credit or refund. A hold or release moves
+ * no posted money, only a reservation, and is labelled as one so it can never
+ * be mistaken for a charge.
+ */
+function statementAmount(entry, currency) {
+    switch (entry.eventType) {
+        case 'hold':
+            return `${(0, balance_1.formatMicros)(-entry.amountMicros, currency)} held`;
+        case 'release':
+            return `${(0, balance_1.formatMicros)(entry.amountMicros, currency)} released`;
+        default:
+            return (0, balance_1.formatMicros)(entry.postedBalanceDeltaMicros, currency);
+    }
+}
+/**
+ * Which account the rows below belong to. Printed on EVERY run: the personal
+ * and workspace ledgers look identical row for row, and a heading is the only
+ * thing that stops one being read as the other.
+ */
+function statementAccountHeading(workspaceId) {
+    return workspaceId
+        ? `Billing statement — workspace ${workspaceId}`
+        : 'Billing statement — your personal account';
+}
+/**
+ * Is this 403 the server saying "you are a member, but not the owner"?
+ *
+ * `requireWorkspaceOwner` answers three different 403s: no workspace, not a
+ * member, not the owner. Only the last one is the case the hint below is
+ * written for.
+ */
+function isOwnerOnlyRefusal(err) {
+    const e = err;
+    if (!e || e.status !== 403)
+        return false;
+    try {
+        const body = JSON.parse(e.body ?? '');
+        return typeof body.error === 'string' && /owner/i.test(body.error);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What a non-owner member is told instead of a bare 403: the ledger is
+ * owner-only, but the balance the refusal pointed them at is not.
+ */
+function workspaceStatementOwnerOnlyMessage(workspaceId, bin) {
+    return (`The statement for workspace ${workspaceId} is readable by a workspace owner only. ` +
+        `Members can see its balance with \`${bin} balance show --workspace ${workspaceId}\`.`);
+}

package/dist/commands/balance/usage.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Aggregate usage summary.
+ *
+ * The shape is owned server-side by `getUsageSummary` and is not a stable
+ * contract this command should reshape, so the default output pretty-prints
+ * what the server sent rather than inventing a table over fields that may move.
+ */
+export default class BalanceUsage extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+export declare function renderUsageSummary(summary: Record<string, unknown>, log: (line: string) => void): void;
+/**
+ * Why `--workspace` is refused here rather than silently dropped, and where a
+ * workspace's figures actually live.
+ */
+export declare function usageNotWorkspaceScopedMessage(workspaceId: string, bin: string): string;