direct-cli 0.2.7__tar.gz → 0.2.9__tar.gz

{direct_cli-0.2.7 → direct_cli-0.2.9}/.github/workflows/api-coverage.yml

@@ -45,12 +45,24 @@ jobs:
 
           report = json.loads(Path("api_coverage_report.json").read_text())
           summary = report["summary"]
+          model_gaps = report["model_gaps"]
           print("## API coverage summary")
           print()
           print(f"- Services checked: {summary['services_checked']}")
           print(f"- Missing methods: {summary['missing_service_methods']}")
           print(f"- Unexpected methods: {summary['unexpected_service_methods']}")
           print(f"- Strict parity OK: {summary['strict_parity_ok']}")
+          print(f"- Live model parity OK: {summary['live_model_parity_ok']}")
+          print(f"- Declared WSDL services: {model_gaps['declared_wsdl_services_count']}")
+          print(f"- Declared WSDL methods: {model_gaps['declared_wsdl_methods_count']}")
+          print(f"- Live-discovered services: {model_gaps['live_discovered_services_count']}")
+          print(f"- Total known methods: {model_gaps['total_known_methods_count']}")
+          print(f"- Model gaps: {model_gaps['live_model_gap_count']}")
+          for item in model_gaps["live_discovered_missing_services"][:10]:
+              methods = ", ".join(item["api_methods"])
+              print(f"- Missing service: {item['api_service']} ({methods})")
+          for item in model_gaps["live_discovery_errors"][:10]:
+              print(f"- Live discovery error: {item['api_service']}: {item['error']}")
           print(f"- Non-WSDL services: {len(report['non_wsdl_services'])}")
           print(f"- CLI helpers: {len(report['cli_helpers'])}")
           PY

{direct_cli-0.2.7 → direct_cli-0.2.9}/AGENTS.md

@@ -106,6 +106,7 @@ Valid canonical examples:
 direct campaigns get --ids 1,2,3
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct keywordsresearch has-search-volume --keywords "buy laptop,buy desktop"
+direct smartadtargets update --id 456 --priority HIGH
 direct dynamicads set-bids --id 789 --bid 12.5
 direct dictionaries get-geo-regions --region-ids 225 --fields GeoRegionId,GeoRegionName
 ```

{direct_cli-0.2.7 → direct_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.2.7
+Version: 0.2.9
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -18,7 +18,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: tapi-yandex-direct>=2021.5.29
+Requires-Dist: orjson
+Requires-Dist: requests
+Requires-Dist: tapi-wrapper2
 Requires-Dist: click>=8.0.0
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: tabulate>=0.8.0
@@ -66,14 +68,46 @@ Or pass credentials directly per command:
 direct --token YOUR_TOKEN --login YOUR_LOGIN campaigns get
 ```
 
+Use profile-specific credentials from `.env`:
+
+```env
+YANDEX_DIRECT_TOKEN_AGENCY1=token-1
+YANDEX_DIRECT_LOGIN_AGENCY1=client-login-1
+YANDEX_DIRECT_TOKEN_AGENCY2=token-2
+YANDEX_DIRECT_LOGIN_AGENCY2=client-login-2
+```
+
+OAuth and profile commands:
+
+```bash
+direct auth login
+direct auth login --profile agency1
+direct auth login --code abc123 --profile agency1
+direct auth login --oauth-token y0_example --profile agency1
+direct auth list
+direct auth use --profile agency1
+direct auth status --profile agency1
+direct --profile agency1 campaigns get
+```
+
+Notes:
+- Legacy profile environment variable is not used.
+- Select credentials with `--profile`.
+- `--login` remains Direct client login.
+- Authorization is performed via `direct auth login`.
+- Alias `auth_login` is not supported.
+
 Install with `pip install direct-cli`, then run commands with `direct`.
+Invoking the deprecated `direct-cli` entrypoint exits with
+`use direct instead of direct-cli`.
 
 ### Global Options
 
 | Option | Description |
 |--------|-------------|
 | `--token` | API access token |
-| `--login` | Yandex advertiser login |
+| `--login` | Direct client login |
+| `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
 
 ### CLI Convention
@@ -101,9 +135,10 @@ Naming rules:
   - multiword commands use kebab-case
   - examples: `get`, `set-bids`, `check-campaigns`, `has-search-volume`
 
-direct-cli owns the public naming contract. `tapi-yandex-direct` may
-influence the internal transport layer, but it does not define canonical CLI
-names.
+The `direct` executable defines the public naming contract. The
+`direct-cli` package name and deprecated shim do not define canonical CLI
+names. `tapi-yandex-direct` may influence the internal transport layer, but it
+does not define canonical CLI names.
 
 The current policy is canonical-only. Historical aliases are not preserved in
 the runtime CLI by default. If compatibility is ever needed, an alias must be
@@ -120,6 +155,7 @@ be supported.
 - If the API requires a complex object, the CLI must expose explicit flags or subcommands instead of forwarding raw JSON.
 
 #### Command Formatting Rules
+
 - Every canonical CLI command must be written strictly on a single line.
 - Multi-line command formatting is not allowed.
 - Shell line continuation using `\` is forbidden in canonical documentation, help text, tests, and examples.
@@ -184,6 +220,7 @@ Valid canonical examples:
 direct campaigns get --ids 1,2,3
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct keywordsresearch has-search-volume --keywords "buy laptop,buy desktop"
+direct smartadtargets update --id 456 --priority HIGH
 direct dynamicads set-bids --id 789 --bid 12.5 --context-bid 9 --priority HIGH
 direct dictionaries get-geo-regions --name Moscow --region-ids 225,187 --exact-names Москва,Санкт-Петербург --fields GeoRegionId,GeoRegionName
 ```
@@ -250,7 +287,7 @@ direct ads delete --id 99999
 ```bash
 direct keywords get --campaign-ids 1,2,3
 direct keywords add --adgroup-id 12345 --keyword "buy laptop" --bid 10.50 --context-bid 5.25 --user-param-1 segment-a --user-param-2 segment-b --dry-run
-direct keywords update --id 88888 --bid 15.00 --context-bid 6.00 --status SUSPENDED
+direct keywords update --id 88888 --keyword "updated keyword text"
 direct keywords delete --id 88888
 ```
 
@@ -272,10 +309,14 @@ Available report types: `CAMPAIGN_PERFORMANCE_REPORT`, `ADGROUP_PERFORMANCE_REPO
 # Reference dictionaries and changes
 direct dictionaries get --names Currencies,GeoRegions
 direct dictionaries get-geo-regions --name Moscow --region-ids 225,187 --exact-names Москва,Санкт-Петербург --fields GeoRegionId,GeoRegionName
+
+# Client info
+direct clients get --fields ClientId,Login,Currency
+
+# Changes
 direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
-direct clients get --fields ClientId,Login,Currency
 
 # Keyword research and retargeting
 direct keywordsresearch has-search-volume --keywords "buy laptop,buy desktop"
@@ -300,6 +341,17 @@ direct smartadtargets update --id 456 --priority HIGH
 direct smartadtargets set-bids --id 456 --average-cpc 10.5 --average-cpa 15 --priority HIGH
 direct dynamicads set-bids --id 789 --bid 12.5 --context-bid 9 --priority HIGH
 
+# Shared bidding strategies
+direct strategies get --limit 5
+direct strategies add --name "Shared Clicks" --type WbMaximumClicks --params '{"SpendLimit":1000000000,"AverageCpc":30000000}' --dry-run
+direct strategies update --id 42 --params '{"AverageCpc":35000000}' --dry-run
+direct strategies archive --id 42 --dry-run
+
+# Dynamic feed ad targets
+direct dynamicfeedadtargets get --adgroup-ids 123 --limit 5
+direct dynamicfeedadtargets add --adgroup-id 33 --name "Feed slice A" --condition "CATEGORY:EQUALS:shoes" --bid 5 --dry-run
+direct dynamicfeedadtargets set-bids --id 789 --bid 6.5 --context-bid 4 --dry-run
+
 # Extensions, assets, feeds, and clients
 direct sitelinks add --sitelink "Docs|https://example.com/docs" --sitelink "Help|https://example.com/help|Desk" --dry-run
 direct vcards add --campaign-id 555 --country "Russia" --city "Moscow" --company-name "Acme" --work-time 1#5#9#0#18#0 --phone-country-code +7 --phone-city-code 495 --phone-number 1234567 --dry-run
@@ -315,12 +367,12 @@ direct agencyclients add-passport-organization-member --passport-organization-lo
 direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
 ```
 
-### Known Transport Gap
+### Known Unsupported API Operation
 
-`dynamicads update` is still a transport gap. Downstream wrappers may assume
-that operation exists, but the current installed CLI help surface does not
-expose `dynamicads update`. Treat it as unsupported until a real command is
-added.
+`dynamicads update` is unsupported by API. The Yandex Direct
+`dynamictextadtargets` service exposes `add`, `get`, `delete`, `suspend`,
+`resume`, and `setBids`, but no `update` operation. Do not add or rely on
+`direct dynamicads update` unless Yandex exposes a real API method.
 
 ### Output Formats
 
@@ -369,19 +421,22 @@ direct campaigns add --name "Test" --start-date 2024-01-01 --dry-run
 
 ### Testing
 
-Three tiers of tests live under `tests/`:
+Four tiers of tests live under `tests/`:
 
 | Tier | Marker | Network | Token required |
 |---|---|---|---|
 | Unit / CLI wiring / dry-run | *(none)* | No | No |
 | Read-only integration | `-m integration` | Yes (production API, read-only) | Yes |
 | Write integration | `-m integration_write` | No (replays VCR cassettes) | No |
+| Live draft write integration | `-m integration_live_write` | Yes when recording, otherwise VCR replay | Yes + `YANDEX_DIRECT_LIVE_WRITE=1` |
 
 ```bash
 pip install -e ".[dev]"
 pytest                              # fast tier — no token
 pytest -m integration -v            # read-only integration tests (needs token)
 pytest -m integration_write -v      # write cassette replay (no token needed)
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v  # live draft cassette replay
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # re-record live draft cassette
 ```
 
 ### API Coverage And Drift Monitoring
@@ -391,13 +446,16 @@ The project now distinguishes four surfaces:
 | Surface | Coverage strategy |
 |---|---|
 | Canonical WSDL-backed SOAP services | `tests/test_api_coverage.py` verifies strict service/method parity and dry-run request-schema coverage or explicit exclusions |
+| Live-discovered WSDL model gaps | `scripts/build_api_coverage_report.py` reports services seen in the audited live API surface but not yet declared in the CLI coverage model |
 | Non-WSDL services (`reports`) | Explicit contract tests |
 | Historical aliases retained by exception | None currently retained |
 | Intentional CLI-only helpers | Explicitly allowlisted with reasons in `direct_cli/wsdl_coverage.py` |
 
 `100% coverage` in this project means full coverage of the supported
-**canonical API surface**. Alias groups and CLI-only helpers remain supported,
-but they are tracked outside the strict parity metric.
+**declared canonical API surface**. The API coverage report also includes a
+`model_gaps` section for live-discovered Yandex Direct services that are not
+yet part of that declared model. Alias groups and CLI-only helpers remain
+supported, but they are tracked outside the strict parity metric.
 
 Useful maintenance commands:
 
@@ -409,7 +467,8 @@ python scripts/check_wsdl_drift.py
 
 CI runs a scheduled API coverage workflow that:
 - runs the fast coverage suites;
-- uploads a machine-readable API coverage report artifact;
+- uploads a machine-readable API coverage report artifact, including declared
+  parity and live-discovered model gap counts;
 - checks the cached WSDL files against the live Yandex Direct API on schedule.
 
 #### Re-recording write cassettes
@@ -440,6 +499,29 @@ The VCR config in `tests/conftest.py` already strips `Authorization`,
 `Client-Login`, cookies and any response header containing the substring
 `login`, but manual verification is mandatory before committing.
 
+#### Live draft write tests
+
+The `integration_live_write` tier is manual-only and intentionally separate
+from sandbox cassette tests. In rewrite mode it runs against the production
+Yandex Direct API, but it may only create disposable draft resources and
+delete the exact IDs it created in the same test run. Current coverage is
+limited to a guarded campaign draft create -> get -> delete check.
+
+Replay the checked-in cassette:
+
+```bash
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v
+```
+
+Re-record it only when you intentionally want to verify live draft behavior:
+
+```bash
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite
+```
+
+Do not add tests to this tier that accept external IDs, resume/suspend/archive
+existing resources, mutate bids, or touch serving campaigns.
+
 ### Release Process
 
 Build, validate and upload to PyPI:
@@ -501,14 +583,16 @@ YANDEX_DIRECT_LOGIN=ваш_логин_на_яндексе
 direct --token ВАШ_ТОКЕН --login ВАШ_ЛОГИН campaigns get
 ```
 
-Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет через `direct`.
+Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
+через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с
+подсказкой `use direct instead of direct-cli`.
 
 ### Глобальные опции
 
 | Опция | Описание |
 |-------|----------|
 | `--token` | OAuth-токен доступа к API |
-| `--login` | Логин рекламодателя на Яндексе |
+| `--login` | Direct client login |
 | `--sandbox` | Использовать тестовое API (песочница) |
 
 ### Использование
@@ -530,17 +614,20 @@ Command naming rules:
 - в документации и примерах каноническими считаются `get`,
   `check-dictionaries` и `has-search-volume`
 
-`direct-cli` владеет публичным naming contract. `tapi-yandex-direct` может
-влиять на внутренний transport layer, но не определяет канонические CLI-имена.
+Публичный naming contract задаёт исполняемый файл `direct`. Имя пакета
+`direct-cli` и deprecated shim не определяют канонические CLI-имена.
+`tapi-yandex-direct` может влиять на внутренний transport layer, но не
+определяет канонические CLI-имена.
 
 Текущая политика — canonical-only. Исторические aliases по умолчанию не
 сохраняются в runtime CLI. Если совместимость когда-нибудь понадобится, alias
 должен быть добавлен как явное exception-правило с конкретным legacy syntax из
 `tapi-yandex-direct`, который действительно нужно поддержать.
 
-`direct-cli` — это транспортный слой над API Яндекс Директа. Канонические
-имена CLI-групп следуют нормализованным Python-именам из
-`tapi-yandex-direct`, а имена подкоманд — это kebab-case проекции API-методов.
+`direct` — это канонический transport entrypoint над API Яндекс Директа,
+устанавливаемый пакетом `direct-cli`. Канонические имена CLI-групп следуют
+нормализованным Python-именам из `tapi-yandex-direct`, а имена подкоманд —
+это kebab-case проекции API-методов.
 
 Базовые соответствия:
 
@@ -575,8 +662,10 @@ Naming rules:
   - multiword commands use kebab-case
   - examples: `get`, `set-bids`, `check-campaigns`, `has-search-volume`
 
-`direct-cli` владеет публичным naming contract. `tapi-yandex-direct` может
-влиять на внутренний transport layer, но не определяет канонические CLI-имена.
+Публичный naming contract задаёт исполняемый файл `direct`. Имя пакета
+`direct-cli` и deprecated shim не определяют канонические CLI-имена.
+`tapi-yandex-direct` может влиять на внутренний transport layer, но не
+определяет канонические CLI-имена.
 
 Текущая политика — canonical-only. Исторические aliases по умолчанию не
 сохраняются в runtime CLI. Если совместимость когда-нибудь понадобится, alias
@@ -724,7 +813,7 @@ direct ads delete --id 99999
 ```bash
 direct keywords get --campaign-ids 1,2,3
 direct keywords add --adgroup-id 12345 --keyword "купить ноутбук" --bid 10.50 --context-bid 5.25 --user-param-1 segment-a --user-param-2 segment-b --dry-run
-direct keywords update --id 88888 --bid 15.00 --context-bid 6.00 --status SUSPENDED
+direct keywords update --id 88888 --keyword "updated keyword text"
 direct keywords delete --id 88888
 ```
 
@@ -746,10 +835,14 @@ direct reports list-types
 # Справочники и изменения
 direct dictionaries get --names Currencies,GeoRegions
 direct dictionaries get-geo-regions --name Москва --region-ids 225,187 --exact-names Москва,Санкт-Петербург --fields GeoRegionId,GeoRegionName
+
+# Информация о клиенте
+direct clients get --fields ClientId,Login,Currency
+
+# Изменения
 direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
-direct clients get --fields ClientId,Login,Currency
 
 # Исследование ключевых слов и ретаргетинг
 direct keywordsresearch has-search-volume --keywords "купить ноутбук,купить компьютер"
@@ -774,6 +867,17 @@ direct smartadtargets update --id 456 --priority HIGH
 direct smartadtargets set-bids --id 456 --average-cpc 10.5 --average-cpa 15 --priority HIGH
 direct dynamicads set-bids --id 789 --bid 12.5 --context-bid 9 --priority HIGH
 
+# Общие стратегии ставок
+direct strategies get --limit 5
+direct strategies add --name "Общая стратегия" --type WbMaximumClicks --params '{"SpendLimit":1000000000,"AverageCpc":30000000}' --dry-run
+direct strategies update --id 42 --params '{"AverageCpc":35000000}' --dry-run
+direct strategies archive --id 42 --dry-run
+
+# Динамические таргеты по фиду
+direct dynamicfeedadtargets get --adgroup-ids 123 --limit 5
+direct dynamicfeedadtargets add --adgroup-id 33 --name "Срез фида А" --condition "CATEGORY:EQUALS:shoes" --bid 5 --dry-run
+direct dynamicfeedadtargets set-bids --id 789 --bid 6.5 --context-bid 4 --dry-run
+
 # Расширения, ассеты, фиды и клиенты
 direct sitelinks add --sitelink "Docs|https://example.com/docs" --sitelink "Help|https://example.com/help|Desk" --dry-run
 direct vcards add --campaign-id 555 --country "Россия" --city "Москва" --company-name "Acme" --work-time 1#5#9#0#18#0 --phone-country-code +7 --phone-city-code 495 --phone-number 1234567 --dry-run
@@ -789,12 +893,13 @@ direct agencyclients add-passport-organization-member --passport-organization-lo
 direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
 ```
 
-### Известный Transport Gap
+### Известная неподдерживаемая API-операция
 
-`dynamicads update` пока остаётся transport gap. Downstream-обёртки могут
-ожидать эту операцию, но текущая help-поверхность установленного CLI не
-экспортирует `dynamicads update`. До появления реальной команды считайте её
-неподдерживаемой.
+`dynamicads update` unsupported by API. Сервис Яндекс Директа
+`dynamictextadtargets` экспортирует `add`, `get`, `delete`, `suspend`,
+`resume` и `setBids`, но не экспортирует `update`. Не добавляйте и не
+используйте `direct dynamicads update`, пока Яндекс не предоставит реальный
+API-метод.
 
 ### Форматы вывода
 
@@ -843,19 +948,22 @@ direct campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
 
 ### Тестирование
 
-В `tests/` три уровня тестов:
+В `tests/` четыре уровня тестов:
 
 | Уровень | Маркер | Сеть | Нужен токен |
 |---|---|---|---|
 | Юнит / CLI / dry-run | *(без маркера)* | Нет | Нет |
 | Read-only интеграция | `-m integration` | Да (prod API, только чтение) | Да |
 | Write интеграция | `-m integration_write` | Нет (replay VCR-кассет) | Нет |
+| Live draft write интеграция | `-m integration_live_write` | Да при записи, иначе VCR replay | Да + `YANDEX_DIRECT_LIVE_WRITE=1` |
 
 ```bash
 pip install -e ".[dev]"
 pytest                              # быстрый уровень — без токена
 pytest -m integration -v            # read-only интеграция (нужен токен)
 pytest -m integration_write -v      # replay write-кассет (токен не нужен)
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v  # replay live draft-кассеты
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # перезапись live draft-кассеты
 ```
 
 #### Перезапись write-кассет
@@ -886,6 +994,30 @@ VCR-конфиг в `tests/conftest.py` уже стрипает `Authorization`,
 куки и любые response-заголовки с подстрокой `login`, но ручная проверка
 перед коммитом обязательна.
 
+#### Live write только на черновиках
+
+Уровень `integration_live_write` запускается только вручную и отделен от
+sandbox/VCR-тестов. В rewrite-режиме он ходит в production API Яндекс Директа,
+но может только создавать одноразовые черновики и удалять ровно те ID, которые
+были созданы в этом же тестовом прогоне. Текущее покрытие: guarded create ->
+get -> delete для draft-кампании.
+
+Replay закоммиченной кассеты:
+
+```bash
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v
+```
+
+Перезапись после явного решения проверить live draft-поведение:
+
+```bash
+YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite
+```
+
+В этот уровень нельзя добавлять тесты, которые принимают внешние ID,
+возобновляют/останавливают/архивируют существующие ресурсы, меняют ставки или
+трогают кампании, которые могут показываться.
+
 ### Публикация на PyPI
 
 Сборка, проверка и загрузка на PyPI: