XCOpenCodeWeb/web/server/lib/quota/DOCUMENTATION.md

Quota Module Documentation

Purpose

This module fetches quota and usage signals for supported providers in the web server runtime.

Entrypoints and structure

• packages/web/server/lib/quota/index.js: public entrypoint imported by packages/web/server/index.js.
• packages/web/server/lib/quota/providers/index.js: provider registry, configured-provider list, and provider dispatcher.
• packages/web/server/lib/quota/providers/interface.js: JSDoc provider contract used as implementation reference.
• packages/web/server/lib/quota/providers/google/: Google-specific auth, API, and transform modules.
• packages/web/server/lib/quota/utils/: shared auth, transform, and formatting helpers.

Supported provider IDs (dispatcher)

These provider IDs are currently dispatchable via fetchQuotaForProvider(providerId) in packages/web/server/lib/quota/providers/index.js.

Provider ID	Display name	Module	Auth aliases/keys
claude	Claude	providers/claude.js	anthropic, claude
codex	Codex	providers/codex.js	openai, codex, chatgpt
google	Google	providers/google/index.js	google, google.oauth, Antigravity accounts file
github-copilot	GitHub Copilot	providers/copilot.js	github-copilot, copilot
github-copilot-addon	GitHub Copilot Add-on	providers/copilot.js	github-copilot, copilot
kimi-for-coding	Kimi for Coding	providers/kimi.js	kimi-for-coding, kimi
nano-gpt	NanoGPT	providers/nanogpt.js	nano-gpt, nanogpt, nano_gpt
openrouter	OpenRouter	providers/openrouter.js	openrouter
zai-coding-plan	z.ai	providers/zai.js	zai-coding-plan, zai, z.ai
minimax-coding-plan	MiniMax Coding Plan (minimax.io)	providers/minimax-coding-plan.js	minimax-coding-plan
minimax-cn-coding-plan	MiniMax Coding Plan (minimaxi.com)	providers/minimax-cn-coding-plan.js	minimax-cn-coding-plan
ollama-cloud	Ollama Cloud	providers/ollama-cloud.js	Cookie file at ~/.config/ollama-quota/cookie (raw session cookie string)

Internal-only provider module

• providers/openai.js exists for logic parity/reuse but is intentionally not registered for dispatcher ID routing.

Response contract

All providers should return results via shared helpers to preserve API shape:

• Required fields: providerId, providerName, ok, configured, usage, fetchedAt
• Optional field: error
• Unsupported provider requests should return ok: false, configured: false, error: Unsupported provider

Add a new provider (quick steps)

1. Choose module shape based on complexity:
   • Simple providers: create packages/web/server/lib/quota/providers/<provider>.js.
   • Complex providers (multi-source auth, multiple API calls, non-trivial transforms): create packages/web/server/lib/quota/providers/<provider>/ with split modules like Google (index.js, auth.js, api.js, transforms.js).
2. Export providerId, providerName, aliases, isConfigured, and fetchQuota.
3. Use shared helpers from packages/web/server/lib/quota/utils/index.js (buildResult, toUsageWindow, auth/conversion helpers) to keep payload shape consistent.
4. Register the provider in packages/web/server/lib/quota/providers/index.js.
5. If needed for direct use, export a named fetcher from packages/web/server/lib/quota/providers/index.js and packages/web/server/lib/quota/index.js.
6. Update this file with the new provider ID, module path, and alias/auth details.
7. Validate with bun run type-check, bun run lint, and bun run build.

Notes for contributors

• Keep provider IDs stable; clients use them directly.
• Avoid adding alias-based dispatch in fetchQuotaForProvider; dispatch currently expects exact provider IDs.
• Keep Google behavior changes isolated and review providers/google/* together.