FOSS/FragmentAPI
0
0
Fork 0
mirror of https://github.com/bohd4nx/FragmentAPI.git synced 2026-07-25 14:24:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure and enhance documentation for Ads and Anonymous Numbers features

Browse Source
This commit is contained in:
bohd4nx
2026-05-21 17:06:28 +03:00
parent fb31bad450
commit 392d8f5587
14 changed files with 167 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+4 -3
View File
@@ -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
docs/SUMMARY.md
+10 -3
View File
@@ -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)
docs/client/ads.md
-55
View File
@@ -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)
docs/client/ads/overview.md
+16
View File
@@ -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`
docs/client/ads/recharge-ads.md
+23
View File
@@ -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)`
docs/client/ads/topup-ton.md
+25
View File
@@ -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)`
docs/client/anonymous-numbers.md
-45
View File
@@ -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`.**
docs/client/anonymous-numbers/get-login-code.md
+19
View File
@@ -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`
docs/client/anonymous-numbers/overview.md
+16
View File
@@ -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.**
docs/client/anonymous-numbers/terminate-sessions.md
+18
View File
@@ -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`
docs/client/anonymous-numbers/toggle-login-codes.md
+18
View File
@@ -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`
docs/client/overview.md
+3 -2
View File
@@ -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.**
docs/client/raw-call.md
+10
View File
@@ -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,
docs/getting-started/quickstart.md
+5 -5
View File
@@ -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)