cloudtips 0.3.0__tar.gz → 0.4.0__tar.gz

cloudtips-0.4.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: cloudtips
+Version: 0.4.0
+Summary: Неофициальная асинхронная Python-библиотека для CloudTips (получение донатов, поллинг, обновление токенов)
+Project-URL: Repository, https://github.com/IRRatium/cloudtips-api
+Project-URL: Issues, https://github.com/IRRatium/cloudtips-api/issues
+License: MIT
+License-File: LICENSE
+Keywords: api,async,asyncio,cloudtips,donations,payments,tips
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# CloudtipsAPI
+
+Неофициальная асинхронная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
+
+## Установка
+
+```bash
+pip install cloudtips
+```
+
+## Быстрый старт
+
+```python
+import asyncio
+import json
+from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
+
+# Загружаем токены из файла
+with open("donate.json") as f:
+    config = json.load(f)
+
+# Колбэк вызывается каждый раз при обновлении токенов.
+# Поддерживаются как async, так и обычные функции.
+# Refresh-токен одноразовый — обязательно сохраняйте новые!
+async def on_token_refresh(token_data: TokenData):
+    config["cloudtips_token"] = token_data.access_token
+    config["cloudtips_refresh_token"] = token_data.refresh_token
+    config["cloudtips_expires_at"] = token_data.expires_at
+    with open("donate.json", "w") as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+    print("Токены обновлены и сохранены.")
+
+auth = CloudTipsAuth(
+    token=config["cloudtips_token"],
+    refresh_token=config["cloudtips_refresh_token"],
+    expires_at=config["cloudtips_expires_at"],
+    on_token_refresh=on_token_refresh,
+)
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+        for d in donations:
+            print(d)
+
+asyncio.run(main())
+```
+
+## Получение донатов
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Все донаты за последние 24 часа
+    donations = await client.get_all_donations()
+    for d in donations:
+        print(d)  # [2026-04-10 20:44] евгения → 50₽ — "оч крутой сервис"
+
+    # Только за конкретный период
+    from datetime import datetime, timedelta, timezone
+
+    yesterday = datetime.now(tz=timezone.utc) - timedelta(days=1)
+    recent = await client.get_donations(since=yesterday)
+```
+
+## Поллинг новых донатов
+
+### Вариант 1 — async-генератор
+
+```python
+async with CloudTipsClient(auth) as client:
+    print("Слушаем новые донаты...")
+    async for donation in client.poll(interval=30):
+        print(f"💰 {donation.name} задонатил {donation.amount}₽")
+        if donation.comment:
+            print(f"   Комментарий: {donation.comment}")
+```
+
+### Вариант 2 — async-колбэк
+
+```python
+async def handle_donation(donation):
+    print(f"Новый донат от {donation.name}: {donation.amount}₽")
+    # await bot.send_message(...)
+
+async with CloudTipsClient(auth) as client:
+    await client.poll(interval=15, callback=handle_donation)
+```
+
+### Вариант 3 — в фоновой задаче asyncio
+
+```python
+async def poll_task(client):
+    async for donation in client.poll(interval=30):
+        print(f"Новый донат: {donation}")
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        task = asyncio.create_task(poll_task(client))
+        # Основная логика...
+        await task
+
+asyncio.run(main())
+```
+
+## Профиль, карты и баланс
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Профиль пользователя
+    me = await client.get_me()
+    print(me.full_name)        # IRRing
+    print(me.payout_method)    # Accumulation
+
+    # Привязанные карты
+    for card in await client.get_cards():
+        print(card)            # MIR *3742 (T-BANK, до 08/34) [по умолчанию]
+        print(card.token)      # tk_89e6b3c6827afd4e9ccc36db2d22f
+
+    # Баланс к выводу
+    s = await client.get_accumulation_summary()
+    print(f"Накоплено: {s.accumulated_amount}₽")
+    print(f"Комиссия: {s.commission_percent}%")
+    print(f"Следующая выплата: {s.next_payout_date or 'не запланирована'}")
+
+    # Информация о комиссиях
+    fee = await client.get_payout_fee_info()
+    print(fee.text)
+
+    # Смена метода выплат
+    await client.set_payout_method("Instant")        # мгновенно
+    await client.set_payout_method("Accumulation")   # накопительно
+
+    # Удаление карты
+    for card in await client.get_cards():
+        await client.delete_card(card.token)
+```
+
+## Структура `Donation`
+
+```python
+@dataclass
+class Donation:
+    transaction_id: int    # уникальный ID транзакции
+    name: str              # имя донатера
+    amount: int            # сумма в рублях
+    tg_id: int             # Telegram ID
+    comment: str           # комментарий (может быть пустым)
+    date: datetime         # дата и время
+
+str(donation)
+# "[2026-04-10 23:04] Каспер → 200₽ — "спасибо за отличный сервис)""
+```
+
+## Обработка ошибок
+
+```python
+from cloudtips import CloudTipsAuthError, CloudTipsAPIError
+
+try:
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_donations()
+except CloudTipsAuthError as e:
+    print(f"Проблема с аутентификацией: {e}")
+except CloudTipsAPIError as e:
+    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
+```
+
+## Примечания
+
+- **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
+- `on_token_refresh` поддерживает как обычные (`def`), так и async-функции (`async def`).
+- Библиотека автоматически обновляет токен за 2 минуты до истечения.
+- Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
+- Клиент — контекстный менеджер (`async with`), это рекомендуемый способ использования.
+
+## Лицензия
+
+MIT

cloudtips-0.4.0/README.md

@@ -0,0 +1,178 @@
+# CloudtipsAPI
+
+Неофициальная асинхронная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
+
+## Установка
+
+```bash
+pip install cloudtips
+```
+
+## Быстрый старт
+
+```python
+import asyncio
+import json
+from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
+
+# Загружаем токены из файла
+with open("donate.json") as f:
+    config = json.load(f)
+
+# Колбэк вызывается каждый раз при обновлении токенов.
+# Поддерживаются как async, так и обычные функции.
+# Refresh-токен одноразовый — обязательно сохраняйте новые!
+async def on_token_refresh(token_data: TokenData):
+    config["cloudtips_token"] = token_data.access_token
+    config["cloudtips_refresh_token"] = token_data.refresh_token
+    config["cloudtips_expires_at"] = token_data.expires_at
+    with open("donate.json", "w") as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+    print("Токены обновлены и сохранены.")
+
+auth = CloudTipsAuth(
+    token=config["cloudtips_token"],
+    refresh_token=config["cloudtips_refresh_token"],
+    expires_at=config["cloudtips_expires_at"],
+    on_token_refresh=on_token_refresh,
+)
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+        for d in donations:
+            print(d)
+
+asyncio.run(main())
+```
+
+## Получение донатов
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Все донаты за последние 24 часа
+    donations = await client.get_all_donations()
+    for d in donations:
+        print(d)  # [2026-04-10 20:44] евгения → 50₽ — "оч крутой сервис"
+
+    # Только за конкретный период
+    from datetime import datetime, timedelta, timezone
+
+    yesterday = datetime.now(tz=timezone.utc) - timedelta(days=1)
+    recent = await client.get_donations(since=yesterday)
+```
+
+## Поллинг новых донатов
+
+### Вариант 1 — async-генератор
+
+```python
+async with CloudTipsClient(auth) as client:
+    print("Слушаем новые донаты...")
+    async for donation in client.poll(interval=30):
+        print(f"💰 {donation.name} задонатил {donation.amount}₽")
+        if donation.comment:
+            print(f"   Комментарий: {donation.comment}")
+```
+
+### Вариант 2 — async-колбэк
+
+```python
+async def handle_donation(donation):
+    print(f"Новый донат от {donation.name}: {donation.amount}₽")
+    # await bot.send_message(...)
+
+async with CloudTipsClient(auth) as client:
+    await client.poll(interval=15, callback=handle_donation)
+```
+
+### Вариант 3 — в фоновой задаче asyncio
+
+```python
+async def poll_task(client):
+    async for donation in client.poll(interval=30):
+        print(f"Новый донат: {donation}")
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        task = asyncio.create_task(poll_task(client))
+        # Основная логика...
+        await task
+
+asyncio.run(main())
+```
+
+## Профиль, карты и баланс
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Профиль пользователя
+    me = await client.get_me()
+    print(me.full_name)        # IRRing
+    print(me.payout_method)    # Accumulation
+
+    # Привязанные карты
+    for card in await client.get_cards():
+        print(card)            # MIR *3742 (T-BANK, до 08/34) [по умолчанию]
+        print(card.token)      # tk_89e6b3c6827afd4e9ccc36db2d22f
+
+    # Баланс к выводу
+    s = await client.get_accumulation_summary()
+    print(f"Накоплено: {s.accumulated_amount}₽")
+    print(f"Комиссия: {s.commission_percent}%")
+    print(f"Следующая выплата: {s.next_payout_date or 'не запланирована'}")
+
+    # Информация о комиссиях
+    fee = await client.get_payout_fee_info()
+    print(fee.text)
+
+    # Смена метода выплат
+    await client.set_payout_method("Instant")        # мгновенно
+    await client.set_payout_method("Accumulation")   # накопительно
+
+    # Удаление карты
+    for card in await client.get_cards():
+        await client.delete_card(card.token)
+```
+
+## Структура `Donation`
+
+```python
+@dataclass
+class Donation:
+    transaction_id: int    # уникальный ID транзакции
+    name: str              # имя донатера
+    amount: int            # сумма в рублях
+    tg_id: int             # Telegram ID
+    comment: str           # комментарий (может быть пустым)
+    date: datetime         # дата и время
+
+str(donation)
+# "[2026-04-10 23:04] Каспер → 200₽ — "спасибо за отличный сервис)""
+```
+
+## Обработка ошибок
+
+```python
+from cloudtips import CloudTipsAuthError, CloudTipsAPIError
+
+try:
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_donations()
+except CloudTipsAuthError as e:
+    print(f"Проблема с аутентификацией: {e}")
+except CloudTipsAPIError as e:
+    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
+```
+
+## Примечания
+
+- **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
+- `on_token_refresh` поддерживает как обычные (`def`), так и async-функции (`async def`).
+- Библиотека автоматически обновляет токен за 2 минуты до истечения.
+- Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
+- Клиент — контекстный менеджер (`async with`), это рекомендуемый способ использования.
+
+## Лицензия
+
+MIT

{cloudtips-0.3.0 → cloudtips-0.4.0}/cloudtips/__init__.py

@@ -1,12 +1,12 @@
 """
-cloudtips — неофициальная Python-библиотека для CloudTips.
+cloudtips — неофициальная асинхронная Python-библиотека для CloudTips.
 """
 
 from .auth import CloudTipsAuth, CloudTipsAuthError
 from .client import CloudTipsAPIError, CloudTipsClient
 from .models import AccumulationSummary, Card, Donation, PayoutFeeInfo, ReceiverProfile, TokenData
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = [
     "CloudTipsAuth",
     "CloudTipsAuthError",

{cloudtips-0.3.0 → cloudtips-0.4.0}/cloudtips/auth.py

@@ -1,7 +1,10 @@
+"""
+Аутентификация CloudTips — управление access/refresh токенами.
+"""
 import time
 from typing import Callable, Optional
 
-import requests
+import aiohttp
 
 from .models import TokenData
 
@@ -14,17 +17,17 @@ class CloudTipsAuth:
     """
     Управляет access/refresh токенами CloudTips.
 
-    Параметр `on_token_refresh` — это колбэк, который вызывается каждый раз
-    после успешного обновления токенов. Используйте его, чтобы сохранить
-    новые токены в файл/БД/переменные окружения — refresh-токен одноразовый!
+    Параметр ``on_token_refresh`` — колбэк, вызываемый после каждого
+    успешного обновления токенов. Refresh-токен одноразовый, поэтому
+    обязательно сохраняйте новые значения.
 
     Пример::
 
-        def save_tokens(token_data: TokenData):
+        async def save_tokens(token_data: TokenData):
             config["cloudtips_token"] = token_data.access_token
             config["cloudtips_refresh_token"] = token_data.refresh_token
             config["cloudtips_expires_at"] = token_data.expires_at
-            save_config(config)
+            await write_config(config)
 
         auth = CloudTipsAuth(
             token="...",
@@ -50,31 +53,31 @@ class CloudTipsAuth:
     # Public
     # ------------------------------------------------------------------
 
-    @property
-    def token(self) -> str:
+    async def get_token(self) -> str:
         """Возвращает актуальный access-токен, автоматически обновляя при необходимости."""
         if self._is_expired():
-            self.refresh()
+            await self.refresh()
         return self._token
 
     @property
     def expires_at(self) -> float:
         return self._expires_at
 
-    def refresh(self) -> TokenData:
+    async def refresh(self) -> TokenData:
         """Принудительно обновляет токены через CloudTips Identity Server."""
-        response = requests.post(
-            _TOKEN_URL,
-            data={
-                "grant_type": "refresh_token",
-                "refresh_token": self._refresh_token,
-                "client_id": _CLIENT_ID,
-            },
-            timeout=10,
-        )
-        _raise_for_status(response)
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                _TOKEN_URL,
+                data={
+                    "grant_type":    "refresh_token",
+                    "refresh_token": self._refresh_token,
+                    "client_id":     _CLIENT_ID,
+                },
+                timeout=aiohttp.ClientTimeout(total=10),
+            ) as response:
+                await _raise_for_status(response)
+                data = await response.json()
 
-        data = response.json()
         token_data = TokenData(
             access_token=data["access_token"],
             refresh_token=data["refresh_token"],
@@ -86,15 +89,18 @@ class CloudTipsAuth:
         self._expires_at = token_data.expires_at
 
         if self._on_token_refresh:
-            self._on_token_refresh(token_data)
+            result = self._on_token_refresh(token_data)
+            # поддержка как async, так и обычных колбэков
+            if hasattr(result, "__await__"):
+                await result
 
         return token_data
 
-    def headers(self) -> dict:
+    async def headers(self) -> dict:
         """Готовые Authorization-заголовки для запросов."""
         return {
-            "Authorization": f"Bearer {self.token}",
-            "Content-Type": "application/json",
+            "Authorization": f"Bearer {await self.get_token()}",
+            "Content-Type":  "application/json",
         }
 
     # ------------------------------------------------------------------
@@ -105,17 +111,15 @@ class CloudTipsAuth:
         return time.time() >= self._expires_at - _EXPIRE_BUFFER
 
 
-def _raise_for_status(response: requests.Response) -> None:
-    try:
-        response.raise_for_status()
-    except requests.HTTPError as e:
+async def _raise_for_status(response: aiohttp.ClientResponse) -> None:
+    if not response.ok:
         try:
-            detail = response.json()
+            detail = await response.json()
         except Exception:
-            detail = response.text
+            detail = await response.text()
         raise CloudTipsAuthError(
-            f"Ошибка при обновлении токена: {response.status_code} — {detail}"
-        ) from e
+            f"Ошибка при обновлении токена: {response.status} — {detail}"
+        )
 
 
 class CloudTipsAuthError(Exception):

{cloudtips-0.3.0 → cloudtips-0.4.0}/cloudtips/client.py

@@ -1,34 +1,50 @@
 """
-Клиент CloudTips API.
+Асинхронный клиент CloudTips API.
 """
-import time
+import asyncio
 from datetime import datetime, timezone, timedelta
-from typing import Callable, Iterator, List, Optional
+from typing import AsyncIterator, Callable, List, Optional
 
-import requests
+import aiohttp
 
 from .auth import CloudTipsAuth
-from .models import Donation, Card, PayoutFeeInfo, AccumulationSummary, ReceiverProfile
+from .models import AccumulationSummary, Card, Donation, PayoutFeeInfo, ReceiverProfile
 
 _BASE_URL = "https://api.cloudtips.ru/api"
 _MSK = timezone(timedelta(hours=3))
 
-HEADERS_BASE = {
-    "Accept": "application/json, text/plain, */*",
+_HEADERS_BASE = {
+    "Accept":          "application/json, text/plain, */*",
     "Accept-Language": "ru-RU,ru;q=0.9",
-    "Origin": "https://lk.cloudtips.ru",
-    "Referer": "https://lk.cloudtips.ru/",
-    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+    "Origin":          "https://lk.cloudtips.ru",
+    "Referer":         "https://lk.cloudtips.ru/",
+    "User-Agent":      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
 }
 
 
 class CloudTipsClient:
     """
-    Основной клиент для работы с CloudTips API.
+    Асинхронный клиент для работы с CloudTips API.
+
+    Используйте как контекстный менеджер, чтобы сессия aiohttp
+    корректно открывалась и закрывалась::
+
+        async with CloudTipsClient(auth) as client:
+            donations = await client.get_all_donations()
+
+    Или управляйте сессией вручную::
+
+        client = CloudTipsClient(auth)
+        await client.open()
+        try:
+            donations = await client.get_all_donations()
+        finally:
+            await client.close()
 
     Пример быстрого старта::
 
-        from cloudtips import CloudTipsClient, CloudTipsAuth
+        import asyncio
+        from cloudtips import CloudTipsAuth, CloudTipsClient
 
         auth = CloudTipsAuth(
             token="...",
@@ -36,23 +52,48 @@ class CloudTipsClient:
             expires_at=1776099728.0,
             on_token_refresh=lambda td: print("Новый refresh:", td.refresh_token),
         )
-        client = CloudTipsClient(auth)
 
-        donations = client.get_all_donations()
-        cards = client.get_cards()
-        summary = client.get_accumulation_summary()
+        async def main():
+            async with CloudTipsClient(auth) as client:
+                donations = await client.get_all_donations()
+                cards     = await client.get_cards()
+                summary   = await client.get_accumulation_summary()
+
+        asyncio.run(main())
     """
 
     def __init__(self, auth: CloudTipsAuth, base_url: str = _BASE_URL) -> None:
         self._auth = auth
         self._base_url = base_url.rstrip("/")
-        self._session = requests.Session()
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    # ------------------------------------------------------------------
+    # Управление сессией
+    # ------------------------------------------------------------------
+
+    async def open(self) -> None:
+        """Открыть aiohttp-сессию."""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+
+    async def close(self) -> None:
+        """Закрыть aiohttp-сессию."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> "CloudTipsClient":
+        await self.open()
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()
 
     # ------------------------------------------------------------------
     # Донаты
     # ------------------------------------------------------------------
 
-    def get_donations(
+    async def get_donations(
         self,
         since: Optional[datetime] = None,
         until: Optional[datetime] = None,
@@ -72,7 +113,7 @@ class CloudTipsClient:
         date_from = _ensure_tz(since or (now - timedelta(hours=24)))
         date_to   = _ensure_tz(until or now)
 
-        data = self._get("/timeline", params={
+        data = await self._get("/timeline", params={
             "page":     page,
             "limit":    limit,
             "dateFrom": date_from.isoformat(),
@@ -94,7 +135,7 @@ class CloudTipsClient:
             }))
         return result
 
-    def get_all_donations(
+    async def get_all_donations(
         self,
         since: Optional[datetime] = None,
         until: Optional[datetime] = None,
@@ -109,7 +150,7 @@ class CloudTipsClient:
         result: List[Donation] = []
         page = 1
         while True:
-            batch = self.get_donations(since=since, until=until, limit=50, page=page)
+            batch = await self.get_donations(since=since, until=until, limit=50, page=page)
             if not batch:
                 break
             result.extend(batch)
@@ -118,23 +159,26 @@ class CloudTipsClient:
             page += 1
         return sorted(result, key=lambda d: d.date)
 
-    def poll(
+    async def poll(
         self,
         interval: int = 30,
         since: Optional[datetime] = None,
         callback: Optional[Callable[[Donation], None]] = None,
-    ) -> Iterator[Donation]:
+    ) -> AsyncIterator[Donation]:
         """
-        Генератор: бесконечный поллинг новых донатов.
+        Асинхронный генератор: бесконечный поллинг новых донатов.
 
-        Использование как генератора::
+        Использование как async-генератора::
 
-            for donation in client.poll(interval=15):
+            async for donation in client.poll(interval=15):
                 print(f"Новый донат: {donation}")
 
-        Или с колбэком (блокирующий режим)::
+        Или с async-колбэком (блокирующий режим)::
+
+            async def handle(donation):
+                await bot.send_message(chat_id, str(donation))
 
-            client.poll(interval=15, callback=handle_donation)
+            await client.poll(interval=15, callback=handle)
 
         :param interval: пауза между запросами в секундах
         :param since: с какого момента начинать (по умолчанию — прямо сейчас)
@@ -143,14 +187,14 @@ class CloudTipsClient:
         last_seen_ids: set = set()
         cursor = _ensure_tz(since or datetime.now(_MSK))
 
-        for d in self.get_all_donations(since=cursor):
+        for d in await self.get_all_donations(since=cursor):
             last_seen_ids.add(d.transaction_id)
 
         while True:
-            time.sleep(interval)
+            await asyncio.sleep(interval)
 
             try:
-                fresh = self.get_all_donations(since=cursor)
+                fresh = await self.get_all_donations(since=cursor)
             except Exception as exc:
                 print(f"[cloudtips] Ошибка при поллинге: {exc}")
                 continue
@@ -160,7 +204,9 @@ class CloudTipsClient:
                     last_seen_ids.add(donation.transaction_id)
                     cursor = max(cursor, donation.date)
                     if callback:
-                        callback(donation)
+                        result = callback(donation)
+                        if hasattr(result, "__await__"):
+                            await result
                     else:
                         yield donation
 
@@ -168,29 +214,26 @@ class CloudTipsClient:
     # Профиль
     # ------------------------------------------------------------------
 
-    def get_me(self) -> ReceiverProfile:
+    async def get_me(self) -> ReceiverProfile:
         """
         Получить профиль текущего пользователя.
 
-        Содержит имя, телефон, метод выплат, лимиты сумм и другие данные.
-
         :return: :class:`ReceiverProfile`
 
         Пример::
 
-            me = client.get_me()
+            me = await client.get_me()
             print(me.full_name)       # IRRing
             print(me.payout_method)   # Accumulation
-            print(me.available_amount_min, me.available_amount_max)  # 49.0 3000.0
         """
-        data = self._get("/receivers/me")
+        data = await self._get("/receivers/me")
         return ReceiverProfile.from_dict(data.get("data", {}))
 
     # ------------------------------------------------------------------
     # Карты
     # ------------------------------------------------------------------
 
-    def get_cards(self) -> List[Card]:
+    async def get_cards(self) -> List[Card]:
         """
         Получить список привязанных карт.
 
@@ -198,49 +241,37 @@ class CloudTipsClient:
 
         Пример::
 
-            for card in client.get_cards():
-                print(card)         # MIR *3742 (T-BANK (TINKOFF), до 08/34) [по умолчанию]
+            for card in await client.get_cards():
+                print(card)         # MIR *3742 (T-BANK, до 08/34) [по умолчанию]
                 print(card.token)   # tk_89e6b3c6827afd4e9ccc36db2d22f
         """
-        data = self._get("/cards")
+        data = await self._get("/cards")
         return [Card.from_dict(item) for item in data.get("data", [])]
 
-    def delete_card(self, card_token: str) -> bool:
+    async def delete_card(self, card_token: str) -> bool:
         """
         Удалить привязанную карту.
 
         :param card_token: токен карты (``card.token``)
         :return: ``True`` если удаление прошло успешно
-
-        Пример::
-
-            for card in client.get_cards():
-                client.delete_card(card.token)
         """
-        data = self._delete("/cards", json={"cardToken": card_token})
+        data = await self._delete("/cards", json={"cardToken": card_token})
         return data.get("succeed", False)
 
     # ------------------------------------------------------------------
     # Выплаты и баланс
     # ------------------------------------------------------------------
 
-    def get_payout_fee_info(self) -> PayoutFeeInfo:
+    async def get_payout_fee_info(self) -> PayoutFeeInfo:
         """
         Получить информацию о комиссиях при выводе средств.
 
         :return: :class:`PayoutFeeInfo`
-
-        Пример::
-
-            fee = client.get_payout_fee_info()
-            print(fee.text)
-            # Стоимость вывода денег на карты Т-Банка — 5%
-            # Стоимость вывода денег на карты других банков — 7%*
         """
-        data = self._get("/payout/fee/info")
+        data = await self._get("/payout/fee/info")
         return PayoutFeeInfo.from_dict(data.get("data", {}))
 
-    def get_accumulation_summary(self) -> AccumulationSummary:
+    async def get_accumulation_summary(self) -> AccumulationSummary:
         """
         Получить сводку по накопленным средствам (баланс к выводу).
 
@@ -248,68 +279,78 @@ class CloudTipsClient:
 
         Пример::
 
-            s = client.get_accumulation_summary()
+            s = await client.get_accumulation_summary()
             print(f"Накоплено: {s.accumulated_amount}₽")
             print(f"Комиссия: {s.commission_percent}%")
-            print(f"Следующая выплата: {s.next_payout_date or 'не запланирована'}")
         """
-        data = self._get("/accumulations/summary")
+        data = await self._get("/accumulations/summary")
         return AccumulationSummary.from_dict(data.get("data", {}))
 
-    def get_payout_method(self) -> str:
+    async def get_payout_method(self) -> str:
         """
         Получить текущий метод выплат.
 
         :return: ``"Instant"`` или ``"Accumulation"``
         """
-        return self.get_me().payout_method
+        return (await self.get_me()).payout_method
 
-    def set_payout_method(self, method: str = "Instant") -> bool:
+    async def set_payout_method(self, method: str = "Instant") -> bool:
         """
         Установить метод выплат.
 
         :param method: ``"Instant"`` (мгновенно) или ``"Accumulation"`` (накопительно)
         :return: ``True`` если успешно
         """
-        data = self._post("/receivers/payout-method", json={"payoutMethod": method})
+        data = await self._post("/receivers/payout-method", json={"payoutMethod": method})
         return data.get("succeed", False)
 
     # ------------------------------------------------------------------
     # Внутренние HTTP-методы
     # ------------------------------------------------------------------
 
-    def _get(self, path: str, params: Optional[dict] = None) -> dict:
-        headers = {**HEADERS_BASE, **self._auth.headers()}
-        response = self._session.get(
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            raise RuntimeError(
+                "Сессия не открыта. Используйте `async with CloudTipsClient(auth) as client:` "
+                "или вызовите `await client.open()` перед первым запросом."
+            )
+        return self._session
+
+    async def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        session = self._ensure_session()
+        headers = {**_HEADERS_BASE, **await self._auth.headers()}
+        async with session.get(
             self._base_url + path,
             headers=headers,
             params=params,
-            timeout=15,
-        )
-        _raise_for_status(response)
-        return response.json()
-
-    def _post(self, path: str, json: Optional[dict] = None) -> dict:
-        headers = {**HEADERS_BASE, **self._auth.headers()}
-        response = self._session.post(
+            timeout=aiohttp.ClientTimeout(total=15),
+        ) as response:
+            await _raise_for_status(response)
+            return await response.json()
+
+    async def _post(self, path: str, json: Optional[dict] = None) -> dict:
+        session = self._ensure_session()
+        headers = {**_HEADERS_BASE, **await self._auth.headers()}
+        async with session.post(
             self._base_url + path,
             headers=headers,
             json=json,
-            timeout=15,
-        )
-        _raise_for_status(response)
-        return response.json()
-
-    def _delete(self, path: str, json: Optional[dict] = None) -> dict:
-        headers = {**HEADERS_BASE, **self._auth.headers()}
-        response = self._session.delete(
+            timeout=aiohttp.ClientTimeout(total=15),
+        ) as response:
+            await _raise_for_status(response)
+            return await response.json()
+
+    async def _delete(self, path: str, json: Optional[dict] = None) -> dict:
+        session = self._ensure_session()
+        headers = {**_HEADERS_BASE, **await self._auth.headers()}
+        async with session.delete(
             self._base_url + path,
             headers=headers,
             json=json,
-            timeout=15,
-        )
-        _raise_for_status(response)
-        return response.json()
+            timeout=aiohttp.ClientTimeout(total=15),
+        ) as response:
+            await _raise_for_status(response)
+            return await response.json()
 
 
 class CloudTipsAPIError(Exception):
@@ -326,10 +367,10 @@ def _ensure_tz(dt: datetime) -> datetime:
     return dt if dt.tzinfo else dt.replace(tzinfo=_MSK)
 
 
-def _raise_for_status(response: requests.Response) -> None:
+async def _raise_for_status(response: aiohttp.ClientResponse) -> None:
     if not response.ok:
         try:
-            detail = response.json()
+            detail = await response.json()
         except Exception:
-            detail = response.text
-        raise CloudTipsAPIError(response.status_code, detail)
+            detail = await response.text()
+        raise CloudTipsAPIError(response.status, detail)

{cloudtips-0.3.0 → cloudtips-0.4.0}/cloudtips/models.py

@@ -71,7 +71,7 @@ class Card:
 
 @dataclass
 class PayoutFeeInfo:
-    text: str                        # текст с описанием комиссий
+    text: str
     downgrade_condition: str
     tinkoff_commission_hint: str
     instant_payout_commission_text: str
@@ -88,12 +88,12 @@ class PayoutFeeInfo:
 
 @dataclass
 class AccumulationSummary:
-    accumulated_amount: float    # накоплено (ещё не выведено)
-    amount_to_deposit: float     # к зачислению
-    commission: float            # сумма комиссии
-    commission_percent: float    # процент комиссии
-    next_payout_date: Optional[str]  # дата следующей выплаты (None если не запланирована)
-    commission_hint: str         # текст подсказки
+    accumulated_amount: float
+    amount_to_deposit: float
+    commission: float
+    commission_percent: float
+    next_payout_date: Optional[str]
+    commission_hint: str
 
     @classmethod
     def from_dict(cls, data: dict) -> "AccumulationSummary":
@@ -155,6 +155,8 @@ class ReceiverProfile:
         )
 
 
+@dataclass
+class TokenData:
     """Новые токены, которые библиотека передаёт в on_token_refresh."""
     access_token: str
     refresh_token: str

{cloudtips-0.3.0 → cloudtips-0.4.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cloudtips"
-version = "0.3.0"
-description = "Неофициальная Python-библиотека для CloudTips (получение донатов, поллинг, обновление токенов)"
+version = "0.4.0"
+description = "Неофициальная асинхронная Python-библиотека для CloudTips (получение донатов, поллинг, обновление токенов)"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.9"
 dependencies = [
-    "requests>=2.28",
+    "aiohttp>=3.9",
 ]
-keywords = ["cloudtips", "donations", "tips", "api", "payments"]
+keywords = ["cloudtips", "donations", "tips", "api", "payments", "async", "asyncio"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
@@ -22,6 +22,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Topic :: Internet :: WWW/HTTP",
+    "Framework :: AsyncIO",
 ]
 
 [project.urls]

cloudtips-0.3.0/PKG-INFO

@@ -1,151 +0,0 @@
-Metadata-Version: 2.4
-Name: cloudtips
-Version: 0.3.0
-Summary: Неофициальная Python-библиотека для CloudTips (получение донатов, поллинг, обновление токенов)
-Project-URL: Repository, https://github.com/IRRatium/cloudtips-api
-Project-URL: Issues, https://github.com/IRRatium/cloudtips-api/issues
-License: MIT
-License-File: LICENSE
-Keywords: api,cloudtips,donations,payments,tips
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Python: >=3.9
-Requires-Dist: requests>=2.28
-Description-Content-Type: text/markdown
-
-# CloudtipsAPI
-
-Неофициальная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
-
-## Установка
-
-```bash
-pip install cloudtips
-```
-
-## Быстрый старт
-
-```python
-import json
-from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
-
-# Загружаем токены из файла (donate.json или своего хранилища)
-with open("donate.json") as f:
-    config = json.load(f)
-
-# Колбэк вызывается каждый раз при обновлении токенов.
-# Refresh-токен одноразовый — обязательно сохраняйте новые!
-def on_token_refresh(token_data: TokenData):
-    config["cloudtips_token"] = token_data.access_token
-    config["cloudtips_refresh_token"] = token_data.refresh_token
-    config["cloudtips_expires_at"] = token_data.expires_at
-    with open("donate.json", "w") as f:
-        json.dump(config, f, ensure_ascii=False, indent=2)
-    print("Токены обновлены и сохранены.")
-
-auth = CloudTipsAuth(
-    token=config["cloudtips_token"],
-    refresh_token=config["cloudtips_refresh_token"],
-    expires_at=config["cloudtips_expires_at"],
-    on_token_refresh=on_token_refresh,
-)
-
-client = CloudTipsClient(auth)
-```
-
-## Получение донатов
-
-```python
-# Все донаты
-donations = client.get_all_donations()
-for d in donations:
-    print(d)  # [2026-04-10 20:44] евгения → 50₽ — "оч крутой сервис"
-
-# Только за последние сутки
-from datetime import datetime, timedelta, timezone
-
-yesterday = datetime.now(tz=timezone.utc) - timedelta(days=1)
-recent = client.get_donations(since=yesterday)
-```
-
-## Поллинг новых донатов
-
-### Вариант 1 — генератор (блокирует поток)
-
-```python
-print("Слушаем новые донаты...")
-for donation in client.poll(interval=30):
-    print(f"💰 {donation.name} задонатил {donation.amount}₽")
-    if donation.comment:
-        print(f"   Комментарий: {donation.comment}")
-```
-
-### Вариант 2 — колбэк
-
-```python
-def handle_donation(donation):
-    print(f"Новый донат от {donation.name}: {donation.amount}₽")
-
-# Блокирующий вызов, удобно для простых скриптов
-client.poll(interval=15, callback=handle_donation)
-```
-
-### Вариант 3 — в отдельном потоке
-
-```python
-import threading
-
-thread = threading.Thread(
-    target=client.poll,
-    kwargs={"interval": 30, "callback": handle_donation},
-    daemon=True,
-)
-thread.start()
-
-# Основная логика программы продолжается...
-```
-
-## Структура `Donation`
-
-```python
-@dataclass
-class Donation:
-    transaction_id: int    # уникальный ID транзакции
-    name: str              # имя донатера
-    amount: int            # сумма в рублях
-    tg_id: int             # Telegram ID
-    comment: str           # комментарий (может быть пустым)
-    date: datetime         # дата и время
-
-str(donation)
-# "[2026-04-10 23:04] Каспер → 200₽ — "спасибо за отличный сервис)""
-```
-
-## Обработка ошибок
-
-```python
-from cloudtips import CloudTipsAuthError, CloudTipsAPIError
-
-try:
-    donations = client.get_donations()
-except CloudTipsAuthError as e:
-    print(f"Проблема с аутентификацией: {e}")
-except CloudTipsAPIError as e:
-    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
-```
-
-## Примечания
-
-- **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
-- Библиотека автоматически обновляет токен за 2 минуты до истечения.
-- Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
-
-## Лицензия
-
-MIT

cloudtips-0.3.0/README.md

@@ -1,130 +0,0 @@
-# CloudtipsAPI
-
-Неофициальная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
-
-## Установка
-
-```bash
-pip install cloudtips
-```
-
-## Быстрый старт
-
-```python
-import json
-from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
-
-# Загружаем токены из файла (donate.json или своего хранилища)
-with open("donate.json") as f:
-    config = json.load(f)
-
-# Колбэк вызывается каждый раз при обновлении токенов.
-# Refresh-токен одноразовый — обязательно сохраняйте новые!
-def on_token_refresh(token_data: TokenData):
-    config["cloudtips_token"] = token_data.access_token
-    config["cloudtips_refresh_token"] = token_data.refresh_token
-    config["cloudtips_expires_at"] = token_data.expires_at
-    with open("donate.json", "w") as f:
-        json.dump(config, f, ensure_ascii=False, indent=2)
-    print("Токены обновлены и сохранены.")
-
-auth = CloudTipsAuth(
-    token=config["cloudtips_token"],
-    refresh_token=config["cloudtips_refresh_token"],
-    expires_at=config["cloudtips_expires_at"],
-    on_token_refresh=on_token_refresh,
-)
-
-client = CloudTipsClient(auth)
-```
-
-## Получение донатов
-
-```python
-# Все донаты
-donations = client.get_all_donations()
-for d in donations:
-    print(d)  # [2026-04-10 20:44] евгения → 50₽ — "оч крутой сервис"
-
-# Только за последние сутки
-from datetime import datetime, timedelta, timezone
-
-yesterday = datetime.now(tz=timezone.utc) - timedelta(days=1)
-recent = client.get_donations(since=yesterday)
-```
-
-## Поллинг новых донатов
-
-### Вариант 1 — генератор (блокирует поток)
-
-```python
-print("Слушаем новые донаты...")
-for donation in client.poll(interval=30):
-    print(f"💰 {donation.name} задонатил {donation.amount}₽")
-    if donation.comment:
-        print(f"   Комментарий: {donation.comment}")
-```
-
-### Вариант 2 — колбэк
-
-```python
-def handle_donation(donation):
-    print(f"Новый донат от {donation.name}: {donation.amount}₽")
-
-# Блокирующий вызов, удобно для простых скриптов
-client.poll(interval=15, callback=handle_donation)
-```
-
-### Вариант 3 — в отдельном потоке
-
-```python
-import threading
-
-thread = threading.Thread(
-    target=client.poll,
-    kwargs={"interval": 30, "callback": handle_donation},
-    daemon=True,
-)
-thread.start()
-
-# Основная логика программы продолжается...
-```
-
-## Структура `Donation`
-
-```python
-@dataclass
-class Donation:
-    transaction_id: int    # уникальный ID транзакции
-    name: str              # имя донатера
-    amount: int            # сумма в рублях
-    tg_id: int             # Telegram ID
-    comment: str           # комментарий (может быть пустым)
-    date: datetime         # дата и время
-
-str(donation)
-# "[2026-04-10 23:04] Каспер → 200₽ — "спасибо за отличный сервис)""
-```
-
-## Обработка ошибок
-
-```python
-from cloudtips import CloudTipsAuthError, CloudTipsAPIError
-
-try:
-    donations = client.get_donations()
-except CloudTipsAuthError as e:
-    print(f"Проблема с аутентификацией: {e}")
-except CloudTipsAPIError as e:
-    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
-```
-
-## Примечания
-
-- **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
-- Библиотека автоматически обновляет токен за 2 минуты до истечения.
-- Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
-
-## Лицензия
-
-MIT