Skip to content

CHANGELOG.md

Latest commit

 

History

History
43 lines (36 loc) · 5.26 KB

CHANGELOG.md

File metadata and controls

43 lines (36 loc) · 5.26 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • cacheMessages option for CommunicationsModule — communications: { cacheMessages: false } in SphereInitOptions disables DM caching in memory and storage. Messages still flow through onDirectMessage() handlers and message:dm events, but are never stored. Useful for anonymous/ephemeral agents (e.g. LLM bots) that only need streaming DM reception. sendDM() still works but doesn't cache the sent message. Deduplication is skipped when caching is disabled.
  • Message signing — signMessage(), verifySignedMessage(), hashSignMessage() crypto functions for secp256k1 ECDSA with recoverable signatures (Bitcoin-like double-SHA256 with Sphere Signed Message:\n prefix). Sphere.signMessage(message) instance method encapsulates private key access. SIGNING_ERROR added to SphereErrorCode. SphereInstance interface in ConnectHost extended with signMessage. 22 unit tests covering signing, verification, round-trips, tampering detection, and edge cases.
  • Centralized logger — logger singleton with debug/warn/error levels, globalThis-based state sharing across tsup bundles, per-tag control (logger.setTagDebug('Nostr', true)), and custom handler support
  • SphereError with typed error codes — All SDK methods throw SphereError with a typed .code field (SphereErrorCode). 15 error codes: NOT_INITIALIZED, ALREADY_INITIALIZED, INVALID_CONFIG, INVALID_IDENTITY, INSUFFICIENT_BALANCE, INVALID_RECIPIENT, TRANSFER_FAILED, STORAGE_ERROR, TRANSPORT_ERROR, AGGREGATOR_ERROR, VALIDATION_ERROR, NETWORK_ERROR, TIMEOUT, DECRYPTION_ERROR, MODULE_NOT_AVAILABLE
  • isSphereError() type guard — Helper function for typed error handling in catch blocks
  • Silent failure logging — All previously silent .catch(() => {}), empty catch blocks, and timeout-based silent failures now log via logger.warn (operational issues) or logger.debug (expected/non-critical)
  • 20 unit tests for logger module
  • IPNS push-based sync via WebSocket — IpnsSubscriptionClient connects to /ws/ipns on IPFS gateways for real-time IPNS update notifications, with exponential backoff reconnection (5s→60s capped) and 30s keepalive pings
  • Fallback HTTP polling — When WebSocket is unavailable, the IPFS provider automatically polls for IPNS changes at a configurable interval (default: 90s)
  • Auto-sync on import — Sphere.import() automatically syncs with all registered token storage providers after initialization to recover tokens from IPFS
  • Debounced auto-sync on remote updates — PaymentsModule subscribes to storage:remote-updated events from token storage providers and performs a debounced (500ms) sync, emitting a new sync:remote-update sphere event
  • storage:remote-updated storage event type — New event emitted by IpfsStorageProvider when a remote IPNS change is detected via WebSocket push or HTTP polling
  • sync:remote-update sphere event — New top-level event with { providerId, name, sequence, cid, added, removed } payload, emitted after a push-triggered sync completes
  • WebSocket factory injection in platform factories — createNodeIpfsStorageProvider() and createBrowserIpfsStorageProvider() now automatically inject platform-appropriate WebSocket factories
  • IpfsHttpClient.getGateways() — New public accessor returning configured gateway URLs
  • IpfsStorageConfig extensions — New optional fields: createWebSocket, wsUrl, fallbackPollIntervalMs, syncDebounceMs
  • IpnsUpdateEvent type — Exported from impl/shared/ipfs for consumers
  • 24 unit tests for IpnsSubscriptionClient covering subscribe, message handling, reconnection, keepalive, fallback polling, and disconnect

Fixed

  • IPFS token recovery via TXF merge — mergeTxfData() now recognizes individual token entries (token-* keys) stored via saveToken(), not just _-prefixed TXF keys; previously IPFS sync returned added: 0 because merge couldn't find tokens in the blob
  • TXF parser handles individual file format — parseTxfStorageData() now extracts tokens from { token, meta } wrapper format used by IPFS individual token storage
  • Sync coalescing — PaymentsModule.sync() now coalesces concurrent calls, preventing race conditions when multiple syncs overlap

Changed

  • All throw new Error() in production code replaced with throw new SphereError() — zero plain errors remaining
  • All console.log/warn/error in production code replaced with logger.debug/warn/error — console output controlled by debug flag
  • logger.warn() and logger.error() are always shown regardless of debug flag; logger.debug() is hidden when debug=false
  • PaymentsModule.updateTokenStorageProviders() now re-subscribes to storage events when providers change
  • PaymentsModule.destroy() now cleans up storage event subscriptions and debounce timers
  • IpfsStorageProvider.shutdown() now disconnects the subscription client