funstat-api 0.1.0__tar.gz → 0.1.2__tar.gz

funstat_api-0.1.2/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

{funstat_api-0.1.0 → funstat_api-0.1.2}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: funstat-api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Sync and async Python client for the Funstat API (Telegram user/group statistics)
 Project-URL: Homepage, https://github.com/chizumeiji/funstat-api
+Project-URL: Documentation, https://chizumeiji.github.io/funstat-api/
 Project-URL: Bug Tracker, https://github.com/chizumeiji/funstat-api/issues
 Author-email: meiji <chizumeiji@gmail.com>
 License: MIT License
@@ -50,6 +51,8 @@ Python client for the [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466) A
 
 Supports both **sync** and **async** usage.
 
+Documentation: https://chizumeiji.github.io/funstat-api/
+
 ## Installation
 
 ```bash

{funstat_api-0.1.0 → funstat_api-0.1.2}/README.md

@@ -4,6 +4,8 @@ Python client for the [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466) A
 
 Supports both **sync** and **async** usage.
 
+Documentation: https://chizumeiji.github.io/funstat-api/
+
 ## Installation
 
 ```bash

funstat_api-0.1.2/README_RU.md

@@ -0,0 +1,82 @@
+# funstat-api
+
+Python-клиент для [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466) API — статистика пользователей и групп Telegram.
+
+Поддерживает **синхронный** и **асинхронный** режимы работы.
+
+## Установка
+
+```bash
+pip install funstat-api
+```
+
+## Быстрый старт
+
+### Синхронно
+
+```python
+from funstat_api import FunstatClient
+
+fs = FunstatClient("your_token")
+
+# Статистика пользователя
+stats = fs.stats("durov")
+print(stats.data.total_msg_count)
+
+# Участники группы
+members = fs.get_group_members("https://t.me/mychat")
+
+# Использование как контекстный менеджер
+with FunstatClient("your_token") as fs:
+    print(fs.ping())
+```
+
+### Асинхронно
+
+```python
+import asyncio
+from funstat_api import AsyncFunstatClient
+
+async def main():
+    async with AsyncFunstatClient("your_token") as fs:
+        stats = await fs.stats("durov")
+        print(stats.data.total_msg_count)
+
+asyncio.run(main())
+```
+
+## Доступные методы
+
+| Метод | Описание |
+|-------|----------|
+| `ping()` | Проверить доступность API и задержку |
+| `get_balance()` | Получить баланс токена |
+| `resolve_username(username)` | Получить информацию по username |
+| `basic_info_by_id(ids)` | Базовая информация по ID пользователя(ей) |
+| `stats_min(user)` | Минимальная статистика пользователя |
+| `stats(user)` | Полная статистика пользователя |
+| `messages_count(user)` | Общее количество сообщений |
+| `groups_count(user)` | Количество групп |
+| `get_messages(user, ...)` | Список сообщений с пагинацией |
+| `get_chats(user)` | Список чатов пользователя |
+| `get_names(user)` | История имён |
+| `get_usernames(user)` | История username'ов |
+| `get_stickers(user)` | Использованные стикерпаки |
+| `get_gifts(user)` | Подарки и их отправители |
+| `common_groups(user)` | Статистика общих групп |
+| `username_usage(username)` | Кто использует или использовал username |
+| `get_group_info(group)` | Информация о группе/канале |
+| `get_group_members(group)` | Участники группы |
+| `search_text(query)` | Поиск сообщений по тексту |
+
+Аргументы `user` и `group` принимают: числовой ID, `@username` или ссылку `https://t.me/...`.
+
+## Зависимости
+
+- `pydantic >= 2.0`
+- `requests >= 2.28` (синхронный клиент)
+- `httpx >= 0.24` (асинхронный клиент)
+
+## Лицензия
+
+MIT

funstat_api-0.1.2/docs/api/async.md

@@ -0,0 +1,57 @@
+# Async Client
+
+```python
+from funstat_api import AsyncFunstatClient
+```
+
+## `AsyncFunstatClient(token)`
+
+Creates an asynchronous client. Uses `httpx` under the hood. All methods must be `await`-ed.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `str` | Your Funstat API token |
+
+---
+
+## Methods
+
+All methods are identical to the [Sync Client](sync.md) but are coroutines — prefix every call with `await`.
+Return types and parameters are the same — refer to [Sync Client](sync.md) for the full reference and [Models](models.md) for response type details.
+
+```python
+async with AsyncFunstatClient("your_token") as fs:
+    stats    = await fs.stats("durov")
+    messages = await fs.get_messages("durov", limit=50)
+    members  = await fs.get_group_members("https://t.me/mychat")
+    usage    = await fs.username_usage("durov")
+```
+
+---
+
+### Parallel requests
+
+Because the client is async, you can fire multiple requests concurrently with `asyncio.gather`:
+
+```python
+import asyncio
+from funstat_api import AsyncFunstatClient
+
+async def main():
+    async with AsyncFunstatClient("your_token") as fs:
+        stats, chats, names = await asyncio.gather(
+            fs.stats("durov"),       # → UserStatsResponse
+            fs.get_chats("durov"),   # → UsrChatInfoResponse
+            fs.get_names("durov"),   # → UserNameInfoResponse
+        )
+
+asyncio.run(main())
+```
+
+---
+
+### close
+
+`async close()`
+
+Closes the underlying `httpx.AsyncClient`. Called automatically when using `async with`.

funstat_api-0.1.2/docs/api/exceptions.md

@@ -0,0 +1,66 @@
+# Exceptions
+
+```python
+from funstat_api import FunstatError, ResolveError, ApiError
+```
+
+---
+
+## `FunstatError`
+
+Base exception for all funstat errors. Catch this to handle any library error:
+
+```python
+from funstat_api import FunstatError
+
+try:
+    result = fs.stats("someone")
+except FunstatError as e:
+    print(f"Something went wrong: {e}")
+```
+
+---
+
+## `ResolveError`
+
+Raised when a username or group cannot be resolved to a numeric ID.
+See [`resolve_username`](sync.md#resolve_usernameusername--resolveduserresponse--none) and [`username_usage`](sync.md#username_usageusername--usernameusageresponse--none) for context.
+
+```python
+from funstat_api import ResolveError
+
+try:
+    result = fs.stats("nonexistent_xyz_404")
+except ResolveError as e:
+    print(f"Not found: {e}")
+```
+
+---
+
+## `ApiError`
+
+Raised when the API returns a non-200 HTTP status code.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `status_code` | `int` | HTTP status code returned by the API |
+| `path` | `str` | API path that was requested |
+
+```python
+from funstat_api import ApiError
+
+try:
+    result = fs.stats("durov")
+except ApiError as e:
+    print(f"HTTP {e.status_code} on {e.path}")
+```
+
+---
+
+## Exception hierarchy
+
+```
+FunstatError
+├── ResolveError   # username/group not found
+└── ApiError       # non-200 HTTP response
+```

funstat_api-0.1.2/docs/api/models.md

@@ -0,0 +1,360 @@
+# Models
+
+All API responses are typed Pydantic v2 models. Import them directly:
+
+```python
+from funstat_api import UserStats, GroupMember, ChatInfo  # etc.
+```
+
+---
+
+## Response wrappers
+
+Every method returns a response wrapper with a consistent shape:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `bool` | Whether the request succeeded |
+| `tech` | [`TechInfo`](#techinfo) | Request cost and balance info |
+| `data` | `... \| None` | The actual payload |
+| `paging` | [`Paging`](#paging)` \| None` | Pagination info (paginated endpoints only) |
+
+---
+
+## TechInfo
+
+```python
+class TechInfo:
+    request_cost: float
+    current_ballance: float
+    request_duration: str
+```
+
+---
+
+## Paging
+
+```python
+class Paging:
+    total: int
+    current_page: int
+    page_size: int
+    total_pages: int
+```
+
+---
+
+## ResolvedUser
+
+```python
+class ResolvedUser:
+    id: int
+    username: str | None
+    first_name: str | None
+    last_name: str | None
+    is_active: bool
+    is_bot: bool
+    has_premium: bool | None
+```
+
+---
+
+## UserStatsMin
+
+```python
+class UserStatsMin:
+    id: int
+    first_name: str | None
+    last_name: str | None
+    is_bot: bool
+    is_active: bool
+    first_msg_date: str | None
+    last_msg_date: str | None
+    total_msg_count: int
+    msg_in_groups_count: int
+    adm_in_groups: int
+    usernames_count: int
+    names_count: int
+    total_groups: int
+```
+
+---
+
+## UserStats
+
+Extends [`UserStatsMin`](#userstatsmin) with additional fields:
+
+```python
+class UserStats(UserStatsMin):
+    is_cyrillic_primary: bool | None
+    lang_code: str | None
+    unique_percent: float | None
+    circle_count: int
+    voice_count: int
+    reply_percent: float
+    media_percent: float
+    link_percent: float
+    favorite_chat: ChatInfo | None
+    media_usage: str | None
+    stars_val: int | None
+    gift_count: int | None
+    about: str | None
+    # ... and more
+```
+
+---
+
+## ChatInfo
+
+```python
+class ChatInfo:
+    id: int
+    title: str
+    is_private: bool
+    username: str | None
+```
+
+---
+
+## ChatInfoExt
+
+Extends [`ChatInfo`](#chatinfo):
+
+```python
+class ChatInfoExt(ChatInfo):
+    is_channel: bool
+    link: str | None
+```
+
+---
+
+## GroupMember
+
+```python
+class GroupMember:
+    id: int
+    username: str | None
+    name: str | None
+    first_name: str | None
+    last_name: str | None
+    is_admin: bool | None
+    is_active: bool
+    today_msg: int
+    has_prem: bool | None
+    has_photo: bool
+    dc_id: int | None
+```
+
+---
+
+## UserMsg
+
+```python
+class UserMsg:
+    date: str
+    message_id: int
+    reply_to_message_id: int | None
+    media_code: int | None
+    media_name: str | None
+    text: str | None
+    group: ChatInfo
+```
+
+---
+
+## UserNameInfo
+
+```python
+class UserNameInfo:
+    name: str
+    date_time: str
+```
+
+---
+
+## UsrChatInfo
+
+```python
+class UsrChatInfo:
+    chat: ChatInfo
+    last_message_id: int
+    messages_count: int
+    last_message: str | None
+    first_message: str | None
+    is_admin: bool
+    is_left: bool
+```
+
+---
+
+## GiftRelationInfo
+
+```python
+class GiftRelationInfo:
+    last_gift_date: str | None
+    from_user_id: int
+    from_first_name: str | None
+    from_last_name: str | None
+    from_main_username: str | None
+    from_is_active: bool
+    to_user_id: int
+    to_first_name: str | None
+    to_last_name: str | None
+    to_main_username: str | None
+    to_is_active: bool
+```
+
+---
+
+## StickerInfo
+
+```python
+class StickerInfo:
+    sticker_set_id: int
+    last_seen: str
+    min_seen: str
+    resolved: str | None
+    title: str | None
+    short_name: str | None
+    stickers_count: int | None
+```
+
+---
+
+## UCommonGroupInfo
+
+```python
+class UCommonGroupInfo:
+    user_id: int
+    common_groups: int
+    first_name: str | None
+    last_name: str | None
+    username: str | None
+    is_user_active: bool
+```
+
+---
+
+## UsernameUsageModel
+
+```python
+class UsernameUsageModel:
+    actual_users: list[ResolvedUser] | None
+    usage_by_users_in_the_past: list[ResolvedUser] | None
+    actual_groups_or_channels: list[ChatInfoExt] | None
+    mention_by_channel_or_group_desc: list[ChatInfoExt] | None
+```
+
+---
+
+## WhoWroteText
+
+```python
+class WhoWroteText:
+    message_id: int
+    user_id: int
+    date: str
+    name: str | None
+    username: str | None
+    is_active: bool
+    group: ChatInfoExt
+    text: str | None
+```
+
+---
+
+## WhoWroteTextPaged
+
+```python
+class WhoWroteTextPaged:
+    total: int
+    data: list[WhoWroteText]
+    is_last_page: bool | None
+    page_size: int | None
+    current_page: int | None
+    total_pages: int | None
+```
+
+---
+
+## PingResult
+
+```python
+class PingResult:
+    request_ping: str     # duration reported by the API
+    responce_ping: float  # actual round-trip in seconds
+```
+
+---
+
+## Response wrappers reference
+
+| Class | `.data` type |
+|-------|-------------|
+| `ResolvedUserResponse` | `list[`[`ResolvedUser`](#resolveduser)`]` |
+| `UserStatsMinResponse` | [`UserStatsMin`](#userstatsmin) |
+| `UserStatsResponse` | [`UserStats`](#userstats) |
+| `UserMsgPagedResponse` | `list[`[`UserMsg`](#usermsg)`]` |
+| `UserNameInfoResponse` | `list[`[`UserNameInfo`](#usernameinfo)`]` |
+| `UsrChatInfoResponse` | `list[`[`UsrChatInfo`](#usrchatinfo)`]` |
+| `GroupMemberResponse` | `list[`[`GroupMember`](#groupmember)`]` |
+| `GiftRelationResponse` | `list[`[`GiftRelationInfo`](#giftrelationinfo)`]` |
+| `StickerInfoResponse` | `list[`[`StickerInfo`](#stickerinfo)`]` |
+| `UCommonGroupInfoResponse` | `list[`[`UCommonGroupInfo`](#ucommongroupinfo)`]` |
+| `UsernameUsageResponse` | [`UsernameUsageModel`](#usernameusagemodel) |
+| `ChatInfoExtResponse` | `list[`[`ChatInfoExt`](#chatinfoext)`]` |
+| `WhoWroteTextResponse` | [`WhoWroteTextPaged`](#whowrotetextpaged) |
+
+---
+
+## ResolvedUserResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`ResolvedUser`](#resolveduser)`]`
+
+## UserStatsMinResponse
+
+`success` · [`TechInfo`](#techinfo) · `data:` [`UserStatsMin`](#userstatsmin)
+
+## UserStatsResponse
+
+`success` · [`TechInfo`](#techinfo) · `data:` [`UserStats`](#userstats)
+
+## UserMsgPagedResponse
+
+`success` · [`TechInfo`](#techinfo) · [`Paging`](#paging) · `data: list[`[`UserMsg`](#usermsg)`]`
+
+## UserNameInfoResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`UserNameInfo`](#usernameinfo)`]`
+
+## UsrChatInfoResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`UsrChatInfo`](#usrchatinfo)`]`
+
+## GroupMemberResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`GroupMember`](#groupmember)`]`
+
+## GiftRelationResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`GiftRelationInfo`](#giftrelationinfo)`]`
+
+## StickerInfoResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`StickerInfo`](#stickerinfo)`]`
+
+## UCommonGroupInfoResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`UCommonGroupInfo`](#ucommongroupinfo)`]`
+
+## UsernameUsageResponse
+
+`success` · [`TechInfo`](#techinfo) · `data:` [`UsernameUsageModel`](#usernameusagemodel)
+
+## ChatInfoExtResponse
+
+`success` · [`TechInfo`](#techinfo) · `data: list[`[`ChatInfoExt`](#chatinfoext)`]`
+
+## WhoWroteTextResponse
+
+`success` · [`TechInfo`](#techinfo) · `data:` [`WhoWroteTextPaged`](#whowrotetextpaged)

funstat_api-0.1.2/docs/api/sync.md

@@ -0,0 +1,257 @@
+# Sync Client
+
+```python
+from funstat_api import FunstatClient
+```
+
+## `FunstatClient(token)`
+
+Creates a synchronous client. Uses `requests` under the hood.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `str` | Your Funstat API token |
+
+---
+
+## Methods
+
+### ping
+
+`ping() →` [`PingResult`](models.md#pingresult) `| None`
+
+Check API availability and measure round-trip latency.
+
+```python
+result = fs.ping()
+print(result.responce_ping)   # seconds
+```
+
+---
+
+### get_balance
+
+`get_balance() →` [`TechInfo`](models.md#techinfo) `| None`
+
+Get current token balance and cost info.
+
+```python
+balance = fs.get_balance()
+print(balance.current_ballance)
+```
+
+---
+
+### resolve_username
+
+`resolve_username(username) →` [`ResolvedUserResponse`](models.md#resolveduserresponse) `| None`
+
+Resolve a username to full user info.
+
+```python
+result = fs.resolve_username("durov")
+user = result.data[0]
+print(user.id, user.first_name)
+```
+
+---
+
+### basic_info_by_id
+
+`basic_info_by_id(ids) →` [`ResolvedUserResponse`](models.md#resolveduserresponse) `| None`
+
+Get basic info for one or multiple users by numeric ID.
+
+```python
+result = fs.basic_info_by_id([123, 456])
+```
+
+---
+
+### stats_min
+
+`stats_min(user) →` [`UserStatsMinResponse`](models.md#userstatsminresponse) `| None`
+
+Get minimal statistics for a user.
+
+```python
+result = fs.stats_min("durov")
+print(result.data.total_msg_count)
+```
+
+---
+
+### stats
+
+`stats(user) →` [`UserStatsResponse`](models.md#userstatsresponse) `| None`
+
+Get full statistics for a user.
+
+```python
+result = fs.stats("durov")
+print(result.data.reply_percent)
+```
+
+---
+
+### messages_count
+
+`messages_count(user) → int`
+
+Get total message count for a user.
+
+---
+
+### groups_count
+
+`groups_count(user, only_msg=False) → int`
+
+Get number of groups a user belongs to.
+Set `only_msg=True` to count only groups where the user has sent messages.
+
+---
+
+### get_messages
+
+`get_messages(user, filter=None, group=None, limit=20, page=1) →` [`UserMsgPagedResponse`](models.md#usermsgpagedresponse) `| None`
+
+Get paginated message history for a user.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `user` | `int \| str` | User identifier |
+| `filter` | `str \| None` | Filter by text content |
+| `group` | `int \| str \| None` | Filter by group |
+| `limit` | `int` | Page size (default 20) |
+| `page` | `int` | Page number (default 1) |
+
+```python
+result = fs.get_messages("durov", filter="hello", limit=50)
+for msg in result.data:
+    print(msg.date, msg.text)
+```
+
+---
+
+### get_chats
+
+`get_chats(user) →` [`UsrChatInfoResponse`](models.md#usrchatinforesponse) `| None`
+
+Get list of chats the user participates in.
+
+---
+
+### get_names
+
+`get_names(user) →` [`UserNameInfoResponse`](models.md#usernameinforesponse) `| None`
+
+Get name change history for a user.
+
+---
+
+### get_usernames
+
+`get_usernames(user) →` [`UserNameInfoResponse`](models.md#usernameinforesponse) `| None`
+
+Get username change history for a user.
+
+---
+
+### get_stickers
+
+`get_stickers(user) →` [`StickerInfoResponse`](models.md#stickerinforesponse) `| None`
+
+Get sticker packs used by a user.
+
+---
+
+### get_gifts
+
+`get_gifts(user, limit=20, page=1) →` [`GiftRelationResponse`](models.md#giftrelationresponse) `| None`
+
+Get gift relations (sent/received) for a user.
+
+---
+
+### common_groups
+
+`common_groups(user) →` [`UCommonGroupInfoResponse`](models.md#ucommongroupinforesponse) `| None`
+
+Get statistics on common groups with other users.
+
+---
+
+### rep
+
+`rep(user) → dict | None`
+
+Get reputation data for a user.
+
+---
+
+### username_usage
+
+`username_usage(username) →` [`UsernameUsageResponse`](models.md#usernameusageresponse) `| None`
+
+Find who currently uses or has previously used a username.
+
+```python
+result = fs.username_usage("durov")
+print(result.data.actual_users)
+```
+
+---
+
+### common_groups_for_users
+
+`common_groups_for_users(ids) →` [`ChatInfoExtResponse`](models.md#chatinfoextresponse) `| None`
+
+Find groups that a list of users all share.
+
+```python
+result = fs.common_groups_for_users([123, 456, 789])
+```
+
+---
+
+### get_group_info
+
+`get_group_info(group) → dict | None`
+
+Get raw info about a group or channel.
+
+---
+
+### get_group_members
+
+`get_group_members(group) →` [`GroupMemberResponse`](models.md#groupmemberresponse) `| None`
+
+Get member list of a group.
+
+```python
+result = fs.get_group_members("https://t.me/mychat")
+for member in result.data:
+    print(member.id, member.username)
+```
+
+---
+
+### search_text
+
+`search_text(query, page=1, page_size=20) →` [`WhoWroteTextResponse`](models.md#whowrotetextresponse) `| None`
+
+Search all indexed messages by text content.
+
+```python
+result = fs.search_text("hello world")
+for item in result.data.data:
+    print(item.user_id, item.text)
+```
+
+---
+
+### close
+
+`close()`
+
+Close the underlying HTTP session. Called automatically when using `with`.

funstat_api-0.1.2/docs/changelog.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — Initial release
+
+- Sync client `FunstatClient` powered by `requests`
+- Async client `AsyncFunstatClient` powered by `httpx`
+- Full Pydantic v2 models for all API responses
+- Auto-resolution of usernames, `@username`, and `t.me/` links
+- Context manager support for both clients

funstat_api-0.1.2/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting Started
+
+## Requirements
+
+- Python 3.10+
+- A Funstat API token — get one at [funstat.info](http://funstat.in/?start=0108FC1E9BEF75617466)
+
+## Installation
+
+```bash
+pip install funstat-api
+```
+
+## Authentication
+
+Pass your token when creating a client:
+
+```python
+from funstat_api import FunstatClient
+
+fs = FunstatClient("your_token_here")
+```
+
+## Checking the connection
+
+```python
+ping = fs.ping()
+print(ping.responce_ping)   # round-trip time in seconds
+
+balance = fs.get_balance()
+print(balance.current_ballance)
+```
+
+## Identifying users
+
+All methods that accept a `user` argument are flexible — you can pass:
+
+```python
+fs.stats(12345678)               # numeric ID
+fs.stats("durov")                # username without @
+fs.stats("@durov")               # username with @
+fs.stats("https://t.me/durov")   # full t.me link
+```
+
+The same applies to `group` arguments.
+
+## Context managers
+
+Both clients support context managers to ensure connections are closed properly:
+
+=== "Sync"
+
+    ```python
+    with FunstatClient("your_token") as fs:
+        print(fs.stats("durov"))
+    ```
+
+=== "Async"
+
+    ```python
+    async with AsyncFunstatClient("your_token") as fs:
+        print(await fs.stats("durov"))
+    ```
+
+## Error handling
+
+```python
+from funstat_api import FunstatClient, ResolveError, ApiError
+
+fs = FunstatClient("your_token")
+
+try:
+    stats = fs.stats("nonexistent_user_xyz")
+except ResolveError as e:
+    print(f"User not found: {e}")
+except ApiError as e:
+    print(f"API error {e.status_code} on {e.path}")
+```

funstat_api-0.1.2/docs/index.md

@@ -0,0 +1,61 @@
+# funstat-api
+
+**Python client for the [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466) API** — Telegram user and group statistics.
+
+Supports both **sync** and **async** modes out of the box.
+
+---
+
+## Installation
+
+```bash
+pip install funstat-api
+```
+
+## Quick Example
+
+=== "Sync"
+
+    ```python
+    from funstat_api import FunstatClient
+
+    with FunstatClient("your_token") as fs:
+        stats = fs.stats("durov")
+        print(stats.data.total_msg_count)
+    ```
+
+=== "Async"
+
+    ```python
+    import asyncio
+    from funstat_api import AsyncFunstatClient
+
+    async def main():
+        async with AsyncFunstatClient("your_token") as fs:
+            stats = await fs.stats("durov")
+            print(stats.data.total_msg_count)
+
+    asyncio.run(main())
+    ```
+
+---
+
+## Features
+
+- ✅ Sync client powered by `requests`
+- ✅ Async client powered by `httpx`
+- ✅ Fully typed — all responses are Pydantic models
+- ✅ Accepts username, `@username`, numeric ID, or `t.me/` link
+- ✅ Auto-resolves usernames to IDs internally
+
+---
+
+[Get Started :material-arrow-right:](getting-started.md){ .md-button .md-button--primary }
+
+---
+
+## Links
+
+- [PyPI](https://pypi.org/project/funstat-api/)
+- [GitHub](https://github.com/chizumeiji/funstat-api)
+- [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466)

funstat_api-0.1.2/docs/stylesheets/extra.css

@@ -0,0 +1,42 @@
+
+h2, h3 {
+  transition: opacity 0.25s ease;
+}
+
+:is(h3:target) ~ h3,
+h3:has(~ h3:target) {
+  opacity: 0.45;
+}
+
+h3:target {
+  opacity: 1 !important;
+  border-left: 3px solid var(--md-accent-fg-color);
+  padding-left: 0.55rem;
+  margin-left: -0.7rem;
+  border-radius: 2px;
+  color: lavender;
+  transition: border-left 0.2s ease, padding-left 0.2s ease, opacity 0.25s ease;
+}
+
+h3:target ~ h3 {
+  opacity: 0.45;
+}
+
+:is(h2:target) ~ h2,
+h2:has(~ h2:target) {
+  opacity: 0.45;
+}
+
+h2:target {
+  opacity: 1 !important;
+  border-left: 3px solid var(--md-accent-fg-color);
+  padding-left: 0.55rem;
+  margin-left: -0.7rem;
+  border-radius: 2px;
+  color: lavender;
+  transition: border-left 0.2s ease, padding-left 0.2s ease, opacity 0.25s ease;
+}
+
+h2:target ~ h2 {
+  opacity: 0.45;
+}

{funstat_api-0.1.0 → funstat_api-0.1.2}/funstat_api/funstat.py

@@ -295,7 +295,7 @@ class WhoWroteTextResponse(BaseModel):
 #  Helpers
 # ─────────────────────────────────────────────────────────────────────────────
 
-BASE_URL = "https://funstat.info/api/v1"
+BASE_URL = "/api/v1"
 
 def _clean_username(username: str) -> str:
     username = username.strip()

funstat_api-0.1.2/mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: funstat-api
+site_description: Python client for the Funstat API — Telegram user and group statistics
+site_url: https://chizumeiji.github.io/funstat-api
+repo_url: https://github.com/chizumeiji/funstat-api
+repo_name: funstat-api
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  language: en
+  palette:
+    - scheme: slate
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    - scheme: default
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.sidebar
+    - navigation.top
+    - navigation.indexes
+    - toc.integrate
+    - search.highlight
+    - content.code.copy
+
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - tables
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference:
+    - Sync Client: api/sync.md
+    - Async Client: api/async.md
+    - Models: api/models.md
+    - Exceptions: api/exceptions.md
+  - Changelog: changelog.md
+
+extra_css:
+  - stylesheets/extra.css
+
+plugins:
+  - search

{funstat_api-0.1.0 → funstat_api-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "funstat-api"
-version = "0.1.0"
+version = "0.1.2"
 description = "Sync and async Python client for the Funstat API (Telegram user/group statistics)"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -33,4 +33,5 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/chizumeiji/funstat-api"
+Documentation = "https://chizumeiji.github.io/funstat-api/"
 "Bug Tracker" = "https://github.com/chizumeiji/funstat-api/issues"

funstat_api-0.1.0/readme.md

@@ -1,82 +0,0 @@
-# funstat-api
-
-Python client for the [Funstat](http://funstat.in/?start=0108FC1E9BEF75617466) API — Telegram user and group statistics.
-
-Supports both **sync** and **async** usage.
-
-## Installation
-
-```bash
-pip install funstat-api
-```
-
-## Quick Start
-
-### Sync
-
-```python
-from funstat_api import FunstatClient
-
-fs = FunstatClient("your_token")
-
-# Get user stats
-stats = fs.stats("durov")
-print(stats.data.total_msg_count)
-
-# Get group members
-members = fs.get_group_members("https://t.me/mychat")
-
-# Use as context manager
-with FunstatClient("your_token") as fs:
-    print(fs.ping())
-```
-
-### Async
-
-```python
-import asyncio
-from funstat_api import AsyncFunstatClient
-
-async def main():
-    async with AsyncFunstatClient("your_token") as fs:
-        stats = await fs.stats("durov")
-        print(stats.data.total_msg_count)
-
-asyncio.run(main())
-```
-
-## Available Methods
-
-| Method | Description |
-|--------|-------------|
-| `ping()` | Check API availability and latency |
-| `get_balance()` | Get current token balance |
-| `resolve_username(username)` | Resolve username to user info |
-| `basic_info_by_id(ids)` | Get basic info by user ID(s) |
-| `stats_min(user)` | Get minimal user statistics |
-| `stats(user)` | Get full user statistics |
-| `messages_count(user)` | Get total message count |
-| `groups_count(user)` | Get number of groups |
-| `get_messages(user, ...)` | Get paginated message list |
-| `get_chats(user)` | Get user's chat list |
-| `get_names(user)` | Get name history |
-| `get_usernames(user)` | Get username history |
-| `get_stickers(user)` | Get used sticker packs |
-| `get_gifts(user)` | Get gift relations |
-| `common_groups(user)` | Get common groups stats |
-| `username_usage(username)` | Who uses or used a username |
-| `get_group_info(group)` | Get group/channel info |
-| `get_group_members(group)` | Get group members |
-| `search_text(query)` | Search messages by text |
-
-`user` and `group` arguments accept: numeric ID, `@username`, or `https://t.me/...` link.
-
-## Dependencies
-
-- `pydantic >= 2.0`
-- `requests >= 2.28` (sync client)
-- `httpx >= 0.24` (async client)
-
-## License
-
-MIT