direct-cli 0.3.10__tar.gz → 0.3.11__tar.gz

{direct_cli-0.3.10 → direct_cli-0.3.11}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.3.11
+
+**Added:**
+
+- `direct campaigns add` and `direct campaigns update` now expose
+  `--tracking-params` for the campaign-level tracking query string
+  (`TextCampaign` / `DynamicTextCampaign` / `SmartCampaign` `.TrackingParams`).
+  `campaigns update` gained an optional `--type` discriminator —
+  required when `--tracking-params` is set, validated against
+  the three subtypes supported by the CLI. Backward compatible:
+  existing `campaigns update --id N --name X` calls without `--type`
+  keep working unchanged. Closes #230.
+- `direct v4account account-management` now supports `--action Get`,
+  `Deposit`, `Invoice`, and `TransferMoney` in addition to `Update`,
+  matching the official v4 Live docs
+  (<https://yandex.ru/dev/direct/doc/dg-v4/reference/AccountManagement-docpage/>).
+  `Get` is read-only and accepts optional `--logins` / `--account-ids`
+  filters. `Deposit`, `Invoice`, and `TransferMoney` are financial
+  mutations: they need `--finance-token` (or `--master-token` +
+  `--operation-num` + `--finance-login`) and respect the existing
+  dry-run-unless-sandbox rule. A Click-side allow-list rejects flags
+  that do not belong to the chosen action before any body is built.
+  Refs #125.
+
+**Fixed:**
+
+- `direct v4 *` command wrappers now let `click.ClickException`
+  (including `UsageError` from `call_v4` shape validation) propagate to
+  Click instead of swallowing it in the generic `except Exception`.
+  Shape-validation errors keep their usage hint and exit with code 2,
+  matching Click's contract; non-Click runtime errors still surface
+  through `print_error` + `Abort` (exit 1). Closes #227.
+
+**Breaking changes:**
+
+- `direct v4finance get-credit-limits` no longer accepts `--logins`; the
+  request body now omits `param` per the official v4 Live docs
+  (<https://yandex.ru/dev/direct/doc/dg-v4/reference/GetCreditLimits.html>),
+  which define the body as `method`, `finance_token`, and `operation_num`
+  only. Refs #125.
+
 ## 0.3.10
 
 **Added:**

{direct_cli-0.3.10 → direct_cli-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.3.10
+Version: 0.3.11
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -228,8 +228,7 @@ 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 --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 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 --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 --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
@@ -238,14 +237,27 @@ direct v4finance pay-campaigns --campaign-ids 123,456 --amount 100.50 --currency
 
 ### V4 Live Shared Account
 
-Shared-account mutations require `--dry-run` in production and can be sent live
-only with top-level `--sandbox`. These commands follow the official v4 Live
-shared-account method shapes: `EnableSharedAccount` accepts one client `Login`,
-and `AccountManagement` updates shared-account settings through `Accounts`.
+`EnableSharedAccount` accepts one client `Login` (agencies only).
+`AccountManagement` exposes the five official v4 Live actions:
+`Get`, `Update`, `Deposit`, `Invoice`, and `TransferMoney`. `Get` is
+read-only and runs against production without `--dry-run`. `Update`,
+`Deposit`, `Invoice`, and `TransferMoney` are mutations: they require
+`--dry-run` in production and can be sent live only with top-level
+`--sandbox`. `Deposit`, `Invoice`, and `TransferMoney` are financial
+operations that need `--finance-token` (or `--master-token` +
+`--operation-num` + `--finance-login`); dry-run output masks the
+financial token.
 
 ```bash
 direct v4account enable-shared-account --client-login client-login --dry-run
+direct v4account account-management --action Get
+direct v4account account-management --action Get --logins client-a,client-b
+direct v4account account-management --action Get --account-ids 1327944,1327945
 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
+direct v4account account-management --action Deposit --payment 1327944=100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
+direct v4account account-management --action Deposit --payment 1327944=100.50 --currency RUB --origin Overdraft --contract CONTRACT_ID --master-token MASTER_TOKEN --operation-num 125 --finance-login agency-login --dry-run
+direct v4account account-management --action Invoice --payment 1327944=100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 126 --finance-login agency-login --dry-run
+direct v4account account-management --action TransferMoney --from-account-id 1327944 --to-account-id 1327945 --amount 50.00 --currency RUB --master-token MASTER_TOKEN --operation-num 127 --finance-login agency-login --dry-run
 direct --sandbox v4account enable-shared-account --client-login client-login
 ```
 
@@ -393,8 +405,12 @@ direct campaigns add --name "Multi-Goal CPA" --start-date 2026-06-01 --type TEXT
 # Notification (Sms/Email) and TimeTargeting accept JSON with WSDL CamelCase keys
 direct campaigns add --name "Notify+Schedule" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
 
+# TrackingParams (campaign-level UTM / tracking query string)
+direct campaigns add --name "UTM" --start-date 2026-06-01 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_campaign={campaign_id}" --dry-run
+
 # Update / lifecycle
 direct campaigns update --id 12345 --name "New Name" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
+direct campaigns update --id 12345 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_medium=cpc" --dry-run
 direct campaigns suspend --id 12345
 direct campaigns resume --id 12345
 direct campaigns archive --id 12345
@@ -1083,8 +1099,12 @@ direct campaigns add --name "Мульти-целевой CPA" --start-date 2026-
 # Notification (Sms/Email) и TimeTargeting принимают JSON с CamelCase ключами WSDL
 direct campaigns add --name "Уведомления+Расписание" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
 
+# TrackingParams — UTM/трекинг на уровне кампании (TextCampaign/DynamicTextCampaign/SmartCampaign.TrackingParams)
+direct campaigns add --name "UTM" --start-date 2026-06-01 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_campaign={campaign_id}" --dry-run
+
 # Обновление и управление статусом
 direct campaigns update --id 12345 --name "Новое название" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
+direct campaigns update --id 12345 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_medium=cpc" --dry-run
 direct campaigns suspend --id 12345
 direct campaigns resume --id 12345
 direct campaigns archive --id 12345

{direct_cli-0.3.10 → direct_cli-0.3.11}/README.md

@@ -185,8 +185,7 @@ 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 --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 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 --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 --currency RUB --master-token MASTER_TOKEN --operation-num 123 --finance-login agency-login --dry-run
@@ -195,14 +194,27 @@ direct v4finance pay-campaigns --campaign-ids 123,456 --amount 100.50 --currency
 
 ### V4 Live Shared Account
 
-Shared-account mutations require `--dry-run` in production and can be sent live
-only with top-level `--sandbox`. These commands follow the official v4 Live
-shared-account method shapes: `EnableSharedAccount` accepts one client `Login`,
-and `AccountManagement` updates shared-account settings through `Accounts`.
+`EnableSharedAccount` accepts one client `Login` (agencies only).
+`AccountManagement` exposes the five official v4 Live actions:
+`Get`, `Update`, `Deposit`, `Invoice`, and `TransferMoney`. `Get` is
+read-only and runs against production without `--dry-run`. `Update`,
+`Deposit`, `Invoice`, and `TransferMoney` are mutations: they require
+`--dry-run` in production and can be sent live only with top-level
+`--sandbox`. `Deposit`, `Invoice`, and `TransferMoney` are financial
+operations that need `--finance-token` (or `--master-token` +
+`--operation-num` + `--finance-login`); dry-run output masks the
+financial token.
 
 ```bash
 direct v4account enable-shared-account --client-login client-login --dry-run
+direct v4account account-management --action Get
+direct v4account account-management --action Get --logins client-a,client-b
+direct v4account account-management --action Get --account-ids 1327944,1327945
 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
+direct v4account account-management --action Deposit --payment 1327944=100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 124 --finance-login agency-login --dry-run
+direct v4account account-management --action Deposit --payment 1327944=100.50 --currency RUB --origin Overdraft --contract CONTRACT_ID --master-token MASTER_TOKEN --operation-num 125 --finance-login agency-login --dry-run
+direct v4account account-management --action Invoice --payment 1327944=100.50 --currency RUB --master-token MASTER_TOKEN --operation-num 126 --finance-login agency-login --dry-run
+direct v4account account-management --action TransferMoney --from-account-id 1327944 --to-account-id 1327945 --amount 50.00 --currency RUB --master-token MASTER_TOKEN --operation-num 127 --finance-login agency-login --dry-run
 direct --sandbox v4account enable-shared-account --client-login client-login
 ```
 
@@ -350,8 +362,12 @@ direct campaigns add --name "Multi-Goal CPA" --start-date 2026-06-01 --type TEXT
 # Notification (Sms/Email) and TimeTargeting accept JSON with WSDL CamelCase keys
 direct campaigns add --name "Notify+Schedule" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
 
+# TrackingParams (campaign-level UTM / tracking query string)
+direct campaigns add --name "UTM" --start-date 2026-06-01 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_campaign={campaign_id}" --dry-run
+
 # Update / lifecycle
 direct campaigns update --id 12345 --name "New Name" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
+direct campaigns update --id 12345 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_medium=cpc" --dry-run
 direct campaigns suspend --id 12345
 direct campaigns resume --id 12345
 direct campaigns archive --id 12345
@@ -1040,8 +1056,12 @@ direct campaigns add --name "Мульти-целевой CPA" --start-date 2026-
 # Notification (Sms/Email) и TimeTargeting принимают JSON с CamelCase ключами WSDL
 direct campaigns add --name "Уведомления+Расписание" --start-date 2026-06-01 --type TEXT_CAMPAIGN --search-strategy HIGHEST_POSITION --network-strategy SERVING_OFF --notification '{"EmailSettings":{"Email":"ops@example.com","SendWarnings":"YES"}}' --time-targeting '{"Schedule":["1A0123456789ABCDEFGHIJKL"],"ConsiderWorkingWeekends":"YES"}' --dry-run
 
+# TrackingParams — UTM/трекинг на уровне кампании (TextCampaign/DynamicTextCampaign/SmartCampaign.TrackingParams)
+direct campaigns add --name "UTM" --start-date 2026-06-01 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_campaign={campaign_id}" --dry-run
+
 # Обновление и управление статусом
 direct campaigns update --id 12345 --name "Новое название" --status SUSPENDED --budget 100000000 --start-date 2024-02-10 --end-date 2024-03-01
+direct campaigns update --id 12345 --type TEXT_CAMPAIGN --tracking-params "utm_source=direct&utm_medium=cpc" --dry-run
 direct campaigns suspend --id 12345
 direct campaigns resume --id 12345
 direct campaigns archive --id 12345

{direct_cli-0.3.10 → direct_cli-0.3.11}/direct_cli/commands/campaigns.py

@@ -601,6 +601,15 @@ def get(
         '({"Schedule":[...], "ConsiderWorkingWeekends":"YES|NO", ...})'
     ),
 )
+@click.option(
+    "--tracking-params",
+    "tracking_params",
+    help=(
+        "Tracking params query-string for "
+        "TextCampaign/DynamicTextCampaign/SmartCampaign.TrackingParams "
+        '(e.g. "utm_source=direct&utm_campaign={campaign_id}")'
+    ),
+)
 @click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
 def add(
@@ -623,6 +632,7 @@ def add(
     bid_ceiling,
     notification_json,
     time_targeting_json,
+    tracking_params,
     dry_run,
 ):
     """Add new campaign"""
@@ -664,12 +674,14 @@ def add(
                 "--setting",
                 "--search-strategy",
                 "--network-strategy",
+                "--tracking-params",
             }
             | text_dynamic_extras,
             "DYNAMIC_TEXT_CAMPAIGN": {
                 "--setting",
                 "--search-strategy",
                 "--network-strategy",
+                "--tracking-params",
             }
             | text_dynamic_extras,
             "SMART_CAMPAIGN": {
@@ -678,6 +690,7 @@ def add(
                 "--network-strategy",
                 "--filter-average-cpc",
                 "--counter-id",
+                "--tracking-params",
             },
         }
         _reject_incompatible_flags(
@@ -695,6 +708,7 @@ def add(
                 "--average-cpa": average_cpa,
                 "--crr": crr,
                 "--bid-ceiling": bid_ceiling,
+                "--tracking-params": tracking_params,
             },
         )
 
@@ -753,6 +767,8 @@ def add(
                 priority_goals_items=priority_goals_items,
                 sub_campaign_block=text_block,
             )
+            if tracking_params:
+                text_block["TrackingParams"] = tracking_params
             campaign_data["TextCampaign"] = text_block
         elif campaign_type_norm == "DYNAMIC_TEXT_CAMPAIGN":
             dyn_block = {
@@ -779,6 +795,8 @@ def add(
                 priority_goals_items=priority_goals_items,
                 sub_campaign_block=dyn_block,
             )
+            if tracking_params:
+                dyn_block["TrackingParams"] = tracking_params
             campaign_data["DynamicTextCampaign"] = dyn_block
         elif campaign_type_norm == "SMART_CAMPAIGN":
             # WSDL SmartCampaignAddItem.CounterId is minOccurs=1
@@ -815,6 +833,8 @@ def add(
                 }
             if parsed_settings:
                 smart_campaign["Settings"] = parsed_settings
+            if tracking_params:
+                smart_campaign["TrackingParams"] = tracking_params
             campaign_data["SmartCampaign"] = smart_campaign
 
         if budget:
@@ -863,9 +883,37 @@ def add(
 @click.option("--budget", type=MICRO_RUBLES, help="New daily budget in micro-rubles")
 @click.option("--start-date", help="New start date (YYYY-MM-DD)")
 @click.option("--end-date", help="New end date (YYYY-MM-DD)")
+@click.option(
+    "--type",
+    "campaign_type",
+    help=(
+        "Campaign subtype "
+        "(TEXT_CAMPAIGN | DYNAMIC_TEXT_CAMPAIGN | SMART_CAMPAIGN). "
+        "Required when updating subtype-specific fields."
+    ),
+)
+@click.option(
+    "--tracking-params",
+    "tracking_params",
+    help=(
+        "Tracking params query-string for "
+        "TextCampaign/DynamicTextCampaign/SmartCampaign.TrackingParams"
+    ),
+)
 @click.option("--dry-run", is_flag=True, help="Show request without sending")
 @click.pass_context
-def update(ctx, campaign_id, name, status, budget, start_date, end_date, dry_run):
+def update(
+    ctx,
+    campaign_id,
+    name,
+    status,
+    budget,
+    start_date,
+    end_date,
+    campaign_type,
+    tracking_params,
+    dry_run,
+):
     """Update campaign"""
     try:
         campaign_data = {"Id": campaign_id}
@@ -886,6 +934,60 @@ def update(ctx, campaign_id, name, status, budget, start_date, end_date, dry_run
         if end_date:
             campaign_data["EndDate"] = end_date
 
+        subtype_supported = {
+            "TEXT_CAMPAIGN",
+            "DYNAMIC_TEXT_CAMPAIGN",
+            "SMART_CAMPAIGN",
+        }
+        campaign_type_norm = (
+            campaign_type.upper().replace("-", "_") if campaign_type else None
+        )
+        subtype_flag_values = {
+            "--tracking-params": tracking_params,
+        }
+        subtype_flags_provided = [
+            flag for flag, value in subtype_flag_values.items() if value is not None
+        ]
+        if (
+            campaign_type_norm is not None
+            and campaign_type_norm not in subtype_supported
+        ):
+            raise click.UsageError(
+                "Invalid value for '--type': "
+                f"{campaign_type!r} is not one of "
+                "'TEXT_CAMPAIGN', 'DYNAMIC_TEXT_CAMPAIGN', 'SMART_CAMPAIGN'."
+            )
+        if subtype_flags_provided and campaign_type_norm is None:
+            raise click.UsageError(
+                f"{', '.join(sorted(subtype_flags_provided))} requires --type "
+                "(TEXT_CAMPAIGN | DYNAMIC_TEXT_CAMPAIGN | SMART_CAMPAIGN)."
+            )
+        if campaign_type_norm is not None:
+            allowed_subtype_flags_by_type = {
+                "TEXT_CAMPAIGN": {"--tracking-params"},
+                "DYNAMIC_TEXT_CAMPAIGN": {"--tracking-params"},
+                "SMART_CAMPAIGN": {"--tracking-params"},
+            }
+            _reject_incompatible_flags(
+                campaign_type_norm,
+                allowed_subtype_flags_by_type[campaign_type_norm],
+                subtype_flag_values,
+            )
+            sub_block: Dict[str, object] = {}
+            if tracking_params:
+                sub_block["TrackingParams"] = tracking_params
+            if not sub_block:
+                raise click.UsageError(
+                    f"--type {campaign_type_norm} requires at least one "
+                    "subtype-specific field to update."
+                )
+            subtype_container = {
+                "TEXT_CAMPAIGN": "TextCampaign",
+                "DYNAMIC_TEXT_CAMPAIGN": "DynamicTextCampaign",
+                "SMART_CAMPAIGN": "SmartCampaign",
+            }[campaign_type_norm]
+            campaign_data[subtype_container] = sub_block
+
         if len(campaign_data) == 1:
             raise click.UsageError("Provide at least one field to update")