usage

type CodexModelScanSource struct {
	// contains filtered or unexported fields
}

type CombinedModelScanSource struct {
	Sources []ModelScanSource
}

type CostResult struct {
	InputCost       float64 `json:"input_cost"`
	OutputCost      float64 `json:"output_cost"`
	CacheReadCost   float64 `json:"cache_read_cost"`
	CacheCreateCost float64 `json:"cache_create_cost"`
	TotalCost       float64 `json:"total_cost"`
	Currency        string  `json:"currency"`
	HasPrice        bool    `json:"has_price"`
}

type DayTokens struct {
	InputTokens       int64
	OutputTokens      int64
	CacheReadTokens   int64
	CacheCreateTokens int64
}

type JSONLTokenSource struct {
	// contains filtered or unexported fields
}

type ModelScanSource interface {
	ScanModelRange(startDate, endDate string) ([]ModelTokens, error)
}

type ModelTokens struct {
	Date              string
	Model             string
	InputTokens       int64
	OutputTokens      int64
	CacheReadTokens   int64
	CacheCreateTokens int64
}

type ProbeResult struct {
	Runtime string `json:"runtime"`
	// Status is "ok" | "failed" | "not_supported".
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

type ProviderRow struct {
	// Provider is the display key (e.g. "Claude" / "OpenAI" / "Gemini").
	Provider string `json:"provider"`
	// Runtime is the canonical runtime kind ("claude"|"codex"|"gemini"|"other").
	Runtime           string   `json:"runtime"`
	InputTokens       int64    `json:"input_tokens"`
	OutputTokens      int64    `json:"output_tokens"`
	CacheReadTokens   int64    `json:"cache_read_tokens"`
	CacheCreateTokens int64    `json:"cache_create_tokens"`
	TotalTokens       int64    `json:"total_tokens"`
	Cost              *float64 `json:"cost"`
	Currency          string   `json:"currency,omitempty"`
	// TopModel is the highest-token model id under this provider (主要消耗).
	TopModel string `json:"top_model,omitempty"`
	// Spark is the per-day total-token trend for this provider (oldest-first).
	Spark []int64 `json:"spark"`
}

type QuotaInfo struct {
	// Runtime is the CLI name: "claude", "codex", "gemini".
	Runtime string `json:"runtime"`

	// ── axis 1: account presence (the only axis allowed to hide a provider)
	Present bool `json:"present"`
	// Evidence lists WHY we believe the account is present (credentials/snapshot/sessions).
	// Empty ⟹ Present is false ⟹ the runtime is not shown at all.
	Evidence []string `json:"evidence,omitempty"`

	// ── axis 2: billing mode
	Billing string `json:"billing,omitempty"`

	// ── axis 3: the reading
	Plan string `json:"plan,omitempty"`
	// Family names WHICH set of limits these windows belong to. The provider can switch a
	// codex account between families with different windows ("codex" = 5h+7d, "premium" = one
	// 7-day window), and when it does, a bar simply disappears. Saying which family is active
	// is the only way the user can tell "the provider changed my plan's shape" from
	// "this app broke".
	Family  string        `json:"family,omitempty"`
	Windows []QuotaWindow `json:"windows,omitempty"`
	// Snapshot is nil when no reading has ever been captured.
	Snapshot *SnapshotMeta `json:"snapshot,omitempty"`

	// ── axis 4: runtime health
	Health RuntimeHealth `json:"health"`

	// Note is a human-readable supplementary message.
	Note string `json:"note,omitempty"`
}

type QuotaProvider interface {
	Runtime() string
	// Query assembles the runtime's four axes from what is already on disk. Never reaches out.
	Query() QuotaInfo
	// CanProbe reports whether this runtime can be asked for its current quota.
	CanProbe() bool
	// Probe asks the provider directly and persists the answer so the offline path sees it too.
	// Only ever called on an explicit user request — it costs a real provider round-trip.
	Probe(ctx context.Context) error
}

type QuotaWindow struct {
	// Kind is "5h" | "7d" (derived from WindowMinutes: ≤300 → 5h else 7d).
	Kind string `json:"kind"`
	// WindowMinutes is the window size the runtime reports (300 / 10080).
	WindowMinutes int `json:"window_minutes,omitempty"`
	// UsedPercent / RemainingPercent in [0,100].
	UsedPercent      float64 `json:"used_percent"`
	RemainingPercent float64 `json:"remaining_percent"`
	// ResetAt is the ISO-8601 time the window resets.
	ResetAt string `json:"reset_at,omitempty"`
	// Expired marks a window whose reset time had PASSED by the time we looked. The counter
	// rolled over, so the used% we captured is not merely old — it is wrong. Expiry is
	// per-window on purpose: a 5h window can roll while the 7d window stays perfectly valid,
	// and condemning both would throw away a number that is still true.
	Expired bool `json:"expired,omitempty"`
	// Inferred marks a value we DERIVED rather than observed.
	//
	// Only one inference is made, and only for an expired window: the counter rolled, and any
	// use since would have made the runtime report a fresher reading — none exists, so the
	// window has not been touched since it reset. Its usage is therefore zero. The reset time
	// is rolled forward by whole window lengths to the next real boundary.
	//
	// This is the ONE place the package computes a number it did not observe, and it is
	// labelled as such all the way to the UI.
	Inferred bool `json:"inferred,omitempty"`
}

type RangeTokenSource interface {
	// ScanRange returns per-day token totals for every date in the inclusive
	// [startDate, endDate] range (YYYY-MM-DD, UTC) that has records. Dates with
	// no data may be absent from the map (callers fill zeros).
	ScanRange(startDate, endDate string) (map[string]DayTokens, error)
}

type Reading struct {
	CapturedAt time.Time
	Source     string // SourceHook | SourceRollout | SourceProbe
	Plan       string
	Billing    string // BillingSubscription | BillingAPI — an api reading has no windows by design
	// Family is WHICH set of limits this reading describes. Codex accounts have several
	// ("codex" = 5h+7d, "premium" = a single 7-day window, plus per-model families), and the
	// provider switches which one is ACTIVE. Two families are not two views of one truth —
	// they have different windows entirely — so readings from different families must never
	// be merged window-by-window. The freshest reading wins whole, and it says which family
	// it speaks for, because "why did my 5h bar disappear?" has no other answer.
	Family  string
	Windows []QuotaWindow
}

type ReportRow struct {
	// Date is the ISO-8601 date string for this bucket (YYYY-MM-DD).
	Date string `json:"date"`
	// InputTokens consumed in this bucket.
	InputTokens int64 `json:"input_tokens"`
	// OutputTokens generated in this bucket. (thinking tokens roll into output —
	// Claude usage has no separate thinking field; see cost.go header.)
	OutputTokens int64 `json:"output_tokens"`
	// CacheReadTokens read from cache in this bucket.
	CacheReadTokens int64 `json:"cache_read_tokens"`
	// CacheCreateTokens written to cache in this bucket (CHG-014 R3 — newly aggregated).
	CacheCreateTokens int64 `json:"cache_create_tokens"`
	// TotalTokens is the sum of all token categories.
	TotalTokens int64 `json:"total_tokens"`
	// Cost is the per-day estimated cost (nil when no model in the day had a
	// known price → honest「—」, never a fabricated default).
	Cost *float64 `json:"cost"`
	// Currency for Cost ("USD"|"CNY"|""). Empty when Cost is nil.
	Currency string `json:"currency,omitempty"`
}

type ReportSummary struct {
	InputTokens       int64 `json:"input_tokens"`
	OutputTokens      int64 `json:"output_tokens"`
	CacheReadTokens   int64 `json:"cache_read_tokens"`
	CacheCreateTokens int64 `json:"cache_create_tokens"`
	TotalTokens       int64 `json:"total_tokens"`
	// Cost / Currency: window total estimated cost. Cost nil → no priced model.
	Cost     *float64 `json:"cost"`
	Currency string   `json:"currency,omitempty"`
	// CostComplete is false when ≥1 model in the window had NO price row (so the
	// shown cost UNDER-counts). UI may flag "≈" / "部分模型无价" honestly.
	CostComplete bool `json:"cost_complete"`
}

type RuntimeHealth struct {
	OK      bool   `json:"ok"`
	Reason  string `json:"reason,omitempty"`
	Version string `json:"version,omitempty"`
}

type SnapshotMeta struct {
	// CapturedAt is the ISO-8601 time the reading was taken.
	CapturedAt string `json:"captured_at,omitempty"`
	// AgeSeconds is how old the reading was at query time.
	AgeSeconds int64 `json:"age_seconds"`
	// Source is where the reading came from: SourceHook | SourceRollout | SourceProbe.
	// This is the field that answers "why did refreshing change nothing?" — a rollout reading
	// only moves when the runtime chooses to write one, whereas a probe is us going and asking.
	Source string `json:"source,omitempty"`
	// Stale marks a reading that can no longer be read as current AS A WHOLE (every window it
	// describes has rolled, or it is simply too old). A SINGLE rolled window does not set this —
	// that lives on QuotaWindow.Expired, so a valid 7d number survives an expired 5h one.
	Stale       bool   `json:"stale"`
	StaleReason string `json:"stale_reason,omitempty"`
}

type TokenSource interface {
	// DailyTokens returns (input, output, cacheRead) token totals for the
	// given UTC calendar date (YYYY-MM-DD).  It returns (0,0,0,nil) when the
	// date has no records.
	DailyTokens(date string) (inputTokens, outputTokens, cacheReadTokens int64, err error)
}

type UsageReport struct {
	// Window is the requested reporting window ("7d" or "30d").
	Window WindowKind `json:"window"`
	// StartDate is the ISO-8601 date of the first bucket.
	StartDate string `json:"start_date"`
	// EndDate is the ISO-8601 date of the last bucket (today).
	EndDate string `json:"end_date"`
	// Rows contains per-day buckets ordered oldest-first.
	// Rows are included even when zero so the frontend can render a full chart.
	Rows []ReportRow `json:"rows"`
	// Summary is the aggregate over the whole window.
	Summary ReportSummary `json:"summary"`
	// Providers is the per-provider cost breakdown (settings 报表). Empty when the
	// source can't attribute usage to models (e.g. legacy aggregate-only sources).
	Providers []ProviderRow `json:"providers"`
	// DataSource describes where the data came from.
	DataSource string `json:"data_source"`
	// Available is false when no usage data source is wired up.
	Available bool `json:"available"`
	// Reason explains why Available is false.
	Reason string `json:"reason,omitempty"`
}

type WindowKind string