sv-cli 0.3.0__py3-none-any.whl

sv_cli/__init__.py

@@ -0,0 +1,3 @@
+"""SV CLI package."""
+
+__version__ = "0.3.0"

sv_cli/adapters.py

@@ -0,0 +1,323 @@
+"""Local command adapters.
+
+Adapters intentionally contain only human-friendly command metadata. Endpoints,
+required fields, and enums are still discovered from SV API definitions
+at runtime whenever possible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ToolAdapter:
+    canonical: str
+    command: str
+    aliases: tuple[str, ...] = ()
+    default_action: str = "run"
+    actions: tuple[str, ...] = ("run",)
+    field_aliases: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    option_aliases: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    async_likely: bool = False
+    # Optional local discovery hints. These are used only when the live API root
+    # has not yet exposed a known tool. The API root remains the source of truth
+    # and overrides these values whenever it contains the tool.
+    endpoint_path: str | None = None
+    definitions_path: str | None = None
+
+
+COMMON_FIELD_ALIASES: dict[str, tuple[str, ...]] = {
+    "keyword": ("keyword", "kw", "query", "seed_keyword"),
+    "keywords": ("keywords", "kws", "keyword_list", "kwlist"),
+    "url": ("url", "domain", "page_url", "website"),
+    "url_a": ("url_a", "urla", "url1", "first_url", "competitor_url"),
+    "url_b": ("url_b", "urlb", "url2", "second_url", "comparison_url"),
+    "brand": ("brand", "brand_name", "company", "company_name"),
+    "type": ("contenttype", "content_type", "imagetype", "image_type", "type"),
+    "language": ("language", "lang", "language_id"),
+    "engine": ("engine", "ai_engine", "model"),
+    "country": ("country", "country_code", "location", "gl"),
+    "location": ("location", "geo", "country", "market"),
+    "text": ("text", "content", "input", "body"),
+    "search": ("searchterm", "search_term", "search", "query", "term"),
+    "query": ("searchterm", "search_term", "query", "search", "term"),
+    "price": ("price", "max_price", "price_ceiling"),
+    "series": ("series", "service_series"),
+    "category": ("category", "service_category"),
+    "outline": ("outline", "outline_text"),
+    "theme": ("theme", "image_theme"),
+    "background": ("background", "bg", "image_background"),
+    "color": ("color", "colour", "palette"),
+    "size": ("size", "image_size", "dimensions"),
+}
+
+TOOL_ADAPTERS: dict[str, ToolAdapter] = {
+    "better-keywords": ToolAdapter(
+        canonical="better-keywords",
+        command="better-keywords",
+        aliases=("keywords",),
+        default_action="research",
+        actions=("research", "filter", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "types": ("researchtype", "research_type", "type", "types"),
+            "languages": ("lang", "language", "languages"),
+            "competition": ("kwcompetition", "kw_competition", "competition"),
+        },
+    ),
+    "content-transformer": ToolAdapter(
+        canonical="content-transformer",
+        command="content-transformer",
+        aliases=("transform",),
+        default_action="rewrite",
+        actions=("rewrite", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "types": ("type", "types", "contenttype", "content_type"),
+            "lengths": ("length", "lengths"),
+            "languages": ("lang", "language", "languages"),
+            "engines": ("engine", "model", "engines"),
+        },
+    ),
+    "core-analysis": ToolAdapter(
+        canonical="core-analysis",
+        command="core-analysis",
+        aliases=("core",),
+        default_action="analyze",
+        actions=("analyze", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+    ),
+    "geogptaudit": ToolAdapter(
+        canonical="geogptaudit",
+        command="geo-audit",
+        aliases=("geogpt-audit", "audit"),
+        default_action="create-task",
+        actions=("create-task", "get-task-status", "get-result", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        async_likely=True,
+        option_aliases={
+            "types": ("scantype", "scan_type", "type", "types"),
+            "languages": ("lang", "language", "languages"),
+        },
+    ),
+    "insight-igniter": ToolAdapter(
+        canonical="insight-igniter",
+        command="insight-igniter",
+        aliases=("insights",),
+        default_action="entities",
+        actions=("entities", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "languages": ("lang", "language", "languages"),
+        },
+    ),
+    "preliminaryaudit": ToolAdapter(
+        canonical="preliminaryaudit",
+        command="preliminary-audit",
+        aliases=("prelim-audit",),
+        default_action="analyze",
+        actions=("analyze", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+    ),
+    "ranklens": ToolAdapter(
+        canonical="ranklens",
+        command="ranklens",
+        aliases=(),
+        default_action="rank",
+        actions=("rank", "competitors", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "languages": ("lang", "language", "languages"),
+            "engines": ("engine", "model", "engines"),
+            "sample-sizes": ("samplesize", "sample_size", "samplesize"),
+        },
+    ),
+    "seo-image": ToolAdapter(
+        canonical="seo-image",
+        command="seo-image",
+        aliases=("image",),
+        default_action="generate",
+        actions=("generate", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "types": ("imagetype", "image_type", "type", "types"),
+            "themes": ("imagetheme", "image_theme", "theme", "themes"),
+            "backgrounds": ("background", "imagebackground", "backgrounds"),
+            "colors": ("primarycolor", "primary_color", "color", "colors"),
+            "secondary-colors": ("secondarycolor", "secondary_color", "secondarycolor"),
+            "sizes": ("imagesize", "image_size", "size", "sizes"),
+            "languages": ("lang", "language", "languages"),
+            "engines": ("engine", "model", "engines"),
+        },
+    ),
+    "seogpt": ToolAdapter(
+        canonical="seogpt",
+        command="seogpt",
+        aliases=("seo-gpt",),
+        default_action="generate",
+        actions=("generate", "raw"),
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            "contenttype": ("type", "contenttype", "content_type"),
+        },
+        option_aliases={
+            "types": ("type", "types", "contenttype", "content_type"),
+            "languages": ("lang", "language", "languages"),
+            "engines": ("engine", "model", "engines"),
+        },
+    ),
+    "seogpt2": ToolAdapter(
+        canonical="seogpt2",
+        command="seogpt2",
+        aliases=("seo-gpt2",),
+        default_action="create-task",
+        actions=("create-task", "get-task-status", "get-result", "raw"),
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            "keyword": ("Topic", "topic", "kw", "keyword", "query", "seed_keyword"),
+            "text": ("Topic", "topic", "text", "content", "input", "body"),
+        },
+        async_likely=True,
+        option_aliases={
+            "types": ("contenttype", "content_type", "type", "types"),
+            "lengths": ("contentlength", "content_length", "length", "lengths"),
+            "languages": ("language", "lang", "languages"),
+            "tones": ("tone", "tones"),
+            "persons": ("person", "persons"),
+            "writers": ("writer", "writers"),
+            "engines": ("engine", "model", "engines"),
+            "pathways": ("pathway", "pathways"),
+        },
+    ),
+    "seogptcompare": ToolAdapter(
+        canonical="seogptcompare",
+        command="seogpt-compare",
+        aliases=("compare",),
+        default_action="create-task",
+        actions=("create-task", "get-task-status", "get-result", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        async_likely=True,
+        option_aliases={
+            "languages": ("lang", "language", "languages"),
+            "countries": ("country", "countries"),
+        },
+    ),
+    "seogptmapping": ToolAdapter(
+        canonical="seogptmapping",
+        command="seo-mapping",
+        aliases=("mapping",),
+        default_action="create-task",
+        actions=("create-task", "get-task-status", "get-result", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        async_likely=True,
+        option_aliases={
+            "types": ("scantype", "scan_type", "type", "types"),
+            "languages": ("lang", "language", "languages"),
+        },
+    ),
+    "topical-authority": ToolAdapter(
+        canonical="topical-authority",
+        command="topical-authority",
+        aliases=("topical",),
+        default_action="topics",
+        actions=("topics", "content", "raw"),
+        field_aliases=COMMON_FIELD_ALIASES,
+        option_aliases={
+            "modes": ("topicmode", "topic_mode", "mode", "modes"),
+            "languages": ("lang", "language", "languages"),
+            "sizes": ("topicsize", "topic_size", "size", "sizes"),
+        },
+    ),
+    "top-competitors": ToolAdapter(
+        canonical="top-competitors",
+        command="top-competitors",
+        aliases=("competitors",),
+        default_action="analyze",
+        actions=("analyze", "raw"),
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            "keyword": ("kw", "keyword", "query", "seed_keyword"),
+        },
+        endpoint_path="top-competitors/",
+        definitions_path="top-competitors/definitions",
+    ),
+    "marketplace-services": ToolAdapter(
+        canonical="marketplace-services",
+        command="marketplace-services",
+        aliases=("marketplace", "services"),
+        default_action="search",
+        actions=("search", "raw"),
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            "keyword": ("searchterm", "search_term", "kw", "keyword", "query"),
+            "search": ("searchterm", "search_term", "search", "query", "term"),
+            "query": ("searchterm", "search_term", "query", "search", "term"),
+        },
+        option_aliases={
+            "series": ("series", "service_series"),
+            "categories": ("category", "service_category", "categories"),
+        },
+        endpoint_path="marketplace-services/",
+        definitions_path="marketplace-services/definitions",
+    ),
+    "content-quality": ToolAdapter(
+        canonical="content-quality",
+        command="content-quality",
+        aliases=("quality", "hcu-quality", "eeat-quality"),
+        default_action="analyze",
+        actions=("analyze", "raw"),
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            "keyword": ("kw", "keyword", "query", "seed_keyword"),
+            "url": ("url1", "url", "domain", "page_url", "website"),
+            "url_a": ("url1", "url_a", "urla", "first_url"),
+            "url_b": ("url2", "url_b", "urlb", "second_url", "comparison_url"),
+        },
+        endpoint_path="content-quality/",
+        definitions_path="content-quality/definitions",
+    ),
+}
+
+
+
+def all_command_names() -> dict[str, str]:
+    """Return command/alias -> adapter canonical mapping."""
+
+    names: dict[str, str] = {}
+    for canonical, adapter in TOOL_ADAPTERS.items():
+        names[adapter.command] = canonical
+        names[canonical] = canonical
+        for alias in adapter.aliases:
+            names[alias] = canonical
+    return names
+
+
+def get_adapter(tool: str) -> ToolAdapter | None:
+    return TOOL_ADAPTERS.get(tool)
+
+
+def field_candidates(tool: str, cli_field: str) -> tuple[str, ...]:
+    adapter = TOOL_ADAPTERS.get(tool)
+    if adapter and cli_field in adapter.field_aliases:
+        return adapter.field_aliases[cli_field]
+    return COMMON_FIELD_ALIASES.get(cli_field, (cli_field,))
+
+
+def tool_display_name(canonical: str) -> str:
+    adapter = TOOL_ADAPTERS.get(canonical)
+    return adapter.command if adapter else canonical
+
+
+def adapter_as_dict(adapter: ToolAdapter) -> dict[str, Any]:
+    return {
+        "canonical": adapter.canonical,
+        "command": adapter.command,
+        "aliases": list(adapter.aliases),
+        "default_action": adapter.default_action,
+        "actions": list(adapter.actions),
+        "async_likely": adapter.async_likely,
+        "endpoint_path": adapter.endpoint_path,
+        "definitions_path": adapter.definitions_path,
+    }

sv_cli/api_client.py

@@ -0,0 +1,82 @@
+"""HTTP client for SV API calls."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from rich.console import Console
+
+from .errors import APIError, NetworkError, TimeoutError
+from .utils import mask_mapping
+
+
+@dataclass
+class APIResponse:
+    data: Any
+    status_code: int
+    elapsed_seconds: float
+    url: str
+
+
+class APIClient:
+    def __init__(self, *, debug: bool = False, console: Console | None = None) -> None:
+        self.debug = debug
+        self.console = console or Console(stderr=True)
+
+    def request_tool(
+        self,
+        *,
+        endpoint: str,
+        payload: dict[str, Any],
+        api_key: str | None,
+        method: str = "POST",
+        timeout: float = 60.0,
+    ) -> APIResponse:
+        final_payload = dict(payload)
+        if api_key and not any(key in final_payload for key in ("k", "api_key", "apikey", "key")):
+            final_payload["k"] = api_key
+
+        method = method.upper()
+        if self.debug:
+            parsed = urlparse(endpoint)
+            shown_path = parsed.path or endpoint
+            self.console.print(f"[dim]{method} {shown_path}[/dim]")
+            self.console.print_json(json.dumps(mask_mapping(final_payload)))
+
+        started = time.perf_counter()
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+                if method == "GET":
+                    response = client.get(endpoint, params=final_payload)
+                elif method in {"POST", "PUT", "PATCH"}:
+                    response = client.request(method, endpoint, json=final_payload)
+                else:
+                    raise APIError(f"Unsupported HTTP method: {method}")
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Request timed out after {timeout:g} seconds.") from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Network error while calling SV API: {exc}") from exc
+
+        elapsed = time.perf_counter() - started
+        if self.debug:
+            self.console.print(f"[dim]HTTP {response.status_code} in {elapsed:.2f}s[/dim]")
+
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            data = response.text
+
+        if response.status_code in {401, 403}:
+            raise APIError(f"API authentication failed: HTTP {response.status_code}. Check your API key.")
+        if response.status_code == 429:
+            raise APIError("API rate limit exceeded. Retry later or increase --poll-interval for async tasks.")
+        if response.status_code >= 400:
+            message = data if isinstance(data, str) else json.dumps(mask_mapping(data), ensure_ascii=False)
+            raise APIError(f"API request failed: HTTP {response.status_code}. {message}")
+
+        return APIResponse(data=data, status_code=response.status_code, elapsed_seconds=elapsed, url=endpoint)

sv_cli/commands/auth.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/better_keywords.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/call.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/config.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/content_quality.py

@@ -0,0 +1,5 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The CLI currently registers this tool through the generic, definition-driven
+adapter layer in sv_cli.main.
+"""

sv_cli/commands/content_transformer.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/core_analysis.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/definitions.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/geo_audit.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/insight_igniter.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/marketplace_services.py

@@ -0,0 +1,5 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The CLI currently registers this tool through the generic, definition-driven
+adapter layer in sv_cli.main.
+"""

sv_cli/commands/options.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/preliminary_audit.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/ranklens.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/seo_image.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/seo_mapping.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/seogpt.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/seogpt2.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/seogpt_compare.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""

sv_cli/commands/top_competitors.py

@@ -0,0 +1,5 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The CLI currently registers this tool through the generic, definition-driven
+adapter layer in sv_cli.main.
+"""

sv_cli/commands/topical_authority.py

@@ -0,0 +1,4 @@
+"""Command module reserved for future adapter-specific customizations.
+
+The initial CLI registers generic, definition-driven commands in sv_cli.main.
+"""