jabb-cli 0.1.0__py3-none-any.whl

jabb_cli/cli.py

@@ -0,0 +1,77 @@
+import sys
+import json as jsonlib
+import click
+from jabb_cli.client import ApiClient, AuthError, RateLimitError, ApiError
+from jabb_cli.output import render_table
+
+
+@click.group()
+@click.option("--json", "json_mode", is_flag=True, help="Print raw JSON envelope instead of a table. Use this when piping output to another program or an agent.")
+@click.option("--detailed", is_flag=True, help="Request response_format=detailed (more fields per row). Costs more tokens — use only when concise fields are insufficient.")
+@click.pass_context
+def main(ctx, json_mode, detailed):
+    """jabb — CLI for JABB Public API v1 (locations, scores, reviews, pnif, sentiment).
+
+    Auth: set JABB_API_KEY to a key minted by your JABB admin.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["json"] = json_mode
+    ctx.obj["detailed"] = detailed
+
+
+def list_resource(ctx, path):
+    params = {"limit": ctx.obj.get("limit", 20)}
+    if ctx.obj.get("cursor"):
+        params["cursor"] = ctx.obj["cursor"]
+    params["response_format"] = "detailed" if ctx.obj["detailed"] else "concise"
+    try:
+        client = ApiClient()
+        result = client.get(path, params=params)
+    except RateLimitError as e:
+        click.echo(jsonlib.dumps({"error": {"code": e.code, "message": e.message, "hint": e.hint}}) if ctx.obj["json"] else f"Rate limited: {e.message}. Retry after {e.retry_after}s. {e.hint}", err=True)
+        sys.exit(3)
+    except AuthError as e:
+        click.echo(jsonlib.dumps({"error": {"code": e.code, "message": e.message, "hint": e.hint}}) if ctx.obj["json"] else f"Auth error: {e.message}. {e.hint}", err=True)
+        sys.exit(2)
+    except ApiError as e:
+        click.echo(jsonlib.dumps({"error": {"code": e.code, "message": e.message, "hint": e.hint}}) if ctx.obj["json"] else f"API error: {e.message}. {e.hint}", err=True)
+        sys.exit(1)
+
+    if ctx.obj["json"]:
+        click.echo(jsonlib.dumps(result))
+    else:
+        data = result["data"]
+        rows = data if isinstance(data, list) else [data]
+        click.echo(render_table(rows))
+        if result.get("next_cursor"):
+            click.echo(f"\n(more results: --cursor {result['next_cursor']})", err=True)
+
+
+RESOURCES = {
+    "locations": ("/api/public/v1/locations", "Business locations. Call when the agent needs a store/venue list or IDs to cross-reference other resources."),
+    "scores": ("/api/public/v1/cx-scores", "CX scores per entity. Call when the agent needs quantitative quality metrics, not raw review text."),
+    "reviews": ("/api/public/v1/quick-jabbs", "Quick JABB evaluations (reviews). Call when the agent needs individual review content/ratings."),
+    "pnif": ("/api/public/v1/pnif", "PNIF analysis. Call when the agent needs the Price/Need/Impact/Frequency breakdown, not raw scores."),
+    "sentiment": ("/api/public/v1/sentiment", "Sentiment mapping. Call when the agent needs sentiment labels/trends, not raw scores or reviews."),
+}
+
+
+def _make_group(name, path, help_text):
+    @click.group(name=name, help=help_text)
+    def group():
+        pass
+
+    @group.command(name="list", help=f"List {name} (paginated). {help_text}")
+    @click.option("--cursor", default=None, help="Opaque pagination cursor from a previous response's next_cursor.")
+    @click.option("--limit", default=20, type=click.IntRange(1, 100), help="Rows per page (1-100, default 20). Keep low for agent contexts.")
+    @click.pass_context
+    def list_cmd(ctx, cursor, limit):
+        ctx.obj["cursor"] = cursor
+        ctx.obj["limit"] = limit
+        list_resource(ctx, path)
+
+    return group
+
+
+for _name, (_path, _help) in RESOURCES.items():
+    main.add_command(_make_group(_name, _path, _help))

jabb_cli/client.py

@@ -0,0 +1,56 @@
+import os
+import requests
+
+DEFAULT_BASE_URL = "https://api.jabb.cx"
+
+
+class ApiError(Exception):
+    def __init__(self, code, message, hint):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+
+
+class AuthError(ApiError):
+    pass
+
+
+class RateLimitError(ApiError):
+    def __init__(self, code, message, hint, retry_after):
+        super().__init__(code, message, hint)
+        self.retry_after = retry_after
+
+
+class ApiClient:
+    def __init__(self):
+        key = os.environ.get("JABB_API_KEY")
+        if not key:
+            raise AuthError(
+                "missing_api_key",
+                "JABB_API_KEY is not set.",
+                "export JABB_API_KEY=jabb_live_... (mint one via your JABB admin).",
+            )
+        self.key = key
+        self.base_url = os.environ.get("JABB_API_BASE_URL", DEFAULT_BASE_URL)
+
+    def get(self, path, params=None):
+        resp = requests.request(
+            "GET",
+            url=f"{self.base_url}{path}",
+            headers={"Authorization": f"Bearer {self.key}"},
+            params=params or {},
+            timeout=15,
+        )
+        if resp.status_code == 200:
+            return resp.json()
+        try:
+            err = resp.json().get("error", {})
+        except (ValueError, KeyError):
+            raise ApiError("unknown", f"HTTP {resp.status_code}", "Server returned non-JSON response.")
+        code, message, hint = err.get("code"), err.get("message"), err.get("hint")
+        if resp.status_code == 429:
+            raise RateLimitError(code, message, hint, int(resp.headers.get("Retry-After", 0)))
+        if resp.status_code in (401, 403):
+            raise AuthError(code, message, hint)
+        raise ApiError(code, message, hint)

jabb_cli/output.py

@@ -0,0 +1,18 @@
+MAX_CELL = 40
+
+
+def _cell(v):
+    s = str(v)
+    return s if len(s) <= MAX_CELL else s[: MAX_CELL - 3] + "..."
+
+
+def render_table(rows):
+    if not rows:
+        return "(no results)"
+    cols = list(rows[0].keys())
+    cells = [[_cell(r.get(c, "")) for c in cols] for r in rows]
+    widths = [max(len(cols[i]), *(len(row[i]) for row in cells)) for i in range(len(cols))]
+    header = "  ".join(c.ljust(w) for c, w in zip(cols, widths))
+    sep = "  ".join("-" * w for w in widths)
+    body = "\n".join("  ".join(cell.ljust(w) for cell, w in zip(row, widths)) for row in cells)
+    return f"{header}\n{sep}\n{body}"

jabb_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: jabb-cli
+Version: 0.1.0
+Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"

jabb_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jabb_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jabb_cli/cli.py,sha256=L0EPSOAiLg0aAY0jrtWeZ6BJl8JDBs9GiJWxXwzif7Y,3671
+jabb_cli/client.py,sha256=YIa3zoKpwjVvVlRnmD3aY2n_XSKCxz9JveA2WokkABE,1769
+jabb_cli/output.py,sha256=VihSnEeUf-N6OsAQOFp83pg0Whz2h27VE8wB1qLiwJ8,616
+jabb_cli-0.1.0.dist-info/METADATA,sha256=BtVBjCso0_p9jt0nhPjeDvL15YIQa5ZzBaTa-fOwNcE,283
+jabb_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+jabb_cli-0.1.0.dist-info/entry_points.txt,sha256=RqoERoKtCqbnEbdA3UPO6NDr_BTrM2TX16gYrn3Cb3o,43
+jabb_cli-0.1.0.dist-info/top_level.txt,sha256=JbTNlL8xVB3ySz9psM3tDCNQQ1OI0JSpKZ_ZPzkGevM,9
+jabb_cli-0.1.0.dist-info/RECORD,,

jabb_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jabb_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jabb = jabb_cli.cli:main

jabb_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jabb_cli