Documentation
¶
Index ¶
Constants ¶
const ( // GitHubBillingAPIVersion is the REST API version that introduced the current // Copilot AI credit billing usage endpoints. GitHubBillingAPIVersion = "2026-03-10" // SourceGitHubBillingAPI identifies reports loaded from GitHub's official // billing usage API, not from Copilot's legacy/internal entitlement endpoint. SourceGitHubBillingAPI = "github_billing_api" )
Variables ¶
var ErrNoGitHubToken = errors.New("missing GitHub token for Copilot AI credit usage")
ErrNoGitHubToken is returned when Copilot AI credit usage is requested without a GitHub REST token. Copilot's chat OAuth token is intentionally not used for billing reports because the official endpoints have their own permissions.
Functions ¶
func BillingTokenStatus ¶
func BillingTokenStatus() string
BillingTokenStatus returns a human-readable status for auth diagnostics.
func TokenFromEnv ¶
TokenFromEnv returns the first supported GitHub REST token and the environment variable it came from. GITHUB_TOKEN wins over GH_TOKEN for predictability.
Types ¶
type BillingAPIError ¶
BillingAPIError describes a non-success response from GitHub's billing API.
func (*BillingAPIError) Error ¶
func (e *BillingAPIError) Error() string
type TimePeriod ¶
type TimePeriod struct {
Year int `json:"year,omitempty"`
Month int `json:"month,omitempty"`
Day int `json:"day,omitempty"`
}
TimePeriod identifies the period GitHub summarized in the report.
type UsageClient ¶
type UsageClient struct {
// contains filtered or unexported fields
}
UsageClient fetches Copilot AI credit usage from GitHub's official billing API.
func NewUsageClient ¶
func NewUsageClient(token string, opts ...UsageClientOption) (*UsageClient, error)
NewUsageClient creates a latest Copilot AI credit usage client.
func NewUsageClientFromEnv ¶
func NewUsageClientFromEnv(opts ...UsageClientOption) (*UsageClient, error)
NewUsageClientFromEnv creates a usage client using GITHUB_TOKEN or GH_TOKEN. GITHUB_API_URL may be set to target GitHub Enterprise Cloud dedicated subdomains; explicit options override the environment base URL.
func (*UsageClient) CurrentUsername ¶
func (c *UsageClient) CurrentUsername(ctx context.Context) (string, error)
CurrentUsername returns the login for the authenticated GitHub token.
func (*UsageClient) GetAICreditUsage ¶
func (c *UsageClient) GetAICreditUsage(ctx context.Context, scope Scope, entity string, filters UsageFilters) (*UsageReport, error)
GetAICreditUsage returns the latest Copilot AI credit usage report for the requested billing scope. If scope is user and entity is empty, the authenticated user's login is discovered via GET /user.
type UsageClientOption ¶
type UsageClientOption func(*UsageClient)
UsageClientOption customizes a UsageClient.
func WithBaseURL ¶
func WithBaseURL(baseURL string) UsageClientOption
WithBaseURL overrides the GitHub API base URL. It is mainly used by tests and can also support GitHub Enterprise Cloud dedicated subdomains.
func WithHTTPClient ¶
func WithHTTPClient(httpClient *http.Client) UsageClientOption
WithHTTPClient overrides the HTTP client used for requests.
type UsageFilters ¶
type UsageFilters struct {
Year int
Month int
Day int
User string
Organization string
Model string
Product string
CostCenterID string
}
UsageFilters mirrors the query parameters supported by the latest GitHub Copilot AI credit usage endpoints. Callers should leave scope-unsupported filters empty; the client serializes only non-zero/non-empty filters.
type UsageItem ¶
type UsageItem struct {
Product string `json:"product,omitempty"`
SKU string `json:"sku,omitempty"`
Model string `json:"model,omitempty"`
UnitType string `json:"unitType,omitempty"`
PricePerUnit float64 `json:"pricePerUnit,omitempty"`
GrossQuantity float64 `json:"grossQuantity,omitempty"`
GrossAmountUSD float64 `json:"grossAmount,omitempty"`
DiscountQuantity float64 `json:"discountQuantity,omitempty"`
DiscountAmountUSD float64 `json:"discountAmount,omitempty"`
NetQuantity float64 `json:"netQuantity,omitempty"`
NetAmountUSD float64 `json:"netAmount,omitempty"`
}
UsageItem is one row from GitHub's AI credit usage report.
type UsageReport ¶
type UsageReport struct {
Scope Scope `json:"scope"`
Entity string `json:"entity"`
TimePeriod TimePeriod `json:"timePeriod"`
Items []UsageItem `json:"items"`
Totals UsageTotals `json:"totals"`
Source string `json:"source"`
Warnings []string `json:"warnings,omitempty"`
}
UsageReport is the normalized latest-only Copilot usage report used by the CLI.
type UsageTotals ¶
type UsageTotals struct {
GrossCredits float64 `json:"grossCredits"`
NetCredits float64 `json:"netCredits"`
GrossAmountUSD float64 `json:"grossAmountUSD"`
NetAmountUSD float64 `json:"netAmountUSD"`
DiscountAmountUSD float64 `json:"discountAmountUSD"`
}
UsageTotals aggregates all report items.
func CalculateTotals ¶
func CalculateTotals(items []UsageItem) UsageTotals
CalculateTotals sums usage report items.
Source Files