atraxis-sdk 0.1.0__tar.gz

atraxis_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+

atraxis_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# История изменений
+
+## 0.1.0 — 2026-09-13
+
+- Добавлены синхронный и асинхронный клиенты всех шести методов Atraxis API.
+- Добавлены неизменяемые модели, безопасные ошибки, пагинация и ограниченные повторы.
+- Добавлен локальный MCP-сервер с отдельным явным разрешением на изменения.
+- Добавлена проверяемая публичная копия OpenAPI-контракта.
+- Документация поясняет способы пополнения склада и ограничения выдачи через API.
+- Направление операции определяется по `from` и `to`.

atraxis_sdk-0.1.0/LICENSE

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

atraxis_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: atraxis-sdk
+Version: 0.1.0
+Summary: Official Python SDK and local MCP server for the Atraxis public API
+Project-URL: Documentation, https://atraxisonline.com/developers/api
+Project-URL: Repository, https://github.com/Atraxis/Python-SDK
+Project-URL: Issues, https://github.com/Atraxis/Python-SDK/issues
+Author: Atraxis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,atraxis,mcp,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
+Requires-Dist: mcp<3,>=2.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Atraxis Python SDK
+
+Официальный SDK для владельцев гильдий и лавок Atraxis. Он помогает подключить к гильдии
+своего бота, сайт или учётную систему: посмотреть склад, работать с внутренними валютами,
+выдавать ценности игрокам и получать историю операций.
+
+```bash
+pip install atraxis-sdk
+```
+
+Требуется Python 3.10 или новее. Перед началом лидер гильдии выпускает приватный токен
+в разделе «Интеграции гильдии». Храните его как пароль: токен даёт доступ к операциям
+вашей гильдии.
+
+## Быстрый старт
+
+```python
+from atraxis import AtraxisClient, CurrencyTransfer
+
+with AtraxisClient("agk_example.redacted") as client:
+    for item in client.iter_warehouse():
+        print(item.warehouse_item_id, item.name, item.quantity)
+
+    result = client.transfer(
+        [CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25)],
+        idempotency_key="order-2026-09-12-0001",
+    )
+    print(result.operation_id)
+```
+
+Асинхронный клиент имеет те же методы:
+
+```python
+import asyncio
+from atraxis import AsyncAtraxisClient
+
+
+async def main() -> None:
+    async with AsyncAtraxisClient("agk_example.redacted") as client:
+        async for event in client.iter_activity():
+            print(event.occurred_at, event.kind, event.net)
+
+
+asyncio.run(main())
+```
+
+Токен и адрес можно передать через `ATRAXIS_API_TOKEN` и `ATRAXIS_API_BASE_URL`.
+По умолчанию SDK обращается к основному серверу Atraxis. Токен не включается в `repr`,
+исключения или логи самого SDK.
+
+## Что умеет SDK
+
+- `get_warehouse`, `iter_warehouse` — склад гильдии;
+- `list_currencies`, `upsert_currency` — внутренние валюты;
+- `get_balances` — балансы игрока;
+- `transfer` — единая операция из 1–10 переводов;
+- `get_activity`, `iter_activity` — история операций гильдии.
+
+Все суммы представлены в Python как `int`, а по сети передаются десятичными строками. Модели
+неизменяемы. Новые необязательные поля ответа не ломают клиент, но обязательные поля всегда
+проверяются.
+
+### Переводы
+
+```python
+from atraxis import CurrencyTransfer, ItemTransfer
+
+parts = [
+    ItemTransfer(warehouse_item_id=700001, player_id=100001, amount=1),
+    CurrencyTransfer.issue("TOKEN", amount=100),
+    CurrencyTransfer.retire("TOKEN", amount=10),
+    CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25),
+    CurrencyTransfer.from_player("TOKEN", player_id=100001, amount=5),
+    CurrencyTransfer.between_players(
+        "TOKEN",
+        from_player_id=100001,
+        to_player_id=100002,
+        amount=3,
+    ),
+]
+```
+
+Передавайте в `idempotency_key` постоянный идентификатор перевода или заказа. Если ключ не
+задан, SDK создаст UUID и вернёт его в `TransferResult.idempotency_key`. Повторный `POST` внутри
+SDK использует тот же ключ.
+
+Транспортные ошибки, `429`, `502`, `503` и `504` повторяются не более двух раз. При `429`
+учитывается `Retry-After`. Ошибки API представлены `AtraxisAPIError`; в них доступны безопасный
+problem response и `request_id`.
+
+Полная интерактивная документация: <https://atraxisonline.com/developers/api>.
+
+## Как пополняется склад
+
+Предметы, кредиты и Эхоны кладут на склад на странице гильдии, через основной бот
+или командой `Внести …` в привязанном чате с Авророй.
+
+Через API их можно только выдавать со склада игрокам. Списать их у игрока через API нельзя.
+
+## Подключение к Codex и Claude Code
+
+```bash
+pip install "atraxis-sdk[mcp]"
+```
+
+MCP позволяет Codex и Claude Code подсказывать по API и работать с вашей гильдией через SDK.
+Без токена помощник отвечает только по документации. С `ATRAXIS_API_TOKEN` он сможет читать
+данные гильдии. Команды, которые меняют валюты или передают ценности, доступны только после
+запуска с `--allow-writes`; для каждого перевода потребуется `idempotency_key`.
+
+Codex в режиме только для чтения, с уже установленной переменной окружения:
+
+```toml
+[mcp_servers.atraxis]
+command = "atraxis-mcp"
+env_vars = ["ATRAXIS_API_TOKEN"]
+```
+
+Или через CLI:
+
+```bash
+codex mcp add atraxis --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" -- atraxis-mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" atraxis -- atraxis-mcp
+```
+
+Готовые конфигурации без токенов лежат в [`examples/mcp`](examples/mcp). Чтобы разрешить
+изменения, добавьте `--allow-writes` в `args` только на своём устройстве и только для помощника,
+которому доверяете.
+
+## Лицензия
+
+MIT.

atraxis_sdk-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Atraxis Python SDK
+
+Официальный SDK для владельцев гильдий и лавок Atraxis. Он помогает подключить к гильдии
+своего бота, сайт или учётную систему: посмотреть склад, работать с внутренними валютами,
+выдавать ценности игрокам и получать историю операций.
+
+```bash
+pip install atraxis-sdk
+```
+
+Требуется Python 3.10 или новее. Перед началом лидер гильдии выпускает приватный токен
+в разделе «Интеграции гильдии». Храните его как пароль: токен даёт доступ к операциям
+вашей гильдии.
+
+## Быстрый старт
+
+```python
+from atraxis import AtraxisClient, CurrencyTransfer
+
+with AtraxisClient("agk_example.redacted") as client:
+    for item in client.iter_warehouse():
+        print(item.warehouse_item_id, item.name, item.quantity)
+
+    result = client.transfer(
+        [CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25)],
+        idempotency_key="order-2026-09-12-0001",
+    )
+    print(result.operation_id)
+```
+
+Асинхронный клиент имеет те же методы:
+
+```python
+import asyncio
+from atraxis import AsyncAtraxisClient
+
+
+async def main() -> None:
+    async with AsyncAtraxisClient("agk_example.redacted") as client:
+        async for event in client.iter_activity():
+            print(event.occurred_at, event.kind, event.net)
+
+
+asyncio.run(main())
+```
+
+Токен и адрес можно передать через `ATRAXIS_API_TOKEN` и `ATRAXIS_API_BASE_URL`.
+По умолчанию SDK обращается к основному серверу Atraxis. Токен не включается в `repr`,
+исключения или логи самого SDK.
+
+## Что умеет SDK
+
+- `get_warehouse`, `iter_warehouse` — склад гильдии;
+- `list_currencies`, `upsert_currency` — внутренние валюты;
+- `get_balances` — балансы игрока;
+- `transfer` — единая операция из 1–10 переводов;
+- `get_activity`, `iter_activity` — история операций гильдии.
+
+Все суммы представлены в Python как `int`, а по сети передаются десятичными строками. Модели
+неизменяемы. Новые необязательные поля ответа не ломают клиент, но обязательные поля всегда
+проверяются.
+
+### Переводы
+
+```python
+from atraxis import CurrencyTransfer, ItemTransfer
+
+parts = [
+    ItemTransfer(warehouse_item_id=700001, player_id=100001, amount=1),
+    CurrencyTransfer.issue("TOKEN", amount=100),
+    CurrencyTransfer.retire("TOKEN", amount=10),
+    CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25),
+    CurrencyTransfer.from_player("TOKEN", player_id=100001, amount=5),
+    CurrencyTransfer.between_players(
+        "TOKEN",
+        from_player_id=100001,
+        to_player_id=100002,
+        amount=3,
+    ),
+]
+```
+
+Передавайте в `idempotency_key` постоянный идентификатор перевода или заказа. Если ключ не
+задан, SDK создаст UUID и вернёт его в `TransferResult.idempotency_key`. Повторный `POST` внутри
+SDK использует тот же ключ.
+
+Транспортные ошибки, `429`, `502`, `503` и `504` повторяются не более двух раз. При `429`
+учитывается `Retry-After`. Ошибки API представлены `AtraxisAPIError`; в них доступны безопасный
+problem response и `request_id`.
+
+Полная интерактивная документация: <https://atraxisonline.com/developers/api>.
+
+## Как пополняется склад
+
+Предметы, кредиты и Эхоны кладут на склад на странице гильдии, через основной бот
+или командой `Внести …` в привязанном чате с Авророй.
+
+Через API их можно только выдавать со склада игрокам. Списать их у игрока через API нельзя.
+
+## Подключение к Codex и Claude Code
+
+```bash
+pip install "atraxis-sdk[mcp]"
+```
+
+MCP позволяет Codex и Claude Code подсказывать по API и работать с вашей гильдией через SDK.
+Без токена помощник отвечает только по документации. С `ATRAXIS_API_TOKEN` он сможет читать
+данные гильдии. Команды, которые меняют валюты или передают ценности, доступны только после
+запуска с `--allow-writes`; для каждого перевода потребуется `idempotency_key`.
+
+Codex в режиме только для чтения, с уже установленной переменной окружения:
+
+```toml
+[mcp_servers.atraxis]
+command = "atraxis-mcp"
+env_vars = ["ATRAXIS_API_TOKEN"]
+```
+
+Или через CLI:
+
+```bash
+codex mcp add atraxis --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" -- atraxis-mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" atraxis -- atraxis-mcp
+```
+
+Готовые конфигурации без токенов лежат в [`examples/mcp`](examples/mcp). Чтобы разрешить
+изменения, добавьте `--allow-writes` в `args` только на своём устройстве и только для помощника,
+которому доверяете.
+
+## Лицензия
+
+MIT.

atraxis_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "atraxis-sdk"
+version = "0.1.0"
+description = "Official Python SDK and local MCP server for the Atraxis public API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Atraxis" }]
+keywords = ["atraxis", "api", "sdk", "mcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.28,<1"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=2.2,<3"]
+dev = [
+  "build>=1.3,<2",
+  "hatchling>=1.27,<2",
+  "mcp>=2.2,<3",
+  "mypy>=1.15,<2",
+  "pytest>=8.3,<10",
+  "pytest-asyncio>=0.25,<2",
+  "PyYAML>=6,<7",
+  "ruff>=0.11,<1",
+]
+
+[project.urls]
+Documentation = "https://atraxisonline.com/developers/api"
+Repository = "https://github.com/Atraxis/Python-SDK"
+Issues = "https://github.com/Atraxis/Python-SDK/issues"
+
+[project.scripts]
+atraxis-mcp = "atraxis.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atraxis"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/scripts",
+  "/README.md",
+  "/CHANGELOG.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.hatch.build]
+artifacts = ["src/atraxis/_contract/*.json", "src/atraxis/_contract/*.sha256"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["atraxis"]
+