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

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

@@ -1,5 +1,202 @@
 # Changelog
 
+## 0.4.2
+
+**BREAKING CHANGES - get requires SelectionCriteria (#498):**
+
+- `adgroups` / `ads` / `keywords` / `strategies` / `creatives` / `dynamicads` /
+  `smartadtargets` / `audiencetargets` `get` now refuse an empty
+  `SelectionCriteria` before the API call, raising a `UsageError` that asks for
+  at least one filter — instead of sending `{"SelectionCriteria": {}}` (which the
+  API rejects with the opaque error 4001 for ad-group/ad/keyword resources).
+  Extends the same guard already shipped for `bids` / `keywordbids` in 0.4.1
+  (#483). WSDL declares `GetRequest.SelectionCriteria` as `minOccurs=1` for all
+  eight resources.
+- `retargeting get` gains `--dry-run` and the shared read/pagination option
+  stack; its `SelectionCriteria` stays optional (WSDL `minOccurs=0`), so a
+  no-filter call is still valid and now omits the empty criteria from the
+  payload.
+- All eight commands and `retargeting get` build their request via the shared
+  `build_common_params` helper, completing the dedup epic #491 (B3c).
+
+**BREAKING CHANGES - auth precedence (#489):**
+
+- Base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` credentials from the
+  environment or current-directory `.env` now win over the active OAuth profile
+  selected by `direct auth use` when `--profile` is not passed. Explicit
+  `--token`, `--login`, and `--profile` still take priority.
+- `direct auth status` reports the selected effective credentials, including
+  base env/`.env` and secret-manager fallbacks, instead of reporting only the
+  active OAuth profile.
+- `direct auth login` can now ask interactive users whether to save the OAuth
+  access token and resolved login into the current-directory `.env`; the default
+  answer is no.
+
+**Docs — live-write coverage limitation (#538):**
+
+- Documented why the SMART_CAMPAIGN / DYNAMIC_TEXT_CAMPAIGN / `adimages`
+  live-write lifecycle (`dynamicads`, `smartadtargets`, `adimages`) stays
+  recorded only as 3500/5004 error cassettes. Verified via direct API calls that
+  the available sandbox **agency** account has no client accounts under it
+  (`agencyclients.get` → empty), cannot create one (3001 "No rights to create
+  clients", access by request only), and that without a client login every
+  agency-scoped mutation returns 8000. Closed #538 as a documented account-tier
+  limitation; no CLI code change. See `tests/MANUAL_COVERAGE.md`.
+
+## 0.4.1
+
+Russian-default CLI localization across all command modules (epic #466).
+
+**Fixed — bug hunt (#483):**
+
+- `bids get` / `keywordbids get`: refuse an empty `SelectionCriteria` before the
+  API call, raising a `UsageError` that asks for at least one filter
+  (`--campaign-ids` / `--adgroup-ids` / `--keyword-ids` / `--serving-statuses`)
+  instead of letting the API reject it with the opaque error 4001.
+- `bids set-auto`: require exactly one of `--campaign-id`, `--adgroup-id`, or
+  `--keyword-id` via the shared `add_single_id_selector` (the three are mutually
+  exclusive per the API docs), matching `bids set`.
+- `reports get`: reject a `--fields` value that parses to an empty list (for
+  example `",,,"`) before building the request, instead of sending an invalid
+  `FieldNames: []` (API error 8000).
+- Error-handling consistency: `get`/lifecycle handlers across `bids`,
+  `keywordbids`, `negativekeywordsharedsets`, `balance`, `strategies`,
+  `retargeting`, `ads` (all 8 commands), and `advideos` now re-raise
+  `click.UsageError` / `click.ClickException` before the generic
+  `except Exception`, so validation errors keep their Click formatting and
+  exit code 2 instead of being downgraded to an `Abort`.
+- Vendor `tapi_yandex_direct`: `to_columns()` no longer raises `IndexError` on
+  report rows shorter than the header (pads with `""`); the error handler reads
+  `error_detail` with `.get()` so an unfamiliar error structure no longer masks
+  the original API error with a `KeyError`.
+- `utils.parse_priority_goals_spec`: corrected the item type annotation to
+  `List[Dict[str, Any]]` (items hold `"YES"/"NO"` strings, not only ints).
+
+**Fixed — `--help` hung on a client-login network call (#480 follow-up):**
+
+- After #480, `get_credentials` resolved the bare Client-Login via a network
+  `clients.get` on every CLI invocation — including `<group> --help` — whenever
+  an OAuth profile with an email login had not yet been migrated. That call had
+  no timeout, so a slow link or a Yandex SmartCaptcha gateway could hang the
+  CLI. Help/version passes now skip the resolver, the resolver is capped with a
+  hard timeout, and the unit suite neutralizes it so tests never touch the
+  network.
+
+**Fixed — auth login saved Passport email, breaking v4 (#480):**
+
+- `direct auth login` (OAuth / PKCE) stored the Passport email
+  (`<login>@yandex.ru`) in `auth.json`, which Direct v4 AccountManagement
+  rejects with `FaultCode 259` ("This client does not exist") — breaking
+  `direct balance` and `direct v4account ...`. Login now resolves the bare
+  **Client-Login** via a one-shot v5 `clients.get` (`resolve_account_login`),
+  falling back to the Passport login only if that call fails.
+- `get_credentials` migrates older profiles in place: when a stored OAuth login
+  is an email whose local part matches the token owner's resolved Client-Login,
+  it is rewritten to the bare login (one-time, persisted). Agency profiles whose
+  login differs from the token owner are never clobbered, and an explicit
+  `--login` is never overridden.
+
+**Localized — interpolated error messages (#478), completing epic #466:**
+
+- Rewrote all 121 interpolated `click.UsageError` / `click.BadParameter` /
+  `print_*` messages (114 f-strings + 7 string concatenations) across the
+  command modules into the stable `t("<template>").format(**kwargs)` pattern,
+  with 96 unique English templates translated to Russian (6 shared templates,
+  e.g. `Provide a non-empty comma-separated {wsdl_key} list.`, in
+  `common.json`). Placeholder names, conversions, and format specs are
+  preserved verbatim in both locales, so the rendered English text is
+  byte-identical to before and the Russian render fills the same fields.
+- `t()` gained `@overload` signatures (`str -> str`, `None -> None`) so
+  `t(...).format(...)` type-checks without touching call sites.
+- `tests/test_i18n.py` now (a) flags f-string / concat — not just static —
+  bare literals in `_RUNTIME_MESSAGE_FUNCS` calls (also covering
+  `print_success`), accepting only `t(...)` / `t(...).format(...)`; and
+  (b) asserts placeholder parity between every English template key and its
+  Russian translation. This completes the error-message localization checklist
+  of epic #466.
+
+**Localized — static error messages (#477):**
+
+- Wrapped all 179 static `click.UsageError` / `click.BadParameter` string
+  literals (and the `auth` OAuth-code `click.prompt`) across 33 command
+  modules in `t(...)`, with Russian translations added to the per-module
+  `translations/*.json` catalogs; seven messages shared across modules
+  (e.g. `Provide at least one field to update`,
+  `--status and --statuses are mutually exclusive`) live in `common.json`.
+  Validation errors now render in Russian by default and in English under
+  `--locale en`. Flag names, enum values, and WSDL field names are unchanged.
+- Extended `tests/test_i18n.py::test_localized_groups_wrap_runtime_messages`
+  to also scan `UsageError` / `BadParameter` / `prompt` / `confirm` (bare or
+  `click.<Name>`); a bare string literal first argument is rejected. Only
+  static `ast.Constant` literals are enforced for now — interpolated
+  (f-string / concat) messages are stage B (#478).
+- Test suite defaults the CLI locale to English (`tests/conftest.py` autouse
+  fixture) so the existing English error-contract assertions stay valid; the
+  Russian default remains covered by `tests/test_i18n.py`.
+
+**Added — scalable i18n mechanism (#467):**
+
+- Source-string-keyed translation catalog: the English `help=` / docstring /
+  epilog text is the catalog key, with Russian translations in external
+  `direct_cli/translations/*.json` files (one per module, plus shared
+  `common.json`). No `cls=`/`help_key` edits in command modules —
+  `cli._apply_directcli_classes` retypes every plain `click.Option` to
+  `LocalizedOption` and localizes command/group docstrings and epilogs at
+  render time.
+- `t()` is now source-keyed and context-free safe (`set_active_locale`), so
+  `print_*` runtime messages localize too. `--locale` is eager so the root
+  `--help` epilog honors an inline `--locale`.
+- `tests/test_i18n.py` gains a `LOCALIZED_GROUPS` registry with two enforced
+  invariants per localized module: translation completeness (no silent English
+  leak under the Russian default) and `print_*` runtime-message wrapping.
+- `v4finance` migrated to the new mechanism and fully localized as the
+  reference module.
+
+**Localized — Core search (#468):**
+
+- Russian help/docstrings for `campaigns`, `ads`, `adgroups`, `keywords`,
+  `keywordbids`, and `bids` (510 unique strings across the six modules).
+  WSDL field paths, enum values, and flag names are kept verbatim; only
+  human-readable text is translated. These groups join `LOCALIZED_GROUPS`,
+  so their translation completeness is now enforced by `test_i18n.py`.
+
+**Localized — Targeting & creatives (#469):**
+
+- Russian help/docstrings for `strategies`, `bidmodifiers`, `smartadtargets`,
+  `vcards`, `feeds`, `dynamicads`, `audiencetargets`, `dynamicfeedadtargets`,
+  `retargeting`, `negativekeywordsharedsets`, `adextensions`, `adimages`,
+  `sitelinks`, `creatives`, `advideos`, and `turbopages` (247 unique strings
+  across the sixteen modules). WSDL field paths, enum values, and flag names
+  are kept verbatim; only human-readable text is translated. These groups
+  join `LOCALIZED_GROUPS`, so their translation completeness is now enforced
+  by `test_i18n.py`.
+
+**Localized — Account, clients, reporting (#470):**
+
+- Russian help/docstrings for `clients`, `agencyclients`, `reports`, `changes`,
+  `auth`, `leads`, `dictionaries`, `keywordsresearch`, `businesses`, and
+  `balance` (142 source strings across the ten modules). WSDL field paths,
+  enum values, and flag names are kept verbatim; only human-readable text is
+  translated.
+- First modules with localized **runtime messages**: `print_*` calls carrying a
+  human-readable literal (`auth` interactive prompts, the `agencyclients delete`
+  not-supported notice) are now wrapped in `t()` so they follow the active
+  locale. `print_error(str(e))` API-error passthroughs are unchanged. These
+  groups join `LOCALIZED_GROUPS`, enforcing both translation completeness and
+  the runtime-message wrapping invariant.
+
+**Localized — v4 Live services (#471), completing epic #466:**
+
+- Russian help/docstrings for `v4account`, `v4tags`, `v4forecast`,
+  `v4wordstat`, `v4events`, `v4adimage`, `v4goals`, `v4keywords`, and `v4meta`
+  (87 source strings across the nine modules). `v4finance` was already
+  localized as the reference module in #467.
+- With these groups, **all 42 CLI command groups are in `LOCALIZED_GROUPS`**:
+  the completeness invariant now covers the entire command tree, so every
+  English help/docstring string ships with a Russian translation under the
+  Russian default. The `v4 Live` epilog (single-sourced docs URL) stays
+  verbatim per the URL-registry rule. This closes the localization epic #466.
+
 ## 0.4.0
 
 Milestone release closing the 0.4.0 roadmap (#123): typed Yandex Direct

{direct_cli-0.4.0 → direct_cli-0.4.2}/CLAUDE.md

@@ -24,9 +24,9 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **Request flow:** `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex API → `output.py` (format/print).
 
-**Credentials priority (CLI):** CLI flags (`--token`, `--login`) > active profile from `direct auth login` > env vars (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > `.env` file > 1Password/Bitwarden refs. See `direct_cli/auth.py:600` (`get_credentials`) and README table for the full chain. `load_dotenv()` runs at `cli.py` import time.
+**Credentials priority (CLI):** explicit CLI flags (`--token`, `--login`, `--profile`) > base env/current working directory `.env` (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > active profile from `direct auth login` / `direct auth use` > 1Password/Bitwarden refs. Explicit `--profile` is isolated and does not fall back to base `.env` login. See `direct_cli/auth.py` (`get_credentials`) and README table for the full chain.
 
-**Credentials priority (tests):** **inverted** — env vars > active profile > skip. Tests must not silently hit production when a developer has an active `direct auth` profile, so env vars take precedence over the profile (see `tests/test_v4_live_contracts.py::_credentials`).
+**Credentials priority (tests):** env vars/current working directory `.env` > active profile > skip. Tests must not silently hit production when a developer has an active `direct auth` profile, so env vars take precedence over the profile (see `tests/test_v4_live_contracts.py::_credentials`).
 
 **Shared utilities** (`utils.py`): `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`, `COMMON_FIELDS` dict. All command modules import from here — don't duplicate.
 
@@ -106,7 +106,7 @@ Builds dist artifacts, runs twine checks, uploads to TestPyPI + PyPI. Does **not
 
 - **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.
 - **Integration** (`test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if absent.
-- **Credential resolution in tests:** env vars first, then active `direct auth` profile, then skip. This is **inverted** vs. CLI (where the profile wins) on purpose: a developer machine with an active profile must not silently hit production on a plain `pytest`.
+- **Credential resolution in tests:** env vars/current working directory `.env` first, then active `direct auth` profile, then skip. This matches the safe CLI default for base env vs. active profile: a developer machine with an active profile must not silently hit production on a plain `pytest`.
 
 ## Dangerous Commands — Never Auto-Test
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -106,6 +106,9 @@ Notes:
 - If the first non-interactive step includes `--client-secret`, the secret is remembered for the matching completion step.
 - If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`.
 - `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
+- After a successful interactive login, Direct CLI asks whether to save the
+  access token and login to the current working directory `.env`; non-interactive
+  login flows do not prompt.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -113,22 +116,23 @@ Credential resolution priority:
 | Priority | Source | Example |
 |----------|--------|---------|
 | 1 | Explicit CLI options | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Profile-specific env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Explicit profile credentials | `direct --profile agency1 campaigns get` |
+| 3 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Active profile credentials | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI automatically loads only the `.env` file from the current working
 directory, i.e. the directory where you run `direct`. It does not search for
-`.env` from the installed package or source-code location. If a profile is
-selected with `--profile` or `direct auth use --profile NAME`, Direct CLI does
-not fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile
-token with a login from the current working directory `.env`. For multi-account
-setups, prefer OAuth profiles or profile-specific env vars instead of base
-credentials.
+`.env` from the installed package or source-code location. Without an explicit
+`--profile`, base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from env or cwd
+`.env` win over the active OAuth profile. With explicit `--profile`, Direct CLI
+uses only that profile's OAuth/profile-env credentials and does not fall back to
+base `YANDEX_DIRECT_LOGIN`; this prevents mixing accounts. `direct auth status`
+without `--profile` reports the effective credential source; with `--profile` it
+reports that profile.
 
-> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+> **Tests follow the safe credential order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This prevents a developer machine with an active profile from silently hitting production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
 
 Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
@@ -208,6 +212,31 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Keyword Suggestions
+
+`get-suggestion` returns up to 20 related phrases for the seed phrases. Repeat
+`--keyword` for multiple seeds. The method consumes API points.
+
+```bash
+direct v4keywords get-suggestion --keyword холодильник --keyword камера
+direct v4keywords get-suggestion --keyword "buy laptop" --format table
+direct v4keywords get-suggestion --keyword холодильник --dry-run
+```
+
+### V4 Live Ad-Image Associations
+
+`AdImageAssociation` is exposed as two typed commands. `get` reads ad-to-image
+associations via an optional selection filter (an empty filter returns up to
+10000 associations). `set` attaches or detaches images: `--association AD_ID=HASH`
+attaches an image, `--association AD_ID` (no hash) detaches the current image
+(max 10000 associations per call).
+
+```bash
+direct v4adimage get --ad-ids 123,456 --status-moderate Yes --limit 20
+direct v4adimage get --campaign-ids 789 --format table
+direct v4adimage set --association 123=abc123hash --association 456 --dry-run
+```
+
 ### V4 Live Budget Forecasts
 
 Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
@@ -233,9 +262,15 @@ per-request token from `--master-token`, `--operation-num`, and
 Environment variables are
 `YANDEX_DIRECT_MASTER_TOKEN`, `YANDEX_DIRECT_FINANCE_LOGIN`,
 `YANDEX_DIRECT_FINANCE_TOKEN`, and `YANDEX_DIRECT_OPERATION_NUM`.
-`transfer-money` and `pay-campaigns` are dry-run-only in this release and
-always require `--dry-run`; `create-invoice` can be sent live when `--dry-run`
-is omitted. Dry-run output masks the financial token.
+`transfer-money`, `pay-campaigns`, and `pay-campaigns-by-card` are dry-run-only
+in this release and always require `--dry-run`; `create-invoice` can be sent
+live when `--dry-run` is omitted. Dry-run output masks the financial token.
+`pay-campaigns-by-card` has an undocumented request shape; its dry-run body
+mirrors the documented `pay-campaigns` shape as a best-effort preview.
+
+> ⚠ **Finance commands have not been tested against the live API.** Treat the
+> request shapes as best-effort and always verify with `--dry-run` before
+> sending anything that runs live (`create-invoice`).
 
 ```bash
 direct v4finance get-clients-units --logins client-login,other-client --format table
@@ -244,6 +279,7 @@ direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --currency
 direct v4finance check-payment --custom-transaction-id A123456789012345678901234567890B
 direct v4finance transfer-money --from-campaign-id 123 --to-campaign-id 456 --amount 100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
 direct v4finance pay-campaigns --campaign-ids 123,456 --amount 100.50 --contract-id CONTRACT_ID --pay-method Bank --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+direct v4finance pay-campaigns-by-card --campaign-ids 123,456 --amount 100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 128 --finance-login agency-login --dry-run
 ```
 
 ### V4 Live Shared Account
@@ -272,6 +308,20 @@ direct v4account account-management --action TransferMoney --from-account-id 132
 direct --sandbox v4account enable-shared-account --client-login client-login
 ```
 
+### V4 Live — Intentionally Omitted Methods
+
+Some v4 Live methods present in the API registry are intentionally **not**
+exposed as CLI commands:
+
+- `DeleteReport` / `DeleteOfflineReport` — disabled by Yandex (the official
+  docs list them under "Отключенные методы" / "Метод отключен. Используйте API
+  версии 5"). Use the v5 reports API instead.
+- `PingAPI`, `PingAPI_X`, `GetVersion`, `GetAvailableVersions` — service
+  diagnostics / version probes with no documented request shape; not useful as
+  user-facing CLI commands.
+- `PayCampaignsByCard` is exposed but **dry-run-only** (undocumented,
+  financially sensitive — see V4 Live Finance above).
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -1019,27 +1069,32 @@ direct --profile agency1 campaigns get
 - Если первый non-interactive шаг включает `--client-secret`, secret запоминается для последующего completion step.
 - Если profile уже хранит confidential OAuth client, `direct auth login --code CODE --profile NAME` использует сохраненные `client_id` и `client_secret`.
 - `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+- После успешного интерактивного входа Direct CLI спрашивает, сохранить ли
+  access token и login в `.env` текущей рабочей папки; non-interactive вход этот
+  вопрос не задаёт.
 
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
 |-----------|----------|--------|
 | 1 | Явные CLI-опции | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Профильные env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Явно выбранный profile | `direct --profile agency1 campaigns get` |
+| 3 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Активный profile | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI автоматически читает только `.env` из текущей рабочей папки, то есть
 из папки, где запущена команда `direct`. Он не ищет `.env` от папки
-установленного пакета или исходного кода. Если профиль выбран через `--profile`
-или `direct auth use --profile NAME`, Direct CLI не подставляет base
-`YANDEX_DIRECT_LOGIN`; это защищает от смешивания токена из профиля с логином из
-`.env` текущей рабочей папки. Для нескольких аккаунтов используйте OAuth
-profiles или профильные env vars, а не базовые credentials.
-
-> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+установленного пакета или исходного кода. Без явного `--profile` базовые
+`YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения или cwd `.env`
+побеждают активный OAuth profile. С явным `--profile` Direct CLI использует
+только OAuth/profile-env credentials этого профиля и не подставляет base
+`YANDEX_DIRECT_LOGIN`; это защищает от смешивания аккаунтов. `direct auth status`
+без `--profile` показывает реально выбранный источник credentials, а с
+`--profile` показывает этот профиль.
+
+> **Тесты используют безопасный порядок credentials.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это защищает от случайного обращения к production API на машине разработчика с активным profile. Контракт зафиксирован в `CLAUDE.md`.
 
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с

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

@@ -63,6 +63,9 @@ Notes:
 - If the first non-interactive step includes `--client-secret`, the secret is remembered for the matching completion step.
 - If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`.
 - `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
+- After a successful interactive login, Direct CLI asks whether to save the
+  access token and login to the current working directory `.env`; non-interactive
+  login flows do not prompt.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -70,22 +73,23 @@ Credential resolution priority:
 | Priority | Source | Example |
 |----------|--------|---------|
 | 1 | Explicit CLI options | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Profile-specific env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Explicit profile credentials | `direct --profile agency1 campaigns get` |
+| 3 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Active profile credentials | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI automatically loads only the `.env` file from the current working
 directory, i.e. the directory where you run `direct`. It does not search for
-`.env` from the installed package or source-code location. If a profile is
-selected with `--profile` or `direct auth use --profile NAME`, Direct CLI does
-not fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile
-token with a login from the current working directory `.env`. For multi-account
-setups, prefer OAuth profiles or profile-specific env vars instead of base
-credentials.
+`.env` from the installed package or source-code location. Without an explicit
+`--profile`, base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from env or cwd
+`.env` win over the active OAuth profile. With explicit `--profile`, Direct CLI
+uses only that profile's OAuth/profile-env credentials and does not fall back to
+base `YANDEX_DIRECT_LOGIN`; this prevents mixing accounts. `direct auth status`
+without `--profile` reports the effective credential source; with `--profile` it
+reports that profile.
 
-> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+> **Tests follow the safe credential order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This prevents a developer machine with an active profile from silently hitting production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
 
 Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
@@ -165,6 +169,31 @@ direct v4wordstat get-report --report-id 123 --format table
 direct v4wordstat delete-report --report-id 123
 ```
 
+### V4 Live Keyword Suggestions
+
+`get-suggestion` returns up to 20 related phrases for the seed phrases. Repeat
+`--keyword` for multiple seeds. The method consumes API points.
+
+```bash
+direct v4keywords get-suggestion --keyword холодильник --keyword камера
+direct v4keywords get-suggestion --keyword "buy laptop" --format table
+direct v4keywords get-suggestion --keyword холодильник --dry-run
+```
+
+### V4 Live Ad-Image Associations
+
+`AdImageAssociation` is exposed as two typed commands. `get` reads ad-to-image
+associations via an optional selection filter (an empty filter returns up to
+10000 associations). `set` attaches or detaches images: `--association AD_ID=HASH`
+attaches an image, `--association AD_ID` (no hash) detaches the current image
+(max 10000 associations per call).
+
+```bash
+direct v4adimage get --ad-ids 123,456 --status-moderate Yes --limit 20
+direct v4adimage get --campaign-ids 789 --format table
+direct v4adimage set --association 123=abc123hash --association 456 --dry-run
+```
+
 ### V4 Live Budget Forecasts
 
 Budget forecasts are asynchronous. Direct CLI makes exactly one API call per
@@ -190,9 +219,15 @@ per-request token from `--master-token`, `--operation-num`, and
 Environment variables are
 `YANDEX_DIRECT_MASTER_TOKEN`, `YANDEX_DIRECT_FINANCE_LOGIN`,
 `YANDEX_DIRECT_FINANCE_TOKEN`, and `YANDEX_DIRECT_OPERATION_NUM`.
-`transfer-money` and `pay-campaigns` are dry-run-only in this release and
-always require `--dry-run`; `create-invoice` can be sent live when `--dry-run`
-is omitted. Dry-run output masks the financial token.
+`transfer-money`, `pay-campaigns`, and `pay-campaigns-by-card` are dry-run-only
+in this release and always require `--dry-run`; `create-invoice` can be sent
+live when `--dry-run` is omitted. Dry-run output masks the financial token.
+`pay-campaigns-by-card` has an undocumented request shape; its dry-run body
+mirrors the documented `pay-campaigns` shape as a best-effort preview.
+
+> ⚠ **Finance commands have not been tested against the live API.** Treat the
+> request shapes as best-effort and always verify with `--dry-run` before
+> sending anything that runs live (`create-invoice`).
 
 ```bash
 direct v4finance get-clients-units --logins client-login,other-client --format table
@@ -201,6 +236,7 @@ direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --currency
 direct v4finance check-payment --custom-transaction-id A123456789012345678901234567890B
 direct v4finance transfer-money --from-campaign-id 123 --to-campaign-id 456 --amount 100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
 direct v4finance pay-campaigns --campaign-ids 123,456 --amount 100.50 --contract-id CONTRACT_ID --pay-method Bank --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+direct v4finance pay-campaigns-by-card --campaign-ids 123,456 --amount 100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 128 --finance-login agency-login --dry-run
 ```
 
 ### V4 Live Shared Account
@@ -229,6 +265,20 @@ direct v4account account-management --action TransferMoney --from-account-id 132
 direct --sandbox v4account enable-shared-account --client-login client-login
 ```
 
+### V4 Live — Intentionally Omitted Methods
+
+Some v4 Live methods present in the API registry are intentionally **not**
+exposed as CLI commands:
+
+- `DeleteReport` / `DeleteOfflineReport` — disabled by Yandex (the official
+  docs list them under "Отключенные методы" / "Метод отключен. Используйте API
+  версии 5"). Use the v5 reports API instead.
+- `PingAPI`, `PingAPI_X`, `GetVersion`, `GetAvailableVersions` — service
+  diagnostics / version probes with no documented request shape; not useful as
+  user-facing CLI commands.
+- `PayCampaignsByCard` is exposed but **dry-run-only** (undocumented,
+  financially sensitive — see V4 Live Finance above).
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -976,27 +1026,32 @@ direct --profile agency1 campaigns get
 - Если первый non-interactive шаг включает `--client-secret`, secret запоминается для последующего completion step.
 - Если profile уже хранит confidential OAuth client, `direct auth login --code CODE --profile NAME` использует сохраненные `client_id` и `client_secret`.
 - `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+- После успешного интерактивного входа Direct CLI спрашивает, сохранить ли
+  access token и login в `.env` текущей рабочей папки; non-interactive вход этот
+  вопрос не задаёт.
 
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
 |-----------|----------|--------|
 | 1 | Явные CLI-опции | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Профильные env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Явно выбранный profile | `direct --profile agency1 campaigns get` |
+| 3 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Активный profile | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI автоматически читает только `.env` из текущей рабочей папки, то есть
 из папки, где запущена команда `direct`. Он не ищет `.env` от папки
-установленного пакета или исходного кода. Если профиль выбран через `--profile`
-или `direct auth use --profile NAME`, Direct CLI не подставляет base
-`YANDEX_DIRECT_LOGIN`; это защищает от смешивания токена из профиля с логином из
-`.env` текущей рабочей папки. Для нескольких аккаунтов используйте OAuth
-profiles или профильные env vars, а не базовые credentials.
-
-> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+установленного пакета или исходного кода. Без явного `--profile` базовые
+`YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения или cwd `.env`
+побеждают активный OAuth profile. С явным `--profile` Direct CLI использует
+только OAuth/profile-env credentials этого профиля и не подставляет base
+`YANDEX_DIRECT_LOGIN`; это защищает от смешивания аккаунтов. `direct auth status`
+без `--profile` показывает реально выбранный источник credentials, а с
+`--profile` показывает этот профиль.
+
+> **Тесты используют безопасный порядок credentials.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это защищает от случайного обращения к production API на машине разработчика с активным profile. Контракт зафиксирован в `CLAUDE.md`.
 
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с