feat: usage report transaction IDs, usage history and exports

README.md

@@ -90,7 +90,7 @@ accepted.
 | Command                    | Operations                                                                                      |
 | -------------------------- | ----------------------------------------------------------------------------------------------- |
 | `kaiten customers`         | `list`, `get`, `create`, `update`, `delete`                                                     |
-| `kaiten instances`         | `list`, `get`, `create`, `update`, `delete`, `audit-trails`, `usage list\|get\|report`          |
+| `kaiten instances`         | `list`, `get`, `create`, `update`, `delete`, `audit-trails`, `usage list\|get\|report\|history\|export` |
 | `kaiten licenses`          | `list`, `get`, `create`, `update`, `delete`, `entitlements list\|get\|associate\|update\|delete` |
 | `kaiten entitlements`      | `list`, `get`, `create`, `update`, `delete`                                                     |
 | `kaiten entitlement-groups`| `list`, `get`, `create`, `update`, `delete`, `add-entitlement`, `remove-entitlement`, `usage`   |
@@ -99,6 +99,7 @@ accepted.
 | `kaiten releases`          | `list`, `get`, `create`, `delete`                                                               |
 | `kaiten service-accounts`  | `list`, `get`, `create`, `update`, `tokens list\|create\|delete`                                |
 | `kaiten deployment-zones`  | `list`, `get`, `create`, `update`, `delete`                                                     |
+| `kaiten billing`           | `settings`, `capabilities`, `health`, `sync`, `close-periods`, `handoff`, `invoices`, `subscriptions`, `prices`, `addons`, `instance-addons`, `vouchers`, `publishable-keys`, `customer-sessions`, `customers` |
 | `kaiten config`            | `set`, `unset`, `view`                                                                          |
 | `kaiten doctor`            | Validate configuration and API connectivity                                                     |
 | `kaiten version`           | Print version, commit and build date                                                            |
@@ -116,7 +117,8 @@ kaiten licenses entitlements list team-v1
 kaiten instances audit-trails acme-production --event-name INSTANCE_UPDATED --after 2026-01-01T00:00:00Z --limit 100
 ```
 
-`--output` (or `KAITEN_OUTPUT`) selects `table`, `json` or `yaml`.
+`--output` (or `KAITEN_OUTPUT`) selects `table`, `json`, `yaml` or `ndjson` (one compact
+JSON document per line: one per row of a list).
 
 Without it, the format follows what the command returns. A list prints a table. A single
 resource (`get`, `create`, a usage report, a new token) prints YAML, and so does
@@ -210,6 +212,62 @@ kaiten instances usage list acme-production
 kaiten entitlement-groups usage compute acme-production
 ```
 
+A report without a key is sent once and never retried: if it fails in flight, it may
+or may not have been counted. Give it a `--transaction-id` and Kaiten applies it at
+most once per key, so the CLI retries it on network errors and on 500, 502, 503 and
+504, and running the same command again is safe. A report the server had already
+counted is answered from the first time, with a note on stderr; stdout is unchanged.
+
+```shell
+kaiten instances usage report acme-production tokens --value 1200 \
+  --transaction-id llm-call:9f2c:tokens
+```
+
+A key already used for a different report exits `5`: send a correction as a new
+report under a new key.
+
+The usage history lists every accepted report, with the counter before and after it
+and the limit it was gated on. The range defaults to the last 30 days.
+
+```shell
+kaiten instances usage history acme-production tokens --from 2026-10-01T00:00:00Z
+
+# Stream it as CSV (default) or NDJSON: one pair, up to 366 days per run...
+kaiten instances usage export acme-production tokens > tokens.csv
+# ...or the whole organization, up to 31 days per run, narrowed if needed
+kaiten instances usage export --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z \
+  --format json --output-file usage-september.ndjson
+```
+
+`--instance-id` and `--entitlement-id` reach deleted instances and entitlements,
+whose reports are kept. A `--from` before the start of the organization's history
+exits `5`. Exports are written as they arrive and are not bound by the CLI's request
+timeout; `--output-file` only takes its final name once the export is complete.
+
+### Billing
+
+```shell
+# Invoices: filter, export, settle
+kaiten billing invoices list --overdue --customer acme
+kaiten billing invoices list --updated-since 2027-01-01T00:00:00Z --output json
+kaiten billing invoices export --from 2027-01-01T00:00:00Z --to 2027-02-01T00:00:00Z \
+  --granularity invoice --output-file january.csv
+kaiten billing invoices mark-paid inv_123 --external-reference WIRE-9
+kaiten billing invoices void inv_123 --reason "duplicate" --yes
+
+# The accounting handoff: lease a batch, book it, acknowledge each invoice
+kaiten billing handoff claim --limit 50 --lease 30m --output ndjson > batch.ndjson
+kaiten billing handoff ack inv_123 --lease-id lease_456 --external-reference ACC-2027-0001
+
+# Subscriptions, prices, add-ons and vouchers take their body from --file or --payload
+kaiten billing subscriptions subscribe acme-prod --payload '{"basePriceId":"price_1"}'
+kaiten billing prices preview team-v1 --file scenario.yaml
+kaiten billing instance-addons set-quantity acme-prod extra-seats --quantity 5
+```
+
+Amounts are printed in the currency's minor units, as the API carries them. An
+acknowledgement with `--lease-id` for an invoice another claim took since exits `5`.
+
 ### Service account tokens
 
 ```shell
@@ -222,7 +280,9 @@ The plaintext token is printed once; the API stores a hash.
 
 ### Destructive commands
 
-`delete`, `remove-entitlement` and `config unset` echo their target and ask for
+`delete`, `remove-entitlement`, `config unset` and the billing commands that
+cannot be undone (`invoices void`, `invoices write-off`, `subscriptions cancel`,
+`instance-addons detach`, the `revoke`s, ...) echo their target and ask for
 confirmation. When stdin is not an interactive terminal they refuse to run instead of
 prompting, so scripts and CI pipelines pass `--yes`:
 

go.mod

@@ -3,7 +3,7 @@ module github.com/kaitencloud/cli
 go 1.25.0
 
 require (
-	github.com/kaitencloud/sdk-go v0.1.0
+	github.com/kaitencloud/sdk-go v0.3.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
 	gopkg.in/yaml.v3 v3.0.1

go.sum

@@ -11,8 +11,8 @@ github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/juju/gnuflag v0.0.0-20171113085948-2ce1bb71843d/go.mod h1:2PavIy+JPciBPrBUjwbNvtwB6RQlve+hkpll6QSNmOE=
-github.com/kaitencloud/sdk-go v0.1.0 h1:r75JTSnJAxrzGsMRTTt2qxJ3wWpKrAgV5wLZ2CnZycU=
-github.com/kaitencloud/sdk-go v0.1.0/go.mod h1:KE77iZ8i+SfjjhUf+qPaQrLHq3/EpFuz4+UPtZ7WFeM=
+github.com/kaitencloud/sdk-go v0.3.0 h1:jggYxW7xgI5TgwYIOCSfIF55uqmqN1lRCtpAJl9SrFo=
+github.com/kaitencloud/sdk-go v0.3.0/go.mod h1:KE77iZ8i+SfjjhUf+qPaQrLHq3/EpFuz4+UPtZ7WFeM=
 github.com/oapi-codegen/runtime v1.3.1 h1:RgDY6J4OGQLbRXhG/Xpt3vSVqYpHQS7hN4m85+5xB9g=
 github.com/oapi-codegen/runtime v1.3.1/go.mod h1:kOdeacKy7t40Rclb1je37ZLFboFxh+YLy0zaPCMibPY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=