direct-cli 0.3.12__tar.gz → 0.3.14__tar.gz

{direct_cli-0.3.12 → direct_cli-0.3.14}/AGENTS.md

@@ -73,21 +73,22 @@ direct dictionaries get-geo-regions \
 
 ### Datetime Rules
 
-- Datetime parameters must be passed in the format `YYYY-MM-DDTHH:MM:SS`.
+- Changes timestamps must match Yandex Direct API format `YYYY-MM-DDTHH:MM:SSZ`.
+- Other datetime parameters use their method-specific documented format.
 - Datetime values must be passed as a single shell token.
-- Canonical examples must not use timezone suffixes like `Z`.
+- Canonical `changes` examples must use the `Z` suffix.
 - Canonical examples must not use quoted space-separated datetime values.
 
 Use:
 
 ```bash
-direct changes check-campaigns --timestamp 2026-04-14T00:00:00
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
 ```
 
 Do not use:
 
 ```bash
-direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00
 direct changes check-campaigns --timestamp "2026-04-14 00:00:00"
 ```
 
@@ -104,7 +105,7 @@ Valid canonical examples:
 
 ```bash
 direct campaigns get --ids 1,2,3
-direct changes check-campaigns --timestamp 2026-04-14T00:00:00
+direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
 direct keywordsresearch has-search-volume --keywords "buy laptop,buy desktop"
 direct smartadtargets update --id 456 --priority HIGH
 direct dynamicads set-bids --id 789 --bid 12.5
@@ -119,7 +120,6 @@ direct dynamicads set-bids --id 789 --bid 12.5 --json '{"StrategyPriority":"HIGH
 direct dictionaries get-geo-regions \
   --region-ids 225 \
   --fields GeoRegionId,GeoRegionName
-direct changes check-campaigns --timestamp 2026-04-14T00:00:00Z
 direct changes check-campaigns --timestamp "2026-04-14 00:00:00"
 ```
 

{direct_cli-0.3.12 → direct_cli-0.3.14}/CHANGELOG.md

@@ -1,5 +1,273 @@
 # Changelog
 
+## 0.3.14
+
+**Fixed:**
+
+- Reports drift checker now points at the canonical Yandex docs URLs
+  (`/ru/type`, `/ru/period`, `/ru/fields-list`, `/ru/spec`) after Yandex
+  retired the `/ru/reports/<page>` path layout and renamed `spec.html`
+  to `spec`. The pre-existing `tests/reports_cache/raw/` had silently
+  been captcha-poisoned for three of those pages (~14.6 KB Yandex
+  SmartCaptcha gateway in place of real docs); cache is now refetched
+  from the live canonical URLs and `spec.json` is byte-equivalent to
+  the pre-migration snapshot except for one updated description string.
+- Five `RESOURCE_MAPPING_V5[*]["docs"]` URLs that Yandex moved from the
+  legacy `…/ru/<group>/<group>` to `…/ru/<group>` single-segment form
+  (`dynamictextadtargets`, `dynamicfeedadtargets`, `reports`,
+  `smartadtargets`, `vcards`). Closes #426.
+
+**Added (drift protection):**
+
+- `direct_cli/reports_coverage.py::fetch_reports_spec` and
+  `direct_cli/wsdl_coverage.py::fetch_wsdl` / `fetch_live_wsdl` now
+  refuse responses that look like a Yandex SmartCaptcha gateway (markers
+  `showcaptcha`, `smartcaptcha`, `<title>Captcha`) or are suspiciously
+  short. This prevents silently poisoning the docs/WSDL cache with
+  rate-limited captcha HTML.
+- `tests/test_api_coverage.py::TestReportsCoverage::test_reports_cache_files_are_real_content`
+  and `TestWsdlCacheFreshness::test_wsdl_cache_files_are_real_content`
+  guard the committed cache files against the same poisoning.
+- `scripts/check_all_docs_urls.py` — health-checks every URL in
+  `RESOURCE_MAPPING_V5` and `REPORTS_SPEC_URLS`. Hard-fails on
+  redirect-to-captcha, canonical move (`Location` with a different path
+  segment), 4xx, or captcha body; soft-warns on 5xx; paces requests to
+  avoid Yandex rate-limit. Wired into `scripts/release_pypi.sh` as a
+  mandatory pre-release gate together with `refresh_reports_cache.py`
+  and a focused pytest pass.
+
+**Contract** (`CLAUDE.md`):
+
+- New rule "No URL literals outside the registry" — every Yandex
+  docs/API URL is declared once in `RESOURCE_MAPPING_V5` or
+  `REPORTS_SPEC_URLS`; importers reference the constant.
+- New rule "Docs/cache freshness guard" — fetchers and cache files
+  enforce minimum-size and no-captcha invariants.
+- New section "PyPI Release" — documents the three pre-release health
+  checks executed by `release_pypi.sh`.
+
+**Breaking changes:**
+
+- `direct ads get` flag `--text-ad-fields` is **renamed** to the
+  WSDL-canonical `--text-ad-field-names` form matching the
+  `TextAdFieldNames` request parameter declared by `AdsGetRequest`.
+  The old `--text-ad-fields` form is no longer accepted — update
+  scripts and automation accordingly. Closes #406.
+- `direct campaigns add` / `direct campaigns update` and `direct
+  strategies add` / `direct strategies update` now reject `--priority-goals`
+  / `--priority-goal` values below 100,000 (0.1 unit in micro-currency).
+  Per Yandex Direct API (add-text-campaign, strategies-types),
+  `PriorityGoalsItem.Value` is `xsd:long` in advertiser currency
+  multiplied by 1,000,000 — the same contract as `--budget`,
+  `--average-cpa`, and other money flags after #399/#400. The error
+  message suggests the micro-currency conversion (e.g. `Did you mean
+  500000000?`). Negative values are also rejected up-front rather than
+  reaching the API. Both parsers share a single
+  `validate_priority_goal_value` helper. Closes #387.
+
+**Added:**
+
+- `direct sitelinks get` now exposes `--sitelink-field-names` for the
+  separate WSDL `SitelinkFieldNames` request parameter
+  (`SitelinkFieldEnum`: `Title`, `Href`, `Description`, `TurboPageId`).
+  Previously only the top-level `--fields` (mapping to `FieldNames`)
+  was available, so the nested `Sitelinks[]` projection could not be
+  controlled from CLI.
+- `direct keywordbids get` now exposes `--fields`,
+  `--search-field-names`, and `--network-field-names` for the
+  separate `FieldNames`, `SearchFieldNames`, and `NetworkFieldNames`
+  request parameters declared by `KeywordBidsGetRequest`. Defaults
+  from `COMMON_FIELDS` are preserved when flags are absent.
+- Regression test `test_every_nested_fieldnames_param_has_cli_option`
+  (`tests/test_api_coverage.py`) scans every cached WSDL `get`
+  request type for `*FieldNames` parameters and verifies that each
+  one has a matching kebab-case CLI option. Acknowledged remaining
+  gaps are tracked in `NESTED_FIELDNAMES_EXCLUSIONS` and #402 so
+  future additions cannot silently slip in.
+- `direct feeds get` now exposes `--file-feed-field-names` and
+  `--url-feed-field-names` for the separate WSDL `FileFeedFieldNames`
+  (`FileFeedFieldEnum`: `Filename`) and `UrlFeedFieldNames`
+  (`UrlFeedFieldEnum`: `Login`, `Url`, `RemoveUtmTags`) request
+  parameters declared by `FeedsGetRequest`. Previously only the
+  top-level `--fields` (mapping to `FieldNames`) was available, so
+  the nested `FileFeed` / `UrlFeed` projections could not be
+  controlled from CLI. Closes #412.
+- `direct keywords get` now exposes
+  `--autotargeting-settings-brand-options-field-names`
+  (`AutotargetingBrandOptionsFieldEnum`: `WithoutBrands`,
+  `WithAdvertiserBrand`, `WithCompetitorsBrand`) and
+  `--autotargeting-settings-categories-field-names`
+  (`AutotargetingCategoriesFieldEnum`: `Exact`, `Narrow`,
+  `Alternative`, `Accessory`, `Broader`) for the separate WSDL
+  `*FieldNames` request parameters declared by
+  `KeywordsGetRequest`. Previously only the top-level `--fields`
+  (mapping to `FieldNames`) was available, so the nested
+  `AutotargetingSettings.BrandOptions` / `Categories` projections
+  could not be controlled from CLI. Closes #413.
+- `direct creatives get` now exposes
+  `--cpc-video-creative-field-names`,
+  `--cpm-video-creative-field-names`,
+  `--smart-creative-field-names`, and
+  `--video-extension-creative-field-names` for the four nested
+  WSDL `*FieldNames` request parameters declared by
+  `CreativesGetRequest` (`CpcVideoCreativeFieldEnum`,
+  `CpmVideoCreativeFieldEnum`, `SmartCreativeFieldEnum`,
+  `VideoExtensionCreativeFieldEnum`). Previously only the top-level
+  `--fields` (mapping to `FieldNames`) was available, so the
+  per-subtype projections could not be controlled from CLI.
+  Closes #411.
+- `direct clients get` now exposes `--contract-field-names`,
+  `--contragent-field-names`, `--contragent-tin-info-field-names`,
+  `--organization-field-names`, and `--tin-info-field-names` for
+  the five nested WSDL `*FieldNames` request parameters declared
+  by `ClientsGetRequest` (`ContractInfoFieldEnum`,
+  `ContragentInfoFieldEnum`, `TinInfoFieldEnum`,
+  `OrgInfoFieldEnum`, `TinInfoFieldEnum`). The command also gains
+  `--dry-run` for parity with other read-path commands.
+  Previously only the top-level `--fields` (mapping to `FieldNames`)
+  was available, so the per-subtype ERIR projections could not be
+  controlled from CLI. Closes #410.
+- `direct agencyclients get` now exposes `--contract-field-names`,
+  `--contragent-field-names`, `--contragent-tin-info-field-names`,
+  `--organization-field-names`, and `--tin-info-field-names` for
+  the five nested WSDL `*FieldNames` request parameters declared
+  by `AgencyClientsGetRequest` (`ContractInfoFieldEnum`,
+  `ContragentInfoFieldEnum`, `TinInfoFieldEnum`,
+  `OrgInfoFieldEnum`, `TinInfoFieldEnum`). The command also gains
+  `--dry-run` for parity with other read-path commands.
+  Previously only the top-level `--fields` (mapping to `FieldNames`)
+  was available, so the per-subtype ERIR projections could not be
+  controlled from CLI. Closes #407.
+- `direct adgroups get` now exposes eight additional
+  `--*-field-names` flags for the separate WSDL `*FieldNames`
+  request parameters declared by `AdGroupsGetRequest`:
+  `--autotargeting-settings-brand-options-field-names`,
+  `--autotargeting-settings-categories-field-names`,
+  `--dynamic-text-ad-group-field-names`,
+  `--dynamic-text-feed-ad-group-field-names`,
+  `--mobile-app-ad-group-field-names`,
+  `--smart-ad-group-field-names`,
+  `--text-ad-group-feed-params-field-names`, and
+  `--unified-ad-group-field-names`. Previously only the top-level
+  `--fields` (mapping to `FieldNames`) was available, so the
+  per-subtype ad-group projections could not be controlled from
+  CLI. Closes #405.
+- `direct ads get` now exposes sixteen additional `--*-field-names`
+  flags for the separate WSDL `*FieldNames` request parameters
+  declared by `AdsGetRequest`: `--cpc-video-ad-builder-ad-field-names`,
+  `--cpm-banner-ad-builder-ad-field-names`,
+  `--cpm-video-ad-builder-ad-field-names`,
+  `--dynamic-text-ad-field-names`, `--listing-ad-field-names`,
+  `--mobile-app-ad-builder-ad-field-names`,
+  `--mobile-app-ad-field-names`,
+  `--mobile-app-cpc-video-ad-builder-ad-field-names`,
+  `--mobile-app-image-ad-field-names`,
+  `--responsive-ad-field-names`, `--shopping-ad-field-names`,
+  `--smart-ad-builder-ad-field-names`,
+  `--text-ad-builder-ad-field-names`,
+  `--text-ad-field-names`,
+  `--text-ad-price-extension-field-names`, and
+  `--text-image-ad-field-names`. Previously only the top-level
+  `--fields` (mapping to `FieldNames`) and non-canonical
+  `--text-ad-fields` were available, so the per-ad-subtype projections
+  could not be controlled from CLI. Closes #406.
+
+**BREAKING CHANGES:**
+
+- `direct campaigns get` flags `--text-campaign-fields`,
+  `--mobile-app-campaign-fields`, `--dynamic-text-campaign-fields`,
+  `--cpm-banner-campaign-fields`, `--smart-campaign-fields`,
+  `--unified-campaign-fields`,
+  `--text-campaign-search-strategy-placement-types-fields`,
+  `--dynamic-text-campaign-search-strategy-placement-types-fields`,
+  `--unified-campaign-search-strategy-placement-types-fields`, and
+  `--unified-campaign-package-bidding-strategy-platforms-fields`
+  are **renamed** to their kebab-case WSDL-canonical `*-field-names`
+  form (`--text-campaign-field-names`,
+  `--mobile-app-campaign-field-names`, ...), matching the parameter
+  names declared by `CampaignsGetRequest`. The old `--*-fields`
+  forms are no longer accepted — update scripts and automation
+  accordingly. Closes #409.
+
+**Additional features:**
+
+- `direct bidmodifiers get` now exposes thirteen additional
+  `--*-adjustment-field-names` flags for the per-adjustment-subtype
+  WSDL `*FieldNames` request parameters declared by
+  `BidModifiersGetRequest`: `--ad-group-adjustment-field-names`,
+  `--demographics-adjustment-field-names`,
+  `--desktop-adjustment-field-names`,
+  `--desktop-only-adjustment-field-names`,
+  `--income-grade-adjustment-field-names`,
+  `--mobile-adjustment-field-names`,
+  `--regional-adjustment-field-names`,
+  `--retargeting-adjustment-field-names`,
+  `--serp-layout-adjustment-field-names`,
+  `--smart-ad-adjustment-field-names`,
+  `--smart-tv-adjustment-field-names`,
+  `--tablet-adjustment-field-names`, and
+  `--video-adjustment-field-names`. Previously only the top-level
+  `--fields` (mapping to `FieldNames`) was available, so the
+  per-adjustment projections could not be controlled from CLI.
+  Closes #408.
+- `direct strategies get` now exposes sixteen additional
+  `--strategy-*-field-names` flags for the separate WSDL
+  `*FieldNames` request parameters declared by `StrategiesGetRequest`,
+  including `--strategy-average-cpa-field-names`,
+  `--strategy-average-cpa-multiple-goals-field-names`,
+  `--strategy-average-cpc-field-names`,
+  `--strategy-maximum-clicks-field-names`,
+  `--strategy-maximum-conversion-rate-field-names`,
+  `--strategy-pay-for-conversion-field-names`, and the remaining
+  per-campaign / per-filter strategy projections. The command also
+  gains `--dry-run` for read-path payload tests. Previously only the
+  top-level `--fields` (mapping to `FieldNames`) was available, so
+  per-strategy-subtype projections could not be controlled from CLI.
+  Closes #414.
+
+Closes #360.
+
+**Tests:**
+
+- `tests/test_integration.py` now gracefully skips the seven read-only
+  classes that rely on live-API probes (`TestReadOnlyAdGroups`,
+  `TestReadOnlyAds`, `TestReadOnlyKeywords`,
+  `TestReadOnlyDynamicFeedAdTargets`, `TestReadOnlyLeads`,
+  `TestReadOnlyBusinesses`, `TestReadOnlyAdVideos`) when the probe
+  raises — previously a temporary API outage crashed `setUpClass`
+  with an opaque traceback.
+- `invoke_get` in `tests/test_integration.py` now passes the resolved
+  test credentials as explicit `--token`/`--login` flags so the
+  integration suite cannot silently fall through to a developer's
+  active `direct auth` profile (priority 1 in the CLI credential
+  chain wins over the profile, matching CLAUDE.md guidance).
+- `tests/test_comprehensive.py` slimmed down: `TestCLIHelp` (full
+  duplicate of `tests/test_cli.py`) removed; the unique
+  `TestCommandsRegistered`, `TestUtils`, `TestOutputFormatters`,
+  `TestAuth`, and `TestErrorHandling` classes are kept.
+- `tests/test_smoke_matrix.py` no longer hard-codes
+  `total_cli_subcommands == 144` or `wsdl_operations == 112`. Counts
+  are derived from the live Click registry and parsed WSDLs.
+- `tests/test_sandbox_write_audit.py` no longer hard-codes
+  `total == 83`. The count derives from `commands_for_category`.
+
+Closes #396.
+
+## 0.3.13
+
+**Breaking changes:**
+
+- `direct campaigns add` and `direct campaigns update` now require all
+  bidding-strategy money flags to be passed directly in micro-rubles,
+  matching the existing `--budget`, `--average-cpa`, `--bid-ceiling`, and
+  `--filter-average-cpc` contract. The CLI no longer accepts decimal currency
+  values or performs unit conversion for campaign money
+  inputs. Closes #399.
+- `direct ads add` and `direct ads update` now apply the same API-native
+  micro-ruble contract to `--price-extension-price` and
+  `--price-extension-old-price`; price-extension values are no longer parsed
+  as decimal currency amounts.
+
 ## 0.3.12
 
 **Added:**

{direct_cli-0.3.12 → direct_cli-0.3.14}/CLAUDE.md

@@ -41,6 +41,8 @@ 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.
 
+**No legacy CLI flag aliases.** A CLI option must be exactly the kebab-case form of the WSDL request parameter (`SitelinkFieldNames` → `--sitelink-field-names`). If an existing flag uses a different name for the same WSDL parameter, rename it as a **breaking change** — do not keep the old form as a second `@click.option` name on the same variable. Document the rename in `CHANGELOG.md` under a `BREAKING CHANGES` heading and bump the version accordingly.
+
 **Runtime-deprecated methods:** WSDL-visible methods that Yandex rejects at runtime belong in `RUNTIME_DEPRECATED_METHODS` (`direct_cli/wsdl_coverage.py`) and must fail with `click.UsageError` before request construction. `agencyclients add` is blocked this way; use `agencyclients add-passport-organization`.
 
 **Strict WSDL parity:** `DRY_RUN_PAYLOAD_EXCLUSIONS` in `tests/api_coverage_payloads.py` must NOT contain any entry whose rationale claims the CLI surface is a «helper», «legacy», or «not part of strict WSDL parity». If the WSDL declares the operation, the CLI mirrors it 1:1 with a `PAYLOAD_CASES` fixture. Legitimate permanent exclusions are limited to:
@@ -72,6 +74,34 @@ Adding a new mutating command requires extending `COMMAND_WSDL_MAP` in `tests/te
 
 **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`.
 
+**No URL literals outside the registry.** Every Yandex docs/API URL is declared once — either in `direct_cli/_vendor/tapi_yandex_direct/resource_mapping.py` (`docs`, `docs_pages.*`) or in `direct_cli/reports_coverage.py::REPORTS_SPEC_URLS`. Tests and scripts import these constants; never write the URL as a string literal anywhere else. Captcha-poisoning of the docs cache (#426) was possible only because the same URL was duplicated in a hard-coded test assertion. Don't repeat that.
+
+**Docs/cache freshness guard.** `direct_cli.reports_coverage.fetch_reports_spec` and `direct_cli.wsdl_coverage.fetch_wsdl` both refuse responses that look like a Yandex SmartCaptcha gate (markers `showcaptcha`, `smartcaptcha`, `<title>Captcha`) or are suspiciously short (<30 KB for HTML, <3 KB for WSDL). The matching tests `test_reports_cache_files_are_real_content` and `test_wsdl_cache_files_are_real_content` enforce the same invariant on committed cache files.
+
+## PyPI Release
+
+Release is two-phase on purpose. Yandex frequently rate-limits the docs host with a SmartCaptcha gateway, which is an external rate-limit on our IP — not evidence that an URL is gone. Mixing docs-health checks into the publish path made releases non-deterministic, so they live in a separate preflight script.
+
+**Phase 1 — preflight (manual, network-dependent):**
+
+```
+bash scripts/preflight_check.sh
+```
+
+Runs three checks:
+
+1. `python scripts/check_all_docs_urls.py` — every Yandex docs URL in `RESOURCE_MAPPING_V5` and `REPORTS_SPEC_URLS` must be reachable. The probe falls back from `HEAD` to `GET` on 4xx (some CDNs reject `HEAD`), then verifies real content. **Hard fail:** confirmed 3xx-to-different-path or 4xx (canonical move / gone). **Soft warning (does not block):** 5xx or persistent captcha — treated as a transient Yandex rate-limit; re-run later to confirm.
+2. `pytest TestReportsCoverage TestWsdlCacheFreshness -v` — read-only check that the committed Reports/WSDL/XSD caches are real content (not captcha).
+3. `git diff --quiet -- tests/reports_cache tests/wsdl_cache` — refuses to proceed with an uncommitted cache refresh. If Yandex changed docs since the last snapshot, run `scripts/refresh_reports_cache.py` separately, review the diff, and commit it before releasing.
+
+**Phase 2 — release (deterministic, no Yandex network calls):**
+
+```
+bash scripts/release_pypi.sh all
+```
+
+Builds dist artifacts, runs twine checks, uploads to TestPyPI + PyPI. Does **not** re-run docs/cache checks — if the captcha rate-limit was active during preflight, that should not block a release of an already-verified artifact.
+
 ## Tests
 
 - **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.