publinker-cli 0.6.2__py3-none-any.whl

publinker_cli/skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: publinker
+description: Read and manage Publinker data (sites, ad revenue reports, pricing floors, site config) with the `publinker` CLI. Use when the user asks about their Publinker sites, revenue, reports, floors or config, or mentions publinker.
+---
+
+# Publinker CLI
+
+The `publinker` command talks to the Publinker API as the logged-in user. It
+only sees the sites that user can see on publinker.com.
+
+## Before anything
+
+1. `publinker whoami`. If it says you are not logged in, ask the user to run
+   `publinker login` themselves (it opens a browser to confirm a code). Never
+   run `publinker login` for them, and never print or store tokens.
+2. `publinker site list` to see the sites, then `publinker use <site>` to set
+   the active one, or pass `--site <site>` on a single command.
+
+## Find the right command
+
+Every group and command has `--help`; read it instead of guessing flags.
+
+```bash
+publinker --help
+publinker site --help
+publinker site report get --help
+publinker site report list-options   # valid --platform and --dimensions-keys values
+```
+
+Add `--json` to any read command when you need to process the output.
+
+## Common reads
+
+```bash
+publinker site report get --platform google_admanager --account-id <network code> \
+  --dimensions-keys date --date-start 2026-01-01 --date-stop 2026-01-07 --json
+publinker site pricing get --json
+publinker site config get --json
+```
+
+## Changes (writes)
+
+Commands that create, change or delete data are blocked by default, and
+each one is unlocked on its own. Before a write:
+
+1. Read the current value first, then tell the user exactly what will change
+   and get a clear yes for that exact command.
+2. Run that one command with `PUBLINKER_ALLOW_WRITES=1` in front of it and an
+   explicit `--site <site>` (the active site from `publinker use` is not
+   enough for a write):
+   `PUBLINKER_ALLOW_WRITES=1 publinker site pricing adjust --site <site> ...`
+3. Never `export PUBLINKER_ALLOW_WRITES`; nothing stays unlocked afterwards.
+   `publinker write allow` no longer opens a window.
+4. Read the value again and show the user the result. If a write times out,
+   read before retrying; it may have gone through.
+
+## Errors
+
+- `401` / "not logged in": the user runs `publinker login`.
+- `403`: the user has no access to that site. Do not retry with other sites.
+- A newer version is announced: tell the user to run `pipx upgrade publinker-cli`.

publinker_cli/state.py

@@ -0,0 +1,138 @@
+"""User-state persistence for publinker-cli.
+
+The state file at ~/.config/publinker/state.json tracks the active site
+(selected via `publinker use <site>`) so that site-scoped commands can be
+called without `--site` every time.
+
+The active site is NOT a secret (it's a domain you own). Plain file storage
+beats keyring here: one less keyring read per command + easy inspection
+(`jq .active_site ~/.config/publinker/state.json`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from publinker_cli import __version__
+
+DEFAULT_STATE_DIR = Path.home() / ".config" / "publinker"
+DEFAULT_STATE_FILE = DEFAULT_STATE_DIR / "state.json"
+
+
+def _state_path() -> Path:
+    """Allow tests to override via PUBLINKER_STATE_FILE."""
+    override = os.environ.get("PUBLINKER_STATE_FILE")
+    return Path(override) if override else DEFAULT_STATE_FILE
+
+
+@dataclass
+class State:
+    active_site: Optional[str] = None
+    set_at: Optional[str] = None  # ISO 8601 UTC
+    set_by_cli_version: Optional[str] = None
+    # Retired file-backed write fields are parsed only so `publinker write block`
+    # can remove them during migration. Runtime authorization never reads them.
+    writes_allowed_until: Optional[str] = None
+    writes_persistent: Optional[bool] = None
+
+    def to_json(self) -> str:
+        # Only emit fields that are set, so the file stays clean.
+        return json.dumps(
+            {k: v for k, v in asdict(self).items() if v is not None}, indent=2
+        )
+
+
+def load() -> State:
+    """Read state from disk. Returns an empty State if the file is missing or unreadable."""
+    path = _state_path()
+    if not path.exists():
+        return State()
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        # Corrupted file → treat as no state. Next save will overwrite cleanly.
+        return State()
+    return State(
+        active_site=data.get("active_site"),
+        set_at=data.get("set_at"),
+        set_by_cli_version=data.get("set_by_cli_version"),
+        writes_allowed_until=data.get("writes_allowed_until"),
+        writes_persistent=data.get("writes_persistent"),
+    )
+
+
+def save(state: State) -> None:
+    """Write state to disk, creating the parent directory if needed."""
+    path = _state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(state.to_json())
+    # 0644 — readable, not group-writable. Active site isn't sensitive.
+    os.chmod(path, 0o644)
+
+
+def set_active_site(site: str) -> State:
+    """Set (or replace) the active site and clear retired write-gate fields."""
+    state = State(
+        active_site=site,
+        set_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        set_by_cli_version=__version__,
+    )
+    save(state)
+    return state
+
+
+def update_write_gate(*, until: Optional[str], persistent: Optional[bool]) -> State:
+    """Rewrite retired gate fields while preserving the active site.
+
+    Runtime authorization ignores these fields. Passing both values as ``None``
+    removes stale armed state written by older CLI versions.
+    """
+    existing = load()
+    state = State(
+        active_site=existing.active_site,
+        set_at=existing.set_at,
+        set_by_cli_version=existing.set_by_cli_version,
+        writes_allowed_until=until,
+        writes_persistent=persistent,
+    )
+    save(state)
+    return state
+
+
+def clear() -> None:
+    """Remove the state file entirely. Idempotent."""
+    path = _state_path()
+    if path.exists():
+        path.unlink()
+
+
+def active_site() -> Optional[str]:
+    """Return the currently selected site, or None."""
+    return load().active_site
+
+
+def resolve_site(explicit: Optional[str]) -> str:
+    """Resolve the site to use for a command.
+
+    Precedence:
+      1. The explicit `--site` flag (passed in)
+      2. The active site from state.json
+      3. Raise NoSiteSelectedError so the caller can render a friendly message
+    """
+    if explicit:
+        return explicit
+    selected = active_site()
+    if selected:
+        return selected
+    raise NoSiteSelectedError(
+        "no site selected. Run `publinker use <domain>` or pass --site <domain>."
+    )
+
+
+class NoSiteSelectedError(Exception):
+    """Raised when a site-scoped command runs without a resolvable site."""

publinker_cli/version.py

@@ -0,0 +1,58 @@
+"""CLI version comparison and the passive update notice (DEV-1973).
+
+Every API request sends `User-Agent: publinker-cli/<version>`; publinker-api
+answers with `X-Publinker-Cli-Latest`. `observe()` reads that header off a
+response the command was making anyway — no extra request — and prints one
+stderr line per process when a newer CLI exists. stdout and the exit status are
+never touched, and a missing or malformed header is silently ignored.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Mapping, Optional
+
+from publinker_cli import __version__, audience
+
+USER_AGENT = f"publinker-cli/{__version__}"
+LATEST_HEADER = "X-Publinker-Cli-Latest"
+
+_VERSION_RE = re.compile(r"^\d+(\.\d+)*$")
+_notified = False
+
+
+def parse_version(value: str) -> tuple[int, ...]:
+    """`"0.10.0"` -> `(0, 10, 0)`. Raises ValueError for anything else."""
+    value = value.strip()
+    if not _VERSION_RE.match(value):
+        raise ValueError(f"not a release version: {value!r}")
+    parts = [int(p) for p in value.split(".")]
+    # Pad so "0.3" and "0.3.0" compare equal.
+    return tuple(parts + [0] * (3 - len(parts)))
+
+
+def is_newer(candidate: str, installed: str = __version__) -> bool:
+    """True when `candidate` is strictly newer than `installed` (numeric order)."""
+    return parse_version(candidate) > parse_version(installed)
+
+
+def observe(headers: Mapping[str, str]) -> None:
+    """Print the update notice once if the response advertises a newer CLI."""
+    global _notified
+    # A customer build has no self-update source (see commands/update.py),
+    # so pointing it at `publinker update` would only produce a refusal.
+    if _notified or audience.is_customer_build():
+        return
+    latest: Optional[str] = headers.get(LATEST_HEADER)
+    try:
+        if not latest or not is_newer(latest):
+            return
+    except ValueError:
+        return
+    _notified = True
+    print(
+        f"publinker-cli {latest} is available (installed {__version__}). "
+        "Run: publinker update",
+        file=sys.stderr,
+    )

publinker_cli/write_gate.py

@@ -0,0 +1,51 @@
+"""Process-scoped write-gate policy for publinker-cli.
+
+Mutations are blocked unless the current process receives
+``PUBLINKER_ALLOW_WRITES=1`` (or another documented truthy value). Durable state
+must never arm writes: a persisted allow window can outlive the reviewed command,
+the authenticated user, or the intended API stage.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from publinker_cli import state
+
+ENV_VAR = "PUBLINKER_ALLOW_WRITES"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class GateStatus:
+    """Snapshot of the process-scoped write-gate decision."""
+
+    allowed: bool
+    reason: str
+
+
+def status() -> GateStatus:
+    """Return the current process gate without reading mutable state."""
+    value = os.environ.get(ENV_VAR, "").strip().lower()
+    if value in _TRUTHY:
+        return GateStatus(allowed=True, reason=f"process env {ENV_VAR}=1")
+    if value:
+        return GateStatus(allowed=False, reason=f"process env {ENV_VAR} is not enabled")
+    return GateStatus(allowed=False, reason="default (process gate absent)")
+
+
+def is_allowed() -> bool:
+    """Return whether a mutation may run in this process."""
+    return status().allowed
+
+
+def clear_legacy_state() -> GateStatus:
+    """Delete retired file-backed gate fields without changing the active site."""
+    snapshot = state.load()
+    if (
+        snapshot.writes_allowed_until is not None
+        or snapshot.writes_persistent is not None
+    ):
+        state.update_write_gate(until=None, persistent=None)
+    return GateStatus(allowed=False, reason="legacy file-backed gate cleared")

publinker_cli-0.6.2.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: publinker-cli
+Version: 0.6.2
+Summary: Command line for Publinker: sites, reports, floors and config.
+Project-URL: Homepage, https://publinker.com
+Author: Martech-DM
+License: Proprietary
+Keywords: auth0,cli,martech,publinker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: black==25.9.0; extra == 'dev'
+Requires-Dist: flake8>=7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# publinker-cli
+
+Command line for [Publinker](https://publinker.com): your sites, ad revenue
+reports, pricing floors and site config, from the terminal and from AI
+assistants like Claude Code and Codex.
+
+You need a Publinker account. The CLI only sees the sites you can see on
+publinker.com.
+
+## Install
+
+Needs Python 3.10+ and [pipx](https://pipx.pypa.io/stable/installation/).
+
+```bash
+pipx install publinker-cli
+publinker skill install   # teaches Claude Code and Codex to use publinker
+publinker login           # opens a browser to confirm a one-time code
+```
+
+Update with `pipx upgrade publinker-cli`.
+
+## Use
+
+```bash
+publinker site list                 # sites you can access
+publinker use example.com           # set your active site
+publinker site report get --help    # every command has --help
+publinker site pricing get
+```
+
+Commands that change data are blocked by default. Allow one command at a time
+by prefixing it with `PUBLINKER_ALLOW_WRITES=1` and naming the site explicitly:
+
+```bash
+PUBLINKER_ALLOW_WRITES=1 publinker site pricing adjust --site example.com ...
+```
+
+Nothing stays unlocked afterwards. Don't `export` the variable.
+
+## Servers and CI
+
+On a machine where you are logged in, run `publinker token`, then on the
+server set `PUBLINKER_TOKEN` to that value. Treat it like a password; mint a
+new one when it expires.
+
+## AI assistants
+
+`publinker skill install` copies a skill to `~/.claude/skills/publinker` and
+`~/.agents/skills/publinker`. For any other assistant, point it at the file
+that `publinker skill path` prints.

publinker_cli-0.6.2.dist-info/RECORD

@@ -0,0 +1,26 @@
+publinker_cli/__init__.py,sha256=lNxLRBBaSEJQvjLBcIMSzm_K43eNXI6tppU9FSwvQ9Y,526
+publinker_cli/__main__.py,sha256=VVzUKqRBm-Gy-Rbcx5cRKslUQLZCrDs8FKRG1mP-RDs,2604
+publinker_cli/audience.py,sha256=fY9PRciHKqdLsP_p9JGPjD4cCTiYFoEg5NGYDnwbcQ4,2611
+publinker_cli/auth.py,sha256=rAqzsVp6UBhJsBg3ihUwV4OLpo9vpl5VNFn9x6mU83Y,5070
+publinker_cli/client.py,sha256=adv89_23T3nDg4rZR_sLG43zkdd9wZL29qXEMk9qs7Q,6941
+publinker_cli/config.py,sha256=Bs-DWTwpMpdESqQcMtOBRBYUb8soD4KQzRKlRDx_Bxw,1799
+publinker_cli/dispatch_cli.py,sha256=1_k-6o93GLGlLAqkiYN4nhi-kPheJeA8dNG9t0q1pk8,14206
+publinker_cli/keyring_store.py,sha256=9JQbJVHk_eG_1YphEJFSkAOnQ3TQWrBM58S_1GLF-rw,3456
+publinker_cli/manifest.py,sha256=kA9pEMAyL_3op9UXEs-3uy-jbzsje-dHjOjzHMB_Xec,15151
+publinker_cli/routes.yaml,sha256=TsAy1zubWAufd0zv3F5uHkXHO1LIHZLwo9N64jeesY8,38345
+publinker_cli/state.py,sha256=_N9bA4kcCfb6LEzQopNKFsSV1gMtBtTKs-28hxWSCuY,4420
+publinker_cli/version.py,sha256=8kSbaUgMEqYvf_VBAuFpBs-RZihEKZCY6kvAJ5U4TSw,2060
+publinker_cli/write_gate.py,sha256=F6a-SWrfDBwsEIzAvSwFmWc0Yd9ATEzcvqpXuP5FKnY,1625
+publinker_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+publinker_cli/commands/auth_cmds.py,sha256=i4SNh16FeAKdLp4wAHsjwWFtAK3pbCpePPNTfcjFr4Y,2216
+publinker_cli/commands/report_options.py,sha256=pQf-llhG4J1t22zA6giyv27_d2-6G1UtGmgj5cxie_Q,3146
+publinker_cli/commands/skill.py,sha256=XEcHag0d8uJYtHuo83IK3jH3NwLaiXFYteGe2h-Qt4s,1493
+publinker_cli/commands/token_cmd.py,sha256=jJgvDEvKwFWnkqJMHmyeQunYUxnXnDD7YizLp6hmXmU,3398
+publinker_cli/commands/update.py,sha256=ToPDP7EEvmmPtHhP1husYj7WeG85rTONAqMUZ3tFhJI,7456
+publinker_cli/commands/use.py,sha256=I44yJsswDuUoRzBit3xoeIw18f_J3LNGiwqh58ZUYCA,3262
+publinker_cli/commands/write.py,sha256=zVZ8HV_vfDGu8TITyN2R-2Xbly3JoOw1iEbTsYSkwA0,2292
+publinker_cli/skill/SKILL.md,sha256=Gh7AgNE5EwrDkq3LB2TpvphSW1lm2cWxN1nuM-8tjsU,2411
+publinker_cli-0.6.2.dist-info/METADATA,sha256=jYPPS1TMh1kbhI6j98RQ6A0tGFWkGuC2_q8aabN4H6U,2715
+publinker_cli-0.6.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+publinker_cli-0.6.2.dist-info/entry_points.txt,sha256=N6mAgefPEmix3dV1y3cKNs815txQVjas1NVXIO5Hmn4,57
+publinker_cli-0.6.2.dist-info/RECORD,,

publinker_cli-0.6.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

publinker_cli-0.6.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+publinker = publinker_cli.__main__:app