Bohdan Triapitsyn
b46153801b
Adds Cursor as a supported quota provider Reads Cursor auth from env, token files, or local app data Improves Cursor usage labels in the UI
60 lines
4.3 KiB
Markdown
60 lines
4.3 KiB
Markdown
# 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/routes.js`: Express route registration for quota endpoints.
|
|
- `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` |
|
|
| `cursor` | Cursor | `providers/cursor.js` | `CURSOR_TOKEN` / `CURSOR_ACCESS_TOKEN`, `CURSOR_REFRESH_TOKEN`, optional token files, or Cursor desktop SQLite DB |
|
|
| `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` |
|
|
| `zhipuai-coding-plan` | Zhipu AI Coding Plan | `providers/zhipuai-coding-plan.js` | `zhipuai-coding-plan`, `zhipuai`, `zhipu` |
|
|
| `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) |
|
|
| `wafer` | Wafer.ai | `providers/wafer.js` | `wafer`, `wafer-ai`, `wafer_ai`, `wafer.ai` |
|
|
|
|
## 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.
|