feat(payments): build payment method management with fallback chains

[retkatmun]

Summary

Closes #951

Implements production-ready payment method management with ordered fallback chains for SubTrackr, as specified in issue #951.

---

What changed

New files

File	Description
src/services/paymentMethodService.ts	Core service: CRUD, chain validation, expiry, analytics, sharing
src/services/PaymentMethodManager.ts	Circuit breaker + health scoring (0-100) + rate limiting
src/services/FallbackChainEngine.ts	6 pluggable strategies: priority, weighted, sticky, priority-burst, geo-aware, round-robin
src/types/paymentMethod.ts	Re-exports + UI-layer types
src/components/payment/PaymentMethodManager.tsx	Full-screen UI (4 tabs: Methods / Chains / Analytics / Alerts)
src/services/__tests__/paymentMethodService.test.ts	Unit tests — all public service methods
src/store/__tests__/walletStore.test.ts	Unit tests — all store actions
src/services/__tests__/paymentFallbackChain.integration.test.ts	11 integration tests — critical fallback paths
docs/payment-method-management.md	Architecture, API reference, error codes

Modified files

File	Change
src/services/walletService.ts	Remove duplicate PaymentMethodService class; re-export from paymentMethodService.ts
src/store/walletStore.ts	Consolidate imports; add full payment method + chain + expiry + analytics + sharing actions

---

Features

Payment method CRUD

• Add / edit / remove / verify methods (max 10 per user)
• Duplicate detection by token + chainId
• Priority tiers: primary → backup → fallback
• Per-method spend cap (maxSpendPerInterval)

Fallback chains

• Named, ordered list of payment methods tried per charge
• stopOnHardDecline — halt on expired/deactivated method
• maxAttempts — cap on methods tried per charge
• Subscription-scoped or global chains
• buildDefaultChain — auto-generated from priority order

Circuit breaker (PaymentMethodManager)

• Opens after 3 consecutive failures; half-open probe after 60 s
• Health score 0-100 per method based on recent success rate
• Rate limiting: max 10 attempts per method per 60 s window

Fallback strategies (FallbackChainEngine)

• priority — Primary → Backup → Fallback, then LRU (default)
• weighted — probabilistic by success rate
• sticky — prefer last-successful method per subscription
• priority-burst — all primaries first, then backups, then fallbacks
• geo-aware — same-chainId methods before cross-chain
• round-robin — distribute evenly across primaries by LRU

Expiry management

• Alert severities: warning (≤30 d), critical (≤7 d), expired
• inActiveChain flag when expired method still in a live chain
• Bulk deactivateExpiredMethods() action

Payment method sharing

• viewer / charger roles; optional spendLimit and expiresAt
• Revocation with revokedAt timestamp

Analytics

• Per-method: attempts, successes, failures, success rate, volume, top failure reason
• Global: fallback rate (fraction of successes that needed a fallback), most reliable method

UI — PaymentMethodManager.tsx

• 4-tab full-screen component: Methods | Chains | Analytics | Alerts
• Alert badge on Alerts tab
• Fully accessible: accessibilityRole, accessibilityLabel, accessibilityState

---

Testing

• Unit (paymentMethodService.test.ts): 40+ tests covering every public method
• Unit (walletStore.test.ts): 35+ tests covering every store action
• Integration (paymentFallbackChain.integration.test.ts): 11 suites
  • Sequential fallback (first fails, second succeeds)
  • Full chain exhaustion
  • stopOnHardDecline — chain halts on expired method
  • maxAttempts cap
  • Gas price spike blocks entire chain
  • Sticky strategy prefers last-success method
  • Geo-aware strategy prefers matching chainId
  • Circuit breaker opens after threshold
  • Default chain generation
  • Validate → process round-trip
  • Analytics after mixed attempt run

---

Acceptance criteria

• Feature implemented with full functionality
• Unit tests added with >80% coverage of new code
• Integration tests for critical paths
• No regression introduced (only removed duplicate code from walletService.ts)
• Documentation updated (docs/payment-method-management.md)
• Performance: service methods are synchronous or use existing ethers RPC calls; no new blocking operations introduced

[drips-wave]

@retkatmun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits