feat: implement invoice versioning, payment analytics, contract ABI cache, and collaboration

[maztah1]

What this fixes

• Implement invoice versioning #1056 (Implement invoice versioning): Invoices previously lacked change tracking, point-in-time state inspection, and safe rollback mechanisms. When an invoice configuration changed, previous revisions and changes were lost with no clear audit history or safe rollback capability.
• Add payment analytics #1055 (Add payment analytics): Developers and consumers lacked a structured analytics engine to aggregate payments, evaluate invoice performance metrics, measure settlement timing, rank payers, and generate reports and visual dashboards.
• Implement smart contract ABI caching #1054 (Implement smart contract ABI caching): Querying Soroban smart contract interface specifications repeatedly generated redundant network and RPC requests, causing latency overhead. There was no dedicated cache system with pluggable storage, fetchers, and sound invalidation.
• Add invoice collaboration features #1053 (Add invoice collaboration features): There was no built-in support for multi-stakeholder collaboration on invoices, including threaded discussions, mention parsing, multi-party quorum approval workflows, and notification dispatching.

What changed

• Invoice Versioning System (src/invoiceVersioning.ts, src/invoiceVersionTracker.ts):
  • Implemented InvoiceVersionManager and enhanced InvoiceVersionTracker with immutable snapshots and SHA-256 integrity checksums (computeChecksum).
  • Added change tracking deriving diff summaries and split rule preview diffs.
  • Added isRollbackSafe() and rollback() with safeguards protecting finalized invoices (Released/Refunded) and options to preserve recorded payments and funded state.
  • Added human-readable audit changelog extraction (getChangeLog) and JSON export/import (exportHistoryJson, importHistoryJson).
  • Added typed errors InvoiceVersionNotFoundError, UnsafeRollbackError, and InvalidVersionError.
• Payment Analytics Engine (src/paymentAnalytics.ts):
  • Implemented PaymentAnalyticsEngine providing aggregation across invoices, payments, tokens, and statuses.
  • Built payer cohort aggregation with volume rankings, payment counts, and repeat payer rate metrics (aggregatePayers).
  • Implemented time-series payment volume aggregation into configurable time windows (aggregateTimeSeries).
  • Added invoice performance and health status classification (analyzeInvoicePerformance).
  • Added reporting formatters (formatReport, exportJson, exportCsv).
  • Added visual chart helpers including horizontal ASCII bar charts (renderAsciiBarChart), sparklines (renderSparkline), volume charts, status distribution charts, and structured data export (exportChartData) compatible with Chart.js and Recharts.
• Smart Contract ABI Caching Layer (src/abiCache.ts):
  • Implemented ContractAbiCache with transparent fetch-and-cache mechanics.
  • Added storage backends: MemoryAbiStorage (with sub-millisecond monotonic sequence LRU eviction and byte-size capacity budgeting) and AdapterAbiStorage (backed by persistent Web Storage / MemoryStorageAdapter).
  • Added ABI fetchers: StaticContractAbiFetcher (registry-based) and RpcContractAbiFetcher (Soroban RPC-based).
  • Implemented sound multi-strategy cache invalidation: by contract ID (invalidate), by WASM bytecode hash (invalidateByWasmHash), by predicate (invalidateMatching), and by TTL expiry (invalidateExpired).
  • Added storage efficiency optimizations including compact mode to strip non-essential docstrings.
  • Added typed errors AbiFetchError and AbiNotFoundError.
• Invoice Collaboration & Approvals (src/invoiceCollaboration.ts):
  • Implemented InvoiceCollaborationManager with threaded discussion comments, nested reply hierarchy trees (getThreadedComments), and @mention extraction.
  • Implemented multi-approver authorization workflows (requestApproval, submitDecision, getApprovalStatus) with configurable quorum thresholds and automatic state transitions.
  • Implemented event-driven notification dispatching with in-app inbox filtering (getNotifications, markNotificationAsRead) and pluggable notification handlers.
  • Added typed errors CollaborationError, CommentNotFoundError, ApprovalRequestNotFoundError, and UnauthorizedCollaborationError.
• Exports & Public API (src/index.ts):
  • Exported all new modules, classes, interfaces, error classes, and error type guards.

Testing

• Ran comprehensive vitest suite for all new and modified components:
  • test/invoiceVersioning.test.ts (9 tests passed)
  • test/paymentAnalytics.test.ts (9 tests passed)
  • test/abiCache.test.ts (10 tests passed)
  • test/invoiceCollaboration.test.ts (10 tests passed)
  • test/invoiceVersionTracker.test.ts (22 tests passed)
  • test/sdkExports.test.ts (7 tests passed)
  • test/client.test.ts (68 tests passed)
  • test/retryPolicy.test.ts (31 tests passed)
  • test/network-environment.test.ts (11 tests passed)
  • Total: 177 tests passed across 9 test suites.
• Type-checked with TypeScript compiler (tsc --noEmit), with zero errors in all new and modified files.

Issues

closes #1056
closes #1055
closes #1054
closes #1053

[drips-wave]

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