direct-cli 0.2.2__tar.gz → 0.2.5__tar.gz

{direct_cli-0.2.2 → direct_cli-0.2.5}/.env.example

@@ -1,6 +1,12 @@
 YANDEX_DIRECT_TOKEN=your_access_token_here
 YANDEX_DIRECT_LOGIN=your_yandex_login_here
 
+# The same OAuth token also works against the Yandex Direct sandbox
+# (https://api-sandbox.direct.yandex.com) — no separate sandbox token is
+# required. Use the ``--sandbox`` CLI flag to route calls there, or run
+# ``pytest -m integration_write --record-mode=rewrite`` to re-record
+# the sandbox VCR cassettes under ``tests/cassettes/``.
+
 # 1Password secret references (optional, used as fallback)
 # YANDEX_DIRECT_OP_TOKEN_REF=op://vault/item/token
 # YANDEX_DIRECT_OP_LOGIN_REF=op://vault/item/login

direct_cli-0.2.5/.github/copilot-instructions.md

@@ -0,0 +1,91 @@
+# Copilot Instructions — Direct CLI
+
+Command-line interface for the Yandex Direct API, built with Python and Click.
+
+## Commands
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run all unit tests
+pytest
+
+# Run integration tests (requires .env with real token)
+pytest -m integration -v
+
+# Run a single test
+pytest tests/test_cli.py::TestCLI::test_cli_help
+
+# Run tests matching pattern
+pytest -k "campaigns"
+
+# Format
+black .
+
+# Lint
+flake8 direct_cli tests
+```
+
+## Architecture
+
+The CLI is a Click group-of-groups. Each API resource maps to one file in `direct_cli/commands/` that defines a Click group (e.g. `campaigns`) with subcommands (`get`, `add`, `update`, `delete`, etc.). All groups are imported and registered in `direct_cli/cli.py`.
+
+Request flow: `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex Direct API → `output.py` (format and print).
+
+`utils.py` holds shared helpers: `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`. All command modules import from these; don't duplicate logic there.
+
+## Key Conventions
+
+**Adding a new command module:**
+1. Create `direct_cli/commands/<resource>.py` with a `@click.group()` and subcommands.
+2. Import and register it in `direct_cli/cli.py` with `cli.add_command(...)`.
+3. Add the command name to `TestCommandsRegistered.EXPECTED_COMMANDS` in `tests/test_comprehensive.py`.
+
+**`--dry-run` flag:** `add` and `update` commands support `--dry-run` — they print the request body as JSON without making an API call. Use this as a test seam: these subcommands can be tested without mocking the HTTP layer.
+
+**SelectionCriteria requirements:** Some resources (`adgroups`, `ads`, `keywords`) require at least one of `Ids`, `CampaignIds`, or `AdGroupIds` in `SelectionCriteria`. Calling `get` without any filter raises API error 4001. Integration tests handle this by fetching a campaign ID first via `get_first_campaign_id()`.
+
+**Default fields in `utils.py`:** `COMMON_FIELDS` maps resource names to default `FieldNames`. Not all fields are valid for all resources — for example, `adimages` uses `AdImageHash` (not `Id`) as its key, and neither `clients` nor `creatives` accept `Status`. When adding a resource, verify field names against the Yandex Direct API docs.
+
+**Error handling in commands:** All command functions wrap API calls in `try/except Exception` and call `print_error(str(e))` + `raise click.Abort()`. Keep this pattern consistent.
+
+**Test types:**
+- Unit tests (`tests/test_cli.py`, `tests/test_comprehensive.py`) — no API calls, run without a token.
+- Integration tests (`tests/test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if token is absent.
+
+**Credentials:** `.env` in the project root. `YANDEX_DIRECT_LOGIN` is the Yandex advertiser login (required). `load_dotenv()` is called at `cli.py` module import, so it is loaded before any Click invocation.
+
+## Dangerous Commands — Do Not Auto-Test
+
+Never invoke these commands in automated tests against a real account.
+
+### 🔴 Irreversible — permanently destroy data
+| Command | Risk |
+|---------|------|
+| `campaigns delete` | Permanently deletes a campaign and all its content |
+| `adgroups delete` | Permanently deletes an ad group and its ads/keywords |
+| `ads delete` | Permanently deletes an ad |
+| `keywords delete` | Permanently deletes a keyword |
+| `audiencetargets delete` | Permanently deletes an audience target |
+
+### 🟠 Financial impact — change bids or spending
+| Command | Risk |
+|---------|------|
+| `bids set` | Changes search/network bids on campaigns — direct cost impact |
+| `keywordbids set` | Changes per-keyword bids |
+| `bidmodifiers set` | Changes bid multipliers (device, region, time, etc.) |
+
+### 🟡 Reversible but affect live traffic
+`campaigns suspend/resume/archive/unarchive`, `ads suspend/resume/archive/unarchive`, `keywords suspend/resume/archive/unarchive`, `audiencetargets suspend/resume`
+
+### 🟡 Account-wide mutations
+`clients update` — modifies account-level settings.
+
+### 🟡 Content creation (hard to clean up in bulk)
+All `add` and `update` subcommands across: `campaigns`, `adgroups`, `ads`, `keywords`, `feeds`, `retargeting`, `sitelinks`, `turbopages`, `vcards`, `adextensions`, `negativekeywordsharedsets`, `smartadtargets`, `dynamicads`, `audiencetargets`.
+
+These can be safely tested using `--dry-run` (outputs the request body as JSON without sending it).
+
+### ✅ Safe to auto-test (read-only, no side effects)
+All `get` subcommands, plus: `changes check*`, `dictionaries list-names`, `keywordsresearch has-search-volume`, `reports list-types`.

direct_cli-0.2.5/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # 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
+

direct_cli-0.2.5/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # 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: '--allowed-tools Bash(gh pr:*)'
+

direct_cli-0.2.5/.gitignore

@@ -0,0 +1,57 @@
+# Byte-compiled / optimized / DLLs
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64
+parts/
+sdist/
+*.egg-info/
+.installed.txt
+pip-log.txt
+Pipfile
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox
+.coverate
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+
+# Environments
+.env
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.log
+*.bak
+*.orig

direct_cli-0.2.5/AGENTS.md

@@ -0,0 +1,382 @@
+# AGENTS.md - Guidelines for AI Coding Agents
+
+This document provides essential information for AI coding agents working on the Direct CLI codebase.
+
+## Project Overview
+
+Direct CLI is a command-line interface for the Yandex Direct API, built with Python and Click. It provides commands for managing campaigns, ad groups, ads, keywords, reports, and other Yandex Direct resources.
+
+## Build, Test, and Lint Commands
+
+### Installation
+
+```bash
+# Install package in development mode
+pip install -e .
+
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run all tests with verbose output
+pytest -v
+
+# Run a single test file
+pytest tests/test_cli.py
+
+# Run a single test by name
+pytest tests/test_cli.py::TestCLI::test_cli_help
+
+# Run tests matching a pattern
+pytest -k "campaigns"
+
+# Run tests with coverage
+pytest --cov=direct_cli
+
+# Run tests with coverage report
+pytest --cov=direct_cli --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Format code with Black
+black .
+
+# Format specific files
+black direct_cli/ tests/
+
+# Check formatting without changes
+black --check .
+
+# Lint with flake8
+flake8 direct_cli tests
+
+# Lint specific file
+flake8 direct_cli/cli.py
+```
+
+### Building
+
+```bash
+# Build package
+python -m build
+
+# Build wheel only
+pip wheel . --no-deps -w dist/
+```
+
+## Code Style Guidelines
+
+### Import Organization
+
+Organize imports in three groups, separated by blank lines:
+
+```python
+# 1. Standard library imports (alphabetical)
+import json
+import os
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+# 2. Third-party imports (alphabetical)
+import click
+from dotenv import load_dotenv
+
+# 3. Local imports (alphabetical)
+from .api import create_client
+from .auth import get_credentials
+from .output import format_output, print_error
+from .utils import parse_ids, build_selection_criteria
+```
+
+### Type Hints
+
+Always use type hints for function parameters and return values:
+
+```python
+def parse_ids(ids_str: Optional[str]) -> Optional[List[int]]:
+    """Parse comma-separated IDs"""
+    if not ids_str:
+        return None
+    return [int(x.strip()) for x in ids_str.split(",")]
+
+
+def create_client(
+    token: Optional[str] = None,
+    login: Optional[str] = None,
+    sandbox: bool = False,
+) -> YandexDirect:
+    """Create YandexDirect client"""
+    ...
+```
+
+### Docstrings
+
+Use descriptive docstrings with Args, Returns, and Raises sections:
+
+```python
+def get_credentials(
+    token: Optional[str] = None,
+    login: Optional[str] = None,
+    env_path: Optional[str] = None,
+) -> Tuple[str, Optional[str]]:
+    """
+    Get credentials with priority:
+    1. Direct arguments
+    2. Environment variables
+    3. .env file
+
+    Args:
+        token: API access token
+        login: Client login (for agency accounts)
+        env_path: Path to .env file
+
+    Returns:
+        Tuple of (token, login)
+
+    Raises:
+        ValueError: If token is not provided
+    """
+    ...
+```
+
+### Naming Conventions
+
+- **Functions and variables**: `snake_case`
+- **Classes**: `PascalCase`
+- **Constants**: `UPPER_SNAKE_CASE`
+- **CLI command names**: `kebab-case` (e.g., `get-campaigns`, `add-adgroup`)
+
+### Error Handling
+
+Use try/except blocks with `print_error()` and `raise click.Abort()`:
+
+```python
+try:
+    client = create_client(
+        token=ctx.obj.get("token"),
+        login=ctx.obj.get("login"),
+        sandbox=ctx.obj.get("sandbox"),
+    )
+    result = client.campaigns().post(data=body)
+    format_output(result().extract(), output_format, output)
+except Exception as e:
+    print_error(str(e))
+    raise click.Abort()
+```
+
+### Click Command Structure
+
+Use Click decorators consistently:
+
+```python
+@click.group()
+def campaigns():
+    """Manage campaigns"""
+    pass
+
+
+@campaigns.command()
+@click.option("--ids", help="Comma-separated campaign IDs")
+@click.option("--status", help="Filter by status")
+@click.option("--limit", type=int, help="Limit number of results")
+@click.pass_context
+def get(ctx, ids, status, limit):
+    """Get campaigns"""
+    ...
+```
+
+## Project Structure
+
+```
+direct-cli/
+├── direct_cli/           # Main package
+│   ├── __init__.py       # Package initialization
+│   ├── cli.py            # Main CLI entry point
+│   ├── api.py            # YandexDirect API client wrapper
+│   ├── auth.py           # Authentication module
+│   ├── utils.py          # Utility functions
+│   ├── output.py         # Output formatting (json, table, csv, tsv)
+│   └── commands/         # Command modules by resource
+│       ├── __init__.py
+│       ├── campaigns.py
+│       ├── adgroups.py
+│       ├── ads.py
+│       ├── keywords.py
+│       ├── reports.py
+│       └── ...           # Other resource commands
+├── tests/                # Test directory
+│   ├── __init__.py
+│   └── test_cli.py
+├── pyproject.toml        # Project configuration
+└── README.md             # User documentation
+```
+
+## Key Patterns
+
+### Creating a New Command Module
+
+1. Create a new file in `direct_cli/commands/`
+2. Define a Click group with commands
+3. Register in `direct_cli/cli.py`
+
+```python
+# direct_cli/commands/newresource.py
+import click
+from ..api import create_client
+from ..output import format_output, print_error
+
+
+@click.group()
+def newresource():
+    """Manage new resource"""
+    pass
+
+
+@newresource.command()
+@click.pass_context
+def get(ctx):
+    """Get new resource"""
+    try:
+        client = create_client(
+            token=ctx.obj.get("token"),
+            login=ctx.obj.get("login"),
+            sandbox=ctx.obj.get("sandbox"),
+        )
+        # ... API call
+        format_output(data, "json", None)
+    except Exception as e:
+        print_error(str(e))
+        raise click.Abort()
+```
+
+Then register in `cli.py`:
+
+```python
+from .commands.newresource import newresource
+cli.add_command(newresource)
+```
+
+### Output Formatting
+
+Use `format_output()` for consistent output:
+
+```python
+from ..output import format_output
+
+# JSON output (default)
+format_output(data, "json", None)
+
+# Table output
+format_output(data, "table", None)
+
+# CSV/TSV to file
+format_output(data, "csv", "output.csv")
+format_output(data, "tsv", "output.tsv")
+```
+
+### Pagination
+
+For large result sets, use `--fetch-all` flag:
+
+```python
+if fetch_all:
+    items = []
+    for item in result().iter_items():
+        items.append(item)
+    format_output(items, output_format, output)
+else:
+    data = result().extract()
+    format_output(data, output_format, output)
+```
+
+## Code Formatting Standards
+
+- **Line length**: 88 characters (Black default)
+- **String quotes**: Prefer double quotes (`"`)
+- **Indentation**: 4 spaces (no tabs)
+- **Blank lines**: 
+  - 2 blank lines before class/function definitions at module level
+  - 1 blank line between methods
+  - 1 blank line between logical sections within functions
+
+## Testing Guidelines
+
+### Test Structure
+
+```python
+import unittest
+from click.testing import CliRunner
+from direct_cli.cli import cli
+
+
+class TestCLI(unittest.TestCase):
+    """Test CLI commands"""
+
+    def setUp(self):
+        self.runner = CliRunner()
+
+    def test_command_help(self):
+        """Test command help"""
+        result = self.runner.invoke(cli, ["command", "--help"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("expected text", result.output)
+```
+
+### Test Naming
+
+- Test files: `test_*.py`
+- Test classes: `Test*`
+- Test methods: `test_*`
+
+## Dependencies
+
+Main dependencies (see `pyproject.toml`):
+- `tapi-yandex-direct` - Yandex Direct API wrapper
+- `click` - CLI framework
+- `python-dotenv` - Environment variable management
+- `tabulate` - Table formatting
+- `colorama` - Terminal colors
+- `tqdm` - Progress bars
+
+Development dependencies:
+- `pytest` - Testing framework
+- `pytest-cov` - Coverage plugin
+- `black` - Code formatter
+- `flake8` - Linter
+
+## Common Tasks
+
+### Adding a New CLI Option
+
+```python
+@campaigns.command()
+@click.option("--new-option", help="Description of new option")
+@click.pass_context
+def get(ctx, new_option):
+    """Get campaigns"""
+    if new_option:
+        # Handle option
+        pass
+```
+
+### Adding a New Output Format
+
+1. Add format function in `output.py`
+2. Update `format_output()` to handle new format type
+3. Update `--format` option help text in commands
+
+## Important Notes
+
+- Always handle missing credentials gracefully with helpful error messages
+- Use `--dry-run` flag for operations that modify data
+- Support pagination for list operations with `--fetch-all` and `--limit`
+- Maintain backward compatibility when changing command signatures
+- Test changes with both sandbox and production API when possible

direct_cli-0.2.5/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+CLI for the Yandex Direct API, built with Python and Click. Installed via pip, published to PyPI.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"              # Install in dev mode
+pytest                               # Unit tests (no token needed)
+pytest -m integration -v             # Integration tests (needs .env with token)
+pytest tests/test_cli.py::TestCLI::test_cli_help  # Single test
+pytest -k "campaigns"                # Pattern match
+black .                              # Format
+flake8 direct_cli tests              # Lint
+```
+
+## Architecture
+
+Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli/commands/` with a Click group and subcommands (`get`, `add`, `update`, `delete`, `suspend`, `resume`, etc.). All groups registered in `direct_cli/cli.py` via `cli.add_command()`.
+
+**Request flow:** `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex API → `output.py` (format/print).
+
+**Credentials priority:** CLI flags (`--token`, `--login`) > env vars (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > `.env` file. `load_dotenv()` runs at `cli.py` import time.
+
+**Shared utilities** (`utils.py`): `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`, `COMMON_FIELDS` dict. All command modules import from here — don't duplicate.
+
+**Output** (`output.py`): `format_output()` supports json (default), table, csv, tsv. Colored helpers: `print_success`, `print_error`, `print_warning`, `print_info`.
+
+## Key Conventions
+
+**Adding a new command module:**
+1. Create `direct_cli/commands/<resource>.py` with `@click.group()` + subcommands.
+2. Register in `cli.py` with `cli.add_command(...)`.
+3. Add command name to `TestCommandsRegistered.EXPECTED_COMMANDS` in `tests/test_comprehensive.py`.
+
+**`--dry-run`:** `add`/`update` commands print request JSON without calling the API. Use as test seam.
+
+**SelectionCriteria:** Resources like `adgroups`, `ads`, `keywords` require at least one of `Ids`, `CampaignIds`, or `AdGroupIds` — otherwise API error 4001.
+
+**Error handling:** All commands wrap API calls in `try/except Exception` → `print_error(str(e))` + `raise click.Abort()`.
+
+**Default fields:** `COMMON_FIELDS` in `utils.py` maps resource names to `FieldNames`. Not all fields are valid for all resources (e.g., `adimages` uses `AdImageHash`, not `Id`).
+
+## Tests
+
+- **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.
+- **Integration** (`test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if absent.
+
+## Dangerous Commands — Never Auto-Test
+
+- **Irreversible (delete):** `campaigns/adgroups/ads/keywords/audiencetargets delete`
+- **Financial:** `bids set`, `keywordbids set`, `bidmodifiers set`
+- **Live traffic:** `suspend/resume/archive/unarchive` on campaigns, ads, keywords
+- **Mutations:** all `add`/`update` subcommands (test with `--dry-run`)
+- **Safe (read-only):** all `get` subcommands, `changes check*`, `dictionaries list-names`, `keywordsresearch has-search-volume`, `reports list-types`