usage

Documentation

Overview

Package usage defines the normalized rate-limit usage model shared across providers. Readers translate each provider's raw API response into these types so the scheduler and CLI can treat every provider uniformly.

Index

• type Credits
• type ResetCredit
• type ResetCredits
• type Usage
  • func (u *Usage) CreditsUsable() bool
  • func (u *Usage) WeeklyExhausted(threshold float64) bool
• type Window
  • func (w Window) Active() bool
  • func (w Window) Missing() bool
  • func (w Window) Remaining() time.Duration

Types

type Credits

type Credits struct {
	HasCredits bool
	Unlimited  bool
	Balance    string
}

Credits describes pay-as-you-go credits that may remain available even when the weekly window is exhausted.

type ResetCredit

type ResetCredit struct {
	Status     string
	GrantedAt  time.Time
	ExpiresAt  time.Time
	RedeemedAt time.Time
}

ResetCredit is a banked Codex rate-limit reset credit.

type ResetCredits

type ResetCredits struct {
	AvailableCount int
	Credits        []ResetCredit
}

ResetCredits summarizes account-backed Codex reset credits.

type Usage

type Usage struct {
	Provider     string
	FiveHour     Window
	Weekly       Window
	Plan         string
	Credits      *Credits
	ResetCredits *ResetCredits
	LimitReached bool
	FetchedAt    time.Time
	Raw          []byte // raw JSON body, for `status -v`
}

Usage is a provider's full rate-limit snapshot at FetchedAt.

func (*Usage) CreditsUsable

func (u *Usage) CreditsUsable() bool

CreditsUsable reports whether credits can cover a request when the weekly window is exhausted.

func (*Usage) WeeklyExhausted

func (u *Usage) WeeklyExhausted(threshold float64) bool

WeeklyExhausted reports whether the weekly window should block new work: its utilization is at/above threshold (0..1, e.g. cfg.WeeklyThreshold) and no usable credits remain. Shared by the scheduler's ping skip and the continue proxy's recovery gate so "weekly is spent" means the same thing everywhere.

type Window

type Window struct {
	UsedPercent   float64
	ResetsAt      time.Time
	WindowSeconds int
}

Window is a single rate-limit window (e.g. the 5h rolling window or the weekly window). UsedPercent is 0..100.

func (Window) Active

func (w Window) Active() bool

Active reports whether the window currently has consumption recorded and has not yet reset. A freshly reset (or never-started) window is inactive, which is the signal the scheduler uses to decide whether to ping immediately.

func (Window) Missing

func (w Window) Missing() bool

Missing reports whether the provider returned no data for this window at all, meaning the limit is not currently enforced (OpenAI temporarily removed Codex's 5h window on 2026-07-12, leaving only the weekly cap). Distinct from an inactive window, which is enforced but has no consumption yet.

func (Window) Remaining

func (w Window) Remaining() time.Duration

Remaining returns the time until this window resets (never negative).