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 is how long to stop hitting an API after an // upstream error. CooldownDuration = 10 * time.Minute // ManualCooldown is the 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 // StaleTTL is how long missing metrics are preserved from a previous // snapshot. After this window a permanently failed sub-fetch (e.g. // expired cookie) stops carrying forward stale data so the button // can show a setup/error state instead. StaleTTL = 30 * time.Minute )
Variables ¶
var LogSink func(msg string)
LogSink is called for cache observability. Set by the plugin at init. Dispatch is asynchronous (see cacheLog), so the sink does not need to be non-blocking — but callers should not assume log lines arrive strictly before subsequent code runs.
Functions ¶
func ClearCache ¶
func ClearCache(providerID string)
ClearCache removes cached data for a provider (or all if id is "").
func StartCredentialWatcher ¶ added in v0.5.0
func StartCredentialWatcher()
StartCredentialWatcher starts a background goroutine that polls known provider credential files and clears the matching provider's cache entry when the file changes. The next scheduled poll then fetches fresh data instead of waiting up to MinTTL for the timer to advance.
Safe to call more than once — the watcher is a singleton.
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)
Pace metrics intentionally do NOT set a Ratio: mapping ±N% delta onto a 0..1 fill bar produces a "half-filled tile" at 0% that reads like a percent meter at 50% and confuses everyone. The signed value + caption ("On pace" / "Reserve" / "Deficit") carries the signal without a misleading fill.
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
BrandBg returns the background color used on button faces.
func (MockProvider) BrandColor ¶
func (MockProvider) BrandColor() string
BrandColor returns the accent color used on button faces.
func (MockProvider) Fetch ¶
func (MockProvider) Fetch(_ FetchContext) (Snapshot, error)
Fetch returns a synthetic Snapshot driven by time-based sine waves.
func (MockProvider) ID ¶
func (MockProvider) ID() string
ID returns the provider identifier used by the registry.
func (MockProvider) MetricIDs ¶
func (MockProvider) MetricIDs() []string
MetricIDs enumerates the metrics this provider emits.
func (MockProvider) Name ¶
func (MockProvider) Name() string
Name returns the human-readable provider name.
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 PeekSnapshotState ¶ added in v0.5.0
PeekSnapshotState returns the last rendered snapshot and its fetch time without triggering a new fetch. Prefers e.result so stale/error faces produced on the last fetch are preserved across minute redraws; falls back to e.snapshot when no fetch has run.
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 cookieaux holds provider-facing helpers for the browser fetch-proxy path.
|
Package cookieaux holds provider-facing helpers for the browser fetch-proxy path. |
|
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. |