feat: Introduce strongly-typed exceptions for TONWalletKit

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

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2025 TonTech
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package io.ton.walletkit
+
+/**
+ * Strongly-typed errors raised by [TONWalletKit] for SDK lifecycle / usage failures.
+ *
+ * These are distinct from [WalletKitBridgeException], which represents failures of the
+ * JavaScript bridge itself. A [TONWalletKitException] signals that the SDK was used
+ * incorrectly (e.g. before initialization or after destruction).
+ */
+sealed class TONWalletKitException(message: String, cause: Throwable? = null) : Exception(message, cause) {
+
+    /** The SDK was used before [TONWalletKit.initialize] was called. */
+    class NotInitialized : TONWalletKitException(
+        "TONWalletKit.initialize() must be called before using the SDK.",
+    )
+
+    /**
+     * The SDK instance has already been destroyed. A new instance must be created.
+     *
+     * @property method The method that was invoked on the destroyed instance, when known.
+     */
+    class Destroyed(val method: String? = null) : TONWalletKitException(
+        method?.let { "Cannot call method '$it' - SDK has been destroyed" }
+            ?: "TONWalletKit instance has been destroyed. Create a new instance.",
+    )
+
+    /** Lazy auto-initialization of the SDK failed. */
+    class AutoInitializationFailed(cause: Throwable) : TONWalletKitException(
+        "Failed to auto-initialize WalletKit: ${cause.message}",
+        cause,
+    )
+}

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

@@ -73,10 +73,14 @@ data class TONBase64(
         /**
          * Parses a Base64-encoded string, validating it upfront.
          *
-         * @throws IllegalArgumentException if [value] is not valid Base64.
+         * @throws TONBase64ValidationException if [value] is not valid Base64.
          */
         fun parse(value: String): TONBase64 {
-            Base64.decode(value, Base64.DEFAULT)
+            try {
+                Base64.decode(value, Base64.DEFAULT)
+            } catch (e: IllegalArgumentException) {
+                throw TONBase64ValidationException(value)
+            }
             return TONBase64(value)
         }
     }
@@ -101,3 +105,12 @@ object TONBase64Serializer : KSerializer<TONBase64> {
         return TONBase64(decoder.decodeString())
     }
 }
+
+/**
+ * Raised when a string fails [TONBase64] validation.
+ *
+ * @property invalidValue The string that was not valid Base64.
+ */
+class TONBase64ValidationException(
+    val invalidValue: String,
+) : IllegalArgumentException("$invalidValue is not a valid base64 encoded string.")

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

@@ -89,6 +89,19 @@ data class TONHex(
         fun fromString(string: String, withPrefix: Boolean = true): TONHex {
             return fromData(string.toByteArray(Charsets.UTF_8), withPrefix)
         }
+
+        /**
+         * Parses a hex string, validating it upfront.
+         *
+         * @throws TONHexValidationException if [value] is not a valid hex string.
+         */
+        fun parse(value: String): TONHex {
+            val hex = TONHex(value)
+            if (hex.data == null) {
+                throw TONHexValidationException(value)
+            }
+            return hex
+        }
     }
 
     override fun toString(): String = value
@@ -111,3 +124,12 @@ object TONHexSerializer : KSerializer<TONHex> {
         return TONHex(decoder.decodeString())
     }
 }
+
+/**
+ * Raised when a string fails [TONHex] validation.
+ *
+ * @property invalidValue The string that was not a valid hex string.
+ */
+class TONHexValidationException(
+    val invalidValue: String,
+) : IllegalArgumentException("$invalidValue is not a valid hex string.")