feat: USDC credit purchasing — stub + demo

[mmurrs]

What this is

A stub demonstrating the proposed USDC credit purchasing flow in the ecloud CLI. Not a final implementation — makes the proposed UX concrete so the team can evaluate it. The billing API backend for USDC credit purchases already exists (PR #22 on ecloud-billing-api).

Problem

ecloud billing only routes through Stripe checkout (credit card). Developers who want to purchase credits with USDC have no CLI path — they'd need to know the contract address independently.

What changed

Command	Change	What it does
ecloud billing top-up	New	Executes USDCCredits.purchaseCreditsFor(amount, account) on-chain. Prompts for USDC amount → approves USDC spend → calls purchaseCreditsFor → polls billing API for credit confirmation. Stubbed until contract address is deployed.
ecloud billing subscribe	Modified	Prompts "Credit card or Purchase credits with USDC?" before Stripe checkout. CC path unchanged. USDC delegates to top-up.
ecloud billing status	Modified	Adds "Need more credits? Run ecloud billing top-up" when credits < $10 or subscription inactive.
ecloud billing cancel	Unchanged	—

How top-up works

1. Show current credit balance (from billing API)
2. Read wallet USDC balance on Base
3. If no USDC → "Send USDC to <wallet> on Base, then re-run"
4. Prompt: "How much USDC to spend on credits?"
5. USDC.approve(USDCCredits, amount)
6. USDCCredits.purchaseCreditsFor(amount, account)
7. Wait for tx confirmation
8. Poll billing API until credits appear

The user's wallet is already loaded (private key is a prerequisite for all billing commands), so the CLI forms and submits the transaction directly.

Demo

npx tsx demo/billing-flow.ts

What's stubbed

• Contract address — placeholder (0x...) until PR chore: update dev billing API server URL to use HTTPS domain #22's USDCCredits contract is deployed on Base
• Base RPC client — needs a public client for Base to read USDC balance and submit txs
• CC top-up — future second payment method within the same top-up command

No billing API changes. No new dependencies (viem already in the project).

Related

• ecloud-billing-api PR chore: update dev billing API server URL to use HTTPS domain #22 (USDC → Stripe credits backend)
• Eng sync (Mar 6) — Cavan proposed top-up as the fourth billing command; Sean confirmed the contract call is purchaseCreditsFor