product-sourcing-capture/docs/superpowers/plans/2026-06-14-ai-engine-and-token-billing.md

AI Engine And Token Billing Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add administrator-managed large-model configuration, user-facing AI analysis actions, and AI token billing through redemption codes.

Architecture: Extend the existing JSON store with aiSettings, aiTokens, and aiTokenLogs. Add an OpenAI-compatible AI client abstraction so official providers and proxy/base-url providers all use one request path. Admins configure model access; users consume AI actions through server endpoints that estimate/charge AI tokens.

Tech Stack: Node.js HTTP server, JSON store, OpenAI-compatible chat completions over fetch, vanilla HTML/CSS/JS frontend, Node test runner.

---

Task 1: Server Tests

Files:

• Modify: tests/server.test.js

• Add tests for admin-only AI settings.

• Add tests for AI token redemption codes.

• Add tests for AI analysis using a fake AI client and token deduction.

• Add tests for insufficient AI tokens.

Task 2: AI Core Module

Files:

• Create: src/ai.js

• Add DEFAULT_AI_SETTINGS.

• Add settings normalization and public masking.

• Add OpenAI-compatible request handling.

• Add prompt builders for item analysis, procurement reports, and rule generation.

• Add token estimation helpers.

Task 3: Store Extensions

Files:

• Modify: src/store.js

• Modify: src/auth.js

• Add aiTokens to users and public users.

• Extend credit codes to include aiTokens.

• Add aiSettings and encrypted API key storage.

• Add AI token deduction logs.

Task 4: API Routes

Files:

• Modify: src/server.js

• Add admin routes for AI settings and connection testing.

• Add user route /api/ai/analyze.

• Require AI token balance before calling the model.

• Deduct AI tokens after successful model use.

Task 5: Frontend UI

Files:

• Modify: public/index.html

• Modify: public/app.js

• Modify: public/styles.css

• Add admin AI configuration panel in management center.

• Extend redemption code UI with AI token amount.

• Show AI token balance on account/admin user rows.

• Add AI analysis actions in item detail.

• Keep visual language aligned with jade/paper/brass product UI.

Task 6: Verification

• Run npm test.
• Run JS syntax checks.
• Restart local service.
• Verify AI settings UI and item detail AI action with browser screenshots.