Skip to content

feat(hooks): add useSettlementBreakdown hook for post-delivery fund distribution - #899

Merged
johdanike merged 2 commits into
SwiftChainn:mainfrom
BigManly4:feat/use-settlement-breakdown-hook
Oct 5, 2026
Merged

johdanike merged 2 commits into
SwiftChainn:mainfrom
BigManly4:feat/use-settlement-breakdown-hook

Conversation

@BigManly4

Copy link
Copy Markdown
Contributor

Closes #782

Summary

Adds useSettlementBreakdown, which fetches the finalized settlement for an escrow from GET /api/escrow/{id}/settlement and polls until the release transaction reaches a terminal state.

Changes

  • services/escrowSettlementService.ts: calls the settlement endpoint through the shared apiClient, maps axios failures to a SettlementServiceError (backend message, 404 message, or generic fallback) and exposes isTerminalStatus.
  • hooks/useSettlementBreakdown.ts: TanStack Query hook. It returns settlement, formatted amounts, taxBreakdown, explorerUrl, isLoading, isFetching, isFinalizing, isTerminal, error and refetch.
    • Polls every 5s (configurable) while the status is pending or finalizing, and stops on confirmed or failed.
    • Does not retry 4xx errors. Retries 5xx and network errors twice.
  • types/settlementBreakdown.ts: SettlementBreakdown with driver payout, platform fee and rate, tax withholdings, held amount and reason, remaining balance, transaction hash and ledger, and delivery summary.
  • lib/settlementFormatters.ts: asset amount formatting (Stellar 7-decimal precision), percentage formatting and the stellar.expert transaction URL builder.

Layering: Component -> useSettlementBreakdown -> escrowSettlementService -> backend. Test data lives in hooks/__tests__/fixtures/settlementApiResponses.ts. Nothing is mocked inline in the source.

Tests

  • hooks/__tests__/useSettlementBreakdown.test.tsx (11): structured data, formatted values, tax breakdown, explorer link, polling until confirmed or failed, no retry on 4xx, retry on 5xx, recovery through refetch, disabled or missing id.
  • services/__tests__/escrowSettlementService.test.ts (10) and lib/__tests__/settlementFormatters.test.ts (4).
  • 25 passing. The hook has 100% coverage.

Note: CI on main is already failing at the Lint step because of existing errors (for example the parse error in app/error.tsx). The files in this PR pass eslint and tsc --noEmit with no errors.

Screenshots

@drips-wave

drips-wave Bot commented Sep 29, 2026

Copy link
Copy Markdown

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

@johdanike

Copy link
Copy Markdown
Contributor

Conflicts!!
I'd fix anyways

@johdanike
johdanike merged commit f4d0c2f into SwiftChainn:main Oct 5, 2026
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hook: useSettlementBreakdown for Post-Delivery Fund Distribution

2 participants