usage

type Accounts struct {
	Rows    []TotalView `json:"rows"`
	Account SourceState `json:"account"`
	Hanzo   SourceState `json:"hanzo"`
}

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

type AnalyticsView struct {
	Scope         Scope             `json:"scope"`
	Plan          string            `json:"plan"`
	Range         string            `json:"range"`
	Start         string            `json:"start"`
	End           string            `json:"end"`
	RetentionDays int               `json:"retentionDays"`
	Export        bool              `json:"export"`
	Providers     ProviderBreakdown `json:"providers"`
}

type CategorySpend struct {
	Category string `json:"category"`
	Cents    int64  `json:"cents"`
	Count    int64  `json:"count"`
}

type LLM struct {
	Available        bool   `json:"available"`
	Requests         int64  `json:"requests"`
	Tokens           int64  `json:"tokens"`
	PromptTokens     int64  `json:"promptTokens"`
	CompletionTokens int64  `json:"completionTokens"`
	CostCents        int64  `json:"costCents"`
	Models           int64  `json:"models"`
	Source           string `json:"source"`
}

type ProviderBreakdown struct {
	Available bool          `json:"available"`
	Items     []ProviderRow `json:"items"`
	Source    string        `json:"source"`
}

type ProviderRow struct {
	Provider  string `json:"provider"`
	Requests  int64  `json:"requests"`
	Tokens    int64  `json:"tokens"`
	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 Claude Max 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 Scope struct {
	Org  string `json:"org"`
	User string `json:"user,omitempty"` // the caller's subject; whose linked-account rows the accounts block carries
}

type SourceState struct {
	Available bool   `json:"available"`
	Scope     string `json:"scope"`
	Source    string `json:"source"` // the table of record
	Note      string `json:"note"`
}

type Sources struct {
	Commerce  bool `json:"commerce"`
	Warehouse bool `json:"warehouse"`
}

type Spend struct {
	Available      bool            `json:"available"`
	TotalCents     int64           `json:"totalCents"`
	MTDCents       int64           `json:"mtdCents"`
	OverageCents   int64           `json:"overageCents"`
	BalanceCents   int64           `json:"balanceCents"`
	AvailableCents int64           `json:"availableCents"`
	ByCategory     []CategorySpend `json:"byCategory"`
	Series         []SpendPoint    `json:"series"`
	Source         string          `json:"source"`
}

type SpendPoint struct {
	T     string `json:"t"` // RFC3339 bucket start (UTC)
	Cents int64  `json:"cents"`
}

type Summary struct {
	Range    string   `json:"range"`
	Start    string   `json:"start"`
	End      string   `json:"end"`
	Interval string   `json:"interval"`
	Scope    Scope    `json:"scope"`
	Spend    Spend    `json:"spend"`
	LLM      LLM      `json:"llm"`
	Accounts Accounts `json:"accounts"`
	Sources  Sources  `json:"sources"`
}

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     string  `json:"source"` // account | hanzo
	Scope      string  `json:"scope"`  // user | org
	Provider   string  `json:"provider"`
	Window     string  `json:"window,omitempty"`
	Requests   int64   `json:"requests,omitempty"`
	Tokens     int64   `json:"tokens,omitempty"`
	CostCents  int64   `json:"costCents,omitempty"`
	UsedPct    float64 `json:"usedPct,omitempty"`
	Confidence string  `json:"confidence"`
	Windows    int64   `json:"windows,omitempty"`
}