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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -118,6 +118,18 @@ Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
 `use direct instead of direct-cli`.
 
+### Quick Start: Check Balance
+
+Yandex removed the legacy v4 `GetBalance` method. Direct CLI uses the v4 Live
+`AccountManagement` method with `Action=Get` for `direct balance`, returning
+money fields such as `Amount`, `AmountAvailableForTransfer`, and `Currency`.
+
+```bash
+direct balance
+direct balance --logins client-login,other-client --format table
+direct balance --logins client-login --dry-run
+```
+
 ### Global Options
 
 | Option | Description |
@@ -127,6 +139,14 @@ Invoking the deprecated `direct-cli` entrypoint exits with
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
 
+### V4 Live Goals
+
+```bash
+direct v4goals get-stat-goals --campaign-ids 123,456
+direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
+direct v4goals get-stat-goals --campaign-ids 123 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.

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

@@ -79,6 +79,18 @@ Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
 `use direct instead of direct-cli`.
 
+### Quick Start: Check Balance
+
+Yandex removed the legacy v4 `GetBalance` method. Direct CLI uses the v4 Live
+`AccountManagement` method with `Action=Get` for `direct balance`, returning
+money fields such as `Amount`, `AmountAvailableForTransfer`, and `Currency`.
+
+```bash
+direct balance
+direct balance --logins client-login,other-client --format table
+direct balance --logins client-login --dry-run
+```
+
 ### Global Options
 
 | Option | Description |
@@ -88,6 +100,14 @@ Invoking the deprecated `direct-cli` entrypoint exits with
 | `--profile` | Credential profile name |
 | `--sandbox` | Use sandbox API |
 
+### V4 Live Goals
+
+```bash
+direct v4goals get-stat-goals --campaign-ids 123,456
+direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
+direct v4goals get-stat-goals --campaign-ids 123 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.

{direct_cli-0.3.0 → direct_cli-0.3.1}/direct_cli/_smoke_probes.py

@@ -8,7 +8,11 @@ from typing import Any, Optional
 
 from .api import create_client
 
-VIDEO_CREATIVE_TYPES = {"VIDEO_EXTENSION_CREATIVE", "CPM_VIDEO_CREATIVE"}
+VIDEO_CREATIVE_TYPES = {
+    "VIDEO_EXTENSION_CREATIVE",
+    "CPM_VIDEO_CREATIVE",
+    "CPC_VIDEO_CREATIVE",
+}
 
 
 def _extract_items(response: Any) -> list[dict[str, Any]]:
@@ -18,7 +22,7 @@ def _extract_items(response: Any) -> list[dict[str, Any]]:
 
 
 def _advideo_get_accepts(client: Any, candidate: str) -> bool:
-    """Return whether advideos.get accepts and returns the candidate ID."""
+    """Return whether advideos.get accepts the candidate ID."""
     body = {
         "method": "get",
         "params": {
@@ -28,7 +32,8 @@ def _advideo_get_accepts(client: Any, candidate: str) -> bool:
         },
     }
     try:
-        return bool(_extract_items(client.advideos().post(data=body)))
+        _extract_items(client.advideos().post(data=body))
+        return True
     except Exception:
         return False
 

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

@@ -1,7 +1,7 @@
 
 __author__ = 'Pavel Maksimov'
 __email__ = 'vur21@ya.ru'
-__version__ = '2026.4.27'
+__version__ = '2026.4.28'
 
 
 from .resource_mapping import *

{direct_cli-0.3.0 → direct_cli-0.3.1}/direct_cli/_vendor/tapi_yandex_direct/v4/adapter.py

@@ -44,9 +44,10 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
         login = api_params.get("login")
         language = api_params.get("language", "en")
 
-        # Enrich the JSON body with token / locale / login (param.login for
-        # agent calls). format_data_to_request does not see api_params, so we
-        # do this here, after super() has already serialised the user data.
+        # Enrich the JSON body with token / locale. format_data_to_request does
+        # not see api_params, so we do this here, after super() has already
+        # serialised the user data. Agency/client selection is transport-level
+        # (Client-Login header); method params must stay schema-shaped.
         raw = params.get("data")
         if raw:
             if isinstance(raw, (bytes, bytearray)):
@@ -66,14 +67,15 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
                 body.setdefault("token", token)
             if language:
                 body.setdefault("locale", language)
-            if login and isinstance(body.get("param"), dict):
-                body["param"].setdefault("login", login)
 
             params["data"] = orjson.dumps(body)
 
         if token:
             params["headers"]["Authorization"] = "Bearer {}".format(token)
 
+        if login:
+            params["headers"]["Client-Login"] = login
+
         return params
 
     def format_data_to_request(self, data) -> Optional[bytes]:

{direct_cli-0.3.0 → direct_cli-0.3.1}/direct_cli/api.py

@@ -5,6 +5,7 @@ API client wrapper for Direct CLI
 from typing import Optional, Dict, Any, List
 
 from direct_cli._vendor.tapi_yandex_direct import YandexDirect
+from direct_cli._vendor.tapi_yandex_direct.v4 import YandexDirectV4Live
 from .auth import get_credentials
 
 
@@ -67,6 +68,58 @@ def create_client(
     )
 
 
+def create_v4_client(
+    token: Optional[str] = None,
+    login: Optional[str] = None,
+    profile: Optional[str] = None,
+    sandbox: bool = False,
+    op_token_ref: Optional[str] = None,
+    op_login_ref: Optional[str] = None,
+    bw_token_ref: Optional[str] = None,
+    bw_login_ref: Optional[str] = None,
+    language: Optional[str] = None,
+    retry_if_exceeded_limit: bool = True,
+    retries_if_server_error: int = 5,
+) -> YandexDirectV4Live:
+    """
+    Create YandexDirect v4 Live client.
+
+    Args:
+        token: API access token
+        login: Client login (for agency accounts)
+        profile: Credential profile name
+        sandbox: Use sandbox API
+        op_token_ref: 1Password secret reference for token
+        op_login_ref: 1Password secret reference for login
+        bw_token_ref: Bitwarden item name/ID for token
+        bw_login_ref: Bitwarden item name/ID for login
+        language: API locale
+        retry_if_exceeded_limit: Retry when the API limit is exceeded
+        retries_if_server_error: Number of retries for server errors
+
+    Returns:
+        YandexDirect v4 Live client instance
+    """
+    final_token, final_login = get_credentials(
+        token,
+        login,
+        profile=profile,
+        op_token_ref=op_token_ref,
+        op_login_ref=op_login_ref,
+        bw_token_ref=bw_token_ref,
+        bw_login_ref=bw_login_ref,
+    )
+
+    return YandexDirectV4Live(
+        access_token=final_token,
+        login=final_login,
+        is_sandbox=sandbox,
+        language=language or "en",
+        retry_if_exceeded_limit=retry_if_exceeded_limit,
+        retries_if_server_error=retries_if_server_error,
+    )
+
+
 def fetch_all_pages(
     client: YandexDirect,
     resource_name: str,

{direct_cli-0.3.0 → direct_cli-0.3.1}/direct_cli/cli.py

@@ -41,6 +41,16 @@ from .commands.advideos import advideos
 from .commands.dynamicfeedadtargets import dynamicfeedadtargets
 from .commands.strategies import strategies
 from .commands.auth import auth
+from .commands.balance import balance
+from .commands.v4shells import (
+    v4account,
+    v4events,
+    v4finance,
+    v4forecast,
+    v4meta,
+    v4wordstat,
+)
+from .commands.v4goals import v4goals
 
 # Load .env file
 load_dotenv()
@@ -173,6 +183,14 @@ for command in (
     advideos,
     dynamicfeedadtargets,
     strategies,
+    balance,
+    v4finance,
+    v4account,
+    v4goals,
+    v4events,
+    v4wordstat,
+    v4forecast,
+    v4meta,
     auth,
 ):
     _register_command(command)

direct_cli-0.3.1/direct_cli/commands/balance.py

@@ -0,0 +1,55 @@
+"""Money balance command backed by Yandex Direct v4 Live."""
+
+import click
+
+from ..api import create_v4_client
+from ..output import format_output, print_error
+from ..utils import parse_csv_strings
+from ..v4 import build_v4_body, call_v4
+from ..v4_contracts import v4_method_contract
+
+
+@v4_method_contract("AccountManagement")
+@click.command()
+@click.option("--logins", help="Comma-separated client logins")
+@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 balance(ctx, logins, output_format, output, dry_run):
+    """Check account money balance."""
+    login_list = parse_csv_strings(logins)
+    configured_login = ctx.obj.get("login")
+    if not login_list and configured_login:
+        login_list = [configured_login]
+
+    param = {
+        "Action": "Get",
+    }
+    if login_list:
+        param["SelectionCriteria"] = {"Logins": login_list}
+    elif ctx.obj.get("sandbox"):
+        raise click.UsageError("Provide --logins or configure YANDEX_DIRECT_LOGIN")
+
+    if dry_run:
+        format_output(build_v4_body("AccountManagement", 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, "AccountManagement", param)
+        format_output(data, output_format, output)
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()

direct_cli-0.3.1/direct_cli/commands/v4goals.py

@@ -0,0 +1,103 @@
+"""Yandex Direct v4 Live goals commands."""
+
+import click
+
+from ..api import create_v4_client
+from ..output import format_output, print_error
+from ..utils import parse_ids
+from ..v4 import build_v4_body, call_v4
+from ..v4_contracts import v4_method_contract
+from .v4shells import V4_EPILOG
+
+
+def _campaign_ids_param(campaign_ids: str) -> dict:
+    """Build the v4 Live CampaignIDInfo parameter."""
+    try:
+        ids = parse_ids(campaign_ids)
+    except ValueError as exc:
+        raise click.UsageError(str(exc))
+    if not ids:
+        raise click.UsageError("--campaign-ids must not be empty")
+    return {"CampaignIDS": ids}
+
+
+def _run_goals_command(
+    ctx,
+    method: str,
+    campaign_ids: str,
+    output_format: str,
+    output: str,
+    dry_run: bool,
+) -> None:
+    param = _campaign_ids_param(campaign_ids)
+    if dry_run:
+        format_output(build_v4_body(method, 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, method, param)
+        format_output(data, output_format, output)
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+
+
+@click.group(epilog=V4_EPILOG)
+def v4goals():
+    """Yandex Direct v4 Live goals commands."""
+
+
+@v4_method_contract("GetStatGoals")
+@v4goals.command(name="get-stat-goals")
+@click.option("--campaign-ids", required=True, help="Comma-separated campaign IDs")
+@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_stat_goals(ctx, campaign_ids, output_format, output, dry_run):
+    """Get Yandex Metrica goals available for campaigns."""
+    _run_goals_command(
+        ctx,
+        "GetStatGoals",
+        campaign_ids,
+        output_format,
+        output,
+        dry_run,
+    )
+
+
+@v4_method_contract("GetRetargetingGoals")
+@v4goals.command(name="get-retargeting-goals")
+@click.option("--campaign-ids", required=True, help="Comma-separated campaign IDs")
+@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_retargeting_goals(ctx, campaign_ids, output_format, output, dry_run):
+    """Get retargeting goals for campaigns."""
+    _run_goals_command(
+        ctx,
+        "GetRetargetingGoals",
+        campaign_ids,
+        output_format,
+        output,
+        dry_run,
+    )

direct_cli-0.3.1/direct_cli/commands/v4shells.py

@@ -0,0 +1,40 @@
+"""Shell command groups for Yandex Direct v4 Live command families."""
+
+import click
+
+V4_EPILOG = (
+    "\b\n"
+    "V4 Live commands use typed flags only. Supported methods are listed in "
+    "the Yandex Direct v4 Live documentation: "
+    "https://yandex.com/dev/direct/doc/dg-v4/en/live/concepts"
+)
+
+
+@click.group(epilog=V4_EPILOG)
+def v4finance():
+    """Yandex Direct v4 Live finance commands."""
+
+
+@click.group(epilog=V4_EPILOG)
+def v4account():
+    """Yandex Direct v4 Live account commands."""
+
+
+@click.group(epilog=V4_EPILOG)
+def v4events():
+    """Yandex Direct v4 Live events commands."""
+
+
+@click.group(epilog=V4_EPILOG)
+def v4wordstat():
+    """Yandex Direct v4 Live wordstat commands."""
+
+
+@click.group(epilog=V4_EPILOG)
+def v4forecast():
+    """Yandex Direct v4 Live forecast commands."""
+
+
+@click.group(epilog=V4_EPILOG)
+def v4meta():
+    """Yandex Direct v4 Live metadata commands."""

{direct_cli-0.3.0 → direct_cli-0.3.1}/direct_cli/smoke_matrix.py

@@ -19,6 +19,7 @@ DANGEROUS = "DANGEROUS"
 
 SMOKE_MATRIX = {
     SAFE: [
+        "balance",
         "adextensions.get",
         "adgroups.get",
         "adimages.get",
@@ -56,6 +57,8 @@ SMOKE_MATRIX = {
         "smartadtargets.get",
         "strategies.get",
         "turbopages.get",
+        "v4goals.get-retargeting-goals",
+        "v4goals.get-stat-goals",
         "vcards.get",
     ],
     WRITE_SANDBOX: [
@@ -190,11 +193,14 @@ def commands_for_category(category: str) -> list[str]:
 def _registered_cli_commands() -> set[str]:
     from direct_cli.cli import cli
 
-    return {
-        command_key(group_name, command_name)
-        for group_name, group in cli.commands.items()
-        for command_name in getattr(group, "commands", {})
-    }
+    registered = set()
+    for group_name, group in cli.commands.items():
+        if hasattr(group, "commands"):
+            for command_name in group.commands:
+                registered.add(command_key(group_name, command_name))
+        else:
+            registered.add(group_name)
+    return registered
 
 
 def _wsdl_operations_count() -> int:

direct_cli-0.3.1/direct_cli/v4.py

@@ -0,0 +1,17 @@
+"""Shared helpers for Yandex Direct v4 Live commands."""
+
+from typing import Any, Optional
+
+
+def build_v4_body(method: str, param: Optional[Any] = None) -> dict:
+    """Build a v4 Live request body."""
+    body = {"method": method}
+    if param is not None:
+        body["param"] = param
+    return body
+
+
+def call_v4(client: Any, method: str, param: Optional[Any] = None) -> Any:
+    """Call one v4 Live method and return the extracted response payload."""
+    result = client.v4live().post(data=build_v4_body(method, param))
+    return result().extract()