feat: Introduce strongly-typed exceptions for TONWalletKit

[nikdim03]

Summary by CodeRabbit

• New Features

  • Added dedicated validation exceptions for Base64 and Hex input parsing with clearer error messages.
  • Introduced SDK exception hierarchy for improved error handling and SDK lifecycle management.

• Bug Fixes

  • Enhanced error consistency across SDK components with specialized exception types.

[coderabbitai]

Caution

Review failed

Failed to post review comments.

GitHub was unavailable or timed out while CodeRabbit was posting the review. Please request a new review later if the pull request still needs one. This happened while posting 4 inline comments. Use @coderabbitai full review to retry the review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0c3210f6-9621-4094-84b4-98a2ff1e4364

📥 Commits

Reviewing files that changed from the base of the PR and between 334abc3 and e25b1df.

📒 Files selected for processing (15)

• TONWalletKit-Android/api/src/main/java/io/ton/walletkit/TONWalletKitException.kt
• TONWalletKit-Android/api/src/main/java/io/ton/walletkit/model/TONBase64.kt
• TONWalletKit-Android/api/src/main/java/io/ton/walletkit/model/TONHex.kt
• TONWalletKit-Android/impl/src/main/assets/walletkit/walletkit-android-bridge.mjs
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/bridge/BridgeDispatchException.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/bridge/dispatch/BridgeRequestRegistry.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/bridge/dispatch/WrappedFunctionRegistry.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/core/TONWalletKit.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/WebViewWalletKitEngine.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/infrastructure/InitializationManager.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/infrastructure/MessageDispatcher.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/infrastructure/WebViewManager.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/parsing/EventParser.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/parsing/TONBridgeEventException.kt
• TONWalletKit-Android/impl/src/main/java/io/ton/walletkit/engine/state/KotlinProviderRegistry.kt

🧰 Additional context used

🪛 detekt (1.23.8)

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/model/TONBase64.kt

[warning] 81-81: The caught exception is swallowed. The original exception could be lost.

(detekt.exceptions.SwallowedException)

📝 Walkthrough

Walkthrough

Introduces typed sealed exception hierarchies to replace generic JVM exceptions (IllegalArgumentException, IllegalStateException) throughout the SDK. New public types include TONWalletKitException, TONBase64ValidationException, and TONHexValidationException. Internal types include BridgeDispatchException and TONBridgeEventException. The bundled JS bridge DeFi managers are standardized to throw DefiError via a new toDefiError helper.

Changes

Typed Exception Standardization

Layer / File(s)	Summary
Public API exception contracts api/.../TONWalletKitException.kt, api/.../model/TONBase64.kt, api/.../model/TONHex.kt	Adds sealed TONWalletKitException (with NotInitialized, Destroyed, AutoInitializationFailed subclasses), TONBase64ValidationException (with updated parse catch behavior), and TONHexValidationException (with a new TONHex.Companion.parse method).
Internal bridge exception contracts impl/.../bridge/BridgeDispatchException.kt, impl/.../engine/parsing/TONBridgeEventException.kt	Defines internal sealed BridgeDispatchException with nine dispatch-failure subclasses and TONBridgeEventException with a MissingField subclass.
SDK lifecycle exception wiring impl/.../core/TONWalletKit.kt, impl/.../engine/WebViewWalletKitEngine.kt, impl/.../engine/infrastructure/InitializationManager.kt	checkNotDestroyed() throws TONWalletKitException.Destroyed(), WebViewWalletKitEngine.call throws TONWalletKitException.Destroyed(method), and InitializationManager.ensureInitialized throws NotInitialized() or AutoInitializationFailed(err) replacing prior WalletKitBridgeException throws.
Bridge dispatch exception wiring impl/.../bridge/dispatch/BridgeRequestRegistry.kt, impl/.../bridge/dispatch/WrappedFunctionRegistry.kt, impl/.../engine/infrastructure/MessageDispatcher.kt, impl/.../engine/infrastructure/WebViewManager.kt, impl/.../engine/state/KotlinProviderRegistry.kt, impl/.../engine/parsing/EventParser.kt	Replaces all generic IllegalArgumentException / IllegalStateException throws in bridge dispatch paths with corresponding typed BridgeDispatchException subclasses and replaces error(...) in EventParser with TONBridgeEventException.MissingField.
JS bridge DeFi error standardization impl/.../assets/walletkit/walletkit-android-bridge.mjs	Adds toDefiError helper and DefiErrorCode.Unknown; standardizes DefiManager provider error throws; updates all SwapManager, StakingManager, GaslessManager, and CryptoOnrampManager catch blocks to rethrow via toDefiError; adds CryptoOnrampErrorCode.DepositFailed; converts createTonstakersProvider, createTonApiGaslessProvider, and TonAPI APY validation from generic Error to typed DefiError/StakingError.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ton-org/kit-android#90: Both PRs modify WebViewManager.kt's bridge dispatch and adapter resolution failure paths, with this PR converting those same paths to BridgeDispatchException types.

Suggested reviewers

• ProudOfZiggy

🐇 Hops along the error trail,
No more strings where types should sail!
Destroyed, NotInitialized — crisp and clear,
toDefiError wraps each fear.
Sealed and typed, the SDK stands tall,
One exception type to catch them all! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and clearly describes the main change: introducing strongly-typed exceptions throughout the TONWalletKit SDK as documented in the raw summary.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/ton-1793-typed-errors

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}