feat: add refund eligibility computation logic and API endpoints for …

[toniasteve15-ui]

#closes #72

PR Description: Read-only refund eligibility endpoint for transaction history (#72)

Summary

This PR implements a read-only refund eligibility helper and API endpoint to allow transaction history interfaces and external consumers to determine when a stuck cross-chain order can be refunded on-chain without initiating transactions.

Changes Included

1. SDK Core (@oversync/sdk)

• computeRefundEligibility Helper: Implemented computeRefundEligibility(input) in packages/sdk/src/state-machine/refund-eligibility.ts.
• Export Integration: Exported computeRefundEligibility and its associated types (RefundEligibilityReasonCode, RefundEligibilityInput, RefundEligibilityResult) from @oversync/sdk.
• Reason Codes: Full support for all 5 required reason codes:
  • not_expired ("not expired"): Timelock is still active or not yet locked on-chain.
  • already_claimed ("already claimed"): Order status is completed or secret_revealed.
  • already_refunded ("already refunded"): Order status is refunded.
  • eligible ("eligible"): Timelock has passed and order is in a refundable state (announced, src_locked, dst_locked, failed, expired).
  • unknown_order ("unknown order"): Order is not found or null.

2. Coordinator API (@oversync/coordinator)

• OrderService.getRefundEligibility: Added getRefundEligibility(publicId, nowUnixSeconds?) method in OrderService.
• Read-only Endpoint: Added GET /api/orders/:id/refund-eligibility endpoint returning JSON:

  {
    "id": "order-id",
    "refundEligibility": {
      "eligible": true,
      "reasonCode": "eligible",
      "reason": "eligible",
      "timeRemainingSeconds": 0
    }
  }

  Returns 404 Not Found with reasonCode: "unknown_order" if the order does not exist.
• Enriched History & Detail Responses: Enriched serialiseOrder in routes/orders.ts to include refundEligibility seamlessly on GET /api/orders/:id and GET /api/orders/history without breaking existing consumers.

3. Frontend & Transaction History (@oversync/frontend)

• Integrated refundEligibility metadata in TransactionHistory.tsx to expose refund eligibility and reason codes.

4. Tests

• SDK Unit Tests: Added packages/sdk/test/refund-eligibility.test.ts with 15 tests covering ETH->XLM and XLM->ETH orders across all order statuses and timelock conditions.
• Coordinator Route Tests: Added coordinator/test/refund-eligibility-route.test.ts verifying HTTP responses for valid orders, unknown orders, and history integration.

Guardrails Adherence

• ✅ No Auto-Submit: No automated refund transactions are submitted.
• ✅ No Contract Modifying Calls: Read-only computation based on order status, timelocks, and time.
• ✅ Evidence-Based Status: Orders are only marked refunded when on-chain evidence is confirmed.
• ✅ Backward Compatible: Existing history endpoints and transaction structures remain 100% compatible.

Verification

• @oversync/sdk unit tests: 142/142 passed (11/11 test files).
• @oversync/coordinator unit and route tests: 143/143 passed (14/14 test files).
• @oversync/frontend build: Vite build succeeded cleanly (dist/ created in 13.76s).
  #closes

[vercel]

@Oluwasuyi-Oluwatimilehin-Daniel is attempting to deploy a commit to the karagoz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@toniasteve15-ui 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

[toniasteve15-ui]

@karagozemin please review and merge

[toniasteve15-ui]

@karagozemin