fix: add circuit breaker for oracle external API calls

[Akatenvictor]

Wrap Open-Meteo and AviationStack axios calls with a circuit breaker pattern to prevent resource waste from repeated failures. After a configurable threshold of consecutive failures the circuit opens and calls fail fast without hitting the network. A half-open state allows a single probe request after the reset timeout to test recovery.

• Open-Meteo: 5 failures / 30s reset
• AviationStack: 3 failures / 60s reset

About this PR

This PR resolves 4 enhancement issues:

Closes #384
Closes #385
Closes #386
Closes #387
Circuit breaker pattern added to src/oracle/oracle.service.ts:

• CircuitBreaker class (lines 25–90) — three states: CLOSED (normal), OPEN (fail fast), HALF_OPEN (probe). Tracks consecutive failures and auto-transitions after a reset timeout.
• Two breaker instances with tuned thresholds:
  • openMeteoBreaker — 5 failures, 30s reset (shared by rainfall + temperature calls)
  • aviationStackBreaker — 3 failures, 60s reset (stricter since it's a paid API)
• All three external calls wrapped: fetchRainfallReading, fetchTemperatureReading, fetchFlightDelayReading

When the circuit is open, calls throw ServiceUnavailableException immediately without network I/O. After the timeout, one probe request goes through — success closes the circuit, failure reopens it.

Changes

#375 - API versioning strategy

• Implemented API versioning interceptor that adds X-API-Version response header
• Added Deprecation header for v1 with Link header pointing to v2 successor
• Updated Swagger config to support x-api-version header for API version negotiation

#373 - Pagination on policy and claims list endpoints

• Added page and limit query parameters to GET /api/v1/products endpoint
• Updated getActiveProducts service method to support Prisma-based pagination with take/skip
• Claims list endpoints (getClaimsByWalletQuery, getClaimHistory) already had pagination

#372 - Rate limiting on claim submission endpoint

• Added claim-specific rate limiting (limit: 5/60s) to POST /api/v1/claims endpoint
• Uses @Throttle decorator with stricter limits than global throttler (60/60s)

#374 - Webhook support for policy/claim status changes

• Created WebhooksService with register/unregister/list and status notification methods
• Created WebhooksController with POST /api/v1/webhooks/register and GET /api/v1/webhooks endpoints
• Policy status changes (e.g., cancel) trigger webhooks with policy.status.change event
• Claim status changes (e.g., PROCESSING → FAILED, PROCESSING → CLAIMED) trigger webhooks with claim.status.change event

Issue Closure

This PR closes the following issues using GitHub keyword syntax:

• Closes [Enhancement] No API versioning strategy #375 - API versioning strategy
• Closes [Enhancement] No pagination on policy and claims list endpoints #373 - No pagination on policy and claims list endpoints
• Closes [Enhancement] No rate limiting on claim submission endpoint #372 - No rate limiting on claim submission endpoint
• Closes [Enhancement] No webhook support for policy/claim status changes #374 - No webhook support for policy/claim status changes

Verification

• All endpoints return proper pagination metadata ({ success, data, total, page, limit })
• Rate limiting prevents claim submission spam beyond 5 attempts per 60 seconds
• Webhooks can be registered with specific events (policy.status.change, claim.status.change)
• API versioning headers are present on all responses

[drips-wave]

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