gengineapi 0.1.0__py3-none-any.whl

gengineapi/modules/base.py

@@ -0,0 +1,196 @@
+"""
+Базовый класс для всех модулей API G-Engine.
+
+Содержит общие методы и функциональность, используемые всеми модулями.
+"""
+import logging
+from abc import ABC
+from typing import Any, Dict, List, Optional, Union
+
+from ..http import AsyncHttpClient
+
+
+class BaseApiModule(ABC):
+    """
+    Базовый класс для всех модулей API.
+    
+    Attributes:
+        http_client: HTTP-клиент для выполнения запросов
+        logger: Логгер для записи информации
+    """
+    
+    def __init__(
+        self,
+        http_client: AsyncHttpClient,
+        logger: Optional[logging.Logger] = None,
+    ) -> None:
+        """
+        Инициализация базового класса модуля API.
+        
+        Args:
+            http_client: HTTP-клиент для выполнения запросов
+            logger: Логгер для записи информации (опционально)
+        """
+        self.http_client = http_client
+        self.logger = logger or logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+    
+    async def _get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Выполняет GET-запрос.
+        
+        Args:
+            endpoint: Конечная точка API
+            params: Параметры запроса (опционально)
+            **kwargs: Дополнительные параметры для HTTP-клиента
+            
+        Returns:
+            Any: Данные из ответа API
+        """
+        return await self.http_client.get(endpoint, params=params, **kwargs)
+    
+    async def _post(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Выполняет POST-запрос.
+        
+        Args:
+            endpoint: Конечная точка API
+            data: Данные для отправки (опционально)
+            params: Параметры запроса (опционально)
+            **kwargs: Дополнительные параметры для HTTP-клиента
+            
+        Returns:
+            Any: Данные из ответа API
+        """
+        return await self.http_client.post(endpoint, json_data=data, params=params, **kwargs)
+    
+    async def _put(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Выполняет PUT-запрос.
+        
+        Args:
+            endpoint: Конечная точка API
+            data: Данные для отправки (опционально)
+            params: Параметры запроса (опционально)
+            **kwargs: Дополнительные параметры для HTTP-клиента
+            
+        Returns:
+            Any: Данные из ответа API
+        """
+        return await self.http_client.put(endpoint, json_data=data, params=params, **kwargs)
+    
+    async def _delete(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Выполняет DELETE-запрос.
+        
+        Args:
+            endpoint: Конечная точка API
+            params: Параметры запроса (опционально)
+            data: Данные для отправки (опционально)
+            **kwargs: Дополнительные параметры для HTTP-клиента
+            
+        Returns:
+            Any: Данные из ответа API
+        """
+        return await self.http_client.delete(endpoint, params=params, json_data=data, **kwargs)
+
+    async def _patch(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Выполняет PATCH-запрос.
+        
+        Args:
+            endpoint: Конечная точка API
+            data: Данные для отправки (опционально)
+            params: Параметры запроса (опционально)
+            **kwargs: Дополнительные параметры для HTTP-клиента
+            
+        Returns:
+            Any: Данные из ответа API
+        """
+        return await self.http_client.patch(endpoint, json_data=data, params=params, **kwargs)
+    
+    @staticmethod
+    def extract_data(response: Dict[str, Any]) -> Any:
+        """
+        Извлекает данные из стандартного формата ответа API.
+        
+        Обрабатывает общую структуру ответа G-Engine API:
+        {
+            "success": true,
+            "message": "...",
+            "data": { ... }
+        }
+        
+        Args:
+            response: Ответ от API
+            
+        Returns:
+            Any: Извлеченные данные или исходный ответ, если не удалось извлечь
+        """
+        if isinstance(response, dict):
+            # Для стандартного формата ответа G-Engine API
+            if "success" in response and "data" in response:
+                return response["data"]
+        return response
+    
+    @staticmethod
+    def remove_none_values(data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Удаляет значения None из словаря.
+        
+        Args:
+            data: Исходный словарь
+            
+        Returns:
+            Dict[str, Any]: Словарь без значений None
+        """
+        return {k: v for k, v in data.items() if v is not None}
+    
+    @staticmethod
+    def format_date_param(date_value: Any) -> Optional[str]:
+        """
+        Форматирует параметр даты для API.
+        
+        Args:
+            date_value: Значение даты (может быть строкой, объектом datetime или date)
+            
+        Returns:
+            Optional[str]: Форматированная дата или None, если значение не было предоставлено
+        """
+        if date_value is None:
+            return None
+            
+        if hasattr(date_value, "strftime"):
+            # Если это datetime или date объект
+            return date_value.strftime("%Y-%m-%d")
+            
+        # Предполагаем, что это уже строка
+        return str(date_value)

gengineapi/modules/currencies.py

@@ -0,0 +1,54 @@
+"""
+Модуль для работы с курсами валют в API G-Engine.
+
+Предоставляет методы для получения актуальных курсов валют.
+"""
+from typing import Any, Dict, Literal, Optional, Union
+
+from .base import BaseApiModule
+
+
+# Типы для параметров API
+RateSource = Literal["cb_rf", "steam"]
+CurrencyPair = Literal["USD:RUB", "EUR:RUB"]
+
+
+class CurrenciesModule(BaseApiModule):
+    """
+    Модуль для работы с курсами валют.
+    
+    Предоставляет методы для получения актуальных курсов валют.
+    """
+    
+    async def get_rate(
+        self,
+        source: RateSource,
+        pair: CurrencyPair,
+    ) -> Dict[str, Any]:
+        """
+        Получает актуальный курс валют.
+        
+        Args:
+            source: Источник курса валют ("cb_rf" или "steam")
+            pair: Валютная пара ("USD:RUB" или "EUR:RUB")
+            
+        Returns:
+            Dict[str, Any]: Информация о курсе валют
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     rate = await client.currencies.get_rate(
+            >>>         source="cb_rf",
+            >>>         pair="USD:RUB"
+            >>>     )
+            >>>     print(f"Курс USD:RUB по ЦБ РФ: {rate['currency_rate']}")
+        """
+        params = {
+            "source": source,
+            "pair": pair,
+        }
+        
+        self.logger.info(f"Получение курса валют: источник {source}, пара {pair}")
+        response = await self._get("currencies", params=params)
+        
+        return self.extract_data(response)

gengineapi/modules/finances.py

@@ -0,0 +1,81 @@
+"""
+Модуль для работы с финансами в API G-Engine.
+
+Предоставляет методы для получения данных о финансах по кошелькам пользователей.
+"""
+from datetime import date
+from typing import Any, Dict, List, Optional, Union
+
+from .base import BaseApiModule
+
+
+class FinancesModule(BaseApiModule):
+    """
+    Модуль для работы с финансами.
+    
+    Предоставляет методы для получения финансовой информации по кошелькам пользователей.
+    """
+    
+    async def get_finances(
+        self,
+        user_cache: bool = True,
+        funds_type: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        sort_by: str = "date",
+        sort_order: str = "desc",
+        start_date: Optional[Union[str, date]] = None,
+        end_date: Optional[Union[str, date]] = None,
+        search_field: Optional[str] = None,
+        search_value: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Получает данные о финансах по кошелькам пользователей.
+        
+        Args:
+            user_cache: Использовать кэш пользователя
+            funds_type: Тип средств ("balance" или "cashback")
+            limit: Ограничение на количество результатов (макс. 500)
+            offset: Смещение для пагинации
+            sort_by: Поле для сортировки
+            sort_order: Порядок сортировки ("asc" или "desc")
+            start_date: Начальная дата для фильтрации
+            end_date: Конечная дата для фильтрации
+            search_field: Поле для поиска
+            search_value: Значение для поиска
+            
+        Returns:
+            List[Dict[str, Any]]: Список финансовых данных
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     finances = await client.finances.get_finances(
+            >>>         funds_type="balance",
+            >>>         limit=50,
+            >>>         sort_by="amount",
+            >>>         sort_order="desc"
+            >>>     )
+            >>>     print(f"Получено {len(finances)} финансовых записей")
+        """
+        params = self.remove_none_values({
+            "user_cache": user_cache,
+            "funds_type": funds_type,
+            "limit": limit,
+            "offset": offset,
+            "sort_by": sort_by,
+            "sort_order": sort_order,
+            "start_date": self.format_date_param(start_date),
+            "end_date": self.format_date_param(end_date),
+            "search_field": search_field,
+            "search_value": search_value,
+        })
+        
+        self.logger.info(f"Получение финансовых данных с параметрами: {params}")
+        response = await self._get("finances", params=params)
+        
+        # В этом API ожидаем список данных в поле "data"
+        data = self.extract_data(response)
+        if data is None:
+            return []
+        
+        return data

gengineapi/modules/payments.py

@@ -0,0 +1,115 @@
+"""
+Модуль для работы с платежами в API G-Engine.
+
+Поддерживает создание и верификацию платежей, выполнение платежей и получение статуса платежей.
+"""
+from decimal import Decimal
+from typing import Any, Dict, Optional, Union
+
+from .base import BaseApiModule
+
+
+class PaymentsModule(BaseApiModule):
+    """
+    Модуль для работы с платежами.
+    
+    Предоставляет методы для создания, верификации и выполнения платежей,
+    а также для получения статуса платежей.
+    """
+    
+    async def verify(
+        self,
+        transaction_id: str,
+        service_id: int,
+        account: str,
+        amount: Union[Decimal, float, str],
+        currency: str,
+    ) -> Dict[str, Any]:
+        """
+        Создает и верифицирует платеж.
+        
+        Args:
+            transaction_id: Идентификатор транзакции (UUID)
+            service_id: Идентификатор сервиса
+            account: Аккаунт для пополнения
+            amount: Сумма транзакции
+            currency: Код валюты (3 символа)
+            
+        Returns:
+            Dict[str, Any]: Информация о созданном платеже
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     payment = await client.payments.verify(
+            >>>         transaction_id="b3f1c8d2-4e9a-42f5-bb8d-8e3b6c6c6a7f",
+            >>>         service_id=1,
+            >>>         account="user@example.com",
+            >>>         amount=10.99,
+            >>>         currency="USD"
+            >>>     )
+            >>>     print(f"Создан платеж: {payment['transaction_id']}")
+        """
+        # Преобразуем amount в строку, если это не строка
+        if not isinstance(amount, str):
+            amount = str(amount)
+            
+        data = {
+            "transaction_id": transaction_id,
+            "service_id": service_id,
+            "account": account,
+            "amount": amount,
+            "currency": currency,
+        }
+        
+        self.logger.info(f"Создание платежа: {transaction_id}, сервис: {service_id}, сумма: {amount} {currency}")
+        response = await self._post("payment/verify", data=data)
+        
+        return self.extract_data(response)
+    
+    async def execute(self, transaction_id: str) -> Dict[str, Any]:
+        """
+        Выполняет платеж на основе идентификатора транзакции.
+        
+        Args:
+            transaction_id: Идентификатор транзакции (UUID)
+            
+        Returns:
+            Dict[str, Any]: Результат выполнения платежа
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     result = await client.payments.execute(
+            >>>         transaction_id="b3f1c8d2-4e9a-42f5-bb8d-8e3b6c6c6a7f"
+            >>>     )
+            >>>     print(f"Статус платежа: {result['status_code']}")
+        """
+        data = {"transaction_id": transaction_id}
+        
+        self.logger.info(f"Выполнение платежа для транзакции: {transaction_id}")
+        response = await self._post("payment/execute", data=data)
+        
+        return self.extract_data(response)
+    
+    async def get_status(self, transaction_id: str) -> Dict[str, Any]:
+        """
+        Получает статус платежа.
+        
+        Args:
+            transaction_id: Идентификатор транзакции (UUID)
+            
+        Returns:
+            Dict[str, Any]: Статус платежа
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     status = await client.payments.get_status(
+            >>>         transaction_id="b3f1c8d2-4e9a-42f5-bb8d-8e3b6c6c6a7f"
+            >>>     )
+            >>>     print(f"Текущий статус платежа: {status['status_code']}")
+        """
+        params = {"transaction_id": transaction_id}
+        
+        self.logger.info(f"Получение статуса платежа для транзакции: {transaction_id}")
+        response = await self._get("payment/status", params=params)
+        
+        return self.extract_data(response)

gengineapi/modules/transactions.py

@@ -0,0 +1,70 @@
+"""
+Модуль для работы с транзакциями в API G-Engine.
+
+Предоставляет методы для получения списка транзакций с различными фильтрами.
+"""
+from datetime import date
+from typing import Any, Dict, List, Optional, Union
+
+from .base import BaseApiModule
+
+
+class TransactionsModule(BaseApiModule):
+    """
+    Модуль для работы с транзакциями.
+    
+    Предоставляет методы для получения списка транзакций с различными фильтрами.
+    """
+    
+    async def get_transactions(
+        self,
+        user_cache: bool = True,
+        limit: int = 100,
+        offset: int = 0,
+        sort_by: str = "date",
+        sort_order: str = "desc",
+        start_date: Optional[Union[str, date]] = None,
+        end_date: Optional[Union[str, date]] = None,
+        search_field: Optional[str] = None,
+        search_value: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Получает список транзакций.
+        
+        Args:
+            user_cache: Использовать кэш пользователя
+            limit: Ограничение на количество результатов (макс. 500)
+            offset: Смещение для пагинации
+            sort_by: Поле для сортировки
+            sort_order: Порядок сортировки ("asc" или "desc")
+            start_date: Начальная дата для фильтрации
+            end_date: Конечная дата для фильтрации
+            search_field: Поле для поиска
+            search_value: Значение для поиска
+            
+        Returns:
+            List[Dict[str, Any]]: Список транзакций
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     transactions = await client.transactions.get_transactions(
+            >>>         limit=50,
+            >>>         start_date="2023-01-01",
+            >>>         end_date="2023-12-31"
+            >>>     )
+            >>>     print(f"Получено {len(transactions)} транзакций")
+        """
+        params = self.remove_none_values({
+            "user_cache": user_cache,
+            "limit": limit,
+            "offset": offset,
+            "sort_by": sort_by,
+            "sort_order": sort_order,
+            "start_date": self.format_date_param(start_date),
+            "end_date": self.format_date_param(end_date),
+            "search_field": search_field,
+            "search_value": search_value,
+        })
+        
+        self.logger.info(f"Получение списка транзакций с параметрами: {params}")
+        return await self._get("transaction/view", params=params)

gengineapi/modules/users.py

@@ -0,0 +1,100 @@
+"""
+Модуль для работы с пользователями в API G-Engine.
+
+Предоставляет методы для получения информации о пользователях, их балансах и текущем пользователе.
+"""
+from datetime import date
+from typing import Any, Dict, List, Optional, Union
+
+from .base import BaseApiModule
+
+
+class UsersModule(BaseApiModule):
+    """
+    Модуль для работы с пользователями.
+    
+    Предоставляет методы для получения информации о пользователях,
+    их балансах и текущем пользователе.
+    """
+    
+    async def get_users(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        start_date: Optional[Union[str, date]] = None,
+        end_date: Optional[Union[str, date]] = None,
+        search_field: Optional[str] = None,
+        search_value: Optional[str] = None,
+        role_name: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Получает список пользователей (только для Observer).
+        
+        Args:
+            limit: Ограничение на количество результатов (макс. 500)
+            offset: Смещение для пагинации
+            sort_by: Поле для сортировки
+            sort_order: Порядок сортировки ("asc" или "desc")
+            start_date: Начальная дата для фильтрации
+            end_date: Конечная дата для фильтрации
+            search_field: Поле для поиска
+            search_value: Значение для поиска
+            role_name: Название роли для фильтрации
+            
+        Returns:
+            List[Dict[str, Any]]: Список пользователей
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     users = await client.users.get_users(
+            >>>         limit=50,
+            >>>         role_name="User"
+            >>>     )
+            >>>     print(f"Получено {len(users)} пользователей")
+        """
+        params = self.remove_none_values({
+            "limit": limit,
+            "offset": offset,
+            "sort_by": sort_by,
+            "sort_order": sort_order,
+            "start_date": self.format_date_param(start_date),
+            "end_date": self.format_date_param(end_date),
+            "search_field": search_field,
+            "search_value": search_value,
+            "role_name": role_name,
+        })
+        
+        self.logger.info(f"Получение списка пользователей с параметрами: {params}")
+        return await self._get("user", params=params)
+    
+    async def get_balance(self) -> Dict[str, Any]:
+        """
+        Получает баланс текущего пользователя.
+        
+        Returns:
+            Dict[str, Any]: Информация о балансе пользователя
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     balance = await client.users.get_balance()
+            >>>     print(f"Баланс: {balance['balance']} {balance['currency']}")
+        """
+        self.logger.info("Получение баланса текущего пользователя")
+        return await self._get("user/balance")
+    
+    async def get_me(self) -> Dict[str, Any]:
+        """
+        Получает данные текущего пользователя.
+        
+        Returns:
+            Dict[str, Any]: Информация о текущем пользователе
+            
+        Examples:
+            >>> async with Client(...) as client:
+            >>>     user = await client.users.get_me()
+            >>>     print(f"Текущий пользователь: {user['login']}")
+        """
+        self.logger.info("Получение данных текущего пользователя")
+        return await self._get("user/me")