Metadata-Version: 2.4
Name: midasbuy-sdk
Version: 0.1.0
Summary: Client for the Midasbuy code-activation API — free tier included
Project-URL: Homepage, https://github.com/zlexdev/midasbuy-sdk
Project-URL: Issues, https://github.com/zlexdev/midasbuy-sdk/issues
License: MIT
License-File: LICENSE
Keywords: activation,api,midasbuy,pubg,sdk,uc
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# midasbuy-sdk

Python-клиент для API активации кодов Midasbuy.

Есть **бесплатный тариф**: ключ выдаётся без регистрации и без оплаты. Это
**бета** — лимиты временные и будут пересмотрены по её итогам.

```bash
pip install midasbuy-sdk
```

## Как получить ключ

Напишите Telegram-боту `@midasbuy_api_bot` команду `/free`.

К заявке приложите ссылки на свои профили на площадках, где вы торгуете, и
скриншоты-подтверждения. Это единственный барьер: он стоит не ради формальности,
а чтобы бесплатные ключи не разошлись пачками по одноразовым аккаунтам.

Один бесплатный ключ в одни руки. Повторная заявка вернёт тот же ключ.

## Первый вызов

```python
from midasbuy_sdk import MidasbuyClient

with MidasbuyClient("ваш-ключ") as client:
    # 1. подключите свой Midas-аккаунт — активировать нужно на него
    account = client.connect_account(cookies="...", game="pubgm")

    # 2. активируйте код
    accepted = client.activate("CODE-1234", account_id=account.account_id)

    # 3. дождитесь результата
    result = client.wait_for(accepted.activation_id)
    print(result.status, result.granted_item)
```

Асинхронно — те же имена методов:

```python
from midasbuy_sdk import AsyncMidasbuyClient

async with AsyncMidasbuyClient("ваш-ключ") as client:
    accepted = await client.activate("CODE-1234", account_id="acc_...")
    result = await client.wait_for(accepted.activation_id)
```

## Что делает клиент за вас

**Ключ идемпотентности.** Каждый POST уходит с `Idempotency-Key`, и повтор
использует **тот же** ключ. Поэтому таймаут или 429 не превращают одну
активацию в две. Свой ключ можно передать явно — тогда и ваш собственный ретрай
схлопнется в одну операцию:

```python
client.activate("CODE-1234", account_id="acc_...", idempotency_key="order-42")
```

**Отступ при 429.** Превышение темпа — это не ошибка, а обратное давление:
клиент ждёт `Retry-After` и продолжает. Исключение `RateLimited` вы увидите
только когда ретраи кончились.

## Ошибки

Каждая — отдельный тип, у всех есть `code` и `request_id` (его удобно
цитировать в поддержке).

- `RateLimited` — слишком быстро. Поле `retry_after`, ничего не потрачено.
- `DailyCapReached` — исчерпан суточный потолок активаций, в `reset_at` время сброса.
- `AuthFailed` — ключ не принят. Сервис намеренно не уточняет, почему.
- `OutOfStock` — кода такого номинала нет в вашем стоке.
- `NotFound` — объекта нет либо он чужой; API эти случаи не различает.
- `WaitTimeout` — `wait_for` не дождался. Активация всё ещё выполняется:
  опросите `get_activation` позже. **Повторно активировать код нельзя** — он
  спишется дважды.

## Методы

| Метод | Что делает |
|---|---|
| `connect_account(cookies, game=)` | Подключить свой Midas-аккаунт |
| `list_accounts()` | Подключённые аккаунты |
| `activate(code, account_id=)` | Активировать один код |
| `activate_batch(denomination_value=, quantity=, account_id=, game=)` | Активировать пачку из своего стока |
| `get_activation(id)` | Статус одной активации |
| `activation_statuses(ids)` | Статусы многих активаций одним вызовом |
| `wait_for(id, poll=, timeout=)` | Ждать терминального статуса |
| `list_games()` | Поддерживаемые игры |
| `list_packages(game)` | Номиналы одной игры |
| `key_status()` | Состояние ключа: остаток на сегодня, срок |

## Про бету

Пока идёт бета, ограничитель — **темп** запросов, а не суточная квота:
упёршись, вы получаете `429`, ждёте и продолжаете работать. Суточный потолок
активаций тоже есть, но он аварийный.

По итогам беты числа будут пересмотрены, и часть возможностей станет платной —
о том, какие именно, сказано заранее: доставка результатов вебхуками, ссылки
для выдачи и второй подключённый Midas-аккаунт.

## Лицензия

MIT.
