feat: add Horizon transaction, history, order book, and trade examples

[WhiteTrojanHorse]

Summary

This PR adds four runnable Horizon examples covering transaction lifecycle monitoring, account-history pagination, order-book inspection, and historical trade analysis.

120 — Transaction Lifecycle Monitoring

Adds 120-transaction-lifecycle-monitor.ts with support for:

• transaction hash validation
• Horizon transaction polling
• pending/unavailable transaction handling
• successful confirmation detection
• failed transaction reporting
• configurable polling interval
• configurable timeout
• Horizon 429/rate-limit handling
• ledger sequence and close-time reporting
• successful operation count
• fee charged and result information
• structured JSON output

When no transaction hash is supplied, the example can discover the latest Horizon transaction so the example remains directly runnable.

121 — Account History Pagination

Adds 121-account-history-pagination.ts with support for:

• Stellar account validation
• account operation-history retrieval
• forward Horizon pagination
• configurable page size
• configurable maximum total record count
• multi-page traversal beyond Horizon's 200-record per-page limit
• operation-type filtering
• duplicate prevention
• safe pagination termination
• operation ID, type, transaction hash, ledger, source account, and timestamp display
• graceful empty-history handling
• useful Horizon/network errors
• structured JSON output

122 — Order Book Inspection

Adds 122-order-book-inspection.ts with support for:

• native and issued Stellar asset parsing
• selling/base and buying/counter asset input
• Horizon order-book retrieval
• configurable market depth
• bid and ask parsing
• best bid and best ask
• bid/ask spread
• mid-market price
• spread percentage
• best bid and ask quantities
• price-level counts
• summarized bid/ask liquidity
• empty order-book handling
• invalid asset-pair errors
• structured JSON output

The example also explains the role of bids and asks when displaying market depth.

123 — Trade History Analysis

Adds 123-trade-history-analysis.ts with support for:

• Stellar asset-pair input
• historical Horizon trade retrieval
• configurable record limits
• trade timestamp
• trade price
• base asset amount
• counter asset amount
• trade type where available
• highest trade price
• lowest trade price
• average trade price
• total traded volume
• counter volume
• number of trades
• ISO-8601 and Unix timestamp filtering
• empty trade-history handling
• invalid asset-pair handling
• structured JSON output

Runner and Documentation

All four examples are registered in the interactive example catalog and documented in the README with direct npm run run-example ... commands and configuration information.

Testing

Focused test coverage includes:

• transaction hash validation
• pending transaction polling
• transaction confirmation and failure
• Horizon rate-limit parsing
• account validation
• multi-page history traversal
• duplicate prevention
• operation filtering
• record limits
• page-size handling
• asset validation
• order-book parsing
• spread and midpoint calculations
• order-book depth and liquidity
• empty order books
• historical trade parsing
• price and volume statistics
• time filtering
• empty trade history
• runner registration
• README documentation

Validation completed:

• 21/21 focused tests passing
• ESLint passing for all new example and test files
• git diff --check passing
• no new dependencies introduced

The repository-wide TypeScript check is currently blocked by a pre-existing unrelated syntax defect in src/runner/catalog.ts on the upstream baseline. That unrelated issue was intentionally left unchanged.

Closes #167
Closes #168
Closes #169
Closes #170

[drips-wave]

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