feat(account): read an invoice, and say what a machine actually costs

[Denis-hamon]

Stacked on #265. The reviewable unit is the last commit.

Nothing in the CLI reads an invoice. The /me schema carries 147 billing paths and the
account command exposes none of them: an operator who wants to know what a machine costs, or
what the last invoice charged for, leaves the terminal.

This adds the reading surface, and one command that answers the question a BareMetal operator
actually has.

ovhcloud account bill list [--from] [--to] [--category] [--order-id] [--reveal]
ovhcloud account bill get <bill_id> [--reveal]
ovhcloud account bill details <bill_id>
ovhcloud account refund list [--from] [--to] [--order-id] [--reveal]
ovhcloud account refund get <refund_id> [--reveal]
ovhcloud account usage [--forecast]
ovhcloud baremetal cost <service_name>

What the measurement decided

Measured on a real account, 20 August 2026.

The date window is a guard, not a convenience. The account holds 2215 invoices; a year is
396, a month is 40. ManageListRequest expands one HTTP call per item, so an unbounded bill list
is 2215 requests. Without --from the window is the current month, and past 400 matches the
command says how many rather than making them.

The download link is a bearer credential, and that is measured rather than assumed. A real
invoice pdfUrl returns the PDF in full with no API token at all — HTTP 200,
application/pdf, 298 KB. The same URL with its esign parameter altered returns HTML instead, so
the signature is what authorises. password, url and pdfUrl are therefore fingerprinted by
default and --reveal prints them, with the substitution applied to the object and not in the
template: a mask that only covers the human-readable output covers nothing, because it is the
pipeline that logs.

--category is checked against the schema, not against a list retyped here. billing.CategoryEnum
holds seven values including purchase-servers. The game protocols of #256 were copied by hand and
were already stale when they shipped.

Usage is one row per element, because the entry-level price is null. On every current-period
entry measured, price is null and the amount lives in elements — 22 of 25 entries carry
elements. A table built on the entry would have shown a column of nothing. The forecast fills both,
so the entry price is the fallback.

Dedicated servers do not appear in usage at all — 0 of 12 servers tested. They are billed at a
flat rate, not per usage, which is why baremetal cost exists and reads somewhere else.

baremetal cost, and why it does not read invoices

Summing invoice lines for one machine costs 1109 requests for a single month (40 invoices,
1068 detail lines, none of them filterable by service). /v1/services?resourceName=<server> answers
the same question in six.

It also answers it better. A server is not one billable service but four or five: the machine,
and the components sold with it. So the price shown is the price of the machine as configured:

💶 ns****.ip-51-68-100.eu — 104.99 EUR

ADVANCE-1 | AMD EPYC 4245P
Renews automatic on 2026-09-01.

| Item                                            | Kind     | Price     | Billed             |
|-------------------------------------------------|----------|-----------|--------------------|
| ADVANCE-1 | AMD EPYC 4245P                      | server   | 104.99 €  | rental for 1 month |
| 25Gbps guaranteed unmetered private bandwidth   | included | 0.00 €    | rental for 1 month |
| 2x SSD NVMe 960GB Datacenter Class Soft RAID    | included | 0.00 €    | rental for 1 month |
| 32GB DDR5 On-Die ECC 5600MHz                    | included | 0.00 €    | rental for 1 month |
| 3Gbps unmetered and guaranteed public bandwidth | included | 0.00 €    | rental for 1 month |

Renewal is read here rather than from serviceInfos, deliberately. Six of the 35 servers on the
account are child services — they carry a parentServiceId, renewalType: option, and no renewal
block of their own. On exactly those six, GET /dedicated/server/{sn}/serviceInfos returns
contradictory values for renew.automatic on consecutive reads: 30 reads in 13 seconds gave 16
transitions, with no convergence, every response HTTP 200. The 29 servers without a parent are
stable 20/20, and /v1/services is stable 15/15 everywhere including the six. Filed upstream as
PUBM-55135. So this command reports what is true — the parent carries the renewal — and names
the parent, instead of deriving a boolean that would be right half the time.

Verification

Gate green on the five steps: go build, go vet, make wasm, go test ./..., docgen.

23 tests (18 unit, 15 cobra) and 15 sabotages, 15 red, with restoration verified by
checksum and go test -count=1 after each repair.

Every command was run against the real API: the default window, the category filter, the volume
guard, the masking under -o json (the point that matters), --reveal, the details of a real
invoice, the refunds, both usage routes, and cost on both a normal server and a child service.

Every command named in an error message was checked against the binary's own command tree.

Not in this patch

The billing surfaces that are empty on this account — deposit, withdrawal, reverse bill, down
payment, credit balance, billing group, purchase order, payment transaction, voucher — all return
[], and debtAccount and fidelityAccount return 404. Listing them is demonstrable; their
details are not, on this account. Same reason burst was left out of #254.

Payment methods and the order surface (/me/order, 3625 orders) are their own lot.

[Denis-hamon]

Human review — Does not work

N2 · An invoice link is a bearer secret
Dimension: Secrets

Expected: password, url and pdfUrl are masked by default; --reveal returns them. The substitution happens on the object, so -o json is masked too.

🛑 failed to read invoice FR000000000: failed to fetch object "FR000000000": OVHcloud API error (status code 404): "The requested object (billId = FR000000000) does not exist" (X-OVH-Query-Id: EU.ext-3.6a8b4603.1312250.9060d06909d2489ea661f458fdfb2a1c)

— Denis (Product Manager), through CLI sandbox review page

[Denis-hamon]

Human review — Does not work

N3 · A default date window, and a refusal beyond it
Dimension: Guard rail

Expected: The guard rail is explicit and says how to narrow down, rather than firing off a thousand requests.

🛑 2107 invoices match, which is 2107 requests to detail them.
Narrow the window with --from and --to, or a category with --category.

— Denis (Product Manager), through CLI sandbox review page

[Denis-hamon]

Follow-up on N2 and N3. Both are false negatives, from two different causes.

N2 — the invoice ID was fictitious. FR000000000 is a documentation identifier and nothing was substituting it in live mode, so the reviewer got a 404 from an invoice that has never existed. Pointed at a real invoice, the command does what the check asks:

**Download**: http… (134 characters)
**PDF password**: JdyJ… (10 characters)

The link and the password are hidden. Both are bearer secrets: the link returns
the PDF with no API token at all. Pass --reveal to print them.

The sandbox now retargets per command instead of sending everything to one machine.

N3 — the refusal is the pass. 2107 invoices match, which is 2107 requests to detail them. Narrow the window with --from and --to, or a category with --category. is exactly what the check expects of the guard rail: explicit, with the count, and saying how to narrow down rather than firing off a thousand requests. Exit 1 is correct. Same root cause as three other verdicts that day — the page never said a check can be validated by a refusal; it does now.

[Denis-hamon]

Human review — Works as intended

N3 · A default date window, and a refusal beyond it
Dimension: Guard rail

Expected: The guard rail is explicit and says how to narrow down, rather than firing off a thousand requests.

🛑 2108 invoices match, which is 2108 requests to detail them.
Narrow the window with --from and --to, or a category with --category.

— Denis (Product Manager), through CLI sandbox review page