usage

type Extra ¶

type Extra struct {
	IsEnabled     bool     `json:"is_enabled"`
	MonthlyLimit  *float64 `json:"monthly_limit"`
	UsedCredits   *float64 `json:"used_credits"`
	Utilization   *float64 `json:"utilization"`
	Currency      string   `json:"currency"`
	DecimalPlaces *int     `json:"decimal_places"`
}

Extra describes the pay-as-you-go ("extra usage") state. Pointer fields are null when extra usage is disabled or the value is not reported.

MonthlyLimit and UsedCredits are reported in the currency's MINOR units (e.g. cents), with DecimalPlaces giving the scale — so 2219 credits at 2 decimal places is 22.19. Use UsedAmount / MonthlyLimitAmount to get major units.

func (e Extra) CurrencySymbol() string

func (e Extra) MonthlyLimitAmount() (amount float64, ok bool)

func (e Extra) UsedAmount() (amount float64, ok bool)

type Fetcher ¶ added in v0.26.0

type Fetcher func(context.Context, *http.Client, string) (*Snapshot, error)

Fetcher permits provider-specific pollers.

type MoneyBucket ¶ added in v0.26.0

type MoneyBucket struct {
	ID        string `json:"id"`
	Label     string `json:"label"`
	Used      *int64 `json:"used_minor,omitempty"`
	Limit     *int64 `json:"limit_minor,omitempty"`
	Remaining *int64 `json:"remaining_minor,omitempty"`
	Currency  string `json:"currency,omitempty"`
	Decimals  *int   `json:"decimals,omitempty"`
}

MoneyBucket is an amount in minor units. Each pointer distinguishes an actual zero from an unreported value.

type MultiPoller ¶ added in v0.26.0

type MultiPoller struct {
	Pollers      map[string]*Poller
	StaticStatus map[string]ProviderStatus
	// contains filtered or unexported fields
}

MultiPoller serves independent provider caches. A failed provider does not hide healthy providers.

func (m *MultiPoller) Get(ctx context.Context) map[string]*Snapshot

func (m *MultiPoller) GetAll(ctx context.Context) (map[string]*Snapshot, map[string]ProviderStatus)

func (m *MultiPoller) GetProvider(ctx context.Context, provider string) (*Snapshot, error)

func (m *MultiPoller) ObserveRateLimit(provider, authKind string, fiveHour, sevenDay float64)

func (m *MultiPoller) StaticProviderStatus(provider string) (ProviderStatus, bool)

type Plan ¶ added in v0.26.0

type Plan struct {
	Tier    string `json:"tier,omitempty"`
	Privacy string `json:"privacy,omitempty"`
}

Plan describes an account plan without making it a billing authority.

type Poller ¶

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

Poller caches usage snapshots and refreshes them from the network at most once per minInterval. Concurrent callers single-flight through one fetch. Safe for concurrent use.

func NewPoller(tokenFn TokenFunc) *Poller

func NewProviderPoller(tokenFn TokenFunc, fetch Fetcher) *Poller

func (p *Poller) Get(ctx context.Context) (*Snapshot, error)

type ProviderStatus ¶ added in v0.26.0

type ProviderStatus struct {
	Available bool   `json:"available"`
	AuthKind  string `json:"auth_kind,omitempty"`
	Reason    string `json:"reason,omitempty"`
	Error     string `json:"error,omitempty"`
}

Status is returned even without a snapshot, so UIs never have to infer an API-key credential from absence. Values: pending, temporarily_unavailable, unsupported.

type Quota ¶ added in v0.26.0

type Quota struct {
	ID          string     `json:"id"`
	Label       string     `json:"label"`
	Utilization *float64   `json:"utilization,omitempty"`
	PeriodKind  string     `json:"period_kind,omitempty"`
	PeriodStart *time.Time `json:"period_start,omitempty"`
	PeriodEnd   *time.Time `json:"period_end,omitempty"`
}

Quota is a provider-neutral plan meter. Utilization is nil when the provider reports a period but not its consumption (zero is therefore preserved).

type Snapshot ¶

type Snapshot struct {
	Provider  string        `json:"provider,omitempty"`
	AuthKind  string        `json:"auth_kind,omitempty"`
	Plan      Plan          `json:"plan,omitempty"`
	Quotas    []Quota       `json:"quotas,omitempty"`
	Money     []MoneyBucket `json:"money,omitempty"`
	FetchedAt time.Time     `json:"fetched_at"`
	Stale     bool          `json:"stale,omitempty"`
	Stability string        `json:"stability,omitempty"`

	FiveHour       *Window `json:"five_hour,omitempty"`
	SevenDay       *Window `json:"seven_day,omitempty"`
	SevenDayOpus   *Window `json:"seven_day_opus,omitempty"`
	SevenDaySonnet *Window `json:"seven_day_sonnet,omitempty"`
	Extra          Extra   `json:"extra_usage,omitempty"`
}

Snapshot is the generic, provider-qualified usage contract. The legacy Anthropic fields remain during migration for old REST clients and callers.

func Fetch(ctx context.Context, client *http.Client, token string) (*Snapshot, error)

func FetchXAI(ctx context.Context, client *http.Client, token string) (*Snapshot, error)

func (s *Snapshot) NormalizeAnthropic()

type TokenFunc ¶

type TokenFunc func(ctx context.Context) (token string, ok bool, err error)

TokenFunc returns the current Anthropic OAuth access token. ok is false when no OAuth credential is in use (e.g. a plain API key), in which case usage tracking is unavailable and the poller stays inert.

type Window ¶

type Window struct {
	Utilization float64   `json:"utilization"`
	ResetsAt    time.Time `json:"resets_at"`
}

Window is a single rate-limit window (e.g. the 5-hour session window or the weekly window). Utilization is a percentage in [0, 100].