direct-cli 0.2.11__tar.gz → 0.3.1__tar.gz

{direct_cli-0.2.11 → direct_cli-0.3.1}/CLAUDE.md

@@ -39,11 +39,17 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **`--dry-run`:** `add`/`update` commands print request JSON without calling the API. Use as test seam.
 
+**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`.
+
 **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()`.
 
-**Default fields:** `COMMON_FIELDS` in `utils.py` maps resource names to `FieldNames`. Not all fields are valid for all resources (e.g., `adimages` uses `AdImageHash`, not `Id`).
+**Default fields:** `COMMON_FIELDS` in `utils.py` maps resource names to default `*FieldNames`. Most entries are `list[str]`; multi-`*FieldNames` resources use `dict[str, list[str]]` keyed by WSDL request param (for example `FieldNames`, `TextAdFieldNames`, `SearchFieldNames`). Not all fields are valid for all resources (e.g., `adimages` uses `AdImageHash`, not `Id`).
+
+**WSDL imports:** Imported schemas used by request validation are cached in `tests/wsdl_cache/imports/` and registered in `IMPORTED_XSD_REGISTRY`. Keep imported nested types resolved; empty `item_fields` for registered imports is coverage drift.
+
+**Smoke probes:** Live ID discovery for safe-smoke and integration tests lives in `direct_cli/_smoke_probes.py`. Functions like `advideo_probe_id()` query the live API to find a real resource ID (env override `YANDEX_DIRECT_TEST_ADVIDEO_ID`, fallback through `creatives.get`) and return `None` on any failure — smoke scripts treat `None` as a benign skip, not a fatal error. CLI entry: `python3 -m direct_cli._smoke_probes advideo`.
 
 ## Tests
 
@@ -66,3 +72,7 @@ subcommand belongs to exactly one category:
 Never auto-test production mutations: agency client changes, live bid changes,
 moderation, lifecycle operations, `clients update`, or any `delete` without
 `--sandbox`.
+
+Client update payloads (`clients update` and `agencyclients update`) must use
+the shared typed helpers in `direct_cli/utils.py`; do not expose raw JSON for
+general client update fields or nested client update payloads.

{direct_cli-0.2.11 → direct_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.2.11
+Version: 0.3.1
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -118,6 +118,18 @@ 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`.
 
+### Quick Start: Check Balance
+
+Yandex removed the legacy v4 `GetBalance` method. Direct CLI uses the v4 Live
+`AccountManagement` method with `Action=Get` for `direct balance`, returning
+money fields such as `Amount`, `AmountAvailableForTransfer`, and `Currency`.
+
+```bash
+direct balance
+direct balance --logins client-login,other-client --format table
+direct balance --logins client-login --dry-run
+```
+
 ### Global Options
 
 | Option | Description |
@@ -127,6 +139,14 @@ Invoking the deprecated `direct-cli` entrypoint exits with
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
 
+### V4 Live Goals
+
+```bash
+direct v4goals get-stat-goals --campaign-ids 123,456
+direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
+direct v4goals get-stat-goals --campaign-ids 123 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -342,7 +362,7 @@ direct dictionaries get-geo-regions --name Moscow --region-ids 225,187 --exact-n
 direct clients get --fields ClientId,Login,Currency
 
 # Changes
-direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
+direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00 --fields CampaignIds,AdGroupIds,AdIds,CampaignsStat
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
 
@@ -352,15 +372,18 @@ direct retargeting add --name "List A" --type AUDIENCE --rule "ALL:12345:30|6789
 direct retargeting update --id 55 --name "Renamed" --rule "ANY:12345:30" --dry-run
 
 # Bids and modifiers
+direct bids get --campaign-ids 123 --fields CampaignId,AdGroupId,KeywordId,Bid
 direct bids set --keyword-id 123 --bid 15000000
 direct bids set-auto --keyword-id 123 --max-bid 20000000 --position PREMIUMBLOCK --scope SEARCH --dry-run
 direct keywordbids set --keyword-id 321 --search-bid 8000000 --network-bid 3000000
 direct keywordbids set-auto --keyword-id 321 --target-traffic-volume 100 --increase-percent 10 --bid-ceiling 12500000 --dry-run
+direct bidmodifiers get --campaign-ids 123 --fields Id,CampaignId,AdGroupId,Level,Type
 direct bidmodifiers add --campaign-id 123 --type DEMOGRAPHICS_ADJUSTMENT --value 150 --gender GENDER_MALE --age AGE_25_34 --dry-run
 direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+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 dynamicads add --adgroup-id 33 --name "Webpage A" --condition "URL:CONTAINS_ANY:test|shop" --condition "PAGE_CONTENT:CONTAINS:baz" --bid 3000000 --context-bid 2000000 --priority HIGH --dry-run
@@ -388,13 +411,15 @@ direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-
 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 update --id 18 --name "Feed A v2" --url "https://example.com/feed-v2.xml" --dry-run
-direct clients update --client-id 999 --phone +70000000000 --fax +70000000001 --email user@example.com --city Moscow --dry-run
-direct agencyclients add --login client-login --first-name Alice --last-name Smith --currency RUB --notification-email ops@example.com --notification-lang RU --send-account-news --no-send-warnings --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
 direct agencyclients add-passport-organization --name "Org" --currency RUB --notification-email ops@example.com --notification-lang EN --no-send-account-news --send-warnings --dry-run
 direct agencyclients add-passport-organization-member --passport-organization-login org-login --role CHIEF --invite-email user@example.com --dry-run
-direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
+direct agencyclients update --client-id 42 --phone +70000000000 --notification-email user@example.com --grant EDIT_CAMPAIGNS=YES --grant IMPORT_XLS=NO --dry-run
 ```
 
+`direct agencyclients add` is runtime-deprecated by Yandex Direct and is blocked by the CLI. Use `direct agencyclients add-passport-organization` instead.
+
 ### Known Unsupported API Operation
 
 `dynamicads update` is unsupported by API. The Yandex Direct
@@ -959,7 +984,7 @@ direct dictionaries get-geo-regions --name Москва --region-ids 225,187 --e
 direct clients get --fields ClientId,Login,Currency
 
 # Изменения
-direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
+direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00 --fields CampaignIds,AdGroupIds,AdIds,CampaignsStat
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
 
@@ -969,15 +994,18 @@ direct retargeting add --name "Список A" --type AUDIENCE --rule "ALL:12345
 direct retargeting update --id 55 --name "Переименованный список" --rule "ANY:12345:30" --dry-run
 
 # Ставки и модификаторы
+direct bids get --campaign-ids 123 --fields CampaignId,AdGroupId,KeywordId,Bid
 direct bids set --keyword-id 123 --bid 15000000
 direct bids set-auto --keyword-id 123 --max-bid 20000000 --position PREMIUMBLOCK --scope SEARCH --dry-run
 direct keywordbids set --keyword-id 321 --search-bid 8000000 --network-bid 3000000
 direct keywordbids set-auto --keyword-id 321 --target-traffic-volume 100 --increase-percent 10 --bid-ceiling 12500000 --dry-run
+direct bidmodifiers get --campaign-ids 123 --fields Id,CampaignId,AdGroupId,Level,Type
 direct bidmodifiers add --campaign-id 123 --type DEMOGRAPHICS_ADJUSTMENT --value 150 --gender GENDER_MALE --age AGE_25_34 --dry-run
 direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+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 dynamicads add --adgroup-id 33 --name "Webpage A" --condition "URL:CONTAINS_ANY:test|shop" --condition "PAGE_CONTENT:CONTAINS:baz" --bid 3000000 --context-bid 2000000 --priority HIGH --dry-run
@@ -1005,13 +1033,15 @@ direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-
 direct creatives add --video-id video-id --dry-run
 direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --dry-run
 direct feeds update --id 18 --name "Фид A v2" --url "https://example.com/feed-v2.xml" --dry-run
-direct clients update --client-id 999 --phone +70000000000 --fax +70000000001 --email user@example.com --city Moscow --dry-run
-direct agencyclients add --login client-login --first-name Alice --last-name Smith --currency RUB --notification-email ops@example.com --notification-lang RU --send-account-news --no-send-warnings --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
 direct agencyclients add-passport-organization --name "Org" --currency RUB --notification-email ops@example.com --notification-lang EN --no-send-account-news --send-warnings --dry-run
 direct agencyclients add-passport-organization-member --passport-organization-login org-login --role CHIEF --invite-email user@example.com --dry-run
-direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
+direct agencyclients update --client-id 42 --phone +70000000000 --notification-email user@example.com --grant EDIT_CAMPAIGNS=YES --grant IMPORT_XLS=NO --dry-run
 ```
 
+`direct agencyclients add` runtime-deprecated в Yandex Direct и блокируется CLI. Используйте `direct agencyclients add-passport-organization`.
+
 ### Известная неподдерживаемая API-операция
 
 `dynamicads update` unsupported by API. Сервис Яндекс Директа

{direct_cli-0.2.11 → direct_cli-0.3.1}/README.md

@@ -79,6 +79,18 @@ 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`.
 
+### Quick Start: Check Balance
+
+Yandex removed the legacy v4 `GetBalance` method. Direct CLI uses the v4 Live
+`AccountManagement` method with `Action=Get` for `direct balance`, returning
+money fields such as `Amount`, `AmountAvailableForTransfer`, and `Currency`.
+
+```bash
+direct balance
+direct balance --logins client-login,other-client --format table
+direct balance --logins client-login --dry-run
+```
+
 ### Global Options
 
 | Option | Description |
@@ -88,6 +100,14 @@ Invoking the deprecated `direct-cli` entrypoint exits with
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
 
+### V4 Live Goals
+
+```bash
+direct v4goals get-stat-goals --campaign-ids 123,456
+direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
+direct v4goals get-stat-goals --campaign-ids 123 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -303,7 +323,7 @@ direct dictionaries get-geo-regions --name Moscow --region-ids 225,187 --exact-n
 direct clients get --fields ClientId,Login,Currency
 
 # Changes
-direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
+direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00 --fields CampaignIds,AdGroupIds,AdIds,CampaignsStat
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
 
@@ -313,15 +333,18 @@ direct retargeting add --name "List A" --type AUDIENCE --rule "ALL:12345:30|6789
 direct retargeting update --id 55 --name "Renamed" --rule "ANY:12345:30" --dry-run
 
 # Bids and modifiers
+direct bids get --campaign-ids 123 --fields CampaignId,AdGroupId,KeywordId,Bid
 direct bids set --keyword-id 123 --bid 15000000
 direct bids set-auto --keyword-id 123 --max-bid 20000000 --position PREMIUMBLOCK --scope SEARCH --dry-run
 direct keywordbids set --keyword-id 321 --search-bid 8000000 --network-bid 3000000
 direct keywordbids set-auto --keyword-id 321 --target-traffic-volume 100 --increase-percent 10 --bid-ceiling 12500000 --dry-run
+direct bidmodifiers get --campaign-ids 123 --fields Id,CampaignId,AdGroupId,Level,Type
 direct bidmodifiers add --campaign-id 123 --type DEMOGRAPHICS_ADJUSTMENT --value 150 --gender GENDER_MALE --age AGE_25_34 --dry-run
 direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+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 dynamicads add --adgroup-id 33 --name "Webpage A" --condition "URL:CONTAINS_ANY:test|shop" --condition "PAGE_CONTENT:CONTAINS:baz" --bid 3000000 --context-bid 2000000 --priority HIGH --dry-run
@@ -349,13 +372,15 @@ direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-
 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 update --id 18 --name "Feed A v2" --url "https://example.com/feed-v2.xml" --dry-run
-direct clients update --client-id 999 --phone +70000000000 --fax +70000000001 --email user@example.com --city Moscow --dry-run
-direct agencyclients add --login client-login --first-name Alice --last-name Smith --currency RUB --notification-email ops@example.com --notification-lang RU --send-account-news --no-send-warnings --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
 direct agencyclients add-passport-organization --name "Org" --currency RUB --notification-email ops@example.com --notification-lang EN --no-send-account-news --send-warnings --dry-run
 direct agencyclients add-passport-organization-member --passport-organization-login org-login --role CHIEF --invite-email user@example.com --dry-run
-direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
+direct agencyclients update --client-id 42 --phone +70000000000 --notification-email user@example.com --grant EDIT_CAMPAIGNS=YES --grant IMPORT_XLS=NO --dry-run
 ```
 
+`direct agencyclients add` is runtime-deprecated by Yandex Direct and is blocked by the CLI. Use `direct agencyclients add-passport-organization` instead.
+
 ### Known Unsupported API Operation
 
 `dynamicads update` is unsupported by API. The Yandex Direct
@@ -920,7 +945,7 @@ direct dictionaries get-geo-regions --name Москва --region-ids 225,187 --e
 direct clients get --fields ClientId,Login,Currency
 
 # Изменения
-direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00
+direct changes check --campaign-ids 1,2,3 --timestamp 2026-04-14T00:00:00 --fields CampaignIds,AdGroupIds,AdIds,CampaignsStat
 direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-dictionaries
 
@@ -930,15 +955,18 @@ direct retargeting add --name "Список A" --type AUDIENCE --rule "ALL:12345
 direct retargeting update --id 55 --name "Переименованный список" --rule "ANY:12345:30" --dry-run
 
 # Ставки и модификаторы
+direct bids get --campaign-ids 123 --fields CampaignId,AdGroupId,KeywordId,Bid
 direct bids set --keyword-id 123 --bid 15000000
 direct bids set-auto --keyword-id 123 --max-bid 20000000 --position PREMIUMBLOCK --scope SEARCH --dry-run
 direct keywordbids set --keyword-id 321 --search-bid 8000000 --network-bid 3000000
 direct keywordbids set-auto --keyword-id 321 --target-traffic-volume 100 --increase-percent 10 --bid-ceiling 12500000 --dry-run
+direct bidmodifiers get --campaign-ids 123 --fields Id,CampaignId,AdGroupId,Level,Type
 direct bidmodifiers add --campaign-id 123 --type DEMOGRAPHICS_ADJUSTMENT --value 150 --gender GENDER_MALE --age AGE_25_34 --dry-run
 direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+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 dynamicads add --adgroup-id 33 --name "Webpage A" --condition "URL:CONTAINS_ANY:test|shop" --condition "PAGE_CONTENT:CONTAINS:baz" --bid 3000000 --context-bid 2000000 --priority HIGH --dry-run
@@ -966,13 +994,15 @@ direct adimages add --name banner.png --image-data BASE64DATA --type ICON --dry-
 direct creatives add --video-id video-id --dry-run
 direct feeds add --name "Фид A" --url "https://example.com/feed.xml" --dry-run
 direct feeds update --id 18 --name "Фид A v2" --url "https://example.com/feed-v2.xml" --dry-run
-direct clients update --client-id 999 --phone +70000000000 --fax +70000000001 --email user@example.com --city Moscow --dry-run
-direct agencyclients add --login client-login --first-name Alice --last-name Smith --currency RUB --notification-email ops@example.com --notification-lang RU --send-account-news --no-send-warnings --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
 direct agencyclients add-passport-organization --name "Org" --currency RUB --notification-email ops@example.com --notification-lang EN --no-send-account-news --send-warnings --dry-run
 direct agencyclients add-passport-organization-member --passport-organization-login org-login --role CHIEF --invite-email user@example.com --dry-run
-direct agencyclients update --client-id 42 --phone +70000000000 --email user@example.com --grant EDIT_CAMPAIGNS --grant IMPORT_XLS --dry-run
+direct agencyclients update --client-id 42 --phone +70000000000 --notification-email user@example.com --grant EDIT_CAMPAIGNS=YES --grant IMPORT_XLS=NO --dry-run
 ```
 
+`direct agencyclients add` runtime-deprecated в Yandex Direct и блокируется CLI. Используйте `direct agencyclients add-passport-organization`.
+
 ### Известная неподдерживаемая API-операция
 
 `dynamicads update` unsupported by API. Сервис Яндекс Директа

direct_cli-0.3.1/direct_cli/_smoke_probes.py

@@ -0,0 +1,94 @@
+"""Live smoke-test probes for IDs that cannot be hardcoded safely."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Optional
+
+from .api import create_client
+
+VIDEO_CREATIVE_TYPES = {
+    "VIDEO_EXTENSION_CREATIVE",
+    "CPM_VIDEO_CREATIVE",
+    "CPC_VIDEO_CREATIVE",
+}
+
+
+def _extract_items(response: Any) -> list[dict[str, Any]]:
+    """Return a normalized list from a tapi response object."""
+    data = response().extract()
+    return data if isinstance(data, list) else []
+
+
+def _advideo_get_accepts(client: Any, candidate: str) -> bool:
+    """Return whether advideos.get accepts the candidate ID."""
+    body = {
+        "method": "get",
+        "params": {
+            "SelectionCriteria": {"Ids": [candidate]},
+            "FieldNames": ["Id", "Status"],
+            "Page": {"Limit": 1},
+        },
+    }
+    try:
+        _extract_items(client.advideos().post(data=body))
+        return True
+    except Exception:
+        return False
+
+
+def advideo_probe_id() -> Optional[str]:
+    """Return an AdVideos ID accepted by ``advideos.get``, or ``None``.
+
+    Returns ``None`` (never raises) on auth failure, missing credentials,
+    or any network/API error — smoke scripts use this in a context where a
+    failed probe should be a benign skip, not a fatal error.
+    """
+    try:
+        client = create_client()
+    except Exception:
+        return None
+
+    env_id = os.getenv("YANDEX_DIRECT_TEST_ADVIDEO_ID")
+    if env_id and _advideo_get_accepts(client, env_id):
+        return env_id
+
+    body = {
+        "method": "get",
+        "params": {
+            "SelectionCriteria": {},
+            "FieldNames": ["Id", "Name", "Type"],
+            "Page": {"Limit": 20},
+        },
+    }
+    try:
+        creatives = _extract_items(client.creatives().post(data=body))
+    except Exception:
+        return None
+
+    for creative in creatives:
+        if creative.get("Type") not in VIDEO_CREATIVE_TYPES:
+            continue
+        candidate = creative.get("Id")
+        if candidate and _advideo_get_accepts(client, str(candidate)):
+            return str(candidate)
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point for smoke probes."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv != ["advideo"]:
+        print("Usage: python3 -m direct_cli._smoke_probes advideo", file=sys.stderr)
+        return 2
+
+    probe_id = advideo_probe_id()
+    if not probe_id:
+        return 1
+    print(probe_id)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{direct_cli-0.2.11 → direct_cli-0.3.1}/direct_cli/_vendor/tapi_yandex_direct/__init__.py

@@ -1,8 +1,9 @@
 
 __author__ = 'Pavel Maksimov'
 __email__ = 'vur21@ya.ru'
-__version__ = '2026.4.25'
+__version__ = '2026.4.28'
 
 
 from .resource_mapping import *
 from .tapi_yandex_direct import YandexDirect
+from .v4 import YandexDirectV4Live

{direct_cli-0.2.11 → direct_cli-0.3.1}/direct_cli/_vendor/tapi_yandex_direct/exceptions.py

@@ -65,6 +65,49 @@ class YandexDirectRequestsLimitError(YandexDirectClientError):
         super().__init__(*args, **kwargs)
 
 
+class V4LiveError(YandexDirectApiError):
+    """Base exception for v4 Live API errors (error_code != 0).
+
+    v4 Live error payload differs from v5: integer ``error_code``, ``error_str``
+    instead of ``error_string``, no ``request_id``. Errors are returned with
+    HTTP 200 — they are detected from the response body, not the status code.
+    """
+
+    def __init__(
+        self,
+        response: Response,
+        message: Union[str, dict],
+        client: TapiClient,
+        *args,
+        **kwargs,
+    ):
+        if isinstance(message, dict):
+            try:
+                self.error_code = int(message.get("error_code", 0))
+            except (TypeError, ValueError):
+                self.error_code = 0
+            self.error_str = message.get("error_str", "")
+            self.error_detail = message.get("error_detail", "")
+        else:
+            self.error_code = 0
+            self.error_str = str(message)
+            self.error_detail = ""
+        super().__init__(response, message, client, *args, **kwargs)
+
+    def __str__(self):
+        return "v4 Live error_code={}, error_str={}, error_detail={}".format(
+            self.error_code, self.error_str, self.error_detail
+        )
+
+
+class V4LiveTokenError(V4LiveError):
+    """v4 Live error_code=53 — invalid or missing OAuth token."""
+
+
+class V4LiveRequestsLimitError(V4LiveError):
+    """v4 Live error_code in (54, 55, 56) — rate / method limit exceeded."""
+
+
 class BackwardCompatibilityError(Exception):
     def __init__(self, name):
         self.name = name

direct_cli-0.3.1/direct_cli/_vendor/tapi_yandex_direct/tapi_yandex_direct.pyi

@@ -0,0 +1,163 @@
+from typing import List, Iterator, Union
+
+from requests import Response
+
+class YandexDirectBaseMethodsClientResponse:
+    @property
+    def data(self) -> dict: ...
+    @property
+    def request_kwargs(self) -> dict: ...
+    @property
+    def response(self) -> Response: ...
+    @property
+    def status_code(self) -> int: ...
+    def __getitem__(self, item) -> Union[dict, list]: ...
+    def __iter__(self) -> Iterator: ...
+
+# Yandex Direct management.
+class YandexDirectClientResponse(YandexDirectBaseMethodsClientResponse):
+    def pages(
+        self, *, max_pages: int = None
+    ) -> Iterator["YandexDirectPageIteratorExecutor"]: ...
+    def items(self, *, max_items: int = None) -> Iterator[dict]: ...
+    def iter_items(
+        self, *, max_pages: int = None, max_items: int = None
+    ) -> Iterator[dict]: ...
+    def extract(self) -> List[dict]: ...
+
+class YandexDirectClientExecutorResponse(YandexDirectBaseMethodsClientResponse):
+    def __call__(self) -> YandexDirectClientResponse: ...
+
+class YandexDirectClientExecutor:
+    def open_docs(self) -> YandexDirectClientExecutor:
+        """Open API official docs of resource in browser."""
+    def open_in_browser(self) -> YandexDirectClientExecutor:
+        """Send a request in the browser."""
+    def help(self) -> YandexDirectClientExecutor:
+        """Print docs of resource."""
+    def get(
+        self, *, params: dict = None, data: dict = None, headers: dict = None
+    ) -> YandexDirectClientExecutorResponse:
+        """
+        Send HTTP 'GET' request.
+
+        :param params: querystring arguments in the URL
+        :param data: send data in the body of the request
+        """
+    def post(
+        self, *, params: dict = None, data: dict = None, headers: dict = None
+    ) -> YandexDirectClientExecutorResponse:
+        """
+        Send HTTP 'POST' request.
+
+        :param params: querystring arguments in the URL
+        :param data: send data in the body of the request
+        """
+
+class YandexDirectPageIteratorResponse(YandexDirectBaseMethodsClientResponse):
+    def items(self, *, max_items: int = None) -> Iterator[dict]: ...
+
+class YandexDirectPageIteratorExecutor(YandexDirectBaseMethodsClientResponse):
+    def __call__(self) -> YandexDirectPageIteratorResponse: ...
+
+# Yandex Direct reports.
+class YandexDirectClientReportResponse(YandexDirectBaseMethodsClientResponse):
+    def iter_lines(self) -> Iterator[str]: ...
+    def iter_values(self) -> Iterator[list]: ...
+    def iter_dicts(self) -> Iterator[dict]: ...
+    def to_lines(self) -> List[str]: ...
+    def to_values(self) -> List[list]: ...
+    def to_columns(self) -> List[list]: ...
+    def to_dicts(self) -> List[dict]: ...
+
+class YandexDirectClientReportExecutorResponse(YandexDirectBaseMethodsClientResponse):
+    def __call__(self) -> YandexDirectClientReportResponse: ...
+    @property
+    def columns(self) -> List[str]: ...
+
+class YandexDirectClientReportExecutor:
+    def open_docs(self) -> YandexDirectClientReportExecutor:
+        """Open API official docs of resource in browser."""
+    def open_in_browser(self) -> YandexDirectClientReportExecutor:
+        """Send a request in the browser."""
+    def help(self) -> YandexDirectClientReportExecutor:
+        """Print docs of resource."""
+    def post(
+        self, *, params: dict = None, data: dict = None, headers: dict = None
+    ) -> YandexDirectClientReportExecutorResponse:
+        """
+        Send HTTP 'POST' request.
+
+        :param params: querystring arguments in the URL
+        :param data: send data in the body of the request
+        """
+
+# Main.
+class YandexDirect:
+    def __init__(
+        self,
+        *,
+        access_token: str,
+        login: str = None,
+        is_sandbox: bool = False,
+        retry_if_not_enough_units: bool = False,
+        retry_if_exceeded_limit: bool = True,
+        retries_if_server_error: int = 5,
+        language: str = None,
+        processing_mode: str = "offline",
+        wait_report: bool = True,
+        return_money_in_micros: bool = False,
+        skip_report_header: bool = True,
+        skip_column_header: bool = False,
+        skip_report_summary: bool = True,
+    ):
+        """
+        Official documentation of the reports resource: https://yandex.ru/dev/direct/doc/ref-v5/concepts/about.html
+        Official documentation of other resources: https://yandex.ru/dev/direct/doc/reports/how-to.html
+
+        :param access_token: Access token.
+        :param login: If you are making inquiries from an agent account, you must be sure to specify the account login.
+        :param is_sandbox: Enable sandbox.
+        :param retry_if_not_enough_units: Repeat request when units run out
+        :param retry_if_exceeded_limit: Repeat the request if the limits on the number of reports or requests are exceeded.
+        :param retries_if_server_error: Number of retries when server errors occur.
+        :param language: The language in which the data for directories and errors will be returned.
+
+        :param processing_mode: (report resource) Report generation mode: online, offline or auto.
+        :param wait_report: (report resource) When requesting a report, it will wait until the report is prepared and download it.
+        :param return_money_in_micros: (report resource) Monetary values in the report are returned in currency with an accuracy of two decimal places.
+        :param skip_report_header: (report resource) Do not display a line with the report name and date range in the report.
+        :param skip_column_header: (report resource) Do not display a line with field names in the report.
+        :param skip_report_summary: (report resource) Do not display a line with the number of statistics lines in the report.
+        """
+    def reports(self) -> YandexDirectClientReportExecutor: ...
+    def adextensions(self) -> YandexDirectClientExecutor: ...
+    def adgroups(self) -> YandexDirectClientExecutor: ...
+    def adimages(self) -> YandexDirectClientExecutor: ...
+    def advideos(self) -> YandexDirectClientExecutor: ...
+    def ads(self) -> YandexDirectClientExecutor: ...
+    def agencyclients(self) -> YandexDirectClientExecutor: ...
+    def audiencetargets(self) -> YandexDirectClientExecutor: ...
+    def bidmodifiers(self) -> YandexDirectClientExecutor: ...
+    def bids(self) -> YandexDirectClientExecutor: ...
+    def businesses(self) -> YandexDirectClientExecutor: ...
+    def campaigns(self) -> YandexDirectClientExecutor: ...
+    def changes(self) -> YandexDirectClientExecutor: ...
+    def clients(self) -> YandexDirectClientExecutor: ...
+    def creatives(self) -> YandexDirectClientExecutor: ...
+    def debugtoken(self, *, client_id: str) -> YandexDirectClientExecutor: ...
+    def dictionaries(self) -> YandexDirectClientExecutor: ...
+    def dynamicads(self) -> YandexDirectClientExecutor: ...
+    def dynamicfeedadtargets(self) -> YandexDirectClientExecutor: ...
+    def feeds(self) -> YandexDirectClientExecutor: ...
+    def keywordbids(self) -> YandexDirectClientExecutor: ...
+    def keywords(self) -> YandexDirectClientExecutor: ...
+    def keywordsresearch(self) -> YandexDirectClientExecutor: ...
+    def leads(self) -> YandexDirectClientExecutor: ...
+    def negativekeywordsharedsets(self) -> YandexDirectClientExecutor: ...
+    def retargeting(self) -> YandexDirectClientExecutor: ...
+    def sitelinks(self) -> YandexDirectClientExecutor: ...
+    def smartadtargets(self) -> YandexDirectClientExecutor: ...
+    def strategies(self) -> YandexDirectClientExecutor: ...
+    def turbopages(self) -> YandexDirectClientExecutor: ...
+    def vcards(self) -> YandexDirectClientExecutor: ...

direct_cli-0.3.1/direct_cli/_vendor/tapi_yandex_direct/v4/__init__.py

@@ -0,0 +1,9 @@
+from .adapter import V4LiveClientAdapter, YandexDirectV4Live
+from .resource_mapping import RESOURCE_MAPPING_V4_LIVE, SUPPORTED_V4_METHODS
+
+__all__ = [
+    "V4LiveClientAdapter",
+    "YandexDirectV4Live",
+    "RESOURCE_MAPPING_V4_LIVE",
+    "SUPPORTED_V4_METHODS",
+]