cloudtips 0.1.0__py3-none-any.whl

cloudtips/__init__.py

@@ -0,0 +1,17 @@
+"""
+cloudtips — неофициальная Python-библиотека для CloudTips.
+"""
+
+from .auth import CloudTipsAuth, CloudTipsAuthError
+from .client import CloudTipsAPIError, CloudTipsClient
+from .models import Donation, TokenData
+
+__version__ = "0.1.0"
+__all__ = [
+    "CloudTipsAuth",
+    "CloudTipsAuthError",
+    "CloudTipsClient",
+    "CloudTipsAPIError",
+    "Donation",
+    "TokenData",
+]

cloudtips/auth.py

@@ -0,0 +1,122 @@
+import time
+from typing import Callable, Optional
+
+import requests
+
+from .models import TokenData
+
+_TOKEN_URL = "https://identity.cloudtips.ru/connect/token"
+_CLIENT_ID = "MobilePhone"
+_EXPIRE_BUFFER = 120  # обновляем токен за 2 минуты до истечения
+
+
+class CloudTipsAuth:
+    """
+    Управляет access/refresh токенами CloudTips.
+
+    Параметр `on_token_refresh` — это колбэк, который вызывается каждый раз
+    после успешного обновления токенов. Используйте его, чтобы сохранить
+    новые токены в файл/БД/переменные окружения — refresh-токен одноразовый!
+
+    Пример::
+
+        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)
+
+        auth = CloudTipsAuth(
+            token="...",
+            refresh_token="...",
+            expires_at=1776099728.0,
+            on_token_refresh=save_tokens,
+        )
+    """
+
+    def __init__(
+        self,
+        token: str,
+        refresh_token: str,
+        expires_at: float,
+        on_token_refresh: Optional[Callable[[TokenData], None]] = None,
+    ) -> None:
+        self._token = token
+        self._refresh_token = refresh_token
+        self._expires_at = expires_at
+        self._on_token_refresh = on_token_refresh
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+
+    @property
+    def token(self) -> str:
+        """Возвращает актуальный access-токен, автоматически обновляя при необходимости."""
+        if self._is_expired():
+            self.refresh()
+        return self._token
+
+    @property
+    def expires_at(self) -> float:
+        return self._expires_at
+
+    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)
+
+        data = response.json()
+        token_data = TokenData(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_at=time.time() + data["expires_in"],
+        )
+
+        self._token = token_data.access_token
+        self._refresh_token = token_data.refresh_token
+        self._expires_at = token_data.expires_at
+
+        if self._on_token_refresh:
+            self._on_token_refresh(token_data)
+
+        return token_data
+
+    def headers(self) -> dict:
+        """Готовые Authorization-заголовки для запросов."""
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    def _is_expired(self) -> bool:
+        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:
+        try:
+            detail = response.json()
+        except Exception:
+            detail = response.text
+        raise CloudTipsAuthError(
+            f"Ошибка при обновлении токена: {response.status_code} — {detail}"
+        ) from e
+
+
+class CloudTipsAuthError(Exception):
+    """Ошибка аутентификации CloudTips."""

cloudtips/client.py

@@ -0,0 +1,173 @@
+"""
+Клиент CloudTips API.
+"""
+import time
+from datetime import datetime, timezone
+from typing import Callable, Iterator, List, Optional
+
+import requests
+
+from .auth import CloudTipsAuth
+from .models import Donation
+
+_BASE_URL = "https://api.cloudtips.ru"
+
+
+class CloudTipsClient:
+    """
+    Основной клиент для работы с CloudTips API.
+
+    Пример быстрого старта::
+
+        from cloudtips import CloudTipsClient, CloudTipsAuth
+
+        auth = CloudTipsAuth(
+            token="...",
+            refresh_token="...",
+            expires_at=1776099728.0,
+            on_token_refresh=lambda td: print("Новый токен:", td.access_token),
+        )
+        client = CloudTipsClient(auth)
+
+        # Получить все донаты
+        donations = client.get_donations()
+
+        # Поллинг новых донатов каждые 30 секунд
+        for donation in client.poll(interval=30):
+            print(donation)
+    """
+
+    def __init__(self, auth: CloudTipsAuth, base_url: str = _BASE_URL) -> None:
+        self._auth = auth
+        self._base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+
+    # ------------------------------------------------------------------
+    # Основные методы
+    # ------------------------------------------------------------------
+
+    def get_donations(
+        self,
+        since: Optional[datetime] = None,
+        limit: int = 100,
+        page: int = 1,
+    ) -> List[Donation]:
+        """
+        Получить список донатов.
+
+        :param since: фильтр — только донаты после этого момента
+        :param limit: кол-во на страницу (max обычно 100)
+        :param page: номер страницы
+        :return: список :class:`Donation`
+        """
+        params: dict = {"pageSize": limit, "page": page}
+        if since is not None:
+            params["from"] = since.isoformat()
+
+        data = self._get("/api/payments", params=params)
+
+        items = data if isinstance(data, list) else data.get("items", data.get("payments", []))
+        return [Donation.from_dict(item) for item in items]
+
+    def get_all_donations(self, since: Optional[datetime] = None) -> List[Donation]:
+        """
+        Получить все донаты с автопагинацией.
+
+        :param since: фильтр по дате
+        :return: полный список :class:`Donation`
+        """
+        result: List[Donation] = []
+        page = 1
+        while True:
+            batch = self.get_donations(since=since, limit=100, page=page)
+            if not batch:
+                break
+            result.extend(batch)
+            if len(batch) < 100:
+                break
+            page += 1
+        return sorted(result, key=lambda d: d.date)
+
+    def poll(
+        self,
+        interval: int = 30,
+        since: Optional[datetime] = None,
+        callback: Optional[Callable[[Donation], None]] = None,
+    ) -> Iterator[Donation]:
+        """
+        Генератор: бесконечный поллинг новых донатов.
+
+        Каждые ``interval`` секунд опрашивает API и отдаёт только **новые**
+        донаты (те, что появились после последнего запроса).
+
+        Использование как генератора::
+
+            for donation in client.poll(interval=15):
+                print(f"Новый донат: {donation}")
+
+        Или с колбэком (блокирующий режим)::
+
+            client.poll(interval=15, callback=handle_donation)
+
+        :param interval: пауза между запросами в секундах
+        :param since: с какого момента начинать (по умолчанию — «прямо сейчас»)
+        :param callback: если передан — метод блокируется и вызывает колбэк
+        """
+        last_seen_ids: set = set()
+        cursor = since or datetime.now(tz=timezone.utc)
+
+        # Первый запрос — грузим уже известные, не отдаём как "новые"
+        for d in self.get_all_donations(since=cursor):
+            last_seen_ids.add(d.transaction_id)
+
+        while True:
+            time.sleep(interval)
+
+            try:
+                fresh = self.get_all_donations(since=cursor)
+            except Exception as exc:
+                # Не падаем, просто пробуем снова на следующей итерации
+                print(f"[cloudtips] Ошибка при поллинге: {exc}")
+                continue
+
+            for donation in fresh:
+                if donation.transaction_id not in last_seen_ids:
+                    last_seen_ids.add(donation.transaction_id)
+                    cursor = max(cursor, donation.date)
+                    if callback:
+                        callback(donation)
+                    else:
+                        yield donation
+
+    # ------------------------------------------------------------------
+    # Вспомогательные
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        url = self._base_url + path
+        response = self._session.get(
+            url,
+            headers=self._auth.headers(),
+            params=params,
+            timeout=15,
+        )
+        _raise_for_status(response)
+        return response.json()
+
+
+class CloudTipsAPIError(Exception):
+    """Ошибка запроса к CloudTips API."""
+
+    def __init__(self, status_code: int, detail: object) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+def _raise_for_status(response: requests.Response) -> None:
+    if not response.ok:
+        try:
+            detail = response.json()
+        except Exception:
+            detail = response.text
+        raise CloudTipsAPIError(response.status_code, detail)

cloudtips/models.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Donation:
+    transaction_id: int
+    name: str
+    amount: int          # рубли
+    tg_id: int
+    comment: str
+    date: datetime
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Donation":
+        raw_date = data["date"]
+        # Убираем offset вида +03:00 → datetime aware через fromisoformat (3.11+)
+        # или ручной парсинг для 3.9/3.10
+        try:
+            dt = datetime.fromisoformat(raw_date)
+        except ValueError:
+            # fallback: обрезаем offset
+            dt = datetime.fromisoformat(raw_date[:19])
+
+        return cls(
+            transaction_id=data["transaction_id"],
+            name=data.get("name", ""),
+            amount=data["amount"],
+            tg_id=data.get("tg_id", 0),
+            comment=data.get("comment", ""),
+            date=dt,
+        )
+
+    def __str__(self) -> str:
+        comment_part = f' — "{self.comment}"' if self.comment else ""
+        return (
+            f"[{self.date.strftime('%Y-%m-%d %H:%M')}] "
+            f"{self.name} → {self.amount}₽{comment_part}"
+        )
+
+
+@dataclass
+class TokenData:
+    """Новые токены, которые библиотека передаёт в on_token_refresh."""
+    access_token: str
+    refresh_token: str
+    expires_at: float   # unix timestamp

cloudtips-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: cloudtips
+Version: 0.1.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.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cloudtips/__init__.py,sha256=SwfI5QmOmDg43EmugF4Z3JCxsBoglzt2zUPuiaRtUNY,408
+cloudtips/auth.py,sha256=f5iCu21Ceve6uBhzJs6daE0GI5oWETtZmzMdhNnlaLk,4097
+cloudtips/client.py,sha256=sttHkDJG1ePQ4AQ5PYwrhbzgscJ2GRNmiC7d_otzEUg,6208
+cloudtips/models.py,sha256=oq_UWMrmKQKulAHcUzEqWJV6l_CGGJbnTsTg8-eviPI,1445
+cloudtips-0.1.0.dist-info/METADATA,sha256=YzuxiI6I0N_tRe1WTRjmQHact7XuOi_M_Nkk-kNiQjU,5322
+cloudtips-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cloudtips-0.1.0.dist-info/licenses/LICENSE,sha256=t8Gzws0s2LPgRwASRw9MHAvwQJwVYTcFW0CoPTbllL0,1063
+cloudtips-0.1.0.dist-info/RECORD,,

cloudtips-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudtips-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IRRing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.