feat(api): implement partner integration sandbox mode (#101)

[bamiebot-maker]

Summary

Closes #1247

Implements the Partner Integration Sandbox Mode for BridgeWise API, allowing dApps, institutional partners, and wallet integrators to simulate cross-chain bridge lifecycle operations without real capital or on-chain transaction fees.

Key Changes

• Isolated Sandbox Context & Interceptor (SandboxInterceptor):
  • Automatically identifies sandbox requests via x-sandbox-mode: true, x-partner-sandbox: true, query parameters (?sandbox=true), or sb_/sandbox_ API keys.
  • Injects isolated request context (partnerId, scenario, requestId) and stamps outgoing response headers (x-sandbox-mode, x-sandbox-scenario, x-sandbox-request-id).
• Configurable Simulation Scenarios (SandboxService):
  • Supports configurable failure modes:
    • success (Standard flow with mock hash generation and steps)
    • insufficient_liquidity (Pool exhaustion simulation)
    • slippage_exceeded (Rejection upon price deviation)
    • route_unavailable (Unsupported chain/token pairings)
    • destination_revert (Simulated revert & refund lifecycle)
    • timeout (Upstream 504 Gateway Timeout simulation)
    • delayed_completion (In-progress processing simulation)
  • Partner configuration management (latency simulation, custom failure rates).
• Test Asset Faucet (POST /sandbox/faucet):
  • Mints mock test tokens (USDC, XLM, ETH, yXLM, USDT, WBTC) directly to recipient test addresses.
• Transaction Lifecycle & State Tracking:
  • Emulates full multi-step bridging (INITIALIZED -> SUBMITTED -> SOURCE_CONFIRMED -> DESTINATION_PROCESSING -> COMPLETED/REFUNDED).
  • Tracks and queries mock transactions by ID or partner.
• Bridge Provider Adapter (SandboxBridgeProvider):
  • Implements BridgeAdapter interface for modular quote resolution.
• REST Endpoints (SandboxController):
  • GET /sandbox/status: Check sandbox capabilities, active scenario, supported chains/tokens.
  • POST /sandbox/scenarios: Set active scenario for partner.
  • POST /sandbox/reset: Reset all simulated transactions and faucet balances.
  • POST /sandbox/quotes: Request simulated quotes.
  • POST /sandbox/transactions: Submit simulated bridge transfer.
  • GET /sandbox/transactions: List partner simulated transactions.
  • GET /sandbox/transactions/:id: Retrieve single simulated transaction status.
  • POST /sandbox/faucet: Mint test assets.
  • POST /sandbox/webhooks/test: Dispatch test webhook notifications.
• Documentation (docs/PARTNER_INTEGRATION_SANDBOX.md):
  • Comprehensive guide with sample curl commands, scenario descriptions, headers, and isolation guarantees.

Testing

• Unit and integration tests added across 4 test suites:
  • apps/api/src/sandbox/sandbox.service.spec.ts
  • apps/api/src/sandbox/sandbox.controller.spec.ts
  • apps/api/src/sandbox/sandbox.interceptor.spec.ts
  • apps/api/src/sandbox/sandbox-bridge-provider.spec.ts
• Result: 36 passed, 36 total (100% pass rate).

[drips-wave]

@bamiebot-maker 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