feat: reconcile pending settlements against Horizon

[samueloyibodevv]

Overview

This PR adds an on-chain settlement-status sync flow so pending developer payouts are reconciled against the configured Horizon network and eventually transition to completed or failed. It closes the payout loop by polling Horizon for each pending settlement tx_hash, retrying transient Horizon failures with backoff, and setting completed_at only after on-chain confirmation.

Related Issue

Closes #310

Changes

⚙️ Settlement Reconciliation

• [MODIFY] src/services/revenueSettlementService.ts

• Added reconcilePendingSettlements() to query pending settlements and reconcile each tx_hash against Horizon.

• Reused withRetry(...) from src/lib/retry.ts for transient Horizon failures.

• Updated payout flow so successful submission leaves settlements in pending with a transaction hash until confirmation.

• Ensured completed_at is set only when Horizon confirms the transaction.

• [ADD] src/services/settlementStatusSyncJob.ts

• Added a background sync job that periodically runs settlement reconciliation.

• Prevents overlapping reconciliation runs and logs failures without crashing the app.

🌐 Runtime Wiring

• [MODIFY] src/index.ts
• Wired the settlement-status sync job into app startup.
• Ensured the job stops during graceful shutdown.
• Reused the active STELLAR_NETWORK Horizon configuration via config.stellar.horizonUrl.

🧱 Store and Model Updates

• [MODIFY] src/types/developer.ts

• Added completed_at to the settlement shape.

• Extended SettlementStore with getPendingSettlements() for reconciliation.

• [MODIFY] src/services/settlementStore.ts

• Added pending-settlement reads to the in-memory store.

• Updated status transitions so completed_at is populated only on confirmed completion.

🧪 Tests

• [MODIFY] src/__tests__/revenueSettlementService.test.ts

• Added coverage for Horizon-confirmed settlement completion.

• Added coverage for unsuccessful Horizon transactions.

• Added coverage for missing Horizon transactions.

• Added coverage for retryable Horizon errors succeeding after backoff.

• Added coverage for exhausted transient Horizon errors leaving status unchanged.

• [MODIFY] tests/integration/billing.test.ts

• Updated the integration-test SettlementStore helper to support pending-settlement queries.

🔧 Configuration and Docs

• [MODIFY] src/config/env.ts

• Added environment validation for settlement sync interval and request timeout.

• [MODIFY] src/config/index.ts

• Added settlement sync config values to the exported runtime config.

• [MODIFY] .env.example

• Added SETTLEMENT_STATUS_SYNC_INTERVAL_MS.

• Added SETTLEMENT_STATUS_SYNC_TIMEOUT_MS.

• [MODIFY] README.md

• Documented the new Horizon-based settlement reconciliation flow.

• Documented the new environment variables and the pending-with-tx-hash lifecycle.

• [MODIFY] src/data/developerData.ts

• Updated fixture validation to allow pending settlements with a non-empty transaction hash after payout submission.

Verification Results

Acceptance Criteria	Status
Pending settlements transition to completed/failed based on on-chain status	✅
Transient Horizon errors are retried with backoff and do not flip status	✅
completed_at is set only on confirmation	✅
Horizon sync honors the selected STELLAR_NETWORK configuration	✅
Background sync job is wired into the app lifecycle	✅
Revenue settlement service tests pass successfully	✅
Typecheck passes successfully	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Run the settlement reconciliation tests
npm test -- src/__tests__/revenueSettlementService.test.ts

# 3. Verify TypeScript types
npm run typecheck

# 4. Optional: inspect the changed files
git diff -- src/services/revenueSettlementService.ts src/services/settlementStatusSyncJob.ts src/services/settlementStore.ts src/index.ts src/config/env.ts src/config/index.ts .env.example README.md

Screenshots

✅ Revenue settlement service tests pass

A screenshot of:

npm test -- src/__tests__/revenueSettlementService.test.ts

[drips-wave]

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