feat: architecture docs, JSDocs, example apps, and debug logging

[faith-ng]

Overview

This pull request addresses and resolves four related issues for the @stellar-split/sdk:

• Create architecture documentation #1076: Architecture & Design Patterns Documentation
• Add JSDoc for all public methods #1075: Comprehensive JSDoc Documentation for Public Methods
• Create TypeScript example applications #1074: TypeScript Example Applications
• Add debug logging #1073: Structured Debug Logging Subsystem

---

What changed

1. Architecture Documentation (#1076)

• Created ARCHITECTURE.md documenting the complete system topology and component interactions:
  • System Topology Diagram: Mermaid flowchart detailing the Client Application Layer, SDK Core modules, and Stellar Soroban infrastructure.
  • Directory & Package Structure: Modular domain boundaries across builders, soroban RPC, resilience, signers, adapters, events, cache, and webhooks.
  • Core Subsystems: Deep dive on Client Orchestration, Transaction Building & Footprint Optimization, Circuit Breakers & Backoff, Key Management (Keypair, EncryptedFile, CloudKms, Browser Wallets), Streaming Transports, Webhook Security, and Debug Logging.
  • Design Patterns: Adapter, Circuit Breaker (with Mermaid state diagram), Optimistic State Concurrency, Typed Event-Driven Architecture, and Plugin Interceptors.
  • End-to-End Sequence Diagrams:
    • Multi-party invoice split and automatic release flow.
    • Resilient RPC failover with Circuit Breaker state transitions.
    • Webhook HMAC-SHA256 signature verification and LRU nonce replay prevention.
  • Best Practices & Guidelines: Guidelines on typed amounts, secret redaction, circuit breaker tuning, and shutdown lifecycle hooks.

2. JSDoc Documentation (#1075)

• Added comprehensive JSDoc comments across public client methods, configuration interfaces, and domain types:
  • Fully documented method purpose, preconditions, and behavioral nuances.
  • Documented @param types, descriptions, and constraints.
  • Documented @returns types and resolution semantics.
  • Added over 190 runnable @example blocks across public SDK methods illustrating realistic usage patterns.

3. TypeScript Example Applications (#1074)

• Created runnable, end-to-end TypeScript example applications in examples/:
  • basic-split-invoice.ts: Canonical invoice splitting lifecycle—multi-party recipient definition with exact stroop allocations, simulation against Soroban RPC, proportional disbursements, and receipt generation.
  • batch-payments.ts: High-volume payroll and payout batch operations with automatic footprint chunking, pre-flight verification, and atomic multi-payment execution.
  • dispute-and-arbitration.ts: Escrow dispute workflows—transitioning to contested states with IPFS evidence attachments, multi-arbiter consensus voting (e.g. 2-of-3 threshold), and automated dispute settlement.
  • realtime-monitoring.ts: Real-time event subscription and live state synchronization via TypedEventEmitter.
• Created examples/README.md with quick-start instructions (npx tsx), flow explanations, and environment variable configuration options.

4. Debug Logging Subsystem (#1073)

• Implemented structured logging in src/logger.ts:
  • Log Levels: Designed LogLevel enum (DEBUG, INFO, WARN, ERROR, NONE) and string union type (LogLevelString) with flexible parsing (parseLogLevel).
  • SdkLogger: Structured logging class supporting severity filtering, runtime level mutation (setLevel), and hierarchical child loggers (child()).
  • Sensitive Data Redaction: Automatic masking of Stellar secret seeds (S[A-Z0-9]{55}) and credential keys (secret, privateKey, password, token, apiKey, etc.) from messages and context payloads.
  • Pluggable Formats & Sinks: Built-in defaultLogFormatter and defaultConsoleSink with support for custom formatters and destination sinks.
  • Client Integration: Added client.logger, client.setLogLevel, client.enableDebugLogging, logger and logLevel client config options, and SPLIT_SDK_LOG_LEVEL environment variable support.
  • Root Re-exports: Exported all logger classes, functions, and types from src/index.ts.

---

Testing

• Logger Unit Tests:
  • test/logger.test.ts: 19 passed (level parsing, string mapping, level filtering, secret redaction, formatting, child loggers, and client integration)
• Baseline SDK Tests:
  • test/client.test.ts: 68 passed
  • test/retryPolicy.test.ts: 31 passed
  • test/network-environment.test.ts: 11 passed
  • test/webhookMiddleware.test.ts: 51 passed
  • test/bundleSizeGuard.test.ts: 8 passed
• Build Verification:
  • npm run build: Successfully generated ESM, CJS, and DTS bundles.
• Example Applications:
  • Verified each example script runs successfully via npx tsx:
    • npx tsx examples/basic-split-invoice.ts (exited 0)
    • npx tsx examples/batch-payments.ts (exited 0)
    • npx tsx examples/dispute-and-arbitration.ts (exited 0)
    • npx tsx examples/realtime-monitoring.ts (exited 0)

---

Issues

closes #1076
closes #1075
closes #1074
closes #1073

[drips-wave]

@faith-ng 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