feat: implement allowance expiry alert script (#78)

[Abdullahi-Code9]

Closes #584

📝 Description

This PR introduces scripts/alert-expiring-allowances.ts, a proactive alerting system for expiring Stellar token allowances. By inspecting Soroban ledger keys directly, it detects upcoming allowance expiries before charges fail, generates structured reports, supports webhook dispatching, and provides an actionable exit code for CI/cron execution.

🚀 Changes Made

1. Allowance Expiry Detection & Script

• scripts/alert-expiring-allowances.ts: Implemented a new script that queries active subscribers and inspects their underlying ContractData ledger entries (liveUntilLedgerSeq) to identify allowances expiring within a configurable ledger window (ALERT_WINDOW_LEDGERS).

2. Subscriber Optimization & Filtering

• Filtered out inactive/paused subscribers and non-expiring allowances (liveUntilLedgerSeq = 0) to prevent false alarms.
• Reused SIM_SOURCE for simulation sources to remove unnecessary RPC round-trips per subscriber check.

3. Webhook Delivery & Automation Output

• Configured JSON reporting to stdout with dry-run support (--dry-run).
• Integrated optional WEBHOOK_URL POST alerts while maintaining exit code 1 whenever expiring allowances are detected (allowing for CI pipeline integration).

4. Compiler Bug Fixes

• scripts/health-check.ts: Updated top-level import to include Account from @stellar/stellar-sdk instead of an invalid non-async dynamic import.
• scripts/export-merchant-report.ts: Updated ledgerCloseTime to Date.parse(event.ledgerClosedAt) to match the @stellar/stellar-sdk API update.

---

🧪 Verification & Testing

Type Safety Verification

Verified strict TypeScript types across scripts without compiler errors:

npx tsc --noEmit

[drips-wave]

@Abdullahi-Code9 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