chore: update examples and README for improved clarity and consistency; streamline print statements and descriptions

README.md

@@ -4,7 +4,7 @@
   <h1 style="margin-top: 24px;">Fragment API</h1>
 
   <p style="font-size: 18px; margin-bottom: 24px;">
-    <b>Async Python client for the Fragment.com API — buy Telegram Stars and Premium, run giveaways, top up TON, Ads balance, manage anonymous numbers, and search the marketplace for usernames, numbers, and gifts.</b>
+    <b>Async Python client for the Fragment API — a unified toolkit to manage Telegram assets: purchase Stars and Premium, top up TON and Ads balances, run giveaways, manage anonymous numbers, and explore the marketplace for usernames, numbers, and gifts.</b>
   </p>
 
 [![PyPI version](https://img.shields.io/pypi/v/pyfragment?style=flat&color=blue)](https://pypi.org/project/pyfragment/)

examples/auctions/search_gifts.py

@@ -8,6 +8,7 @@ Use next_offset for pagination.
 """
 
 import asyncio
+import json
 
 from pyfragment import FragmentClient, GiftsResult
 
@@ -28,16 +29,10 @@ FILTER = ""  # "", "auction", "sale", "sold" — or omit
 
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
-        result: GiftsResult = await client.search_gifts(
+        result: GiftsResult = await client.search_gifts(QUERY, collection=COLLECTION, sort=SORT, filter=FILTER)
-            QUERY, collection=COLLECTION, sort=SORT, filter=FILTER
-        )
 
         print(f"Found {len(result.items)} result(s):")
-        for item in result.items:
+        print(json.dumps(result.items, indent=2))
-            price = f"{item['price']} TON" if item["price"] else "n/a"
-            print(
-                f"  {item['name']:30s}  {item['status'] or '':15s}  {price:12s}  {item['date'] or '—'}"
-            )
 
         if result.next_offset:
             print(f"\nMore results available — next page offset: {result.next_offset}")

examples/auctions/search_numbers.py

@@ -7,6 +7,7 @@ Use next_offset_id for pagination.
 """
 
 import asyncio
+import json
 
 from pyfragment import FragmentClient, NumbersResult
 
@@ -26,21 +27,13 @@ FILTER = ""  # "", "auction", "sale", "sold" — or omit
 
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
-        result: NumbersResult = await client.search_numbers(
+        result: NumbersResult = await client.search_numbers(QUERY, sort=SORT, filter=FILTER)
-            QUERY, sort=SORT, filter=FILTER
-        )
 
         print(f"Found {len(result.items)} result(s):")
-        for item in result.items:
+        print(json.dumps(result.items, indent=2))
-            price = f"{item['price']} TON" if item["price"] else "n/a"
-            print(
-                f"  {item['name']:20s}  {item['status'] or '':15s}  {price:10s}  {item['date'] or '—'}"
-            )
 
         if result.next_offset_id:
-            print(
+            print(f"\nMore results available — next page offset: {result.next_offset_id}")
-                f"\nMore results available — next page offset: {result.next_offset_id}"
-            )
 
 
 if __name__ == "__main__":

examples/auctions/search_usernames.py

@@ -7,6 +7,7 @@ Use next_offset_id for pagination.
 """
 
 import asyncio
+import json
 
 from pyfragment import FragmentClient, UsernamesResult
 
@@ -26,21 +27,13 @@ FILTER = "auction"  # "", "auction", "sale", "sold" — or omit
 
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
-        result: UsernamesResult = await client.search_usernames(
+        result: UsernamesResult = await client.search_usernames(QUERY, sort=SORT, filter=FILTER)
-            QUERY, sort=SORT, filter=FILTER
-        )
 
         print(f"Found {len(result.items)} result(s):")
-        for item in result.items:
+        print(json.dumps(result.items, indent=2))
-            price = f"{item['price']} TON" if item["price"] else "n/a"
-            print(
-                f"  {item['name']:20s}  {item['status'] or '':15s}  {price:10s}  {item['date'] or '—'}"
-            )
 
         if result.next_offset_id:
-            print(
+            print(f"\nMore results available — next page offset: {result.next_offset_id}")
-                f"\nMore results available — next page offset: {result.next_offset_id}"
-            )
 
 
 if __name__ == "__main__":

examples/numbers/manage_number.py

@@ -27,21 +27,14 @@ async def main() -> None:
         # Fetch the latest login code
         result = await client.get_login_code(NUMBER)
         if result.code:
-            print(
+            print(f"Login code for {result.number}: {result.code} ({result.active_sessions} active session(s))")
-                f"Login code for {result.number}: {result.code} ({result.active_sessions} active session(s))"
-            )
         else:
-            print(
+            print(f"No pending login code for {result.number} ({result.active_sessions} active session(s))")
-                f"No pending login code for {result.number} ({result.active_sessions} active session(s))"
-            )
 
         # Terminate all active sessions
         try:
             terminated = await client.terminate_sessions(NUMBER)
-            print(
+            print(f"Sessions terminated for {terminated.number}" + (f": {terminated.message}" if terminated.message else ""))
-                f"Sessions terminated for {terminated.number}"
-                + (f": {terminated.message}" if terminated.message else "")
-            )
         except AnonymousNumberError as e:
             print(f"Could not terminate sessions: {e}")
 

examples/purchase/recharge_ads_balance.py

@@ -30,9 +30,7 @@ AMOUNT = 10  # 1–1 000 000 000 TON
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
         try:
-            result: AdsRechargeResult = await client.recharge_ads(
+            result: AdsRechargeResult = await client.recharge_ads(ACCOUNT, amount=AMOUNT)
-                ACCOUNT, amount=AMOUNT
-            )
         except WalletError as e:
             print(f"Wallet error — insufficient balance or misconfiguration: {e}")
             return
@@ -40,9 +38,7 @@ async def main() -> None:
             print(f"Invalid argument: {e}")
             return
 
-    print(
+    print(f"{result.amount} TON recharged to Ads account {ACCOUNT} | tx: {result.transaction_id}")
-        f"{result.amount} TON recharged to Ads account {ACCOUNT} | tx: {result.transaction_id}"
-    )
 
 
 if __name__ == "__main__":

examples/purchase/run_premium_giveaway.py

@@ -26,13 +26,9 @@ MONTHS = 3  # 3, 6 or 12
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
         try:
-            result = await client.giveaway_premium(
+            result = await client.giveaway_premium(CHANNEL, winners=WINNERS, months=MONTHS)
-                CHANNEL, winners=WINNERS, months=MONTHS
-            )
         except UserNotFoundError:
-            print(
+            print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
-                f"Channel {CHANNEL} was not found on fragment.com — check the username and try again."
-            )
             return
         except ConfigurationError as e:
             print(f"Invalid argument: {e}")

examples/purchase/run_stars_giveaway.py

@@ -26,13 +26,9 @@ AMOUNT = 1000  # 500–1 000 000 stars per winner
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
         try:
-            result = await client.giveaway_stars(
+            result = await client.giveaway_stars(CHANNEL, winners=WINNERS, amount=AMOUNT)
-                CHANNEL, winners=WINNERS, amount=AMOUNT
-            )
         except UserNotFoundError:
-            print(
+            print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
-                f"Channel {CHANNEL} was not found on fragment.com — check the username and try again."
-            )
             return
         except ConfigurationError as e:
             print(f"Invalid argument: {e}")

examples/purchase/send_premium.py

@@ -25,21 +25,15 @@ MONTHS = 3  # 3, 6 or 12
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
         try:
-            result = await client.purchase_premium(
+            result = await client.purchase_premium(USERNAME, months=MONTHS, show_sender=True)
-                USERNAME, months=MONTHS, show_sender=True
-            )
         except UserNotFoundError:
-            print(
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
-                f"User {USERNAME} was not found on fragment.com — check the username and try again."
-            )
             return
         except ConfigurationError as e:
             print(f"Invalid argument: {e}")
             return
 
-    print(
+    print(f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}")
-        f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}"
-    )
 
 
 if __name__ == "__main__":

examples/purchase/send_stars.py

@@ -25,21 +25,15 @@ AMOUNT = 500  # 50–1 000 000 stars
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
         try:
-            result = await client.purchase_stars(
+            result = await client.purchase_stars(USERNAME, amount=AMOUNT, show_sender=True)
-                USERNAME, amount=AMOUNT, show_sender=True
-            )
         except UserNotFoundError:
-            print(
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
-                f"User {USERNAME} was not found on fragment.com — check the username and try again."
-            )
             return
         except ConfigurationError as e:
             print(f"Invalid argument: {e}")
             return
 
-    print(
+    print(f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}")
-        f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}"
-    )
 
 
 if __name__ == "__main__":

examples/purchase/topup_ton_balance.py

@@ -34,9 +34,7 @@ async def main() -> None:
         try:
             result = await client.topup_ton(USERNAME, amount=AMOUNT, show_sender=True)
         except UserNotFoundError:
-            print(
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
-                f"User {USERNAME} was not found on fragment.com — check the username and try again."
-            )
             return
         except WalletError as e:
             print(f"Wallet error — insufficient balance or misconfiguration: {e}")
@@ -45,9 +43,7 @@ async def main() -> None:
             print(f"Invalid argument: {e}")
             return
 
-    print(
+    print(f"{result.amount} TON successfully topped up for {result.username} | tx: {result.transaction_id}")
-        f"{result.amount} TON successfully topped up for {result.username} | tx: {result.transaction_id}"
-    )
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "pyfragment"
 version = "2026.0.2"
-description = "Async Python client for the Fragment.com API — buy Telegram Stars and Premium, run giveaways, top up TON Ads balance, and manage anonymous numbers."
+description = "Async Python client for the Fragment API — a unified toolkit to manage Telegram assets: purchase Stars and Premium, top up TON and Ads balances, run giveaways, manage anonymous numbers, and explore the marketplace for usernames, numbers, and gifts."
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.12"