docs: add examples to various API methods for better clarity

docs/README.md

@@ -40,3 +40,9 @@ If you are integrating Fragment into a bot or backend, this docs set is meant to
 - [Result Models](reference/models.md)
 - [Literal Types](reference/literals.md)
 - [Troubleshooting](advanced/troubleshooting.md)
+
+## Live examples
+
+**Up-to-date runnable examples live in the main repository:**
+
+- https://github.com/bohd4nx/pyfragment/tree/master/examples

docs/client/ads/recharge-ads.md

@@ -21,3 +21,10 @@ await client.recharge_ads(
 ## Return
 
 - `AdsRechargeResult(transaction_id, amount)`
+
+## Example
+
+```python
+result: AdsRechargeResult = await client.recharge_ads("@mychannel", amount=50)
+print(result.transaction_id)
+```

docs/client/ads/topup-ton.md

@@ -23,3 +23,10 @@ await client.topup_ton(
 ## 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/anonymous-numbers/get-login-code.md

@@ -17,3 +17,10 @@ await client.get_login_code(number: str) -> LoginCodeResult
 - `number`
 - `code` (`None` if no pending code)
 - `active_sessions`
+
+## Example
+
+```python
+result: LoginCodeResult = await client.get_login_code("+1234567890")
+print(result.code)
+```

docs/client/anonymous-numbers/terminate-sessions.md

@@ -16,3 +16,10 @@ await client.terminate_sessions(number: str) -> TerminateSessionsResult
 
 - `number`
 - `message`
+
+## Example
+
+```python
+result: TerminateSessionsResult = await client.terminate_sessions("+1234567890")
+print(result.message)
+```

docs/client/anonymous-numbers/toggle-login-codes.md

@@ -16,3 +16,9 @@ await client.toggle_login_codes(number: str, can_receive: bool) -> None
 ## Return
 
 - `None`
+
+## Example
+
+```python
+await client.toggle_login_codes("+1234567890", can_receive=False)
+```

docs/client/marketplace/search-gifts.md

@@ -73,3 +73,15 @@ In requests, each trait is sent as `attr[trait]` with a list of values.
 ## Pagination
 
 If `next_offset` is not `None`, pass it back as `offset` to load the next page.
+
+## Example
+
+```python
+result: GiftsResult = await client.search_gifts(
+    query="",
+    collection="plushpepe",
+    sort="price_desc",
+    filter="auction",
+)
+print(len(result.items), result.next_offset)
+```

docs/client/marketplace/search-numbers.md

@@ -52,3 +52,10 @@ Common values accepted by Fragment:
 If `next_offset_id` is not `None`, pass it back as `offset_id` to load the next page.
 
 Keep requesting pages until `next_offset_id` becomes `None`.
+
+## Example
+
+```python
+result: NumbersResult = await client.search_numbers("888", sort="price_asc", filter="sale")
+print(len(result.items), result.next_offset_id)
+```

docs/client/marketplace/search-usernames.md

@@ -52,3 +52,10 @@ Common values accepted by Fragment:
 If `next_offset_id` is not `None`, pass it back as `offset_id` to load the next page.
 
 This is cursor pagination, so do not try to calculate offsets manually.
+
+## Example
+
+```python
+result: UsernamesResult = await client.search_usernames("durov", sort="price_desc", filter="auction")
+print(len(result.items), result.next_offset_id)
+```

docs/client/premium/giveaway.md

@@ -32,3 +32,10 @@ await client.giveaway_premium(
 - `UserNotFoundError`
 - `WalletError`
 - `VerificationError`
+
+## Example
+
+```python
+result: PremiumGiveawayResult = await client.giveaway_premium("@channel", winners=100, months=3)
+print(result.amount)
+```

docs/client/premium/purchase.md

@@ -32,3 +32,10 @@ await client.purchase_premium(
 - `UserNotFoundError`
 - `WalletError`
 - `VerificationError`
+
+## Example
+
+```python
+result: PremiumResult = await client.purchase_premium("@username", months=6, payment_method="ton")
+print(result.transaction_id)
+```

docs/client/stars/giveaway.md

@@ -32,3 +32,10 @@ await client.giveaway_stars(
 - `UserNotFoundError`
 - `WalletError`
 - `VerificationError`
+
+## Example
+
+```python
+result: StarsGiveawayResult = await client.giveaway_stars("@channel", winners=3, amount=1000)
+print(result.transaction_id)
+```

docs/client/stars/purchase.md

@@ -32,3 +32,10 @@ await client.purchase_stars(
 - `UserNotFoundError`: target user not found
 - `WalletError`: insufficient balance or wallet-side issue
 - `VerificationError`: verification/KYC required for operation
+
+## Example
+
+```python
+result: StarsResult = await client.purchase_stars("@username", amount=500, payment_method="ton")
+print(result.amount)
+```