midasbuy-sdk 0.1.0__tar.gz

midasbuy_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Types
+        run: mypy
+
+      - name: Tests
+        run: pytest -q

midasbuy_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+# Publish to PyPI on a version tag, via a Trusted Publisher (OIDC).
+#
+# No API token lives in this repository. PyPI is configured once, by hand, to
+# trust THIS repo + THIS workflow file + the `pypi` environment; the job then
+# exchanges a short-lived OIDC token for upload rights. A leaked repo secret
+# cannot publish, because there is no secret to leak.
+#
+# One-time setup on PyPI (Project → Publishing → Add a new pending publisher):
+#   owner: zlexdev · repo: midasbuy-sdk · workflow: publish.yml · environment: pypi
+#
+# Cutting a release:
+#   1. bump `version` in pyproject.toml AND `__version__` in __init__.py
+#   2. git tag v0.1.0 && git push origin v0.1.0
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" build
+
+      # The gate: a broken release is worse than a late one.
+      - name: Checks
+        run: |
+          ruff check .
+          mypy
+          pytest -q
+
+      # The tag IS the version — a mismatch means the wheel on PyPI would not
+      # match the source at that tag, and that is unfixable after upload.
+      - name: Tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c 'import tomllib,pathlib;print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          test "$tag" = "$pkg" || { echo "tag $tag != version $pkg"; exit 1; }
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # the OIDC token exchanged for upload rights
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

midasbuy_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

midasbuy_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlexdev
+
+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.

midasbuy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+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.

midasbuy_sdk-0.1.0/README.md

@@ -0,0 +1,105 @@
+# 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.

midasbuy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "midasbuy-sdk"
+version = "0.1.0"
+description = "Client for the Midasbuy code-activation API — free tier included"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["midasbuy", "pubg", "uc", "activation", "api", "sdk"]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/zlexdev/midasbuy-sdk"
+Issues = "https://github.com/zlexdev/midasbuy-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.21", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/midasbuy_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

midasbuy_sdk-0.1.0/src/midasbuy_sdk/__init__.py

@@ -0,0 +1,57 @@
+"""midasbuy-sdk — a small client for the Midasbuy activation API.
+
+    from midasbuy_sdk import MidasbuyClient
+
+    with MidasbuyClient("your-key") as client:
+        accepted = client.activate("CODE-1234", account_id="acc_…")
+        result = client.wait_for(accepted.activation_id)
+        print(result.status, result.granted_item)
+
+The free tier is a **beta**: its limits are temporary and will be re-set from
+what the beta measures. Get a key from the Telegram bot — see the README.
+"""
+
+from midasbuy_sdk.client import DEFAULT_BASE_URL, AsyncMidasbuyClient, MidasbuyClient
+from midasbuy_sdk.errors import (
+    AuthFailed,
+    DailyCapReached,
+    MidasbuyError,
+    NotFound,
+    OutOfStock,
+    RateLimited,
+    ServerError,
+    ValidationFailed,
+    WaitTimeout,
+)
+from midasbuy_sdk.models import (
+    Accepted,
+    AccountConnect,
+    Activation,
+    BatchAccepted,
+    KeyStatus,
+    Package,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Accepted",
+    "AccountConnect",
+    "Activation",
+    "AsyncMidasbuyClient",
+    "AuthFailed",
+    "BatchAccepted",
+    "DailyCapReached",
+    "KeyStatus",
+    "MidasbuyClient",
+    "MidasbuyError",
+    "NotFound",
+    "OutOfStock",
+    "Package",
+    "RateLimited",
+    "ServerError",
+    "ValidationFailed",
+    "WaitTimeout",
+    "__version__",
+]

midasbuy_sdk-0.1.0/src/midasbuy_sdk/client.py

@@ -0,0 +1,364 @@
+"""The client — sync and async, same method names, same behaviour.
+
+Two things it does for you that are easy to get wrong by hand:
+
+* **Idempotency.** Every POST carries an ``Idempotency-Key``. A retry reuses the
+  SAME key, so a timeout or a 429 can never turn one activation into two. Pass
+  your own key when you want a business-level retry to collapse too.
+* **Backoff.** 429 and 5xx are retried with the server's own ``Retry-After``
+  when it sends one. A spent rate budget is normal back-pressure, not an error
+  to handle — by the time you see :class:`RateLimited`, the retries are gone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections.abc import Sequence
+from typing import Any
+
+import httpx
+
+from midasbuy_sdk.errors import DailyCapReached, MidasbuyError, RateLimited, WaitTimeout, error_for
+from midasbuy_sdk.models import (
+    Accepted,
+    AccountConnect,
+    Activation,
+    BatchAccepted,
+    KeyStatus,
+    Package,
+)
+
+DEFAULT_BASE_URL = "https://free.midas.chqcode.dev/v1"
+"""The free contour. Point at your paid host by passing ``base_url=``."""
+
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+_MAX_BACKOFF_S = 30.0
+
+
+class _Common:
+    """Everything that does not care whether the transport blocks."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required — get a free one from the bot")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": "midasbuy-sdk",
+        }
+
+    def _post_headers(self, idempotency_key: str | None) -> dict[str, str]:
+        # Generated per CALL, not per retry: the whole point is that every
+        # attempt of one logical operation carries the same key.
+        return {**self._headers, "Idempotency-Key": idempotency_key or str(uuid.uuid4())}
+
+    @staticmethod
+    def _unwrap(response: httpx.Response) -> dict[str, Any]:
+        request_id = response.headers.get("x-request-id")
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        if response.is_success:
+            data = payload.get("data", payload)
+            return data if isinstance(data, dict) else {"items": data}
+
+        error = payload.get("error", payload) if isinstance(payload, dict) else {}
+        code = error.get("code") if isinstance(error, dict) else None
+        message = (
+            error.get("message") if isinstance(error, dict) else None
+        ) or response.reason_phrase
+        exc = error_for(response.status_code, code, message, request_id)
+        if isinstance(exc, RateLimited):
+            exc.retry_after = _retry_after(response)
+        if isinstance(exc, DailyCapReached) and isinstance(error, dict):
+            exc.reset_at = error.get("reset_at") or (error.get("context") or {}).get("reset_at")
+        raise exc
+
+    def _sleep_for(self, attempt: int, response: httpx.Response | None) -> float:
+        if response is not None:
+            explicit = _retry_after(response, default=0.0)
+            if explicit > 0:
+                return min(explicit, _MAX_BACKOFF_S)
+        return min(2.0**attempt, _MAX_BACKOFF_S)
+
+
+def _retry_after(response: httpx.Response, *, default: float = 1.0) -> float:
+    raw = response.headers.get("retry-after")
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+class MidasbuyClient(_Common):
+    """Blocking client. Use it as a context manager to close the pool."""
+
+    def __init__(self, api_key: str, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = httpx.Client(timeout=self._timeout)
+
+    def __enter__(self) -> MidasbuyClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        headers = self._post_headers(idempotency_key) if method == "POST" else self._headers
+        last: MidasbuyError | None = None
+        for attempt in range(self._max_retries + 1):
+            response = self._http.request(
+                method, f"{self._base_url}{path}", json=json, params=params, headers=headers
+            )
+            if response.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                time.sleep(self._sleep_for(attempt, response))
+                continue
+            try:
+                return self._unwrap(response)
+            except MidasbuyError as exc:
+                last = exc
+                raise
+        raise last or MidasbuyError("request failed")
+
+    def connect_account(
+        self, cookies: str, *, game: str, idempotency_key: str | None = None
+    ) -> AccountConnect:
+        """Link YOUR Midas account. Async: poll ``list_accounts`` for the status."""
+        return AccountConnect.from_json(
+            self._request(
+                "POST",
+                "/accounts/connect",
+                json={"cookies": cookies, "game": game},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def list_accounts(self) -> list[dict[str, Any]]:
+        return list(self._request("GET", "/accounts/list").get("items", []))
+
+    def activate(
+        self, code: str, *, account_id: str, idempotency_key: str | None = None
+    ) -> Accepted:
+        """Activate one code. Returns as soon as the job is queued (202)."""
+        return Accepted.from_json(
+            self._request(
+                "POST",
+                "/redeem/activate",
+                json={"code": code, "account_id": account_id},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def activate_batch(
+        self,
+        *,
+        denomination_value: int,
+        quantity: int,
+        account_id: str,
+        game: str,
+        idempotency_key: str | None = None,
+    ) -> BatchAccepted:
+        """Activate up to ``quantity`` codes of one denomination from your stock."""
+        return BatchAccepted.from_json(
+            self._request(
+                "POST",
+                "/redeem/activate-batch-by-denomination",
+                json={
+                    "denomination_value": denomination_value,
+                    "quantity": quantity,
+                    "account_id": account_id,
+                    "game": game,
+                },
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def get_activation(self, activation_id: str) -> Activation:
+        return Activation.from_json(
+            self._request("GET", "/redeem/get", params={"id": activation_id})
+        )
+
+    def activation_statuses(self, activation_ids: Sequence[str]) -> list[Activation]:
+        """Statuses for many ids in one call — cheaper than polling each."""
+        data = self._request(
+            "POST", "/redeem/status-batch", json={"activation_ids": list(activation_ids)}
+        )
+        return [Activation.from_json(row) for row in data.get("activations", [])]
+
+    def wait_for(
+        self, activation_id: str, *, poll: float = 2.0, timeout: float = 300.0
+    ) -> Activation:
+        """Poll until the activation is terminal. Raises :class:`WaitTimeout` if not."""
+        deadline = time.monotonic() + timeout
+        while True:
+            activation = self.get_activation(activation_id)
+            if activation.is_terminal:
+                return activation
+            if time.monotonic() >= deadline:
+                raise WaitTimeout(
+                    f"activation {activation_id} still {activation.status} after {timeout}s"
+                )
+            time.sleep(poll)
+
+    def list_games(self) -> list[str]:
+        """Games the catalog supports — the ``game`` argument everywhere else."""
+        data = self._request("GET", "/catalog/games")
+        return [str(row.get("code") or row.get("id") or row) for row in data.get("items", [])]
+
+    def list_packages(self, game: str) -> list[Package]:
+        """Purchasable denominations for one game."""
+        data = self._request("GET", "/catalog/items", params={"game": game})
+        return [Package.from_json(row) for row in data.get("items", [])]
+
+    def key_status(self) -> KeyStatus:
+        """Your key: status, expiry, and how much of today's cap is left."""
+        return KeyStatus.from_json(self._request("GET", "/subscription"))
+
+
+class AsyncMidasbuyClient(_Common):
+    """The same eight methods, awaited."""
+
+    def __init__(self, api_key: str, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self._timeout)
+
+    async def __aenter__(self) -> AsyncMidasbuyClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        headers = self._post_headers(idempotency_key) if method == "POST" else self._headers
+        for attempt in range(self._max_retries + 1):
+            response = await self._http.request(
+                method, f"{self._base_url}{path}", json=json, params=params, headers=headers
+            )
+            if response.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                await asyncio.sleep(self._sleep_for(attempt, response))
+                continue
+            return self._unwrap(response)
+        raise MidasbuyError("request failed")
+
+    async def connect_account(
+        self, cookies: str, *, game: str, idempotency_key: str | None = None
+    ) -> AccountConnect:
+        return AccountConnect.from_json(
+            await self._request(
+                "POST",
+                "/accounts/connect",
+                json={"cookies": cookies, "game": game},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def list_accounts(self) -> list[dict[str, Any]]:
+        return list((await self._request("GET", "/accounts/list")).get("items", []))
+
+    async def activate(
+        self, code: str, *, account_id: str, idempotency_key: str | None = None
+    ) -> Accepted:
+        return Accepted.from_json(
+            await self._request(
+                "POST",
+                "/redeem/activate",
+                json={"code": code, "account_id": account_id},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def activate_batch(
+        self,
+        *,
+        denomination_value: int,
+        quantity: int,
+        account_id: str,
+        game: str,
+        idempotency_key: str | None = None,
+    ) -> BatchAccepted:
+        return BatchAccepted.from_json(
+            await self._request(
+                "POST",
+                "/redeem/activate-batch-by-denomination",
+                json={
+                    "denomination_value": denomination_value,
+                    "quantity": quantity,
+                    "account_id": account_id,
+                    "game": game,
+                },
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def get_activation(self, activation_id: str) -> Activation:
+        return Activation.from_json(
+            await self._request("GET", "/redeem/get", params={"id": activation_id})
+        )
+
+    async def activation_statuses(self, activation_ids: Sequence[str]) -> list[Activation]:
+        data = await self._request(
+            "POST", "/redeem/status-batch", json={"activation_ids": list(activation_ids)}
+        )
+        return [Activation.from_json(row) for row in data.get("activations", [])]
+
+    async def wait_for(
+        self, activation_id: str, *, poll: float = 2.0, timeout: float = 300.0
+    ) -> Activation:
+        deadline = time.monotonic() + timeout
+        while True:
+            activation = await self.get_activation(activation_id)
+            if activation.is_terminal:
+                return activation
+            if time.monotonic() >= deadline:
+                raise WaitTimeout(
+                    f"activation {activation_id} still {activation.status} after {timeout}s"
+                )
+            await asyncio.sleep(poll)
+
+    async def list_games(self) -> list[str]:
+        data = await self._request("GET", "/catalog/games")
+        return [str(row.get("code") or row.get("id") or row) for row in data.get("items", [])]
+
+    async def list_packages(self, game: str) -> list[Package]:
+        data = await self._request("GET", "/catalog/items", params={"game": game})
+        return [Package.from_json(row) for row in data.get("items", [])]
+
+    async def key_status(self) -> KeyStatus:
+        return KeyStatus.from_json(await self._request("GET", "/subscription"))

midasbuy_sdk-0.1.0/src/midasbuy_sdk/errors.py

@@ -0,0 +1,110 @@
+"""Typed errors — one per way a call can fail, carrying the facts you need.
+
+Every error keeps ``code`` (the stable machine string from the API) and
+``request_id``, so a support message can quote something the operator can find.
+"""
+
+from __future__ import annotations
+
+
+class MidasbuyError(Exception):
+    """Base for everything this client raises."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status: int | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+        return " · ".join(parts)
+
+
+class AuthFailed(MidasbuyError):
+    """The key is missing, wrong, expired or revoked.
+
+    The API answers a single neutral 401 for all of those on purpose, so this
+    error cannot tell you which — get a fresh key if you believe it is live.
+    """
+
+
+class RateLimited(MidasbuyError):
+    """You are calling faster than the key's per-minute budget.
+
+    Nothing was consumed. Wait ``retry_after`` seconds and continue — this is
+    the beta's normal back-pressure, not a wall.
+    """
+
+    def __init__(self, message: str, *, retry_after: float = 1.0, **kwargs: object) -> None:
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+        self.retry_after = retry_after
+
+
+class DailyCapReached(MidasbuyError):
+    """The key's daily activation stop-loss is spent; it resets at ``reset_at``."""
+
+    def __init__(self, message: str, *, reset_at: str | None = None, **kwargs: object) -> None:
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+        self.reset_at = reset_at
+
+
+class OutOfStock(MidasbuyError):
+    """No code of that denomination is in your stock."""
+
+
+class NotFound(MidasbuyError):
+    """No such object — or it belongs to someone else. The API does not
+    distinguish the two, so neither does this error."""
+
+
+class ValidationFailed(MidasbuyError):
+    """The request body was rejected before anything happened."""
+
+
+class ServerError(MidasbuyError):
+    """The service failed. Retried automatically; this means it kept failing."""
+
+
+class WaitTimeout(MidasbuyError):
+    """``wait_for`` gave up before the activation reached a terminal status.
+
+    The activation is still running — poll ``get_activation`` later. It is NOT
+    safe to re-activate the code: that would spend it twice.
+    """
+
+
+_BY_CODE: dict[str, type[MidasbuyError]] = {
+    "code_out_of_stock": OutOfStock,
+    "activation_window_limit": DailyCapReached,
+    "rate_limited": RateLimited,
+}
+
+
+def error_for(status: int, code: str | None, message: str, request_id: str | None) -> MidasbuyError:
+    """Map an API failure onto the narrowest error class available."""
+    if code and code in _BY_CODE:
+        return _BY_CODE[code](message, code=code, status=status, request_id=request_id)
+    if status == 401:
+        return AuthFailed(message, code=code, status=status, request_id=request_id)
+    if status == 404:
+        return NotFound(message, code=code, status=status, request_id=request_id)
+    if status == 429:
+        return RateLimited(message, code=code, status=status, request_id=request_id)
+    if status in (400, 409, 422):
+        return ValidationFailed(message, code=code, status=status, request_id=request_id)
+    if status >= 500:
+        return ServerError(message, code=code, status=status, request_id=request_id)
+    return MidasbuyError(message, code=code, status=status, request_id=request_id)

midasbuy_sdk-0.1.0/src/midasbuy_sdk/models.py

@@ -0,0 +1,134 @@
+"""What the API gives back, as plain dataclasses.
+
+Deliberately not pydantic: this client should install next to any version of
+anything. Unknown fields are kept in ``raw`` so a server-side addition never
+breaks your code — and so you can read a field this SDK does not model yet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Accepted:
+    """A 202: the work is queued, not done. Poll with ``get_activation``."""
+
+    activation_id: str
+    status: str
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Accepted:
+        return cls(
+            activation_id=str(data.get("activation_id") or data.get("id") or ""),
+            status=str(data.get("status", "pending")),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BatchAccepted:
+    """A batch 202 — ``accepted`` may be lower than you asked for."""
+
+    activation_ids: list[str]
+    accepted: int
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> BatchAccepted:
+        ids = [str(i) for i in data.get("activation_ids", [])]
+        return cls(activation_ids=ids, accepted=int(data.get("accepted", len(ids))), raw=data)
+
+
+@dataclass(frozen=True, slots=True)
+class Activation:
+    id: str
+    status: str
+    granted_item: str | None = None
+    failure_reason: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    TERMINAL: frozenset[str] = frozenset({"success", "failed", "indeterminate"})
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status.lower() in self.TERMINAL
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status.lower() == "success"
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Activation:
+        return cls(
+            id=str(data.get("id", "")),
+            status=str(data.get("status", "")),
+            granted_item=data.get("granted_item"),
+            failure_reason=data.get("failure_reason"),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AccountConnect:
+    account_id: str
+    status: str
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> AccountConnect:
+        return cls(
+            account_id=str(data.get("account_id", "")),
+            status=str(data.get("status", "connecting")),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class KeyStatus:
+    """Your key as the service sees it — what is left and when it resets."""
+
+    status: str
+    expires_at: str | None = None
+    limit_per_day: int | None = None
+    used_today: int | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def remaining_today(self) -> int | None:
+        if self.limit_per_day is None or self.used_today is None:
+            return None
+        return max(0, self.limit_per_day - self.used_today)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> KeyStatus:
+        return cls(
+            status=str(data.get("status", "")),
+            expires_at=data.get("expires_at"),
+            limit_per_day=data.get("limit_per_day"),
+            used_today=data.get("used_today"),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Package:
+    """One purchasable denomination from the catalog."""
+
+    id: str
+    game: str
+    denomination_value: int | None = None
+    title: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Package:
+        return cls(
+            id=str(data.get("id", "")),
+            game=str(data.get("game", "")),
+            denomination_value=data.get("denomination_value"),
+            title=data.get("title") or data.get("name"),
+            raw=data,
+        )

midasbuy_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,178 @@
+"""What must not break: idempotency across retries, error mapping, wait_for."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from midasbuy_sdk import (
+    AsyncMidasbuyClient,
+    AuthFailed,
+    DailyCapReached,
+    MidasbuyClient,
+    OutOfStock,
+    RateLimited,
+    WaitTimeout,
+)
+
+BASE = "https://free.test/v1"
+
+
+def _client(**kwargs: object) -> MidasbuyClient:
+    return MidasbuyClient("key-123", base_url=BASE, **kwargs)  # type: ignore[arg-type]
+
+
+@respx.mock
+def test_activate_returns_the_accepted_id() -> None:
+    respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(
+            202, json={"data": {"activation_id": "act_1", "status": "pending"}}
+        )
+    )
+    with _client() as client:
+        accepted = client.activate("CODE", account_id="acc_1")
+    assert accepted.activation_id == "act_1"
+
+
+@respx.mock
+def test_post_always_carries_an_idempotency_key() -> None:
+    route = respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(202, json={"data": {"activation_id": "act_1"}})
+    )
+    with _client() as client:
+        client.activate("CODE", account_id="acc_1")
+    assert route.calls.last.request.headers["Idempotency-Key"]
+
+
+@respx.mock
+def test_a_retried_429_reuses_the_same_key() -> None:
+    """The one thing that must never break: a retry is not a second activation."""
+    route = respx.post(f"{BASE}/redeem/activate").mock(
+        side_effect=[
+            httpx.Response(
+                429, headers={"Retry-After": "0"}, json={"error": {"code": "rate_limited"}}
+            ),
+            httpx.Response(202, json={"data": {"activation_id": "act_1"}}),
+        ]
+    )
+    with _client() as client:
+        client.activate("CODE", account_id="acc_1")
+
+    keys = {call.request.headers["Idempotency-Key"] for call in route.calls}
+    assert len(route.calls) == 2
+    assert len(keys) == 1
+
+
+@respx.mock
+def test_an_explicit_key_wins() -> None:
+    route = respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(202, json={"data": {"activation_id": "act_1"}})
+    )
+    with _client() as client:
+        client.activate("CODE", account_id="acc_1", idempotency_key="mine-1")
+    assert route.calls.last.request.headers["Idempotency-Key"] == "mine-1"
+
+
+@respx.mock
+def test_rate_limited_after_the_retries_are_spent() -> None:
+    respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(
+            429,
+            headers={"Retry-After": "7"},
+            json={"error": {"code": "rate_limited", "message": "slow down"}},
+        )
+    )
+    with _client(max_retries=0) as client, pytest.raises(RateLimited) as excinfo:
+        client.activate("CODE", account_id="acc_1")
+    assert excinfo.value.retry_after == 7.0
+
+
+@respx.mock
+def test_daily_cap_carries_its_reset() -> None:
+    respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(
+            429,
+            json={
+                "error": {
+                    "code": "activation_window_limit",
+                    "message": "cap reached",
+                    "reset_at": "2026-07-26T00:00:00Z",
+                }
+            },
+        )
+    )
+    with _client(max_retries=0) as client, pytest.raises(DailyCapReached) as excinfo:
+        client.activate("CODE", account_id="acc_1")
+    assert excinfo.value.reset_at == "2026-07-26T00:00:00Z"
+
+
+@respx.mock
+def test_auth_and_stock_errors_are_distinct_types() -> None:
+    respx.get(f"{BASE}/subscription").mock(
+        return_value=httpx.Response(401, json={"error": {"code": "unauthorized", "message": "no"}})
+    )
+    respx.post(f"{BASE}/redeem/activate-batch-by-denomination").mock(
+        return_value=httpx.Response(
+            409, json={"error": {"code": "code_out_of_stock", "message": "empty"}}
+        )
+    )
+    with _client() as client:
+        with pytest.raises(AuthFailed):
+            client.key_status()
+        with pytest.raises(OutOfStock):
+            client.activate_batch(
+                denomination_value=60, quantity=2, account_id="acc_1", game="pubgm"
+            )
+
+
+@respx.mock
+def test_wait_for_polls_until_terminal() -> None:
+    respx.get(f"{BASE}/redeem/get").mock(
+        side_effect=[
+            httpx.Response(200, json={"data": {"id": "act_1", "status": "running"}}),
+            httpx.Response(
+                200, json={"data": {"id": "act_1", "status": "success", "granted_item": "60 UC"}}
+            ),
+        ]
+    )
+    with _client() as client:
+        activation = client.wait_for("act_1", poll=0, timeout=5)
+    assert activation.succeeded
+    assert activation.granted_item == "60 UC"
+
+
+@respx.mock
+def test_wait_for_times_out_without_lying() -> None:
+    respx.get(f"{BASE}/redeem/get").mock(
+        return_value=httpx.Response(200, json={"data": {"id": "act_1", "status": "running"}})
+    )
+    with _client() as client, pytest.raises(WaitTimeout):
+        client.wait_for("act_1", poll=0, timeout=0)
+
+
+@respx.mock
+def test_key_status_reports_what_is_left() -> None:
+    respx.get(f"{BASE}/subscription").mock(
+        return_value=httpx.Response(
+            200, json={"data": {"status": "active", "limit_per_day": 1000, "used_today": 40}}
+        )
+    )
+    with _client() as client:
+        status = client.key_status()
+    assert status.remaining_today == 960
+
+
+@respx.mock
+async def test_async_client_mirrors_the_sync_one() -> None:
+    respx.post(f"{BASE}/redeem/activate").mock(
+        return_value=httpx.Response(202, json={"data": {"activation_id": "act_9"}})
+    )
+    async with AsyncMidasbuyClient("key-123", base_url=BASE) as client:
+        accepted = await client.activate("CODE", account_id="acc_1")
+    assert accepted.activation_id == "act_9"
+
+
+def test_an_empty_key_is_refused_before_any_call() -> None:
+    with pytest.raises(ValueError):
+        MidasbuyClient("")