feat: webhooks client, analytics tracking, state subscriptions, and parseAmount tests

[dev-fani]

What this fixes

• Unit tests for parseAmount edge cases #1037 (parseAmount unit tests and edge cases): Lack of comprehensive edge case unit tests for parseAmount, including validation of multiple decimal points, fractional digit validation, negative amounts handling (-1.5, -0.5), boundary amounts (zero, sub-stroops, max i64, arbitrary bigints), and truncation behavior (dropping precision past 7 decimals without rounding up).
• Add analytics tracking #1036 (analytics tracking): Absence of an optional analytics tracking API for collecting SDK operational usage metrics, respecting developer/user privacy (sanitizing Stellar secret keys, anonymizing public keys, stripping PII, respecting Do Not Track), collecting method latencies/error rates, and generating comprehensive reports.
• Implement webhook client #1035 (webhook client): Missing client library for receiving, verifying, and processing incoming webhooks, including HMAC-SHA256 signature verification, timestamp freshness validation to prevent replay attacks, middleware execution, type-safe event handlers, and an HTTP request adapter.
• Add real-time invoice state subscription #1034 (real-time invoice state subscription): Missing WebSocket-based real-time invoice state updates with fine-grained multi-criteria filtering (invoiceId, status, creator, payer, minFunded, custom predicates), reliable auto-reconnection with exponential backoff and jitter, and automated re-subscription.

What changed

1. parseAmount Enhancement & Comprehensive Unit Tests (Unit tests for parseAmount edge cases #1037):

   • Added validation against multiple decimal points and non-digit fractional characters.
   • Fixed negative decimal handling to accurately compute signed BigInt stroops (e.g. -1.5 -> -15000000n, -0.5 -> -5000000n).
   • Added test/parseAmount.test.ts with 24 test cases covering valid inputs, rounding/truncation, boundary conditions, and invalid syntax.
   • Re-exported parseAmount and formatAmount from SDK root.

2. Analytics Tracking API & Privacy Controller (Add analytics tracking #1036):

   • Created src/analyticsTracking.ts with AnalyticsTracker, PrivacyController, and AnalyticsCollector.
   • Strictly opt-in (enabled: false by default) with explicit optIn() / optOut() and Do Not Track detection.
   • Privacy controls: automated scrubbing of Stellar secret keys (S...), anonymization/masking of public keys (G...), removal of PII fields (email, ip, password), and strict privacy mode.
   • In-memory metrics collector calculating percentiles (p50, p95, p99), error rates, method call counts, and custom metric counters with queue bounding.
   • Automated Proxy helper wrapClientWithAnalytics to intercept method latency and success/error status.
   • Added test/analyticsTracking.test.ts with 14 unit tests.

3. Webhook Client Library (Implement webhook client #1035):

   • Created src/webhookClient.ts and re-exported from src/webhooks/index.ts and src/index.ts.
   • HMAC-SHA256 timing-safe verification using crypto.timingSafeEqual against raw request body and timestamp to prevent replay attacks.
   • Supports event-specific handlers (on("payment", ...)), wildcard handlers (on("*", ...)), once(), off(), and onError().
   • Middleware pipeline support (use()).
   • Integrated createHttpHandler() adapter for Node.js http / express servers.
   • Added test/webhookClient.test.ts with 17 unit tests.

4. Real-time Invoice State Subscription (Add real-time invoice state subscription #1034):

   • Created src/invoiceStateSubscription.ts with InvoiceStateSubscriber and matchesFilter.
   • Full support for multi-criteria filtering: single/multiple invoiceId, wildcard "*", lifecycle status, creator, payer, minFunded, and custom predicate functions, with dynamic runtime updates via updateFilter().
   • Reliable connection manager with exponential backoff, jitter, configurable maxAttempts, heartbeat ping/pong, and automatic re-subscription on reconnect.
   • Added test/invoiceStateSubscription.test.ts with 12 unit tests.

Testing

All tests executed locally via Vitest:

• test/parseAmount.test.ts: 24 passed
• test/analyticsTracking.test.ts: 14 passed
• test/webhookClient.test.ts: 17 passed
• test/invoiceStateSubscription.test.ts: 12 passed
• test/sdkExports.test.ts: 4 passed
• test/property-roundtrip.test.ts: 8 passed
• test/property-client-invariants.test.ts: 10 passed
• npm test (test/client.test.ts, test/retryPolicy.test.ts, test/network-environment.test.ts): 110 passed

Total: 199 tests passed across all suites.

Issues

closes #1034
closes #1035
closes #1036
closes #1037

[drips-wave]

@dev-fani 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