publinker-cli 0.6.2__py3-none-any.whl

publinker_cli/__init__.py

@@ -0,0 +1,14 @@
+"""publinker-cli — per-user OAuth CLI over publinker-api.
+
+Public surface:
+- `PublinkerClient` — authenticated HTTP client (importable for the future MCP wrapper).
+- `app` (in `publinker_cli.__main__`) — Typer CLI entry point.
+"""
+
+# Defined before the client import: client.py reads it for the User-Agent.
+# Bump together with pyproject.toml and the server-side latest-version constant.
+__version__ = "0.6.2"
+
+from publinker_cli.client import PublinkerClient  # noqa: E402
+
+__all__ = ["PublinkerClient", "__version__"]

publinker_cli/__main__.py

@@ -0,0 +1,83 @@
+"""publinker — CLI entry point.
+
+`pip install publinker-cli` registers this module as the `publinker` console script
+via the [project.scripts] section of pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from publinker_cli import __version__
+from publinker_cli.commands import auth_cmds, use as use_cmd
+from publinker_cli.commands import report_options, token_cmd, update as update_cmd
+from publinker_cli.commands import skill as skill_cmd, write as write_cmd
+from publinker_cli.dispatch_cli import register_routes
+from publinker_cli.manifest import load_manifest
+
+app = typer.Typer(
+    name="publinker",
+    help="CLI for publinker-api. Per-user Auth0 OAuth, OS-keychain token storage.",
+    add_completion=True,
+    no_args_is_help=True,
+)
+
+# Hand-written top-level commands (auth lifecycle + site selector).
+app.command("login")(auth_cmds.login)
+app.command("logout")(auth_cmds.logout)
+app.command("whoami")(auth_cmds.whoami)
+app.command(
+    "token",
+    help=(
+        "Print a live access token (stdout only) for curl/browser debugging. "
+        "--id for the id_token, --json for the full bundle."
+    ),
+)(token_cmd.token_command)
+app.command(
+    "use",
+    help="Set or clear the active publinker site (persisted across sessions).",
+)(use_cmd.use_command)
+app.command(
+    "update",
+    help="Check for (--check) or install a newer publinker-cli. No login needed.",
+)(update_cmd.update_command)
+app.add_typer(write_cmd.app, name="write")
+app.add_typer(skill_cmd.app, name="skill")
+
+# Everything else (manifest-defined reads and guarded mutations) is materialized
+# from publinker_cli/routes.yaml. Adding an API operation is a YAML edit plus a
+# passing test run; no command boilerplate is required.
+_groups = register_routes(app, load_manifest())
+
+# Hand-written companion to `site report get` — surfaces the platform +
+# dimensions_keys enums we've verified against prod.
+_report_group = _groups.get(("site", "report"))
+if _report_group is not None:
+    _report_group.command(
+        "list-options",
+        help="Show verified platform + dimensions_keys values for `report get`.",
+    )(report_options.list_options)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"publinker {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """publinker — CLI for publinker-api."""
+
+
+if __name__ == "__main__":
+    app()

publinker_cli/audience.py

@@ -0,0 +1,73 @@
+"""Which slice of the route manifest this build exposes (DEV-1566).
+
+The manifest describes 130 routes, including the whole `/overwatch` admin
+surface, billing, invoices, subscriptions and Auth0 user management. Shipping
+all of it to an external customer is an information-disclosure problem — the
+wheel becomes a map of the internal API — and the audit that produced
+DEV-1566 flagged it as a blocker for external release.
+
+Every route therefore carries `audience: customer | internal`. **`internal` is
+the default and the safe one**: a route added without an explicit audience
+never reaches a customer build, so forgetting the field fails closed.
+
+Resolution order, first match wins:
+
+1. ``PUBLINKER_CLI_AUDIENCE`` in the environment — for tests and for an
+   internal user who wants to see the customer surface without reinstalling.
+2. ``_BUILD_AUDIENCE`` below, rewritten by ``scripts/build-customer-wheel.sh``
+   when packaging the customer wheel.
+3. ``internal`` — a plain ``pip install -e .`` from the repo is an internal
+   developer install.
+"""
+
+from __future__ import annotations
+
+import os
+
+INTERNAL = "internal"
+CUSTOMER = "customer"
+VALID = (CUSTOMER, INTERNAL)
+
+ENV_VAR = "PUBLINKER_CLI_AUDIENCE"
+
+# Rewritten at package time by scripts/build-customer-wheel.sh. Leave as
+# "internal" in the repo — the committed state is the developer install.
+_BUILD_AUDIENCE = "customer"
+
+
+class AudienceError(ValueError):
+    """Raised when an audience value is not one we recognise."""
+
+
+def _validate(value: str, source: str) -> str:
+    if value not in VALID:
+        raise AudienceError(
+            f"{source} is {value!r}; expected one of {', '.join(VALID)}"
+        )
+    return value
+
+
+def current_audience() -> str:
+    """The audience this process should expose."""
+    override = os.environ.get(ENV_VAR, "").strip().lower()
+    if override:
+        return _validate(override, f"${ENV_VAR}")
+    return _validate(_BUILD_AUDIENCE, "the packaged build audience")
+
+
+def is_customer_build() -> bool:
+    return current_audience() == CUSTOMER
+
+
+def route_is_visible(route_audience: str | None, audience: str | None = None) -> bool:
+    """Whether a route with this `audience` ships in the given build.
+
+    An internal build sees everything. A customer build sees only routes
+    explicitly marked `customer` — anything missing, misspelled or `internal`
+    is hidden, so the failure mode is a missing command rather than an
+    exposed admin endpoint.
+    """
+    audience = audience or current_audience()
+    if audience == INTERNAL:
+        return True
+    return route_audience == CUSTOMER

publinker_cli/auth.py

@@ -0,0 +1,152 @@
+"""Auth0 Device Authorization Flow (RFC 8628).
+
+Two operations:
+- `device_login()` — runs the full device flow end-to-end; returns a TokenBundle.
+- `refresh_token(...)` — exchanges a refresh token for a new access token.
+
+Both are pure: no keyring writes. The caller decides what to persist.
+"""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+import requests
+
+from publinker_cli.config import Auth0Config, auth0_config
+from publinker_cli.keyring_store import TokenBundle
+
+
+class AuthError(Exception):
+    """Raised when the Auth0 flow fails terminally (user denied, expired, server error)."""
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    device_code: str
+    user_code: str
+    verification_uri_complete: str
+    expires_in: int  # seconds
+    interval: int  # poll seconds
+
+
+def request_device_code(cfg: Optional[Auth0Config] = None) -> DeviceCode:
+    """Step 1 of RFC 8628 — request a device code from Auth0."""
+    cfg = cfg or auth0_config()
+    resp = requests.post(
+        cfg.device_code_url,
+        data={
+            "client_id": cfg.client_id,
+            "scope": cfg.scopes,
+            "audience": cfg.audience,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=10,
+    )
+    if resp.status_code != 200:
+        raise AuthError(f"device code request failed: {resp.status_code} {resp.text}")
+    body = resp.json()
+    return DeviceCode(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri_complete=body["verification_uri_complete"],
+        expires_in=int(body["expires_in"]),
+        interval=int(body["interval"]),
+    )
+
+
+def poll_for_token(
+    device_code: DeviceCode,
+    cfg: Optional[Auth0Config] = None,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.monotonic,
+) -> TokenBundle:
+    """Step 2 of RFC 8628 — poll the token endpoint until the user authorizes or it expires.
+
+    `sleep` and `now` are injectable for tests.
+    """
+    cfg = cfg or auth0_config()
+    interval = device_code.interval
+    deadline = now() + device_code.expires_in
+
+    while now() < deadline:
+        sleep(interval)
+        resp = requests.post(
+            cfg.token_url,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code.device_code,
+                "client_id": cfg.client_id,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            return TokenBundle.from_token_response(resp.json())
+
+        # 4xx with `error` field — either keep polling (pending/slow_down) or bail.
+        try:
+            err = resp.json().get("error", "")
+        except ValueError:
+            err = ""
+
+        if err == "authorization_pending":
+            continue
+        if err == "slow_down":
+            interval += 5
+            continue
+        if err in {"access_denied", "expired_token"}:
+            raise AuthError(f"login failed: {err}")
+        raise AuthError(
+            f"unexpected token endpoint response {resp.status_code}: {resp.text}"
+        )
+
+    raise AuthError("device code expired before user completed login")
+
+
+def refresh_access_token(
+    refresh_token: str, cfg: Optional[Auth0Config] = None
+) -> TokenBundle:
+    """Exchange a refresh token for a new access token (and rotated refresh token)."""
+    cfg = cfg or auth0_config()
+    resp = requests.post(
+        cfg.token_url,
+        data={
+            "grant_type": "refresh_token",
+            "client_id": cfg.client_id,
+            "refresh_token": refresh_token,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=10,
+    )
+    if resp.status_code != 200:
+        raise AuthError(f"refresh failed: {resp.status_code} {resp.text}")
+    body = resp.json()
+    # Auth0 rotates refresh tokens — the response may contain a NEW refresh_token, or
+    # (rarely) reuse the old one. Carry forward the prior refresh token if the response
+    # omits it, so the caller never loses ability to refresh again.
+    if "refresh_token" not in body:
+        body["refresh_token"] = refresh_token
+    return TokenBundle.from_token_response(body)
+
+
+def device_login(
+    cfg: Optional[Auth0Config] = None,
+    open_browser: bool = True,
+    on_user_code: Optional[Callable[[DeviceCode], None]] = None,
+) -> TokenBundle:
+    """Run the full device flow end-to-end. Returns the new token bundle.
+
+    `on_user_code` is invoked with the device code so the caller can print the
+    user_code + verification URL. If `open_browser` is True the verification URL
+    is also opened in the default browser.
+    """
+    code = request_device_code(cfg)
+    if on_user_code is not None:
+        on_user_code(code)
+    if open_browser:
+        webbrowser.open(code.verification_uri_complete)
+    return poll_for_token(code, cfg)

publinker_cli/client.py

@@ -0,0 +1,166 @@
+"""Authenticated HTTP client for publinker-api.
+
+Importable by both the CLI commands and the future MCP server. Handles silent
+token refresh on 401 — the caller never sees an auth retry.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any, Optional
+
+import requests
+
+from publinker_cli import auth, keyring_store, version
+from publinker_cli.config import DEFAULT_STAGE, api_base_url
+
+# A ready access token (e.g. from `publinker token` on a logged-in machine) for
+# CI and containers. Used as-is: never stored, never refreshed.
+TOKEN_ENV_VAR = "PUBLINKER_TOKEN"
+
+
+class NotAuthenticatedError(Exception):
+    """No token in keyring (or it's been revoked and can't be refreshed)."""
+
+
+class APIError(Exception):
+    """publinker-api returned a non-2xx response."""
+
+    def __init__(self, status: int, body: str, path: str) -> None:
+        super().__init__(f"{path} → HTTP {status}: {body}")
+        self.status = status
+        self.body = body
+        self.path = path
+
+
+class PublinkerClient:
+    """Thin authenticated wrapper over publinker-api.
+
+    Auto-refreshes the access token when it's about to expire (60s leeway) and on
+    a 401 response (one retry). After a failed refresh the bundle is cleared from
+    the keyring so the next operation triggers a fresh `login`.
+    """
+
+    def __init__(
+        self, stage: str = DEFAULT_STAGE, session: Optional[requests.Session] = None
+    ) -> None:
+        self.stage = stage
+        self.base_url = api_base_url(stage).rstrip("/")
+        self._session = session or requests.Session()
+
+    # ─── Auth token management ──────────────────────────────────────────────
+
+    def _bundle(self) -> keyring_store.TokenBundle:
+        env_token = os.environ.get(TOKEN_ENV_VAR, "").strip()
+        if env_token:
+            return keyring_store.TokenBundle(env_token, "", "", 2**31 - 1)
+        bundle = keyring_store.load()
+        if bundle is None:
+            raise NotAuthenticatedError("not logged in — run `publinker login`")
+        if bundle.is_expired():
+            bundle = self._refresh(bundle)
+        return bundle
+
+    def current_bundle(self) -> keyring_store.TokenBundle:
+        """Return a token bundle guaranteed valid right now.
+
+        Public counterpart to `_bundle()` for callers that need the token itself
+        rather than an API call (e.g. `publinker token`). Refreshes and re-saves
+        when expired; raises NotAuthenticatedError when the session is gone.
+        """
+        return self._bundle()
+
+    def _refresh(self, bundle: keyring_store.TokenBundle) -> keyring_store.TokenBundle:
+        if os.environ.get(TOKEN_ENV_VAR, "").strip():
+            # Leave the stored login alone: the env token is the one that failed.
+            raise NotAuthenticatedError(
+                f"${TOKEN_ENV_VAR} was rejected (expired?) — "
+                "mint a new one with `publinker token`"
+            )
+        if not bundle.refresh_token:
+            keyring_store.clear()
+            raise NotAuthenticatedError("session expired — run `publinker login`")
+        try:
+            new_bundle = auth.refresh_access_token(bundle.refresh_token)
+        except auth.AuthError as exc:
+            keyring_store.clear()
+            raise NotAuthenticatedError(
+                f"session expired ({exc}) — run `publinker login`"
+            ) from exc
+        keyring_store.save(new_bundle)
+        return new_bundle
+
+    # ─── HTTP ───────────────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict:
+        bundle = self._bundle()
+        url = f"{self.base_url}{path}"
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {bundle.access_token}"
+        headers["User-Agent"] = version.USER_AGENT
+
+        resp = self._session.request(method, url, headers=headers, timeout=30, **kwargs)
+        if resp.status_code == 401:
+            # The token wasn't actually expired by our clock, but the API rejected it.
+            # Force a refresh and retry once.
+            bundle = self._refresh(bundle)
+            headers["Authorization"] = f"Bearer {bundle.access_token}"
+            resp = self._session.request(
+                method, url, headers=headers, timeout=30, **kwargs
+            )
+        if not resp.ok:
+            raise APIError(resp.status_code, resp.text, path)
+        version.observe(resp.headers)
+
+        # The API returns 204 No Content for some endpoints; tolerate empty bodies.
+        if not resp.content:
+            return {}
+        try:
+            return resp.json()
+        except ValueError:
+            return {"raw": resp.text}
+
+    def get(self, path: str, **kwargs: Any) -> dict:
+        return self._request("GET", path, **kwargs)
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict:
+        """Public method/path entry point used by the manifest dispatcher."""
+        return self._request(method, path, **kwargs)
+
+    # ─── v0 resource shortcuts ──────────────────────────────────────────────
+
+    def list_sites(self) -> list[str]:
+        """`GET /site` → list of site domain strings."""
+        return self.get("/site").get("sites", [])
+
+    def list_companies(self) -> list[str]:
+        """`GET /company` → list of company id strings."""
+        return self.get("/company").get("companyIds", [])
+
+    # ─── Local profile ──────────────────────────────────────────────────────
+
+    def whoami(self) -> dict:
+        """Decode the id_token locally — no API call, no token cost.
+
+        Returns the JWT claims (email, name, sub, etc.). The id_token's signature
+        is NOT verified here — we issued it ourselves to ourselves; tampering would
+        only fool the user, not the API.
+        """
+        bundle = keyring_store.load()
+        if bundle is None or not bundle.id_token:
+            raise NotAuthenticatedError("not logged in — run `publinker login`")
+        return _decode_jwt_payload(bundle.id_token)
+
+
+def _decode_jwt_payload(token: str) -> dict:
+    """Decode the payload segment of a JWT without verifying the signature."""
+    try:
+        _, payload_b64, _ = token.split(".")
+    except ValueError as exc:
+        raise ValueError(f"malformed JWT: {exc}") from exc
+    # JWT uses base64url without padding — re-pad before decoding.
+    padding = "=" * (-len(payload_b64) % 4)
+    decoded = base64.urlsafe_b64decode(payload_b64 + padding)
+    return json.loads(decoded)

publinker_cli/commands/auth_cmds.py

@@ -0,0 +1,69 @@
+"""login / logout / whoami commands."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from publinker_cli import auth, keyring_store, state, write_gate
+from publinker_cli.client import NotAuthenticatedError, PublinkerClient
+
+console = Console()
+
+
+def login() -> None:
+    """Authenticate via Auth0 Device Authorization Flow."""
+
+    def on_user_code(code: auth.DeviceCode) -> None:
+        console.print(
+            "\n[bold]Confirm the code in your browser:[/bold] "
+            f"[cyan bold]{code.user_code}[/cyan bold]"
+        )
+        console.print(f"[dim]URL: {code.verification_uri_complete}[/dim]")
+        console.print(
+            f"[dim]Opening your browser... (expires in {code.expires_in // 60} min)[/dim]\n"
+        )
+
+    with console.status("[bold green]Waiting for authorization...", spinner="dots"):
+        try:
+            bundle = auth.device_login(on_user_code=on_user_code)
+        except auth.AuthError as exc:
+            console.print(f"[red]Login failed:[/red] {exc}")
+            raise typer.Exit(code=1)
+    keyring_store.save(bundle)
+    console.print("[green]✓ Logged in.[/green]")
+
+
+def logout() -> None:
+    """Clear the cached token and any retired file-backed write state."""
+    keyring_store.clear()
+    write_gate.clear_legacy_state()
+    console.print("[green]✓ Logged out.[/green]")
+
+
+def whoami() -> None:
+    """Show the identity behind the current token (no API call)."""
+    try:
+        client = PublinkerClient()
+        claims = client.whoami()
+    except NotAuthenticatedError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+
+    table = Table(show_header=False, box=None)
+    table.add_column(style="cyan", no_wrap=True)
+    table.add_column()
+    for key in ("email", "name", "sub", "nickname", "email_verified"):
+        if key in claims:
+            table.add_row(key, str(claims[key]))
+
+    selected = state.active_site()
+    if selected:
+        table.add_row("active site", selected)
+    else:
+        table.add_row(
+            "active site",
+            "[dim]none (run `publinker use <domain>` to set one)[/dim]",
+        )
+    console.print(table)

publinker_cli/commands/report_options.py

@@ -0,0 +1,100 @@
+"""`publinker site report list-options` — quick reference for report filters.
+
+The `/site/{site}/report` endpoint's `platform` and `dimensions_keys` filters
+have no enum on the server (whatever the ETL bucketed by, the API will look
+up). This command surfaces the values we've actually seen in the codebase
+and verified against prod, so new users don't have to fish in DDB.
+
+If the set grows or shifts, update the constants here — they're
+intentionally hand-curated rather than introspected, because the API
+itself has no listing endpoint to query.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+# (platform, source / extractor, account_id format example)
+_PLATFORMS: tuple[tuple[str, str, str], ...] = (
+    (
+        "google_admanager",
+        "Google Ad Manager reporting API",
+        "12345678  (GAM network code)",
+    ),
+    (
+        "google_ads",
+        "Google Ads API",
+        "1234567890  (Ads customer id)",
+    ),
+    (
+        "active_campaign",
+        "ActiveCampaign API",
+        "<AC account>",
+    ),
+    (
+        "google_postmaster",
+        "Google Postmaster Tools",
+        "<sender domain>",
+    ),
+    (
+        "escalated",
+        "Publinker escalated-issues pipeline",
+        "publinker",
+    ),
+)
+
+
+# (dimensions_keys, what each row represents, typical platform)
+_DIMENSIONS: tuple[tuple[str, str, str], ...] = (
+    ("date", "one row per day (aggregate)", "any"),
+    (
+        "date,channel",
+        "one row per (day, traffic channel)",
+        "google_admanager / google_ads",
+    ),
+    ("date,channel,adunit", "one row per (day, channel, ad unit)", "google_admanager"),
+    (
+        "date,channel,country_code,country_name,url,adunit",
+        "full detail — one row per URL × adunit per day",
+        "google_admanager",
+    ),
+    ("date,domain,device,country", "escalated-issues breakdown", "escalated"),
+    (
+        "date,channel,country_code,country_name,url,adunit:report_type=adspeed",
+        "adspeed-style report (separate fact set)",
+        "google_admanager",
+    ),
+)
+
+
+def list_options() -> None:
+    """Print the verified platform + dimensions_keys values."""
+    platforms = Table(
+        title="platform values (publinker site report get --platform <X>)"
+    )
+    platforms.add_column("value", style="cyan")
+    platforms.add_column("source")
+    platforms.add_column("account_id example", style="dim")
+    for row in _PLATFORMS:
+        platforms.add_row(*row)
+    console.print(platforms)
+
+    dims = Table(
+        title="dimensions_keys values (publinker site report get --dimensions-keys <X>)"
+    )
+    dims.add_column("value", style="cyan", overflow="fold")
+    dims.add_column("granularity")
+    dims.add_column("platform", style="dim")
+    for row in _DIMENSIONS:
+        dims.add_row(*row)
+    console.print(dims)
+
+    console.print(
+        "\n[dim]The set is what we've verified against prod; the API itself "
+        "has no listing endpoint. If you find a working combination not "
+        "listed here, please add it to cli/publinker_cli/commands/report_options.py.[/dim]"
+    )