direct-cli 0.3.6__tar.gz → 0.3.8__tar.gz

{direct_cli-0.3.6 → direct_cli-0.3.8}/.github/workflows/claude.yml

@@ -46,5 +46,5 @@ jobs:
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
+          claude_args: "--model claude-opus-4-7"
 

direct_cli-0.3.8/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.3.8
+
+**BREAKING CHANGES:**
+
+- `direct ads update` now requires `--type {TEXT_AD,TEXT_IMAGE_AD,MOBILE_APP_AD}`. Scripts that called `ads update` with only field flags will fail with `Missing option '--type'`. Mirrors the WSDL one-of choice between TextAd/TextImageAd/MobileAppAd update subtypes (PR #197).
+- `direct ads add --type TEXT_IMAGE_AD` rejects `--title/--text` (TEXT_IMAGE_AD has no such WSDL fields). `direct ads update --status` rejected — use `ads suspend/resume/archive/unarchive` for status changes (PR #190).
+- `direct ads add --type MOBILE_APP_AD --href` rejected — MobileAppAd uses `--tracking-url`, not `--href` (PR #196).
+- `direct feeds add` now requires `--business-type {RETAIL,HOTELS,REALTY,AUTOMOBILES,FLIGHTS,OTHER}`. Mirrors WSDL FeedAddItem.BusinessType (minOccurs=1) (PR #201).
+
+**Schema gate — mutating ops parity:**
+
+- Extended the WSDL `*FieldNames` schema gate (introduced for `get` in 0.3.7) to mutating operations (`add/update/set/setBids/lifecycle`). Added per-operation waiver granularity via `SCHEMA_GATE_OPERATION_WAIVERS` (PR #181).
+- Promoted dynamicads, bidmodifiers add/set, adimages/advideos/vcards add (media payloads), adextensions/retargeting/feeds.add typed fixtures to `PAYLOAD_CASES` (PRs #184, #185, #187, #188).
+- Added MOBILE_APP_AD branch to `ads add` mirroring WSDL `MobileAppAdAdd` (PR #190).
+- `bidmodifiers.delete` correctly classified as a real destructive WSDL operation and added to schema gate (PR #194); the earlier "Helper/legacy surface" rationale was a mis-classification — see post-mortem in #199 / PR #200.
+
+**Strict WSDL parity policy:**
+
+- Documented "Strict WSDL parity" principle in `CLAUDE.md`: `DRY_RUN_PAYLOAD_EXCLUSIONS` may only contain entries from five legitimate categories (read-path `*.get`, runtime-deprecated, v4-not-in-v5-wsdl, custom non-RPC endpoints, methods covered by `tests/test_dry_run.py`). New guard test `test_dry_run_exclusions_have_no_helper_or_legacy_rationale` fails CI if any rationale uses banned phrases (PR #200).
+
+**Integration test coverage:**
+
+- Added read-only sandbox integration tests for `changes`, `keywordsresearch`, `balance` (PR #186).
+- Added v5 write integration coverage for `strategies` lifecycle, `retargeting update`, `bids get/set-auto`, plus `auth status/list` read-only tests (PR #189).
+- Re-recorded TestWriteBidsRead cassettes against live API and rewrote host to sandbox so the bids endpoints get real coverage in replay mode (PR #193).
+
+**CI infrastructure:**
+
+- Switched Claude code-review GitHub Action from default (Sonnet 4.5) to Claude Opus 4.7 for deeper PR review (PR #192).
+
+**Refs:** Closes issues #118, #136, #137, #175, #176, #180, #183, #191, #199.
+
+## 0.3.3
+
+**BREAKING CHANGE:** OAuth profiles created before 0.3.3 (without `refresh_token` and `expires_at`) are no longer accepted. Any such profile will fail immediately with an "incomplete profile" error. Run `direct auth login --profile <name>` to re-authenticate and create a valid 0.3.3 profile.
+
+- Added refresh token persistence for OAuth profiles.
+- Added automatic OAuth access token refresh before expiry.
+- Added `expires_in` details to `direct auth status`.
+- Added JSON output for `direct auth status`.
+- Kept `direct auth login --oauth-token` as a manual access-token import without auto-refresh.

{direct_cli-0.3.6 → direct_cli-0.3.8}/CLAUDE.md

@@ -24,7 +24,9 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **Request flow:** `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex API → `output.py` (format/print).
 
-**Credentials priority:** CLI flags (`--token`, `--login`) > env vars (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > `.env` file. `load_dotenv()` runs at `cli.py` import time.
+**Credentials priority (CLI):** CLI flags (`--token`, `--login`) > active profile from `direct auth login` > env vars (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > `.env` file > 1Password/Bitwarden refs. See `direct_cli/auth.py:600` (`get_credentials`) and README table for the full chain. `load_dotenv()` runs at `cli.py` import time.
+
+**Credentials priority (tests):** **inverted** — env vars > active profile > skip. Tests must not silently hit production when a developer has an active `direct auth` profile, so env vars take precedence over the profile (see `tests/test_v4_live_contracts.py::_credentials`).
 
 **Shared utilities** (`utils.py`): `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`, `COMMON_FIELDS` dict. All command modules import from here — don't duplicate.
 
@@ -41,6 +43,15 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **Runtime-deprecated methods:** WSDL-visible methods that Yandex rejects at runtime belong in `RUNTIME_DEPRECATED_METHODS` (`direct_cli/wsdl_coverage.py`) and must fail with `click.UsageError` before request construction. `agencyclients add` is blocked this way; use `agencyclients add-passport-organization`.
 
+**Strict WSDL parity:** `DRY_RUN_PAYLOAD_EXCLUSIONS` in `tests/api_coverage_payloads.py` must NOT contain any entry whose rationale claims the CLI surface is a «helper», «legacy», or «not part of strict WSDL parity». If the WSDL declares the operation, the CLI mirrors it 1:1 with a `PAYLOAD_CASES` fixture. Legitimate permanent exclusions are limited to:
+- read-path `*.get` (covered by SelectionCriteria tests);
+- runtime-deprecated methods (see `RUNTIME_DEPRECATED_METHODS`);
+- v4 methods that have no v5 WSDL (covered by `direct_cli/v4_contracts.py`);
+- custom non-RPC endpoints (e.g. `reports.get` — TSV stream);
+- methods explicitly covered by `tests/test_dry_run.py::test_<service>_<op>_payload`.
+
+A guard in `tests/test_api_coverage.py::test_dry_run_exclusions_have_no_helper_or_legacy_rationale` enforces this — any rationale outside those five categories that uses the banned phrasing is a mis-classification: write a `PAYLOAD_CASES` fixture instead. See post-mortem in issue #199.
+
 **SelectionCriteria:** Resources like `adgroups`, `ads`, `keywords` require at least one of `Ids`, `CampaignIds`, or `AdGroupIds` — otherwise API error 4001.
 
 **Error handling:** All commands wrap API calls in `try/except Exception` → `print_error(str(e))` + `raise click.Abort()`.
@@ -55,6 +66,7 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 - **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.
 - **Integration** (`test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if absent.
+- **Credential resolution in tests:** env vars first, then active `direct auth` profile, then skip. This is **inverted** vs. CLI (where the profile wins) on purpose: a developer machine with an active profile must not silently hit production on a plain `pytest`.
 
 ## Dangerous Commands — Never Auto-Test
 

{direct_cli-0.3.6 → direct_cli-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.6
+Version: 0.3.8
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -125,6 +125,8 @@ fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile token
 with a login from the project `.env`. For multi-account setups, prefer OAuth
 profiles or profile-specific env vars instead of base credentials.
 
+> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+
 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`.
@@ -158,6 +160,24 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Tags
+
+Campaign tags are managed as `{TagID, Tag}` pairs. Use `TagID=0` to create a
+new campaign tag. Banner/ad tags are assigned by campaign tag IDs. Update
+methods replace the full tag list for the target campaign or banner, so pass
+existing tags again if they must remain assigned. Ad group tags are filter-only
+through `direct adgroups get --tag-ids/--tags`; this release does not add ad
+group tag mutation commands.
+
+```bash
+direct v4tags get-campaigns --campaign-ids 3193279,1634563
+direct v4tags get-banners --banner-ids 2571700,2571745
+direct v4tags get-banners --campaign-ids 3193279
+direct v4tags update-campaigns --campaign-id 3193279 --tag 0=akapulko --tag 16590=orange --dry-run
+direct v4tags update-banners --banner-ids 2571700,2571745 --tag-ids 16590,16734 --dry-run
+direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
+```
+
 ### V4 Live Events
 
 ```bash
@@ -178,6 +198,19 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Budget Forecasts
+
+Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
+command and does not poll automatically; repeat `list` or `get` yourself until
+the forecast is ready.
+
+```bash
+direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast list --format table
+direct v4forecast get --forecast-id 123 --format table
+direct v4forecast delete --forecast-id 123
+```
+
 ### V4 Live Finance
 
 Finance methods require an extra financial token for money operations. In the
@@ -462,7 +495,7 @@ direct vcards add --campaign-id 555 --country "Russia" --city "Moscow" --company
 direct adextensions add --callout-text "Free shipping" --dry-run
 direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-run
 direct creatives add --video-id video-id --dry-run
-direct feeds add --name "Feed A" --url "https://example.com/feed.xml" --dry-run
+direct feeds add --name "Feed A" --url "https://example.com/feed.xml" --business-type RETAIL --dry-run
 direct feeds update --id 18 --name "Feed A v2" --url "https://example.com/feed-v2.xml" --dry-run
 direct clients update --client-info "Priority client" --phone +70000000000 --notification-email user@example.com --notification-lang EN --email-subscription RECEIVE_RECOMMENDATIONS=YES --setting DISPLAY_STORE_RATING=NO --dry-run
 direct --login CLIENT_LOGIN clients update --phone +70000000000 --notification-email user@example.com --dry-run
@@ -534,17 +567,22 @@ Four tiers of tests live under `tests/`:
 | 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` |
+| Live draft write integration (v5) | `-m integration_live_write` | Yes when recording, otherwise VCR replay | Yes + `YANDEX_DIRECT_LIVE_WRITE=1` |
+| v4 live read | `-m v4_live_read` | Yes (production v4 JSON API, read-only) | Yes |
+| v4 live account-level report write (opt-in) | `-k _opt_in_write` in `tests/test_v4_live_contracts.py` | Yes (production v4) | Yes + `YANDEX_DIRECT_V4_LIVE_REPORT_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  # live draft cassette replay (v5)
 YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # re-record live draft cassette
+YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1 pytest tests/test_v4_live_contracts.py -k _opt_in_write -v  # v4 wordstat/forecast account-level lifecycle
 ```
 
+The v4 account-level write tier (`YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1`) creates real Wordstat and forecast reports in the production account and deletes them in the same run. There are **no cassettes** — these tests run against live API only. Created IDs are tracked in `~/.direct-cli/test-orphans.json` so that if the run is interrupted between create and delete, the next invocation will retry the cleanup automatically (see `tests/_orphan_store.py`).
+
 #### Smoke command scripts
 
 Every CLI subcommand is classified in `direct_cli/smoke_matrix.py`.
@@ -562,9 +600,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 39 |
-| CLI subcommands including `auth` | 130 |
-| API CLI subcommands excluding `auth` | 126 |
+| CLI groups including `auth` | 40 |
+| CLI subcommands including `auth` | 144 |
+| API CLI subcommands excluding `auth` | 140 |
 
 ### API Coverage And Drift Monitoring
 
@@ -782,6 +820,8 @@ base `YANDEX_DIRECT_LOGIN`; это защищает от смешивания т
 логином из project `.env`. Для нескольких аккаунтов используйте OAuth profiles
 или профильные env vars, а не базовые credentials.
 
+> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с
 подсказкой `use direct instead of direct-cli`.
@@ -1082,7 +1122,7 @@ direct vcards add --campaign-id 555 --country "Россия" --city "Москв
 direct adextensions add --callout-text "Free shipping" --dry-run
 direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-run
 direct creatives add --video-id video-id --dry-run
-direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --dry-run
+direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --business-type RETAIL --dry-run
 direct feeds update --id 18 --name "Фид A v2" --url "https://example.com/feed-v2.xml" --dry-run
 direct clients update --client-info "Приоритетный клиент" --phone +70000000000 --notification-email user@example.com --notification-lang EN --email-subscription RECEIVE_RECOMMENDATIONS=YES --setting DISPLAY_STORE_RATING=NO --dry-run
 direct --login CLIENT_LOGIN clients update --phone +70000000000 --notification-email user@example.com --dry-run
@@ -1155,17 +1195,22 @@ direct campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
 | Юнит / 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` |
+| Live draft write интеграция (v5) | `-m integration_live_write` | Да при записи, иначе VCR replay | Да + `YANDEX_DIRECT_LIVE_WRITE=1` |
+| v4 live read | `-m v4_live_read` | Да (prod v4 JSON API, только чтение) | Да |
+| v4 live запись отчётов на уровне аккаунта (opt-in) | `-k _opt_in_write` в `tests/test_v4_live_contracts.py` | Да (prod v4) | Да + `YANDEX_DIRECT_V4_LIVE_REPORT_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  # replay live draft-кассеты (v5)
 YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # перезапись live draft-кассеты
+YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1 pytest tests/test_v4_live_contracts.py -k _opt_in_write -v  # жизненный цикл v4 wordstat/forecast
 ```
 
+Уровень v4 account-level write (`YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1`) создаёт настоящие Wordstat-отчёты и прогнозы в боевом аккаунте и удаляет их в том же запуске. **Кассет нет** — эти тесты идут только в живой API. Созданные ID пишутся в `~/.direct-cli/test-orphans.json`: если запуск оборвался между create и delete, при следующем вызове осиротевшие ID будут удалены автоматически (см. `tests/_orphan_store.py`).
+
 #### Smoke-скрипты команд
 
 Каждая CLI-подкоманда классифицирована в `direct_cli/smoke_matrix.py`.
@@ -1183,9 +1228,9 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 39 |
-| CLI subcommands с `auth` | 130 |
-| API CLI subcommands без `auth` | 126 |
+| CLI groups с `auth` | 40 |
+| CLI subcommands с `auth` | 144 |
+| API CLI subcommands без `auth` | 140 |
 
 #### Live sandbox write smoke
 

{direct_cli-0.3.6 → direct_cli-0.3.8}/README.md

@@ -82,6 +82,8 @@ fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile token
 with a login from the project `.env`. For multi-account setups, prefer OAuth
 profiles or profile-specific env vars instead of base credentials.
 
+> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+
 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`.
@@ -115,6 +117,24 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Tags
+
+Campaign tags are managed as `{TagID, Tag}` pairs. Use `TagID=0` to create a
+new campaign tag. Banner/ad tags are assigned by campaign tag IDs. Update
+methods replace the full tag list for the target campaign or banner, so pass
+existing tags again if they must remain assigned. Ad group tags are filter-only
+through `direct adgroups get --tag-ids/--tags`; this release does not add ad
+group tag mutation commands.
+
+```bash
+direct v4tags get-campaigns --campaign-ids 3193279,1634563
+direct v4tags get-banners --banner-ids 2571700,2571745
+direct v4tags get-banners --campaign-ids 3193279
+direct v4tags update-campaigns --campaign-id 3193279 --tag 0=akapulko --tag 16590=orange --dry-run
+direct v4tags update-banners --banner-ids 2571700,2571745 --tag-ids 16590,16734 --dry-run
+direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
+```
+
 ### V4 Live Events
 
 ```bash
@@ -135,6 +155,19 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Budget Forecasts
+
+Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
+command and does not poll automatically; repeat `list` or `get` yourself until
+the forecast is ready.
+
+```bash
+direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast list --format table
+direct v4forecast get --forecast-id 123 --format table
+direct v4forecast delete --forecast-id 123
+```
+
 ### V4 Live Finance
 
 Finance methods require an extra financial token for money operations. In the
@@ -419,7 +452,7 @@ direct vcards add --campaign-id 555 --country "Russia" --city "Moscow" --company
 direct adextensions add --callout-text "Free shipping" --dry-run
 direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-run
 direct creatives add --video-id video-id --dry-run
-direct feeds add --name "Feed A" --url "https://example.com/feed.xml" --dry-run
+direct feeds add --name "Feed A" --url "https://example.com/feed.xml" --business-type RETAIL --dry-run
 direct feeds update --id 18 --name "Feed A v2" --url "https://example.com/feed-v2.xml" --dry-run
 direct clients update --client-info "Priority client" --phone +70000000000 --notification-email user@example.com --notification-lang EN --email-subscription RECEIVE_RECOMMENDATIONS=YES --setting DISPLAY_STORE_RATING=NO --dry-run
 direct --login CLIENT_LOGIN clients update --phone +70000000000 --notification-email user@example.com --dry-run
@@ -491,17 +524,22 @@ Four tiers of tests live under `tests/`:
 | 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` |
+| Live draft write integration (v5) | `-m integration_live_write` | Yes when recording, otherwise VCR replay | Yes + `YANDEX_DIRECT_LIVE_WRITE=1` |
+| v4 live read | `-m v4_live_read` | Yes (production v4 JSON API, read-only) | Yes |
+| v4 live account-level report write (opt-in) | `-k _opt_in_write` in `tests/test_v4_live_contracts.py` | Yes (production v4) | Yes + `YANDEX_DIRECT_V4_LIVE_REPORT_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  # live draft cassette replay (v5)
 YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # re-record live draft cassette
+YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1 pytest tests/test_v4_live_contracts.py -k _opt_in_write -v  # v4 wordstat/forecast account-level lifecycle
 ```
 
+The v4 account-level write tier (`YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1`) creates real Wordstat and forecast reports in the production account and deletes them in the same run. There are **no cassettes** — these tests run against live API only. Created IDs are tracked in `~/.direct-cli/test-orphans.json` so that if the run is interrupted between create and delete, the next invocation will retry the cleanup automatically (see `tests/_orphan_store.py`).
+
 #### Smoke command scripts
 
 Every CLI subcommand is classified in `direct_cli/smoke_matrix.py`.
@@ -519,9 +557,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 39 |
-| CLI subcommands including `auth` | 130 |
-| API CLI subcommands excluding `auth` | 126 |
+| CLI groups including `auth` | 40 |
+| CLI subcommands including `auth` | 144 |
+| API CLI subcommands excluding `auth` | 140 |
 
 ### API Coverage And Drift Monitoring
 
@@ -739,6 +777,8 @@ base `YANDEX_DIRECT_LOGIN`; это защищает от смешивания т
 логином из project `.env`. Для нескольких аккаунтов используйте OAuth profiles
 или профильные env vars, а не базовые credentials.
 
+> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с
 подсказкой `use direct instead of direct-cli`.
@@ -1039,7 +1079,7 @@ direct vcards add --campaign-id 555 --country "Россия" --city "Москв
 direct adextensions add --callout-text "Free shipping" --dry-run
 direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-run
 direct creatives add --video-id video-id --dry-run
-direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --dry-run
+direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --business-type RETAIL --dry-run
 direct feeds update --id 18 --name "Фид A v2" --url "https://example.com/feed-v2.xml" --dry-run
 direct clients update --client-info "Приоритетный клиент" --phone +70000000000 --notification-email user@example.com --notification-lang EN --email-subscription RECEIVE_RECOMMENDATIONS=YES --setting DISPLAY_STORE_RATING=NO --dry-run
 direct --login CLIENT_LOGIN clients update --phone +70000000000 --notification-email user@example.com --dry-run
@@ -1112,17 +1152,22 @@ direct campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
 | Юнит / 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` |
+| Live draft write интеграция (v5) | `-m integration_live_write` | Да при записи, иначе VCR replay | Да + `YANDEX_DIRECT_LIVE_WRITE=1` |
+| v4 live read | `-m v4_live_read` | Да (prod v4 JSON API, только чтение) | Да |
+| v4 live запись отчётов на уровне аккаунта (opt-in) | `-k _opt_in_write` в `tests/test_v4_live_contracts.py` | Да (prod v4) | Да + `YANDEX_DIRECT_V4_LIVE_REPORT_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  # replay live draft-кассеты (v5)
 YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rewrite  # перезапись live draft-кассеты
+YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1 pytest tests/test_v4_live_contracts.py -k _opt_in_write -v  # жизненный цикл v4 wordstat/forecast
 ```
 
+Уровень v4 account-level write (`YANDEX_DIRECT_V4_LIVE_REPORT_WRITE=1`) создаёт настоящие Wordstat-отчёты и прогнозы в боевом аккаунте и удаляет их в том же запуске. **Кассет нет** — эти тесты идут только в живой API. Созданные ID пишутся в `~/.direct-cli/test-orphans.json`: если запуск оборвался между create и delete, при следующем вызове осиротевшие ID будут удалены автоматически (см. `tests/_orphan_store.py`).
+
 #### Smoke-скрипты команд
 
 Каждая CLI-подкоманда классифицирована в `direct_cli/smoke_matrix.py`.
@@ -1140,9 +1185,9 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 39 |
-| CLI subcommands с `auth` | 130 |
-| API CLI subcommands без `auth` | 126 |
+| CLI groups с `auth` | 40 |
+| CLI subcommands с `auth` | 144 |
+| API CLI subcommands без `auth` | 140 |
 
 #### Live sandbox write smoke
 

{direct_cli-0.3.6 → direct_cli-0.3.8}/direct_cli/cli.py

@@ -43,10 +43,12 @@ from .commands.strategies import strategies
 from .commands.auth import auth
 from .commands.balance import balance
 from .commands.v4events import v4events
+from .commands.v4forecast import v4forecast
 from .commands.v4finance import v4finance
 from .commands.v4account import v4account
-from .commands.v4shells import v4forecast, v4meta
+from .commands.v4shells import v4meta
 from .commands.v4goals import v4goals
+from .commands.v4tags import v4tags
 from .commands.v4wordstat import v4wordstat
 
 # Load .env file
@@ -186,6 +188,7 @@ for command in (
     v4goals,
     v4events,
     v4wordstat,
+    v4tags,
     v4forecast,
     v4meta,
     auth,

{direct_cli-0.3.6 → direct_cli-0.3.8}/direct_cli/commands/ads.py

@@ -163,21 +163,40 @@ def get(
     default="TEXT_AD",
     help="Ad type",
 )
-@click.option("--title", help="Ad title (TEXT_AD only)")
-@click.option("--text", help="Ad text (TEXT_AD only)")
-@click.option("--href", help="Ad URL (TEXT_AD only)")
-@click.option("--image-hash", help="Ad image hash for TEXT_IMAGE_AD")
+@click.option("--title", help="Ad title (TEXT_AD / MOBILE_APP_AD)")
+@click.option("--text", help="Ad text (TEXT_AD / MOBILE_APP_AD)")
+@click.option("--href", help="Ad URL (TEXT_AD / TEXT_IMAGE_AD)")
+@click.option("--image-hash", help="Ad image hash (TEXT_IMAGE_AD / MOBILE_APP_AD)")
+@click.option(
+    "--action",
+    help="MOBILE_APP_AD call-to-action (MobileAppAdActionEnum, e.g. INSTALL)",
+)
+@click.option("--tracking-url", help="MOBILE_APP_AD tracking URL")
+@click.option("--age-label", help="MOBILE_APP_AD age label (MobAppAgeLabelEnum)")
 @click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def add(ctx, adgroup_id, ad_type, title, text, href, image_hash, dry_run):
+def add(
+    ctx,
+    adgroup_id,
+    ad_type,
+    title,
+    text,
+    href,
+    image_hash,
+    action,
+    tracking_url,
+    age_label,
+    dry_run,
+):
     """Add new ad"""
     try:
         ad_type_norm = (ad_type or "TEXT_AD").upper().replace("-", "_")
-        supported_types = {"TEXT_AD", "TEXT_IMAGE_AD"}
+        supported_types = {"TEXT_AD", "TEXT_IMAGE_AD", "MOBILE_APP_AD"}
         if ad_type_norm not in supported_types:
             raise click.UsageError(
                 "Invalid value for '--type': "
-                f"{ad_type!r} is not one of 'TEXT_AD', 'TEXT_IMAGE_AD'."
+                f"{ad_type!r} is not one of "
+                "'TEXT_AD', 'TEXT_IMAGE_AD', 'MOBILE_APP_AD'."
             )
 
         ad_data = {"AdGroupId": adgroup_id}
@@ -200,6 +219,11 @@ def add(ctx, adgroup_id, ad_type, title, text, href, image_hash, dry_run):
                 "Href": href,
             }
         elif ad_type_norm == "TEXT_IMAGE_AD":
+            if title or text:
+                raise click.UsageError(
+                    "--title/--text are only valid for TEXT_AD. "
+                    "For TEXT_IMAGE_AD, use --image-hash and --href."
+                )
             if not image_hash or not href:
                 raise click.UsageError(
                     "TEXT_IMAGE_AD requires both --image-hash and --href"
@@ -208,10 +232,37 @@ def add(ctx, adgroup_id, ad_type, title, text, href, image_hash, dry_run):
                 "AdImageHash": image_hash,
                 "Href": href,
             }
-            if title:
-                ad_data["TextImageAd"]["Title"] = title
-            if text:
-                ad_data["TextImageAd"]["Text"] = text
+        elif ad_type_norm == "MOBILE_APP_AD":
+            if href:
+                raise click.UsageError(
+                    "--href does not apply to MOBILE_APP_AD. "
+                    "Use --tracking-url instead."
+                )
+            missing_fields = [
+                option_name
+                for option_name, value in (
+                    ("--title", title),
+                    ("--text", text),
+                    ("--action", action),
+                )
+                if not value
+            ]
+            if missing_fields:
+                raise click.UsageError(
+                    "MOBILE_APP_AD requires " + ", ".join(missing_fields)
+                )
+            mobile_app_ad = {
+                "Title": title,
+                "Text": text,
+                "Action": action.upper(),
+            }
+            if image_hash:
+                mobile_app_ad["AdImageHash"] = image_hash
+            if tracking_url:
+                mobile_app_ad["TrackingUrl"] = tracking_url
+            if age_label:
+                mobile_app_ad["AgeLabel"] = age_label.upper()
+            ad_data["MobileAppAd"] = mobile_app_ad
 
         body = {"method": "add", "params": {"Ads": [ad_data]}}
 
@@ -237,30 +288,98 @@ def add(ctx, adgroup_id, ad_type, title, text, href, image_hash, dry_run):
 
 @ads.command()
 @click.option("--id", "ad_id", required=True, type=int, help="Ad ID")
-@click.option("--status", help="New status")
-@click.option("--title", help="New text ad title")
-@click.option("--text", help="New text ad text")
-@click.option("--href", help="New text ad URL")
-@click.option("--image-hash", help="New text image ad image hash")
+@click.option(
+    "--type",
+    "ad_type",
+    required=True,
+    help="Ad subtype: TEXT_AD | TEXT_IMAGE_AD | MOBILE_APP_AD",
+)
+@click.option(
+    "--status",
+    help=(
+        "Deprecated: not part of WSDL AdUpdateItem. "
+        "Use 'direct ads suspend/resume/archive/unarchive' instead."
+    ),
+)
+@click.option("--title", help="Title (TEXT_AD / MOBILE_APP_AD)")
+@click.option("--text", help="Text (TEXT_AD / MOBILE_APP_AD)")
+@click.option("--href", help="URL (TEXT_AD / TEXT_IMAGE_AD)")
+@click.option("--image-hash", help="Image hash (TEXT_IMAGE_AD / MOBILE_APP_AD)")
+@click.option(
+    "--action",
+    help="MOBILE_APP_AD call-to-action (MobileAppAdActionEnum, e.g. INSTALL)",
+)
+@click.option("--tracking-url", help="MOBILE_APP_AD tracking URL")
+@click.option("--age-label", help="MOBILE_APP_AD age label (MobAppAgeLabelEnum)")
 @click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def update(ctx, ad_id, status, title, text, href, image_hash, dry_run):
+def update(
+    ctx,
+    ad_id,
+    ad_type,
+    status,
+    title,
+    text,
+    href,
+    image_hash,
+    action,
+    tracking_url,
+    age_label,
+    dry_run,
+):
     """Update ad"""
+    if status:
+        raise click.UsageError(
+            "Use 'direct ads suspend/resume/archive/unarchive' to change status. "
+            "The --status flag is not supported by WSDL AdUpdateItem."
+        )
+
+    ad_type_norm = ad_type.upper().replace("-", "_")
+    supported_types = {"TEXT_AD", "TEXT_IMAGE_AD", "MOBILE_APP_AD"}
+    if ad_type_norm not in supported_types:
+        raise click.UsageError(
+            "Invalid value for '--type': "
+            f"{ad_type!r} is not one of "
+            "'TEXT_AD', 'TEXT_IMAGE_AD', 'MOBILE_APP_AD'."
+        )
+
     try:
         ad_data = {"Id": ad_id}
 
-        if status:
-            ad_data["Status"] = status
-        if any([title, text, href]):
-            ad_data["TextAd"] = {}
+        if ad_type_norm == "TEXT_AD":
+            text_ad = {}
             if title:
-                ad_data["TextAd"]["Title"] = title
+                text_ad["Title"] = title
             if text:
-                ad_data["TextAd"]["Text"] = text
+                text_ad["Text"] = text
+            if href:
+                text_ad["Href"] = href
+            if text_ad:
+                ad_data["TextAd"] = text_ad
+        elif ad_type_norm == "TEXT_IMAGE_AD":
+            text_image_ad = {}
+            if image_hash:
+                text_image_ad["AdImageHash"] = image_hash
             if href:
-                ad_data["TextAd"]["Href"] = href
-        if image_hash:
-            ad_data["TextImageAd"] = {"AdImageHash": image_hash}
+                text_image_ad["Href"] = href
+            if text_image_ad:
+                ad_data["TextImageAd"] = text_image_ad
+        elif ad_type_norm == "MOBILE_APP_AD":
+            mobile_app_ad = {}
+            if title:
+                mobile_app_ad["Title"] = title
+            if text:
+                mobile_app_ad["Text"] = text
+            if image_hash:
+                mobile_app_ad["AdImageHash"] = image_hash
+            if action:
+                mobile_app_ad["Action"] = action.upper()
+            if tracking_url:
+                mobile_app_ad["TrackingUrl"] = tracking_url
+            if age_label:
+                mobile_app_ad["AgeLabel"] = age_label.upper()
+            if mobile_app_ad:
+                ad_data["MobileAppAd"] = mobile_app_ad
 
         body = {"method": "update", "params": {"Ads": [ad_data]}}