refactor: rename error classes for consistency and clarity; update related code and tests

examples/client_init.py

@@ -0,0 +1,36 @@
+"""
+Example: initializing FragmentClient.
+
+Cookies can be passed as a dict or as a JSON string.
+wallet_version defaults to "V5R1" — change to "V4R2" for older wallets.
+"""
+
+import asyncio
+
+from fragmentapi import FragmentClient
+
+SEED = "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 word16 word17 word18 word19 word20 word21 word22 word23 word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+
+async def main() -> None:
+    client = FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2"
+    )
+
+    print("FragmentClient initialized")
+    print("   %-16s %s" % ("Wallet version:", client.wallet_version))
+    print("   %-16s %s..." % ("API key:", client.api_key[:8]))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/gift_premium.py

@@ -0,0 +1,45 @@
+"""
+Example: gift Telegram Premium to a user.
+
+Supported durations: 3, 6, or 12 months.
+Set show_sender=False to send anonymously.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+MONTHS = 3  # 3, 6, or 12
+
+
+async def main() -> None:
+    client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+    try:
+        result = await client.gift_premium(USERNAME, months=MONTHS, show_sender=True)
+    except UserNotFoundError:
+        print(f"User {USERNAME!r} not found on Fragment.")
+        return
+    except ConfigurationError as e:
+        print(f"Invalid parameters: {e}")
+        return
+
+    print("Premium gifted")
+    print("   %-14s %s" % ("Username:", result.username))
+    print("   %-14s %s months" % ("Duration:", result.months))
+    print("   %-14s %s" % ("Transaction:", result.transaction_id))
+    print("   %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/gift_stars.py

@@ -0,0 +1,45 @@
+"""
+Example: gift Telegram Stars to a user.
+
+Amount must be an integer between 50 and 1 000 000.
+Set show_sender=False to send anonymously.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+AMOUNT = 500  # 50–1 000 000
+
+
+async def main() -> None:
+    client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+    try:
+        result = await client.gift_stars(USERNAME, amount=AMOUNT, show_sender=True)
+    except UserNotFoundError:
+        print(f"User {USERNAME!r} not found on Fragment.")
+        return
+    except ConfigurationError as e:
+        print(f"Invalid parameters: {e}")
+        return
+
+    print("Stars gifted")
+    print("   %-14s %s" % ("Username:", result.username))
+    print("   %-14s %s" % ("Stars:", result.stars))
+    print("   %-14s %s" % ("Transaction:", result.transaction_id))
+    print("   %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/topup_ton.py

@@ -0,0 +1,48 @@
+"""
+Example: top up a Telegram Ads account with TON.
+
+Amount must be an integer between 1 and 1 000 000 000 TON.
+Your wallet must hold at least the topup amount + ~0.056 TON for gas.
+"""
+
+import asyncio
+
+from fragmentapi import ConfigurationError, FragmentClient, UserNotFoundError, WalletError
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+AMOUNT = 10  # TON, integer — 1–1 000 000 000
+
+
+async def main() -> None:
+    client = FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES)
+
+    try:
+        result = await client.topup_ton(USERNAME, amount=AMOUNT, show_sender=True)
+    except UserNotFoundError:
+        print(f"User {USERNAME!r} not found on Fragment.")
+        return
+    except WalletError as e:
+        print(f"Wallet error: {e}")
+        return
+    except ConfigurationError as e:
+        print(f"Invalid parameters: {e}")
+        return
+
+    print("TON topped up")
+    print("   %-14s %s" % ("Username:", result.username))
+    print("   %-14s %s TON" % ("Amount:", result.amount))
+    print("   %-14s %s" % ("Transaction:", result.transaction_id))
+    print("   %-14s %s" % ("Timestamp:", result.timestamp))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())