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

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

@@ -1,5 +1,48 @@
 # 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).

{direct_cli-0.4.1 → 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.1 → direct_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.4.1
+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
@@ -1065,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.1 → 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
@@ -1022,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` завершается ошибкой с

direct_cli-0.4.2/direct_cli/_autotargeting.py

@@ -0,0 +1,206 @@
+"""Shared autotargeting CLI helpers for ad groups and keywords.
+
+``adgroups`` (DynamicTextAdGroup/DynamicTextFeedAdGroup) and ``keywords`` both
+parse the same AutotargetingCategories / AutotargetingSettings CLI surface.
+The helpers used to be duplicated in each command module and had drifted
+(category-token normalization, and which legacy flags conflict with the typed
+``AutotargetingSettings`` flags). This module is the single source of truth.
+
+The legacy-mix guard models an **intentional** asymmetry explicitly via
+``legacy_candidates``: ``adgroups`` treats only ``--autotargeting-category`` as
+legacy (it has no ``--autotargeting-brand-option`` flag at all), while
+``keywords`` treats both ``--autotargeting-category`` and
+``--autotargeting-brand-option`` as legacy.
+
+Token normalization is unified on :func:`normalize_enum_token` for both
+categories and brand options. For categories this is behavior-preserving (the
+constants are single words with no ``_``, so ``-``->``_`` only ever touches
+already-invalid tokens). For brand options it is a deliberate *loosening*: the
+constants contain underscores (``WITHOUT_BRANDS``), so the hyphenated spelling
+(``WITHOUT-BRANDS``) — rejected by the old flat ``.strip().upper()`` — is now
+accepted, making every autotargeting enum normalize identically.
+"""
+
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import click
+
+from .i18n import t
+
+AUTOTARGETING_CATEGORIES = (
+    "EXACT",
+    "ALTERNATIVE",
+    "COMPETITOR",
+    "BROADER",
+    "ACCESSORY",
+)
+AUTOTARGETING_BRAND_OPTIONS = (
+    "WITHOUT_BRANDS",
+    "WITH_ADVERTISER_BRAND",
+)
+
+
+def normalize_enum_token(value: str) -> str:
+    """Normalize enum-like CLI tokens to Yandex Direct uppercase constants."""
+    return value.strip().upper().replace("-", "_")
+
+
+def parse_autotargeting_categories(
+    raw_values: Tuple[str, ...],
+) -> Optional[List[Dict[str, str]]]:
+    """Parse AutotargetingCategories CLI items (CATEGORY=YES|NO)."""
+    if not raw_values:
+        return None
+
+    allowed_categories = ", ".join(AUTOTARGETING_CATEGORIES)
+    items: List[Dict[str, str]] = []
+    for raw_value in raw_values:
+        category_raw, separator, value_raw = raw_value.strip().partition("=")
+        if not separator:
+            raise click.UsageError(
+                t(
+                    "--autotargeting-category expects CATEGORY=YES|NO "
+                    "(for example EXACT=YES)"
+                )
+            )
+
+        category = normalize_enum_token(category_raw)
+        value = normalize_enum_token(value_raw)
+        if category not in AUTOTARGETING_CATEGORIES:
+            raise click.UsageError(
+                t(
+                    "Invalid --autotargeting-category category {category_raw!r}; "
+                    "allowed: {allowed_categories}"
+                ).format(
+                    category_raw=category_raw, allowed_categories=allowed_categories
+                )
+            )
+        if value not in {"YES", "NO"}:
+            raise click.UsageError(
+                t(
+                    "Invalid --autotargeting-category value {value_raw!r}; "
+                    "expected YES or NO"
+                ).format(value_raw=value_raw)
+            )
+        items.append({"Category": category, "Value": value})
+
+    return items
+
+
+def parse_autotargeting_brand_options(
+    raw_values: Tuple[str, ...],
+) -> Optional[List[Dict[str, str]]]:
+    """Parse AutotargetingSettings BrandOptions CLI items (OPTION=YES|NO)."""
+    if not raw_values:
+        return None
+
+    allowed_options = ", ".join(AUTOTARGETING_BRAND_OPTIONS)
+    items: List[Dict[str, str]] = []
+    for raw_value in raw_values:
+        option_raw, separator, value_raw = raw_value.strip().partition("=")
+        if not separator:
+            raise click.UsageError(
+                t(
+                    "--autotargeting-brand-option expects OPTION=YES|NO "
+                    "(for example WITHOUT_BRANDS=YES)"
+                )
+            )
+
+        option = normalize_enum_token(option_raw)
+        value = normalize_enum_token(value_raw)
+        if option not in AUTOTARGETING_BRAND_OPTIONS:
+            raise click.UsageError(
+                t(
+                    "Invalid --autotargeting-brand-option option {option_raw!r}; "
+                    "allowed: {allowed_options}"
+                ).format(option_raw=option_raw, allowed_options=allowed_options)
+            )
+        if value not in {"YES", "NO"}:
+            raise click.UsageError(
+                t(
+                    "Invalid --autotargeting-brand-option value {value_raw!r}; "
+                    "expected YES or NO"
+                ).format(value_raw=value_raw)
+            )
+
+        items.append({"Option": option, "Value": value})
+
+    return items
+
+
+def build_autotargeting_settings(
+    *,
+    exact: Optional[str],
+    narrow: Optional[str],
+    alternative: Optional[str],
+    accessory: Optional[str],
+    broader: Optional[str],
+    without_brands: Optional[str],
+    with_advertiser_brand: Optional[str],
+    with_competitors_brand: Optional[str],
+) -> Optional[Dict[str, Dict[str, str]]]:
+    """Build AutotargetingSettings (Categories + BrandOptions) from typed flags."""
+    categories: Dict[str, str] = {}
+    for field_name, value in (
+        ("Exact", exact),
+        ("Narrow", narrow),
+        ("Alternative", alternative),
+        ("Accessory", accessory),
+        ("Broader", broader),
+    ):
+        if value is not None:
+            categories[field_name] = value.upper()
+
+    brand_options: Dict[str, str] = {}
+    for field_name, value in (
+        ("WithoutBrands", without_brands),
+        ("WithAdvertiserBrand", with_advertiser_brand),
+        ("WithCompetitorsBrand", with_competitors_brand),
+    ):
+        if value is not None:
+            brand_options[field_name] = value.upper()
+
+    settings: Dict[str, Dict[str, str]] = {}
+    if categories:
+        settings["Categories"] = categories
+    if brand_options:
+        settings["BrandOptions"] = brand_options
+
+    return settings or None
+
+
+def reject_legacy_autotargeting_mix(
+    settings: Optional[Dict[str, Dict[str, str]]],
+    *,
+    legacy_candidates: Sequence[Tuple[str, bool]],
+) -> None:
+    """Reject typed AutotargetingSettings combined with legacy autotargeting flags.
+
+    ``legacy_candidates`` is an ordered ``(flag_name, supplied)`` sequence that
+    declares which flags count as legacy for the calling resource. Ad groups
+    declare only ``--autotargeting-category``; keywords declare both
+    ``--autotargeting-category`` and ``--autotargeting-brand-option``. The
+    error message preserves both original source strings so every translation
+    catalog entry stays referenced and the rendered output is unchanged.
+    """
+    if settings is None:
+        return
+
+    declared = [flag for flag, _ in legacy_candidates]
+    supplied = [flag for flag, present in legacy_candidates if present]
+    if not supplied:
+        return
+
+    if declared == ["--autotargeting-category"]:
+        raise click.UsageError(
+            t(
+                "AutotargetingSettings flags cannot be combined with legacy "
+                "--autotargeting-category flags."
+            )
+        )
+
+    raise click.UsageError(
+        t(
+            "AutotargetingSettings flags cannot be combined with legacy {arg0} flags."
+        ).format(arg0=", ".join(supplied))
+    )