usage

type Accounts struct {
	// Rows is the two row sets CONCATENATED, never summed — each row says which
	// side it came from. A percent is not money and a provider's own spend is not
	// a Hanzo charge, so adding them would produce a number that means nothing.
	Rows []TotalView `json:"rows"`
	// Account is the state of the caller's own linked-account side.
	Account SourceState `json:"account"`
	// Hanzo is the state of the org's Hanzo-routed side.
	Hanzo SourceState `json:"hanzo"`
}

type AnalyticsAccess struct {
	Datastore     bool // analytics.datastore
	RetentionDays int  // analytics.retention_days
	Export        bool // analytics.export
}

type CategorySpend struct {
	// Category is the bucket the ledger's own tag mapped to. An untagged or
	// unrecognised line gets its own honest bucket rather than being folded away.
	Category string `json:"category"`
	// Cents is what the org spent in that bucket over the window, in US cents.
	Cents int64 `json:"cents"`
	// Count is how many ledger lines rolled up into it.
	Count int64 `json:"count"`
}

type LLM struct {
	// Available is false when the warehouse was not connected or a query blipped.
	// The totals below are then honest zeros, NOT measured ones.
	Available bool `json:"available"`
	// Requests is how many completions the org made in the window.
	Requests int64 `json:"requests"`
	// Tokens is the total tokens those completions consumed.
	Tokens int64 `json:"tokens"`
	// PromptTokens is the input half of that total.
	PromptTokens int64 `json:"promptTokens"`
	// CompletionTokens is the output half.
	CompletionTokens int64 `json:"completionTokens"`
	// CostCents is what they cost the org, in US cents. This IS a Hanzo charge.
	CostCents int64 `json:"costCents"`
	// Models is how many distinct models were used.
	Models int64 `json:"models"`
	// Source names the warehouse table the totals came from.
	Source string `json:"source"`
}

type ProviderBreakdown struct {
	// Available is false when the warehouse could not be read, which means "no
	// answer" and NOT "no usage" — Items is then empty for a reason.
	Available bool `json:"available"`
	// Items is one row per provider, most tokens first.
	Items []ProviderRow `json:"items"`
	// Source names the warehouse table the rows came from.
	Source string `json:"source"`
}

type ProviderRow struct {
	// Provider is the upstream the requests were routed to, e.g. anthropic.
	Provider string `json:"provider"`
	// Requests is how many completions the org made against that provider.
	Requests int64 `json:"requests"`
	// Tokens is the total tokens those completions consumed, prompt plus
	// completion.
	Tokens int64 `json:"tokens"`
	// CostCents is what they cost the org, in US cents.
	CostCents int64 `json:"costCents"`
}

type Sample struct {
	Provider string // matches Link.Provider / @hanzo/usage providerRegistry id
	Account  string // the account label (an identifier, never a secret)
	Plan     string // the plan name from the provider identity; display only
	Kind     string // subscription | apikey (validKind) — mirrors Link.Kind
	Machine  string // the machine that OBSERVED this (an attribute, not a key)

	Lane          string    // the meter's lane id (five_hour|seven_day_opus|…) — the identity
	Window        string    // the canonical class (6h|day|week|month)
	WindowMinutes int32     // the duration the meter reported (300 for Claude's 5h)
	WindowStart   time.Time // WHICH instance of the window this measures — the dedup key
	ResetsAt      time.Time // when the window resets (RateWindow.resetsAt); zero = unknown

	// UsedPct is the lane's used percent, 0..100 — RateWindow.usedPercent. For a
	// subscription account this is THE quota signal and often the ONLY one.
	//
	// QUOTA GAP (deliberate, reported, not faked): there is NO absolute
	// used/limit token quota column, because nothing can populate one. The meter
	// reports a percent, not a limit (Claude: dataConfidence `percentOnly`). The
	// hanzoai/plans catalog expresses `ai.requests_per_min` / `ai.tokens_per_min`
	// — per-MINUTE rate limits, a different concept from a window quota — and in
	// any case it is HANZO's own plan catalog, which cannot know what Anthropic
	// grants a subscription plan. An always-zero quota_limit would read as "the
	// limit is zero"; absent is honest. It lands as an additive column when a
	// source for it exists.
	UsedPct    float64
	Confidence string // exact|estimated|percentOnly|unknown — see the const block
	// Synthetic marks a lane the meter FABRICATED (RateWindow.isSyntheticPlaceholder
	// — set when a provider returned null for a lane and the adapter filled it in).
	// Carried so a made-up lane is never rendered as observed truth.
	Synthetic bool

	// Absolute counters — UsageTotals. Present only when the source really reports
	// them (`exact`); zero otherwise, which Confidence disambiguates.
	Requests          int64
	InputTokens       int64
	OutputTokens      int64
	TotalTokens       int64
	CachedInputTokens int64

	// Money — ProviderCostSnapshot, in minor units (cents). CostCents is what the
	// PROVIDER says this account spent (Claude's extra_usage overage; 0 for a flat
	// subscription — the plan is the charge). CostLimitCents is that meter's budget
	// (ProviderCostSnapshot.limit) — a MONEY cap, never a token quota. Neither is a
	// Hanzo charge: this plane holds no metering client.
	CostCents      int64
	CostLimitCents int64
	Currency       string // ProviderCostSnapshot.currencyCode; "" = unknown
}

type SourceState struct {
	// Available is whether this side's ledger answered. False means its rows are
	// missing, not that there were none.
	Available bool `json:"available"`
	// Scope is whose rows this side carries: "user" or "org".
	Scope string `json:"scope"`
	// Source is the table of record the rows came from.
	Source string `json:"source"`
	// Note is the human sentence that says what this side's numbers mean, so a
	// board cannot present a plan percentage as a Hanzo charge.
	Note string `json:"note"`
}

type Sources struct {
	// Commerce is whether the billing ledger answered the spend block.
	Commerce bool `json:"commerce"`
	// Warehouse is whether the usage warehouse answered the LLM block.
	Warehouse bool `json:"warehouse"`
}

type Spend struct {
	// Available is false when the commerce ledger was unconfigured or
	// unreachable. Every number below is then an honest zero, NOT a measured one.
	Available bool `json:"available"`
	// TotalCents is consumption over the requested window, in US cents. It is
	// self-consistent with ByCategory and Series.
	TotalCents int64 `json:"totalCents"`
	// MTDCents is commerce's authoritative month-to-date consumed figure, which
	// is a different period from the window and is not derived from it.
	MTDCents int64 `json:"mtdCents"`
	// OverageCents is month-to-date consumption beyond the plan's allowance.
	OverageCents int64 `json:"overageCents"`
	// BalanceCents is the prepaid wallet's balance, in US cents.
	BalanceCents int64 `json:"balanceCents"`
	// AvailableCents is what of that balance is still spendable.
	AvailableCents int64 `json:"availableCents"`
	// ByCategory is the window's spend split by ledger category, largest first.
	ByCategory []CategorySpend `json:"byCategory"`
	// Series is the window's spend over time, gap-filled at the window's
	// interval.
	Series []SpendPoint `json:"series"`
	// Source names where the roll-up came from.
	Source string `json:"source"`
}

type SpendPoint struct {
	// T is the bucket's start instant, RFC3339 UTC. Buckets are gap-filled, so a
	// window with no spend still has its points.
	T string `json:"t"`
	// Cents is the consumption recorded in that bucket, in US cents.
	Cents int64 `json:"cents"`
}

type Total struct {
	Source     string
	Scope      string
	Provider   string
	Window     string
	Requests   int64
	Tokens     int64
	CostCents  int64
	UsedPct    float64
	Confidence string
	Windows    int64
}

type TotalView struct {
	// Source is where the row came from: "account" is the provider's own meter
	// on the caller's linked account, "hanzo" is Hanzo-routed inference. The two
	// are never summed.
	Source string `json:"source"`
	// Scope is whose row it is: "user" for the caller's own linked accounts,
	// "org" for the whole tenant's Hanzo-routed usage.
	Scope string `json:"scope"`
	// Provider is the upstream the usage was measured against.
	Provider string `json:"provider"`
	// Window is the meter window class the row rolls up, when it has one.
	Window string `json:"window,omitempty"`
	// Requests is how many requests the row covers.
	Requests int64 `json:"requests,omitempty"`
	// Tokens is the total tokens the row covers.
	Tokens int64 `json:"tokens,omitempty"`
	// CostCents is the row's cost in US cents. For an "account" row this is the
	// PROVIDER's own charge, not a Hanzo one.
	CostCents int64 `json:"costCents,omitempty"`
	// UsedPct is how much of a plan window the row consumed, 0–100. It is a
	// share, never money.
	UsedPct float64 `json:"usedPct,omitempty"`
	// Confidence says how much the counters mean; a percentage-only meter leaves
	// them at zero.
	Confidence string `json:"confidence"`
	// Windows is how many window instances rolled up into the row.
	Windows int64 `json:"windows,omitempty"`
}