feat: implement generic circuit breaker pattern for external service calls

[menawar]

Summary

Closes #1002

This PR introduces a generic Circuit Breaker pattern to protect both the backend and frontend systems from cascading failures when calling external services or when the mobile app calls the backend API.

Changes

1. Generic Circuit Breaker Utility

Created a reusable CircuitBreaker class in both the backend and frontend environments:

• Backend: backend/services/shared/circuitBreaker.ts
• Frontend: src/services/network/circuitBreaker.ts

Features:

• State Machine: Closed -> Open -> Half-Open -> Closed.
• Configurable thresholds for consecutive failures, recovery timeouts, and success thresholds.
• Fast-failure mechanism with CircuitOpenError.
• Frontend Only: Emits telemetry events to mobileTracer during state transitions and fast-fails.

2. Integration with API Clients

Integrated the CircuitBreaker natively into our ApiClients:

• Backend (backend/services/shared/apiClient.ts):
  • Automatically trips the circuit on 5xx server errors or network errors.
  • Bypasses circuit tripping for expected 4xx client errors, preserving existing application logic perfectly.
• Frontend (src/services/network/apiClient.ts):
  • Automatically trips the circuit on 5xx server errors or network errors.
  • Ensures seamless degradation to the UI.

3. Unit Tests

Added comprehensive test suites for both environments:

• backend/services/shared/__tests__/circuitBreaker.test.ts
• src/services/network/__tests__/circuitBreaker.test.ts
• Coverage: >80% covering success paths, consecutive failures, state transitions, half-open failure relapses, manual resets, and tracer events.

Test Results

Tests:       11 passed, 11 total
Test Suites: 2 passed, 2 total

Acceptance Criteria

• Feature implemented with full functionality
• Unit tests added with >80% coverage
• Integration tests for critical paths (API Client integrations)
• No regression introduced
• Documentation updated (JSDoc included)

[drips-wave]

@menawar 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