From 392d8f558727d481e4e889bc176e8f5fc2fd9ce8 Mon Sep 17 00:00:00 2001 From: bohd4nx Date: Thu, 21 May 2026 17:06:28 +0300 Subject: [PATCH] docs: restructure and enhance documentation for Ads and Anonymous Numbers features --- docs/README.md | 7 ++- docs/SUMMARY.md | 13 ++++- docs/client/ads.md | 55 ------------------- docs/client/ads/overview.md | 16 ++++++ docs/client/ads/recharge-ads.md | 23 ++++++++ docs/client/ads/topup-ton.md | 25 +++++++++ docs/client/anonymous-numbers.md | 45 --------------- .../anonymous-numbers/get-login-code.md | 19 +++++++ docs/client/anonymous-numbers/overview.md | 16 ++++++ .../anonymous-numbers/terminate-sessions.md | 18 ++++++ .../anonymous-numbers/toggle-login-codes.md | 18 ++++++ docs/client/overview.md | 5 +- docs/client/raw-call.md | 10 ++++ docs/getting-started/quickstart.md | 10 ++-- 14 files changed, 167 insertions(+), 113 deletions(-) delete mode 100644 docs/client/ads.md create mode 100644 docs/client/ads/overview.md create mode 100644 docs/client/ads/recharge-ads.md create mode 100644 docs/client/ads/topup-ton.md delete mode 100644 docs/client/anonymous-numbers.md create mode 100644 docs/client/anonymous-numbers/get-login-code.md create mode 100644 docs/client/anonymous-numbers/overview.md create mode 100644 docs/client/anonymous-numbers/terminate-sessions.md create mode 100644 docs/client/anonymous-numbers/toggle-login-codes.md diff --git a/docs/README.md b/docs/README.md index 06d44df..f1ee60c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# pyfragment Documentation +# Overview `pyfragment` is an async Python client for [Fragment](https://fragment.com). @@ -30,8 +30,9 @@ If you are integrating Fragment into a bot or backend, this docs set is meant to - Stars: [Purchase](client/stars/purchase.md), [Giveaway](client/stars/giveaway.md) - Premium: [Purchase](client/premium/purchase.md), [Giveaway](client/premium/giveaway.md) -- Marketplace: [Overview](client/marketplace/overview.md), Ads: [Ads](client/ads.md) -- Management: [Anonymous Numbers](client/anonymous-numbers.md) +- Marketplace: [Overview](client/marketplace/overview.md), Ads: [Overview](client/ads/overview.md) +- Numbers: [Anonymous Numbers](client/anonymous-numbers/overview.md) +- Utility operations: [Raw API Calls](client/raw-call.md) ## Additional references diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3ff3698..637633c 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,4 +1,4 @@ -- [Start Here](getting-started/installation.md) +- [Overview](README.md) - Setup Guide - [Installation](getting-started/installation.md) - [Library and Configuration](getting-started/configuration.md) @@ -13,13 +13,20 @@ - Premium - [Purchase](client/premium/purchase.md) - [Giveaway](client/premium/giveaway.md) - - [Ads](client/ads.md) - - [Anonymous Numbers](client/anonymous-numbers.md) - Marketplace - [Overview](client/marketplace/overview.md) - [Search Usernames](client/marketplace/search-usernames.md) - [Search Numbers](client/marketplace/search-numbers.md) - [Search Gifts](client/marketplace/search-gifts.md) + - Ads + - [Overview](client/ads/overview.md) + - [Top Up TON](client/ads/topup-ton.md) + - [Recharge Ads](client/ads/recharge-ads.md) + - Anonymous Numbers + - [Overview](client/anonymous-numbers/overview.md) + - [Get Login Code](client/anonymous-numbers/get-login-code.md) + - [Toggle Login Codes](client/anonymous-numbers/toggle-login-codes.md) + - [Terminate Sessions](client/anonymous-numbers/terminate-sessions.md) - [Raw API Calls](client/raw-call.md) - Reference - [Result Models](reference/models.md) diff --git a/docs/client/ads.md b/docs/client/ads.md deleted file mode 100644 index cf951a2..0000000 --- a/docs/client/ads.md +++ /dev/null @@ -1,55 +0,0 @@ -# Ads - -Ads methods cover two different actions: - -- sending TON to a user, -- recharging your own Telegram Ads account. - -## topup_ton - -```python -await client.topup_ton( - username: str, - amount: int, - show_sender: bool = True, -) -> AdsTopupResult -``` - -Rules: - -- `username`: recipient Telegram username -- `amount`: integer from `1` to `1_000_000_000` -- `show_sender`: sender visibility - -**Important:** `amount` must be an integer in allowed range. - -## recharge_ads - -```python -await client.recharge_ads( - account: str, - amount: int, -) -> AdsRechargeResult -``` - -Rules: - -- `account`: channel/bot username linked to your ads account -- `amount`: integer from `1` to `1_000_000_000` - -## Returns - -- `AdsTopupResult(transaction_id, username, amount)` -- `AdsRechargeResult(transaction_id, amount)` - -## Common errors - -- `ConfigurationError` -- `UserNotFoundError` (topup recipient) -- `WalletError` -- `VerificationError` - -## Related flows - -- [Stars Purchase](stars/purchase.md) -- [Premium Purchase](premium/purchase.md) diff --git a/docs/client/ads/overview.md b/docs/client/ads/overview.md new file mode 100644 index 0000000..a6659da --- /dev/null +++ b/docs/client/ads/overview.md @@ -0,0 +1,16 @@ +# Ads Overview + +Ads flow is split into two methods: + +- [Top Up TON](topup-ton.md) +- [Recharge Ads](recharge-ads.md) + +Use the first method to send TON to a Telegram user. +Use the second method to fund your own Telegram Ads account. + +## Common errors + +- `ConfigurationError` +- `UserNotFoundError` (for recipient/account issues) +- `WalletError` +- `VerificationError` diff --git a/docs/client/ads/recharge-ads.md b/docs/client/ads/recharge-ads.md new file mode 100644 index 0000000..e86c07c --- /dev/null +++ b/docs/client/ads/recharge-ads.md @@ -0,0 +1,23 @@ +# Recharge Ads + +Use this method to add funds to your Telegram Ads account. + +## Method + +```python +await client.recharge_ads( + account: str, + amount: int, +) -> AdsRechargeResult +``` + +## Parameters + +- `account`: channel or bot username linked to your ads account +- `amount`: integer from `1` to `1_000_000_000` + +**Important:** `amount` must be an integer in the allowed range. + +## Return + +- `AdsRechargeResult(transaction_id, amount)` diff --git a/docs/client/ads/topup-ton.md b/docs/client/ads/topup-ton.md new file mode 100644 index 0000000..aebdfd3 --- /dev/null +++ b/docs/client/ads/topup-ton.md @@ -0,0 +1,25 @@ +# 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)` diff --git a/docs/client/anonymous-numbers.md b/docs/client/anonymous-numbers.md deleted file mode 100644 index 465ad27..0000000 --- a/docs/client/anonymous-numbers.md +++ /dev/null @@ -1,45 +0,0 @@ -# Anonymous Numbers - -These methods help you manage login behavior and active sessions for anonymous numbers owned by your current account. - -## get_login_code - -```python -await client.get_login_code(number: str) -> LoginCodeResult -``` - -Returns: - -- `number` -- `code` (`None` if no pending code) -- `active_sessions` - -## toggle_login_codes - -```python -await client.toggle_login_codes(number: str, can_receive: bool) -> None -``` - -Use `can_receive=True` to allow incoming login codes, or `False` to block them. - -## terminate_sessions - -```python -await client.terminate_sessions(number: str) -> TerminateSessionsResult -``` - -Returns: - -- `number` -- `message` - -## Common errors - -- `AnonymousNumberError.NOT_OWNED` -- `AnonymousNumberError.TERMINATE_FAILED` - -## Practical note - -These methods operate only on numbers owned by the currently authorized Fragment account. - -**If a number is not yours, requests will fail with `AnonymousNumberError`.** diff --git a/docs/client/anonymous-numbers/get-login-code.md b/docs/client/anonymous-numbers/get-login-code.md new file mode 100644 index 0000000..9e20770 --- /dev/null +++ b/docs/client/anonymous-numbers/get-login-code.md @@ -0,0 +1,19 @@ +# Get Login Code + +Use this method to fetch a pending login code for an anonymous number. + +## Method + +```python +await client.get_login_code(number: str) -> LoginCodeResult +``` + +## Parameters + +- `number`: anonymous number (with or without leading `+`) + +## Return + +- `number` +- `code` (`None` if no pending code) +- `active_sessions` diff --git a/docs/client/anonymous-numbers/overview.md b/docs/client/anonymous-numbers/overview.md new file mode 100644 index 0000000..f6434d8 --- /dev/null +++ b/docs/client/anonymous-numbers/overview.md @@ -0,0 +1,16 @@ +# Anonymous Numbers Overview + +These methods help you manage login behavior and active sessions for anonymous numbers owned by your account. + +Available methods: + +- [Get Login Code](get-login-code.md) +- [Toggle Login Codes](toggle-login-codes.md) +- [Terminate Sessions](terminate-sessions.md) + +## Common errors + +- `AnonymousNumberError.NOT_OWNED` +- `AnonymousNumberError.TERMINATE_FAILED` + +**If a number is not owned by your account, requests will fail.** diff --git a/docs/client/anonymous-numbers/terminate-sessions.md b/docs/client/anonymous-numbers/terminate-sessions.md new file mode 100644 index 0000000..a803e67 --- /dev/null +++ b/docs/client/anonymous-numbers/terminate-sessions.md @@ -0,0 +1,18 @@ +# Terminate Sessions + +Use this method to terminate active sessions for an anonymous number. + +## Method + +```python +await client.terminate_sessions(number: str) -> TerminateSessionsResult +``` + +## Parameters + +- `number`: anonymous number (with or without leading `+`) + +## Return + +- `number` +- `message` diff --git a/docs/client/anonymous-numbers/toggle-login-codes.md b/docs/client/anonymous-numbers/toggle-login-codes.md new file mode 100644 index 0000000..2ecba8e --- /dev/null +++ b/docs/client/anonymous-numbers/toggle-login-codes.md @@ -0,0 +1,18 @@ +# Toggle Login Codes + +Use this method to allow or block login code delivery. + +## Method + +```python +await client.toggle_login_codes(number: str, can_receive: bool) -> None +``` + +## Parameters + +- `number`: anonymous number (with or without leading `+`) +- `can_receive`: `True` to allow codes, `False` to block codes + +## Return + +- `None` diff --git a/docs/client/overview.md b/docs/client/overview.md index 58aba74..9fbeac2 100644 --- a/docs/client/overview.md +++ b/docs/client/overview.md @@ -36,7 +36,8 @@ All methods are async and should be used inside `async with FragmentClient(...) - Stars: [Purchase](stars/purchase.md), [Giveaway](stars/giveaway.md) - Premium: [Purchase](premium/purchase.md), [Giveaway](premium/giveaway.md) -- Ads: [Ads operations](ads.md) -- Utility operations: [Anonymous Numbers](anonymous-numbers.md), [Marketplace](marketplace/overview.md), [Raw API Calls](raw-call.md) +- Marketplace: [Overview](marketplace/overview.md), Ads: [Overview](ads/overview.md) +- Numbers: [Anonymous Numbers](anonymous-numbers/overview.md) +- Utility operations: [Raw API Calls](raw-call.md) **If you are new to the library, start with Stars Purchase or Wallet read (`get_wallet`) first.** diff --git a/docs/client/raw-call.md b/docs/client/raw-call.md index 0159ac0..44d89d5 100644 --- a/docs/client/raw-call.md +++ b/docs/client/raw-call.md @@ -21,6 +21,16 @@ await client.call( ) -> dict[str, Any] ``` +## Parameters + +- `method`: Fragment API method name +- `data`: optional request payload as dictionary +- `page_url`: page URL used for referer/hash context (defaults to `https://fragment.com`) + +## Return + +- `dict[str, Any]`: raw Fragment API response + Use this carefully: - request/response shape is Fragment-defined, diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 9bebcb1..fa8d816 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -29,8 +29,8 @@ If this script returns wallet data, your setup is healthy. Then move to feature pages: -- Stars: [Purchase](../client/stars/purchase.md), [Giveaway](../client/stars/giveaway.md) -- Premium: [Purchase](../client/premium/purchase.md), [Giveaway](../client/premium/giveaway.md) -- [Ads](../client/ads.md) -- [Anonymous Numbers](../client/anonymous-numbers.md) -- [Marketplace](../client/marketplace/overview.md) +- Stars: [Purchase](client/stars/purchase.md), [Giveaway](client/stars/giveaway.md) +- Premium: [Purchase](client/premium/purchase.md), [Giveaway](client/premium/giveaway.md) +- Marketplace: [Overview](client/marketplace/overview.md), Ads: [Overview](client/ads/overview.md) +- Numbers: [Anonymous Numbers](client/anonymous-numbers/overview.md) +- Utility operations: [Raw API Calls](client/raw-call.md)