[DRAFT][PLAN] AI Credits Widget: buy or stream developer AI credits with G$

[sirpy]

[DRAFT] [PLAN] AI Credits Widget: buy or stream developer AI credits with G$

This plan sub-issue drafts the execution strategy for AI Credits Widget: buy developer AI credits with G$, with the following additional requirement: user should also be able to stream G$s to buy credits.

Required states, flows, and behaviors

Expand the original required states to support G$ streaming for credits:

• All original states: disconnected, connected_empty, quote_ready, payment_pending, payment_confirmed, has_credits, usage_empty, usage_active, insufficient_g_balance, insufficient_ai_credits, payment_failed, backend_unavailable, unsupported_chain
• New/modified states:
  • streaming_setup: option to initiate streaming G$ if supported by the wallet or backend (wallet disconnected, connected, or after credits are spent)
  • streaming_active: user has enabled an active G$ streaming payment toward credits; display streaming status, running balance, option to pause/cancel
  • streaming_paused/streaming_stopped: stream is paused or ended; offer to restart or switch to one-time buy

Extended Flows

• Allow switching between one-time G$ buy and streaming G$ purchase modes.
• Streaming UX:
  1. Wallet connects.
  2. User selects between "Buy Once" or "Stream G$ for Credits".
  3. If streaming, configure stream amount/rate and confirm approval.
  4. Show running stream status card: credits accrue in near real-time, user can pause/stop.
  5. If stream is paused/stopped, maintain credits and offer to top-up or resume stream.
  6. API key, setup, usage, and error states match the one-time buy flow after credits are accrued.
• Preserve all original behaviors for wallet, balance quoting, payment confirmation, usage logs, API key/privacy management, error/degraded states, and Storybook scenarios.

Execution plan

1. Reference file mapping:

   • From GoodDollar/antseed-integration:
     • AGENTS.md (design/actor semantics)
     • README.md, docs/ARCHITECTURE.md, docs/PAYMENT_FLOW.md (API/payment boundaries)
     • backend/README.md, backend/src/types.ts, backend/src/pricing.ts (backend API structure, pricing, extensibility for streaming)
     • contracts/src/AgentCreditVault.sol, contracts/src/CeloGdAntSeedVault.sol (credit/token vault mechanics—assess G$ streaming feasibility)
   • From GoodDollar/GoodWidget:
     • Use packages/claim-widget as reference for package, project, theming, embed/host patterns
     • Use packages/ui for all primitives; extend if streaming-specific UI elements (progress, status bars, editable tickers) needed
     • Use packages/core, packages/embed as above
     • Storybook: implement new streaming states under packages/ai-credits-widget Storybook folder; update/add fixtures as needed
     • Playwright: Add streaming-specific tests under tests/widgets/ai-credits-widget/

2. Component mapping:

   • New, package-local components in @goodwidget/ai-credits-widget:
     • StreamingCreditSetupCard: stream/buy mode selector, controls for stream amount/rate, start/stop buttons
     • StreamingStatusCard: indicator/progress for streaming state, real-time estimated credits, pause/cancel
     • Extend state machine/context for streaming operation with fallback to one-time flows
   • Update/additions in packages/ui if reusable:
     • Possibly generic StreamingProgressBar, toggle controls, or confirmation dialogs if needed elsewhere

3. Supports both buy and stream:

   • Add UI affordance to toggle between the two
   • Fixture/mocked backend streaming endpoint
   • Clearly indicate streaming is beta/experimental if backend is not yet productionized

4. Acceptance Criteria:

   • All original ACs from MVP, with clear streaming capability (select, start, run/monitor, pause/stop, switch to buy)
   • Streaming-specific states, flows, and error handling covered in Storybook and Playwright
   • No settlement details or multi-chain complexity leaks into the UI

5. Human Reviewer Checklist:

   1. All reference files from antseed-integration and GoodWidget mapped/linked
   2. UI supports both G$ one-time buys and streaming, states switch cleanly
   3. All required states and behaviors implemented including streaming user flows
   4. Storybook and Playwright cover all streaming and original scenarios
   5. Code is modular, streaming logic isolated, UI/UX follows GoodWidget conventions
   6. Copy and error messages are clear about streaming status, fallback options
   7. No premature exposure of Antseed/USDC details to users

Parent: #30

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: This may be caused by a repository ruleset violation. See granting bypass permissions for the agent, or please contact support if the issue persists. (Request id: F6A9:281287:C866EC5:9EDB622:6A0C81E0)