NEXUS Credits

Technical summary

Core NEXUS plugin that manages the platform's credits and resource consumption — tracks AI usage, fires a single alert when the configurable limit (default 90%) is reached and keeps a full transaction history, with a billing modal, bonus/plan pools and the /credits chat command.

Executed scope

• plugin.json: v1.0.0, slug nexus-credits, "Core" category, is_core: true.
• No own tab (no tab.php): registerDoc "Sistema de Créditos" (credit-card icon) + registerModal("credits") + 4 API actions + Fastr.
• State — JSON in admin_configs (cfg_key = 'credits_state'): total (550), used, bonus_total (500), bonus_used (409), plan_total (50), plan_used, warn_sent; history in credits_history (id INT PK AI, amount DECIMAL, reason TEXT, created_at DATETIME).
• credits_read() — defaults + saved-state merge + last 50 transactions (amount, reason, created_at as at).
• credits_write() — strips history from the state and persists the JSON with INSERT ... ON DUPLICATE KEY UPDATE.
• credits_add($amount, $reason) — adds to used, records the transaction, computes pct = used/total*100 and, when pct >= credits.warn_pct (default 90%, via setting()) with warn_sent false, calls notify_credit_warning() and marks warn_sent = true — the alert fires only once per cycle.
• credits_set_total() — resets the limit and clears the alert flag.
• credits_reset() — deletes the state, TRUNCATE credits_history and restarts with the defaults (CREDIT_TOTAL, used 0, warn_sent false).
• credits_pct() — min(100, used/total*100).
• API: 4 actions — credits (read), credits_add (float amount + reason), ia_credits ({ ia_credits: read } for the AIs) and ia_credits_legacy (compat).
• Modal modals/credits.php (118 lines, PHP server-rendered, slate + indigo/violet theme) — "System Billing / Resource Consumption"; Bonus Resource Pool card (indigo-600 → violet-600 gradient bar with glow; "Cycle expires in 29 days") and Base Tier Credits card (slate-200 bar, emerald-600 values); conditional Distributed Node Telemetry per-AI breakdown (emoji, author, last_updated, Bonus indigo-500/40 + Base emerald-500/40 bars — renders only when $ia_credits['ias'] is populated externally); Credential Management admin panel (bg-indigo-50) with credits_set form (Total Allocated Credits $, step 0.01, UPDATE POOL button indigo-600) and credits_reset form (TERMINATE CYCLE & RESET COUNTER).
• Fastr — /credits (arg_required: false) — shows balance and history.
• Empty cron (jobs: [], on-demand); no migrations; no i18n (modal UI in English).

Stack and tools

• PHP 8 (no framework)
• MySQL 8 (admin_configs + credits_history)
• Tailwind CSS + Alpine.js (premium light, slate/indigo/violet)
• NEXUS plugin system (PluginManager: docs, modals, API actions, Fastr)

Operational tags

• Credits
• Créditos
• Billing
• Consumo de Recursos
• IA
• Core Plugin
• Plugin NEXUS

Operational result

• Central consumption control: credit state in a single JSON with full MySQL history.
• Automatic 90% alert: notification fired once per cycle (no spam) when usage crosses the configurable threshold.
• Two independent pools: bonus (bonus_total/bonus_used) and plan (plan_total/plan_used) with progress bars in the modal.
• AI compatibility: ia_credits and ia_credits_legacy actions expose the balance to assistant consumption.
• Admin control: reset the allocated limit and restart the cycle in 1 click (UPDATE POOL / TERMINATE CYCLE & RESET COUNTER).
• Quick access: /credits chat command shows balance and history without opening the panel.