orbiads-cli 1.0.0__tar.gz

orbiads_cli-1.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Node / SvelteKit
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+frontend/.svelte-kit/
+frontend/build/
+
+# Python
+backend/venv/
+backend/__pycache__/
+backend/**/__pycache__/
+**/*.pyc
+backend/.pytest_cache/
+
+# Jules workflow — fichier temporaire de corps de PR (généré par Claude, supprimé par us-done.sh)
+.github/.us-pr-body.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Logs
+*.log
+backend/logs/
+
+# Backup files
+*.bak
+backend/.venv/
+
+# Secrets & credentials
+client_secret*.json
+*.credentials.json
+service-account*.json
+
+# Dev test scripts (non-pytest)
+backend/test_gam*.py
+backend/test_integrated*.py
+backend/.venv/

orbiads_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrbiAds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orbiads_cli-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: orbiads-cli
+Version: 1.0.0
+Summary: OrbiAds CLI — Google Ad Manager from the command line
+Project-URL: Homepage, https://orbiads.com
+Project-URL: Documentation, https://orbiads.com/docs/cli
+Project-URL: Repository, https://github.com/OrbiAds/Orbiads-GAM-MCP
+Author-email: OrbiAds <contact@orbiads.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adtech,cli,gam,google-ad-manager
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OrbiAds CLI
+
+Google Ad Manager from the command line.
+
+## Install
+
+```bash
+pip install orbiads-cli
+```
+
+## Quick Start
+
+```bash
+orbiads auth login
+orbiads network info
+orbiads campaigns list --json
+```
+
+## Documentation
+
+See [https://orbiads.com/docs/cli](https://orbiads.com/docs/cli)

orbiads_cli-1.0.0/README.md

@@ -0,0 +1,21 @@
+# OrbiAds CLI
+
+Google Ad Manager from the command line.
+
+## Install
+
+```bash
+pip install orbiads-cli
+```
+
+## Quick Start
+
+```bash
+orbiads auth login
+orbiads network info
+orbiads campaigns list --json
+```
+
+## Documentation
+
+See [https://orbiads.com/docs/cli](https://orbiads.com/docs/cli)

orbiads_cli-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orbiads-cli"
+version = "1.0.0"
+description = "OrbiAds CLI — Google Ad Manager from the command line"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "OrbiAds", email = "contact@orbiads.com" },
+]
+keywords = ["google-ad-manager", "gam", "cli", "adtech"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "typer[all]>=0.12.0",
+    "httpx>=0.27.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+orbiads = "orbiads_cli.main:app"
+
+[project.urls]
+Homepage = "https://orbiads.com"
+Documentation = "https://orbiads.com/docs/cli"
+Repository = "https://github.com/OrbiAds/Orbiads-GAM-MCP"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/orbiads_cli"]

orbiads_cli-1.0.0/src/orbiads_cli/__init__.py

@@ -0,0 +1,3 @@
+"""OrbiAds CLI — Google Ad Manager from the command line."""
+
+__version__ = "1.0.0"

orbiads_cli-1.0.0/src/orbiads_cli/client.py

@@ -0,0 +1,279 @@
+"""HTTP client with auto-refresh, retry, and JSend envelope parsing."""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+
+import httpx
+import typer
+
+from orbiads_cli import config
+
+# Public Firebase client identifier (same as frontend).
+# This is NOT a secret — it only identifies the Firebase project.
+FIREBASE_API_KEY = "AIzaSyAr2J5-a6GjIStBSOoIKB48DzSr0K-wHiQ"
+FIREBASE_REFRESH_URL = (
+    f"https://securetoken.googleapis.com/v1/token?key={FIREBASE_API_KEY}"
+)
+
+# Exponential backoff delays for 429 retries (seconds).
+_BACKOFF_DELAYS = [1, 2, 4]
+
+
+# ---------------------------------------------------------------------------
+# Exit-code mapping
+# ---------------------------------------------------------------------------
+
+_STATUS_TO_EXIT: dict[int, int] = {
+    404: 3,
+    401: 4,
+    403: 4,
+    409: 5,
+    412: 6,
+}
+
+
+def _exit_code(status: int) -> int:
+    """Map HTTP status to CLI exit code."""
+    return _STATUS_TO_EXIT.get(status, 1)
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class CliApiError(Exception):
+    """API error with semantic exit code for CLI commands."""
+
+    def __init__(
+        self,
+        exit_code: int,
+        message: str,
+        error_code: str = "",
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.message = message
+        self.error_code = error_code
+        self.details: dict[str, Any] = details or {}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_CREDITS_RE = re.compile(
+    r"[Bb]alance[:\s]+(\d+).*[Rr]equired[:\s]+(\d+)"
+)
+
+
+def _parse_credits_message(message: str, details: dict[str, Any]) -> None:
+    """Best-effort extraction of balance/required from an error message."""
+    m = _CREDITS_RE.search(message)
+    if m:
+        details["balance"] = int(m.group(1))
+        details["required"] = int(m.group(2))
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class OrbiAdsClient:
+    """Thin wrapper around ``httpx.Client`` with auth and retry logic."""
+
+    def __init__(self, cfg: dict) -> None:
+        self._cfg = cfg
+        self._http = httpx.Client(
+            base_url=cfg["apiUrl"],
+            headers={"Authorization": f"Bearer {cfg['token']}"},
+            timeout=30.0,
+        )
+        self._refreshed = False  # guard: at most one refresh per request
+
+    # -- public convenience methods ------------------------------------------
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self._request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+    # -- core request loop ---------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        self._refreshed = False
+        resp = self._http.request(method, path, **kwargs)
+
+        # 401 → attempt one token refresh then retry
+        if resp.status_code == 401 and not self._refreshed:
+            if self._refresh_token():
+                self._refreshed = True
+                resp = self._http.request(method, path, **kwargs)
+            else:
+                raise CliApiError(
+                    4, "Session expired. Run `orbiads auth login`."
+                )
+
+        # 429 → exponential backoff (max 3 retries)
+        if resp.status_code == 429:
+            resp = self._retry_with_backoff(method, path, **kwargs)
+
+        # Parse JSend envelope
+        return self._parse_response(resp)
+
+    # -- token refresh -------------------------------------------------------
+
+    def _refresh_token(self) -> bool:
+        """Refresh Firebase ID token using the stored refresh token.
+
+        Returns ``True`` on success, ``False`` otherwise.
+        """
+        refresh_token = self._cfg.get("refreshToken")
+        if not refresh_token:
+            return False
+
+        try:
+            resp = httpx.post(
+                FIREBASE_REFRESH_URL,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": refresh_token,
+                },
+                timeout=15.0,
+            )
+        except httpx.HTTPError:
+            return False
+
+        if resp.status_code != 200:
+            return False
+
+        data = resp.json()
+        new_token = data.get("id_token", "")
+        new_refresh = data.get("refresh_token", "")
+        if not new_token:
+            return False
+
+        # Persist new tokens
+        config.set_token(new_token, new_refresh)
+        self._cfg["token"] = new_token
+        self._cfg["refreshToken"] = new_refresh
+        self._http.headers["Authorization"] = f"Bearer {new_token}"
+        return True
+
+    # -- 429 backoff ---------------------------------------------------------
+
+    def _retry_with_backoff(
+        self, method: str, path: str, **kwargs: Any
+    ) -> httpx.Response:
+        resp: httpx.Response | None = None
+        for delay in _BACKOFF_DELAYS:
+            typer.echo(
+                f"Rate limited, retrying in {delay}s...", err=True
+            )
+            time.sleep(delay)
+            resp = self._http.request(method, path, **kwargs)
+            if resp.status_code != 429:
+                return resp
+        # Return the last 429 so the caller can raise the appropriate error.
+        assert resp is not None
+        return resp
+
+    # -- response parsing ----------------------------------------------------
+
+    @staticmethod
+    def _parse_response(resp: httpx.Response) -> Any:
+        """Parse a JSend-style envelope.
+
+        On success returns the ``data`` field.
+        On error raises :class:`CliApiError` with the correct exit code.
+        """
+        try:
+            body = resp.json()
+        except Exception:
+            if resp.status_code >= 400:
+                raise CliApiError(
+                    _exit_code(resp.status_code),
+                    f"HTTP {resp.status_code} (non-JSON response)",
+                )
+            return None
+
+        if resp.status_code >= 400:
+            err = body.get("error") or {}
+            code = err.get("code", "")
+            message = err.get("message", f"HTTP {resp.status_code}")
+            details: dict[str, Any] = {}
+
+            # Extract structured details from the error payload.
+            if isinstance(err.get("details"), dict):
+                details = err["details"]
+
+            # Map INSUFFICIENT_CREDITS (HTTP 412) to exit code 6 with
+            # balance/required details parsed from the message or payload.
+            exit = _exit_code(resp.status_code)
+            if code == "INSUFFICIENT_CREDITS":
+                exit = 6
+                # Backend may include balance/required in details or message.
+                if "balance" not in details:
+                    _parse_credits_message(message, details)
+
+            # For 404, include the request path as the resource hint.
+            if resp.status_code == 404 and "resource" not in details:
+                try:
+                    details["resource"] = resp.request.url.path
+                except RuntimeError:
+                    pass  # request not set (e.g. in tests)
+
+            raise CliApiError(exit, message, code, details)
+
+        return body.get("data")
+
+    # -- cleanup -------------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "OrbiAdsClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+_singleton: OrbiAdsClient | None = None
+
+
+def get_client() -> OrbiAdsClient:
+    """Return a configured :class:`OrbiAdsClient`.
+
+    Reuses a single instance within the process (singleton).
+    Exits with code 4 if the user is not authenticated.
+    """
+    global _singleton
+    if _singleton is not None:
+        return _singleton
+
+    cfg = config.load()
+    if not cfg or not cfg.get("token"):
+        typer.echo(
+            "Not authenticated. Run `orbiads auth login` first.", err=True
+        )
+        raise typer.Exit(code=4)
+
+    _singleton = OrbiAdsClient(cfg)
+    return _singleton

orbiads_cli-1.0.0/src/orbiads_cli/commands/advertisers.py

@@ -0,0 +1,47 @@
+"""Manage GAM advertisers."""
+
+import typer
+
+from orbiads_cli.client import CliApiError, get_client
+from orbiads_cli.errors import handle_error
+from orbiads_cli.output import OutputContext, confirm, render, render_detail, success
+
+app = typer.Typer(help="Manage GAM advertisers", no_args_is_help=True)
+
+
+@app.command("list")
+def list_advertisers(ctx: typer.Context):
+    """List advertisers."""
+    out: OutputContext = ctx.obj
+    try:
+        client = get_client()
+        data = client.get("/api/gam/advertisers")
+        # Response may be a model with "advertisers" key or a list
+        if isinstance(data, dict):
+            items = data.get("advertisers", data.get("companies", []))
+        else:
+            items = data if isinstance(data, list) else []
+        render(items, ["id", "name", "type"], out)
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", help="Advertiser name"),
+):
+    """Create a new advertiser."""
+    out: OutputContext = ctx.obj
+    if not confirm(f'Create advertiser "{name}"?', out):
+        raise typer.Exit(code=0)
+    try:
+        client = get_client()
+        data = client.post("/api/gam/advertisers", json={"name": name})
+        if out.format == "json":
+            render_detail(data, out)
+        else:
+            adv_id = data.get("id", "?") if isinstance(data, dict) else "?"
+            success(f"Advertiser created: {adv_id}")
+    except CliApiError as e:
+        handle_error(e)

orbiads_cli-1.0.0/src/orbiads_cli/commands/auth.py

@@ -0,0 +1,173 @@
+"""Authentication commands: login, logout, status."""
+
+import time
+import webbrowser
+
+import httpx
+import typer
+from rich.console import Console
+
+from orbiads_cli import config
+from orbiads_cli.config import DEFAULT_API_URL
+
+app = typer.Typer(help="Authentication (login, logout, status)", no_args_is_help=True)
+
+# stderr console for all auth output (stdout reserved for JSON data)
+err_console = Console(stderr=True)
+
+# Maximum polling duration in seconds (match server device code TTL)
+_MAX_POLL_DURATION = 900
+
+# HTTP timeout for individual requests
+_HTTP_TIMEOUT = 30.0
+
+
+def _get_api_url() -> str:
+    """Return the configured API URL or the default."""
+    cfg = config.load()
+    return cfg.get("apiUrl", DEFAULT_API_URL) if cfg else DEFAULT_API_URL
+
+
+@app.command()
+def login() -> None:
+    """Authenticate with OrbiAds via browser device flow."""
+    api_url = _get_api_url()
+
+    # Step 1: Request a device code
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/auth/gam/device-code",
+            timeout=_HTTP_TIMEOUT,
+        )
+        resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        err_console.print(f"[red]Failed to initiate login: {exc}[/red]")
+        raise typer.Exit(code=1) from None
+
+    body = resp.json()
+    if body.get("error"):
+        err_console.print(f"[red]Server error: {body['error'].get('message', 'Unknown error')}[/red]")
+        raise typer.Exit(code=1)
+
+    data = body["data"]
+    device_code = data["deviceCode"]
+    user_code = data["userCode"]
+    verification_url = data["verificationUrl"]
+    poll_interval = data.get("pollInterval", 5)
+
+    # Step 2: Display instructions and open browser
+    err_console.print()
+    err_console.print(f"  To authorize, visit: [bold cyan]{verification_url}[/bold cyan]")
+    err_console.print(f"  Your code: [bold yellow]{user_code}[/bold yellow]")
+    err_console.print()
+    err_console.print("  Waiting for authorization...", style="dim")
+
+    webbrowser.open(verification_url)
+
+    # Step 3: Poll for authorization
+    start_time = time.monotonic()
+    try:
+        with err_console.status("[bold green]Waiting for browser authorization...") as spinner:
+            while True:
+                elapsed = time.monotonic() - start_time
+                if elapsed >= _MAX_POLL_DURATION:
+                    err_console.print(
+                        "[red]Authorization timed out (max 15 min). Please try again.[/red]"
+                    )
+                    raise typer.Exit(code=4)
+
+                time.sleep(poll_interval)
+
+                try:
+                    poll_resp = httpx.get(
+                        f"{api_url}/api/auth/gam/device-token-status",
+                        params={"deviceCode": device_code},
+                        timeout=_HTTP_TIMEOUT,
+                    )
+                    poll_resp.raise_for_status()
+                except httpx.HTTPError as exc:
+                    err_console.print(f"[red]Polling error: {exc}[/red]")
+                    raise typer.Exit(code=1) from None
+
+                poll_body = poll_resp.json()
+                if poll_body.get("error"):
+                    err_console.print(
+                        f"[red]Server error: {poll_body['error'].get('message', 'Unknown error')}[/red]"
+                    )
+                    raise typer.Exit(code=1)
+
+                poll_data = poll_body["data"]
+                status_value = poll_data["status"]
+
+                if status_value == "authorized":
+                    # Save tokens
+                    config.set_token(
+                        poll_data["accessToken"],
+                        poll_data["refreshToken"],
+                    )
+                    spinner.stop()
+                    err_console.print("[bold green]Authenticated successfully![/bold green]")
+                    raise typer.Exit(code=0)
+
+                elif status_value == "expired":
+                    spinner.stop()
+                    err_console.print(
+                        "[red]Authorization expired. Please try again.[/red]"
+                    )
+                    raise typer.Exit(code=4)
+
+                # status == "pending" — continue polling
+
+    except KeyboardInterrupt:
+        err_console.print("\n[yellow]Authorization cancelled.[/yellow]")
+        raise typer.Exit(code=1) from None
+
+
+@app.command()
+def logout() -> None:
+    """Clear local credentials."""
+    config.clear()
+    err_console.print("Logged out.")
+    raise typer.Exit(code=0)
+
+
+@app.command()
+def status() -> None:
+    """Show current authentication status."""
+    if not config.has_token():
+        err_console.print("Not authenticated.")
+        raise typer.Exit(code=4)
+
+    api_url = _get_api_url()
+    token = config.get_token()
+
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/me",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=_HTTP_TIMEOUT,
+        )
+    except httpx.HTTPError as exc:
+        err_console.print(f"[red]Request failed: {exc}[/red]")
+        raise typer.Exit(code=1) from None
+
+    if resp.status_code == 401:
+        err_console.print("[red]Token invalid. Run `orbiads auth login` to re-authenticate.[/red]")
+        raise typer.Exit(code=4)
+
+    if resp.status_code != 200:
+        err_console.print(f"[red]Unexpected response (HTTP {resp.status_code}).[/red]")
+        raise typer.Exit(code=1)
+
+    body = resp.json()
+    if body.get("error"):
+        err_console.print(f"[red]Server error: {body['error'].get('message', 'Unknown')}[/red]")
+        raise typer.Exit(code=1)
+
+    data = body.get("data", {})
+    email = data.get("email", "unknown")
+    network = data.get("networkCode", "not set")
+
+    err_console.print(f"  Authenticated as: [bold]{email}[/bold]")
+    err_console.print(f"  GAM Network:      [bold]{network}[/bold]")
+    raise typer.Exit(code=0)