rankrush-cli 0.1.37__py3-none-any.whl

rankrush/__init__.py

@@ -0,0 +1,3 @@
+"""RankRush CLI — agent-native wrapper for the RankRush Supabase backend."""
+
+__version__ = "0.1.37"

rankrush/cache.py

@@ -0,0 +1,83 @@
+"""Local file cache for time-series CLI data (visibility snapshots, etc.).
+
+Cache directory: ~/.rankrush/cache/
+Each key maps to a JSON file: ~/.rankrush/cache/<key>.json
+
+File format:
+{
+  "entries": [
+    {"ts": "2026-04-04T10:00:00", "data": { ... }},
+    ...
+  ]
+}
+
+Entries are appended in chronological order. The cache is append-only —
+old entries are never deleted, enabling trend queries.
+"""
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _cache_dir() -> Path:
+    d = Path.home() / ".rankrush" / "cache"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _cache_file(key: str) -> Path:
+    safe = key.replace("/", "_").replace(":", "_")
+    return _cache_dir() / f"{safe}.json"
+
+
+def append(key: str, data: dict) -> str:
+    """Append a snapshot to the cache. Returns the timestamp written."""
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    path = _cache_file(key)
+
+    if path.exists():
+        with path.open() as f:
+            store = json.load(f)
+    else:
+        store = {"entries": []}
+
+    store["entries"].append({"ts": ts, "data": data})
+
+    with path.open("w") as f:
+        json.dump(store, f, indent=2)
+
+    return ts
+
+
+def latest(key: str, n: int = 1) -> list[dict]:
+    """Return the N most recent entries for a key, newest first."""
+    path = _cache_file(key)
+    if not path.exists():
+        return []
+    with path.open() as f:
+        store = json.load(f)
+    return list(reversed(store.get("entries", [])))[:n]
+
+
+def history(key: str, days: int = 7) -> list[dict]:
+    """Return all entries within the last `days` days, oldest first."""
+    from datetime import timedelta
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    path = _cache_file(key)
+    if not path.exists():
+        return []
+    with path.open() as f:
+        store = json.load(f)
+
+    result = []
+    for entry in store.get("entries", []):
+        try:
+            ts = datetime.fromisoformat(entry["ts"].replace("Z", "+00:00"))
+            if ts >= cutoff:
+                result.append(entry)
+        except (KeyError, ValueError):
+            continue
+    return result

rankrush/cli.py

@@ -0,0 +1,241 @@
+"""RankRush CLI — entrypoint.
+
+Usage:
+    rankrush <command> [options]
+
+First time? Run ``rankrush init`` to set up your API key.
+
+Environment (loaded from ~/.config/rankrush/.env, or set in your shell):
+    RANKRUSH_API_KEY            Required — generate from dashboard → Settings → API Keys
+    SUPABASE_PUBLISHABLE_KEY    Required — Supabase project anon (publishable) key
+                                fallback name: RANKRUSH_SUPABASE_KEY
+
+The Supabase URL is compiled in (rankrush.ai project). ``--stage`` targets the
+stage environment instead (bundled stage URL + anon key); power users can also
+set ``RANKRUSH_SUPABASE_URL`` / ``SUPABASE_PUBLISHABLE_KEY`` directly.
+
+User-level config:
+    ~/.rankrush/config.toml     [api] table with ``api_key`` key.
+                                See cli/README.md.
+
+Global flags:
+    --api-key KEY       Override the RankRush API key.
+    --stage             Target the stage environment (app.stage.rankrush.ai).
+                        Uses RANKRUSH_STAGE_API_KEY; set it with
+                        ``rankrush init --stage``.
+    --debug             Re-raise the underlying exception (with traceback)
+                        instead of printing the friendly one-line CliError.
+"""
+
+import os
+
+import click
+from dotenv import load_dotenv
+
+from rankrush import client, env_file, output
+from rankrush.errors import CliError
+
+# Load env vars in priority order. ``override=False`` everywhere means the
+# first source wins (shell exports > repo cli/.env > user-level env file).
+# (1) Shell environment is already in ``os.environ`` — nothing to do.
+# (2) Repo-local cli/.env (when working from a repo checkout).
+_repo_env_path = os.path.join(os.path.dirname(__file__), "..", ".env")
+load_dotenv(dotenv_path=_repo_env_path, override=False)
+# (3) User-level env file (created by ``rankrush init``).
+env_file.load_user_env(override=False)
+
+from rankrush.commands.profiles import profiles_group
+from rankrush.commands.visibility import visibility_group
+from rankrush.commands.keywords import keywords_group
+from rankrush.commands.buzz.drafts import drafts_group
+from rankrush.commands.buzz.research import research_group
+from rankrush.commands.buzz.strategy import strategy_group
+from rankrush.commands.buzz.posts import posts_group
+from rankrush.commands.smoke import smoke
+from rankrush.commands.audit import audit_group
+from rankrush.commands.nodes import nodes_group
+from rankrush.commands.report import report_group
+from rankrush.commands.leadgen import leadgen_group
+from rankrush.commands.blog import blog_group
+from rankrush.commands.cms import cms_group
+from rankrush.commands.scans import scans_group
+from rankrush.commands.leads import leads_group
+from rankrush.commands.init import init
+
+
+class CliErrorBoundaryGroup(click.Group):
+    """Top-level Click group that traps `CliError` from any sub-command.
+
+    By default, prints `ERROR: <human message>` to stderr (with secrets
+    scrubbed) and exits with code 1 — no Python traceback. With `--debug`
+    the original exception is re-raised so the traceback is visible.
+    """
+
+    def invoke(self, ctx: click.Context) -> object:
+        try:
+            return super().invoke(ctx)
+        except CliError as exc:
+            if ctx.obj and ctx.obj.get("debug"):
+                raise
+            as_json = _detect_json_flag(ctx)
+            output.error_message(str(exc), as_json=as_json)
+            ctx.exit(1)
+
+
+def _detect_json_flag(ctx: click.Context) -> bool:
+    """Walk the context chain looking for an `as_json` parameter on any sub-command."""
+    current = ctx
+    while current is not None:
+        params = current.params or {}
+        if params.get("as_json"):
+            return True
+        current = current.parent
+    return False
+
+
+_HELP_INTRO = """\
+RankRush CLI — track and improve your AI discoverability from the terminal.
+
+\b
+First five minutes:
+  1. Install:    pip install rankrush-cli
+  2. Configure:  rankrush init       (paste your API key)
+  3. Verify:     rankrush smoke      (live health check)
+  4. Explore:    rankrush profiles list
+
+Get an API key at https://app.rankrush.ai → Settings → API Keys.
+
+Full docs: https://github.com/nikolapevic/rankrush#readme
+"""
+
+
+@click.group(cls=CliErrorBoundaryGroup, help=_HELP_INTRO)
+@click.option(
+    "--api-key",
+    "api_key",
+    envvar="RANKRUSH_API_KEY",
+    default=None,
+    help="Override the RankRush API key.",
+)
+@click.option(
+    "--stage",
+    is_flag=True,
+    default=False,
+    help="Target the stage environment (app.stage.rankrush.ai). Uses "
+    "RANKRUSH_STAGE_API_KEY — set it with `rankrush init --stage`.",
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    default=False,
+    help="Re-raise underlying exceptions with full traceback (developer mode).",
+)
+@click.version_option(package_name="rankrush-cli")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    api_key: str | None,
+    stage: bool,
+    debug: bool,
+):
+    ctx.ensure_object(dict)
+    ctx.obj["debug"] = debug
+    ctx.obj["api_key"] = api_key
+    ctx.obj["stage"] = stage
+    # Stash the flag values into the client module so the next ``_load()``
+    # call picks them up. Click resolves ``RANKRUSH_API_KEY`` into this arg
+    # automatically — but the layered resolver in ``rankrush.config`` must
+    # remain authoritative when the flag is absent, so we only forward a
+    # value that came from an explicit ``--api-key`` invocation. Click's
+    # ``envvar=`` would otherwise short-circuit the file lookup.
+    client.set_overrides(
+        api_key=api_key if _flag_was_explicit(ctx, "api_key") else None,
+        stage=stage,
+    )
+
+
+def _flag_was_explicit(ctx: click.Context, name: str) -> bool:
+    """Return True only if a flag value came from the command line.
+
+    Click's ``get_parameter_source`` distinguishes COMMANDLINE from ENVIRONMENT
+    / DEFAULT / DEFAULT_MAP. When the value came from env, we want the
+    config-file layer to still win for the *other* setting if the user only
+    set one env var — so we let ``rankrush.config`` re-evaluate the env on
+    its own rather than treating Click's env-pull as a flag override.
+    """
+    source = ctx.get_parameter_source(name)
+    if source is None:
+        return False
+    return source == click.core.ParameterSource.COMMANDLINE
+
+
+# Top-level commands
+cli.add_command(init)
+cli.add_command(smoke)
+cli.add_command(profiles_group)
+cli.add_command(visibility_group)
+cli.add_command(keywords_group)
+cli.add_command(audit_group)
+cli.add_command(nodes_group)
+cli.add_command(report_group)
+cli.add_command(leadgen_group)
+cli.add_command(blog_group)
+cli.add_command(cms_group)
+cli.add_command(scans_group)
+cli.add_command(leads_group)
+
+# buzz sub-group
+@cli.group("buzz")
+def buzz_group():
+    """Buzz (Reddit/Quora community engagement) commands."""
+
+
+buzz_group.add_command(drafts_group)
+buzz_group.add_command(research_group)
+buzz_group.add_command(strategy_group)
+buzz_group.add_command(posts_group)
+
+
+@cli.command("repl")
+def repl():
+    """Start an interactive REPL session.
+
+    Type commands as you would on the CLI (without the 'rankrush' prefix).
+    Type 'exit' or Ctrl-D to quit.
+
+    Example:
+      (rankrush) > buzz drafts list --json
+      (rankrush) > visibility check --profile-id 718bb7c7-ba2c-4e24-8333-5aac575c9cc0
+    """
+    import shlex
+
+    click.echo("RankRush REPL — type 'help' for commands, 'exit' to quit.")
+    while True:
+        try:
+            line = input("(rankrush) > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            click.echo("\nBye.")
+            break
+
+        if not line:
+            continue
+        if line in ("exit", "quit"):
+            break
+        if line == "help":
+            click.echo(cli.get_help(click.Context(cli)))
+            continue
+
+        try:
+            args = shlex.split(line)
+            # Invoke as a standalone Click call so output goes to stdout normally
+            cli.main(args=args, standalone_mode=False)
+        except SystemExit:
+            pass  # Click raises SystemExit(0) on --help; suppress it in REPL
+        except CliError as exc:
+            click.echo(f"Error: {exc}", err=True)
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+
+
+if __name__ == "__main__":
+    cli()

rankrush/client.py

@@ -0,0 +1,227 @@
+"""Supabase HTTP client — the real backend is always the hard dependency.
+
+The Supabase URL is compiled in (``rankrush.config.DEFAULT_SUPABASE_URL``)
+and points at the single rankrush.ai project — it is not overridable by
+flag, env, or config file by design. Only the API key resolves via a
+layered lookup (see ``rankrush.config``):
+
+  API key:  ``--api-key`` flag → ``RANKRUSH_API_KEY`` env → (none)
+
+The Supabase publishable (anon) key is bundled with the CLI — it is public
+by design (the React app at app.rankrush.ai embeds the same value in every
+browser session). It can still be overridden via ``SUPABASE_PUBLISHABLE_KEY``
+or the fallback ``RANKRUSH_SUPABASE_KEY`` for self-hosters, but a fresh
+install never needs to configure it.
+
+All HTTP and JSON-decoding errors are raised as `CliError` subclasses
+(`AuthError`, `NetworkError`, `ServerError`, `MalformedResponseError`,
+`ConfigError`). Bare `requests` exceptions never escape this module.
+"""
+
+import json
+import os
+
+import requests
+
+from rankrush.config import (
+    DEFAULT_SUPABASE_URL,
+    STAGE_SUPABASE_URL,
+    resolve_api_key,
+)
+from rankrush.errors import (
+    AuthError,
+    ConfigError,
+    LimitExceededError,
+    MalformedResponseError,
+    NetworkError,
+    ServerError,
+)
+
+# Bundled Supabase publishable (anon) keys — public by design; the React apps
+# embed these same values in every browser session, so they are safe to ship
+# with the CLI. Selected by target (prod default, or stage via --stage).
+# Self-hosters override via SUPABASE_PUBLISHABLE_KEY (or RANKRUSH_SUPABASE_KEY).
+_BUNDLED_KEY = "sb_publishable_yvyF-kVnm5RQUJFbGRlMuQ_9e9HGLS3"
+_STAGE_BUNDLED_KEY = "sb_publishable_9kp-2oku93xo4FexUvEbHQ_ftFqDouR"
+
+_BASE: str | None = None
+_KEY: str | None = None
+_API_KEY: str | None = None
+
+# CLI-flag overrides set by ``cli.py`` after Click parses the root group's
+# ``--api-key`` / ``--stage`` options. Read by ``_load()`` on first request and
+# never re-read until the module-level cache is reset (tests).
+_FLAG_API_KEY: str | None = None
+_STAGE: bool = False
+
+
+def set_overrides(api_key: str | None = None, stage: bool = False) -> None:
+    """Stash the ``--api-key`` / ``--stage`` flag values for the next ``_load()``.
+
+    Called by the Click root group in ``rankrush.cli`` before any sub-command
+    runs. ``api_key`` may be None (flag not provided), in which case the
+    env/file chain handles resolution. ``stage`` selects the stage target
+    (URL + publishable key + ``RANKRUSH_STAGE_API_KEY``).
+    """
+    global _FLAG_API_KEY, _STAGE
+    _FLAG_API_KEY = api_key
+    _STAGE = stage
+
+
+def _load() -> None:
+    """Resolve connection settings into module-level cache.
+
+    Idempotent — once ``_BASE`` is set the function is a no-op so per-request
+    callers don't pay re-resolution cost. Tests reset the three module
+    globals to None to force re-evaluation.
+    """
+    global _BASE, _KEY, _API_KEY
+    if _BASE is not None:
+        return
+
+    # Target selects the bundled URL + publishable key (prod default, or stage
+    # via --stage). RANKRUSH_SUPABASE_URL / SUPABASE_PUBLISHABLE_KEY still
+    # override the bundled defaults for power users / self-hosters.
+    default_url = STAGE_SUPABASE_URL if _STAGE else DEFAULT_SUPABASE_URL
+    default_key = _STAGE_BUNDLED_KEY if _STAGE else _BUNDLED_KEY
+    _BASE = os.getenv("RANKRUSH_SUPABASE_URL") or default_url
+    _KEY = (
+        os.getenv("SUPABASE_PUBLISHABLE_KEY")
+        or os.getenv("RANKRUSH_SUPABASE_KEY")
+        or default_key
+    )
+    _API_KEY = resolve_api_key(_FLAG_API_KEY, stage=_STAGE)
+
+    if not _API_KEY:
+        if _STAGE:
+            raise ConfigError(
+                "RANKRUSH_STAGE_API_KEY is not set. Run `rankrush init --stage` "
+                "to configure, or generate a key at app.stage.rankrush.ai → "
+                "Settings → API Keys."
+            )
+        raise ConfigError(
+            "RANKRUSH_API_KEY is not set. Run `rankrush init` to configure, "
+            "or generate a key in the RankRush dashboard → Settings → API Keys."
+        )
+
+
+def _auth_headers() -> dict:
+    _load()
+    return {
+        "Authorization": f"Bearer {_API_KEY}",
+        "apikey": _KEY,
+        "Content-Type": "application/json",
+    }
+
+
+def _raise_for_status(resp: requests.Response, context: str) -> None:
+    """Translate an HTTP error response into the appropriate CliError subclass.
+
+    `context` is a short label (e.g. function name or table name) used in the
+    user-facing message. Never include URL, key, or response body — those may
+    contain secrets.
+    """
+    status = resp.status_code
+    if status < 400:
+        return
+
+    if status in (401, 403):
+        raise AuthError(
+            "API key rejected. Run `rankrush init` to (re)configure, or check "
+            "`RANKRUSH_API_KEY` in your .env or environment."
+        )
+    if status >= 500:
+        raise ServerError(
+            f"RankRush backend returned {status} for {context}. Try again in a minute."
+        )
+    # 422 with a tier-limit body is part of the contract — surface the
+    # structured fields as LimitExceededError so callers can format an
+    # actionable message. Any other 4xx still falls through to generic
+    # ServerError to avoid leaking PII from arbitrary error bodies.
+    if status == 422:
+        try:
+            body = resp.json()
+        except (json.JSONDecodeError, ValueError):
+            body = None
+        if isinstance(body, dict) and body.get("code") in (
+            "keyword_limit_exceeded",
+            "profile_keyword_limit",
+            "limit_exceeded",
+        ):
+            code = str(body["code"])
+            limit = body.get("limit")
+            used = body.get("used")
+            tier = body.get("tier")
+            upgrade_to = body.get("upgrade_to")
+            if code == "profile_keyword_limit":
+                msg = (
+                    f"Per-profile keyword limit reached ({used}/{limit}). "
+                    "Remove keywords from this profile before generating more."
+                )
+            else:
+                tier_label = (tier or "your").capitalize() if tier else "your"
+                if upgrade_to:
+                    msg = (
+                        f"You're at your keyword limit ({used}/{limit} for {tier_label} tier). "
+                        f"Upgrade to {str(upgrade_to).capitalize()} for more: "
+                        "https://app.rankrush.ai/billing"
+                    )
+                else:
+                    msg = (
+                        f"You're at your keyword limit ({used}/{limit}). "
+                        "Contact sales for a higher cap."
+                    )
+            raise LimitExceededError(
+                msg,
+                code=code,
+                limit=limit,
+                used=used,
+                tier=tier,
+                upgrade_to=upgrade_to,
+            )
+    # 4xx other than auth — surface the status code only; body may contain PII.
+    raise ServerError(
+        f"RankRush backend returned {status} for {context}."
+    )
+
+
+def _decode_json(resp: requests.Response, context: str):
+    """Parse a JSON response body. Raises MalformedResponseError on failure."""
+    try:
+        return resp.json()
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise MalformedResponseError(
+            f"Backend returned a non-JSON response for {context}."
+        ) from exc
+
+
+def invoke_function(name: str, body: dict, timeout: int = 60) -> dict:
+    """POST to a Supabase Edge Function.
+
+    Raises:
+      AuthError              — backend rejected the API key
+      NetworkError           — connection failure or timeout
+      ServerError            — backend returned 4xx/5xx
+      MalformedResponseError — response body is not valid JSON
+      ConfigError            — required env vars missing
+    """
+    _load()
+    url = f"{_BASE}/functions/v1/{name}"
+    try:
+        resp = requests.post(url, json=body, headers=_auth_headers(), timeout=timeout)
+    except requests.exceptions.Timeout as exc:
+        raise NetworkError(
+            f"Request to edge function {name!r} timed out after {timeout}s."
+        ) from exc
+    except requests.exceptions.ConnectionError as exc:
+        raise NetworkError(
+            "Couldn't reach the RankRush API. Check your internet connection."
+        ) from exc
+    except requests.exceptions.RequestException as exc:
+        raise NetworkError(
+            f"Network error calling edge function {name!r}."
+        ) from exc
+
+    _raise_for_status(resp, context=f"edge function {name!r}")
+    return _decode_json(resp, context=f"edge function {name!r}")
+