socialscrape-cli 0.1.0__py3-none-any.whl

socialscrape_cli/cli.py

@@ -0,0 +1,689 @@
+"""socialscrape: social media data from the command line.
+
+    socialscrape github user torvalds
+    socialscrape transcript https://www.youtube.com/watch?v=dQw4w9WgXcQ
+    socialscrape search threads "open source" --all --max-credits 20
+    socialscrape facebook --help              # the resources of a platform
+    socialscrape facebook profile-posts --help
+
+Commands and platforms come from the generated catalog (stubs excluded), so
+this file names no platform. Results go to stdout; the price of each call and
+anything else for humans go to stderr, so `socialscrape ... | jq` stays clean.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import getpass
+import json
+import os
+import sys
+from dataclasses import dataclass
+from typing import IO, Any
+
+import httpx
+
+from . import __version__, config, table
+from .catalog import Catalog, Endpoint, Param, load_catalog
+from .client import ApiClient, ApiResponse
+
+EXIT_OK, EXIT_API, EXIT_USAGE, EXIT_AUTH, EXIT_RETRY = 0, 1, 2, 3, 4
+AUTH_CODES = {"unauthorized", "forbidden", "insufficient_credits"}
+GLOBAL_FLAGS = {"key", "api_url", "output", "json", "table", "ndjson", "envelope", "all", "pages", "max_pages",
+                "max_items", "max_credits", "quiet", "timeout", "raw", "help", "version", "dry_run"}
+CROSS = {"profile": "profile", "post": "post", "comments": "comments", "search": "search"}
+NATIVE_COMMANDS = ("credits", "usage", "job", "batch", "monitors")
+
+
+class UsageError(Exception):
+    pass
+
+
+class Parser(argparse.ArgumentParser):
+    """argparse that reports a problem as UsageError instead of printing and exiting."""
+
+    def error(self, message: str):  # type: ignore[override]
+        raise UsageError(message)
+
+
+@dataclass
+class Env:
+    out: IO[str]
+    err: IO[str]
+    stdin: IO[str]
+    environ: dict[str, str]
+    http: httpx.Client | None
+    cat: Catalog
+    out_tty: bool
+    err_tty: bool
+
+    def say(self, msg: str) -> None:
+        print(msg, file=self.err)
+
+
+def cli_name(s: str) -> str:
+    return s.replace("_", "-").replace(".", "-").lower()
+
+
+# ------------------------------------------------------------------ global options
+
+
+def global_parser() -> argparse.ArgumentParser:
+    g = argparse.ArgumentParser(add_help=False, allow_abbrev=False)
+    g.add_argument("--key", help="API key (default: $SOCIALSCRAPE_API_KEY, then the saved one)")
+    g.add_argument("--api-url", dest="api_url")
+    g.add_argument("-o", "--output", choices=("json", "table", "ndjson"))
+    g.add_argument("--json", action="store_true")
+    g.add_argument("--table", action="store_true")
+    g.add_argument("--ndjson", action="store_true")
+    g.add_argument("--envelope", action="store_true", help="print the whole response, not just its data")
+    g.add_argument("--raw", action="store_true", help="ask for the platform's original object and print the whole response")
+    g.add_argument("--all", action="store_true", help="follow cursors to the end (each page costs credits)")
+    g.add_argument("--pages", type=int, default=1)
+    g.add_argument("--max-pages", dest="max_pages", type=int, default=50)
+    g.add_argument("--max-items", dest="max_items", type=int)
+    g.add_argument("--max-credits", dest="max_credits", type=int)
+    g.add_argument("--dry-run", dest="dry_run", action="store_true", help="show the request and its price; send nothing")
+    g.add_argument("-q", "--quiet", action="store_true")
+    g.add_argument("--timeout", type=float, default=70.0)
+    g.add_argument("--version", action="store_true")
+    g.add_argument("-h", "--help", action="store_true")
+    return g
+
+
+# ------------------------------------------------------------------ resource parsers
+
+
+def _bool(v: str) -> bool:
+    if v.lower() in ("1", "true", "yes", "on"):
+        return True
+    if v.lower() in ("0", "false", "no", "off"):
+        return False
+    raise argparse.ArgumentTypeError(f"expected true or false, got {v!r}")
+
+
+def _json_value(v: str) -> Any:
+    try:
+        return json.loads(v)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(f"expected JSON: {e}") from None
+
+
+def positional_candidates(ep: Endpoint) -> list[Param]:
+    required = [p for p in ep.params if p.required and p.location != "body"]
+    if required:
+        return required[:1]
+    for group in ep.one_of:
+        return [p for n in group if (p := ep.param(n)) is not None]
+    return []
+
+
+def hyphenate(args: list[str]) -> list[str]:
+    """`--max_age_days=7` and `--max-age-days=7` are the same option."""
+    out = []
+    for a in args:
+        if a.startswith("--") and len(a) > 2:
+            name, eq, val = a.partition("=")
+            a = name.replace("_", "-") + eq + val
+        out.append(a)
+    return out
+
+
+def looks_like_url(v: str) -> bool:
+    return v.startswith(("http://", "https://")) or ("/" in v and "." in v.split("/")[0])
+
+
+def resource_parser(ep: Endpoint, prog: str) -> argparse.ArgumentParser:
+    cands = positional_candidates(ep)
+    ap = Parser(prog=prog, allow_abbrev=False, description=f"{ep.summary}. {price(ep)}.\n{ep.description}".strip(),
+                                 formatter_class=argparse.RawDescriptionHelpFormatter,
+                                 epilog="Global options (anywhere on the line): -o json|table|ndjson, --all, --pages N, "
+                                        "--max-credits N, --raw, --envelope, --key, -q. See `socialscrape --help`.")
+    if cands:
+        ap.add_argument("value", nargs="?", help="/".join(p.name for p in cands) + " (the form is detected)")
+    taken: set[str] = set()
+    for p in ep.params:
+        if p.name == "raw":
+            continue  # the global --raw
+        opts = [p.name]
+        extra = ["max-age"] if p.name == "max_age_days" else list(p.aliases)
+        for a in extra:
+            if a not in opts and a not in GLOBAL_FLAGS:
+                opts.append(a)
+        strings: list[str] = []
+        for o in opts:
+            flag = "--" + o.replace("_", "-")  # `--max_age_days` is accepted too: see hyphenate()
+            if flag not in taken:
+                taken.add(flag)
+                strings.append(flag)
+        help_ = p.description + (f" One of: {', '.join(p.enum)}." if p.enum else "") + (" (required)" if p.required else "")
+        kw: dict[str, Any] = {"dest": p.name, "help": help_}
+        if p.type == "boolean":
+            ap.add_argument(*strings, nargs="?", const=True, type=_bool, default=None, **kw)
+        elif p.type == "integer":
+            ap.add_argument(*strings, type=int, default=None, **kw)
+        elif p.type == "number" and p.name != "max_age_days":
+            ap.add_argument(*strings, type=float, default=None, **kw)
+        elif p.type in ("array", "object"):
+            ap.add_argument(*strings, type=_json_value, default=None, **kw)
+        else:
+            ap.add_argument(*strings, default=None, choices=list(p.enum) if p.enum else None, **kw)
+    return ap
+
+
+def price(ep: Endpoint) -> str:
+    return {"free": "Free", "standard": "1 credit", "transcript": "1 credit (AI transcription: 1 up to 2 minutes, then "
+            "5 per started minute of the whole video)", "per_5_items": "1 credit per 5 items", "batch": "Sum of its requests"}.get(ep.credits, ep.credits)
+
+
+def params_from(ep: Endpoint, ns: argparse.Namespace, g: argparse.Namespace) -> dict[str, Any]:
+    given = {p.name: getattr(ns, p.name) for p in ep.params if hasattr(ns, p.name) and getattr(ns, p.name) is not None}
+    value = getattr(ns, "value", None)
+    if value is not None:
+        cands = positional_candidates(ep)
+        if looks_like_url(value):
+            target = next((p for p in cands if p.type == "url"), cands[0])
+        else:
+            target = next((p for p in cands if p.type != "url"), cands[0])
+        if target.name in given:
+            raise UsageError(f"{target.name} given twice (as the argument and as --{target.name.replace('_', '-')})")
+        given[target.name] = value
+    if g.raw and ep.param("raw") is not None:
+        given["raw"] = True
+    missing = [p.name for p in ep.params if p.required and p.location != "body" and given.get(p.name) in (None, "")]
+    if missing:
+        raise UsageError(f"{ep.id} needs: {', '.join(missing)}")
+    for grp in ep.one_of:
+        if not any(given.get(n) not in (None, "") for n in grp):
+            raise UsageError(f"{ep.id} needs one of: {' or '.join(grp)}")
+    return given
+
+
+# ------------------------------------------------------------------ running a request
+
+
+def key_for(env: Env, g: argparse.Namespace, cfg: dict) -> str | None:
+    return g.key or env.environ.get("SOCIALSCRAPE_API_KEY") or cfg.get("api_key")
+
+
+def exit_code_for(body: dict) -> int:
+    err = body.get("error") or {}
+    code = err.get("code")
+    if code in AUTH_CODES:
+        return EXIT_AUTH
+    return EXIT_RETRY if err.get("retryable") else EXIT_API
+
+
+def emit(env: Env, g: argparse.Namespace, body: dict) -> None:
+    """Print a successful result in the chosen format."""
+    fmt = "json"
+    if g.table:
+        fmt = "table"
+    elif g.ndjson:
+        fmt = "ndjson"
+    elif g.output:
+        fmt = g.output
+    elif g.json:
+        fmt = "json"
+    payload: Any = body if (g.envelope or g.raw) else body.get("data")
+    if fmt == "table":
+        print(table.render(payload.get("data") if (g.envelope or g.raw) else payload), file=env.out)
+    elif fmt == "ndjson":
+        data = payload.get("data") if (g.envelope or g.raw) else payload
+        rows = data.get("items") if isinstance(data, dict) and isinstance(data.get("items"), list) else [data]
+        for row in rows:
+            print(json.dumps(row, ensure_ascii=False, separators=(",", ":")), file=env.out)
+    elif env.out_tty:
+        print(json.dumps(payload, ensure_ascii=False, indent=2), file=env.out)
+    else:
+        print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")), file=env.out)
+
+
+def footer(env: Env, g: argparse.Namespace, body: dict, charged: int, pages: int) -> None:
+    if g.quiet:
+        return
+    bits = [f"credits charged: {charged}"]
+    if body.get("credits_remaining") is not None:
+        bits.append(f"remaining: {body['credits_remaining']}")
+    if body.get("cached"):
+        bits.append("cached")
+    if pages > 1:
+        bits.append(f"pages: {pages}")
+    if body.get("has_more") and pages >= 1:
+        bits.append(f"more available (cursor: {body.get('cursor')})")
+    env.say(" | ".join(bits))
+
+
+def run_request(env: Env, g: argparse.Namespace, cfg: dict, ep: Endpoint, params: dict[str, Any],
+                path_params: dict[str, str] | None = None, body: Any = None) -> int:
+    if g.dry_run:
+        path = ep.path
+        for name, value in (path_params or {}).items():
+            path = path.replace("{" + name + "}", str(value))
+        shown = {"method": ep.method, "path": path, "query": {k: v for k, v in params.items() if v is not None},
+                 "price": price(ep), "response": ep.response}
+        if body is not None:
+            shown["body"] = body
+        print(json.dumps(shown, ensure_ascii=False, indent=2 if env.out_tty else None), file=env.out)
+        return EXIT_OK
+    key = key_for(env, g, cfg)
+    if not key:
+        env.say("error: no API key. Run `socialscrape login`, or set SOCIALSCRAPE_API_KEY. "
+                f"Get a key at {env.cat.api['dashboard_url']}")
+        return EXIT_AUTH
+    api_url = g.api_url or env.environ.get("SOCIALSCRAPE_API_URL") or cfg.get("api_url") or env.cat.api["base_url"]
+    client = ApiClient(api_url, http=env.http, timeout=g.timeout, user_agent=f"socialscrape-cli/{__version__}")
+    try:
+        want_pages = (g.max_pages if g.all else g.pages) if ep.paginated else 1
+        total = 0
+        collected: list[Any] = []
+        resp: ApiResponse | None = None
+        pages = 0
+        query = dict(params)
+        while True:
+            resp = client.request(ep.method, ep.path, api_key=key, query=query, body=body, path_params=path_params)
+            pages += 1
+            rb = resp.body
+            if not rb.get("ok"):
+                if pages > 1 and collected:
+                    env.say(f"stopped after {pages - 1} page(s): {(rb.get('error') or {}).get('message')}")
+                    break
+                return fail(env, g, rb)
+            total += int(rb.get("credits_charged") or 0)
+            data = rb.get("data")
+            if want_pages == 1 or not isinstance(data, dict) or "items" not in data:
+                collected = []
+                break
+            collected += data["items"]
+            more = bool(rb.get("has_more")) and rb.get("cursor")
+            if not more or pages >= want_pages:
+                break
+            if g.max_items and len(collected) >= g.max_items:
+                break
+            if g.max_credits is not None and total >= g.max_credits:
+                env.say(f"stopped: --max-credits {g.max_credits} reached")
+                break
+            if not g.quiet:
+                env.say(f"page {pages}: {len(collected)} items so far, {total} credits")
+            query["cursor"] = rb["cursor"]
+        assert resp is not None
+        out = dict(resp.body)
+        if collected:
+            if g.max_items:
+                collected = collected[: g.max_items]
+            data = dict(out["data"])
+            data["items"] = collected
+            out["data"] = data
+            out["credits_charged"] = total
+        emit(env, g, out)
+        footer(env, g, out, total, pages)
+        return EXIT_OK
+    finally:
+        client.close()
+
+
+def fail(env: Env, g: argparse.Namespace, body: dict) -> int:
+    err = body.get("error") or {}
+    if g.envelope or g.raw:
+        print(json.dumps(body, ensure_ascii=False), file=env.out)
+    rid = f" (request {body['request_id']})" if body.get("request_id") else ""
+    env.say(f"error: {err.get('code', 'unknown')}: {err.get('message', 'request failed')}{rid}")
+    if err.get("retryable"):
+        env.say("this error is retryable; failures are free")
+    code = err.get("code")
+    if code == "insufficient_credits":
+        env.say(f"buy credits at {env.cat.api['dashboard_url']}")
+    elif code == "invalid_params":
+        env.say("see `socialscrape <platform> <resource> --help` for the parameters")
+    return exit_code_for(body)
+
+
+# ------------------------------------------------------------------ commands
+
+
+def top_help(env: Env) -> str:
+    groups = "\n".join(f"  {cli_name(g.key):<14} {g.title}" for g in env.cat.groups)
+    return f"""socialscrape {__version__}: social media data from the command line
+
+usage: socialscrape <platform> <resource> [value] [--param value ...]
+       socialscrape <command> ...
+
+shortcuts (the platform is an argument):
+  transcript URL              transcript of a video or post, any supported platform
+  profile PLATFORM HANDLE     a profile          post PLATFORM URL      one post
+  search PLATFORM QUERY       keyword search     comments PLATFORM URL  comments on a post
+
+account:
+  login | logout | config     save, remove or show the API key
+  credits                     balance (free)
+  usage [daily|routes]        request history (free)
+  job ID                      result of an async job (free)
+  batch FILE|-                up to 100 requests from JSON, one call
+  monitors ACTION             watch a list and get webhooks
+  endpoints [PLATFORM]        list what you can call
+
+platforms (socialscrape <platform> --help lists its resources):
+{groups}
+
+output:    -o json|table|ndjson (also --json --table --ndjson), --envelope (whole response), --raw (platform's
+           original object included, whole response printed), -q (no price line on stderr)
+preview:   --dry-run shows the request and its price and sends nothing (no key needed)
+paging:    --pages N | --all [--max-pages N] [--max-items N] [--max-credits N]  (each page costs credits)
+auth:      --key K | $SOCIALSCRAPE_API_KEY | `socialscrape login`; --api-url for another server
+exit:      0 ok, 1 API error, 2 usage, 3 key or credits, 4 retryable (rate limit, upstream, network)
+Data goes to stdout; the price and notices go to stderr."""
+
+
+def group_help(env: Env, key: str) -> str:
+    g = env.cat.group(key)
+    assert g is not None
+    rows = [f"{g.title}: {g.description}", "", f"usage: socialscrape {cli_name(key)} <resource> [value] [--param value ...]", ""]
+    for e in env.cat.group_endpoints(key):
+        need = e.signature()
+        rows.append(f"  {cli_name(e.resource):<28} {e.summary}  [{price(e)}]" + (f"  needs {need}" if need else ""))
+    return "\n".join(rows)
+
+
+def find_group(env: Env, name: str) -> str | None:
+    want = cli_name(name)
+    for g in env.cat.groups:
+        if cli_name(g.key) == want:
+            return g.key
+    return None
+
+
+def find_resource(env: Env, group: str, name: str) -> Endpoint | None:
+    want = cli_name(name)
+    for e in env.cat.group_endpoints(group):
+        if cli_name(e.resource) == want:
+            return e
+    return None
+
+
+def suggest(word: str, options: list[str]) -> str:
+    near = difflib.get_close_matches(cli_name(word), [cli_name(o) for o in options], n=3, cutoff=0.5)
+    return f" Did you mean: {', '.join(near)}?" if near else ""
+
+
+def run_resource(env: Env, g: argparse.Namespace, cfg: dict, ep: Endpoint, rest: list[str], prog: str) -> int:
+    ap = resource_parser(ep, prog)
+    if g.help:
+        print(ap.format_help(), file=env.out)
+        return EXIT_OK
+    try:
+        params = params_from(ep, ap.parse_args(hyphenate(rest)), g)
+    except UsageError as e:
+        env.say(f"error: {e}\n{ap.format_usage().strip()}")
+        return EXIT_USAGE
+    return run_request(env, g, cfg, ep, params)
+
+
+def cmd_platform(env: Env, g: argparse.Namespace, cfg: dict, group: str, rest: list[str]) -> int:
+    if not rest:
+        print(group_help(env, group), file=env.out if g.help else env.err)
+        return EXIT_OK if g.help else EXIT_USAGE
+    ep = find_resource(env, group, rest[0])
+    if ep is None:
+        names = [e.resource for e in env.cat.group_endpoints(group)]
+        env.say(f"error: {cli_name(group)} has no resource {rest[0]!r}.{suggest(rest[0], names)}\n" + group_help(env, group))
+        return EXIT_USAGE
+    return run_resource(env, g, cfg, ep, rest[1:], f"socialscrape {cli_name(group)} {cli_name(ep.resource)}")
+
+
+def cmd_cross(env: Env, g: argparse.Namespace, cfg: dict, role: str, rest: list[str]) -> int:
+    table_ = env.cat.roles.get(role, {})
+    if not rest or rest[0].startswith("-"):
+        plats = ", ".join(cli_name(k) for k in table_)
+        print(f"usage: socialscrape {role} <platform> <value> [--param value ...]\nplatforms: {plats}", file=env.out if g.help else env.err)
+        return EXIT_OK if g.help else EXIT_USAGE
+    key = find_group(env, rest[0])
+    if key is None or key not in table_:
+        env.say(f"error: no {role} command for {rest[0]!r}.{suggest(rest[0], list(table_))}\nplatforms: "
+                + ", ".join(cli_name(k) for k in table_))
+        return EXIT_USAGE
+    entry = table_[key]
+    args = rest[1:]
+    if role == "search":
+        kind = entry["default"]
+        if "--kind" in args:
+            i = args.index("--kind")
+            kind = args[i + 1] if i + 1 < len(args) else ""
+            args = args[:i] + args[i + 2:]
+        eid = entry["kinds"].get(kind) or next((v for k, v in entry["kinds"].items() if cli_name(k) == cli_name(kind)), None)
+        if eid is None:
+            env.say(f"error: kind must be one of: {', '.join(entry['kinds'])}")
+            return EXIT_USAGE
+    else:
+        eid = entry
+    ep = env.cat.by_id[eid]
+    return run_resource(env, g, cfg, ep, args, f"socialscrape {role} {cli_name(key)}")
+
+
+def cmd_transcript(env: Env, g: argparse.Namespace, cfg: dict, rest: list[str]) -> int:
+    ep = env.cat.by_id.get("transcript")
+    if ep is None:
+        env.say("error: transcripts are not available in this catalog")
+        return EXIT_USAGE
+    return run_resource(env, g, cfg, ep, rest, "socialscrape transcript")
+
+
+def cmd_endpoints(env: Env, g: argparse.Namespace, rest: list[str]) -> int:
+    if rest:
+        key = find_group(env, rest[0])
+        if key is None:
+            env.say(f"error: unknown platform {rest[0]!r}.{suggest(rest[0], [x.key for x in env.cat.groups])}")
+            return EXIT_USAGE
+        print(group_help(env, key), file=env.out)
+        return EXIT_OK
+    for grp in env.cat.groups:
+        names = ", ".join(cli_name(e.resource) for e in env.cat.group_endpoints(grp.key))
+        print(f"{cli_name(grp.key)}: {names}", file=env.out)
+    return EXIT_OK
+
+
+def native(env: Env, eid: str) -> Endpoint | None:
+    return env.cat.by_id.get(eid)
+
+
+def cmd_account(env: Env, g: argparse.Namespace, cfg: dict, cmd: str, rest: list[str]) -> int:
+    def need(eid: str) -> Endpoint | None:
+        ep = native(env, eid)
+        if ep is None:
+            env.say(f"error: {cmd} is not available on this server")
+        return ep
+
+    try:
+        if cmd == "credits":
+            ep = need("account.credits")
+            return run_request(env, g, cfg, ep, {}) if ep else EXIT_USAGE
+        if cmd == "usage":
+            sub = rest[0] if rest and not rest[0].startswith("-") else ""
+            eid = {"": "account.usage", "daily": "account.usage.daily", "routes": "account.usage.routes"}.get(sub)
+            if eid is None:
+                raise UsageError("usage [daily|routes]")
+            ep = need(eid)
+            if ep is None:
+                return EXIT_USAGE
+            ap = resource_parser(ep, f"socialscrape usage {sub}".strip())
+            return run_request(env, g, cfg, ep, params_from(ep, ap.parse_args(hyphenate(rest[1:] if sub else rest)), g))
+        if cmd == "job":
+            ep = need("jobs.by_id")
+            if ep is None:
+                return EXIT_USAGE
+            if not rest:
+                raise UsageError("job JOB_ID")
+            return run_request(env, g, cfg, ep, {}, path_params={"job_id": rest[0]})
+        if cmd == "batch":
+            ep = need("batch.post")
+            if ep is None:
+                return EXIT_USAGE
+            return run_request(env, g, cfg, ep, {}, body={"requests": batch_requests(env, rest)})
+        if cmd == "monitors":
+            return cmd_monitors(env, g, cfg, rest)
+    except UsageError as e:
+        env.say(f"error: {e}")
+        return EXIT_USAGE
+    return EXIT_USAGE
+
+
+def batch_requests(env: Env, rest: list[str]) -> list[dict]:
+    if not rest:
+        raise UsageError("batch FILE|-   (JSON: a list of {\"endpoint\": \"github.user\", \"params\": {...}})")
+    try:
+        if rest[0] == "-":
+            text = env.stdin.read()
+        else:
+            with open(rest[0], encoding="utf-8") as f:
+                text = f.read()
+    except (OSError, UnicodeDecodeError) as e:
+        raise UsageError(f"cannot read {rest[0]}: {e.strerror or type(e).__name__}") from None
+    try:
+        data = json.loads(text)
+    except ValueError as e:
+        raise UsageError(f"batch input is not JSON: {e}") from None
+    items = data.get("requests") if isinstance(data, dict) else data
+    if not isinstance(items, list) or not items:
+        raise UsageError("batch input must be a non-empty list of requests")
+    out = []
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise UsageError(f"request {i} is not an object")
+        if "path" in item:
+            out.append({"path": item["path"], "params": item.get("params") or {}})
+            continue
+        ep = env.cat.by_id.get(str(item.get("endpoint")))
+        if ep is None or ep.method != "GET" or ep.kind == "native":
+            raise UsageError(f"request {i}: unknown endpoint {item.get('endpoint')!r} (see `socialscrape endpoints`)")
+        out.append({"path": ep.path, "params": item.get("params") or {}})
+    return out
+
+
+MONITOR_ACTIONS = {"create": "monitors.post", "list": "monitors", "delete": "monitors.by_id.delete",
+                   "test": "monitors.by_id.test.post", "deliveries": "monitors.by_id.deliveries",
+                   "events": "monitors.events", "redeliver": "monitors.events.by_id.redeliver.post"}
+
+
+def cmd_monitors(env: Env, g: argparse.Namespace, cfg: dict, rest: list[str]) -> int:
+    avail = {a: env.cat.by_id[i] for a, i in MONITOR_ACTIONS.items() if i in env.cat.by_id}
+    if not rest or rest[0] not in avail:
+        env.say("usage: socialscrape monitors " + "|".join(avail) + " [args]\n"
+                "  create ENDPOINT_ID --webhook-url URL [--interval-minutes N] [--param key=value ...]\n"
+                "  delete|test|deliveries MONITOR_ID    events [MONITOR_ID]    redeliver EVENT_ID")
+        return EXIT_USAGE
+    action, args = rest[0], rest[1:]
+    ep = avail[action]
+    if action == "create":
+        ap = Parser(prog="socialscrape monitors create", allow_abbrev=False)
+        ap.add_argument("endpoint")
+        ap.add_argument("--webhook-url", required=True)
+        ap.add_argument("--interval-minutes", type=int)
+        ap.add_argument("--param", action="append", default=[], metavar="key=value")
+        try:
+            ns = ap.parse_args(hyphenate(args))
+        except UsageError as e:
+            env.say(f"error: {e}")
+            return EXIT_USAGE
+        target = env.cat.by_id.get(ns.endpoint)
+        if target is None or not target.paginated:
+            env.say("error: ENDPOINT_ID must be a list endpoint id (see `socialscrape endpoints`)")
+            return EXIT_USAGE
+        watched = dict(p.split("=", 1) for p in ns.param if "=" in p)
+        body = {"endpoint": target.path, "params": watched, "webhook_url": ns.webhook_url}
+        if ns.interval_minutes:
+            body["interval_minutes"] = ns.interval_minutes
+        return run_request(env, g, cfg, ep, {}, body=body)
+    if action == "list":
+        return run_request(env, g, cfg, ep, {})
+    if action == "events":
+        return run_request(env, g, cfg, ep, {"monitor_id": args[0]} if args else {})
+    if not args:
+        env.say(f"error: monitors {action} needs an id")
+        return EXIT_USAGE
+    name = "event_id" if action == "redeliver" else "monitor_id"
+    return run_request(env, g, cfg, ep, {}, path_params={name: args[0]}, body={} if ep.method == "POST" else None)
+
+
+def cmd_login(env: Env, g: argparse.Namespace, path, cfg: dict, rest: list[str]) -> int:
+    key = g.key or (rest[0] if rest else None)
+    if not key:
+        if env.stdin.isatty():
+            key = getpass.getpass("SocialScrape API key (input hidden): ")
+        else:
+            key = env.stdin.readline().strip()
+    key = (key or "").strip()
+    if not key.startswith("ss_"):
+        env.say("error: that does not look like a SocialScrape key (ss_live_... or ss_test_...)")
+        return EXIT_USAGE
+    api_url = g.api_url or env.environ.get("SOCIALSCRAPE_API_URL") or cfg.get("api_url") or env.cat.api["base_url"]
+    client = ApiClient(api_url, http=env.http, timeout=g.timeout, user_agent=f"socialscrape-cli/{__version__}")
+    try:
+        resp = client.request("GET", "/v1/account/credits", api_key=key)
+    finally:
+        client.close()
+    if not resp.ok:
+        code = (resp.body.get("error") or {}).get("code")
+        if code in AUTH_CODES:
+            env.say(f"error: the API refused that key ({code}); nothing saved")
+            return EXIT_AUTH
+        env.say(f"warning: could not verify the key ({(resp.body.get('error') or {}).get('message')}); saving it anyway")
+    config.save(path, {**cfg, "api_key": key})
+    left = (resp.body.get("data") or {}).get("credits_remaining")
+    env.say(f"saved to {path}" + (f" | credits remaining: {left}" if left is not None else ""))
+    return EXIT_OK
+
+
+# ------------------------------------------------------------------ entry point
+
+
+def main(argv: list[str] | None = None, *, environ: dict[str, str] | None = None, stdout: IO[str] | None = None,
+         stderr: IO[str] | None = None, stdin: IO[str] | None = None, http: httpx.Client | None = None) -> int:
+    env = Env(out=stdout or sys.stdout, err=stderr or sys.stderr, stdin=stdin or sys.stdin,
+              environ=dict(os.environ) if environ is None else environ, http=http, cat=load_catalog(),
+              out_tty=bool((stdout or sys.stdout).isatty()), err_tty=bool((stderr or sys.stderr).isatty()))
+    try:
+        g, rest = global_parser().parse_known_args(sys.argv[1:] if argv is None else argv)
+    except SystemExit:
+        return EXIT_USAGE
+    if g.version:
+        print(f"socialscrape {__version__}", file=env.out)
+        return EXIT_OK
+    if g.pages < 1 or g.max_pages < 1:
+        env.say("error: --pages and --max-pages must be at least 1")
+        return EXIT_USAGE
+    path = config.config_path(env.environ)
+    cfg = config.load(path)
+    if not rest:
+        print(top_help(env), file=env.out if g.help else env.err)
+        return EXIT_OK if g.help else EXIT_USAGE
+    cmd, args = rest[0], rest[1:]
+    if cmd == "help":
+        print(top_help(env), file=env.out)
+        return EXIT_OK
+    if cmd == "login":
+        return cmd_login(env, g, path, cfg, args)
+    if cmd == "logout":
+        if "api_key" in cfg:
+            config.save(path, {k: v for k, v in cfg.items() if k != "api_key"})
+        env.say("removed the saved key" if "api_key" in cfg else "no saved key")
+        return EXIT_OK
+    if cmd == "config":
+        key = key_for(env, g, cfg)
+        src = "--key" if g.key else "$SOCIALSCRAPE_API_KEY" if env.environ.get("SOCIALSCRAPE_API_KEY") else "config file" if cfg.get("api_key") else "-"
+        print(f"config file: {path}\napi key:     {config.mask(key)} (from {src})\napi url:     "
+              f"{g.api_url or env.environ.get('SOCIALSCRAPE_API_URL') or cfg.get('api_url') or env.cat.api['base_url']}", file=env.out)
+        return EXIT_OK
+    if cmd == "endpoints":
+        return cmd_endpoints(env, g, args)
+    if cmd == "transcript":
+        return cmd_transcript(env, g, cfg, args)
+    if cmd in CROSS:
+        return cmd_cross(env, g, cfg, CROSS[cmd], args)
+    if cmd in NATIVE_COMMANDS:
+        return cmd_account(env, g, cfg, cmd, args)
+    group = find_group(env, cmd)
+    if group is not None:
+        return cmd_platform(env, g, cfg, group, args)
+    every = [x.key for x in env.cat.groups] + ["transcript", "login", "credits", "usage", "batch", "monitors", "endpoints", *CROSS]
+    env.say(f"error: unknown command or platform {cmd!r}.{suggest(cmd, every)}\nrun `socialscrape --help`")
+    return EXIT_USAGE