Add typed V4 Live finance and shared-account commands

[axisrow]

Summary

Expose the high-priority V4 Live finance and shared-account methods that still have no practical V5 equivalent, using typed Direct CLI commands.

Commands

Implement these commands with typed flags:

• direct v4finance get-clients-units --logins LOGIN[,LOGIN...]
• direct v4finance get-credit-limits --logins LOGIN[,LOGIN...]
• direct v4finance transfer-money --from-login LOGIN --to-login LOGIN --amount AMOUNT --dry-run
• direct v4finance pay-campaigns --campaign-ids IDS --amount AMOUNT --dry-run
• direct v4finance check-payment --payment-id ID
• direct v4account account-management ... --dry-run
• direct v4account enable-shared-account ... --dry-run

Exact flag names should stay canonical: lowercase kebab-case, comma-separated list flags, and explicit typed inputs. Do not add raw JSON passthrough.

Implementation Notes

• Use the V4 foundation helper from the V4 CLI foundation issue.
• Money values stay human-readable at the CLI boundary and convert internally if V4 requires another wire format.
• Mutating commands must support --dry-run and print the exact V4 request body.
• If official V4 docs contradict the vendored SUPPORTED_V4_METHODS, record the finding and mark the method api-status:docs-drift before implementation.
• Do not add GetBalance unless official verification shows it works; current vendored registry notes it was removed with error code 509.

Test Plan

• Dry-run tests assert exact request bodies for mutating commands.
• Unit tests for comma-separated login/campaign ID parsing.
• CLI error tests for missing required flags and invalid money values.
• Mocked adapter tests for successful read commands.

Acceptance Criteria

• All listed commands are registered and documented.
• Mutating commands have --dry-run coverage.
• Invalid inputs fail with Click usage errors before API calls.
• README includes single-line canonical examples.
• Commands are classified in the smoke matrix.

Contract source rule

When this issue touches API contracts, V4 Live methods, request bodies, response shapes, safety classification, or CLI command payloads:

• Treat official Yandex Direct docs and safe live probes as the only authoritative sources for wire shape.
• Do not treat issue examples, guessed param names, or vendored method registries as authoritative by themselves.
• If official docs are missing, 404, ambiguous, disabled, or contradict this issue, stop implementation and record the docs drift before coding.
• Public CLI must stay typed and canonical: no public --json passthrough for user-facing input.
• Mutating or financially sensitive V4 commands stay dry-run-only unless the issue explicitly says otherwise after verification.
• Update direct_cli/v4_contracts.py source status (confirmed-live, docs, undocumented) and add focused tests for exact request bodies.

[axisrow]

Detailed plan — typed V4 Live finance and shared-account commands

Blocked by

#124 (foundation: create_v4_client, build_v4_body, run_v4, group shells).

Commands and exact flag contracts

v4finance get-clients-units --logins LOGIN[,LOGIN...]

• Method: GetClientsUnits.
• Param: {"Logins": [<list>]}.
• Use parse_ids-style helper but for strings → parse_logins.

v4finance get-credit-limits --logins LOGIN[,LOGIN...]

• Method: GetCreditLimits.
• Param: {"Logins": [<list>]}.

v4finance transfer-money --from-login LOGIN --to-login LOGIN --amount AMOUNT [--currency RUB] [--dry-run]

• Method: TransferMoney.
• Param: {"SourceLogin": ..., "DestinationLogin": ..., "Amount": <int micros>, "Currency": ...}.
• Add a money parser parse_money_to_micros(value: str) -> int in direct_cli/v4/money.py. Accept either "100.50" (rubles) or "100500000" (micros) — pick ONE canonical form (rubles by default, document explicitly). Reject negative and zero.

v4finance pay-campaigns --campaign-ids IDS --amount AMOUNT [--currency RUB] [--dry-run]

• Method: PayCampaigns.
• Param: {"CampaignIDS": [<int>], "Amount": <micros>, "Currency": ...}.
• parse_ids from direct_cli/utils.py:17-28 already handles comma-separated IDs.

v4finance check-payment --payment-id ID

• Method: CheckPayment.
• Param: {"PaymentID": <int>}.

v4account account-management --action ACTION --campaign-id ID [--dry-run]

• Method: AccountManagement.
• Param: typed object — verify the WSDL/docs spec for accepted action enum BEFORE coding. If the surface is unclear, leave behind needs:official-verification and fall back to read-only sub-actions only.
• Mutating, so --dry-run is mandatory.

v4account enable-shared-account --master-login LOGIN --slave-logins LOGIN[,LOGIN...] [--dry-run]

• Method: EnableSharedAccount.
• Param: {"MasterLogin": ..., "SlaveLogins": [...]} — verify exact key names against vendored adapter or docs before coding.

Files to create

• direct_cli/commands/v4finance.py — Click group + 5 subcommands above.
• direct_cli/commands/v4account.py — Click group + 2 subcommands above.
• direct_cli/v4/money.py — parse_money_to_micros, format_micros_to_money.

Files to modify

• direct_cli/cli.py — cli.add_command(v4finance) + cli.add_command(v4account) already done in Add V4 Live CLI foundation with typed command groups #124, but re-verify after merge.
• direct_cli/smoke_matrix.py — register every new command:
  • v4finance.get-clients-units, v4finance.get-credit-limits, v4finance.check-payment → SAFE.
  • v4finance.transfer-money, v4finance.pay-campaigns, v4account.* → DANGEROUS (per CLAUDE.md: production money mutations are never auto-tested).
• tests/test_comprehensive.py::TestCommandsRegistered::EXPECTED_COMMANDS — add v4finance, v4account.
• README.md — add canonical single-line example per command in the V4 Live section.

Tests to add

• tests/test_v4finance.py:
  • Dry-run tests: transfer-money and pay-campaigns produce the exact {method, param} body.
  • parse_money_to_micros("100.50") → 100500000. Reject "-1", "0", "abc".
  • --logins a,b,c parses to a list of three.
  • Missing required flags fail with Click usage errors before any API call.
• tests/test_v4account.py:
  • Dry-run tests for account-management and enable-shared-account.
  • Invalid action enum fails with Click usage error.
• tests/test_v4_safety.py:
  • transfer-money and pay-campaigns are classified DANGEROUS in smoke_matrix.py.

Acceptance criteria

• All 7 commands registered, typed, no public --json.
• All mutating commands support --dry-run and tests assert exact bodies.
• Money values use a single canonical input format (rubles), documented in --help and README.
• Smoke matrix classification is correct (DANGEROUS for mutating money commands).
• Default tests are offline.

Verification

pytest -q tests/test_v4finance.py tests/test_v4account.py tests/test_v4_safety.py
direct v4finance transfer-money --from-login a --to-login b --amount 100.50 --dry-run
direct v4finance get-clients-units --logins a,b,c   # needs token

Out of scope (deferred to next milestone tracker)

• PayCampaignsByCard, CreateInvoice — present in SUPPORTED_V4_METHODS but not in this milestone.
• GetBalance — removed by Yandex (error 509). README will state: use direct campaigns get --field-names Funds instead.

Pre-implementation verification (CRITICAL)

For AccountManagement, EnableSharedAccount, TransferMoney, PayCampaigns: read the official Yandex Direct API V4 Live docs for each method and capture the exact param key names + enum values BEFORE writing the typed flags. The vendored SUPPORTED_V4_METHODS only lists the method, not the param schema. If docs disagree with vendored expectations, file a sub-issue with label api-status:docs-drift and resolve before coding.

[axisrow]

Expanded the v4 finance coverage locally with the missing typed commands.

Added:

• direct v4finance get-clients-units --logins LOGIN[,LOGIN...] [--dry-run] [--format json|table|csv|tsv] [--output FILE]
• direct v4finance create-invoice --payment CAMPAIGN_ID=AMOUNT [--payment CAMPAIGN_ID=AMOUNT ...] --currency RUB --master-token MASTER_TOKEN --operation-num N --finance-login LOGIN [--dry-run] [--format json|table|csv|tsv] [--output FILE]
• create-invoice also supports --finance-token as the alternative to --master-token.

Contract notes:

• CreateInvoice sends Payments[].CampaignID/Sum/Currency and injects finance_token / operation_num through the existing v4 adapter top-level fields.
• v4finance.get-clients-units is classified SAFE; v4finance.create-invoice is classified DANGEROUS and has an opt-in live write test guarded by YANDEX_DIRECT_LIVE_FINANCE_WRITE=1.
• PayCampaignsByCard remains undocumented and unexposed.
• The previous check-payment --payment-id wording is superseded by the already live-confirmed --custom-transaction-id contract.

Verification:

• Focused finance/contract/smoke/API coverage tests passed.
• Full suite was attempted but live integration DNS for api.direct.yandex.ru is unavailable from this environment.

[axisrow]

Audit — v4 Live finance & shared-account commands vs. official Yandex Direct docs

Auditing this issue's implementation against the official Yandex Direct API v4 Live docs surfaced three deviations between the CLI and the docs. Two of them are real bugs and now have PRs; one was deliberate and is documented inline.

Findings

1. v4finance get-credit-limits violated docs → fix in PR #233

Official docs (dg-v4/reference/GetCreditLimits) define the request body as {method, finance_token, operation_num} only — no param. The CLI required --logins and shipped param=[logins]. PR #233 removes --logins (breaking change), aligns the v4 contract entry (param_shape=PARAM_OPTIONAL_OBJECT, example_param=None), updates all 7 tests, and patches scripts/test_safe_commands.sh + README + tests/API_COVERAGE.md + CHANGELOG.

2. v4account account-management was incomplete → enhancement in PR #234

Official docs (dg-v4/reference/AccountManagement-docpage) define five Action values: Get, Update, Deposit, Invoice, TransferMoney. The CLI only accepted Update. PR #234 adds the missing four through the existing single-command-with---action pattern (same as the API: one method, five actions). Verbatim docs schema is mirrored: Get → optional SelectionCriteria.Logins (≤50) and/or AccountIDS (≤100); Deposit/Invoice → Payments[].AccountID/Amount/Currency (≤50) with Deposit adding optional Origin="Overdraft" and Contract; TransferMoney → single Transfers[].FromAccountID/ToAccountID/Amount/Currency. Financial sub-actions reuse v4finance's finance-token plumbing 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.

3. v4finance check-payment — no public docs, no change

The method does not appear in _AllMethods.html. The CLI's --custom-transaction-id contract was confirmed live via sandbox probes on 2026-04-30 (see tests/API_COVERAGE.md — PaymentID returns error_code=71; a valid 32-character CustomTransactionID returns error_code=370 "Transaction does not exist", i.e. passes shape validation). No code change in either PR; the discovery context stays documented inline.

Cross-PR notes

• --dry-run-unless---sandbox safety rule preserved for all shared-account mutations.
• Finance-token masking (<redacted>) preserved on every dry-run output.
• Smoke matrix classification unchanged: v4account.account-management is still one WRITE_SANDBOX row (one CLI command = one matrix entry; worst-action dominates).
• Both PRs branch off main independently — they can be reviewed and merged in either order.

Source

• GetClientsUnits, GetCreditLimits, TransferMoney, PayCampaigns, CreateInvoice, AccountManagement Update, AccountManagement Get, AccountManagement Deposit, AccountManagement Invoice, AccountManagement TransferMoney, EnableSharedAccount concept.

Pull requests

• fix(v4finance): get-credit-limits drops --logins per official docs #233 — fix(v4finance): get-credit-limits drops --logins per official docs (breaking)
• feat(v4account): support all 5 AccountManagement actions #234 — feat(v4account): support all 5 AccountManagement actions