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

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.8 → direct_cli-0.3.9}/CLAUDE.md

@@ -52,6 +52,15 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 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()`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.8
+Version: 0.3.9
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -384,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
@@ -410,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
@@ -424,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
@@ -480,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
@@ -558,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/`:
@@ -666,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
@@ -1011,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
@@ -1037,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
@@ -1051,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
@@ -1107,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
 
 # Динамические таргеты по фиду
@@ -1186,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/` четыре уровня тестов:
@@ -1262,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 всё ещё воспроизводит сохранённый

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

@@ -341,6 +341,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
@@ -367,11 +376,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
@@ -381,6 +400,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
@@ -437,8 +483,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
@@ -515,6 +561,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/`:
@@ -623,6 +680,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
@@ -968,6 +1031,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
@@ -994,11 +1066,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
@@ -1008,6 +1091,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
@@ -1064,8 +1174,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
 
 # Динамические таргеты по фиду
@@ -1143,6 +1253,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/` четыре уровня тестов:
@@ -1219,6 +1340,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 всё ещё воспроизводит сохранённый

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

@@ -55,7 +55,20 @@ from .commands.v4wordstat import v4wordstat
 load_dotenv()
 
 
-@click.group(name="direct")
+CLI_EPILOG = """\b
+Credential context:
+  --login / YANDEX_DIRECT_LOGIN selects the Yandex Direct Client-Login.
+  Use direct auth status to inspect the selected OAuth profile.
+
+\b
+API errors:
+  Item-level Yandex Direct Errors are reported as command failures.
+  Error 8800 usually means the object is not available under the current
+  Client-Login/account.
+"""
+
+
+@click.group(name="direct", epilog=CLI_EPILOG)
 @click.version_option(__version__, prog_name="direct")
 @click.option("--token", envvar="YANDEX_DIRECT_TOKEN", help="API access token")
 @click.option("--login", envvar="YANDEX_DIRECT_LOGIN", help="Client login")