playerok-requests-api 0.1.6
Библиотека для взаимодействия с GraphQL API платформы Playerok
Requires Python: >=3.6


## Установка

```bash
pip install playerok-requests-api
```

## Требования

- Python 3.6+
- Библиотека `wrapper-tls-requests==1.1.2`
- Файл cookies (`cookies.json`) для аутентификации

## Использование

```python
from playerok_requests_api.users import PlayerokUsersApi

api = PlayerokUsersApi(cookies_file="cookies.json", logger=True)
profile = api.get_profile()
if profile:
    print(f"Ник: {profile[0]}, Всего товаров: {profile[2]}")
```

## Содержание

- [Обзор](#обзор)
- [Документация](#документация)
  - [Пользователи](#пользователи)
  - [Сделки](#сделки)
  - [Товары](#товары)
  - [Чаты](#чаты)
- [Лицензия](#лицензия)

## Обзор

API разделён на четыре основных модуля, каждый из которых отвечает за определённый аспект работы с платформой Playerok:

- **Пользователи**: Управление профилями пользователей, балансами и связанной информацией.
- **Сделки**: Работа со сделками, включая подтверждение сделок и получение оплаченных сделок.
- **Товары**: Управление товарами (лотами) на платформе, включая получение, копирование и повышение приоритета товаров.
- **Чаты**: Взаимодействие с функционалом чатов, включая отправку сообщений и получение статусов сообщений.

## Документация

### Пользователи

Модуль `PlayerokUsersApi` предоставляет функционал для управления информацией о пользователях на платформе Playerok. Он позволяет получать данные о профиле, балансе, а также ID пользователя по его имени.

#### Инициализация

```python
from playerok_requests_api.users import PlayerokUsersApi

api = PlayerokUsersApi(cookies_file="cookies.json", logger=False)
```

- **cookies_file**: Путь к файлу с cookies для аутентификации (по умолчанию `cookies.json`).
- **logger**: Включение/выключение логирования (по умолчанию `False`).

#### Методы

| Метод                     | Описание                                                                 | Возвращаемое значение                     |
|---------------------------|--------------------------------------------------------------------------|------------------------------------------|
| `get_username()`          | Получает имя пользователя и ID текущего аккаунта из cookies.             | Кортеж `(username, id)` или `('', '')` при ошибке. |
| `get_id_for_username(username)` | Получает ID пользователя по его имени.                              | `str` (ID) или `None` при ошибке.        |
| `get_balance()`           | Получает информацию о балансе аккаунта.                                  | Словарь с ключами `AllBalance`, `available`, `pendingIncome`, `frozen` или `None`. |
| `get_full_info()`         | Получает полную информацию о профиле пользователя.                       | Словарь с данными профиля или `None`.    |
| `get_profile()`           | Получает краткую информацию о профиле (ник, отзывы, товары, сделки).     | Кортеж `(nickname, testimonial_count, total_items, purchases_total, sales_total, active_items, finished_items)` или `None`. |

#### Пример использования

##### Получение профиля пользователя

```python
profile = api.get_profile()
if profile:
    print(f"Ник: {profile[0]}")
    print(f"Количество отзывов: {profile[1]}")
    print(f"Всего товаров: {profile[2]}")
else:
    print("Ошибка при получении профиля")
```

##### Получение баланса

```python
balance = api.get_balance()
if balance:
    print(f"Общий баланс: {balance['AllBalance']}")
    print(f"Доступно: {balance['available']}")
else:
    print("Ошибка при получении баланса")
```

#### Обработка ошибок

- При ошибках запросов (например, неверные cookies или проблемы с API) методы возвращают `None` и выводят сообщение об ошибке.
- Включите логирование (`logger=True`) для получения дополнительной информации об ошибках.

### Сделки

Модуль `PlayerokDealsApi` предоставляет функционал для работы со сделками на платформе Playerok. Он позволяет подтверждать сделки и получать список оплаченных сделок.

#### Инициализация

```python
from playerok_requests_api.deals import PlayerokDealsApi

api = PlayerokDealsApi(cookies_file="cookies.json", logger=False)
```

- **cookies_file**: Путь к файлу с cookies для аутентификации (по умолчанию `cookies.json`).
- **logger**: Включение/выключение логирования (по умолчанию `False`).

#### Методы

| Метод                     | Описание                                                                 | Возвращаемое значение                     |
|---------------------------|--------------------------------------------------------------------------|------------------------------------------|
| `get_username()`          | Получает имя пользователя и ID текущего аккаунта из cookies.             | Кортеж `(username, id)` или `('', '')` при ошибке. |
| `deal_confirm(id)`        | Подтверждает сделку по её ID.                                            | Словарь с ответом API или `None` при ошибке. |
| `get_actual_deals()`      | Получает список актуальных оплаченных сделок для текущего пользователя.  | Словарь с данными сделок или `None` при ошибке. |

#### Пример использования

##### Подтверждение сделки

```python
deal_id = "12345"
response = api.deal_confirm(deal_id)
if response:
    print("Сделка успешно подтверждена:", response)
else:
    print("Ошибка при подтверждении сделки")
```

##### Получение актуальных сделок

```python
deals = api.get_actual_deals()
if deals:
    print("Актуальные сделки:", deals)
else:
    print("Ошибка при получении сделок")
```

#### Обработка ошибок

- При ошибках (например, неверный ID сделки или проблемы с API) методы возвращают `None` и выводят сообщение об ошибке.
- Включите логирование (`logger=True`) для диагностики проблем.

### Товары

Модуль `PlayerokItemsApi` предоставляет функционал для управления товарами (лотами) на платформе Playerok. Он позволяет получать информацию о товарах, копировать товары, повышать их приоритет и возобновлять завершенные лоты.

#### Инициализация

```python
from playerok_requests_api.items import PlayerokItemsApi

api = PlayerokItemsApi(cookies_file="cookies.json", logger=False)
```

- **cookies_file**: Путь к файлу с cookies для аутентификации (по умолчанию `cookies.json`).
- **logger**: Включение/выключение логирования (по умолчанию `False`).

#### Методы

| Метод                            | Описание                                                                 | Возвращаемое значение                     |
|----------------------------------|--------------------------------------------------------------------------|------------------------------------------|
| `get_username()`                 | Получает имя пользователя и ID текущего аккаунта из cookies.             | Кортеж `(username, id)` или `('', '')` при ошибке. |
| `fetch_lots(after_cursor=None)`  | Получает завершенные лоты с пагинацией.                                  | Словарь с данными лотов или `None` при ошибке. |
| `fetch_exhibited_lots(userid=None, after_cursor=None)` | Получает выставленные лоты (свои или другого пользователя). | Словарь с данными лотов или `None` при ошибке. |
| `all_exhibited_lots(userid=None)`| Получает все выставленные лоты (свои или другого пользователя).          | Список словарей с данными лотов.         |
| `get_all_lots(search_filter=None)` | Получает все завершенные лоты с опциональным фильтром поиска.           | Список словарей с данными лотов.         |
| `copy_product(link)`             | Получает данные для выставления товара по ссылке.                       | Словарь с данными товара или `None` при ошибке. |
| `increase_item_priority(item_id)`| Повышает приоритет товара по его ID.                                    | Словарь с ответом API или `None` при ошибке. |
| `refill_item(item_id)`           | Возобновляет завершенный товар по его ID.                               | Словарь с ответом API или `None` при ошибке. |
| `get_product_data(link)`         | Получает полную информацию о товаре по ссылке.                          | Словарь с данными товара или `None` при ошибке. |
| `get_item_positioninfind(item_slug)` | Получает позицию товара на рынке по его slug.                        | `int` (позиция) или ошибка.              |

#### Пример использования

##### Получение всех выставленных лотов

```python
lots = api.all_exhibited_lots()
if lots:
    for lot in lots:
        print(f"Товар: {lot['node']['name']}, Цена: {lot['node']['price']}")
else:
    print("Ошибка при получении лотов")
```

##### Копирование товара

```python
link = "https://playerok.com/products/example-product"
product_data = api.copy_product(link)
if product_data:
    print(f"Название: {product_data['title']}, Цена: {product_data['price']}")
else:
    print("Ошибка при копировании товара")
```

#### Обработка ошибок

- При ошибках (например, неверная ссылка или проблемы с API) методы возвращают `None` или пустой список и выводят сообщение об ошибке.
- Включите логирование (`logger=True`) для получения дополнительной информации.

### Чаты

Модуль `PlayerokChatsApi` предоставляет функционал для работы с чатами на платформе Playerok. Он позволяет отправлять сообщения, получать статусы сообщений, отслеживать новые и непрочитанные сообщения, а также управлять информацией о чатах.

#### Инициализация

```python
from playerok_requests_api.chats import PlayerokChatsApi

api = PlayerokChatsApi(cookies_file="cookies.json", logger=False)
```

- **cookies_file**: Путь к файлу с cookies для аутентификации (по умолчанию `cookies.json`).
- **logger**: Включение/выключение логирования (по умолчанию `False`).

#### Методы

| Метод                            | Описание                                                                 | Возвращаемое значение                     |
|----------------------------------|--------------------------------------------------------------------------|------------------------------------------|
| `get_username()`                 | Получает имя пользователя и ID текущего аккаунта из cookies.             | Кортеж `(username, id)` или `('', '')` при ошибке. |
| `on_username_id_get(profileusername, username)` | Получает ID чата для указанных пользователей.                     | `str` (ID чата) или `None` при ошибке.   |
| `on_send_message(username, text)`| Отправляет сообщение указанному пользователю.                           | Словарь с ответом API или `None` при ошибке. |
| `get_status_messages(difference=300)` | Получает сообщения со статусами сделок за указанный период (в секундах). | Список словарей с данными `{id, status, timestamp}` или `None`. |
| `get_new_messages(interval=5, max_interval=30)` | Получает новые сообщения с периодической проверкой.             | Список словарей с данными `{chat_id, participant, message, date}`. |
| `get_messages_info(unread=False)`| Получает информацию о всех чатах (или только с непрочитанными сообщениями). | Список словарей с данными чатов или `[]`. |
| `fetch_chats(after_cursor=None)` | Получает чаты с пагинацией.                                             | Словарь с данными чатов или `None` при ошибке. |
| `get_unread_messages()`          | Возвращает количество непрочитанных сообщений.                          | `int` (количество сообщений).            |

#### Пример использования

##### Отправка сообщения

```python
username = "example_user"
message = "Привет, как дела?"
response = api.on_send_message(username, message)
if response:
    print("Сообщение отправлено:", response)
else:
    print("Ошибка при отправке сообщения")
```

##### Получение новых сообщений

```python
new_messages = api.get_new_messages()
if new_messages:
    for msg in new_messages:
        print(f"От: {msg['participant']}, Сообщение: {msg['message']}, Время: {msg['date']}")
else:
    print("Новых сообщений нет")
```

##### Подсчет непрочитанных сообщений

```python
unread_count = api.get_unread_messages()
print(f"Непрочитанных сообщений: {unread_count}")
```

#### Обработка ошибок

- При ошибках (например, неверный username, проблемы с API или отсутствие чата) методы возвращают `None`, пустой список или 0 и выводят сообщение об ошибке.
- Включите логирование (`logger=True`) для получения дополнительной информации об ошибках.

#### Примечания

- Метод `get_status_messages` требует доработки для обработки всех страниц сообщений, а не только первой.
- Метод `get_new_messages` работает в цикле с настраиваемыми интервалами проверки, что может быть полезно для мониторинга чатов в реальном времени.

## Лицензия

MIT License