orbiads-cli 1.0.0__py3-none-any.whl

orbiads_cli/__init__.py

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

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/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/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)

orbiads_cli/commands/billing.py

@@ -0,0 +1,54 @@
+"""Check credits and billing."""
+
+import typer
+
+from orbiads_cli.client import CliApiError, get_client
+from orbiads_cli.errors import handle_error
+from orbiads_cli.output import render, render_detail
+
+app = typer.Typer(help="Check credits and billing", no_args_is_help=True)
+
+
+@app.command()
+def balance(ctx: typer.Context):
+    """Show current credit balance and plan info."""
+    try:
+        client = get_client()
+        data = client.get("/api/billing")
+
+        # Display key billing fields
+        detail = {
+            "credits": data.get("balance", 0),
+            "plan": data.get("plan", "unknown"),
+            "nextRenewal": data.get("cycleStart", "N/A"),
+            "overdue": data.get("overdue", False),
+        }
+        render_detail(detail, ctx.obj)
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def transactions(
+    ctx: typer.Context,
+    limit: int = typer.Option(20, "--limit", help="Max results"),
+):
+    """List recent credit transactions."""
+    try:
+        client = get_client()
+        data = client.get("/api/billing/transactions", params={"limit": limit})
+
+        rows = data if isinstance(data, list) else []
+        columns = ["timestamp", "type", "amount", "reason"]
+        # Normalize column names: backend may use camelCase
+        normalized = []
+        for row in rows:
+            normalized.append({
+                "timestamp": row.get("timestamp", row.get("date", "")),
+                "type": row.get("type", ""),
+                "amount": row.get("amount", ""),
+                "reason": row.get("reason", ""),
+            })
+        render(normalized, columns, ctx.obj)
+    except CliApiError as e:
+        handle_error(e)

orbiads_cli/commands/campaigns.py

@@ -0,0 +1,111 @@
+"""Manage GAM campaigns."""
+
+from __future__ import annotations
+
+import typer
+
+from orbiads_cli.client import CliApiError, get_client
+from orbiads_cli.errors import handle_error
+from orbiads_cli.output import OutputContext, confirm, info, render, render_detail, success
+
+app = typer.Typer(help="Manage GAM campaigns", no_args_is_help=True)
+
+_LIST_COLUMNS = ["id", "name", "status", "createdAt"]
+
+
+@app.command("list")
+def list_campaigns(
+    ctx: typer.Context,
+    status: str = typer.Option(None, "--status", help="Filter by status (comma-separated, e.g. draft,deployed)"),
+    limit: int = typer.Option(None, "--limit", help="Max number of campaigns to return"),
+):
+    """List campaigns."""
+    try:
+        client = get_client()
+        params: dict[str, str | int] = {}
+        if status is not None:
+            params["status"] = status
+        if limit is not None:
+            params["limit"] = limit
+        data = client.get("/api/campaigns", params=params)
+        out: OutputContext = ctx.obj
+        render(data, _LIST_COLUMNS, out)
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    campaign_id: str = typer.Argument(..., help="Campaign ID"),
+):
+    """Get campaign details."""
+    try:
+        client = get_client()
+        data = client.get(f"/api/campaigns/{campaign_id}")
+        out: OutputContext = ctx.obj
+        render_detail(data, out)
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def deploy(
+    ctx: typer.Context,
+    campaign_id: str = typer.Argument(..., help="Campaign ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Deploy a draft campaign to GAM."""
+    try:
+        out: OutputContext = ctx.obj
+        # Merge local --yes with global --yes
+        effective_ctx = OutputContext(format=out.format, yes=out.yes or yes)
+        if not confirm(f"Deploy campaign {campaign_id}?", effective_ctx):
+            raise typer.Exit(code=0)
+
+        info(f"Deploying campaign {campaign_id}...")
+        client = get_client()
+        client.post(f"/api/campaigns/{campaign_id}/deploy")
+        success(f"Campaign {campaign_id} deployed successfully.")
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def pause(
+    ctx: typer.Context,
+    campaign_id: str = typer.Argument(..., help="Campaign ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Pause a deployed campaign."""
+    try:
+        out: OutputContext = ctx.obj
+        effective_ctx = OutputContext(format=out.format, yes=out.yes or yes)
+        if not confirm(f"Pause campaign {campaign_id}?", effective_ctx):
+            raise typer.Exit(code=0)
+
+        client = get_client()
+        client.post(f"/api/campaigns/{campaign_id}/pause")
+        success(f"Campaign {campaign_id} paused successfully.")
+    except CliApiError as e:
+        handle_error(e)
+
+
+@app.command()
+def archive(
+    ctx: typer.Context,
+    campaign_id: str = typer.Argument(..., help="Campaign ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Archive a campaign."""
+    try:
+        out: OutputContext = ctx.obj
+        effective_ctx = OutputContext(format=out.format, yes=out.yes or yes)
+        if not confirm(f"Archive campaign {campaign_id}?", effective_ctx):
+            raise typer.Exit(code=0)
+
+        client = get_client()
+        client.post(f"/api/campaigns/{campaign_id}/archive")
+        success(f"Campaign {campaign_id} archived successfully.")
+    except CliApiError as e:
+        handle_error(e)