jabb-cli 0.1.0__tar.gz

jabb_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,69 @@
+# jabb
+
+CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```bash
+export JABB_API_KEY=jabb_test_...
+jabb locations list
+```
+
+Time to first result: under 5 minutes from a minted key.
+
+## Usage
+
+```
+jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
+```
+
+Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.
+
+- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
+- `--detailed` — request more fields per row (costs more tokens/bandwidth).
+- `--cursor` — pass the previous response's `next_cursor` to page forward.
+- `--limit` — rows per page, 1-100, default 20.
+
+Examples:
+
+```bash
+jabb scores list --detailed
+jabb reviews list --limit 5
+jabb pnif list --json
+jabb locations list --cursor eyJwIjo... --limit 50
+```
+
+## Auth
+
+Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.
+
+For local development against a jabb-server instance running on your machine:
+
+```bash
+export JABB_API_BASE_URL=http://127.0.0.1:5500
+```
+
+Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic API error |
+| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
+| 3 | Rate limited (message includes retry-after seconds) |
+
+## For Claude Code users
+
+See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data.
+
+## Scope
+
+Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.

jabb_cli-0.1.0/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-0.1.0/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-0.1.0/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/jabb_cli.egg-info/PKG-INFO

@@ -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/jabb_cli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+jabb_cli/__init__.py
+jabb_cli/cli.py
+jabb_cli/client.py
+jabb_cli/output.py
+jabb_cli.egg-info/PKG-INFO
+jabb_cli.egg-info/SOURCES.txt
+jabb_cli.egg-info/dependency_links.txt
+jabb_cli.egg-info/entry_points.txt
+jabb_cli.egg-info/requires.txt
+jabb_cli.egg-info/top_level.txt
+tests/test_cli_errors.py
+tests/test_cli_resources.py
+tests/test_client.py
+tests/test_output.py

jabb_cli-0.1.0/jabb_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jabb_cli-0.1.0/jabb_cli.egg-info/entry_points.txt

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

jabb_cli-0.1.0/jabb_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+click>=8.1
+requests>=2.31
+
+[dev]
+pytest>=8.0

jabb_cli-0.1.0/jabb_cli.egg-info/top_level.txt

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

jabb_cli-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "jabb-cli"
+version = "0.1.0"
+description = "CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment."
+requires-python = ">=3.11"
+dependencies = ["click>=8.1", "requests>=2.31"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+jabb = "jabb_cli.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["jabb_cli*"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

jabb_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jabb_cli-0.1.0/tests/test_cli_errors.py

@@ -0,0 +1,24 @@
+from unittest.mock import patch
+from click.testing import CliRunner
+from jabb_cli.cli import main
+from jabb_cli.client import AuthError, RateLimitError
+
+def test_missing_key_exit_code_2(monkeypatch):
+    monkeypatch.delenv("JABB_API_KEY", raising=False)
+    result = CliRunner().invoke(main, ["locations", "list"])
+    assert result.exit_code == 2
+    assert "JABB_API_KEY" in result.output
+
+def test_auth_error_exit_code_2(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.cli.ApiClient.get", side_effect=AuthError("invalid_api_key", "bad", "mint a new one")):
+        result = CliRunner().invoke(main, ["locations", "list"])
+    assert result.exit_code == 2
+    assert "mint a new one" in result.output
+
+def test_rate_limit_exit_code_3(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.cli.ApiClient.get", side_effect=RateLimitError("rate_limited", "slow down", "wait", 7)):
+        result = CliRunner().invoke(main, ["locations", "list"])
+    assert result.exit_code == 3
+    assert "7" in result.output

jabb_cli-0.1.0/tests/test_cli_resources.py

@@ -0,0 +1,45 @@
+import pytest
+from unittest.mock import patch
+from click.testing import CliRunner
+from jabb_cli.cli import main
+
+CASES = [
+    (["locations", "list"], "/api/public/v1/locations"),
+    (["scores", "list"], "/api/public/v1/cx-scores"),
+    (["reviews", "list"], "/api/public/v1/quick-jabbs"),
+    (["pnif", "list"], "/api/public/v1/pnif"),
+    (["sentiment", "list"], "/api/public/v1/sentiment"),
+]
+
+@pytest.mark.parametrize("args,expected_path", CASES)
+def test_resource_hits_expected_endpoint(monkeypatch, args, expected_path):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.cli.ApiClient.get", return_value={"data": [], "next_cursor": None}) as m:
+        result = CliRunner().invoke(main, args)
+    assert result.exit_code == 0
+    assert m.call_args.args[0] == expected_path
+
+def test_cursor_and_limit_flags_forwarded(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.cli.ApiClient.get", return_value={"data": [], "next_cursor": None}) as m:
+        CliRunner().invoke(main, ["locations", "list", "--cursor", "abc", "--limit", "5"])
+    assert m.call_args.kwargs["params"]["cursor"] == "abc"
+    assert m.call_args.kwargs["params"]["limit"] == 5
+
+def test_dict_shaped_data_renders_as_single_row(monkeypatch):
+    """pnif/sentiment return an aggregate object, not a list of rows — must not crash."""
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    dict_data = {"topics": [], "counts": {"total_positive": 0}}
+    with patch("jabb_cli.cli.ApiClient.get", return_value={"data": dict_data, "next_cursor": None}):
+        result = CliRunner().invoke(main, ["sentiment", "list"])
+    assert result.exit_code == 0
+    assert "topics" in result.output
+    assert "counts" in result.output
+
+def test_dict_shaped_data_json_mode_unaffected(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    dict_data = {"topics": []}
+    with patch("jabb_cli.cli.ApiClient.get", return_value={"data": dict_data, "next_cursor": None}):
+        result = CliRunner().invoke(main, ["--json", "sentiment", "list"])
+    assert result.exit_code == 0
+    assert result.output.strip() == '{"data": {"topics": []}, "next_cursor": null}'

jabb_cli-0.1.0/tests/test_client.py

@@ -0,0 +1,48 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from jabb_cli.client import ApiClient, AuthError, RateLimitError, ApiError
+
+def _resp(status, body, headers=None):
+    m = MagicMock()
+    m.status_code = status
+    m.json.return_value = body
+    m.headers = headers or {}
+    return m
+
+def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv("JABB_API_KEY", raising=False)
+    with pytest.raises(AuthError):
+        ApiClient()
+
+def test_get_success(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    client = ApiClient()
+    with patch("jabb_cli.client.requests.request", return_value=_resp(200, {"data": [{"id": "1"}], "next_cursor": None})) as m:
+        result = client.get("/api/public/v1/locations", params={"limit": 20})
+    assert result["data"] == [{"id": "1"}]
+    called_headers = m.call_args.kwargs["headers"]
+    assert called_headers["Authorization"] == "Bearer jabb_test_x"
+
+def test_401_raises_auth_error(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    client = ApiClient()
+    body = {"error": {"code": "invalid_api_key", "message": "bad key", "hint": "mint a new one"}}
+    with patch("jabb_cli.client.requests.request", return_value=_resp(401, body)):
+        with pytest.raises(AuthError) as exc:
+            client.get("/api/public/v1/locations")
+    assert exc.value.hint == "mint a new one"
+
+def test_429_raises_rate_limit_with_retry_after(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    client = ApiClient()
+    body = {"error": {"code": "rate_limited", "message": "slow down", "hint": "retry later"}}
+    with patch("jabb_cli.client.requests.request", return_value=_resp(429, body, {"Retry-After": "12"})):
+        with pytest.raises(RateLimitError) as exc:
+            client.get("/api/public/v1/locations")
+    assert exc.value.retry_after == 12
+
+def test_base_url_override(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    monkeypatch.setenv("JABB_API_BASE_URL", "http://127.0.0.1:5500")
+    client = ApiClient()
+    assert client.base_url == "http://127.0.0.1:5500"

jabb_cli-0.1.0/tests/test_output.py

@@ -0,0 +1,14 @@
+from jabb_cli.output import render_table
+
+def test_render_table_empty():
+    assert render_table([]) == "(no results)"
+
+def test_render_table_columns_from_first_row():
+    out = render_table([{"id": "1", "name": "Cafe X"}, {"id": "2", "name": "Cafe Y"}])
+    lines = out.splitlines()
+    assert lines[0].split() == ["id", "name"]
+    assert "Cafe X" in out and "Cafe Y" in out
+
+def test_render_table_truncates_long_values():
+    out = render_table([{"id": "1", "note": "x" * 80}])
+    assert "..." in out