providers

package

v0.2.2 Latest Latest Go to latest Published: Apr 12, 2026 License: MIT Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/anthonybaldwin/UsageButtons

Links

Open Source Insights

Documentation ¶

Overview ¶

Package providers defines the provider interface, snapshot types, and the provider registry.

Index ¶

Constants
Variables
func ClearCache(providerID string)
func Register(p Provider)
type FetchContext
type GetSnapshotOptions
type MetricValue
- func (m MetricValue) NumericVal() float64
- func (m MetricValue) RatioVal() float64
type MockProvider
type Provider
- func Get(id string) Provider
- func List() []Provider
type Snapshot
- func GetSnapshot(p Provider, opts GetSnapshotOptions) Snapshot
- func PeekSnapshot(providerID string) *Snapshot

Constants ¶

View Source

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 ¶

View Source

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 "").

func Register ¶

func Register(p Provider)

Register adds a provider to the global registry.

Types ¶

type FetchContext ¶

type FetchContext struct {
	PollIntervalMs int64
	Force          bool
}

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 (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) 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 Provider ¶

type Provider interface {
	ID() string
	Name() string
	BrandColor() string
	MetricIDs() []string
	Fetch(ctx FetchContext) (Snapshot, error)
}

Provider is the interface every usage-data source implements.

func Get ¶

func Get(id string) Provider

Get returns a provider by ID, or nil.

func List ¶

func List() []Provider

List returns all registered providers.

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 ¶

func PeekSnapshot(providerID string) *Snapshot

PeekSnapshot returns the cached snapshot without fetching.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
claude Package claude implements the Claude OAuth API usage provider.	Package claude implements the Claude OAuth API usage provider.
codex Package codex implements the Codex OAuth API usage provider.	Package codex implements the Codex OAuth API usage provider.
copilot Package copilot implements the GitHub Copilot usage provider.	Package copilot implements the GitHub Copilot usage provider.
cursor Package cursor implements the Cursor usage provider.	Package cursor implements the Cursor usage provider.
kimik2 Package kimik2 implements the Kimi K2 credits provider.	Package kimik2 implements the Kimi K2 credits provider.
openrouter Package openrouter implements the OpenRouter API usage provider.	Package openrouter implements the OpenRouter API usage provider.
warp Package warp implements the Warp AI usage provider.	Package warp implements the Warp AI usage provider.
zai Package zai implements the z.ai usage provider.	Package zai implements the z.ai usage provider.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL