direct-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{direct_cli-0.4.2 → direct_cli-0.4.3}/CHANGELOG.md

@@ -1,5 +1,220 @@
 # Changelog
 
+## 0.4.3
+
+**Features — batch `ads add` via `--from-file` / `--ads-json` (#562, #558 follow-up):**
+
+- `ads add` now accepts a batch of flag-form ad rows from a JSONL file
+  (`--from-file`) or an inline JSON array (`--ads-json`); each row is the same
+  flag set keyed by the kebab flag name without the leading dashes (e.g.
+  `{"type":"TEXT_AD","title":"...","text":"...","href":"...","adgroup-id":1}`).
+  `--adgroup-id` becomes the batch default and may be overridden per row. Single
+  typed-flag mode is unchanged.
+- The ~400-line flag→object logic of `ads add` was extracted into a reusable,
+  ctx-free `build_ad_object()` so the single-flag command and the batch
+  normalizer emit byte-identical ad objects (golden-tested across every
+  subtype).
+- New shared `direct_cli/commands/_batch.py` engine (JSONL/inline loading,
+  chunking, per-chunk send with partial-success reporting, dry-run preview,
+  `add`/`update`-aware result key). `keywords add` was migrated onto it with no
+  behavior change (its existing batch suite is the proof).
+- Chunk size `ADS_ADD_MAX_BATCH = 100` (conservative chunk, not the 1000-object
+  API ceiling — a partial failure rolls back at most 100 ads).
+
+**Features — batch `ads update` via `--from-file` / `--ads-json` (#563, #558 follow-up):**
+
+- `ads update` now accepts a batch of flag-form ad-update rows from a JSONL file
+  (`--from-file`) or an inline JSON array (`--ads-json`); each row is the same
+  flag set keyed by the kebab flag name without the leading dashes plus its own
+  `id` and `type` (e.g. `{"id":5,"type":"TEXT_AD","title":"New"}`). The
+  `--clear-image-hash` mechanic works per row as a JSON boolean. Single
+  typed-flag mode is unchanged.
+- The subtype-dispatch body of `ads update` (type validation, the
+  incompatible-flag / "does not convert between subtypes" guard, per-subtype
+  assembly, and the empty-subtype no-op guard) was extracted into a reusable,
+  ctx-free `build_ad_update_object()` so the single-flag command and the batch
+  normalizer emit byte-identical ad-update objects (golden-tested across every
+  subtype). Reuses the shared `_batch.py` engine with `method="update"` /
+  `result_key="UpdateResults"`.
+- `--id` and `--type` become per-row in batch mode (each row carries its own);
+  single-item mode still requires both. The per-row normalizer reproduces the
+  command's `--id`/`--type` required checks, the `--image-hash` /
+  `--clear-image-hash` mutex, and the same Click-type coercion as the single
+  path (a JSON float `id` is rejected, not truncated).
+
+**Features — batch `adgroups add` via `--from-file` / `--adgroups-json` (#564, #558 follow-up):**
+
+- `adgroups add` now accepts a batch of flag-form ad-group rows from a JSONL
+  file (`--from-file`) or an inline JSON array (`--adgroups-json`); each row is
+  the same flag set keyed by the kebab flag name without the leading dashes
+  (e.g. `{"name":"G","campaign-id":12,"region-ids":"225","type":"TEXT_AD_GROUP"}`).
+  `--campaign-id` becomes the batch default and may be overridden per row.
+  Single typed-flag mode is unchanged.
+- The flag→object logic of `adgroups add` (type validation, the
+  incompatible-flag guard, the negative-keyword compatibility check, region IDs,
+  and per-subtype assembly) was extracted into a reusable, ctx-free
+  `build_adgroup_object()` so the single-flag command and the batch normalizer
+  emit byte-identical ad-group objects (golden-tested across every subtype).
+  `--name` / `--campaign-id` / `--region-ids` become per-row in batch mode;
+  single-item mode still requires them (parity-gate `INTERNAL_VALIDATION`
+  entries). Per-row coercion runs every typed field through its single-flag
+  Click type (a JSON float `campaign-id` is rejected, not truncated).
+- The shared `_batch.send_batch` gained an optional `post` callable so
+  `adgroups` keeps its endpoint routing: a `UnifiedAdGroup` payload must use API
+  v501 (`_post_adgroups`). Because that routing keys off the whole body, a batch
+  may **not** mix `UNIFIED_AD_GROUP` with other ad-group types — the CLI refuses
+  the mix up front with a clear `UsageError` rather than send non-unified groups
+  to the v501 endpoint.
+
+**Features — batch `adgroups update` via `--from-file` / `--adgroups-json` (#565, #558 follow-up):**
+
+- `adgroups update` now accepts a batch of flag-form ad-group-update rows from a
+  JSONL file (`--from-file`) or an inline JSON array (`--adgroups-json`); each
+  row is the same flag set keyed by the kebab flag name without the leading
+  dashes plus its own `id` (e.g. `{"id":5,"name":"New"}`). The `--dynamic-feed`
+  routing works per row as a JSON boolean. Single typed-flag mode is unchanged.
+- The subtype-dispatch body of `adgroups update` (the mixed-subtype reject
+  guard, per-subtype assembly, the `--dynamic-feed` DynamicTextAdGroup ↔
+  DynamicTextFeedAdGroup routing, and the empty-payload no-op guard) was
+  extracted into a reusable, ctx-free `build_adgroup_update_object()` so the
+  single-flag command and the batch normalizer emit byte-identical objects
+  (golden-tested across every subtype). `--id` becomes per-row in batch mode;
+  single-item mode still requires it (parity-gate `INTERNAL_VALIDATION` entry).
+  Per-row coercion runs every typed field through its single-flag Click type (a
+  JSON float `id` is rejected, not truncated).
+- Reuses the shared `_batch.send_batch` with `method="update"` /
+  `result_key="UpdateResults"` and the `post=_post_adgroups` endpoint routing.
+  As with `adgroups add`, a batch may **not** mix `UNIFIED_AD_GROUP` with other
+  ad-group types (unified groups use API v501) — the CLI refuses the mix up
+  front with a clear `UsageError`.
+
+**Fixes — reject non-positive IDs before the request (#558):**
+
+- Mutating commands and lifecycle ops took their object-ID selector
+  (`--id` / `--adgroup-id` / `--campaign-id` / `--keyword-id` / `--client-id`)
+  as a bare `int`, which accepted `0` and negatives and forwarded them to the
+  API (opaque rejection). Every such selector now uses `click.IntRange(min=1)`
+  and rejects a non-positive id with a clear `UsageError` (exit 2) before any
+  request. Coverage is the full mutation surface, not a subset:
+  - every `delete` / `suspend` / `resume` / `archive` / `unarchive` /
+    `moderate` lifecycle command (via the shared `_lifecycle.py` factory);
+  - `ads add` / `ads update`, `adgroups add` / `adgroups update`,
+    `keywords add` / `keywords update`;
+  - `campaigns update`, `feeds update`, `strategies update`,
+    `retargeting update`, `negativekeywordsharedsets update`, `vcards add`;
+  - `smartadtargets add` / `update` / `set-bids`,
+    `audiencetargets add` / `set-bids`, `dynamicads add` / `set-bids`,
+    `dynamicfeedadtargets add` / `set-bids`;
+  - the bid setters `bids set` / `set-auto`, `keywordbids set` / `set-auto`
+    (the `campaign-id` / `adgroup-id` / `keyword-id` "exactly one of" trios),
+    `bidmodifiers add` / `set`;
+  - `agencyclients update --client-id`.
+
+  The ad-image lifecycle (`--hash`, a string) is unchanged. Secondary
+  reference-ID flags that point at *other* objects inside a write payload
+  (e.g. `--feed-id`, `--counter-id`, `--vcard-id`, `--region-id`,
+  `--retargeting-list-id`) are left as-is for now and tracked as follow-up.
+- Batch-size caps (the docs allow up to 1000 objects per add/update and 10000
+  ids per delete) are intentionally **not** added: the CLI builds a
+  single-item payload for every mutation, so there is no caller-controllable
+  array to overflow. Multi-item batch mode (`--from-file`) for ads/adgroups is
+  tracked as follow-up work.
+- De-staled the `KEYWORDS_ADD_MAX_BATCH` comment: it claimed the API caps a
+  `keywords.add` request at 10 (citing an outdated doc page that states no such
+  number). The real documented per-call limit is 1000; the value `10` is a
+  conservative chunk size for batch add, not the API ceiling — comment fixed,
+  value unchanged.
+
+**Fixes — explain Error 8300 on delete/moderate (#548):**
+
+- `raise_for_api_result_errors` now appends a hint when the API returns code
+  8300, mirroring the existing 8800 hint: the ad is likely not in `DRAFT`
+  status, and `Status=UNKNOWN` is an API fallback value (a status outside the
+  v5 enum), not a business status — such ads can only be archived/unarchived,
+  not deleted or sent to moderation. Covers `ads delete` / `ads moderate` and
+  any command routing through `format_output`. English-only, matching the 8800
+  hint (`output.py` does not import i18n).
+
+**Docs — audiencetargets get requires a filter (#554):**
+
+- Clarified that `audiencetargets get` cannot page the whole account: unlike
+  `retargeting get --fetch-all`, the live API hard-rejects an empty
+  `SelectionCriteria` (error 8000 with no criteria, 4001 with `{}`). The
+  required-filter guard now explains this and recommends the `campaigns get` →
+  batched `campaign_ids` sweep instead. No API behavior change; message only.
+
+**Fixes — preflight SelectionCriteria array limits on get (#555, P0):**
+
+- `keywordbids get` now rejects `--campaign-ids` >10, `--adgroup-ids` >1000,
+  `--keyword-ids` >10000; `dynamicads get` / `smartadtargets get` reject
+  `--campaign-ids` >2 — before the request, with a clear `UsageError` (exit 2)
+  naming the array and ceiling, instead of the opaque API `error_code=4001`.
+  These are runtime ceilings (the WSDL declares the arrays `unbounded`), pinned
+  next to each command with a doc/live-4001 citation, the same discipline as
+  `KEYWORDS_ADD_MAX_BATCH`. Verified live 2026-06-16. Other `get` arrays
+  (`AdGroupIds`/`Ids` on dynamic/smart, etc.) are intentionally **not** capped
+  because the live API accepts them.
+
+**Internal — dedup v4 Live output-option stack (#550):**
+
+- Replaced the byte-identical `--format`/`--output`/`--dry-run` trio across the
+  standard v4 Live and `balance` commands with a shared `v4_output_options`
+  decorator (the v4 analogue of `get_options`, epic #491). The CLI surface is
+  unchanged — same option order, names, `click.Choice(["json","table","csv",
+  "tsv"])` format, defaults, and help. `v4account enable-shared-account` /
+  `account-management` (reversed order, custom `--dry-run` help) and the
+  dry-run-only `v4finance transfer-money` / `pay-campaigns` /
+  `pay-campaigns-by-card` (no `--format`/`--output`) keep their divergent
+  stacks and are intentionally excluded.
+
+**Fixes — `ads update` can now clear AdImageHash (#552):**
+
+- Added `--clear-image-hash` to `ads update`. The flag sends
+  `AdImageHash: null` so an image can be removed from an existing ad — e.g.
+  unblocking a `TEXT_AD` whose image was restricted in moderation — without
+  recreating the ad. Supported for the three subtypes whose WSDL `AdImageHash`
+  is nillable: `TEXT_AD`, `DYNAMIC_TEXT_AD`, `MOBILE_APP_AD`. It is **rejected**
+  for `TEXT_IMAGE_AD` and `MOBILE_APP_IMAGE_AD`, which share the non-nillable
+  `ImageAdUpdateBase.AdImageHash` — the live API returns error 8000
+  (`AdImageHash cannot have the null value`) for those, verified directly.
+  `--image-hash` and `--clear-image-hash` are mutually exclusive.
+  Previously there was no way to reset the image: `--image-hash ""` was dropped
+  by a truthy check, and `--image-hash null` sent the literal string `"null"`.
+
+**Fixes — docs-URL drift regression (re-fixes #463):**
+
+- Restored the four WSDL `docs` URLs for `dynamicads`,
+  `dynamicfeedadtargets`, `smartadtargets` and `vcards` that the
+  `tapi-yandex-direct` 2026.5.29 vendor update silently reverted back to the
+  removed `…/dev/direct/doc/ru/<service>` HTML pages (which 404 since Yandex
+  dropped those pages in September 2025). The fix from #464 was overwritten by
+  the `rm -rf` + `cp -R` vendor sync; preflight
+  (`scripts/check_all_docs_urls.py`) caught it. URLs now point back at the live
+  `https://api.direct.yandex.com/v5/<service>?wsdl` endpoints — the only
+  authoritative source still served.
+- Fixed the same URLs at the source in the `axisrow/tapi-yandex-direct` fork so
+  the next vendor update no longer re-introduces the dead pages.
+- Added an offline regression guard
+  (`tests/test_audit_wire_shape.py::test_removed_doc_services_pin_wsdl_url`):
+  the four doc-removed services must keep WSDL `docs` URLs, failing in CI before
+  the network preflight ever runs.
+
+**Bug Fixes — reject empty-string CSV-ID flags in `adgroups` (#570):**
+
+- `adgroups add` and `adgroups update` now reject an explicitly-provided
+  empty/whitespace value for `--region-ids`, `--negative-keyword-shared-set-ids`
+  and `--feed-category-ids` (e.g. `--region-ids ""`, `--region-ids " "`,
+  `--region-ids ","`, or a batch row `{"region-ids":""}`) with a clear
+  `UsageError` instead of silently dropping the field. Previously `parse_ids("")`
+  returned `None` and the `if region_ids:` guards treated a provided-but-empty
+  value identically to an omitted option; for `RegionIds` (WSDL `minOccurs=1` on
+  add) that stripped a required field and sent an invalid body to the live API.
+- The fix is centralized in a new `_require_nonempty_ids_option` helper that
+  distinguishes `None` (option omitted) from an all-blank value, so single mode
+  and `--from-file` / `--adgroups-json` batch mode behave identically for both
+  add and update. A genuinely malformed value with real tokens
+  (e.g. `225,,226`) still reports the precise `Invalid ID` error, unchanged.
+
 ## 0.4.2
 
 **BREAKING CHANGES - get requires SelectionCriteria (#498):**

{direct_cli-0.4.2 → direct_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.4.2
+Version: 0.4.3
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -543,6 +543,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --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 --clear-image-hash  # remove the image (AdImageHash: null; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only)
 direct ads update --id 99999 --type TEXT_AD --title2 "New second headline" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -561,7 +562,10 @@ 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`,
+`--href`, `--image-hash`, `--clear-image-hash` (update only — sets
+`AdImageHash: null`; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only, since
+TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD have a non-nillable `AdImageHash`),
+`--title2`, `--display-url-path`, `--vcard-id`,
 `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business`, and `--erir-ad-description`. For `ads add`,
@@ -708,6 +712,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get always needs a filter — the API rejects an empty
+# SelectionCriteria, so there is no whole-account paging. To sweep the account,
+# run `campaigns get` first, then page audiencetargets get in batches of campaign ids.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run
@@ -1371,6 +1378,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --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 --clear-image-hash  # удалить изображение (AdImageHash: null; только TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD)
 direct ads update --id 99999 --type TEXT_AD --title2 "Новый второй заголовок" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -1389,7 +1397,10 @@ direct ads delete --id 99999
 ```
 
 Доступные типизированные флаги TEXT_AD для `ads add` / `ads update`:
-`--title`, `--text`, `--href`, `--image-hash`, `--title2`, `--display-url-path`,
+`--title`, `--text`, `--href`, `--image-hash`, `--clear-image-hash`
+(только update — устанавливает `AdImageHash: null`; только TEXT_AD /
+DYNAMIC_TEXT_AD / MOBILE_APP_AD, так как у TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD
+поле `AdImageHash` не nillable), `--title2`, `--display-url-path`,
 `--vcard-id`, `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business` и `--erir-ad-description`. Для `ads add`
@@ -1538,6 +1549,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get всегда требует фильтр — API отклоняет пустой
+# SelectionCriteria, поэтому обхода всего аккаунта нет. Чтобы собрать аккаунт,
+# сначала выполните `campaigns get`, затем запрашивайте audiencetargets get батчами campaign id.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run

{direct_cli-0.4.2 → direct_cli-0.4.3}/README.md

@@ -500,6 +500,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --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 --clear-image-hash  # remove the image (AdImageHash: null; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only)
 direct ads update --id 99999 --type TEXT_AD --title2 "New second headline" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -518,7 +519,10 @@ 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`,
+`--href`, `--image-hash`, `--clear-image-hash` (update only — sets
+`AdImageHash: null`; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only, since
+TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD have a non-nillable `AdImageHash`),
+`--title2`, `--display-url-path`, `--vcard-id`,
 `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business`, and `--erir-ad-description`. For `ads add`,
@@ -665,6 +669,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get always needs a filter — the API rejects an empty
+# SelectionCriteria, so there is no whole-account paging. To sweep the account,
+# run `campaigns get` first, then page audiencetargets get in batches of campaign ids.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run
@@ -1328,6 +1335,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --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 --clear-image-hash  # удалить изображение (AdImageHash: null; только TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD)
 direct ads update --id 99999 --type TEXT_AD --title2 "Новый второй заголовок" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -1346,7 +1354,10 @@ direct ads delete --id 99999
 ```
 
 Доступные типизированные флаги TEXT_AD для `ads add` / `ads update`:
-`--title`, `--text`, `--href`, `--image-hash`, `--title2`, `--display-url-path`,
+`--title`, `--text`, `--href`, `--image-hash`, `--clear-image-hash`
+(только update — устанавливает `AdImageHash: null`; только TEXT_AD /
+DYNAMIC_TEXT_AD / MOBILE_APP_AD, так как у TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD
+поле `AdImageHash` не nillable), `--title2`, `--display-url-path`,
 `--vcard-id`, `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business` и `--erir-ad-description`. Для `ads add`
@@ -1495,6 +1506,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get всегда требует фильтр — API отклоняет пустой
+# SelectionCriteria, поэтому обхода всего аккаунта нет. Чтобы собрать аккаунт,
+# сначала выполните `campaigns get`, затем запрашивайте audiencetargets get батчами campaign id.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run

{direct_cli-0.4.2 → direct_cli-0.4.3}/direct_cli/_vendor/tapi_yandex_direct/resource_mapping.py

@@ -76,14 +76,20 @@ RESOURCE_MAPPING_V5 = {
         "docs": "https://yandex.ru/dev/direct/doc/ru/dictionaries/dictionaries",
         "methods": ["get"],
     },
+    # Yandex removed the human-readable doc pages for DynamicTextAdTargets,
+    # DynamicFeedAdTargets, SmartAdTargets and VCards in September 2025 (the
+    # /ru/ and /en/ pages now 404, and the services are gone from the docs
+    # navigation). The services themselves remain live, so `docs` points at the
+    # WSDL endpoint — the only authoritative source still served for them. See
+    # issue #463.
     "dynamicads": {
         "resource": "json/v5/dynamictextadtargets",
-        "docs": "https://yandex.ru/dev/direct/doc/ru/dynamictextadtargets",
+        "docs": "https://api.direct.yandex.com/v5/dynamictextadtargets?wsdl",
         "methods": ["get", "add", "delete", "suspend", "resume", "setBids"],
     },
     "dynamicfeedadtargets": {
         "resource": "json/v5/dynamicfeedadtargets",
-        "docs": "https://yandex.ru/dev/direct/doc/ru/dynamicfeedadtargets",
+        "docs": "https://api.direct.yandex.com/v5/dynamicfeedadtargets?wsdl",
         "methods": ["get", "add", "delete", "suspend", "resume", "setBids"],
     },
     "keywordbids": {
@@ -118,7 +124,8 @@ RESOURCE_MAPPING_V5 = {
     },
     "vcards": {
         "resource": "json/v5/vcards",
-        "docs": "https://yandex.ru/dev/direct/doc/ru/vcards",
+        # Doc page removed Sep 2025 (see comment above); WSDL still live.
+        "docs": "https://api.direct.yandex.com/v5/vcards?wsdl",
         "methods": ["get", "add", "delete"],
     },
     "turbopages": {
@@ -154,7 +161,8 @@ RESOURCE_MAPPING_V5 = {
     },
     "smartadtargets": {
         "resource": "json/v5/smartadtargets",
-        "docs": "https://yandex.ru/dev/direct/doc/ru/smartadtargets",
+        # Doc page removed Sep 2025 (see comment above); WSDL still live.
+        "docs": "https://api.direct.yandex.com/v5/smartadtargets?wsdl",
         "methods": ["get", "add", "update", "delete", "suspend", "resume", "setBids"],
     },
     "strategies": {

direct_cli-0.4.3/direct_cli/commands/_batch.py

@@ -0,0 +1,181 @@
+"""Shared JSONL/inline batch engine for multi-item ``add``/``update`` commands.
+
+Extracted from the ``keywords add`` batch machinery (issue #562) so ``ads`` and
+``adgroups`` reuse one loader/chunker/sender instead of duplicating it. Only the
+resource-specific pieces (the row normalizer and any overflow warning) stay in
+the command module and are passed in.
+
+Message strings are NOT hardcoded with a resource name: ``load_inline_rows`` and
+``send_batch`` take the catalog keys / nouns from the caller, so each command
+keeps its own (already-translated) wording byte-identical.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Iterator, List, Optional
+
+import click
+
+from ..api import client_from_ctx
+from ..i18n import t
+from ..output import (
+    format_json,
+    format_output,
+    print_error,
+    raise_for_api_result_errors,
+)
+
+
+def load_jsonl_rows(path: str) -> List[Any]:
+    """Read a JSONL file into a list of decoded rows (one JSON value per line).
+
+    Blank lines are skipped. A read error or a malformed line raises a
+    ``click.UsageError`` with the same catalog keys ``keywords`` used.
+    """
+    rows: List[Any] = []
+    file_path = Path(path)
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise click.UsageError(
+            t("Cannot read --from-file {path!r}: {exc}").format(path=path, exc=exc)
+        )
+
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(
+                t("Row {line_number}: invalid JSON: {arg0}").format(
+                    line_number=line_number, arg0=exc.msg
+                )
+            )
+    return rows
+
+
+def load_inline_rows(
+    json_str: str,
+    *,
+    invalid_json_key: str,
+    not_array_key: str,
+) -> List[Any]:
+    """Parse an inline JSON array of rows.
+
+    ``invalid_json_key`` / ``not_array_key`` are the EN catalog keys for the two
+    error cases, so each command keeps its own ``--<resource>-json`` wording
+    (and its existing RU translation) unchanged.
+    """
+    try:
+        decoded = json.loads(json_str)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(t(invalid_json_key).format(arg0=exc.msg))
+    if not isinstance(decoded, list):
+        raise click.UsageError(t(not_array_key))
+    return decoded
+
+
+def chunked(items: List[Any], size: int) -> Iterator[List[Any]]:
+    for start in range(0, len(items), size):
+        yield items[start : start + size]
+
+
+def normalize_results(raw: Any, result_key: str) -> List[Any]:
+    """Unwrap the per-item result list from an ``add``/``update`` response.
+
+    ``result_key`` is ``"AddResults"`` for ``add`` and ``"UpdateResults"`` for
+    ``update`` — Yandex names the list after the method.
+    """
+    if isinstance(raw, dict):
+        results = raw.get(result_key)
+        if isinstance(results, list):
+            return results
+        return [raw]
+    if isinstance(raw, list):
+        return raw
+    return [raw]
+
+
+def send_batch(
+    ctx,
+    *,
+    resource: str,
+    method: str,
+    payload_key: str,
+    items: List[Any],
+    max_batch: int,
+    create_client: Callable,
+    dry_run: bool,
+    noun: str,
+    result_key: str = "AddResults",
+    on_warn: Optional[Callable[[List[Any]], None]] = None,
+    post: Optional[Callable[[Any, dict], Any]] = None,
+) -> None:
+    """Chunk ``items`` and send each chunk through ``client.<resource>()``.
+
+    ``--dry-run`` prints the chunk preview and returns. Otherwise each chunk is
+    posted in a loop; on failure any already-created items are reported (so a
+    retry does not silently duplicate them). ``noun`` is the plural object name
+    used in that partial-success message (e.g. ``"keywords"``, ``"ads"``).
+    ``result_key`` is the response list name (``"AddResults"`` for ``add``,
+    ``"UpdateResults"`` for ``update``).
+
+    ``post`` overrides how a chunk body is sent: a ``(client, body) -> response``
+    callable. It defaults to ``client.<resource>().post(data=body)``; ``adgroups``
+    passes its endpoint-routing ``_post_adgroups`` (UnifiedAdGroup payloads must
+    use API v501).
+    """
+    chunks = list(chunked(items, max_batch))
+
+    if on_warn is not None:
+        on_warn(items)
+
+    if dry_run:
+        preview = {
+            "chunks": len(chunks),
+            "totalItems": len(items),
+            "chunkSize": max_batch,
+            "firstChunk": {"method": method, "params": {payload_key: chunks[0]}},
+        }
+        print(format_json(preview, indent=2))
+        return
+
+    all_results: List[Any] = []
+    try:
+        client = client_from_ctx(ctx, create_client)
+
+        for index, chunk in enumerate(chunks, start=1):
+            click.echo(
+                f"Sending chunk {index}/{len(chunks)}: {len(chunk)} items",
+                err=True,
+            )
+            body = {"method": method, "params": {payload_key: chunk}}
+            if post is not None:
+                response = post(client, body)
+            else:
+                response = getattr(client, resource)().post(data=body)
+            chunk_results = normalize_results(response().extract(), result_key)
+            # Only items without per-item Errors are "already applied" — the
+            # partial-success diagnostic must not lie about failed items.
+            all_results.extend(
+                item
+                for item in chunk_results
+                if not (isinstance(item, dict) and item.get("Errors"))
+            )
+            raise_for_api_result_errors(chunk_results)
+
+        format_output({result_key: all_results}, "json", None)
+    except click.UsageError:
+        raise
+    except Exception as e:
+        if all_results:
+            click.echo(
+                f"Partial success before failure — these {noun} were already "
+                "applied in Yandex Direct (retrying may duplicate them):",
+                err=True,
+            )
+            click.echo(format_json({result_key: all_results}, indent=2), err=True)
+        print_error(str(e))
+        raise click.Abort()

{direct_cli-0.4.2 → direct_cli-0.4.3}/direct_cli/commands/_lifecycle.py

@@ -68,8 +68,15 @@ def make_lifecycle_command(
         ``@group.command`` registration sticks).
     """
 
+    # A lifecycle id is always a positive object id; type=int used to accept 0
+    # and negatives and forward them to the API (opaque rejection). For the
+    # integer path, validate min=1 before the request (issue #558). The
+    # ad-image path keeps id_type=str (a hash is not an integer) and is
+    # untouched.
+    option_type = click.IntRange(min=1) if id_type is int else id_type
+
     @group.command(name=method, help=help_text)
-    @click.option(id_option, id_param, required=True, type=id_type, help=id_help)
+    @click.option(id_option, id_param, required=True, type=option_type, help=id_help)
     @click.option("--dry-run", is_flag=True, help="Show request without sending")
     @click.pass_context
     @handle_api_errors