docs: update documentation to reflect changes from TON to GRAM, including method renaming and new top-up method

docs/client/ads/overview.md

@@ -2,10 +2,10 @@
 
 Ads flow is split into two methods:
 
-- [Top Up TON](topup-ton.md)
+- [Top Up GRAM](topup-gram.md)
 - [Recharge Ads](recharge-ads.md)
 
-Use the first method to send TON to a Telegram user.
+Use the first method to send GRAM (ex TON) to a Telegram user.
 Use the second method to fund your own Telegram Ads account.
 
 ## Common errors

docs/client/ads/topup-gram.md

@@ -0,0 +1,38 @@
+# Top Up GRAM
+
+Use this method to send GRAM (ex TON) to a user's Telegram balance.
+
+## Method
+
+```python
+await client.topup_gram(
+    username: str,
+    amount: int,
+    show_sender: bool = True,
+) -> AdsTopupResult
+```
+
+## Parameters
+
+- `username`: recipient Telegram username — `@username`, `username`, or `https://t.me/username`
+- `amount`: integer from `1` to `1_000_000_000`
+- `show_sender`: controls sender visibility
+
+**`amount` must be an integer in the allowed range.**
+
+## Return
+
+- `AdsTopupResult(transaction_id, username, amount)`
+
+## Typical errors
+
+- `ConfigurationError`: invalid amount
+- `UserNotFoundError`: recipient not found on Fragment
+- `WalletError`: insufficient GRAM (ex TON) balance
+
+## Example
+
+```python
+result: AdsTopupResult = await client.topup_gram("@username", amount=10, show_sender=True)
+print(result.transaction_id)
+```

docs/client/ads/topup-ton.md

@@ -1,32 +0,0 @@
-# Top Up TON
-
-Use this method to send TON to a user's Telegram balance.
-
-## Method
-
-```python
-await client.topup_ton(
-    username: str,
-    amount: int,
-    show_sender: bool = True,
-) -> AdsTopupResult
-```
-
-## Parameters
-
-- `username`: recipient Telegram username
-- `amount`: integer from `1` to `1_000_000_000`
-- `show_sender`: controls sender visibility
-
-**Important:** `amount` must be an integer in the allowed range.
-
-## Return
-
-- `AdsTopupResult(transaction_id, username, amount)`
-
-## Example
-
-```python
-result: AdsTopupResult = await client.topup_ton("@username", amount=10, show_sender=True)
-print(result.transaction_id)
-```

docs/client/overview.md

@@ -19,7 +19,7 @@ Main async methods on `FragmentClient`:
 - `purchase_premium(...)`
 - `giveaway_stars(...)`
 - `giveaway_premium(...)`
-- `topup_ton(...)`
+- `topup_gram(...)`
 - `recharge_ads(...)`
 - `get_wallet()`
 - `get_login_code(...)`

docs/client/premium/giveaway.md

@@ -9,7 +9,7 @@ await client.giveaway_premium(
     channel: str,
     winners: int,
     months: int = 3,
-    payment_method: PaymentMethod = "ton",
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
 ) -> PremiumGiveawayResult
 ```
 
@@ -18,7 +18,7 @@ await client.giveaway_premium(
 - `channel`: accepts `@channel`, `channel`, or `https://t.me/channel`
 - `winners`: integer from `1` to `24_000`
 - `months`: one of `3`, `6`, `12`
-- `payment_method`: `"ton"` or `"usdt_ton"`
+- `payment_method`: `PaymentMethod.GRAM` (default), `PaymentMethod.USDT_GRAM`, or any other `PaymentMethod` value
 
 **`winners` must be a positive integer, and large values can increase total cost significantly.**
 

docs/client/premium/purchase.md

@@ -9,7 +9,7 @@ await client.purchase_premium(
     username: str,
     months: int,
     show_sender: bool = True,
-    payment_method: PaymentMethod = "ton",
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
 ) -> PremiumResult
 ```
 
@@ -18,7 +18,7 @@ await client.purchase_premium(
 - `username`: accepts `@username`, `username`, or `https://t.me/username`
 - `months`: one of `3`, `6`, `12`
 - `show_sender`: controls sender visibility on recipient side
-- `payment_method`: `"ton"` or `"usdt_ton"`
+- `payment_method`: `PaymentMethod.GRAM` (default), `PaymentMethod.USDT_GRAM`, or any other `PaymentMethod` value
 
 **`months` only supports `3`, `6`, or `12`.**
 
@@ -36,6 +36,6 @@ await client.purchase_premium(
 ## Example
 
 ```python
-result: PremiumResult = await client.purchase_premium("@username", months=6, payment_method="ton")
+result: PremiumResult = await client.purchase_premium("@username", months=6, payment_method=PaymentMethod.GRAM)
 print(result.transaction_id)
 ```

docs/client/stars/giveaway.md

@@ -9,16 +9,16 @@ await client.giveaway_stars(
     channel: str,
     winners: int,
     amount: int,
-    payment_method: PaymentMethod = "ton",
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
 ) -> StarsGiveawayResult
 ```
 
 ## Parameters
 
 - `channel`: accepts `@channel`, `channel`, or `https://t.me/channel`
-- `winners`: integer from `1` to `5`
+- `winners`: integer from `1` to `15`
 - `amount`: integer from `500` to `1_000_000` (per winner)
-- `payment_method`: `"ton"` or `"usdt_ton"`
+- `payment_method`: `PaymentMethod.GRAM` (default), `PaymentMethod.USDT_GRAM`, or any other `PaymentMethod` value
 
 **Each winner receives the full `amount` value.**
 

docs/client/stars/purchase.md

@@ -9,18 +9,18 @@ await client.purchase_stars(
     username: str,
     amount: int,
     show_sender: bool = True,
-    payment_method: PaymentMethod = "ton",
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
 ) -> StarsResult
 ```
 
 ## Parameters
 
 - `username`: accepts `@username`, `username`, or `https://t.me/username`
-- `amount`: integer from `50` to `1_000_000`
+- `amount`: integer from `50` to `10_000_000`
 - `show_sender`: controls sender visibility on recipient side
-- `payment_method`: `"ton"` or `"usdt_ton"`
+- `payment_method`: `PaymentMethod.GRAM` (default), `PaymentMethod.USDT_GRAM`, or any other `PaymentMethod` value
 
-**Amount must be between `50` and `1_000_000`.**
+**Amount must be between `50` and `10_000_000`.**
 
 ## Return
 
@@ -36,6 +36,6 @@ await client.purchase_stars(
 ## Example
 
 ```python
-result: StarsResult = await client.purchase_stars("@username", amount=500, payment_method="ton")
+result: StarsResult = await client.purchase_stars("@username", amount=500, payment_method=PaymentMethod.GRAM)
 print(result.amount)
 ```