Skip to content

feat: add balance top-up requests and admin credit API - #16774

Open
romy651 wants to merge 7 commits into
LibreChat-AI:devfrom
fdj-united:codex/balance-topup-requests-upstream
Open

romy651 wants to merge 7 commits into
LibreChat-AI:devfrom
fdj-united:codex/balance-topup-requests-upstream

Conversation

@romy651

@romy651 romy651 commented Oct 5, 2026 •

Copy link
Copy Markdown

Summary

When balance limits are enabled, users can exhaust their credits before the next automatic refill, but they currently have no built-in way to ask an administrator for help. Administrators also lack a capability-gated, audited, and retry-safe API for inspecting balances and applying a manual reset.

This PR adds a user balance top-up request flow in Settings and in the chat balance notice, exposes pending-request state through the balance API, and adds administrative endpoints for listing user balances and applying credits. Administrative credits are atomic and idempotent, request resolution is lease-protected, and successful operations are recorded in the audit log.

The existing general announcement banner is unchanged.

How it works

User submits request (Settings or chat balance notice)
  -> POST /api/balance/request
  -> one pending BalanceRequest per user
  -> admin lists balances/pending requests
  -> POST /api/admin/balance/:userId
  -> idempotent credit + audit entry + request resolution

The admin UI is provided by LibreChat-AI/admin-panel#149.

Type of change

  • Feature
  • Tests / tooling / CI

Testing

Tested environments/configuration:

  • MongoDB standalone and replica-set-backed test paths
  • Balance enabled with and without automatic refill
  • Production client build

Automated tests:

  • npm run build:packages
  • npm run build:client
  • TypeScript checks for client, API, data-provider, and data-schemas
  • Upstream-relative static checks, including ESLint, Prettier, import sorting, design rules, circular dependencies, config migrations, and unused i18n keys
  • 47 balance/admin API tests
  • 100 balance-request and transaction tests
  • 60 server-controller tests
  • 14 client balance-notice and request-dialog tests

Screenshots / recordings

State Light mode Dark mode
Running low Running-low credit notice above the chat input in light mode Running-low credit notice above the chat input in dark mode
Out of credits Out-of-credit notice above the chat input in light mode Out-of-credit notice above the chat input in dark mode

Checklist

  • I reviewed my own changes
  • Relevant tests have been added or updated
  • Existing relevant tests pass
  • The change does not introduce new warnings or errors
  • User-facing or complex behavior is documented where necessary
  • Required dependency changes have been merged/published
  • Required documentation PR: N/A

@codegraph-librechat codegraph-librechat Bot added 🗺️ Billing Engine codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🛡️ security review labels Oct 5, 2026
@romy651
romy651 marked this pull request as ready for review October 5, 2026 10:20
# Conflicts:
#	client/src/components/Nav/Settings/BillingControls.tsx
Romuald Wandji and others added 2 commits October 6, 2026 10:13
…requests-upstream

# Conflicts:
#	packages/api/src/index.ts
#	packages/data-provider/src/types.ts
#	packages/data-schemas/src/methods/transaction.ts
@codegraph-librechat codegraph-librechat Bot added the 🗺️ Identity & Billing codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) label Oct 9, 2026
@codegraph-librechat codegraph-librechat Bot added the 🗺️ DB Models & Ops codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) label Oct 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🗺️ Billing Engine codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🗺️ DB Models & Ops codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🗺️ Identity & Billing codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🛡️ security review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant