usage

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 28, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package usage reads Codex rate-limit status from the ChatGPT backend.

Index

Constants

View Source 
const (
	RedeemReset           = "reset"
	RedeemNothingToReset  = "nothing_to_reset"
	RedeemNoCredit        = "no_credit"
	RedeemAlreadyRedeemed = "already_redeemed"
)

Outcomes of redeeming a usage limit reset.

View Source 
const DefaultBaseURL = "https://chatgpt.com/backend-api"

DefaultBaseURL is the ChatGPT backend used by the Codex CLI.

Variables

View Source 
var ErrUnauthorized = errors.New("access token was rejected")

ErrUnauthorized means the access token was rejected.

Functions

This section is empty.

Types

type AdditionalRateLimit 

type AdditionalRateLimit struct {
	LimitName      string     `json:"limit_name"`
	MeteredFeature string     `json:"metered_feature"`
	RateLimit      *RateLimit `json:"rate_limit"`
}

AdditionalRateLimit is a separately metered limit, e.g. for one model.

type Client 

type Client struct {
	BaseURL   string
	HTTP      *http.Client
	UserAgent string
}

Client fetches usage from the ChatGPT backend.

func NewClient 

func NewClient(baseURL string, httpClient *http.Client, userAgent string) *Client

NewClient returns a Client for baseURL, falling back to DefaultBaseURL.

func (*Client) Fetch 

func (c *Client) Fetch(ctx context.Context, creds Credentials) (*Response, error)

Fetch returns the current usage for one workspace.

func (*Client) FetchResetCredits 

func (c *Client) FetchResetCredits(ctx context.Context, creds Credentials) (*ResetCredits, error)

FetchResetCredits lists the usage limit resets a workspace has earned.

func (*Client) Redeem 

func (c *Client) Redeem(ctx context.Context, creds Credentials, requestID, creditID string) (*RedeemResult, error)

Redeem spends a usage limit reset, clearing the workspace's current limits. requestID is an idempotency key: retrying with the same ID never spends a second reset. An empty creditID lets the server pick the reset.

type Credentials 

type Credentials struct {
	AccessToken string
	AccountID   string
	FedRAMP     bool
}

Credentials authorize a usage request for one workspace.

type Credits 

type Credits struct {
	HasCredits bool       `json:"has_credits"`
	Unlimited  bool       `json:"unlimited"`
	Balance    flexString `json:"balance"`
}

Credits is the purchased-credit balance.

type RateLimit 

type RateLimit struct {
	Allowed         bool    `json:"allowed"`
	LimitReached    bool    `json:"limit_reached"`
	PrimaryWindow   *Window `json:"primary_window"`
	SecondaryWindow *Window `json:"secondary_window"`
}

RateLimit is the state of a limit and its windows.

func (*RateLimit) Blocked 

func (r *RateLimit) Blocked() bool

Blocked reports whether the limit currently stops usage.

func (*RateLimit) Windows 

func (r *RateLimit) Windows() []*Window

Windows returns the non-nil windows of a limit, primary first.

type RedeemResult 

type RedeemResult struct {
	Code         string `json:"code"`
	WindowsReset int64  `json:"windows_reset"`
}

RedeemResult is the outcome of redeeming a usage limit reset.

type ResetCredit 

type ResetCredit struct {
	ID          string `json:"id"`
	ResetType   string `json:"reset_type"`
	Status      string `json:"status"` // available, redeeming or redeemed
	GrantedAt   string `json:"granted_at"`
	ExpiresAt   string `json:"expires_at"` // RFC 3339; empty if it never expires
	Title       string `json:"title"`
	Description string `json:"description"`
}

ResetCredit is one earned usage limit reset.

func (ResetCredit) Expiry 

func (c ResetCredit) Expiry() (time.Time, bool)

Expiry is when the credit expires, if it does.

type ResetCredits 

type ResetCredits struct {
	Credits          []ResetCredit `json:"credits"`
	AvailableCount   int64         `json:"available_count"`
	TotalEarnedCount int64         `json:"total_earned_count"`
}

ResetCredits is the list of usage limit resets from /wham/rate-limit-reset-credits. Redeeming one clears the current limits.

func (*ResetCredits) Available 

func (r *ResetCredits) Available() []ResetCredit

Available returns the redeemable credits, soonest to expire first.

type Response 

type Response struct {
	PlanType             string                `json:"plan_type"`
	RateLimit            *RateLimit            `json:"rate_limit"`
	CodeReviewRateLimit  *RateLimit            `json:"code_review_rate_limit"`
	AdditionalRateLimits []AdditionalRateLimit `json:"additional_rate_limits"`
	Credits              *Credits              `json:"credits"`
	SpendControl         *struct {
		Reached bool `json:"reached"`
	} `json:"spend_control"`
	RateLimitReachedType *struct {
		Type string `json:"type"`
	} `json:"rate_limit_reached_type"`
	RateLimitResetCredits *struct {
		AvailableCount int64 `json:"available_count"`
	} `json:"rate_limit_reset_credits"`
}

Response is the subset of /wham/usage this tool reads. Every nested value may be null or missing.

func (*Response) AvailableResets 

func (r *Response) AvailableResets() int64

AvailableResets is the number of usage limit resets the account can redeem.

type StatusError 

type StatusError struct {
	Action string
	Status int
	Body   string
}

StatusError is an unexpected HTTP status from the backend.

func (*StatusError) Error 

func (e *StatusError) Error() string

type Window 

type Window struct {
	UsedPercent        float64 `json:"used_percent"`
	LimitWindowSeconds int64   `json:"limit_window_seconds"`
	ResetAfterSeconds  int64   `json:"reset_after_seconds"`
	ResetAt            int64   `json:"reset_at"`
}

Window is one rate-limit window, e.g. the rolling 5 hours or the week.

func (*Window) Label 

func (w *Window) Label() string

Label names the window by its length: "5h", "weekly", "daily", or a duration.

func (*Window) LeftPercent 

func (w *Window) LeftPercent() float64

LeftPercent is the share of the window still available, clamped to 0–100.

func (*Window) ResetTime 

func (w *Window) ResetTime(now time.Time) time.Time

ResetTime is when the window resets.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.