# Atraxis Python SDK

Официальный Python SDK для API Atraxis. Читайте события и объявления игры, подключайте
к гильдии своего бота, сайт или лавку: получайте содержимое склада, работайте с валютами
и выдавайте ценности игрокам, настраивайте роли и ограничения участников.

```bash
pip install atraxis-sdk
```

Требуется Python 3.10 или новее. Для событий и объявлений токен не нужен. Для работы
с гильдией лидер выпускает токен в разделе «Интеграции гильдии». Храните его как пароль:
он даёт доступ к складу, валютам и переводам вашей гильдии.

## Публичные события и объявления

События и объявления доступны без токена:

```python
from atraxis import AtraxisClient

with AtraxisClient() as client:
    for event in client.iter_events():
        print(event.title, event.status, event.ends_at)
    page = client.get_announcements()
    checkpoint = page.checkpoint
    for announcement in client.iter_new_announcements(after_id=checkpoint):
        print(announcement.text)
```

Эти методы доступны также в `AsyncAtraxisClient`. Токен нужен только для методов гильдии.

Для постоянного опроса вызывайте `get_announcements(order="asc", after_id=checkpoint)`.
Передавайте `next_cursor`, сохраняя те же фильтры и `after_id`, пока не обработаете все страницы;
после этого сохраните последний `checkpoint`. История хранится 90 дней.
Ответ 410 означает, что сохранённая позиция устарела: начните чтение без `after_id` и `cursor`.
Лимит обоих публичных методов вместе — 300 запросов в минуту с IP; после 429 учитывайте `Retry-After`.

MCP-инструменты `atraxis_get_events` и `atraxis_get_announcements` доступны без `ATRAXIS_API_TOKEN`
и без `--allow-writes`. Для инструментов гильдии настройте токен.
OpenAPI: <https://atraxisonline.com/api/developers/openapi.json>.

## Роли и ограничения участников

Для этих методов требуется SDK 0.8.0 или новее. Лидер разрешает лавке или боту
управлять ролями и ограничениями в разделе «Интеграции гильдии».
`manage_roles` разрешает создавать и удалять роли, менять их название, права и порядок, назначать роли участникам.
`manage_member_restrictions` разрешает просмотр и изменение личных ограничений.
После перевыпуска токена или смены лидера права нужно выдать заново.

Пять методов покрывают все действия с ролями и участниками.

| Метод | Возможности |
| --- | --- |
| `get_guild_roles()` | Роли, права, лимиты и версия настроек |
| `manage_guild_roles(change, ...)` | Создание, настройка, удаление и порядок ролей |
| `list_guild_members(...)` | Страница участников, их роли и доступные ограничения |
| `get_guild_member(player_id)` | Один участник с версией для изменений |
| `update_guild_member(player_id, change, ...)` | Роль, ограничения или оба изменения вместе |

```python
from dataclasses import replace
from uuid import uuid4
from atraxis import AtraxisClient

with AtraxisClient("agk_example.redacted") as client:
    operation_key = str(uuid4())  # Сохраните для повтора этого действия.
    created = client.manage_guild_roles(
        {"action": "create", "name": "Хранитель"},
        idempotency_key=operation_key,
    )
    print(created.role)

    # Выберите игровой ID участника своей гильдии.
    member = client.get_guild_member(100001)
    if member.restrictions is not None:
        flags = replace(member.restrictions, matrix_claim=True, guild_teleport=True)
        updated = client.update_guild_member(
            member.player_id,
            {"role": "member", "restrictions": flags.to_dict()},
            expected_version=member.version,
            idempotency_key=str(uuid4()),
        )
        print(updated.version)
```

В `manage_guild_roles` поле `action` определяет остальные поля запроса.

| `action` | Поля изменения |
| --- | --- |
| `create` | `name` |
| `update` | `role_key`, `name`, `permissions`, `max_members` |
| `delete` | `role_key` и `replacement_role`, если у роли есть участники |
| `reorder` | `roles` со всеми ключами по одному разу, от `leader` до `member` |

Новая роль создаётся без прав и лимита. В `update` передавайте все настройки,
которые должны действовать после сохранения. Чтобы сохранить права или лимит,
передайте их текущие значения. Пустой список `permissions` снимает все права,
а `max_members=None` снимает лимит.
Удаление назначает выбранную роль всем участникам удаляемой роли и сохраняет их
личные ограничения. Роли `leader` и `member` защищены от удаления.

В `update_guild_member` пропущенные поля сохраняются. `{"restrictions": None}`
снимает все ограничения. Для установки передайте все шесть флагов, где `True`
запрещает действие. Роль и ограничения сохраняются вместе. Для изменения обоих
полей токену нужны оба разрешения. Смена роли сохраняет ограничения, если поле
`restrictions` пропущено. Через API нельзя передать лидерство, изменить роль лидера или установить ему ограничения.

Ограничения в ответе равны `None`, если токен не может ими управлять или участник
это лидер гильдии. При создании роли `expected_version` необязателен. Если передать
его, сервер проверит версию. Для остальных действий с ролями используйте `version`
из `get_guild_roles`, для участника — его `version` из списка или `get_guild_member`.
При `412` обновите данные, проверьте изменения и отправьте новое действие с новой
версией и новым ключом. Ответ `409` означает, что ключ уже использован для другого
запроса. Для повтора после сетевого сбоя сохраняйте прежние аргументы и ключ.

Все пять методов доступны в `AsyncAtraxisClient`. В MCP им соответствуют пять
инструментов. Инструменты записи доступны с `--allow-writes` и требуют явный
`idempotency_key`. Для изменения существующих настроек обязателен `expected_version`.

## Гильдии и лавки: быстрый старт

```python
from atraxis import AtraxisClient, CurrencyTransfer

with AtraxisClient("agk_example.redacted") as client:
    warehouse = client.get_warehouse()
    for item in warehouse.items:
        print(item.warehouse_item_id, item.name, item.quantity)

        if item.instance and item.instance.kind == "equipment":
            print(item.instance.level, item.instance.quality, item.instance.combat_stats)

    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.deposit_method, event.net)


asyncio.run(main())
```

Токен и адрес можно передать через `ATRAXIS_API_TOKEN` и `ATRAXIS_API_BASE_URL`.
По умолчанию SDK обращается к основному серверу Atraxis. Токен не включается в `repr`,
исключения или логи самого SDK.

## Что умеет SDK

- `get_events`, `iter_events` — активные события;
- `get_announcements`, `iter_announcements`, `iter_new_announcements` — объявления и обновления ленты;
- `get_warehouse`, `iter_warehouse` — весь склад гильдии одним запросом;
- `list_currencies`, `upsert_currency` — внутренние валюты;
- `resolve_player_identities` — все подтверждённые ID одного игрока по игровому или платформенному ID;
- `get_balances` — балансы игрока;
- `transfer` — единая операция из 1–64 переводов;
- `get_activity`, `iter_activity`, `iter_new_activity` — история операций гильдии и последовательное получение новых записей.

Все суммы представлены в Python как `int`, а по сети передаются десятичными строками. Модели
неизменяемы. Новые необязательные поля ответа не ломают клиент, но обязательные поля всегда
проверяются.

У предмета на складе два идентификатора: `item_id` обозначает общий тип предмета,
а `warehouse_item_id` — конкретную позицию, которую нужно передать при выдаче. Для
уникальной позиции `is_unique` равен `True`, а `instance` содержит характеристики именно
этого экземпляра: боевые параметры и улучшения экипировки, бонусы инструментов и удочек,
умения щита, свойства улова, состояние артефакта или журнала. В `condition` указаны
прочность и её единица — `percent` или `points`. Поля `durability` и `max_durability`
сохранены для совместимости со старыми подключениями.

### Переводы

```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`; в них доступны
ответ API и `request_id`.
При ошибке записи `AtraxisError.idempotency_key` содержит ключ отправленного
действия, включая ключ, созданный SDK. Для повтора используйте его вместе
с прежними аргументами и версией. `AtraxisAPIError.retry_after` содержит значение
заголовка `Retry-After`, если сервер его передал. Ошибки MCP помечаются `isError`
и содержат статус, ID запроса и срок повтора, когда они доступны.


Для `/activity` доступно до 300 запросов в минуту с одного IP и 60 на гильдию. Остальные методы гильдии
имеют отдельный лимит: до 100 запросов с IP и 60 на гильдию.

Полная интерактивная документация: <https://atraxisonline.com/developers/api>.

### Кроссплатформенные идентификаторы

Лавке не нужно отдельно просить покупателя зарегистрировать ID в Telegram, VK или на другой платформе.
Передайте любой известный идентификатор, и API вернёт игровой ID вместе со всеми текущими
подтверждёнными привязками:

```python
with AtraxisClient("agk_example.redacted") as client:
    identities = client.resolve_player_identities("telegram", "987654321")
    game_id = int(identities.by_platform["game"])
```

`platform` — `game` для игрового ID или код платформы из поля `provider` в `/api/providers`.
Внешний `player_id` передавайте строкой без изменений.

## Как пополняется склад и выдаются предметы

Свой склад пополняют на странице гильдии или через основной бот. В привязанном чате
гильдии используйте `Внести …`. Участник с правом брать предметы со склада может там же
использовать `Забрать …`. Обе команды принимают до 64 позиций через точку с запятой:

```text
Внести Стабилизатор - 2 штуки; 1000 кредитов
Забрать Стабилизатор - 2 штуки; номер 4
```

`Номер N` относится к последнему списку соответствующего раздела склада в основном боте.
Для выдачи нужны право брать предметы со склада и свободное место в сумке.

В любом чате Авроры, где работает обычное `Передать`, можно выбрать склад любой гильдии
по её уникальному тегу:

```text
Передать ТЕГ Стабилизатор - 2 штуки
Передать ТЕГ 1000 кредитов; номер 4 - 2 штуки
```

Укажите тег перед названием предмета, без скобок. Команда работает в чатах Авроры,
кроме общего; членство в выбранной гильдии не требуется.

Через API их можно только выдавать со склада игрокам. Списать их у игрока через API нельзя.

История возвращает одну целую операцию на команду или запрос. У операции есть
`operation_id`, время, источник и `transfers` со всеми позициями в исходном порядке.
Каждая позиция содержит `index`, стороны, актив, `gross`, `fee`, `net` и доступный снимок
предмета. `deposit_method` различает `guild_deposit` и `tagged_transfer`, а
`source_identity` сохраняет платформу и внешний ID отправителя. У исторических записей
дополнительные сведения могут отсутствовать.

По умолчанию `get_activity()` возвращает 20 операций, максимум — 50.
Для первоначальной сверки получите полный склад и сохраните его контрольную точку:

```python
with AtraxisClient("agk_example.redacted") as client:
    warehouse = client.get_warehouse()
    last_operation_id = warehouse.activity_checkpoint
```

Для последующих проверок используйте `iter_new_activity()`. Он получает операции от старых
к новым и проходит все страницы. Передачи, появившиеся во время чтения, попадут
в следующую проверку. Если у склада ещё нет истории, `activity_checkpoint` равен `None`:
его также можно передать в `after_operation_id`:

```python
with AtraxisClient("agk_example.redacted") as client:
    for operation in client.iter_new_activity(after_operation_id=last_operation_id):
        process_operation(operation)  # учитывает все operation.transfers
        last_operation_id = operation.operation_id
```

Сохраняйте `operation_id` вместе с результатом учёта операции в своей базе. Для повторных
запросов оплаты или выдачи используйте прежний `idempotency_key` заказа. Новый ключ
обозначает новую оплату или выдачу.

`get_activity()` также поддерживает `order="desc"`, `order="asc"` и `cursor`.
Передачи, появившиеся во время чтения страниц, попадут в следующую проверку.
Поле `checkpoint` страницы можно сохранять после обработки **всех** её продолжений
по `next_cursor`. После каждой отдельной обработанной операции можно сохранять её
`operation_id` и продолжать через `after_operation_id` после перезапуска.

При `410` сохранённая операция больше недоступна. Получите склад через `get_warehouse()`,
сверьте остатки и уже обработанные заказы, затем сохраните его `activity_checkpoint`.
Сверка остатков не заменяет проверку выполненных заказов: не выдавайте их повторно.
Налоги и системные механики могут менять склад отдельно от истории передач, поэтому
сверку склада стоит повторять периодически.

### Переход на SDK 0.9 и контракт API 2.0

Обновление меняет формат `/activity`. Вместо `ActivityEvent` используется
`ActivityOperation`, содержащий `ActivityTransfer`. Замените `after_event_id` на
`after_operation_id`, а сохранённую позицию — на ID полностью обработанной операции.
Старые курсоры отклоняются с явной ошибкой. Сначала согласуйте обновление интеграции и
сервера, затем возобновите обработку. Сохранённые ключи заказов продолжают защищать
повтор оплаты и выдачи.

Ошибки отдельных переводов содержат `error.problem.transfer_index` с номером позиции
от нуля. Ошибка сохраняет `idempotency_key` и `request_id`. Если сервер требует ждать
больше 30 секунд, SDK возвращает `429` с исходным `retry_after`, чтобы расписание повтора
контролировала интеграция.

## Подключение к Codex и Claude Code

```bash
pip install "atraxis-sdk[mcp]"
```

MCP позволяет Codex и Claude Code читать события и объявления, помогать с API и работать
с вашей гильдией. Для событий и объявлений токен не нужен. С `ATRAXIS_API_TOKEN` помощник
сможет читать данные гильдии. Для переводов, настройки валют, ролей и ограничений
запустите MCP с `--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.