feat: update payment method handling and validation across giveaway examples; adjust limits for winners and amounts

examples/purchase/run_premium_giveaway.py

@@ -3,13 +3,13 @@ Example: run a Telegram Premium giveaway for a channel.
 
 winners must be an integer between 1 and 24 000.
 months (Premium duration per winner) must be 3, 6, or 12.
-payment_method can be "ton" or "usdt_ton".
 Channel can be "@channel", "channel", or "https://t.me/channel".
 """
 
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.models.enums import PaymentMethod
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
@@ -28,7 +28,7 @@ COOKIES = {
 CHANNEL = "https://t.me/channel"
 WINNERS = 10  # 1–24 000
 MONTHS = 3  # 3, 6 or 12
-PAYMENT_METHOD = "ton"  # "ton" or "usdt_ton"
+PAYMENT_METHOD = PaymentMethod.TON  # PaymentMethod.TON or PaymentMethod.USDT_TON
 
 
 async def main() -> None:

examples/purchase/run_stars_giveaway.py

@@ -1,15 +1,15 @@
 """
 Example: run a Telegram Stars giveaway for a channel.
 
-winners must be an integer between 1 and 5.
+winners must be an integer between 1 and 15.
 amount (stars per winner) must be an integer between 500 and 1 000 000.
-payment_method can be "ton" or "usdt_ton".
 Channel can be "@channel", "channel", or "https://t.me/channel".
 """
 
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.models.enums import PaymentMethod
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
@@ -26,9 +26,9 @@ COOKIES = {
 }
 
 CHANNEL = "https://t.me/channel"
-WINNERS = 3  # 1–5
+WINNERS = 3  # 1–15
 AMOUNT = 1000  # 500–1 000 000 stars per winner
-PAYMENT_METHOD = "usdt_ton"  # "ton" or "usdt_ton"
+PAYMENT_METHOD = PaymentMethod.USDT_TON  # PaymentMethod.TON or PaymentMethod.USDT_TON
 
 
 async def main() -> None:

examples/purchase/send_premium.py

@@ -3,13 +3,13 @@ Example: purchase Telegram Premium for a user.
 
 Supported durations: 3, 6, or 12 months.
 Set show_sender=False to send anonymously.
-payment_method can be "ton" or "usdt_ton".
 Username can be "@username", "username", or "https://t.me/username".
 """
 
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.models.enums import PaymentMethod
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
@@ -27,7 +27,7 @@ COOKIES = {
 
 USERNAME = "https://t.me/username"
 MONTHS = 3  # 3, 6 or 12
-PAYMENT_METHOD = "ton"  # "ton" or "usdt_ton"
+PAYMENT_METHOD = PaymentMethod.TON  # PaymentMethod.TON or PaymentMethod.USDT_TON
 
 
 async def main() -> None:

examples/purchase/send_stars.py

@@ -1,15 +1,15 @@
 """
 Example: purchase Telegram Stars for a user.
 
-Amount must be an integer between 50 and 1 000 000.
+Amount must be an integer between 50 and 10 000 000.
 Set show_sender=False to send anonymously.
-payment_method can be "ton" or "usdt_ton".
 Username can be "@username", "username", or "https://t.me/username".
 """
 
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.models.enums import PaymentMethod
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
@@ -26,8 +26,8 @@ COOKIES = {
 }
 
 USERNAME = "https://t.me/username"
-AMOUNT = 500  # 50–1 000 000 stars
+AMOUNT = 500  # 50–10 000 000 stars
-PAYMENT_METHOD = "usdt_ton"  # "ton" or "usdt_ton"
+PAYMENT_METHOD = PaymentMethod.USDT_TON  # PaymentMethod.TON or PaymentMethod.USDT_TON
 
 
 async def main() -> None:

pyfragment/client.py

@@ -166,7 +166,7 @@ class FragmentClient:
 
         Args:
             username: Recipient identifier — ``@username``, ``username``, or ``https://t.me/username``.
-            amount: Number of stars — integer from ``50`` to ``1 000 000``.
+            amount: Number of stars — integer from ``50`` to ``10 000 000``.
             show_sender: Show your name as the gift sender. Defaults to ``True``.
             payment_method: Payment currency — ``"ton"`` (default) or ``"usdt_ton"``.
 
@@ -222,7 +222,7 @@ class FragmentClient:
 
         Args:
             channel: Channel identifier — ``@channel``, ``channel``, or ``https://t.me/channel``.
-            winners: Number of winners — integer from ``1`` to ``5``.
+            winners: Number of winners — integer from ``1`` to ``15``.
             amount: Stars each winner receives — integer from ``500`` to ``1 000 000``.
             payment_method: Payment currency — ``"ton"`` (default) or ``"usdt_ton"``.
 
@@ -243,7 +243,7 @@ class FragmentClient:
 
         Args:
             channel: Channel identifier — ``@channel``, ``channel``, or ``https://t.me/channel``.
-            winners: Number of winners — positive integer.
+            winners: Number of winners — integer from ``1`` to ``24 000``.
             months: Premium duration per winner — ``3``, ``6``, or ``12``. Defaults to ``3``.
             payment_method: Payment currency — ``"ton"`` (default) or ``"usdt_ton"``.
 

pyfragment/core/constants/ton.py

@@ -7,7 +7,7 @@ USDT_TON_MASTER_ADDRESS: str = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
 DEVICE_INFO: dict[str, Any] = {
     "platform": "iphone",
     "appName": "Tonkeeper",
-    "appVersion": "26.04.0",
+    "appVersion": "26.05.0",
     "maxProtocolVersion": 2,
     "features": [
         "SendTransaction",

pyfragment/exceptions.py

@@ -11,6 +11,8 @@ from pyfragment.core.constants.limits import (
     STARS_PURCHASE_MIN,
     STARS_WINNERS_MAX,
     STARS_WINNERS_MIN,
+    TON_TOPUP_MAX,
+    TON_TOPUP_MIN,
     TONAPI_KEY_MIN_LENGTH,
 )
 
@@ -37,7 +39,7 @@ class ConfigurationError(ClientError):
     INVALID_STARS_AMOUNT = (
         f"Invalid Stars amount: must be an integer between {STARS_PURCHASE_MIN:,} and {STARS_PURCHASE_MAX:,}."
     )
-    INVALID_TON_AMOUNT = "Invalid TON amount: must be an integer between 1 and 1,000,000,000."
+    INVALID_TON_AMOUNT = f"Invalid TON amount: must be an integer between {TON_TOPUP_MIN:,} and {TON_TOPUP_MAX:,}."
     INVALID_USERNAME = (
         "Invalid username '{username}'. "
         "Must be 5-32 characters and contain only letters (A-Z, a-z), digits (0-9), or underscores (_)."