direct-cli 0.3.7__tar.gz → 0.3.9__tar.gz

{direct_cli-0.3.7 → direct_cli-0.3.9}/.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.9/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.3.9
+
+**Added:**
+
+- `direct keywords add` now supports batch mode via `--from-file PATH`
+  (JSONL, one keyword object per line) or `--keywords-json '[…]'`
+  (inline JSON array). The CLI splits input into chunks of 10 — the
+  Yandex Direct API limit for `keywords.add` documented at
+  https://yandex.ru/dev/direct/doc/dg/objects/keyword.html — preserves
+  input order, and merges `AddResults` from every chunk into a single
+  response. Item-level errors do not abort the batch. If a chunk-level
+  exception breaks the loop, already-created Ids are printed to stderr
+  with a "Partial success before failure" header so a retry doesn't
+  duplicate them. Pre-flight warning when any AdGroupId in the input
+  exceeds the per-ad-group limit of 200 keywords (the API rejects the
+  excess with per-item errors; warning surfaces this before any chunk
+  is sent). Row keys use WSDL CamelCase (`Keyword`, `AdGroupId`,
+  `Bid`, `ContextBid`, `UserParam1`, `UserParam2`); unknown keys are
+  rejected with the row number, and JSON booleans are explicitly
+  rejected to prevent silent `True → 1` coercion. `--adgroup-id` is
+  optional in batch mode and acts as a default, overridable per row.
+  `--dry-run` prints the first chunk's payload alongside
+  `{chunks, totalItems, chunkSize}`. Single-item mode (`--keyword`)
+  is unchanged (#203).
+- `direct campaigns add` typed flags for CPA strategies and
+  cross-cutting `CampaignAddItem` fields: `--goal-id` (single
+  Metrika goal), `--crr` (CRR percentage for
+  `PAY_FOR_CONVERSION_CRR`),
+  `--priority-goals goal_id:value,…` (multi-goal CPA via
+  WSDL `PriorityGoalsArray`), `--average-cpa MICRO_RUBLES`,
+  `--bid-ceiling MICRO_RUBLES`, `--counter-ids`
+  (TextCampaign/DynamicTextCampaign), `--notification JSON`
+  (`CampaignBase.Notification` with `SmsSettings`/`EmailSettings`
+  shape validation), `--time-targeting JSON`
+  (`CampaignAddItem.TimeTargeting` with `HolidaysSchedule`
+  shape validation). Strategy-subtype compatibility is enforced
+  via `UsageError` at CLI level both ways: WSDL-incompatible flags
+  are rejected (e.g. `--average-cpa` for `HIGHEST_POSITION`,
+  `--crr` outside `PAY_FOR_CONVERSION_CRR`,
+  `--bid-ceiling` for `PayForConversionCrr` /
+  `PayForConversionMultipleGoals`), and WSDL `minOccurs=1`
+  fields are demanded up-front (e.g. picking `AVERAGE_CPA`
+  without `--average-cpa`+`--goal-id`, or `PAY_FOR_CONVERSION_CRR`
+  without `--crr`+`--goal-id`, or `*_MULTIPLE_GOALS` without
+  `--priority-goals`, all fail at the CLI instead of the API).
+  Closes #204.
+
+**Notes:**
+
+- Issue #204 also requested `--goals` (array) and
+  `--network-settings`; both were dropped after WSDL audit. Yandex
+  `Strategy*Add` complex types declare only scalar `GoalId`, so
+  multi-goal CPA is shipped through `--priority-goals` instead
+  (correct WSDL path: `TextCampaign.PriorityGoals.Items[].GoalId/Value`).
+  No `NetworkSettings` field exists on `CampaignAddItem` /
+  `TextCampaignAddItem` / `DynamicTextCampaignAddItem` /
+  `SmartCampaignAddItem` in the current `campaigns.xml` WSDL.
+
+**Fixed:**
+
+- Refreshed `TestWriteFeeds` and `TestWriteSmartAdTargets` VCR cassettes against a real sandbox, dropped the `_FEED_REGRESSION_PATTERNS` skip workaround, and updated `sandbox_feed` / `sandbox_smart_adgroup` fixtures to pass the now-WSDL-required `--business-type RETAIL` (FeedAddItem) and `--counter-id` (SmartCampaignAddItem). Tests now skip only on genuine sandbox limitations, not on the missing-option proxy that the workaround papered over (#206, fallout from #201). Test invocation now also passes `--login` and prefers env vars over an active `direct auth` profile, matching the inversion documented in CLAUDE.md.
+- WSDL parity gate now fails fast when `COMMAND_WSDL_MAP` points at a container that does not exist in the WSDL request schema. The previous skip-on-empty-required-list silently masked typo'd container names (#206, Copilot follow-up from #205).
+- `WSDL_FIELD_TO_CLI_OPTION` no longer references the non-existent generic `--file` flag. `SourceType` maps to `{--url}` and `ImageData` maps to `{--image-data, --image-file}`, matching the real CLI surface (#206, Copilot follow-up from #205).
+- `direct bidmodifiers set --help` no longer advertises the rejected `--campaign-id`/`--type` legacy path; the rejection now happens via an eager Click callback (same pattern as deprecated `keywords update` options), preserving the existing `UsageError` message for regression coverage (#206, Copilot follow-up from #214).
+
+**Refs:** Closes issues #122, #138, #198, #202, #203, #204, #206, #207.
+
+## 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.7 → direct_cli-0.3.9}/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,24 @@ 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.
+
+**WSDL parity gate:** `tests/test_wsdl_parity_gate.py` runs four invariant checks across every `add`/`update`/`set` command in `WRITE_SANDBOX`:
+
+1. *Empty subtype no-op* — a mutating command with only the resource ID must refuse to send the payload (no silent no-op on the live API).
+2. *Silent data loss* — a typed flag that does not belong to the chosen `--type` must raise `UsageError`, not be dropped.
+3. *WSDL `minOccurs=1` not validated* — every required WSDL item field must be enforced either via Click `required=True` *or* a documented `UsageError` body check (listed in `INTERNAL_VALIDATION`).
+4. *Strategy enum drift* — `STRATEGY_TYPES` (`direct_cli/commands/strategies.py`) must equal the subtype-of-one field names in `StrategyAddItem`.
+
+Adding a new mutating command requires extending `COMMAND_WSDL_MAP` in `tests/test_wsdl_parity_gate.py` (the coverage test fails otherwise) and, if the WSDL request has a non-mechanical field name, also `WSDL_FIELD_TO_CLI_OPTION`. Tracked in issue #198.
+
 **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 +75,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.7 → direct_cli-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.7
+Version: 0.3.9
 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`.
@@ -382,6 +384,15 @@ direct campaigns add --name "My Campaign" --start-date 2024-02-01 --type TEXT_CA
 direct campaigns add --name "Dynamic Campaign" --start-date 2024-02-01 --type DYNAMIC_TEXT_CAMPAIGN --setting ADD_METRICA_TAG=NO --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --dry-run
 direct campaigns add --name "Smart Campaign" --start-date 2024-02-01 --type SMART_CAMPAIGN --network-strategy AVERAGE_CPC_PER_FILTER --filter-average-cpc 1000000 --counter-id 123 --dry-run
 
+# CPA strategy (single goal): --goal-id required, --average-cpa / --bid-ceiling are micro-rubles
+direct campaigns add --name "CPA Campaign" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy AVERAGE_CPA --network-strategy SERVING_OFF --goal-id 1234567 --average-cpa 500000000 --bid-ceiling 1000000000 --counter-ids 111,222 --dry-run
+
+# Multi-goal CPA via PriorityGoals (goal_id:value pairs, WSDL PriorityGoalsItem)
+direct campaigns add --name "Multi-Goal CPA" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy AVERAGE_CPA_MULTIPLE_GOALS --network-strategy SERVING_OFF --priority-goals 1234567:80,9876543:20 --bid-ceiling 1000000000 --dry-run
+
+# Notification (Sms/Email) and TimeTargeting accept JSON with WSDL CamelCase keys
+direct campaigns add --name "Notify+Schedule" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
+
 # Update / lifecycle
 direct campaigns update --id 12345 --name "New Name" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
 direct campaigns suspend --id 12345
@@ -408,11 +419,21 @@ direct adgroups delete --id 67890
 direct ads get --campaign-ids 1,2,3
 direct ads get --adgroup-ids 45678 --format table
 direct ads add --adgroup-id 12345 --type TEXT_AD --title "Title" --text "Ad text" --href "https://example.com" --dry-run
-direct ads add --adgroup-id 12345 --type TEXT_IMAGE_AD --image-hash abcdefghijklmnopqrst --href "https://example.com" --title "Banner" --text "Image ad" --dry-run
-direct ads update --id 99999 --status PAUSED --title "New Title" --text "New text" --href "https://example.com" --image-hash abcdefghijklmnopqrst
+direct ads add --adgroup-id 12345 --type TEXT_AD --title "Title" --text "Ad text" --href "https://example.com" --title2 "Second headline" --display-url-path "deals" --mobile YES --vcard-id 111 --sitelink-set-id 222 --turbo-page-id 333 --ad-extensions "444,555" --dry-run
+direct ads add --adgroup-id 12345 --type TEXT_IMAGE_AD --image-hash abcdefghijklmnopqrst --href "https://example.com" --turbo-page-id 555 --dry-run
+direct ads update --id 99999 --type TEXT_AD --title "New Title" --text "New text" --href "https://example.com"
+direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --title2 "New second headline" --vcard-id 222
 direct ads delete --id 99999
 ```
 
+Available TEXT_AD typed flags for `ads add` / `ads update`: `--title`, `--text`,
+`--href`, `--image-hash`, `--title2`, `--display-url-path`, `--vcard-id`,
+`--sitelink-set-id`, `--turbo-page-id`. `--mobile` (default `NO`) and
+`--ad-extensions` are `ads add`-only — `TextAdUpdate` does not contain `Mobile`,
+and ad-extension updates go through the `CalloutSetting` WSDL field, which is
+not yet exposed by the CLI. TEXT_IMAGE_AD additionally accepts `--turbo-page-id`.
+
 #### Keywords
 
 ```bash
@@ -422,6 +443,33 @@ direct keywords update --id 88888 --keyword "updated keyword text"
 direct keywords delete --id 88888
 ```
 
+**Batch keyword upload** (CLI auto-chunks to the API limit of 10 per request):
+
+```bash
+# From a JSONL file (one keyword object per line)
+direct keywords add --adgroup-id 12345 --from-file keywords.jsonl
+
+# Inline JSON array
+direct keywords add --keywords-json '[{"Keyword":"buy laptop","Bid":10000000},{"Keyword":"buy desktop"}]'
+```
+
+Example `keywords.jsonl`:
+
+```jsonl
+{"Keyword":"buy laptop","Bid":10000000,"UserParam1":"src=ad1"}
+{"Keyword":"buy desktop","ContextBid":5000000}
+{"Keyword":"купить ноутбук","AdGroupId":99999}
+```
+
+- Row keys use WSDL CamelCase: `Keyword`, `AdGroupId`, `Bid`, `ContextBid`, `UserParam1`, `UserParam2`.
+- `--adgroup-id` provides the default group ID; rows can override it via per-row `AdGroupId`.
+- Each effective row must resolve `Keyword` and `AdGroupId`; unknown fields are rejected with the row number.
+- API limit: 10 items per `keywords.add` request — see [Yandex Direct docs](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). The CLI sends as many chunks as needed and merges `AddResults`.
+- API limit: 200 keywords per ad group. The CLI prints a warning if any `AdGroupId` in the input exceeds it; the API rejects the excess as per-item errors.
+- Item-level errors from the API do not abort the batch; the merged output includes successes and per-item errors.
+- If a chunk fails with a network-level error mid-batch, already-created Ids are printed to stderr (`Partial success before failure`) so a retry doesn't duplicate them.
+- `--dry-run` shows the first chunk's payload plus `{chunks, totalItems, chunkSize}`.
+
 #### Reports
 
 ```bash
@@ -478,8 +526,8 @@ direct dynamicads set-bids --id 789 --bid 12500000 --context-bid 9000000 --prior
 
 # Shared bidding strategies
 direct strategies get --limit 5
-direct strategies add --name "Shared Clicks" --type WbMaximumClicks --spend-limit 1000000000 --average-cpc 30000000 --dry-run
-direct strategies update --id 42 --type WbMaximumClicks --average-cpc 35000000 --dry-run
+direct strategies add --name "Shared Clicks" --type WbMaximumClicks --weekly-spend-limit 1000000000 --bid-ceiling 30000000 --dry-run
+direct strategies update --id 42 --type WbMaximumClicks --weekly-spend-limit 35000000 --dry-run
 direct strategies archive --id 42 --dry-run
 
 # Dynamic feed ad targets
@@ -493,7 +541,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
@@ -556,6 +604,17 @@ Use `--dry-run` on `add` / `update` commands to preview the API request before s
 direct campaigns add --name "Test" --start-date 2024-01-01 --dry-run
 ```
 
+### API Errors
+
+Yandex Direct can return a successful HTTP response that still contains
+item-level `Errors` for one object. Direct CLI treats those responses as
+failed operations: it exits non-zero and prints the error code, message, and
+details.
+
+Code `8800` with `Object not found` usually means the object is not available
+under the current `Client-Login` or account. Check the selected `--login`,
+`YANDEX_DIRECT_LOGIN`, or auth profile before retrying.
+
 ### Testing
 
 Four tiers of tests live under `tests/`:
@@ -565,17 +624,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`.
@@ -659,6 +723,12 @@ For `v4account` sandbox smoke, `enable-shared-account` uses
 `account-management` requires `YANDEX_DIRECT_V4ACCOUNT_ACCOUNT_ID`; without it
 the runner reports `NOT_COVERED` for that command.
 
+`clients.update` is opt-in because it mutates client-level account metadata.
+Set `YANDEX_DIRECT_CLIENTS_UPDATE_LOGIN` to an expendable sandbox
+`Client-Login`; the runner passes it through `--login` and updates only
+`ClientInfo` with a unique smoke marker. Without that variable, the runner
+reports `NOT_COVERED` for `clients.update`.
+
 #### Re-recording write cassettes
 
 The `integration_write` pytest tier still replays stored write-test traffic
@@ -813,6 +883,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`.
@@ -1002,6 +1074,15 @@ direct campaigns add --name "Моя кампания" --start-date 2024-02-01 --
 direct campaigns add --name "Динамическая кампания" --start-date 2024-02-01 --type DYNAMIC_TEXT_CAMPAIGN --setting ADD_METRICA_TAG=NO --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --dry-run
 direct campaigns add --name "Смарт-кампания" --start-date 2024-02-01 --type SMART_CAMPAIGN --network-strategy AVERAGE_CPC_PER_FILTER --filter-average-cpc 1000000 --counter-id 123 --dry-run
 
+# CPA-стратегия (одна цель): --goal-id обязателен, --average-cpa/--bid-ceiling — micro-рубли
+direct campaigns add --name "CPA-кампания" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy AVERAGE_CPA --network-strategy SERVING_OFF --goal-id 1234567 --average-cpa 500000000 --bid-ceiling 1000000000 --counter-ids 111,222 --dry-run
+
+# Мульти-целевой CPA через PriorityGoals (пары goal_id:value, WSDL PriorityGoalsItem)
+direct campaigns add --name "Мульти-целевой CPA" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy AVERAGE_CPA_MULTIPLE_GOALS --network-strategy SERVING_OFF --priority-goals 1234567:80,9876543:20 --bid-ceiling 1000000000 --dry-run
+
+# Notification (Sms/Email) и TimeTargeting принимают JSON с CamelCase ключами WSDL
+direct campaigns add --name "Уведомления+Расписание" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
+
 # Обновление и управление статусом
 direct campaigns update --id 12345 --name "Новое название" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
 direct campaigns suspend --id 12345
@@ -1028,11 +1109,22 @@ direct adgroups delete --id 67890
 direct ads get --campaign-ids 1,2,3
 direct ads get --adgroup-ids 45678 --format table
 direct ads add --adgroup-id 12345 --type TEXT_AD --title "Заголовок" --text "Текст объявления" --href "https://example.com" --dry-run
-direct ads add --adgroup-id 12345 --type TEXT_IMAGE_AD --image-hash abcdefghijklmnopqrst --href "https://example.com" --title "Баннер" --text "Имиджевое объявление" --dry-run
-direct ads update --id 99999 --status PAUSED --title "Новый заголовок" --text "Новый текст" --href "https://example.com" --image-hash abcdefghijklmnopqrst
+direct ads add --adgroup-id 12345 --type TEXT_AD --title "Заголовок" --text "Текст" --href "https://example.com" --title2 "Второй заголовок" --display-url-path "deals" --mobile YES --vcard-id 111 --sitelink-set-id 222 --turbo-page-id 333 --ad-extensions "444,555" --dry-run
+direct ads add --adgroup-id 12345 --type TEXT_IMAGE_AD --image-hash abcdefghijklmnopqrst --href "https://example.com" --turbo-page-id 555 --dry-run
+direct ads update --id 99999 --type TEXT_AD --title "Новый заголовок" --text "Новый текст" --href "https://example.com"
+direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --title2 "Новый второй заголовок" --vcard-id 222
 direct ads delete --id 99999
 ```
 
+Доступные типизированные флаги TEXT_AD для `ads add` / `ads update`:
+`--title`, `--text`, `--href`, `--image-hash`, `--title2`, `--display-url-path`,
+`--vcard-id`, `--sitelink-set-id`, `--turbo-page-id`. `--mobile`
+(default `NO`) и `--ad-extensions` доступны только в `ads add` — WSDL
+`TextAdUpdate` не содержит `Mobile`, а обновление расширений идёт через поле
+`CalloutSetting`, которое пока не покрыто CLI. Для TEXT_IMAGE_AD дополнительно
+доступен `--turbo-page-id`.
+
 #### Ключевые слова
 
 ```bash
@@ -1042,6 +1134,33 @@ direct keywords update --id 88888 --keyword "updated keyword text"
 direct keywords delete --id 88888
 ```
 
+**Пакетная загрузка ключевых слов** (CLI автоматически режет на куски по API-лимиту 10/запрос):
+
+```bash
+# Из JSONL-файла (по одному объекту ключевого слова на строку)
+direct keywords add --adgroup-id 12345 --from-file keywords.jsonl
+
+# Inline JSON-массив
+direct keywords add --keywords-json '[{"Keyword":"купить ноутбук","Bid":10000000},{"Keyword":"купить ПК"}]'
+```
+
+Пример `keywords.jsonl`:
+
+```jsonl
+{"Keyword":"купить ноутбук","Bid":10000000,"UserParam1":"src=ad1"}
+{"Keyword":"купить ПК","ContextBid":5000000}
+{"Keyword":"buy laptop","AdGroupId":99999}
+```
+
+- Ключи строки — WSDL CamelCase: `Keyword`, `AdGroupId`, `Bid`, `ContextBid`, `UserParam1`, `UserParam2`.
+- `--adgroup-id` задаёт значение по умолчанию; в строке можно переопределить через `AdGroupId`.
+- В каждой строке должны разрешаться `Keyword` и `AdGroupId`; неизвестные поля отклоняются с указанием номера строки.
+- API-лимит: 10 элементов на запрос `keywords.add` — см. [документацию Yandex Direct](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). CLI отправит нужное число чанков и склеит `AddResults`.
+- API-лимит: 200 ключевых слов на одну группу объявлений. CLI печатает предупреждение, если в каком-то `AdGroupId` во входе их больше; API отклонит излишек item-level ошибками.
+- Item-level ошибки от API не прерывают batch; объединённый вывод содержит и успешные Id, и ошибки.
+- При сетевой ошибке в середине batch уже созданные Id выводятся в stderr (`Partial success before failure`), чтобы при retry не возникли дубли.
+- `--dry-run` показывает payload первого чанка плюс `{chunks, totalItems, chunkSize}`.
+
 #### Отчёты
 
 ```bash
@@ -1098,8 +1217,8 @@ direct dynamicads set-bids --id 789 --bid 12500000 --context-bid 9000000 --prior
 
 # Общие стратегии ставок
 direct strategies get --limit 5
-direct strategies add --name "Общая стратегия" --type WbMaximumClicks --spend-limit 1000000000 --average-cpc 30000000 --dry-run
-direct strategies update --id 42 --type WbMaximumClicks --average-cpc 35000000 --dry-run
+direct strategies add --name "Общая стратегия" --type WbMaximumClicks --weekly-spend-limit 1000000000 --bid-ceiling 30000000 --dry-run
+direct strategies update --id 42 --type WbMaximumClicks --weekly-spend-limit 35000000 --dry-run
 direct strategies archive --id 42 --dry-run
 
 # Динамические таргеты по фиду
@@ -1113,7 +1232,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
@@ -1177,6 +1296,17 @@ direct campaigns get --fetch-all   # все страницы
 direct campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
 ```
 
+### Ошибки API
+
+Яндекс Директ может вернуть успешный HTTP-ответ, внутри которого есть
+item-level `Errors` для конкретного объекта. Direct CLI считает такой ответ
+ошибкой операции: команда завершается с ненулевым кодом и печатает код ошибки,
+сообщение и детали.
+
+Код `8800` с `Object not found` обычно означает, что объект недоступен в
+текущем `Client-Login` или аккаунте. Перед повтором проверьте выбранный
+`--login`, `YANDEX_DIRECT_LOGIN` или auth profile.
+
 ### Тестирование
 
 В `tests/` четыре уровня тестов:
@@ -1186,17 +1316,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`.
@@ -1248,6 +1383,12 @@ sandbox-токен не нужен.
 Для `account-management` нужна переменная
 `YANDEX_DIRECT_V4ACCOUNT_ACCOUNT_ID`; без неё runner покажет `NOT_COVERED`.
 
+`clients.update` включается только явно, потому что меняет client-level
+metadata аккаунта. Укажите `YANDEX_DIRECT_CLIENTS_UPDATE_LOGIN` с disposable
+sandbox `Client-Login`; runner передаст его через `--login` и изменит только
+`ClientInfo` на уникальный smoke marker. Без этой переменной runner покажет
+`NOT_COVERED` для `clients.update`.
+
 #### Перезапись write-кассет
 
 Уровень `integration_write` в pytest всё ещё воспроизводит сохранённый