task: normalize Soroban RPC errors to stable API codes for /api/billing/deduct

[icodeBisola]

Summary

Closes #319

Maps Soroban RPC failures in sorobanBilling.ts to stable error types so /api/billing/deduct always returns predictable HTTP status codes.

Changes

src/services/sorobanBilling.ts

• Added SorobanRpcErrorCategory type: INSUFFICIENT_BALANCE | TIMEOUT | CONTRACT_ERROR | NETWORK_ERROR
• Added SorobanRpcError class (extends Error) carrying a category field
• Added classifyError(message) helper that maps error message keywords to categories
• All throws inside invoke() now produce SorobanRpcError with the correct category (HTTP errors → NETWORK_ERROR, missing result → NETWORK_ERROR, simulation errors → classified by message, abort/timeout → TIMEOUT)

src/routes/billing.ts

• Imported SorobanRpcError, BadGatewayError, GatewayTimeoutError
• /deduct catch block maps SorobanRpcError categories:
  • INSUFFICIENT_BALANCE → PaymentRequiredError (402)
  • TIMEOUT → GatewayTimeoutError (504)
  • CONTRACT_ERROR / NETWORK_ERROR → BadGatewayError (502)
• result.success === false block also maps error message keywords to the same stable codes

src/services/sorobanBilling.test.ts

• Added 7 new tests covering all SorobanRpcError categories
• All 12 tests pass (5 original + 7 new)

Acceptance Criteria

Scenario	HTTP Status	Code
Insufficient balance	402	INSUFFICIENT_BALANCE
RPC timeout / abort	504	SOROBAN_RPC_TIMEOUT
Contract error	502	SOROBAN_RPC_ERROR
Network / HTTP error	502	SOROBAN_RPC_ERROR

Test Output

PASS src/services/sorobanBilling.test.ts
  buildSorobanBalanceInvocation
    ✓ assembles a balance invocation for a user id
  buildSorobanDeductInvocation
    ✓ assembles a deduct invocation with optional idempotency key
  SorobanRpcBillingClient
    ✓ posts a balance invocation and normalizes the returned balance
    ✓ posts a deduct invocation and returns the transaction hash
    ✓ normalizes simulation failures returned by Soroban RPC
  SorobanRpcError categories
    ✓ classifies insufficient balance as INSUFFICIENT_BALANCE
    ✓ classifies insufficient funds as INSUFFICIENT_BALANCE
    ✓ classifies contract error as CONTRACT_ERROR
    ✓ classifies simulation failed as CONTRACT_ERROR
    ✓ classifies HTTP failure as NETWORK_ERROR
    ✓ classifies timeout/abort as TIMEOUT
    ✓ missing result in RPC response is classified as NETWORK_ERROR

Tests: 12 passed, 12 total

[drips-wave]

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