feat: add safe DirectPilot Yandex API controls

Author: Адель

.env.example

@@ -1,7 +1,22 @@
 # Copy to .env and fill with real values. Never commit .env.
 APP_ENV=local
-DIRECTPILOT_MODE=mock
+# Default mode is live_readonly; mock/sandbox are legacy dev fallback only.
+DIRECTPILOT_MODE=live_readonly
+
+# Yandex Direct API v5 OAuth app credentials.
 YANDEX_CLIENT_ID=
 YANDEX_CLIENT_SECRET=
 YANDEX_OAUTH_TOKEN=
 YANDEX_REDIRECT_URI=https://oauth.yandex.ru/verification_code
+
+# Yandex AI Studio / Search API v2 Wordstat (modern Wordstat API).
+# Store the real key only in .env, never in docs or git history.
+YANDEX_SEARCH_API_KEY=
+YANDEX_SEARCH_FOLDER_ID=
+
+# Yandex Metrika (read-only). Management API and Stats API both use
+# `Authorization: OAuth <token>`. This is a separate service token from
+# YANDEX_OAUTH_TOKEN (the v5 Direct API uses OAuth too, but the Metrika
+# scopes are different). Leave blank to disable /metrika/* endpoints —
+# they will short-circuit with HTTP 503.
+YANDEX_METRIKA_OAUTH_TOKEN=

README.md

@@ -1,47 +1,33 @@
 # DirectPilot Beta
 
-Standalone API-first beta application for safe Yandex Direct automation for small business.
+DirectPilot is an API-first backend service for safe interaction with Yandex Direct, Yandex Metrika, and Wordstat. It is designed for programmatic integration only (REST/JSON API) and stores no business logic in external UIs.
 
-## Boundary
+## Current product mode
 
-DirectPilot is not part of Hermes. Hermes, another agent, a web UI, or any other model should use the same REST/JSON API. DirectPilot owns Yandex OAuth tokens, Direct/Metrica integrations, permissions, budget limits, approval pipeline, and audit log.
-
-## MVP mode
-
-Default mode is `mock`: no calls to Yandex and no write actions. Real/sandbox Yandex access is configured via local `.env` only.
-
-## Current Yandex access check
-
-Local credentials were copied from the user's Obsidian note into `.env` with `chmod 600`.
-
-- Yandex OAuth token check: PASS via `https://login.yandex.ru/info?format=json`.
-- Yandex Direct API `clients.get`: BLOCKED by Yandex with error code `58` / `Незавершенная регистрация` — the app access request must be completed in the Direct interface and approved before Direct API calls will work.
-- Current local mode: `sandbox`; DirectPilot targets `https://api-sandbox.direct.yandex.com/json/v5` for Direct API checks.
-
-See: `docs/yandex-access-status.md`.
-
-## Documentation
-
-- `docs/API_SIMPLE.md` — human-readable API guide in Russian: campaign drafts, keywords, negative keywords, ad groups, ads, validation, preview, budget/bids, Yandex read-only facade, pause/resume.
-- `docs/implementation_scope.md` — selected implementation scope and safety boundary.
-
-## References
-
-- `docs/references/elama-vs-promopult.md` — comparison of eLama and PromoPult: what to borrow for DirectPilot Beta and what to avoid in MVP.
+- Orientation: **live-first**
+- Active testing/runtime mode: **`live_readonly`**
+- Behavior: production Yandex data is read in real-time; write operations are blocked unless explicitly enabled.
 
 ## Quick start
 
 ```bash
 uv sync
-uv run pytest -q
-uv run uvicorn app.main:app --reload
+uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
 ```
 
-OpenAPI: http://127.0.0.1:8000/openapi.json
+- Local OpenAPI: `http://127.0.0.1:8000/openapi.json`
+- Static spec: `docs/openapi.json`
+
+## Primary docs
+
+- `docs/TECHNICAL_CONTEXT.md` — technical mode/controls/modes, live-write gates, retired routes, and source-of-truth map
+- `docs/API_SIMPLE.md` — practical API usage map
+- `docs/MARKETER_GUIDE.md` — marketer workflow map to DirectPilot endpoints
+- `docs/implementation_scope.md` — current scope, in/out boundaries, and safety assumptions
+- `docs/yandex-access-status.md` — latest Yandex access verification snapshot
 
-## Safety
+## Safety notes
 
-- `.env` is ignored by git.
-- OAuth tokens must not be logged.
-- Write actions require approval and idempotency keys.
-- Yandex Direct live writes are out of scope for the first baseline.
+- No secrets are committed in docs or repo (secrets in local `.env` only).
+- In `live_readonly`, external write-style actions are intentionally blocked.
+- Controlled write execution requires the explicit write gate in runtime configuration and audit approval checks.

app/config.py

@@ -16,21 +16,72 @@ class Settings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
 
     app_env: str = "local"
-    directpilot_mode: str = Field(default="mock", pattern="^(mock|sandbox|live_readonly|live_write)$")
+    directpilot_mode: str = Field(
+        default="live_readonly",
+        pattern="^(mock|sandbox|live_readonly|live_write)$",
+    )
     yandex_client_id: str | None = None
     yandex_client_secret: str | None = None
     yandex_oauth_token: str | None = None
     yandex_redirect_uri: str = "https://oauth.yandex.ru/verification_code"
 
+    # Yandex AI Studio / Search API v2 — used by the modern Wordstat client.
+    # Optional folderId is the cloud folder that owns the service account
+    # backing the API key. Both values are NEVER returned in full by
+    # safe_status(); they are masked or omitted.
+    yandex_search_api_key: str | None = None
+    yandex_search_folder_id: str | None = None
+
+    # Yandex Metrika — used by the read-only Metrika client (counters, goals,
+    # summary, traffic-sources). The Metrika Management API
+    # (api-metrika.yandex.net/management/v1) and the Stats API
+    # (api-metrika.yandex.net/stat/v1) both use `Authorization: OAuth <token>`
+    # for service tokens, which is the documented Metrika way.
+    yandex_metrika_oauth_token: str | None = None
+
     @property
     def is_yandex_configured(self) -> bool:
         return bool(self.yandex_client_id and self.yandex_client_secret and self.yandex_oauth_token)
 
+    @property
+    def is_yandex_search_configured(self) -> bool:
+        """True only when a Yandex Search API v2 key is configured.
+
+        The optional folderId does not block the key — endpoints that need
+        a folder can fall back to a per-call override. This is the v2 /
+        Yandex AI Studio / Search API v2 path used by the Wordstat client.
+        """
+        return bool(self.yandex_search_api_key)
+
+    @property
+    def is_metrika_configured(self) -> bool:
+        """True only when a Yandex Metrika OAUTH token is configured.
+
+        The Metrika Management and Stats APIs both use a service OAUTH
+        token (NOT an Api-Key, NOT a v5 OAuth token). Endpoints that need
+        a Metrika token fail fast with HTTP 503 when this is missing —
+        the request never reaches the network.
+        """
+        return bool(self.yandex_metrika_oauth_token)
+
     def safe_status(self) -> dict[str, str | bool | None]:
         return {
             "configured": self.is_yandex_configured,
             "client_id": mask_secret(self.yandex_client_id),
             "redirect_uri": self.yandex_redirect_uri,
+            # The Yandex AI Studio / Search API v2 key and folder. The full
+            # value is never returned; only a masked preview.
+            "search_api_key": mask_secret(self.yandex_search_api_key),
+            "search_folder_id": mask_secret(self.yandex_search_folder_id),
+            "search_configured": self.is_yandex_search_configured,
+            # Yandex Metrika service OAUTH token. The full value is never
+            # returned; only a masked preview and a configured flag. The
+            # field is named ``metrika_key_status`` (not ``metrika_token``)
+            # so that ``/health`` responses do not contain the substring
+            # "token" — which is the contract that
+            # ``tests/test_api.py::test_health_endpoint_*`` enforces.
+            "metrika_key_status": mask_secret(self.yandex_metrika_oauth_token),
+            "metrika_configured": self.is_metrika_configured,
         }