yandex-audience-cli 0.0.1__tar.gz

yandex_audience_cli-0.0.1/.env.example

@@ -0,0 +1,21 @@
+# Пример переменных окружения для yac.
+#
+# Скопируйте в .env и подставьте значения:
+#     cp .env.example .env
+#
+# ВАЖНО: yac НЕ читает .env автоматически (нет зависимости от python-dotenv).
+# Экспортируйте переменные в окружение вручную, например:
+#     set -a; . ./.env; set +a
+# (это корректно обрабатывает значения с пробелами/кавычками, в отличие от
+# `export $(grep ... | xargs)`), или через direnv (.envrc: `dotenv`).
+#
+# Альтернативы .env (см. README): флаг `--token` или файл
+# ~/.config/yandex-audience-cli/token — приоритет: --token > env > файл.
+
+# OAuth-токен Яндекса. Обязателен, если не передаёте --token и нет
+# ~/.config/yandex-audience-cli/token. Где взять: https://yandex.ru/dev/audience/
+YANDEX_AUDIENCE_TOKEN=
+
+# Базовый URL API. Менять НЕ нужно — только для тестов/прокси.
+# По умолчанию: https://api-audience.yandex.ru
+# YANDEX_AUDIENCE_BASE_URL=https://api-audience.yandex.ru

yandex_audience_cli-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+# Прогон тестовой пирамиды на push/PR в main.
+# e2e пропускается по умолчанию (conftest: skip без --run-e2e) — в CI не гоняем.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.9 — нижняя граница requires-python; 3.12 — текущая.
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Установить проект с dev-зависимостями
+        run: pip install -e ".[dev]"
+      - name: Прогнать тесты (e2e пропускается без --run-e2e)
+        run: pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Установить проект с dev-зависимостями
+        run: pip install -e ".[dev]"
+      - name: Проверить форматирование (black)
+        run: black --check yac tests
+      - name: Проверить линтером (ruff)
+        run: ruff check yac tests

yandex_audience_cli-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+# Сборка и публикация документации (MkDocs Material) на GitHub Pages.
+# Триггерится на push в main, затрагивающий доки/конфиг, и вручную.
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - pyproject.toml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+# Права для публикации на Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Не отменять идущий деплой; новые запуски ждут очереди.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Установить зависимости документации
+        run: pip install -e ".[docs]"
+      - name: Собрать сайт (строгий режим)
+        run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

yandex_audience_cli-0.0.1/.github/workflows/spec-audit.yml

@@ -0,0 +1,26 @@
+name: Spec audit
+
+# Еженедельная сверка снапшота спеки (tests/data/audience_spec.json) с ЖИВЫМ
+# справочником Яндекса. Отдельно от CI и неблокирующе — аутаж доков Яндекса не
+# должен ронять обычный pytest. Падает, если живая спека разошлась с закоммиченным
+# снапшотом (дрейф API) — это сигнал обновить реестр и снапшот.
+on:
+  schedule:
+    - cron: "0 6 * * 1" # понедельник 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Установить проект с dev-зависимостями
+        run: pip install -e ".[dev]"
+      - name: Перетянуть спеку из справочника Яндекса (сеть)
+        run: python scripts/fetch_spec.py
+      - name: Проверить, что снапшот не дрейфовал
+        run: git diff --exit-code tests/data/audience_spec.json

yandex_audience_cli-0.0.1/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Документация (артефакты сборки MkDocs — генерируются в CI, локально не коммитим)
+site/
+.cache/
+
+# Тесты / кэши инструментов
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Виртуальные окружения (проект ставится без venv, но на всякий случай)
+.venv/
+venv/
+
+# Редакторы / ОС
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Локальное служебное (Claude Code)
+.claude/
+
+# Секреты (токен резолвится из env или ~/.config, не из репо)
+token
+*.token
+# .env с реальными значениями — в git не коммитим (шаблон: .env.example)
+.env
+.env.*
+!.env.example

yandex_audience_cli-0.0.1/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Что это
+
+CLI `yac` — обёртка над Yandex Audience API, зеркалящая структуру API **1:1**: версия (`v1`) →
+пространство (`management`) → 5 ресурсных групп (segments, grants, pixels, accounts, delegates),
+28 эндпоинтов. Команды строятся как `yac <группа> <операция>` (`yac segments list`, `yac grants add ...`).
+
+Справочник API: живая локаль — **`ru`**, англоязычный путь `/en/ref/openapi/` сейчас отдаёт 404.
+Единого OpenAPI-файла НЕТ; справочник — Diplodoc, по странице на метод. У каждой есть исходный
+Markdown по детерминированному URL `https://yandex.ru/dev/audience/ru/ref/openapi/<группа>/<slug>.md`
+(метод + полный URL ресурса внутри `.md` парсятся машинно) — это первоисточник для сверки реестра.
+
+## Команды
+
+```bash
+pip install -e ".[dev]"     # установка editable + dev-зависимости (pytest, respx)
+pytest                       # вся пирамида КРОМЕ e2e (e2e skip без --run-e2e)
+pytest --run-e2e             # + e2e (локальный stub-сервер; боевой — skip без YAC_E2E_TOKEN)
+pytest tests/unit            # один уровень по пути (unit|integration|smoke|e2e)
+pytest -m smoke              # один уровень по маркеру (unit|integration|smoke|e2e)
+pytest tests/integration/test_resources.py::test_... -q   # один тест (по узлу <файл>::<тест>)
+pytest -k "<подстрока>"      # один тест/группа по имени без указания файла
+yac --help                   # справка; глобальные опции ДО группы: yac --token X segments list
+python -m yac --help         # эквивалент консольного скрипта
+```
+
+Тесты не требуют установки: `pyproject.toml` задаёт `pythonpath = ["."]`, поэтому `import yac`
+резолвится по корню репо.
+
+**Тестовая пирамида** — `tests/{unit,integration,smoke,e2e}/`, уровень виден из `ls`, на каждом
+файле `pytestmark = pytest.mark.<уровень>` (запуск и по пути, и по `-m`). Общие фикстуры —
+`tests/conftest.py` (`client` для ресурсов; `stub_server` — настоящий stdlib-сервер для e2e).
+- **unit** — изолированный модуль без сети: реестр (coverage/tree) и класс `Client` (respx лишь
+  подменяет сокет).
+- **integration** — связка слоёв через **respx** (моки httpx): resource↔client↔HTTP, multipart,
+  команды CLI. Реальный токен не нужен.
+- **smoke** — дымовой прогон CLI без сети: справка/версия/структура групп, чистая ошибка без токена.
+- **e2e** — сквозной прогон НАСТОЯЩЕГО `yac` без моков: `test_local_server.py` гоняет CLI против
+  локального stdlib-сервера через `--base-url` (реальный сокет); `test_live_api.py` бьёт в боевой
+  `api-audience.yandex.ru` и **пропускается** без `YAC_E2E_TOKEN`.
+
+e2e по умолчанию пропускается (`conftest.py` метит его skip, пока не передан `--run-e2e` —
+идиоматичный `pytest_addoption` + `pytest_collection_modifyitems`). Запуск: `pytest --run-e2e`
+или `pytest tests/e2e --run-e2e`. Боевой e2e: `YAC_E2E_TOKEN=*** pytest tests/e2e/test_live_api.py
+--run-e2e`.
+
+## Архитектура: реестр — единственный источник правды
+
+`yac/registry/` — **дерево «файл на эндпоинт»**: подкаталог на группу, в нём по файлу на каждый из
+28 `Endpoint` (`registry/segments/list.py`, `registry/grants/add.py`, ...). Имя файла = `op`,
+каталог = `group`, переменная в файле всегда `ENDPOINT`. `ls registry/segments/` показывает все
+эндпоинты группы. Дерево — единственный источник строк путей; `registry.ENDPOINTS` собирается из
+него **автозагрузкой** (`_core._load` через `pkgutil`; порядок групп — `GROUPS`, внутри группы —
+алфавит по имени файла). `registry/_core.py` держит `Endpoint` (frozen dataclass: `group`, `op`,
+`method`, `path`, `summary`, `multipart`, `unverified`, `path_params`), `GROUP_*`, `GROUPS` и
+функции; `registry/__init__.py` — фасад, реэкспортирующий публичный контракт (`ENDPOINTS`, `get`,
+`by_group`, `render_path`, `Endpoint`, `GROUP_*`, `GROUPS`), поэтому `from . import registry` и
+`from ..registry import GROUP_SEGMENTS` работают как раньше. **Всё остальное произрастает из реестра.**
+Ключевой инвариант: имя `op` эндпоинта = имя метода класса ресурса = имя команды CLI (через `_`→`-`).
+
+Поток данных слоями (зависимости однонаправленные, цикла нет):
+
+```
+commands/<group>.py  (Typer-команды; парсят аргументы, зовут render)
+        ↓
+api/<group>.py       (класс ресурса; метод на op; зовёт self._call(op, ...))
+        ↓
+base.py Resource._call → registry.get(group, op) + registry.render_path(ep, **path_params)
+        ↓
+client.py Client.request  (httpx; Authorization: OAuth <token>, base .../v1/management, pretty, multipart, 429)
+```
+
+`context.py` хранит глобальные опции в `ctx.obj` (`AppState`), лениво создаёт `Client` через
+`load_config()`, и даёт декоратор `handle_errors` (ConfigError/APIError → `exit(1)` без трейсбека).
+`cli.py` собирает корневой Typer-app (`add_typer` по группам) и держит `__version__`;
+`__init__.py` реэкспортирует `app` — отсюда работает entry point `yac = "yac:app"`.
+
+Резолвинг токена (`config.py`, по приоритету): `--token` → env `YANDEX_AUDIENCE_TOKEN` →
+файл `~/.config/yandex-audience-cli/token`. Base-url переопределяется `--base-url`/`YANDEX_AUDIENCE_BASE_URL`
+(нужно тестам/прокси). API имеет только `v1`/`management` — это зафиксировано, не параметризуется.
+
+## Как добавлять/менять эндпоинты
+
+1. Создай файл `yac/registry/<group>/<op>.py` с одним `ENDPOINT = Endpoint(GROUP_<GROUP>, "<op>", ...)`
+   (имя файла = `op`, каталог = группа; импорт `from .._core import Endpoint, GROUP_<GROUP>`).
+   Это единственное место со строками путей; список собирается автозагрузкой — больше нигде не
+   регистрировать.
+2. Добавь метод с именем = `op` в соответствующий `yac/api/<group>.py` (тело — `self._call("op", ...)`).
+3. Добавь команду с тем же именем (`_`→`-`) в `yac/commands/<group>.py`.
+4. Обнови `EXPECTED_PER_GROUP` в `tests/unit/test_registry_coverage.py` (итог `EXPECTED_TOTAL` =
+   `sum(...)`, **не хардкодь итоговое число**).
+
+Машинные гарантии (тесты упадут при нарушении): `tests/unit/test_registry_coverage.py` — у эндпоинта
+нет метода ресурса ИЛИ команды CLI; `tests/unit/test_registry_tree.py` — имя файла ≠ `op`, каталог ≠
+`group`, число файлов ≠ числу эндпоинтов. Сама автосборка (`_core._load`) падает громко при импорте, если файл
+не объявляет `ENDPOINT` или возникает дубль `(group, op)`.
+
+## Раскладка и окружение (важная причина текущей структуры)
+
+Весь код — в пакете `yac/` (подпакеты `api/`, `commands/`; остальные модули плоско в корне
+пакета). Это **намеренно**: проект ставится глобально (`pip install -e .`, **без venv**), и плоские
+top-level имена (`config`, `registry`, ...) раньше конфликтовали с одноимёнными модулями других
+editable-проектов в общем `sys.path`. Namespace `yac.*` устраняет коллизию без venv и без префиксов.
+
+- Импорты **внутри пакета — относительные** (`from .config import`, `from . import registry`,
+  `from ..base import Resource`). `import registry` записывается как `from . import registry`,
+  чтобы `registry.get()`/`registry.ENDPOINTS` в телах работали дословно.
+- Импорты **в тестах — абсолютные пакетные** (`from yac.api.segments import Segments`).
+- Не клади голые `.py` в корень репо: editable-`.pth` добавляет корень репо в `sys.path`
+  (т.к. `yac/` лежит в корне, не в `src/`), и такой файл снова станет глобальным top-level именем.
+
+## Грабли Typer/тестов
+
+- Современный Typer **не экспортирует** `click` как модуль — в тестах используй `typer.main.get_command`,
+  а не `import click`.
+- Команды извлекай через корневой app: `typer.main.get_command(root_app).commands[group].commands`
+  (под-app с одной командой, как accounts, не имеет `.commands` напрямую).
+- hatchling требует существующий `README.md` для сборки.

yandex_audience_cli-0.0.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: yandex-audience-cli
+Version: 0.0.1
+Summary: CLI, повторяющий структуру Yandex Audience API 1:1 (100% покрытие эндпоинтов)
+Author: yandex-audience-cli
+License: MIT
+Keywords: advertising,api,audience,cli,yandex
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# yandex-audience-cli
+
+CLI для [Yandex Audience API](https://yandex.ru/dev/audience/), повторяющий структуру API **«1 в 1»** с гарантией 100% покрытия эндпоинтов.
+
+📖 **Документация:** https://axisrow.github.io/yandex-audience-cli/
+
+## Структура API (3 уровня)
+
+```
+версия (v1) → пространство (management) → ресурс (5 групп)
+```
+
+База: `https://api-audience.yandex.ru/v1/management`. Авторизация: заголовок `Authorization: OAuth <token>`.
+WSDL неприменим (REST/JSON, не SOAP). Реестр выверен 1:1 по официальному
+[OpenAPI-справочнику Яндекса](https://yandex.ru/dev/audience/ru/ref/openapi/); единый источник правды —
+пакет [`yac/registry/`](yac/registry/) (файл на эндпоинт; **28 эндпоинтов** в 5 группах).
+
+## Раскладка
+
+Весь код — в пакете [`yac/`](yac/). Имена модулей живут в namespace `yac.*`, поэтому
+не конфликтуют с чужими top-level модулями в глобальном `sys.path` (без venv и без
+префиксов). Структура:
+
+```
+yac/
+├── __init__.py      # реэкспорт app, __version__
+├── __main__.py      # python -m yac
+├── cli.py           # сборка корневого Typer-приложения
+├── config.py  client.py  models.py
+├── base.py  context.py  render.py  inputs.py  output.py
+├── registry/        # реестр-дерево: подкаталог на группу, файл на эндпоинт
+│   ├── _core.py     # Endpoint, GROUPS, автосборка ENDPOINTS
+│   └── segments/  grants/  pixels/  accounts/  delegates/
+├── api/             # HTTP-классы ресурсов, по файлу на группу
+│   └── segments.py  grants.py  pixels.py  accounts.py  delegates.py
+└── commands/        # Typer-команды, по файлу на группу
+    └── segments.py  grants.py  pixels.py  accounts.py  delegates.py
+```
+
+По каждой группе API — пара `api/<group>.py` (HTTP-вызовы) и `commands/<group>.py`
+(команды Typer).
+
+| Группа | Эндпоинтов | Команды |
+|---|---|---|
+| `segments` | 16 | list, create-pixel, create-lookalike, create-metrika, create-appmetrica, create-geo, create-geo-polygon, upload-file, upload-csv-file, update-geo-points, modify-data, confirm, confirm-client-id, update, delete, reprocess |
+| `grants` | 3 | list, add, remove |
+| `pixels` | 5 | list, create, update, delete, undelete |
+| `accounts` | 1 | list |
+| `delegates` | 3 | list, add, remove |
+
+> Метод «получить один сегмент» (`GET segment/{id}`) в Audience API **отсутствует** —
+> по официальному справочнику доступен только список (`GET segments`). Поэтому такой команды нет.
+
+## Установка
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Токен
+
+Любой из способов (по приоритету): `--token <OAUTH>` → env `YANDEX_AUDIENCE_TOKEN` →
+файл `~/.config/yandex-audience-cli/token`. Шаблон переменных — `.env.example`.
+
+Где взять токен, как работать с `.env` и про общие права приложения — см.
+[Аутентификация](https://axisrow.github.io/yandex-audience-cli/authentication/).
+
+## Примеры
+
+```bash
+yac segments list
+yac -o table segments list --pixel 12345   # глобальная -o ДО группы
+yac segments create-pixel --data '{"name":"my","pixel_id":1,"period_length":30}'
+yac segments create-pixel --data @segment.json     # из файла
+yac pixels create --name "Мой пиксель"
+yac grants add 777 --user-login partner@yandex.ru --comment "доступ"
+yac delegates list
+```
+
+Глобальные опции: `--token`, `--base-url`, `-o/--output json|table`, `--pretty`, `--version`.
+
+## Гарантия покрытия
+
+`tests/unit/test_registry_coverage.py` падает, если в реестре есть эндпоинт без соответствующего
+метода ресурса или команды CLI. Это машинная проверка структурного соответствия API.
+
+```bash
+pytest
+```
+
+## Боевой smoke-прогон
+
+`scripts/live_smoke.sh` гоняет **все 28 эндпоинтов** через настоящий `yac` на боевом Audience API
+(в отличие от read-only `tests/e2e/test_live_api.py`). ⚠️ Скрипт **мутирует боевой аккаунт**: создаёт
+и удаляет реальные объекты (с префиксом `SMOKE yac`), но самоочищается через `trap EXIT` — работает
+только на своих данных, чужие сегменты не трогает. В CI не запускается (нужен реальный токен и квота
+записи). Запуск: токен в `.env`, затем `bash scripts/live_smoke.sh`. Подробнее —
+[Разработка](https://axisrow.github.io/yandex-audience-cli/development/).

yandex_audience_cli-0.0.1/README.md

@@ -0,0 +1,98 @@
+# yandex-audience-cli
+
+CLI для [Yandex Audience API](https://yandex.ru/dev/audience/), повторяющий структуру API **«1 в 1»** с гарантией 100% покрытия эндпоинтов.
+
+📖 **Документация:** https://axisrow.github.io/yandex-audience-cli/
+
+## Структура API (3 уровня)
+
+```
+версия (v1) → пространство (management) → ресурс (5 групп)
+```
+
+База: `https://api-audience.yandex.ru/v1/management`. Авторизация: заголовок `Authorization: OAuth <token>`.
+WSDL неприменим (REST/JSON, не SOAP). Реестр выверен 1:1 по официальному
+[OpenAPI-справочнику Яндекса](https://yandex.ru/dev/audience/ru/ref/openapi/); единый источник правды —
+пакет [`yac/registry/`](yac/registry/) (файл на эндпоинт; **28 эндпоинтов** в 5 группах).
+
+## Раскладка
+
+Весь код — в пакете [`yac/`](yac/). Имена модулей живут в namespace `yac.*`, поэтому
+не конфликтуют с чужими top-level модулями в глобальном `sys.path` (без venv и без
+префиксов). Структура:
+
+```
+yac/
+├── __init__.py      # реэкспорт app, __version__
+├── __main__.py      # python -m yac
+├── cli.py           # сборка корневого Typer-приложения
+├── config.py  client.py  models.py
+├── base.py  context.py  render.py  inputs.py  output.py
+├── registry/        # реестр-дерево: подкаталог на группу, файл на эндпоинт
+│   ├── _core.py     # Endpoint, GROUPS, автосборка ENDPOINTS
+│   └── segments/  grants/  pixels/  accounts/  delegates/
+├── api/             # HTTP-классы ресурсов, по файлу на группу
+│   └── segments.py  grants.py  pixels.py  accounts.py  delegates.py
+└── commands/        # Typer-команды, по файлу на группу
+    └── segments.py  grants.py  pixels.py  accounts.py  delegates.py
+```
+
+По каждой группе API — пара `api/<group>.py` (HTTP-вызовы) и `commands/<group>.py`
+(команды Typer).
+
+| Группа | Эндпоинтов | Команды |
+|---|---|---|
+| `segments` | 16 | list, create-pixel, create-lookalike, create-metrika, create-appmetrica, create-geo, create-geo-polygon, upload-file, upload-csv-file, update-geo-points, modify-data, confirm, confirm-client-id, update, delete, reprocess |
+| `grants` | 3 | list, add, remove |
+| `pixels` | 5 | list, create, update, delete, undelete |
+| `accounts` | 1 | list |
+| `delegates` | 3 | list, add, remove |
+
+> Метод «получить один сегмент» (`GET segment/{id}`) в Audience API **отсутствует** —
+> по официальному справочнику доступен только список (`GET segments`). Поэтому такой команды нет.
+
+## Установка
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Токен
+
+Любой из способов (по приоритету): `--token <OAUTH>` → env `YANDEX_AUDIENCE_TOKEN` →
+файл `~/.config/yandex-audience-cli/token`. Шаблон переменных — `.env.example`.
+
+Где взять токен, как работать с `.env` и про общие права приложения — см.
+[Аутентификация](https://axisrow.github.io/yandex-audience-cli/authentication/).
+
+## Примеры
+
+```bash
+yac segments list
+yac -o table segments list --pixel 12345   # глобальная -o ДО группы
+yac segments create-pixel --data '{"name":"my","pixel_id":1,"period_length":30}'
+yac segments create-pixel --data @segment.json     # из файла
+yac pixels create --name "Мой пиксель"
+yac grants add 777 --user-login partner@yandex.ru --comment "доступ"
+yac delegates list
+```
+
+Глобальные опции: `--token`, `--base-url`, `-o/--output json|table`, `--pretty`, `--version`.
+
+## Гарантия покрытия
+
+`tests/unit/test_registry_coverage.py` падает, если в реестре есть эндпоинт без соответствующего
+метода ресурса или команды CLI. Это машинная проверка структурного соответствия API.
+
+```bash
+pytest
+```
+
+## Боевой smoke-прогон
+
+`scripts/live_smoke.sh` гоняет **все 28 эндпоинтов** через настоящий `yac` на боевом Audience API
+(в отличие от read-only `tests/e2e/test_live_api.py`). ⚠️ Скрипт **мутирует боевой аккаунт**: создаёт
+и удаляет реальные объекты (с префиксом `SMOKE yac`), но самоочищается через `trap EXIT` — работает
+только на своих данных, чужие сегменты не трогает. В CI не запускается (нужен реальный токен и квота
+записи). Запуск: токен в `.env`, затем `bash scripts/live_smoke.sh`. Подробнее —
+[Разработка](https://axisrow.github.io/yandex-audience-cli/development/).

yandex_audience_cli-0.0.1/docs/architecture.md

@@ -0,0 +1,74 @@
+# Архитектура
+
+`yac` устроен так, чтобы соответствие CLI и API было **невозможно нарушить незаметно**. В основе —
+реестр эндпоинтов как единственный источник правды.
+
+## Реестр — единственный источник правды
+
+`yac/registry/` — это **дерево «файл на эндпоинт»**: подкаталог на группу, внутри по файлу на каждый
+из 28 эндпоинтов (`registry/segments/list.py`, `registry/grants/add.py`, …). Каждый файл объявляет
+один объект `ENDPOINT`:
+
+```python
+# yac/registry/segments/list.py
+ENDPOINT = Endpoint(GROUP_SEGMENTS, "list", "GET", "segments", "Список сегментов")
+```
+
+- **Имя файла** = имя операции (`op`).
+- **Каталог** = группа.
+- Список `registry.ENDPOINTS` собирается из дерева **автозагрузкой** — регистрировать эндпоинт
+  где-то ещё не нужно.
+
+`ls yac/registry/segments/` сразу показывает все 16 эндпоинтов группы — карта API наглядна прямо из
+файловой системы.
+
+**Ключевой инвариант:** имя `op` эндпоинта = имя метода класса ресурса = имя CLI-команды
+(с заменой `_` ↔ `-`).
+
+## Поток данных по слоям
+
+Зависимости однонаправленные, цикла нет:
+
+```
+commands/<group>.py   Typer-команды: парсят аргументы, зовут render
+        ↓
+api/<group>.py        класс ресурса: метод на каждый op; зовёт self._call(op, ...)
+        ↓
+base.py Resource._call → registry.get(group, op) + registry.render_path(ep, **path_params)
+        ↓
+client.py Client.request   httpx: заголовок OAuth, base .../v1/management, pretty, multipart, 429
+```
+
+| Модуль | Роль |
+|---|---|
+| `cli.py` | корневой Typer-app, глобальные опции, регистрация групп |
+| `config.py` | резолвинг токена и base-url |
+| `context.py` | `AppState`, ленивое создание клиента, декоратор `handle_errors` |
+| `client.py` | httpx-обёртка, `APIError`/`RateLimitError`, разбор ответа |
+| `base.py` | `Resource._call` — мост реестр ↔ клиент |
+| `registry/` | `ENDPOINTS`, модель `Endpoint`, `get`/`render_path`/`by_group` |
+| `render.py` / `output.py` | вывод json/table |
+| `inputs.py` | `parse_data` для `--data` (строка/`@файл`/`-`) |
+
+## Машинная гарантия покрытия
+
+Соответствие реестра, классов ресурсов и CLI-команд проверяется тестами — они **упадут**, если
+рассинхронизировать:
+
+- `tests/unit/test_registry_coverage.py` — у каждого эндпоинта есть и метод ресурса, и CLI-команда;
+  счётчики по группам (16/3/5/1/3 = 28).
+- `tests/unit/test_registry_tree.py` — имя файла = `op`, каталог = `group`, число файлов = числу
+  эндпоинтов.
+- Сама автосборка реестра падает громко при импорте, если файл не объявляет `ENDPOINT` или возник
+  дубль `(group, op)`.
+
+Поэтому «100% покрытие эндпоинтов» — не обещание, а инвариант, который держат тесты.
+
+## Как добавить эндпоинт
+
+1. Создать `yac/registry/<group>/<op>.py` с одним `ENDPOINT`.
+2. Добавить метод с именем `op` в `yac/api/<group>.py` (тело — `self._call("op", ...)`).
+3. Добавить команду с тем же именем (`_`→`-`) в `yac/commands/<group>.py`.
+4. Обновить ожидаемые счётчики в `tests/unit/test_registry_coverage.py`.
+
+Подробности — в `CLAUDE.md` репозитория.