fix(backend): resolve EscrowService, RateLimitGuard, and EscrowAnalytics issues (#742, #743, #744, #748)

[Prudentdev-xyz]

Summary

This pull request resolves compilation errors and runtime issues across EscrowService, RateLimitGuard, and EscrowAnalyticsService:

1. EscrowService missing helpers and metrics (EscrowService calls private helper methods and constants that don't exist, so the file fails to compile #743)

   • Added missing AuditService import.
   • Exported constants ESCROWS_INDEX_KEY, ESCROW_PERSISTENCE_FALLBACK_METRIC, and ESCROW_TRANSACTION_INCONSISTENT_METRIC.
   • Defined key builder methods (escrowKey, depositorKey, contractKey) and implemented fetchMany with Redis MGET and JSON parsing.
   • Implemented logFallback and rethrowIfInconsistent with proper metric increments and transaction integrity checks.

2. ioredis type augmentation for custom rateLimitCheck command (Missing ioredis type augmentation for the custom rateLimitCheck Lua command #744)

   • Added ambient type definitions extending Redis and ChainableCommander interfaces in ioredis to declare rateLimitCheck.

3. RateLimitGuard advertised headers calculation (RateLimitGuard.setRateLimitHeaders is called with the tier config object instead of the pipeline decisions, so advertised rate-limit headers are always wrong #742)

   • Fixed canActivate() to pass real pipeline decisions along with tierConfig to setRateLimitHeaders().
   • Updated Lua script to return remaining bucket tokens on successful checks.
   • Enhanced setRateLimitHeaders() to select the tighter (lower-remaining) decision across multiple identities (e.g., IP and wallet) to protect clients from exhaustion.
   • Added unit tests verifying RateLimit-Remaining and RateLimit-Reset reflect bucket state and decrease across consecutive calls.

4. EscrowAnalyticsService invalid fallback shape (EscrowAnalyticsService crashes on a non-existent item.s.* fallback shape when escrowService is unavailable #748)

   • Removed dead item.s.* fallback property access in getPaginatedEscrowAnalytics().
   • Replaced with safe nullish coalescing defaults (item?.amountXLM ?? '0', item?.createdAt ?? new Date().toISOString()).
   • Added a unit test covering the standalone branch where Redis is available but escrowService is not injected.

Related Issues

• Closes RateLimitGuard.setRateLimitHeaders is called with the tier config object instead of the pipeline decisions, so advertised rate-limit headers are always wrong #742
• Closes EscrowService calls private helper methods and constants that don't exist, so the file fails to compile #743
• Closes Missing ioredis type augmentation for the custom rateLimitCheck Lua command #744
• Closes EscrowAnalyticsService crashes on a non-existent item.s.* fallback shape when escrowService is unavailable #748

[drips-wave]

@Prudentdev-xyz 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