Metadata-Version: 2.4
Name: jabb-cli
Version: 0.6.0
Summary: CLI and MCP server for JABB Public API v1 — 21 endpoints, shell completions, Postman collection, browser docs.
Author: JABB
License-Expression: MIT
Project-URL: Homepage, https://github.com/JAB-Bers/jabb-cli
Project-URL: Repository, https://github.com/JAB-Bers/jabb-cli
Project-URL: Issues, https://github.com/JAB-Bers/jabb-cli/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: mcp<2,>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# jabb-cli

CLI and MCP server for [JABB Public API v1](https://api.jabb.cx/api/public/v1/openapi.yaml) — all 20 endpoints including read intelligence and write operations (owner replies, webhooks).

## Install

```bash
pip install jabb-cli
```

## Quickstart

```bash
export JABB_API_KEY=jabb_live_...
jabb whoami          # verify key + quota
jabb locations list
jabb scores list --detailed
```

Time to first result: under 5 minutes from a minted key.

## Resources (read)

```
jabb [--json] [--detailed] [--quiet] <resource> list [options]
```

| Resource | Endpoint | Filters |
|----------|----------|---------|
| `locations` | `/locations` | `--cursor`, `--limit` |
| `scores` | `/cx-scores` | `--cursor`, `--limit` |
| `reviews` | `/quick-jabbs` | `--cursor`, `--limit`, `--location` |
| `pnif` | `/pnif` | `--cursor`, `--limit`, `--days` |
| `sentiment` | `/sentiment` | `--cursor`, `--limit`, `--days` |
| `alerts` | `/alerts` | `--days`, `--location` |
| `phases` | `/phases` | `--days` |
| `demographics` | `/demographics` | `--days`, `--location` |
| `experience` | `/experience-metrics` | `--days`, `--location` |
| `verbatims` | `/verbatims` | `--days`, `--location` |
| `emotions` | `/emotions` | `--days`, `--location` |
| `summary` | `/summary` | `--days` |
| `reports` | `/reports` | `--cursor`, `--limit` |
| `webhooks` | `/webhooks` | — |

Global flags:

- `--json` — raw API envelope (`{"data": [...], "next_cursor": ...}`). Use for scripting/agents.
- `--detailed` — more fields per row.
- `--quiet` / `-q` — suppress pagination hints on stderr.
- `-n` / `--limit` — rows per page, 1–100, default 20.
- `--cursor` — opaque cursor from previous `next_cursor` to page forward.

## Write commands

Require `write:reply` or `write:webhooks` scope on the API key (not included in default grant — request explicitly at mint).

```bash
# Single evaluation detail
jabb reviews get <jabb_id>

# Owner replies
jabb reviews reply <jabb_id> "Thank you for your feedback!"
jabb reviews ai-reply <jabb_id> [--tone professional|friendly|apologetic] [--language en|fr|ar]

# Report download
jabb reports download <report_id> [--out report.pdf]

# Webhooks
jabb webhooks create <url> --events review.created --events score.updated
jabb webhooks list
jabb webhooks delete <webhook_id>
jabb webhooks test <webhook_id>
```

## Auth

```bash
export JABB_API_KEY=jabb_live_...          # production
export JABB_API_BASE_URL=http://127.0.0.1:5500  # local dev override
```

Key is org-scoped and per-scope. Default keys carry all `read:*` scopes. Write scopes (`write:reply`, `write:webhooks`) must be requested explicitly when minting.

## Verify key

```bash
jabb whoami
# Key:    jabb_live_ABCDEFGHIJKLMNOP...
# Status: valid
# Quota:  58/60 requests remaining
```

## Open API docs

```bash
jabb docs            # open interactive Swagger UI in browser
jabb docs --openapi  # open raw OpenAPI spec (YAML)
```

## Shell completions

Tab-complete commands and options in bash, zsh, or fish:

```bash
# bash — add to ~/.bashrc
eval "$(jabb completions bash)"

# zsh — add to ~/.zshrc
eval "$(jabb completions zsh)"

# fish — add to ~/.config/fish/config.fish
jabb completions fish | source
```

## Postman collection

Import `postman/jabb-api-v1.json` into Postman. Set two collection variables:

| Variable | Value |
|----------|-------|
| `base_url` | `https://api.jabb.cx` |
| `JABB_API_KEY` | your API key |

All 27 endpoints across 5 folders (Read, Replies, Webhooks, Key Management, Utilities). Auth is pre-configured as Bearer token using `{{JABB_API_KEY}}`.

To regenerate after spec changes:
```bash
python scripts/gen_postman.py
```

## 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 |

## MCP server

`jabb mcp` starts a **stdio MCP server** exposing all endpoints as typed agent tools. Any MCP host (Claude Code, Claude Desktop, Cursor…) can query your JABB data with nothing but an API key.

### Tools

| Tool | Use when |
|------|----------|
| `jabb_list_locations` | Asking about branches/stores or need location IDs |
| `jabb_get_cx_scores` | Need quantitative CX metrics / composite score |
| `jabb_list_quick_jabbs` | Need individual evaluation content or ratings |
| `jabb_get_pnif` | Price/Need/Impact/Frequency breakdown |
| `jabb_get_sentiment` | Sentiment labels or topic-level trends |
| `jabb_get_alerts` | Urgency alerts — score drops, spikes, anomalies |
| `jabb_get_phases` | Journey stage (phase) performance breakdown |
| `jabb_get_demographics` | Reviewer demographic profile (age, gender, city) |
| `jabb_get_experience_metrics` | NPS / CSAT / CES scores |
| `jabb_get_verbatims` | Actual customer verbatim feedback text |
| `jabb_get_emotions` | Emotion distribution (Satisfaction, Frustration…) |
| `jabb_get_summary` | AI-generated executive narrative summary |
| `jabb_list_reports` | List generated report metadata |
| `jabb_get_quick_jabb` | Full detail for a single evaluation (responses, stage ratings, AI analysis, owner reply) |
| `jabb_post_reply` | Post / update an owner reply on an evaluation |
| `jabb_ai_assist_reply` | Generate AI draft reply (does not save — call `jabb_post_reply` to publish) |
| `jabb_list_webhooks` | List registered webhook endpoints |
| `jabb_create_webhook` | Register a new webhook endpoint |
| `jabb_delete_webhook` | Deactivate a webhook registration |
| `jabb_test_webhook` | Send a test.ping to verify a webhook endpoint is reachable |

Responses capped at ~25 KB. Truncated payloads include `"truncated": true` and preserve `next_cursor` for paging. API errors surface as tool errors with the API's `code` + `hint`. 429s include `Retry-After` seconds.

### Connect (Claude Code)

```bash
claude mcp add jabb -- jabb mcp
```

Or add to your repo's `.mcp.json`:

```json
{
  "mcpServers": {
    "jabb": {
      "command": "jabb",
      "args": ["mcp"],
      "env": { "JABB_API_KEY": "${JABB_API_KEY}" }
    }
  }
}
```

### Connect (Claude Desktop)

```json
{
  "mcpServers": {
    "jabb": {
      "command": "jabb",
      "args": ["mcp"],
      "env": { "JABB_API_KEY": "jabb_live_..." }
    }
  }
}
```

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JABB_API_KEY` | Yes | — | API key minted by your JABB admin |
| `JABB_API_BASE_URL` | No | `https://api.jabb.cx` | Override for local dev |

## API reference

Full spec: `https://api.jabb.cx/api/public/v1/openapi.yaml`  
LLM-friendly: `https://api.jabb.cx/.well-known/llms.txt` · `llms-full.txt`
