Documentation
¶
Overview ¶
Package providers defines the provider interface, snapshot types, and the provider registry.
Index ¶
Constants ¶
const ( // MinTTL matches the shortest user-selectable poll interval. // Any poll within this window reuses the snapshot. MinTTL = 5 * time.Minute // CooldownDuration: after an upstream error, stop hitting the API. CooldownDuration = 10 * time.Minute // ManualCooldown: minimum gap between user-initiated (force=true) // refreshes per provider. Prevents button-mashing from hammering // upstream APIs. 30s is responsive enough for deliberate retries // but limits a frustrated user to ~2 req/min. ManualCooldown = 30 * time.Second )
Variables ¶
var LogSink func(msg string)
LogSink is called for cache observability. Set by the plugin at init.
Functions ¶
func ClearCache ¶
func ClearCache(providerID string)
ClearCache removes cached data for a provider (or all if id is "").
Types ¶
type FetchContext ¶
FetchContext provides context to a provider's Fetch method.
type GetSnapshotOptions ¶
type GetSnapshotOptions struct {
Force bool
}
GetSnapshotOptions configures a cache lookup.
type MetricValue ¶
type MetricValue struct {
ID string `json:"id"`
Label string `json:"label"`
Name string `json:"name,omitempty"`
Value any `json:"value"` // number or string
NumericValue *float64 `json:"numericValue,omitempty"`
NumericUnit string `json:"numericUnit,omitempty"` // "percent"|"dollars"|"cents"|"count"
NumericGoodWhen string `json:"numericGoodWhen,omitempty"` // "high"|"low"
NumericMax *float64 `json:"numericMax,omitempty"`
Unit string `json:"unit,omitempty"`
Ratio *float64 `json:"ratio,omitempty"` // 0..1
Direction string `json:"direction,omitempty"` // "up"|"down"|"right"|"left"
ResetInSeconds *float64 `json:"resetInSeconds,omitempty"`
Caption string `json:"caption,omitempty"`
RawCount *int `json:"rawCount,omitempty"`
RawMax *int `json:"rawMax,omitempty"`
UpdatedAt string `json:"updatedAt,omitempty"`
Stale *bool `json:"stale,omitempty"`
}
MetricValue represents a single usage metric from a provider.
func PaceMetric ¶ added in v0.3.0
func PaceMetric(in PaceInput) *MetricValue
PaceMetric computes a linear-burn-rate pace metric.
Returns nil if the input is degenerate (zero window, no elapsed time).
The metric value shows the delta between actual and expected usage:
- Positive value = reserve (used less than expected — good)
- Negative value = deficit (used more than expected — bad)
Ratio is mapped 0..1 where 0.5 = on track, 1.0 = full reserve, 0.0 = full deficit. Clamped to [0, 1].
func (MetricValue) NumericVal ¶
func (m MetricValue) NumericVal() float64
NumericVal returns the numeric value or 0.
func (MetricValue) RatioVal ¶
func (m MetricValue) RatioVal() float64
RatioVal returns the ratio or -1 if not set.
type MockProvider ¶
type MockProvider struct{}
MockProvider generates deterministic sine-wave data for development.
func (MockProvider) BrandBg ¶ added in v0.3.0
func (MockProvider) BrandBg() string
func (MockProvider) BrandColor ¶
func (MockProvider) BrandColor() string
func (MockProvider) Fetch ¶
func (MockProvider) Fetch(_ FetchContext) (Snapshot, error)
func (MockProvider) ID ¶
func (MockProvider) ID() string
func (MockProvider) MetricIDs ¶
func (MockProvider) MetricIDs() []string
func (MockProvider) Name ¶
func (MockProvider) Name() string
type PaceInput ¶ added in v0.3.0
type PaceInput struct {
MetricID string // e.g. "session-pace", "weekly-pace"
Label string // e.g. "Session", "Weekly"
Name string // e.g. "Session pace"
UsedPercent float64 // 0-100, how much has been consumed
WindowDuration time.Duration // total window length
ResetIn time.Duration // time remaining until reset
}
PaceInput is the data a provider passes to compute a pace metric.
type Provider ¶
type Provider interface {
ID() string
Name() string
BrandColor() string
BrandBg() string
MetricIDs() []string
Fetch(ctx FetchContext) (Snapshot, error)
}
Provider is the interface every usage-data source implements.
type Snapshot ¶
type Snapshot struct {
ProviderID string `json:"providerId"`
ProviderName string `json:"providerName"`
Source string `json:"source"` // "mock"|"oauth"|"web"|"cli"|"cache"
Metrics []MetricValue `json:"metrics"`
Status string `json:"status,omitempty"`
Error string `json:"error,omitempty"`
}
Snapshot is the result of a single provider fetch.
func GetSnapshot ¶
func GetSnapshot(p Provider, opts GetSnapshotOptions) Snapshot
GetSnapshot returns a provider snapshot, using the cache when possible. Guarantees at most one in-flight fetch per provider.
func PeekSnapshot ¶
PeekSnapshot returns the cached snapshot without fetching.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package claude implements the Claude OAuth API usage provider.
|
Package claude implements the Claude OAuth API usage provider. |
|
Package codex implements the Codex OAuth API usage provider.
|
Package codex implements the Codex OAuth API usage provider. |
|
Package copilot implements the GitHub Copilot usage provider.
|
Package copilot implements the GitHub Copilot usage provider. |
|
Package cursor implements the Cursor usage provider.
|
Package cursor implements the Cursor usage provider. |
|
Package kimik2 implements the Kimi K2 credits provider.
|
Package kimik2 implements the Kimi K2 credits provider. |
|
Package ollama implements the Ollama usage provider.
|
Package ollama implements the Ollama usage provider. |
|
Package openrouter implements the OpenRouter API usage provider.
|
Package openrouter implements the OpenRouter API usage provider. |
|
Package warp implements the Warp AI usage provider.
|
Package warp implements the Warp AI usage provider. |
|
Package zai implements the z.ai usage provider.
|
Package zai implements the z.ai usage provider. |