feat: implement circuit breaker pattern for external payment provider calls

[olaleyeolajide81-sketch]

Summary

Closes #293

This PR implements a circuit breaker pattern for all external payment provider calls in �ackend/src/services/payment-service.ts and �ackend/src/services/multiProviderPaymentService.ts, improving system resilience against provider outages and repeated failures.

---

Problem

External payment provider calls had no protection against cascading failures. A provider outage or repeated errors would cause every request to hit the failing service and return errors with no fast-fail mechanism.

Solution

A lightweight, zero-dependency CircuitBreaker class was added and integrated at the call sites for both payment services.

---

Changes

New file: �ackend/src/utils/circuitBreaker.ts

• CircuitBreaker class with three states: CLOSED (normal), OPEN (failing fast), HALF_OPEN (recovery probe)
• Configurable ailureThreshold (default 5) and
  ecoveryTimeMs (default 60 s)
• CircuitOpenError typed error thrown when circuit is OPEN — callers get a clear signal and never hit the provider

eset() method for admin/maintenance use

• Pure TypeScript, no extra dependencies

Modified: �ackend/src/payment-service.ts

• Import and instantiate CircuitBreaker in PaymentService
• executePayment is now wrapped in circuitBreaker.execute()
• On CircuitOpenError, a structured failure response is returned immediately without hitting the Stellar provider
• Added input validation (�alidatePaymentRequest) for meter_id, �mount, and userId — missing in the original and required by existing tests
• getCircuitBreakerState() accessor added for observability

Modified: �ackend/src/services/multiProviderPaymentService.ts

• One independent CircuitBreaker per provider stored in providerCircuitBreakers: Map<string, CircuitBreaker>
• Circuit breakers are initialized alongside rate limiters for all active providers
• Lazy creation: providers added after construction get a breaker on first use
• executeProviderPayment wrapped in the per-provider circuit breaker
• CircuitOpenError returns a structured failure response that identifies the blocked circuit
• getProviderCircuitBreakerState(providerId) added for observability

New file: �ackend/src/test/circuit-breaker.test.ts

• 17 unit tests covering all state transitions
• CLOSED initial state, failure counting, threshold enforcement
• OPEN fast-fail (fn not called), CircuitOpenError type and circuit name
• HALF_OPEN transition, probe success → CLOSED, probe failure → OPEN re-open
• Manual reset, custom threshold, custom recovery time, error re-throw

---

Acceptance Criteria

Criterion	Status
Circuit breaker added for external payment provider calls	✅
Configurable failure thresholds and recovery time	✅
Returns appropriate errors when circuit is open	✅
All existing tests pass	✅ (no existing logic removed; validation added to satisfy existing test expectations)
Per-provider isolation in MultiProviderPaymentService	✅

---

Testing

The CI workflow (.github/workflows/test.yml) runs the Rust contract tests. The Node.js backend tests (Jest) are in �ackend/ and cover all new and modified code.

New test file: �ackend/src/test/circuit-breaker.test.ts

• 17 tests, all passing locally with �un test / jest --testPathPattern circuit-breaker

Existing test suites unaffected:

• payment-service.test.ts — validation now done in service (satisfies existing test expectations)
• multiProvider.test.ts — all existing scenarios unchanged
• server.integration.test.ts — no route changes