janekbaraniewski/openusage/openusage-provider

OpenUsage Provider Skill

Invocation: When a user asks to add, create, or implement a new AI provider to OpenUsage.

You are implementing a new AI usage/quota provider for the OpenUsage TUI dashboard. This is a multi-step process. Follow every step precisely.

Phase 0 — Quiz the User (MANDATORY)

Before writing any code, you MUST gather all of the following information. Ask these questions conversationally but DO NOT proceed until every answer is obtained. If the user doesn't know an answer, research it yourself (check the provider's docs, API reference, etc).

Questions to ask:

1. Provider name & ID

• What is the human-readable name? (e.g. "OpenAI", "DeepSeek", "Gemini CLI")
• What should the snake_case provider ID be? (e.g. openai, deep_seek, gemini_cli)

1. Authentication method — which of these applies?

• api_key — user sets an env var like PROVIDER_API_KEY (most common for API providers)
• oauth — OAuth flow with stored credentials (e.g. Gemini CLI)
• cli — shells out to a CLI binary (e.g. GitHub Copilot via gh)
• local — reads local files/databases (e.g. Claude Code stats)
• token — extracted from local storage (e.g. Cursor IDE token from SQLite)

1. If API key auth: What is the env var name? (e.g. XAI_API_KEY)

1. Data source — how do we get usage data?

• HTTP API with rate-limit headers (probe a lightweight endpoint like /v1/models)
• Dedicated usage/balance REST endpoint (e.g. DeepSeek /user/balance)
• Local files (stats JSON, session files, SQLite databases)
• CLI subprocess output
• Combination of the above

1. What metrics are available? Try to identify:

• Rate limits: RPM, TPM, RPD, TPD (from headers or API)
• Spending: balance, credits, daily/weekly/monthly spend
• Usage: messages, tokens (input/output/reasoning), sessions, tool calls
• Account metadata: plan name, email, org, billing cycle

1. API documentation URL — link to the provider's rate-limit or usage docs

1. Base URL — the API base (e.g. https://api.openai.com/v1)

1. Probe model (if using header probing) — a cheap/default model to use for the probe request (e.g. gpt-4.1-mini)

1. Color role for the dashboard tile — pick one that doesn't conflict with existing providers:

• green (OpenAI), peach (Anthropic), lavender (Cursor), blue (Gemini CLI)
• sky (DeepSeek), teal (xAI), yellow (Groq), sapphire (Mistral)
• rosewater (OpenRouter), maroon (Copilot), flamingo (Codex), auto (Claude Code)

1. Does the provider support per-model usage breakdowns? (for the Analytics tab)

Phase 1 — Research

Before coding, look up the provider's API docs to understand:

• Exact HTTP endpoints, methods, headers
• Response JSON schemas
• Rate-limit header names and formats
• Any balance/credits/usage endpoints
• Authentication header format (Bearer, x-api-key, etc.)
• Error response codes and their meaning (401, 403, 429)

Document your findings in a brief summary before proceeding.

Phase 2 — Create the Provider Package

2.1 Directory structure

Create internal/providers/<provider_id>/ with these files:

internal/providers/<provider_id>/
├── <provider_id>.go       # Provider struct + Fetch() implementation
├── <provider_id>_test.go  # Tests
└── widget.go              # Dashboard widget configuration (only if customizing beyond defaults)

2.2 Provider implementation (<provider_id>.go)

The provider MUST:

1. Define a `Provider` struct that embeds providerbase.Base:

package <provider_id>
 
import (
    "context"
    "fmt"
    "net/http"
    "time"
 
    "github.com/janekbaraniewski/openusage/internal/core"
    "github.com/janekbaraniewski/openusage/internal/parsers"
    "github.com/janekbaraniewski/openusage/internal/providers/providerbase"
)
 
const (
    defaultBaseURL = "https://api.<provider>.com/v1"
)
 
type Provider struct {
    providerbase.Base
}

1. Implement a `New()` constructor that registers the ProviderSpec:

func New() *Provider {
    return &Provider{
        Base: providerbase.New(core.ProviderSpec{
            ID: "<provider_id>",
            Info: core.ProviderInfo{
                Name:         "<Provider Name>",
                Capabilities: []string{"headers"},
                DocURL:       "https://docs.<provider>.com/rate-limits",
            },
            Auth: core.ProviderAuthSpec{
                Type:             core.ProviderAuthTypeAPIKey,
                APIKeyEnv:        "<PROVIDER_API_KEY>",
                DefaultAccountID: "<provider_id>",
            },
            Setup: core.ProviderSetupSpec{
                Quickstart: []string{"Set <PROVIDER_API_KEY> to a valid API key."},
            },
            Dashboard: dashboardWidget(), // or providerbase.DefaultDashboard(providerbase.WithColorRole(core.DashboardColorRole<Color>))
        }),
    }
}

1. Implement the `Fetch()` method — this is the core data collection logic.

Key rules for Fetch():

• First param is context.Context — pass it to all HTTP requests via http.NewRequestWithContext
• Second param is core.AccountConfig — use acct.ResolveAPIKey() for API key, acct.BaseURL for custom base URL, acct.Binary for CLI path
• Return (core.UsageSnapshot, error)
• For auth failures: return a valid snapshot with Status: core.StatusAuth and err == nil
• For rate limiting: return snapshot with Status: core.StatusLimited and err == nil
• For fatal errors (network failure, bad request): return (core.UsageSnapshot{}, err)
• Always prefix error messages with provider name: fmt.Errorf("<provider_id>: creating request: %w", err)
• Initialize all maps: Metrics: make(map[string]core.Metric), Resets: make(map[string]time.Time), etc.

Pattern A: HTTP header probing (simplest — for providers that expose rate-limit headers)

func (p *Provider) Fetch(ctx context.Context, acct core.AccountConfig) (core.UsageSnapshot, error) {
    apiKey := acct.ResolveAPIKey()
    if apiKey == "" {
        return core.UsageSnapshot{
            ProviderID: p.ID(),
            AccountID:  acct.ID,
            Timestamp:  time.Now(),
            Status:     core.StatusAuth,
            Message:    "no API key found (set <ENV_VAR> or configure token)",
        }, nil
    }
 
    baseURL := acct.BaseURL
    if baseURL == "" {
        baseURL = defaultBaseURL
    }
 
    url := baseURL + "/models/<default_model>"
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return core.UsageSnapshot{}, fmt.Errorf("<provider_id>: creating request: %w", err)
    }
    req.Header.Set("Authorization", "Bearer "+apiKey)
 
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return core.UsageSnapshot{}, fmt.Errorf("<provider_id>: request failed: %w", err)
    }
    defer resp.Body.Close()
 
    snap := core.UsageSnapshot{
        ProviderID: p.ID(),
        AccountID:  acct.ID,
        Timestamp:  time.Now(),
        Metrics:    make(map[string]core.Metric),
        Resets:     make(map[string]time.Time),
        Raw:        parsers.RedactHeaders(resp.Header),
    }
 
    switch resp.StatusCode {
    case http.StatusUnauthorized, http.StatusForbidden:
        snap.Status = core.StatusAuth
        snap.Message = fmt.Sprintf("HTTP %d – check API key", resp.StatusCode)
        return snap, nil
    case http.StatusTooManyRequests:
        snap.Status = core.StatusLimited
        snap.Message = "rate limited (HTTP 429)"
    }
 
    parsers.ApplyRateLimitGroup(resp.Header, &snap, "rpm", "requests", "1m",
        "x-ratelimit-limit-requests", "x-ratelimit-remaining-requests", "x-ratelimit-reset-requests")
    parsers.ApplyRateLimitGroup(resp.Header, &snap, "tpm", "tokens", "1m",
        "x-ratelimit-limit-tokens", "x-ratelimit-remaining-tokens", "x-ratelimit-reset-tokens")
 
    if snap.Status == "" {
        snap.Status = core.StatusOK
        snap.Message = "OK"
    }
 
    return snap, nil
}

Pattern B: REST API + balance endpoint (like DeepSeek)

Split into helper methods: fetchBalance(), fetchRateLimits(), etc. Parse JSON responses into core.Metric entries. Use snap.SetAttribute("key", "value") for account metadata.

Pattern C: Local file readers (like Claude Code, Codex)

Read from known paths using acct.Binary or acct.ExtraData["config_dir"]. Parse JSON/SQLite data. Populate metrics from parsed data.

2.3 Metric keys — naming conventions

2.4 Attribute keys — naming conventions

Use snap.SetAttribute() for metadata displayed in the details panel:

2.5 ModelUsage records (for Analytics tab)

If the provider returns per-model breakdowns, populate snap.ModelUsage:

snap.ModelUsage = append(snap.ModelUsage, core.ModelUsageRecord{
    RawModelID:   "gpt-4o-2025-01-01",
    ProviderSlug: "<provider_id>",
    InputTokens:  1234,
    OutputTokens: 567,
    TotalCost:    0.0042,
    RequestCount: 15,
})

2.6 DailySeries (for Analytics charts)

If the provider has historical daily data, populate snap.DailySeries:

snap.DailySeries = map[string][]core.TimePoint{
    "cost": {
        {Date: "2025-01-15", Value: 1.23},
        {Date: "2025-01-16", Value: 2.34},
    },
}

Phase 3 — Dashboard Widget Configuration

3.1 When to use defaults vs custom widget

• Use defaults (via providerbase.DefaultDashboard(providerbase.WithColorRole(...))) for simple header-probing providers with just RPM/TPM.
• Create `widget.go` when the provider has rich metrics (credits, spending, activity, per-model data).

3.2 Custom widget (widget.go)

package <provider_id>
 
import "github.com/janekbaraniewski/openusage/internal/core"
 
func dashboardWidget() core.DashboardWidget {
    cfg := core.DefaultDashboardWidget()
 
    cfg.ColorRole = core.DashboardColorRole<Color>
 
    // Gauge priority — which metrics show as gauge bars in the tile (need Limit+Remaining or Limit+Used)
    cfg.GaugePriority = []string{
        "credit_balance", "spend_limit", "rpm", "tpm",
    }
    cfg.GaugeMaxLines = 2