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

direct_cli-0.3.3/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.3.3
+
+**BREAKING CHANGE:** OAuth profiles created before 0.3.3 (without `refresh_token` and `expires_at`) are no longer accepted. Any such profile will fail immediately with an "incomplete profile" error. Run `direct auth login --profile <name>` to re-authenticate and create a valid 0.3.3 profile.
+
+- Added refresh token persistence for OAuth profiles.
+- Added automatic OAuth access token refresh before expiry.
+- Added `expires_in` details to `direct auth status`.
+- Added JSON output for `direct auth status`.
+- Kept `direct auth login --oauth-token` as a manual access-token import without auto-refresh.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.1
+Version: 0.3.3
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -83,7 +83,6 @@ OAuth and profile commands:
 direct auth login
 direct auth login --profile agency1
 direct auth login --code abc123 --profile agency1
-direct auth login --oauth-token y0_example --profile agency1
 direct auth list
 direct auth use --profile agency1
 direct auth status --profile agency1
@@ -95,6 +94,8 @@ Notes:
 - Select credentials with `--profile`.
 - `--login` remains Direct client login.
 - Authorization is performed via `direct auth login`.
+- OAuth profiles store refresh tokens and refresh access tokens automatically.
+- `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -147,6 +148,45 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Events
+
+```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
+```
+
+### V4 Live Finance
+
+Finance methods require an extra financial token for money operations. In the
+Yandex Direct web UI, open Tools -> API -> Financial operations, enable the
+financial operations checkbox, click Save, then issue the master token on the
+same Financial operations page and confirm by SMS. Direct CLI can compute the
+per-request token from `--master-token`, `--operation-num`, and
+`--finance-login`; alternatively pass a precomputed token with `--finance-token`.
+Environment variables are
+`YANDEX_DIRECT_MASTER_TOKEN`, `YANDEX_DIRECT_FINANCE_LOGIN`,
+`YANDEX_DIRECT_FINANCE_TOKEN`, and `YANDEX_DIRECT_OPERATION_NUM`. Money mutation
+commands are dry-run-only in this release and always require `--dry-run`; dry-run
+output masks the financial token.
+
+```bash
+direct v4finance get-credit-limits --logins client-login --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login
+direct v4finance get-credit-limits --logins client-login,other-client --format table
+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 --currency RUB --contract-id CONTRACT_ID --pay-method Bank --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+```
+
+### V4 Live Shared Account
+
+Shared-account mutations are dry-run-only in this release and always require
+`--dry-run`.
+
+```bash
+direct v4account enable-shared-account --client-login client-login --dry-run
+direct v4account account-management --action Update --account-id 1327944 --day-budget 100.50 --spend-mode Default --money-in-sms Yes --money-out-sms No --email ops@example.com --money-warning-value 25 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -344,6 +384,7 @@ direct keywords delete --id 88888
 ```bash
 # Get a report (saved to file)
 direct reports get --type CAMPAIGN_PERFORMANCE_REPORT --from 2024-01-01 --to 2024-01-31 --name "January Report" --fields "Date,CampaignId,Clicks,Cost" --format csv --output report.csv
+direct reports get --type CUSTOM_REPORT --from 2024-01-01 --to 2024-01-31 --name "Goals Report" --fields "Date,CampaignId,GoalsRoi" --goals 12345,67890 --attribution-models AUTO --format csv --output goals-report.csv
 
 # List available report types
 direct reports list-types
@@ -509,9 +550,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 31 |
-| CLI subcommands including `auth` | 122 |
-| API CLI subcommands excluding `auth` | 118 |
+| CLI groups including `auth` | 39 |
+| CLI subcommands including `auth` | 130 |
+| API CLI subcommands excluding `auth` | 126 |
 
 ### API Coverage And Drift Monitoring
 
@@ -549,7 +590,7 @@ CI runs a scheduled API coverage workflow that:
 
 `WRITE_SANDBOX` smoke is a live check against the Yandex Direct **sandbox**.
 It does not replay stored HTTP traffic and it does not create new recordings.
-Run it only when you intentionally want to call `api-sandbox.direct.yandex.com`:
+Run it only when you intentionally want to call `api-sandbox.direct.yandex.ru`:
 
 ```bash
 set -a && source .env && set +a
@@ -691,13 +732,16 @@ OAuth и profile-команды:
 direct auth login
 direct auth login --profile agency1
 direct auth login --code abc123 --profile agency1
-direct auth login --oauth-token y0_example --profile agency1
 direct auth list
 direct auth use --profile agency1
 direct auth status --profile agency1
 direct --profile agency1 campaigns get
 ```
 
+Примечания:
+- OAuth profiles сохраняют refresh token и автоматически обновляют access token.
+- `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
@@ -966,6 +1010,7 @@ direct keywords delete --id 88888
 ```bash
 # Сформировать отчёт (сохраняется в файл)
 direct reports get --type CAMPAIGN_PERFORMANCE_REPORT --from 2024-01-01 --to 2024-01-31 --name "Отчёт за январь" --fields "Date,CampaignId,Clicks,Cost" --format csv --output report.csv
+direct reports get --type CUSTOM_REPORT --from 2024-01-01 --to 2024-01-31 --name "Отчёт по целям" --fields "Date,CampaignId,GoalsRoi" --goals 12345,67890 --attribution-models AUTO --format csv --output goals-report.csv
 
 # Список доступных типов отчётов
 direct reports list-types
@@ -1132,16 +1177,16 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 31 |
-| CLI subcommands с `auth` | 122 |
-| API CLI subcommands без `auth` | 118 |
+| CLI groups с `auth` | 39 |
+| CLI subcommands с `auth` | 130 |
+| API CLI subcommands без `auth` | 126 |
 
 #### Live sandbox write smoke
 
 `WRITE_SANDBOX` smoke — это live-проверка против **sandbox-окружения**
 Яндекс Директа. Она не воспроизводит сохранённый HTTP-трафик и не создаёт
 новые записи. Запускайте её только когда намеренно хотите обратиться к
-`api-sandbox.direct.yandex.com`:
+`api-sandbox.direct.yandex.ru`:
 
 ```bash
 set -a && source .env && set +a

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

@@ -44,7 +44,6 @@ OAuth and profile commands:
 direct auth login
 direct auth login --profile agency1
 direct auth login --code abc123 --profile agency1
-direct auth login --oauth-token y0_example --profile agency1
 direct auth list
 direct auth use --profile agency1
 direct auth status --profile agency1
@@ -56,6 +55,8 @@ Notes:
 - Select credentials with `--profile`.
 - `--login` remains Direct client login.
 - Authorization is performed via `direct auth login`.
+- OAuth profiles store refresh tokens and refresh access tokens automatically.
+- `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -108,6 +109,45 @@ direct v4goals get-retargeting-goals --campaign-ids 123,456 --format table
 direct v4goals get-stat-goals --campaign-ids 123 --dry-run
 ```
 
+### V4 Live Events
+
+```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
+```
+
+### V4 Live Finance
+
+Finance methods require an extra financial token for money operations. In the
+Yandex Direct web UI, open Tools -> API -> Financial operations, enable the
+financial operations checkbox, click Save, then issue the master token on the
+same Financial operations page and confirm by SMS. Direct CLI can compute the
+per-request token from `--master-token`, `--operation-num`, and
+`--finance-login`; alternatively pass a precomputed token with `--finance-token`.
+Environment variables are
+`YANDEX_DIRECT_MASTER_TOKEN`, `YANDEX_DIRECT_FINANCE_LOGIN`,
+`YANDEX_DIRECT_FINANCE_TOKEN`, and `YANDEX_DIRECT_OPERATION_NUM`. Money mutation
+commands are dry-run-only in this release and always require `--dry-run`; dry-run
+output masks the financial token.
+
+```bash
+direct v4finance get-credit-limits --logins client-login --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login
+direct v4finance get-credit-limits --logins client-login,other-client --format table
+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 --currency RUB --contract-id CONTRACT_ID --pay-method Bank --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
+```
+
+### V4 Live Shared Account
+
+Shared-account mutations are dry-run-only in this release and always require
+`--dry-run`.
+
+```bash
+direct v4account enable-shared-account --client-login client-login --dry-run
+direct v4account account-management --action Update --account-id 1327944 --day-budget 100.50 --spend-mode Default --money-in-sms Yes --money-out-sms No --email ops@example.com --money-warning-value 25 --dry-run
+```
+
 ### CLI Convention
 
 The current CLI convention is defined as follows.
@@ -305,6 +345,7 @@ direct keywords delete --id 88888
 ```bash
 # Get a report (saved to file)
 direct reports get --type CAMPAIGN_PERFORMANCE_REPORT --from 2024-01-01 --to 2024-01-31 --name "January Report" --fields "Date,CampaignId,Clicks,Cost" --format csv --output report.csv
+direct reports get --type CUSTOM_REPORT --from 2024-01-01 --to 2024-01-31 --name "Goals Report" --fields "Date,CampaignId,GoalsRoi" --goals 12345,67890 --attribution-models AUTO --format csv --output goals-report.csv
 
 # List available report types
 direct reports list-types
@@ -470,9 +511,9 @@ Current command surface:
 | WSDL-backed API services | 29 |
 | Supported API services including Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups including `auth` | 31 |
-| CLI subcommands including `auth` | 122 |
-| API CLI subcommands excluding `auth` | 118 |
+| CLI groups including `auth` | 39 |
+| CLI subcommands including `auth` | 130 |
+| API CLI subcommands excluding `auth` | 126 |
 
 ### API Coverage And Drift Monitoring
 
@@ -510,7 +551,7 @@ CI runs a scheduled API coverage workflow that:
 
 `WRITE_SANDBOX` smoke is a live check against the Yandex Direct **sandbox**.
 It does not replay stored HTTP traffic and it does not create new recordings.
-Run it only when you intentionally want to call `api-sandbox.direct.yandex.com`:
+Run it only when you intentionally want to call `api-sandbox.direct.yandex.ru`:
 
 ```bash
 set -a && source .env && set +a
@@ -652,13 +693,16 @@ OAuth и profile-команды:
 direct auth login
 direct auth login --profile agency1
 direct auth login --code abc123 --profile agency1
-direct auth login --oauth-token y0_example --profile agency1
 direct auth list
 direct auth use --profile agency1
 direct auth status --profile agency1
 direct --profile agency1 campaigns get
 ```
 
+Примечания:
+- OAuth profiles сохраняют refresh token и автоматически обновляют access token.
+- `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
@@ -927,6 +971,7 @@ direct keywords delete --id 88888
 ```bash
 # Сформировать отчёт (сохраняется в файл)
 direct reports get --type CAMPAIGN_PERFORMANCE_REPORT --from 2024-01-01 --to 2024-01-31 --name "Отчёт за январь" --fields "Date,CampaignId,Clicks,Cost" --format csv --output report.csv
+direct reports get --type CUSTOM_REPORT --from 2024-01-01 --to 2024-01-31 --name "Отчёт по целям" --fields "Date,CampaignId,GoalsRoi" --goals 12345,67890 --attribution-models AUTO --format csv --output goals-report.csv
 
 # Список доступных типов отчётов
 direct reports list-types
@@ -1093,16 +1138,16 @@ YANDEX_DIRECT_LIVE_WRITE=1 pytest -m integration_live_write -v --record-mode=rew
 | WSDL-backed API services | 29 |
 | API services с учётом Reports | 30 |
 | WSDL operations | 112 |
-| CLI groups с `auth` | 31 |
-| CLI subcommands с `auth` | 122 |
-| API CLI subcommands без `auth` | 118 |
+| CLI groups с `auth` | 39 |
+| CLI subcommands с `auth` | 130 |
+| API CLI subcommands без `auth` | 126 |
 
 #### Live sandbox write smoke
 
 `WRITE_SANDBOX` smoke — это live-проверка против **sandbox-окружения**
 Яндекс Директа. Она не воспроизводит сохранённый HTTP-трафик и не создаёт
 новые записи. Запускайте её только когда намеренно хотите обратиться к
-`api-sandbox.direct.yandex.com`:
+`api-sandbox.direct.yandex.ru`:
 
 ```bash
 set -a && source .env && set +a

direct_cli-0.3.3/direct_cli/_vendor/tapi_yandex_direct/endpoints.py

@@ -0,0 +1,14 @@
+"""Runtime endpoints for Yandex Direct API transports."""
+
+from typing import Any, Dict
+
+DIRECT_API_PRODUCTION_ROOT = "https://api.direct.yandex.ru/"
+DIRECT_API_SANDBOX_ROOT = "https://api-sandbox.direct.yandex.ru/"
+DIRECT_DEBUG_ROOT = "https://"
+
+
+def get_direct_api_root(api_params: Dict[str, Any]) -> str:
+    """Return the Direct API root for production or sandbox requests."""
+    if api_params.get("is_sandbox"):
+        return DIRECT_API_SANDBOX_ROOT
+    return DIRECT_API_PRODUCTION_ROOT

{direct_cli-0.3.1 → direct_cli-0.3.3}/direct_cli/_vendor/tapi_yandex_direct/tapi_yandex_direct.py

@@ -9,6 +9,7 @@ from tapi2 import TapiAdapter, generate_wrapper_from_adapter, JSONAdapterMixin
 from tapi2.exceptions import ResponseProcessException, ClientError, TapiException
 
 from . import exceptions
+from .endpoints import DIRECT_DEBUG_ROOT, get_direct_api_root
 from .resource_mapping import RESOURCE_MAPPING_V5
 
 logger = logging.getLogger(__name__)
@@ -72,11 +73,8 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
 
     def get_api_root(self, api_params: dict, resource_name: str) -> str:
         if resource_name == "debugtoken":
-            return "https://"
-        elif api_params.get("is_sandbox"):
-            return "https://api-sandbox.direct.yandex.com/"
-        else:
-            return "https://api.direct.yandex.com/"
+            return DIRECT_DEBUG_ROOT
+        return get_direct_api_root(api_params)
 
     def get_request_kwargs(self, api_params: dict, *args, **kwargs) -> dict:
         """Обогащение запроса, параметрами"""
@@ -154,7 +152,7 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
                 "The report generation time has exceeded the server limit. "
                 "Please try to change the request parameters, "
                 "reduce the period or the amount of requested data.",
-                **kwargs
+                **kwargs,
             )
         elif response.status_code == 405:
             raise exceptions.YandexDirectApiError(
@@ -162,7 +160,7 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
                 "This resource does not support the HTTP method {}\n".format(
                     response.request.method
                 ),
-                **kwargs
+                **kwargs,
             )
 
         data = self.response_to_native(response)
@@ -190,7 +188,7 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
         response: Response,
         request_kwargs: dict,
         api_params: dict,
-        **kwargs
+        **kwargs,
     ) -> None:
         if response.status_code in (201, 202):
             pass
@@ -230,7 +228,7 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
         response: Response,
         request_kwargs: dict,
         api_params: dict,
-        **kwargs
+        **kwargs,
     ) -> bool:
         status_code = response.status_code
         error_data = error_message.get("error", {})
@@ -283,7 +281,7 @@ class YandexDirectClientAdapter(JSONAdapterMixin, TapiAdapter):
         response: Response,
         request_kwargs: dict,
         api_params: dict,
-        **kwargs
+        **kwargs,
     ) -> Optional[dict]:
         limit = response_data["result"].get("LimitedBy")
         if limit:

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

@@ -18,6 +18,7 @@ from tapi2 import JSONAdapterMixin, TapiAdapter, generate_wrapper_from_adapter
 from tapi2.exceptions import ClientError, ResponseProcessException, TapiException
 
 from .. import exceptions
+from ..endpoints import get_direct_api_root
 from .resource_mapping import (
     RESOURCE_MAPPING_V4_LIVE,
     SUPPORTED_V4_METHODS,
@@ -33,9 +34,7 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
         super().__init__(*args, **kwargs)
 
     def get_api_root(self, api_params: dict, resource_name: str) -> str:
-        if api_params.get("is_sandbox"):
-            return "https://api-sandbox.direct.yandex.ru/"
-        return "https://api.direct.yandex.ru/"
+        return get_direct_api_root(api_params)
 
     def get_request_kwargs(self, api_params: dict, *args, **kwargs) -> dict:
         params = super().get_request_kwargs(api_params, *args, **kwargs)
@@ -43,11 +42,14 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
         token = api_params.get("access_token")
         login = api_params.get("login")
         language = api_params.get("language", "en")
-
-        # 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.
+        finance_token = api_params.get("finance_token")
+        operation_num = api_params.get("operation_num")
+
+        # Enrich the JSON body with top-level v4 Live fields.
+        # 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)):
@@ -67,6 +69,10 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
                 body.setdefault("token", token)
             if language:
                 body.setdefault("locale", language)
+            if finance_token:
+                body.setdefault("finance_token", finance_token)
+            if operation_num is not None:
+                body.setdefault("operation_num", operation_num)
 
             params["data"] = orjson.dumps(body)
 
@@ -100,7 +106,9 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
                 data = None
         return data
 
-    def process_response(self, response: Response, request_kwargs: dict, **kwargs) -> dict:
+    def process_response(
+        self, response: Response, request_kwargs: dict, **kwargs
+    ) -> dict:
         # Mirror the v5 behaviour: turn the serialised body back into a dict so
         # downstream hooks (extract, retry) can read it.
         if isinstance(request_kwargs.get("data"), (bytes, bytearray, str)):
@@ -180,8 +188,13 @@ class V4LiveClientAdapter(JSONAdapterMixin, TapiAdapter):
 
         return False
 
-    def extract(self, data, response: Optional[Response] = None,
-                request_kwargs: Optional[dict] = None, **kwargs):
+    def extract(
+        self,
+        data,
+        response: Optional[Response] = None,
+        request_kwargs: Optional[dict] = None,
+        **kwargs,
+    ):
         # v4 Live always nests payload under "data". For methods returning a
         # bare scalar (TransferMoney → 1), the scalar comes through unchanged.
         # response / request_kwargs are accepted but unused — they are kept

{direct_cli-0.3.1 → direct_cli-0.3.3}/direct_cli/_vendor/tapi_yandex_direct/v4/adapter.pyi

@@ -49,6 +49,8 @@ class YandexDirectV4Live:
         language: str = "en",
         retry_if_exceeded_limit: bool = True,
         retries_if_server_error: int = 5,
+        finance_token: Optional[str] = None,
+        operation_num: Optional[int] = None,
     ) -> None: ...
 
     def v4live(self) -> V4LiveExecutor: ...

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

@@ -80,6 +80,8 @@ def create_v4_client(
     language: Optional[str] = None,
     retry_if_exceeded_limit: bool = True,
     retries_if_server_error: int = 5,
+    finance_token: Optional[str] = None,
+    operation_num: Optional[int] = None,
 ) -> YandexDirectV4Live:
     """
     Create YandexDirect v4 Live client.
@@ -96,6 +98,8 @@ def create_v4_client(
         language: API locale
         retry_if_exceeded_limit: Retry when the API limit is exceeded
         retries_if_server_error: Number of retries for server errors
+        finance_token: Financial token for v4 Live finance methods
+        operation_num: Financial operation number for v4 Live finance methods
 
     Returns:
         YandexDirect v4 Live client instance
@@ -117,6 +121,8 @@ def create_v4_client(
         language=language or "en",
         retry_if_exceeded_limit=retry_if_exceeded_limit,
         retries_if_server_error=retries_if_server_error,
+        finance_token=finance_token,
+        operation_num=operation_num,
     )