howmuchleft v0.14.1 /internal/cache
Updated
On this page

Fetches Claude API usage data, caches responses with TTL and exponential backoff, and converts between API, cache, and display formats.

#internal/cache

#internal/cache

#CacheTTL

Go go
const CacheTTL        = 60 * time.Second

Cache TTL constants.

#ErrorCacheTTL

Go go
const ErrorCacheTTL   = 60 * time.Second

#MaxErrorCacheTTL

Go go
const MaxErrorCacheTTL = 5 * time.Minute

#CombinedTimeout

Go go
const CombinedTimeout = 7 * time.Second

#ErrAuth

Go go
var ErrAuth = errors.New("authentication error (401/403)")

ErrAuth is returned when the usage API responds with 401 or 403.

#NowMs

Go go
var NowMs = func() int64 {

NowMs returns the current time in unix milliseconds. Exported for testing.

#UsageResponse

Go go
type UsageResponse struct

UsageResponse is the parsed JSON from the usage API.

#WindowUsage

Go go
type WindowUsage struct

WindowUsage represents a single usage window from the API.

#ExtraUsage

Go go
type ExtraUsage struct

ExtraUsage represents extra/overage usage from the API.

#CacheData

Go go
type CacheData struct

CacheData is persisted to .statusline-cache.json.

#CachedWindow

Go go
type CachedWindow struct

CachedWindow stores a usage window in the cache.

#CachedExtra

Go go
type CachedExtra struct

CachedExtra stores extra usage in the cache.

#UsageResult

Go go
type UsageResult struct

UsageResult is what GetUsageData returns to callers.

#WindowResult

Go go
type WindowResult struct

WindowResult represents a single usage window for display.

#ExtraResult

Go go
type ExtraResult struct

ExtraResult represents extra usage for display.

#FetchUsageFromAPI

Go go
func FetchUsageFromAPI(accessToken string) (*UsageResponse, error)

FetchUsageFromAPI calls the usage API with the given access token. Returns ErrAuth for 401/403, generic error for other failures.

#ReadCache

Go go
func ReadCache(claudeDir string) *CacheData

ReadCache reads the cache file from claudeDir. Returns nil on any error.

#WriteCache

Go go
func WriteCache(claudeDir string, data *CacheData) error

WriteCache atomically writes cache data to the cache file.

#IsCacheValid

Go go
func IsCacheValid(cache *CacheData, now int64, forceRefresh bool) bool

IsCacheValid determines whether the cached data can be used without refresh.

#GetUsageData

Go go
func GetUsageData(claudeDir string, forceRefresh bool) *UsageResult

GetUsageData is the main entry point: reads cache, fetches if needed, returns results.

#ParseWindowFromMap

Go go
func ParseWindowFromMap(m map[string]interface{}) (percent *float64, resetAtMs *int64)

ParseWindowFromMap extracts used_percentage and resets_at from a rate limit window map (five_hour or seven_day). Returns nil for either value if the key is missing or has the wrong type. resets_at is converted from unix seconds to unix milliseconds. Does NOT apply to extra_usage (different shape).

#WriteUsageFromStdin

Go go
func WriteUsageFromStdin(claudeDir string, rateLimits map[string]interface{}) error

WriteUsageFromStdin writes rate limit data from stdin directly to cache, bypassing the API. This is the "newer Claude Code" path where rate_limits are provided in the stdin JSON.

Search