feat(usage-limits): add Novita AI balance provider

[mynameistito]

Summary

• Add a Novita AI balance provider using the documented billing endpoint and the shared balance quota model.
• Convert Novita's 1/10,000 USD values safely and keep auto-discovered credentials scoped to the official API origin.
• Cover provider wiring, config/schema, tests, package docs, and the docs site.

Closes #172

Verification

• bun run test (463 usage-limits tests passed)
• bun run typecheck
• bun run check
• bun run build
• bun run test:package
• bun run knip

The docs check/build emitted a non-blocking warning because GITHUB_TOKEN is not set for the live GitHub releases content source.

---

Summary by cubic

Adds Novita AI as a supported balance provider in the usage-limits plugin, displaying the current available USD balance from Novita's official billing endpoint. Closes #172.

• Converts Novita's 1/10,000 USD monetary values safely and rejects malformed amounts such as negatives, fractions, or unsafe integers.
• Auto-discovered OpenCode credentials are only sent to https://api.novita.ai; a custom baseUrl requires an explicit authPath or apiKey.
• Adds config/schema, package README, docs site pages, examples, and tests; classifies the addition as a minor package change and a patch for the docs site.

^{Written for commit 0fc6b5b. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 0fc6b5b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@mynameistito/opencode-usage-limits	Minor
@mynameistito/opencode-plugins-docs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (2)

AGENTS.md — auto-discovered
packages/opencode-usage-limits/AGENTS.md — auto-discovered

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d5c5f30a-7bbb-4edb-b304-0623ff132e22

📥 Commits

Reviewing files that changed from the base of the PR and between 4489c85 and 0fc6b5b.

📒 Files selected for processing (19)

• .changeset/646af05b.md
• .changeset/b908f8ed.md
• README.md
• apps/web/docs/index.mdx
• apps/web/docs/usage-limits.mdx
• packages/opencode-usage-limits/README.md
• packages/opencode-usage-limits/__tests__/config.test.ts
• packages/opencode-usage-limits/__tests__/providers/index.test.ts
• packages/opencode-usage-limits/__tests__/providers/novita-ai.test.ts
• packages/opencode-usage-limits/examples/usage-limits.jsonc
• packages/opencode-usage-limits/package.json
• packages/opencode-usage-limits/src/config-schema.ts
• packages/opencode-usage-limits/src/config.ts
• packages/opencode-usage-limits/src/errors-shared.ts
• packages/opencode-usage-limits/src/errors/response-decode.ts
• packages/opencode-usage-limits/src/providers/index.ts
• packages/opencode-usage-limits/src/providers/novita-ai.ts
• packages/opencode-usage-limits/src/types.ts
• packages/opencode-usage-limits/usage-limits.schema.json

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added Novita AI as a supported provider. Its available USD balance can be shown in the sidebar and prompt footer.
  • Added configuration options for Novita AI credentials and API base URL.

• Documentation

  • Updated provider lists and setup guidance, including credential and custom base URL restrictions.
  • Clarified the distinction between Alibaba Token Plan and Qwen.

Walkthrough

The usage-limits plugin adds a Novita AI provider that fetches availableBalance and displays it as remaining USD. The changes add credential and configuration support, provider registration, tests, examples, documentation, and release changesets.

Changes

Novita AI balance provider

Layer / File(s)	Summary
Provider identity and configuration packages/opencode-usage-limits/src/types.ts, packages/opencode-usage-limits/src/config-schema.ts, packages/opencode-usage-limits/src/config.ts, packages/opencode-usage-limits/src/errors-shared.ts, packages/opencode-usage-limits/src/errors/response-decode.ts, packages/opencode-usage-limits/usage-limits.schema.json, packages/opencode-usage-limits/__tests__/config.test.ts, packages/opencode-usage-limits/examples/usage-limits.jsonc	Adds Novita AI provider types, configuration and published schemas, auth parsing, and error labels. The ProviderID union also adds commandcode. The example config adds a disabled Novita AI provider.
Balance retrieval and provider registration packages/opencode-usage-limits/src/providers/novita-ai.ts, packages/opencode-usage-limits/src/providers/index.ts, packages/opencode-usage-limits/__tests__/providers/novita-ai.test.ts, packages/opencode-usage-limits/__tests__/providers/index.test.ts	Registers the provider and requests the billing balance with bearer authentication. It converts digit-only availableBalance values from ten-thousandths of a dollar to USD, selects credentials according to origin, and reports credential, response-decode, and transport errors. Tests cover balance parsing, credentials, HTTP errors, and provider mapping.
Provider documentation and release notes README.md, apps/web/docs/index.mdx, apps/web/docs/usage-limits.mdx, packages/opencode-usage-limits/README.md, packages/opencode-usage-limits/package.json, .changeset/*	Adds Novita AI to provider lists and documents balance display, conversion, credential sources, and custom-origin restrictions. Adds package metadata and changesets. The website overview also separates Alibaba Token Plan from Qwen.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant UsageLimits
  participant NovitaAiProvider
  participant NovitaAPI
  UsageLimits->>NovitaAiProvider: Provide settings and available credentials
  NovitaAiProvider->>NovitaAPI: Request billing balance with bearer token
  NovitaAPI-->>NovitaAiProvider: Return availableBalance
  NovitaAiProvider->>NovitaAiProvider: Convert balance to USD
  NovitaAiProvider-->>UsageLimits: Return timestamped USD credits window

Loading

Merge Risk: ⚪ Minimal · up to 0fc6b

No identified issue blocks merging the Novita AI balance provider after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 0fc6b

Automatically discovered credentials remain restricted to Novita’s official origin, and custom destinations require explicit credential configuration. No introduced security flaw was established, but custom credential-file authority and runtime redirect behavior warrant a bounded assessment.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The new exchange exposes the selected API credential to its authorized destination and retrieves account balance data. It operates with the existing process’s filesystem and environment authority; credential exposure would be bounded by the selected key’s actual permissions, which were not supplied.

Trust Boundaries and Controls

• observed — Changing baseUrl alone cannot forward automatically discovered OpenCode credentials to a custom origin. The custom-origin branch requires a configured credential or explicit authPath; missing credentials fail before the network request. Source tests encode both rejection and explicit-key behavior.
• observed — The production configuration loader reads the existing user-level XDG configuration path. Explicit authPath takes precedence and may supply credentials to a custom origin; the shared reader imposes a size bound but no directory allowlist or credential-origin binding. This is a documented override responsibility, not an established lower-trust bypass.

Resilience and Maintainability Implications

• observed — The new caller inherits the unchanged HTTP transport’s two-megabyte response bound, timeout and interruption handling, and typed failures that omit raw error bodies and credentials.

Hardening Proposals

• proposed — Consider making redirect policy explicit for authenticated balance requests, or verifying cross-origin Authorization stripping with the supported production runtime. This would make the origin guarantee less dependent on implicit Fetch behavior; it is hardening, not a verified leak.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a Novita AI balance provider.
Description check	✅ Passed	The description explains the change, references the related issue, and lists validation commands and results. It does not state the tested OpenCode V2 CLI or plugin versions, and it omits the template…
Linked Issues check	✅ Passed	Issue #172 requirements are implemented. The provider fetches Novita’s billing endpoint through the Effect runtime and returns availableBalance as a USD Balance quota with no total, percentage, or…
Out of Scope Changes check	✅ Passed	The changes support Issue #172. They add the Novita provider and its tests, configuration, runtime wiring, package and site documentation, example configuration, and release changesets. The overview a…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the balance bright,
Ten-thousandths turn to dollars right.
A token travels, scoped with care,
The Novita total waits out there.
Tests keep zero safe in sight,
Then hop through docs into the night.}

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Deploying with Alchemy

The latest deployment for this pull request.

Status	Name	Latest commit	Updated (UTC)
Deployment successful View Cloudflare logs	opencode-plugins-docs-pr-183	0fc6b5bc	2026-10-05T04:56:28.707Z

Diagnostics: View GitHub Actions run

[cubic-dev-ai]

All reported issues were addressed across 19 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>