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

{direct_cli-0.3.15 → direct_cli-0.4.0}/.github/workflows/claude.yml

@@ -46,5 +46,5 @@ jobs:
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-          claude_args: "--model claude-opus-4-7"
+          claude_args: "--model claude-opus-4-8"
 

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

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.4.0
+
+Milestone release closing the 0.4.0 roadmap (#123): typed Yandex Direct
+API **v4 Live** CLI support and completion of the post-0.3.0 write-command
+coverage gates. All public v4 input stays typed and canonical — no `--json`
+passthrough — and mirrors `dg-v4/live/*` wire shapes 1:1.
+
+**Added — typed v4 Live CLI:**
+
+- v4 Live command foundation with typed Click groups and a `--dry-run`
+  seam that prints the `{method, param}` body before token/locale
+  enrichment (#124, closes #111 — typed CLI, not raw JSON passthrough).
+- `v4finance` and `v4account` typed finance and shared-account commands
+  (#125).
+- `v4goals`, `v4events`, `v4wordstat`, and `v4forecast` typed commands
+  (#126).
+- `v4events get-events-log` and `v4forecast create-new-forecast` now expose
+  every documented input field (#456).
+- Russian-default CLI help with English opt-in, starting with `v4finance`
+  (#458).
+
+**Changed — write-command coverage gates:**
+
+- Extended the WSDL schema gate to mutating operations; `keywordbids.set`
+  is now enum-validated against its WSDL `*FieldEnum` (#118).
+- Per-method `WRITE_SANDBOX` integration coverage completed — zero
+  unexplained `NOT_COVERED` commands in `direct_cli/smoke_matrix.py`
+  (#122).
+- Closed the remaining mutating `DRY_RUN_PAYLOAD_EXCLUSIONS`; every
+  declared WSDL operation now has a `PAYLOAD_CASES` fixture or a
+  documented technical exclusion (#127).
+
+**Tests / tooling:**
+
+- Offline VCR cassettes for all v5 read-only commands (#455).
+- v4 Live read cassettes and a fix for an unbounded retry-loop (#457,
+  closes #454).
+- Docs/wire-shape scanner with the 2026-05-29 sweep (#451).
+
+`strict_parity_ok`, `live_model_parity_ok`, and `schema_parity_ok` all
+report `true` in `scripts/build_api_coverage_report.py`.
+
+## 0.3.16
+
+**BREAKING CHANGES (regression fix — reverts 0.3.15 wire-shape changes):**
+
+- `direct v4finance transfer-money` now requires `--currency` again and
+  re-emits `Currency` on every `FromCampaigns` / `ToCampaigns` item.
+  The 0.3.15 removal verified against `dg-v4/reference/TransferMoney`
+  (legacy v4); the actual Live 4 docs at
+  `dg-v4/live/TransferMoney` define `PayCampElement` with
+  `CampaignID`, `Sum`, and `Currency`, and explicitly mark `Currency` as
+  obligatory in the Live 4 changelog. The CLI now matches the live
+  docs 1:1. See audit comment on #125 for the reproducible diff.
+- `direct v4finance pay-campaigns` now requires `--currency` again and
+  re-emits `Currency` on every `Payments[]` item. Same root cause:
+  `dg-v4/reference/PayCampaigns` (legacy) lacks `Currency`,
+  `dg-v4/live/PayCampaigns` (Live 4) requires it.
+- `direct v4finance pay-campaigns` accepts `--pay-method Overdraft`
+  again. The Live 4 changelog explicitly adds `Overdraft` for direct
+  advertisers (paired with `Bank` for agencies). Only `Bank` keeps the
+  `--contract-id` requirement.
+- `direct v4finance create-invoice` now requires `--currency` again and
+  re-emits `Currency` on every `Payments[]` item, mirroring
+  `dg-v4/live/CreateInvoice`.
+
+This release reverts the wire-shape changes shipped by PRs #441, #442,
+#443 (which closed #432, #433, #434). The CLI lives in the `v4finance`
+Live group and must mirror `dg-v4/live/*`, not `dg-v4/reference/*`.
+
 ## 0.3.15
 
 **BREAKING CHANGES:**

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.15
+Version: 0.4.0
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -154,6 +154,12 @@ direct balance --logins client-login --dry-run
 | `--login` | Direct client login |
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
+| `--locale` | Help/message language: `ru` (default) or `en`. Also set via `YANDEX_DIRECT_CLI_LOCALE`. Command and flag names are unchanged. |
+
+Help text is shown in Russian by default. Switch to English with
+`direct --locale en ...` or `export YANDEX_DIRECT_CLI_LOCALE=en`. For example,
+`direct v4finance --help` shows the financial master-token setup steps using
+the locale-appropriate Yandex Direct UI labels.
 
 ### V4 Live Goals
 
@@ -186,6 +192,7 @@ direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
 ```bash
 direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00
 direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00 --currency RUB --limit 100 --offset 0 --format table
+direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00 --last-event-only Yes --with-text-description Yes --filter-campaign-ids 123,456 --filter-event-type MoneyOut,MoneyIn
 ```
 
 ### V4 Live Wordstat Reports
@@ -209,6 +216,7 @@ the forecast is ready.
 
 ```bash
 direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast create --phrases "buy laptop" --geo-ids 213 --auction-bids Yes --common-minus-words "used,broken"
 direct v4forecast list --format table
 direct v4forecast get --forecast-id 123 --format table
 direct v4forecast delete --forecast-id 123
@@ -232,10 +240,10 @@ is omitted. Dry-run output masks the financial token.
 ```bash
 direct v4finance get-clients-units --logins client-login,other-client --format table
 direct v4finance get-credit-limits --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login
-direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
+direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --currency RUB --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
 direct v4finance check-payment --custom-transaction-id A123456789012345678901234567890B
-direct v4finance transfer-money --from-campaign-id 123 --to-campaign-id 456 --amount 100.50 --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 --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+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
 ```
 
 ### V4 Live Shared Account

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

@@ -111,6 +111,12 @@ direct balance --logins client-login --dry-run
 | `--login` | Direct client login |
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
+| `--locale` | Help/message language: `ru` (default) or `en`. Also set via `YANDEX_DIRECT_CLI_LOCALE`. Command and flag names are unchanged. |
+
+Help text is shown in Russian by default. Switch to English with
+`direct --locale en ...` or `export YANDEX_DIRECT_CLI_LOCALE=en`. For example,
+`direct v4finance --help` shows the financial master-token setup steps using
+the locale-appropriate Yandex Direct UI labels.
 
 ### V4 Live Goals
 
@@ -143,6 +149,7 @@ direct v4tags update-banners --banner-ids 2571700 --clear-tags --dry-run
 ```bash
 direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00
 direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00 --currency RUB --limit 100 --offset 0 --format table
+direct v4events get-events-log --from 2026-04-14T00:00:00 --to 2026-04-15T00:00:00 --last-event-only Yes --with-text-description Yes --filter-campaign-ids 123,456 --filter-event-type MoneyOut,MoneyIn
 ```
 
 ### V4 Live Wordstat Reports
@@ -166,6 +173,7 @@ the forecast is ready.
 
 ```bash
 direct v4forecast create --phrases "buy laptop,buy desktop" --geo-ids 213 --currency RUB
+direct v4forecast create --phrases "buy laptop" --geo-ids 213 --auction-bids Yes --common-minus-words "used,broken"
 direct v4forecast list --format table
 direct v4forecast get --forecast-id 123 --format table
 direct v4forecast delete --forecast-id 123
@@ -189,10 +197,10 @@ is omitted. Dry-run output masks the financial token.
 ```bash
 direct v4finance get-clients-units --logins client-login,other-client --format table
 direct v4finance get-credit-limits --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login
-direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
+direct v4finance create-invoice --payment 123=100.50 --payment 456=25 --currency RUB --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
 direct v4finance check-payment --custom-transaction-id A123456789012345678901234567890B
-direct v4finance transfer-money --from-campaign-id 123 --to-campaign-id 456 --amount 100.50 --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 --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+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
 ```
 
 ### V4 Live Shared Account

{direct_cli-0.3.15 → direct_cli-0.4.0}/direct_cli/_vendor/tapi_yandex_direct/v4/adapter.py

@@ -176,9 +176,15 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
                 code = 0
 
         if code in (54, 55) and api_params.get("retry_if_exceeded_limit", True):
-            logger.warning("v4 Live limit exceeded (code=%s), retry in 10s", code)
-            time.sleep(10)
-            return True
+            # Bound the limit-exceeded retries with the same attempt budget as
+            # the server-error branch below.  Without this guard the loop is
+            # infinite (sleep 10s, retry, forever) whenever the API keeps
+            # returning code 54/55 — which hangs the caller indefinitely.
+            if repeat_number < api_params.get("retries_if_server_error", 5):
+                logger.warning("v4 Live limit exceeded (code=%s), retry in 10s", code)
+                time.sleep(10)
+                return True
+            return False
 
         if code in (52, 1000, 1001, 1002) or response.status_code == 500:
             if repeat_number < api_params.get("retries_if_server_error", 5):

{direct_cli-0.3.15 → direct_cli-0.4.0}/direct_cli/cli.py

@@ -8,6 +8,11 @@ from click.core import ParameterSource
 
 from . import __version__
 from .auth import get_active_profile, get_credentials, load_env_file
+from .i18n import (
+    LOCALE_ENV_VAR,
+    resolve_locale,
+    t,
+)
 from .utils import get_docs_url
 
 from .commands.campaigns import campaigns
@@ -155,6 +160,21 @@ class DirectCliGroup(_NoSuchOptionHintMixin, click.Group):
 
     command_class = DirectCliCommand
 
+    def format_epilog(self, ctx, formatter):
+        """Render a locale-aware epilog when the group opts into i18n.
+
+        A group sets ``localized_epilog_key`` (a key in ``i18n.CATALOG``) and,
+        optionally, ``localized_epilog_suffix`` (an already-built tail appended
+        verbatim so single-sourced text such as ``V4_EPILOG`` is not
+        duplicated). Groups without the attribute keep their static epilog.
+        """
+        key = getattr(self, "localized_epilog_key", None)
+        if key:
+            text = t(key, resolve_locale(ctx))
+            suffix = getattr(self, "localized_epilog_suffix", None)
+            self.epilog = f"{text}\n\n{suffix}" if suffix else text
+        super().format_epilog(ctx, formatter)
+
 
 def _apply_directcli_classes(command: click.Command) -> None:
     """Recursively retype *command* (and subcommands) so every node in the
@@ -182,6 +202,12 @@ def _apply_directcli_classes(command: click.Command) -> None:
 @click.option("--login", envvar="YANDEX_DIRECT_LOGIN", help="Client login")
 @click.option("--profile", help="Credential profile name")
 @click.option("--sandbox", is_flag=True, help="Use sandbox API")
+@click.option(
+    "--locale",
+    envvar=LOCALE_ENV_VAR,
+    default=None,
+    help="Language for help and messages (ru or en; default: ru)",
+)
 @click.option(
     "--op-token-ref",
     envvar="YANDEX_DIRECT_OP_TOKEN_REF",
@@ -209,6 +235,7 @@ def cli(
     login,
     profile,
     sandbox,
+    locale,
     op_token_ref,
     op_login_ref,
     bw_token_ref,
@@ -218,6 +245,7 @@ def cli(
     ctx.ensure_object(dict)
     ctx.obj["sandbox"] = sandbox
     ctx.obj["profile"] = profile
+    ctx.obj["locale"] = locale
     active_profile = None
     if ctx.invoked_subcommand != "auth":
         active_profile = get_active_profile()

direct_cli-0.4.0/direct_cli/commands/v4events.py

@@ -0,0 +1,232 @@
+"""Yandex Direct v4 Live events commands."""
+
+import re
+from datetime import datetime
+from typing import Optional
+
+import click
+
+from ..api import create_v4_client
+from ..output import format_output, print_error
+from ..utils import parse_csv_strings, parse_ids
+from ..v4 import build_v4_body, call_v4
+from ..v4_contracts import v4_method_contract
+from .v4shells import V4_EPILOG
+
+V4_DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+V4_DATETIME_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}")
+
+# Documented GetEventsLogFilter.EventType enum (dg-v4/live/GetEventsLog).
+EVENT_TYPES = [
+    "BannerModerated",
+    "CampaignFinished",
+    "LowCTR",
+    "MoneyOut",
+    "MoneyWarning",
+    "MoneyIn",
+    "PausedByDayBudget",
+    "WarnMinPrice",
+    "WarnPlace",
+]
+
+
+def _events_log_filter(
+    campaign_ids: Optional[str],
+    banner_ids: Optional[str],
+    phrase_ids: Optional[str],
+    account_ids: Optional[str],
+    event_type: Optional[str],
+) -> Optional[dict]:
+    """Build the GetEventsLogFilter object; None when no filter is provided."""
+    filter_obj: dict = {}
+    for option_name, raw, key in (
+        ("--filter-campaign-ids", campaign_ids, "CampaignIDS"),
+        ("--filter-banner-ids", banner_ids, "BannerIDS"),
+        ("--filter-phrase-ids", phrase_ids, "PhraseIDS"),
+        ("--filter-account-ids", account_ids, "AccountIDS"),
+    ):
+        if not raw:
+            continue
+        try:
+            parsed = parse_ids(raw)
+        except ValueError as exc:
+            raise click.UsageError(f"{option_name}: {exc}") from exc
+        if parsed:
+            filter_obj[key] = parsed
+    if event_type:
+        types = parse_csv_strings(event_type)
+        if types:
+            unknown = [value for value in types if value not in EVENT_TYPES]
+            if unknown:
+                raise click.UsageError(
+                    "--filter-event-type has unknown values: "
+                    f"{', '.join(unknown)}. Valid values: {', '.join(EVENT_TYPES)}"
+                )
+            filter_obj["EventType"] = types
+    return filter_obj or None
+
+
+def _parse_v4_datetime(value: str, option_name: str) -> datetime:
+    """Parse a strict v4 Live CLI datetime token."""
+    if not V4_DATETIME_RE.fullmatch(value):
+        raise click.UsageError(
+            f"Invalid {option_name}: {value}. Expected YYYY-MM-DDTHH:MM:SS"
+        )
+    try:
+        return datetime.strptime(value, V4_DATETIME_FORMAT)
+    except ValueError:
+        raise click.UsageError(
+            f"Invalid {option_name}: {value}. Expected YYYY-MM-DDTHH:MM:SS"
+        )
+
+
+def _events_log_param(
+    timestamp_from: str,
+    timestamp_to: str,
+    currency: str,
+    limit: Optional[int],
+    offset: Optional[int],
+    last_event_only: Optional[str] = None,
+    with_text_description: Optional[str] = None,
+    logins: Optional[str] = None,
+    campaign_ids: Optional[str] = None,
+    banner_ids: Optional[str] = None,
+    phrase_ids: Optional[str] = None,
+    account_ids: Optional[str] = None,
+    event_type: Optional[str] = None,
+) -> dict:
+    """Build the v4 Live GetEventsLog parameter."""
+    from_dt = _parse_v4_datetime(timestamp_from, "--from")
+    to_dt = _parse_v4_datetime(timestamp_to, "--to")
+    if from_dt > to_dt:
+        raise click.UsageError("--from must be earlier than or equal to --to")
+
+    param = {
+        "TimestampFrom": timestamp_from,
+        "TimestampTo": timestamp_to,
+        "Currency": currency,
+    }
+    if last_event_only:
+        param["LastEventOnly"] = last_event_only
+    if with_text_description:
+        param["WithTextDescription"] = with_text_description
+    if logins:
+        login_list = parse_csv_strings(logins)
+        if login_list:
+            param["Logins"] = login_list
+    filter_obj = _events_log_filter(
+        campaign_ids, banner_ids, phrase_ids, account_ids, event_type
+    )
+    if filter_obj is not None:
+        param["Filter"] = filter_obj
+    if limit is not None:
+        param["Limit"] = limit
+    if offset is not None:
+        param["Offset"] = offset
+    return param
+
+
+@click.group(epilog=V4_EPILOG)
+def v4events():
+    """Yandex Direct v4 Live events commands."""
+
+
+@v4_method_contract("GetEventsLog")
+@v4events.command(name="get-events-log")
+@click.option(
+    "--from",
+    "timestamp_from",
+    required=True,
+    help="Start timestamp in YYYY-MM-DDTHH:MM:SS format",
+)
+@click.option(
+    "--to",
+    "timestamp_to",
+    required=True,
+    help="End timestamp in YYYY-MM-DDTHH:MM:SS format",
+)
+@click.option(
+    "--last-event-only",
+    type=click.Choice(["Yes", "No"]),
+    help="Return only the latest record per event type — Yes/No",
+)
+@click.option(
+    "--with-text-description",
+    type=click.Choice(["Yes", "No"]),
+    help="Include event text descriptions in the response — Yes/No",
+)
+@click.option("--currency", default="RUB", show_default=True, help="Currency")
+@click.option("--logins", help="Comma-separated client logins")
+@click.option("--filter-campaign-ids", help="Filter: comma-separated campaign IDs")
+@click.option("--filter-banner-ids", help="Filter: comma-separated banner IDs")
+@click.option("--filter-phrase-ids", help="Filter: comma-separated phrase IDs")
+@click.option("--filter-account-ids", help="Filter: comma-separated account IDs")
+@click.option(
+    "--filter-event-type",
+    help="Filter: comma-separated event types (" + ", ".join(EVENT_TYPES) + ")",
+)
+@click.option("--limit", type=click.IntRange(min=0), help="Result limit")
+@click.option("--offset", type=click.IntRange(min=0), help="Result offset")
+@click.option(
+    "--format",
+    "output_format",
+    default="json",
+    type=click.Choice(["json", "table", "csv", "tsv"]),
+    help="Output format",
+)
+@click.option("--output", help="Output file")
+@click.option("--dry-run", is_flag=True, help="Show request without sending")
+@click.pass_context
+def get_events_log(
+    ctx,
+    timestamp_from,
+    timestamp_to,
+    last_event_only,
+    with_text_description,
+    currency,
+    logins,
+    filter_campaign_ids,
+    filter_banner_ids,
+    filter_phrase_ids,
+    filter_account_ids,
+    filter_event_type,
+    limit,
+    offset,
+    output_format,
+    output,
+    dry_run,
+):
+    """Get v4 Live events log entries."""
+    param = _events_log_param(
+        timestamp_from,
+        timestamp_to,
+        currency,
+        limit,
+        offset,
+        last_event_only=last_event_only,
+        with_text_description=with_text_description,
+        logins=logins,
+        campaign_ids=filter_campaign_ids,
+        banner_ids=filter_banner_ids,
+        phrase_ids=filter_phrase_ids,
+        account_ids=filter_account_ids,
+        event_type=filter_event_type,
+    )
+    if dry_run:
+        format_output(build_v4_body("GetEventsLog", param), "json", None)
+        return
+
+    try:
+        client = create_v4_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            profile=ctx.obj.get("profile"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+        data = call_v4(client, "GetEventsLog", param)
+        format_output(data, output_format, output)
+    except click.ClickException:
+        raise
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()