feat: implement error logging, breadcrumb tracking, error context, and error aggregation

[joromi1]

What this fixes

• Implement error logging #1069 (Error Logging): The SDK lacked a structured, level-aware error and operational logging mechanism with support for clear severity filtering, human-readable text and structured JSON formatting, and reliable pluggable storage sinks.
• Add breadcrumb tracking #1070 (Breadcrumb Tracking): When errors occurred, developers lacked chronological insight into preceding events (HTTP calls, Soroban RPC interactions, on-chain transactions, state transitions, and UI actions).
• Implement error context #1071 (Error Context): Errors lacked structured contextual metadata (operations, account IDs, invoice IDs, network details, tags, and breadcrumb trails), and thrown error objects could not be safely serialized to JSON when containing BigInt values or circular references, or risked leaking sensitive credentials like Stellar secret keys.
• Implement error aggregation #1072 (Error Aggregation): Repeated or related errors across batch payments or high-frequency invocations were difficult to group, diagnose, and monitor. Developers needed logical grouping strategies, anomaly/pattern detection (such as error spikes, recurring entity failures, and cascading failures), and comprehensive reporting.

What changed

• Error Logger (src/errorLogger.ts):
  • Implemented ErrorLogger with log levels (debug, info, warn, error, fatal), priority filtering (isLogLevelEnabled, parseLogLevel), and child logger support with merged context.
  • Implemented TextLogFormatter for human-readable outputs and JsonLogFormatter for structured logging with safe serialization.
  • Created LogStorage contract and implementations: MemoryLogStorage (bounded FIFO ring buffer), ConsoleLogStorage, and MultiLogStorage.
• Breadcrumb Tracker (src/breadcrumbTracker.ts):
  • Designed Breadcrumb structure capturing category, message, level, timestamp, and rich data payloads.
  • Implemented BreadcrumbTracker with helper methods (trackHttp, trackTransaction, trackRpc, trackStateChange, trackUserAction, trackError).
  • Added storage-efficient RingBufferBreadcrumbStorage with bounded memory capacity and fast retrieval with filtering.
• Error Context (src/errorContext.ts):
  • Implemented attachErrorContext, getErrorContext, and hasErrorContext preserving error prototypes and integrating with StellarSplitError.
  • Added sanitizeContext recursively masking Stellar secret seeds (S[A-Z0-9]{55}) and sensitive credential keys, and handling circular references.
  • Added serializeError converting standard/StellarSplit errors into pure JSON-safe objects with BigInt stringification.
  • Provided fluent ErrorContextBuilder, withErrorContext (sync/async wrapper), and wrapError.
• Error Aggregator (src/errorAggregator.ts):
  • Implemented ErrorAggregator with flexible grouping strategies (code, message, type, component, fingerprint, and custom resolvers).
  • Added normalizeErrorMessage template normalizer masking dynamic addresses, hashes, numbers, and UUIDs.
  • Implemented automated pattern detection for error spikes, high-frequency dominant errors, recurring entity failures, and cascading failures.
  • Added generateReport with export formats in text, markdown, and JSON.
• SDK Exports (src/index.ts):
  • Re-exported all new classes, utilities, and TypeScript types from the root package entry point.

Testing

• Ran test suite with Vitest:
  • test/errorLogger.test.ts: 13 passing tests (levels, formatters, storage limits, filtering, logger API)
  • test/breadcrumbTracker.test.ts: 11 passing tests (storage efficiency, ring buffer eviction, rich context tracking, fast filtering)
  • test/errorContext.test.ts: 11 passing tests (context attachment, sanitization/masking, BigInt/circular serialization, fluent builder, withErrorContext)
  • test/errorAggregator.test.ts: 13 passing tests (normalization, grouping, pattern detection, reporting in text/markdown/JSON)
  • Baseline test suites: test/client.test.ts, test/retryPolicy.test.ts, test/network-environment.test.ts (110 passing tests)
  • Total: 158 tests passed (0 failed)
• Ran TypeScript type-checking on all new implementation and test files with zero errors.

Issues

closes #1072
closes #1071
closes #1070
closes #1069

[drips-wave]

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