core

type AccountConfig struct {
	ID         string            `json:"id"`
	Provider   string            `json:"provider"`
	Auth       string            `json:"auth,omitempty"`        // "api_key", "oauth", "cli", "local", "token"
	APIKeyEnv  string            `json:"api_key_env,omitempty"` // env var name holding the API key
	ProbeModel string            `json:"probe_model,omitempty"` // model to use for probe requests
	Binary     string            `json:"binary,omitempty"`      // path to CLI binary
	BaseURL    string            `json:"base_url,omitempty"`    // custom API base URL (e.g. for OpenRouter)
	Token      string            `json:"-"`                     // runtime-only: access token (never persisted)
	ExtraData  map[string]string `json:"-"`                     // runtime-only: extra detection data
}

type DashboardColorRole string

type DashboardCompactRow struct {
	Label       string
	Keys        []string
	Matcher     DashboardMetricMatcher
	MaxSegments int
}

type DashboardDisplayStyle string

type DashboardMetricGroupOverride struct {
	Group string
	Label string
	Order int
}

type DashboardMetricMatcher struct {
	Prefix string
	Suffix string
}

type DashboardRawGroup struct {
	Label string
	Keys  []string
}

type DashboardResetStyle string

type DashboardStandardSection string

type DashboardWidget struct {
	DisplayStyle DashboardDisplayStyle
	ResetStyle   DashboardResetStyle
	ColorRole    DashboardColorRole
	// Opt-in client composition panel (client share + trend) in tile view.
	ShowClientComposition bool
	// Opt-in tool composition panel (tool share) in tile view.
	ShowToolComposition bool

	// API key provider metadata. APIKeyEnv marks a provider as configurable in API Keys tab.
	APIKeyEnv        string
	DefaultAccountID string

	// When ResetStyle is DashboardResetStyleCompactModelResets and the number of active
	// reset entries meets/exceeds this value, reset pills are grouped.
	ResetCompactThreshold int

	GaugePriority               []string
	GaugeMaxLines               int
	CompactRows                 []DashboardCompactRow
	RawGroups                   []DashboardRawGroup
	MetricLabelOverrides        map[string]string
	MetricGroupOverrides        map[string]DashboardMetricGroupOverride
	CompactMetricLabelOverrides map[string]string

	HideMetricKeys     []string
	HideMetricPrefixes []string
	// Hide key-level "credits" row when richer account-level balance metric is present.
	HideCreditsWhenBalancePresent bool

	// Hide noisy metrics that are often zero-value for this provider.
	SuppressZeroMetricKeys []string
	// Hide all zero-valued non-quota metrics.
	SuppressZeroNonUsageMetrics bool

	// StandardSectionOrder controls normalized tile section ordering and visibility.
	// Unknown values are ignored; omitted sections are hidden.
	StandardSectionOrder []DashboardStandardSection

	DataSpec WidgetDataSpec
}

type DetailSection struct {
	Name  string
	Order int
	Style DetailSectionStyle
}

type DetailSectionStyle string

type DetailWidget struct {
	Sections []DetailSection
}

type Metric struct {
	Limit     *float64 `json:"limit,omitempty"`
	Remaining *float64 `json:"remaining,omitempty"`
	Used      *float64 `json:"used,omitempty"`
	Unit      string   `json:"unit"`   // "requests", "tokens", "USD", "credits"
	Window    string   `json:"window"` // "1m", "1d", "month", "rolling-5h", etc.
}

type MetricGroup string

type ModelNormalizationConfig struct {
	Enabled       bool                         `json:"enabled"`
	GroupBy       string                       `json:"group_by,omitempty"`       // lineage | release
	MinConfidence float64                      `json:"min_confidence,omitempty"` // 0..1
	Overrides     []ModelNormalizationOverride `json:"overrides,omitempty"`
}

type ModelNormalizationOverride struct {
	Provider         string `json:"provider,omitempty"`
	RawModelID       string `json:"raw_model_id"`
	CanonicalLineage string `json:"canonical_lineage_id"`
	CanonicalRelease string `json:"canonical_release_id,omitempty"`
	CanonicalModel   string `json:"canonical_model,omitempty"`
}

type ModelUsageRecord struct {
	RawModelID string `json:"raw_model_id"`
	RawSource  string `json:"raw_source,omitempty"` // api | jsonl | sqlite | metrics_fallback

	CanonicalLineageID string `json:"canonical_lineage_id,omitempty"`
	CanonicalReleaseID string `json:"canonical_release_id,omitempty"`
	CanonicalVendor    string `json:"canonical_vendor,omitempty"`
	CanonicalFamily    string `json:"canonical_family,omitempty"`
	CanonicalVariant   string `json:"canonical_variant,omitempty"`
	Canonical          string `json:"canonical,omitempty"` // Canonical model name for consistent identification

	Confidence float64 `json:"confidence,omitempty"` // 0..1
	Reason     string  `json:"reason,omitempty"`

	Window     string            `json:"window,omitempty"`
	Dimensions map[string]string `json:"dimensions,omitempty"` // provider/account/client/endpoint

	InputTokens     *float64 `json:"input_tokens,omitempty"`
	OutputTokens    *float64 `json:"output_tokens,omitempty"`
	CachedTokens    *float64 `json:"cached_tokens,omitempty"`
	ReasoningTokens *float64 `json:"reasoning_tokens,omitempty"`
	TotalTokens     *float64 `json:"total_tokens,omitempty"`
	CostUSD         *float64 `json:"cost_usd,omitempty"`
	Requests        *float64 `json:"requests,omitempty"`
}

type ProviderAuthSpec struct {
	Type             ProviderAuthType
	APIKeyEnv        string
	DefaultAccountID string
}

type ProviderAuthType string

type ProviderInfo struct {
	Name         string   // e.g. "OpenAI", "Anthropic"
	Capabilities []string // "headers", "cli_stats", "usage_endpoint", "credits_endpoint"
	DocURL       string   // link to vendor's rate-limit documentation
}

type ProviderSetupSpec struct {
	DocsURL    string
	Quickstart []string
}

type ProviderSpec struct {
	ID        string
	Info      ProviderInfo
	Auth      ProviderAuthSpec
	Setup     ProviderSetupSpec
	Dashboard DashboardWidget
	Detail    DetailWidget
}

type Status string

type TimePoint struct {
	Date  string  `json:"date"`  // "2025-01-15"
	Value float64 `json:"value"` // metric value at that date
}

type TimeWindow string

type UsageProvider interface {
	ID() string

	Describe() ProviderInfo

	// Spec defines provider-level auth/setup metadata and presentation defaults.
	Spec() ProviderSpec

	// DashboardWidget defines how provider metrics should be presented in dashboard tiles.
	DashboardWidget() DashboardWidget
	// DetailWidget defines how sections should be rendered in the details panel.
	DetailWidget() DetailWidget

	Fetch(ctx context.Context, acct AccountConfig) (UsageSnapshot, error)
}

type UsageSnapshot struct {
	ProviderID  string                 `json:"provider_id"`
	AccountID   string                 `json:"account_id"`
	Timestamp   time.Time              `json:"timestamp"`
	Status      Status                 `json:"status"`
	Metrics     map[string]Metric      `json:"metrics"`                // keys like "rpm", "tpm", "rpd"
	Resets      map[string]time.Time   `json:"resets,omitempty"`       // e.g. "rpm_reset"
	Attributes  map[string]string      `json:"attributes,omitempty"`   // normalized provider/account metadata
	Diagnostics map[string]string      `json:"diagnostics,omitempty"`  // non-fatal errors, warnings, probe/debug notes
	Raw         map[string]string      `json:"raw,omitempty"`          // provider metadata/debug bag (not for primary quota analytics)
	ModelUsage  []ModelUsageRecord     `json:"model_usage,omitempty"`  // per-model usage rows with canonical IDs
	DailySeries map[string][]TimePoint `json:"daily_series,omitempty"` // time-indexed data (e.g. "messages", "cost", "tokens_<model>")
	Message     string                 `json:"message,omitempty"`      // human-readable summary
}

type WidgetDataSpec struct {
	RequiredMetricKeys []string
	OptionalMetricKeys []string
	MetricPrefixes     []string
}