scrapebadger-cli 0.23.2__tar.gz → 0.24.0__tar.gz

scrapebadger_cli-0.24.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: scrapebadger-cli
+Version: 0.24.0
+Summary: ScrapeBadger CLI — Twitter, Vinted, Google, and Web Scraping from the command line
+Author: ScrapeBadger Team
+License: MIT
+Keywords: ai-tools,cli,mcp,scrapebadger,twitter,vinted,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ScrapeBadger CLI
+
+Google Light Search uses the dedicated `/v1/google/light/search` endpoint:
+
+```bash
+scrapebadger google light-search "vinted api" --gl us --hl en
+```
+
+Light returns organic results and related searches for 10 credits per successful
+uncached request. Regular `scrapebadger google search` costs 20 credits and
+returns the full SERP. Cache hits and failed requests are free.
+
+Command-line access to ScrapeBadger APIs, including Etsy, AliExpress, Target, ASOS, Best Buy, search engines, social media and general web scraping.
+
+## Install
+
+```bash
+pip install scrapebadger-cli
+# or: uv tool install scrapebadger-cli
+```
+
+The installed command is `scrapebadger`. To run without installing:
+
+```bash
+uvx --from scrapebadger-cli scrapebadger --help
+```
+
+## Quick Start
+
+```bash
+scrapebadger login                 # approve in the browser; or: scrapebadger login --api-key sb_live_...
+scrapebadger twitter user elonmusk
+scrapebadger twitter search "AI agents" --output table
+scrapebadger vinted search "nike shoes" --market de
+scrapebadger web scrape https://example.com --js
+```
+
+## Getting a key and setting up agents (0.24.0+)
+
+```bash
+scrapebadger init                  # detect Claude Code / Codex / Cursor; install skill + MCP
+scrapebadger init --yes --all      # same, without prompts
+scrapebadger login                 # device flow: open the link, approve, key is saved
+scrapebadger trial                 # 50 free credits without an account (one per network, 7 days)
+scrapebadger connect               # print the link that attaches a trial key to an account
+```
+
+`init` installs the ScrapeBadger skill (`SKILL.md` and `references/endpoints.md`)
+into `~/.claude/skills/scrapebadger` and `~/.codex/skills/scrapebadger`, registers
+the hosted MCP server (`claude mcp add --scope user ...`, `codex mcp add ...`, or a
+merge into `~/.cursor/mcp.json` that keeps your other servers), and offers `login`
+or `trial` when no key is configured. Cursor has no on-disk global rules location,
+so it gets the MCP server only.
+
+`trial` solves a short proof of work, saves the key and prints a notice to pass on
+to your human. A trial key works only from the IP that created it, on read APIs,
+at 10 requests/min, and not through the hosted MCP server. It refuses to replace an
+account key unless you pass `--force`.
+
+## Saved results and free re-reads
+
+Every API command also writes its full JSON response to
+`~/.cache/scrapebadger/results/<api>-<command>-<UTC timestamp>.json` (honours
+`XDG_CACHE_HOME`; the newest 200 are kept) and prints one line to stderr:
+
+```
+saved: ~/.cache/scrapebadger/results/google-search-20261023T101500123456Z.json · credits: 20 · result_id: 6f1c...
+```
+
+stdout is unchanged. Disable with `scrapebadger --no-save ...` or `SCRAPEBADGER_SAVE=0`.
+
+Re-slice a saved result locally, for free:
+
+```bash
+scrapebadger view --summary                       # newest result: types, list lengths, byte sizes
+scrapebadger view --last google --max-items 5 --fields title,link
+scrapebadger view path/to/result.json --jq '.organic_results[].link'   # needs jq on PATH
+```
+
+`--fields` (dotted paths) and `--max-items` apply to the main item list (the
+top-level array, else the largest top-level list); truncation adds
+`"_truncated": {"path", "kept", "total"}`.
+
+Re-read a result from the server within ~15 minutes, free, sliced server-side:
+
+```bash
+scrapebadger results get <result_id> --max-items 3 --fields id,text
+```
+
+## Quotes, bug reports and feedback (all free)
+
+```bash
+scrapebadger quote /v1/google/search -p q="coffee" -p gl=us     # cost, validation, latency
+scrapebadger quote /v1/web/scrape --method POST --body '{"url": "https://example.com"}'
+scrapebadger report-bug "Empty results for a public profile" --request-id <X-Request-ID> --endpoint /v1/instagram/users/x
+scrapebadger feedback "Please add Pinterest" --details "..."
+```
+
+Error messages include the `request_id` to quote in a bug report, and the
+upgrade or claim link when you are out of credits.
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SCRAPEBADGER_API_KEY` | | API key (wins over `.env` and `~/.config/scrapebadger/config.json`) |
+| `SCRAPEBADGER_API_URL` | `https://scrapebadger.com` | API base URL, e.g. a local stack |
+| `SCRAPEBADGER_SITE_URL` | `https://scrapebadger.com` | Where `init` downloads the skill from |
+| `SCRAPEBADGER_MCP_URL` | `https://mcp.scrapebadger.com/mcp` | MCP server `init` registers |
+| `SCRAPEBADGER_SAVE` | `1` | `0` disables saving results |
+
+## Vinted mobile data (0.14.0+)
+
+```sh
+scrapebadger vinted mobile-operations
+scrapebadger vinted mobile sold-comparables --market fr --params '{"catalog_id":"1242","brand_id":"53","status_id":"2"}'
+scrapebadger vinted search "nike" --sizes 206 --materials 43
+```
+
+The catalog lists 76 public read operations with parameter types and examples.
+Each mobile read costs 1 credit; discovery is free. Sold comparables are a
+Vinted-selected sample, not a complete sales history or guaranteed final sale prices.
+
+### Vinted image search
+
+```bash
+scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
+scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53
+```
+
+Provide exactly one of `--image`, `--image-url` or `--image-base64`. JPEG, PNG and
+WebP up to 5 MiB are supported. Returns active listings in visual ranking order;
+10 credits per successful request. Filter with `--catalog-ids`, `--brand-ids`,
+`--status-ids`, `--color-ids`, `--size-ids`, `--material-ids` and price bounds.
+Resend the same image and `--time` from pagination when requesting `--page 2`.
+
+## Dedicated ecommerce APIs
+
+```bash
+scrapebadger etsy search "ceramic mug" --currency USD --country US
+scrapebadger aliexpress search "keyboard"
+scrapebadger target search "laptop" --zip-code 55403 --store-id 1375
+scrapebadger asos search "shoes" --market uk
+scrapebadger bestbuy search "laptop"
+```
+
+Run `scrapebadger <api> --help` to list product, review, store, availability and
+reference commands for that API. Each command supports `--help` for its exact
+parameters. Requests use your API key's existing permissions and credit balance.

scrapebadger_cli-0.24.0/README.md

@@ -0,0 +1,149 @@
+# ScrapeBadger CLI
+
+Google Light Search uses the dedicated `/v1/google/light/search` endpoint:
+
+```bash
+scrapebadger google light-search "vinted api" --gl us --hl en
+```
+
+Light returns organic results and related searches for 10 credits per successful
+uncached request. Regular `scrapebadger google search` costs 20 credits and
+returns the full SERP. Cache hits and failed requests are free.
+
+Command-line access to ScrapeBadger APIs, including Etsy, AliExpress, Target, ASOS, Best Buy, search engines, social media and general web scraping.
+
+## Install
+
+```bash
+pip install scrapebadger-cli
+# or: uv tool install scrapebadger-cli
+```
+
+The installed command is `scrapebadger`. To run without installing:
+
+```bash
+uvx --from scrapebadger-cli scrapebadger --help
+```
+
+## Quick Start
+
+```bash
+scrapebadger login                 # approve in the browser; or: scrapebadger login --api-key sb_live_...
+scrapebadger twitter user elonmusk
+scrapebadger twitter search "AI agents" --output table
+scrapebadger vinted search "nike shoes" --market de
+scrapebadger web scrape https://example.com --js
+```
+
+## Getting a key and setting up agents (0.24.0+)
+
+```bash
+scrapebadger init                  # detect Claude Code / Codex / Cursor; install skill + MCP
+scrapebadger init --yes --all      # same, without prompts
+scrapebadger login                 # device flow: open the link, approve, key is saved
+scrapebadger trial                 # 50 free credits without an account (one per network, 7 days)
+scrapebadger connect               # print the link that attaches a trial key to an account
+```
+
+`init` installs the ScrapeBadger skill (`SKILL.md` and `references/endpoints.md`)
+into `~/.claude/skills/scrapebadger` and `~/.codex/skills/scrapebadger`, registers
+the hosted MCP server (`claude mcp add --scope user ...`, `codex mcp add ...`, or a
+merge into `~/.cursor/mcp.json` that keeps your other servers), and offers `login`
+or `trial` when no key is configured. Cursor has no on-disk global rules location,
+so it gets the MCP server only.
+
+`trial` solves a short proof of work, saves the key and prints a notice to pass on
+to your human. A trial key works only from the IP that created it, on read APIs,
+at 10 requests/min, and not through the hosted MCP server. It refuses to replace an
+account key unless you pass `--force`.
+
+## Saved results and free re-reads
+
+Every API command also writes its full JSON response to
+`~/.cache/scrapebadger/results/<api>-<command>-<UTC timestamp>.json` (honours
+`XDG_CACHE_HOME`; the newest 200 are kept) and prints one line to stderr:
+
+```
+saved: ~/.cache/scrapebadger/results/google-search-20261023T101500123456Z.json · credits: 20 · result_id: 6f1c...
+```
+
+stdout is unchanged. Disable with `scrapebadger --no-save ...` or `SCRAPEBADGER_SAVE=0`.
+
+Re-slice a saved result locally, for free:
+
+```bash
+scrapebadger view --summary                       # newest result: types, list lengths, byte sizes
+scrapebadger view --last google --max-items 5 --fields title,link
+scrapebadger view path/to/result.json --jq '.organic_results[].link'   # needs jq on PATH
+```
+
+`--fields` (dotted paths) and `--max-items` apply to the main item list (the
+top-level array, else the largest top-level list); truncation adds
+`"_truncated": {"path", "kept", "total"}`.
+
+Re-read a result from the server within ~15 minutes, free, sliced server-side:
+
+```bash
+scrapebadger results get <result_id> --max-items 3 --fields id,text
+```
+
+## Quotes, bug reports and feedback (all free)
+
+```bash
+scrapebadger quote /v1/google/search -p q="coffee" -p gl=us     # cost, validation, latency
+scrapebadger quote /v1/web/scrape --method POST --body '{"url": "https://example.com"}'
+scrapebadger report-bug "Empty results for a public profile" --request-id <X-Request-ID> --endpoint /v1/instagram/users/x
+scrapebadger feedback "Please add Pinterest" --details "..."
+```
+
+Error messages include the `request_id` to quote in a bug report, and the
+upgrade or claim link when you are out of credits.
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SCRAPEBADGER_API_KEY` | | API key (wins over `.env` and `~/.config/scrapebadger/config.json`) |
+| `SCRAPEBADGER_API_URL` | `https://scrapebadger.com` | API base URL, e.g. a local stack |
+| `SCRAPEBADGER_SITE_URL` | `https://scrapebadger.com` | Where `init` downloads the skill from |
+| `SCRAPEBADGER_MCP_URL` | `https://mcp.scrapebadger.com/mcp` | MCP server `init` registers |
+| `SCRAPEBADGER_SAVE` | `1` | `0` disables saving results |
+
+## Vinted mobile data (0.14.0+)
+
+```sh
+scrapebadger vinted mobile-operations
+scrapebadger vinted mobile sold-comparables --market fr --params '{"catalog_id":"1242","brand_id":"53","status_id":"2"}'
+scrapebadger vinted search "nike" --sizes 206 --materials 43
+```
+
+The catalog lists 76 public read operations with parameter types and examples.
+Each mobile read costs 1 credit; discovery is free. Sold comparables are a
+Vinted-selected sample, not a complete sales history or guaranteed final sale prices.
+
+### Vinted image search
+
+```bash
+scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
+scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53
+```
+
+Provide exactly one of `--image`, `--image-url` or `--image-base64`. JPEG, PNG and
+WebP up to 5 MiB are supported. Returns active listings in visual ranking order;
+10 credits per successful request. Filter with `--catalog-ids`, `--brand-ids`,
+`--status-ids`, `--color-ids`, `--size-ids`, `--material-ids` and price bounds.
+Resend the same image and `--time` from pagination when requesting `--page 2`.
+
+## Dedicated ecommerce APIs
+
+```bash
+scrapebadger etsy search "ceramic mug" --currency USD --country US
+scrapebadger aliexpress search "keyboard"
+scrapebadger target search "laptop" --zip-code 55403 --store-id 1375
+scrapebadger asos search "shoes" --market uk
+scrapebadger bestbuy search "laptop"
+```
+
+Run `scrapebadger <api> --help` to list product, review, store, availability and
+reference commands for that API. Each command supports `--help` for its exact
+parameters. Requests use your API key's existing permissions and credit balance.

{scrapebadger_cli-0.23.2 → scrapebadger_cli-0.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrapebadger-cli"
-version = "0.23.2"
+version = "0.24.0"
 description = "ScrapeBadger CLI — Twitter, Vinted, Google, and Web Scraping from the command line"
 requires-python = ">=3.10"
 license = {text = "MIT"}

scrapebadger_cli-0.24.0/src/scrapebadger_cli/client.py

@@ -0,0 +1,114 @@
+"""HTTP client for ScrapeBadger API."""
+
+import os
+from typing import Any
+
+import httpx
+import typer
+
+from scrapebadger_cli import results
+from scrapebadger_cli.config import get_api_key
+
+BASE_URL = os.environ.get("SCRAPEBADGER_API_URL", "https://scrapebadger.com")
+_client: httpx.Client | None = None
+
+# Links an error body may carry (402 / zero-credit 429 / trial errors).
+_ERROR_LINKS = ("claim_url", "upgrade_url", "free_credits_url", "pricing_url", "signup_url")
+
+
+def _new_client(headers: dict[str, str] | None = None) -> httpx.Client:
+    return httpx.Client(base_url=BASE_URL, headers=headers, timeout=300.0)
+
+
+def _get_client() -> httpx.Client:
+    global _client
+    if _client is None:
+        api_key = get_api_key()
+        if not api_key:
+            typer.echo(
+                "No API key found. Set SCRAPEBADGER_API_KEY or run: scrapebadger login"
+                " (or scrapebadger trial for a 50-credit key without an account)",
+                err=True,
+            )
+            raise typer.Exit(1)
+        _client = _new_client({"X-API-Key": api_key})
+    return _client
+
+
+def api_get(path: str, params: dict[str, Any] | None = None, *, save: bool = True) -> dict | list:
+    """Make a GET request to the ScrapeBadger API.
+
+    ``save=False`` for account/meta calls that are not results worth caching.
+    """
+    clean = {k: v for k, v in (params or {}).items() if v is not None}
+    resp = _get_client().get(path, params=clean or None)
+    return _handle_response(resp, path if save else None)
+
+
+def api_post(
+    path: str, json_body: dict[str, Any] | None = None, *, save: bool = True
+) -> dict | list:
+    """Make a POST request to the ScrapeBadger API."""
+    resp = _get_client().post(path, json=json_body)
+    return _handle_response(resp, path if save else None)
+
+
+def api_post_raw(path: str, json_body: dict[str, Any] | None = None) -> tuple[bytes, str]:
+    """POST and return ``(body_bytes, content_type)`` without JSON-decoding.
+
+    For `/v1/web/scrape` with `raw_content`, whose response is the scraped body
+    itself. Returns bytes, not text: the payload may be an image or a PDF and
+    decoding it would corrupt it.
+    """
+    resp = _get_client().post(path, json=json_body)
+    if resp.status_code >= 400:
+        _handle_response(resp)
+    return resp.content, resp.headers.get("content-type", "")
+
+
+def public_post(path: str, json_body: dict[str, Any]) -> tuple[int, dict]:
+    """POST to an unauthenticated ``/v1/public/*`` endpoint; ``(status, body)``.
+
+    Errors are returned, not raised: the trial and device flows branch on them.
+    """
+    with _new_client() as client:
+        resp = client.post(path, json=json_body)
+    try:
+        body = resp.json()
+    except ValueError:
+        body = {"error": "invalid_response", "detail": resp.text}
+    return resp.status_code, body if isinstance(body, dict) else {"data": body}
+
+
+def error_message(body: Any, fallback: str = "") -> str:
+    """One readable message from an error body, plus any links it carries."""
+    if not isinstance(body, dict):
+        return fallback
+    if isinstance(body.get("detail"), dict):  # HTTPException(detail={...})
+        body = {**body, **body["detail"]}
+    message = str(body.get("message") or body.get("detail") or body.get("error") or fallback)
+    for key in _ERROR_LINKS:
+        url = body.get(key)
+        if url and url not in message:
+            message += f"\n  {key}: {url}"
+    return message
+
+
+def _handle_response(resp: httpx.Response, save_path: str | None = None) -> dict | list:
+    """Handle API response, exit on errors; save successful results when asked."""
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+        except ValueError:
+            body = None
+        message = error_message(body, resp.text)
+        if request_id := resp.headers.get("x-request-id"):
+            message += f"\n  request_id: {request_id}"
+        typer.echo(f"Error ({resp.status_code}): {message}", err=True)
+        raise typer.Exit(1)
+    if resp.status_code == 204:
+        return {"status": "deleted"}
+    data = resp.json()
+    if save_path:
+        results.save(resp, data, save_path)
+    return data

scrapebadger_cli-0.24.0/src/scrapebadger_cli/commands/agent.py

@@ -0,0 +1,242 @@
+"""Agent helpers: view saved results, re-read results, quote, feedback."""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from scrapebadger_cli import results as saved
+from scrapebadger_cli.client import api_get, api_post
+from scrapebadger_cli.output import console, render
+from scrapebadger_cli.views import apply_view, summary
+
+results_app = typer.Typer(no_args_is_help=True)
+
+FMT = typer.Option("json", "--output", "-o", help="Output format: json, csv, table, markdown")
+JQ = typer.Option(None, "--jq", help="jq expression to run on the result")
+FIELDS = typer.Option(None, "--fields", help="Comma-separated (dotted) fields of each item to keep")
+MAX_ITEMS = typer.Option(None, "--max-items", help="Keep only the first N items of the main list")
+SUMMARY = typer.Option(False, "--summary", help="Structural outline instead of the data")
+
+
+def _print_json(data: Any) -> None:
+    sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False, default=str) + "\n")
+
+
+def _run_jq(expr: str, data: Any) -> None:
+    if not shutil.which("jq"):
+        typer.echo(
+            "Error: --jq needs the jq binary on PATH (brew install jq / apt install jq).", err=True
+        )
+        raise typer.Exit(1)
+    proc = subprocess.run(
+        ["jq", expr], input=json.dumps(data), capture_output=True, text=True, check=False
+    )
+    sys.stdout.write(proc.stdout)
+    if proc.returncode:
+        typer.echo(proc.stderr.rstrip(), err=True)
+        raise typer.Exit(proc.returncode)
+
+
+def _known_apis() -> list[str]:
+    from scrapebadger_cli.main import app
+
+    return [g.name for g in app.registered_groups if g.name]
+
+
+def _latest(api: str | None) -> Path:
+    files = saved.saved_files()
+    if api:
+        # "google" must not match "google-play-..." files.
+        longer = [a for a in _known_apis() if a.startswith(f"{api}-")]
+        files = [
+            f
+            for f in files
+            if f.name.startswith(f"{api}-") and not any(f.name.startswith(f"{a}-") for a in longer)
+        ]
+    if not files:
+        where = f" for {api}" if api else ""
+        typer.echo(f"Error: no saved results{where} in {saved.results_dir()}", err=True)
+        raise typer.Exit(1)
+    return files[0]
+
+
+def view(
+    target: str | None = typer.Argument(
+        None, help="Saved result file (default: the newest). With --last: an API name filter"
+    ),
+    last: bool = typer.Option(
+        False, "--last", help="Use the newest saved result (of TARGET's API)"
+    ),
+    jq: str | None = JQ,
+    fields: str | None = FIELDS,
+    max_items: int | None = MAX_ITEMS,
+    show_summary: bool = SUMMARY,
+    fmt: str = FMT,
+) -> None:
+    """Re-slice a saved result locally (free, no API call)."""
+    if last or target is None:
+        path = _latest(target if last else None)
+    else:
+        path = Path(target).expanduser()
+        if not path.exists() and (saved.results_dir() / target).exists():
+            path = saved.results_dir() / target
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError) as exc:
+        typer.echo(f"Error: cannot read {path}: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"viewing: {path}", err=True)
+
+    data = apply_view(data, fields, max_items)
+    if show_summary:
+        data = summary(data)
+    if jq:
+        _run_jq(jq, data)
+    elif fmt == "json":
+        _print_json(data)
+    else:
+        render(data, fmt)
+
+
+@results_app.command("get")
+def results_get(
+    result_id: str = typer.Argument(..., help="X-Result-ID of an earlier call (kept ~15 min)"),
+    jq: str | None = JQ,
+    fields: str | None = FIELDS,
+    max_items: int | None = MAX_ITEMS,
+    show_summary: bool = SUMMARY,
+    fmt: str = FMT,
+) -> None:
+    """Re-read an earlier result from the server, free, optionally sliced server-side."""
+    data = api_get(
+        f"/v1/results/{result_id}",
+        {
+            "jq": jq,
+            "fields": fields,
+            "max_items": max_items,
+            "summary": "true" if show_summary else None,
+        },
+        save=False,
+    )
+    if fmt == "json":
+        _print_json(data)
+    else:
+        render(data, fmt)
+
+
+def _parse_params(pairs: list[str]) -> dict[str, str]:
+    params = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise typer.BadParameter(f"expected key=value, got {pair!r}", param_hint="--param")
+        params[key] = value
+    return params
+
+
+def quote(
+    path: str = typer.Argument(..., help="Endpoint path, e.g. /v1/google/search"),
+    param: list[str] = typer.Option([], "--param", "-p", help="Query param key=value (repeatable)"),
+    body: str | None = typer.Option(None, "--body", help="JSON request body (POST endpoints)"),
+    method: str = typer.Option("GET", "--method", "-X", help="HTTP method of the endpoint"),
+    fmt: str = typer.Option("pretty", "--output", "-o", help="pretty or json"),
+) -> None:
+    """Price and validate a call before making it (free, never billed)."""
+    try:
+        json_body = json.loads(body) if body else None
+    except ValueError as exc:
+        raise typer.BadParameter(f"not valid JSON: {exc}", param_hint="--body") from exc
+    data = api_post(
+        "/v1/quote",
+        {"method": method.upper(), "path": path, "params": _parse_params(param), "body": json_body},
+        save=False,
+    )
+    if fmt == "json" or not isinstance(data, dict):
+        _print_json(data)
+        return
+
+    out = [f"{data.get('method', method)} {data.get('path', path)}"]
+    valid = data.get("valid")
+    out.append(
+        "params:  "
+        + {True: "valid", False: "INVALID", None: "not validated"}.get(valid, str(valid))
+    )
+    for err in data.get("errors") or []:
+        out.append(f"  - {err.get('field')}: {err.get('message')}")
+    credits = data.get("credits") or {}
+    out.append(f"billing: {data.get('billing')}")
+    out.append(
+        f"credits: {credits.get('min')}–{credits.get('max') if credits.get('max') is not None else '∞'}"
+        f" (base {credits.get('base')}, per item {credits.get('per_item')})"
+    )
+    if usd := data.get("usd"):
+        out.append(
+            f"usd:     max ${usd.get('max_per_call_list')}/call · "
+            f"${usd.get('per_1k_calls_list')}/1k (list) · ${usd.get('per_1k_calls_best')}/1k (best plan)"
+        )
+    if lat := data.get("latency"):
+        out.append(
+            f"latency: p50 {lat.get('p50_ms')} ms · p95 {lat.get('p95_ms')} ms · "
+            f"p99 {lat.get('p99_ms')} ms ({lat.get('samples')} calls, {lat.get('window_days')} d)"
+        )
+    else:
+        out.append("latency: no samples yet")
+    out += [f"note:    {n}" for n in data.get("notes") or []]
+    typer.echo("\n".join(out))
+
+
+def _send_feedback(
+    kind: str,
+    summary_text: str,
+    details: str | None,
+    request_id: str | None,
+    endpoint: str | None,
+    contact: str | None,
+) -> None:
+    body = {
+        "type": kind,
+        "summary": summary_text,
+        "details": details,
+        "request_id": request_id,
+        "endpoint": endpoint,
+        "contact": contact,
+    }
+    data = api_post("/v1/feedback", {k: v for k, v in body.items() if v}, save=False)
+    data = data if isinstance(data, dict) else {}
+    console.print(f"[green]Received.[/green] [dim]id: {data.get('id', '?')}[/dim]")
+    if message := data.get("message"):
+        typer.echo(message)
+
+
+SUMMARY_ARG = typer.Argument(..., help="One-line summary (max 200 chars)")
+DETAILS = typer.Option(None, "--details", "-d", help="Longer description (max 5000 chars)")
+REQUEST_ID = typer.Option(None, "--request-id", help="X-Request-ID of the call concerned")
+ENDPOINT = typer.Option(None, "--endpoint", help="Endpoint concerned, e.g. /v1/google/search")
+CONTACT = typer.Option(None, "--contact", help="How to reach you (optional)")
+
+
+def report_bug(
+    summary_text: str = SUMMARY_ARG,
+    details: str | None = DETAILS,
+    request_id: str | None = REQUEST_ID,
+    endpoint: str | None = ENDPOINT,
+    contact: str | None = CONTACT,
+) -> None:
+    """Report a bug (wrong data, an error, a block) to the ScrapeBadger team. Free."""
+    _send_feedback("bug", summary_text, details, request_id, endpoint, contact)
+
+
+def feedback(
+    summary_text: str = SUMMARY_ARG,
+    details: str | None = DETAILS,
+    request_id: str | None = REQUEST_ID,
+    endpoint: str | None = ENDPOINT,
+    contact: str | None = CONTACT,
+) -> None:
+    """Send feedback or a feature request to the ScrapeBadger team. Free."""
+    _send_feedback("feedback", summary_text, details, request_id, endpoint, contact)