withfeedback 0.1.0__py3-none-any.whl

withfeedback-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: withfeedback
+Version: 0.1.0
+Summary: Command-line client for withfeedback.com — testimonials, feedback moderation, imports, widgets, and NPS
+Project-URL: Homepage, https://withfeedback.com
+Project-URL: Documentation, https://withfeedback.com/api/docs/
+License: MIT
+Keywords: cli,feedback,testimonials,withfeedback
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=24
+Description-Content-Type: text/markdown
+
+# withfeedback CLI
+
+Command-line client for [withfeedback.com](https://withfeedback.com):
+testimonials, feedback moderation, CSV imports, surveys, NPS, widgets, and
+quota usage — from your terminal or CI.
+
+## Install
+
+```bash
+pip install withfeedback
+# or run without installing:
+uvx withfeedback --help
+```
+
+The console command is `withfeedback`.
+
+## Quick start with a personal access token (PAT)
+
+Good for CI and quick scripting:
+
+1. Log in at your withfeedback.com instance and open **Account → API Tokens**
+   (`/accounts/tokens/`).
+2. Create a token with the scopes you need (see the table below).
+3. Either export it per-shell:
+
+   ```bash
+   export WITHFEEDBACK_TOKEN=spd_abc123...
+   withfeedback testimonials list --team <TEAM_ID> --project <PROJECT_ID>
+   ```
+
+   or persist it in the OS keychain:
+
+   ```bash
+   withfeedback login --token spd_abc123...
+   ```
+
+API access requires a plan that includes the API/CLI/MCP feature (Pro and
+above).
+
+## Login via OAuth2 device flow (interactive)
+
+```bash
+withfeedback login
+```
+
+No flags needed against withfeedback.com — the CLI defaults to the official
+public client id `7yQMsnY2Is2f5tCuwwgItoQu3fRkEX2wnzIRj0Vh` (public by
+design — device-flow clients carry no secret). For a self-hosted instance
+pass your own client:
+
+```bash
+withfeedback login --client-id <CLIENT_ID>       # or WITHFEEDBACK_CLIENT_ID
+```
+
+What happens:
+
+1. The CLI calls `POST /o/device-authorization/` and prints a verification
+   URL plus a short code (it also tries to open your browser).
+2. You open the URL, enter the code, and approve the requested scopes.
+3. The CLI polls `POST /o/token/` until you approve, then stores the access
+   and refresh tokens in the **OS keychain** via `keyring` (macOS Keychain,
+   Windows Credential Locker, Secret Service/KWallet on Linux) — never in a
+   plaintext file.
+
+When an access token expires, the CLI transparently refreshes it. Refresh
+tokens rotate on every use; the rotated token replaces the stored one.
+(Stored PATs are never "refreshed" — if a PAT is rejected, the CLI tells you
+to create a new one and run `withfeedback login --token` again.)
+
+```bash
+withfeedback logout   # remove stored tokens from the keychain
+```
+
+Token resolution precedence for every command:
+`--token` flag > `WITHFEEDBACK_TOKEN` env var > OS keychain.
+
+## Commands
+
+```bash
+withfeedback login [--client-id <ID> | --token <PAT>]
+withfeedback logout
+
+withfeedback testimonials list    --team <ID> --project <ID> [--status pending|approved|rejected|spam] [--rating N] [--q text] [--json]
+withfeedback testimonials approve <SUBMISSION_ID> --team <ID> [--json]
+withfeedback testimonials reject  <SUBMISSION_ID> --team <ID> [--json]
+withfeedback testimonials create  --team <ID> --project <ID> --text "..." [--rating N] [--name ..] [--email ..] [--title ..] [--company ..] [--consent] [--tag t]... [--json]
+
+withfeedback import csv FILE --team <ID> --project <ID> --text-col COL [--rating-col COL] [--name-col COL] [--email-col COL] [--consent] [--json]
+
+withfeedback surveys list  --team <ID> --project <ID> [--json]
+withfeedback nps summary   --team <ID> --project <ID> [--json]
+withfeedback widgets list  --team <ID> --project <ID> [--json]
+withfeedback usage         --team <ID> [--json]
+```
+
+Human output is plain text tables. Pass `--json` for machine-readable output
+(raw API responses) — errors still go to stderr.
+
+### CSV import
+
+`withfeedback import csv` validates the file locally (header columns, row
+count), builds the column mapping from your `--*-col` options, and uploads
+the file to the server's multipart import endpoint. Rows are processed
+asynchronously and land as **pending** submissions; the command prints the
+batch id and a status URL to poll.
+
+```bash
+withfeedback import csv reviews.csv \
+  --team <TEAM_ID> --project <PROJECT_ID> \
+  --text-col "Testimonial" --rating-col "Stars" \
+  --name-col "Author" --email-col "Email" --consent
+```
+
+Pass `--consent` only when display consent was actually collected for these
+rows.
+
+## Required scopes per command
+
+| Command | Required scope |
+|---|---|
+| `testimonials list` | `read:feedback` (or `read:testimonials`) |
+| `testimonials approve` / `reject` | `moderate:submissions` (`write:*` cannot moderate) |
+| `testimonials create` | `write:testimonials` (or `write:feedback`) |
+| `import csv` | `write:feedback` |
+| `surveys list`, `nps summary` | `read:surveys` |
+| `widgets list` | `read:widgets` |
+| `usage` | `read:feedback` |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General / unknown error |
+| 2 | Usage / config error (bad flags, unreadable CSV, missing column) |
+| 3 | Auth error (not logged in, invalid or expired token) |
+| 4 | Forbidden or payment required (missing scope/role, plan without API access, quota exceeded, billing blocked) |
+| 5 | Not found (unknown team/project/object or no access) |
+| 6 | Validation error or invalid state transition |
+| 7 | Network error (server unreachable) |
+
+On API errors the API's error detail is printed to stderr.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WITHFEEDBACK_API_URL` | `https://withfeedback.com` | API base URL (self-hosted/staging override) |
+| `WITHFEEDBACK_TOKEN` | — | PAT (beats the keychain, loses to `--token`) |
+| `WITHFEEDBACK_CLIENT_ID` | official public client id | Client id for `login` (override for self-hosted) |
+| `WITHFEEDBACK_SCOPES` | all CLI scopes | Scopes requested during device-flow login |
+
+On the first request of a run the CLI checks `GET /.well-known/speedpy.json`
+once and warns (never fails) when the manifest is unreachable or the API is
+older than the minimum this client expects.
+
+## Development
+
+```bash
+uv run --with pytest --with httpx --with click --with keyring pytest packages/withfeedback-cli/
+```

withfeedback-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+withfeedback_cli/__init__.py,sha256=clnmpqafsocCATdjRtqF8VsYdR2hUmHo0hnWRo05Ns0,59
+withfeedback_cli/auth.py,sha256=oUQPdMKxFblM-Rekr3I5HrFaUvDlqaYTwsd4OiN5Bco,9295
+withfeedback_cli/client.py,sha256=db2T4vEPZUmyJkng3CCmpk40HCIxx2HZBNRvxSfTbzQ,5445
+withfeedback_cli/main.py,sha256=tbSS4EVMhiM2iEWhFHpsWdoU6Y15utk6QzZNp63W-fQ,20957
+withfeedback-0.1.0.dist-info/METADATA,sha256=c-ZT9FZM5kXc06YBSbWfs6DimyetbEJB5wwEnfqO0gU,6295
+withfeedback-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+withfeedback-0.1.0.dist-info/entry_points.txt,sha256=GpkGmOuJYp1tagxxF4n_4wawWiUt-eBntWcgzM-mwbY,59
+withfeedback-0.1.0.dist-info/RECORD,,

withfeedback-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

withfeedback-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+withfeedback = withfeedback_cli.main:cli

withfeedback_cli/__init__.py

@@ -0,0 +1,3 @@
+"""withfeedback.com CLI package."""
+
+__version__ = "0.1.0"

withfeedback_cli/auth.py

@@ -0,0 +1,284 @@
+"""Authentication for the withfeedback CLI.
+
+Tokens live in the OS keychain via ``keyring`` (macOS Keychain, Windows
+Credential Locker, Secret Service on Linux) — never in plaintext files.
+
+Stored entries (service ``withfeedback-cli``):
+
+- ``access_token`` — OAuth2 access token or PAT
+- ``refresh_token`` — OAuth2 refresh token (rotation handled on refresh)
+- ``token_kind`` — ``"oauth"`` or ``"pat"``
+- ``client_id`` — OAuth2 client id used for login/refresh
+
+Token resolution precedence for API calls:
+``--token`` flag > ``WITHFEEDBACK_TOKEN`` env > keychain.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+import webbrowser
+
+import httpx
+import keyring
+import keyring.errors
+
+from .client import APIError, TIMEOUT, USER_AGENT, get_base_url
+
+KEYRING_SERVICE = "withfeedback-cli"
+
+#: Official public device-flow OAuth2 client for withfeedback.com
+#: (public by design — device-flow clients have no secret).
+#: Override with --client-id / WITHFEEDBACK_CLIENT_ID for self-hosted
+#: instances.
+DEFAULT_CLIENT_ID = "7yQMsnY2Is2f5tCuwwgItoQu3fRkEX2wnzIRj0Vh"
+
+#: Scopes requested during device-flow login — everything the CLI uses.
+DEFAULT_SCOPES = (
+    "read:teams read:feedback write:feedback read:testimonials "
+    "write:testimonials moderate:submissions read:widgets read:surveys"
+)
+
+_KEYS = ("access_token", "refresh_token", "token_kind", "client_id")
+
+
+# ---------------------------------------------------------------------------
+# Keychain storage
+# ---------------------------------------------------------------------------
+
+
+def store_tokens(
+    access_token: str,
+    refresh_token: str = "",
+    *,
+    kind: str = "oauth",
+    client_id: str = "",
+) -> None:
+    """Persist tokens to the OS keychain.
+
+    Writes the new values before deleting anything, so an interruption
+    mid-update never leaves the keychain without a usable access token.
+    """
+    keyring.set_password(KEYRING_SERVICE, "access_token", access_token)
+    keyring.set_password(KEYRING_SERVICE, "token_kind", kind)
+    if client_id:
+        keyring.set_password(KEYRING_SERVICE, "client_id", client_id)
+    if refresh_token:
+        keyring.set_password(KEYRING_SERVICE, "refresh_token", refresh_token)
+    else:
+        # Delete last: everything new is already written at this point.
+        _delete_entry("refresh_token")
+
+
+def _read(key: str) -> str:
+    try:
+        return keyring.get_password(KEYRING_SERVICE, key) or ""
+    except Exception:
+        return ""
+
+
+def stored_access_token() -> str:
+    return _read("access_token")
+
+
+def stored_refresh_token() -> str:
+    return _read("refresh_token")
+
+
+def stored_token_kind() -> str:
+    return _read("token_kind")
+
+
+def stored_client_id() -> str:
+    return _read("client_id")
+
+
+def _delete_entry(key: str) -> None:
+    """Delete a keychain entry. A missing entry is fine; any other failure
+    is logged (the stale credential is still in the keychain)."""
+    try:
+        keyring.delete_password(KEYRING_SERVICE, key)
+    except keyring.errors.PasswordDeleteError:
+        pass  # entry didn't exist — nothing to delete
+    except Exception as exc:
+        print(
+            f"warning: could not delete keychain entry {key!r}: {exc}. "
+            "The stale credential may still be stored — remove it with your "
+            "OS keychain tool if needed.",
+            file=sys.stderr,
+        )
+
+
+def clear_tokens() -> None:
+    for key in _KEYS:
+        _delete_entry(key)
+
+
+# ---------------------------------------------------------------------------
+# OAuth2 device flow + refresh-token rotation
+# ---------------------------------------------------------------------------
+
+
+def device_flow(client_id: str, scope: str | None = None) -> dict:
+    """Run the device authorization grant; return the full token response
+    (``access_token``, ``refresh_token``, ``expires_in``, ...)."""
+    base = get_base_url()
+    scope = scope or os.environ.get("WITHFEEDBACK_SCOPES", DEFAULT_SCOPES)
+    try:
+        resp = httpx.post(
+            f"{base}/o/device-authorization/",
+            data={"client_id": client_id, "scope": scope},
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "User-Agent": USER_AGENT,
+            },
+            timeout=TIMEOUT,
+        )
+        resp.raise_for_status()
+    except httpx.RequestError as exc:
+        raise APIError(0, f"Network error contacting {base}: {exc}") from exc
+    except httpx.HTTPStatusError as exc:
+        raise APIError(
+            exc.response.status_code,
+            f"Device authorization failed: HTTP {exc.response.status_code}. "
+            "Is the client id correct?",
+        ) from exc
+    data = resp.json()
+
+    verification_uri = data.get("verification_uri_complete") or data["verification_uri"]
+    user_code = data["user_code"]
+    device_code = data["device_code"]
+    interval = data.get("interval", 5)
+    expires_in = data.get("expires_in", 600)
+
+    print(
+        f"\n  Open this URL in your browser:\n    {verification_uri}\n"
+        f"\n  Enter code: {user_code}\n",
+        file=sys.stderr,
+    )
+    try:
+        webbrowser.open(verification_uri)
+    except Exception:
+        pass  # headless environments
+
+    # Poll no longer than the device code is valid (RFC 8628 §3.5): the
+    # deadline caps the loop, and each sleep is clamped to the time left.
+    deadline = time.monotonic() + expires_in
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        time.sleep(min(interval, remaining))
+        try:
+            token_resp = httpx.post(
+                f"{base}/o/token/",
+                data={
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                    "client_id": client_id,
+                },
+                headers={
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "User-Agent": USER_AGENT,
+                },
+                timeout=TIMEOUT,
+            )
+        except httpx.HTTPError as exc:
+            raise APIError(
+                0,
+                f"Network error while waiting for device-flow approval: {exc}. "
+                "Check your connection and run 'withfeedback login' again.",
+            ) from exc
+        if token_resp.status_code == 200:
+            print("  Authenticated successfully.\n", file=sys.stderr)
+            return token_resp.json()
+
+        try:
+            error = token_resp.json().get("error", "")
+        except ValueError:
+            raise APIError(
+                token_resp.status_code,
+                f"Device flow: token endpoint returned HTTP "
+                f"{token_resp.status_code}.",
+            )
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            # RFC 8628 §3.5: increase the polling interval by 5 seconds.
+            interval += 5
+            continue
+        raise APIError(token_resp.status_code, f"Device flow error: {error}")
+
+    raise APIError(0, "Device code expired before approval. Run login again.")
+
+
+def refresh_access_token() -> str:
+    """Exchange the stored refresh token for a new pair.
+
+    Refresh tokens rotate server-side: the response's new refresh token
+    replaces the stored one. Returns the new access token, or "" when
+    refresh isn't possible (no refresh token / refresh rejected).
+    """
+    refresh_token = stored_refresh_token()
+    client_id = stored_client_id()
+    if not refresh_token or not client_id:
+        return ""
+
+    base = get_base_url()
+    try:
+        resp = httpx.post(
+            f"{base}/o/token/",
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": client_id,
+            },
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "User-Agent": USER_AGENT,
+            },
+            timeout=TIMEOUT,
+        )
+    except httpx.HTTPError:
+        return ""
+    if resp.status_code != 200:
+        return ""
+
+    payload = resp.json()
+    access_token = payload.get("access_token", "")
+    if not access_token:
+        return ""
+    store_tokens(
+        access_token,
+        payload.get("refresh_token", ""),  # rotated refresh token
+        kind="oauth",
+        client_id=client_id,
+    )
+    return access_token
+
+
+# ---------------------------------------------------------------------------
+# Token resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_token(flag_token: str = "") -> tuple[str, str]:
+    """Resolve (token, source) — source is "flag", "env", or "keyring".
+
+    Raises :class:`APIError` when no credentials exist anywhere.
+    """
+    if flag_token:
+        return flag_token, "flag"
+    env_token = os.environ.get("WITHFEEDBACK_TOKEN", "")
+    if env_token:
+        return env_token, "env"
+    stored = stored_access_token()
+    if stored:
+        return stored, "keyring"
+    raise APIError(
+        0,
+        "Not authenticated. Run 'withfeedback login' (device flow), "
+        "'withfeedback login --token <PAT>', or set WITHFEEDBACK_TOKEN.",
+    )

withfeedback_cli/client.py

@@ -0,0 +1,175 @@
+"""Tiny internal HTTP client for the withfeedback.com API (CLI edition).
+
+Responsibilities:
+
+- Base URL resolution (``WITHFEEDBACK_API_URL`` env override, default
+  ``https://withfeedback.com``).
+- Bearer auth header (token is resolved by :mod:`withfeedback_cli.auth`).
+- 30 second request timeout.
+- One-shot, in-process cached version-compatibility check against
+  ``GET /.well-known/speedpy.json`` — warns (never fails) when the
+  manifest is unreachable or older than we expect.
+- Readable :class:`APIError` messages carrying the API's error detail.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import httpx
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://withfeedback.com"
+MIN_API_VERSION = "1.0.0"
+USER_AGENT = f"withfeedback-cli/{__version__}"
+TIMEOUT = 30.0
+
+
+class APIError(Exception):
+    """API error with a readable message and the HTTP status (0 = network)."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+def get_base_url() -> str:
+    """Resolve the API base URL (env override, no trailing slash)."""
+    return os.environ.get("WITHFEEDBACK_API_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+# ---------------------------------------------------------------------------
+# Version compatibility (manifest) check — cached in process, warn-only
+# ---------------------------------------------------------------------------
+
+_manifest_state: dict[str, Any] = {"checked": False, "manifest": None}
+
+
+def _parse_version(value: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in value.strip().split("."))
+
+
+def check_compatibility() -> dict | None:
+    """Fetch ``/.well-known/speedpy.json`` once per process; warn, never fail."""
+    if _manifest_state["checked"]:
+        return _manifest_state["manifest"]
+    _manifest_state["checked"] = True
+
+    base = get_base_url()
+    try:
+        resp = httpx.get(
+            f"{base}/.well-known/speedpy.json",
+            timeout=TIMEOUT,
+            headers={"User-Agent": USER_AGENT},
+        )
+        resp.raise_for_status()
+        manifest = resp.json()
+    except Exception:
+        print(
+            f"warning: could not fetch {base}/.well-known/speedpy.json — "
+            "skipping API version compatibility check.",
+            file=sys.stderr,
+        )
+        return None
+
+    _manifest_state["manifest"] = manifest
+    api_version = str(manifest.get("service", {}).get("api_version", ""))
+    try:
+        if api_version and _parse_version(api_version) < _parse_version(MIN_API_VERSION):
+            print(
+                f"warning: server API version {api_version} is older than the "
+                f"minimum this client expects ({MIN_API_VERSION}); some "
+                "commands may not work.",
+                file=sys.stderr,
+            )
+    except ValueError:
+        pass
+    return manifest
+
+
+def reset_compatibility_cache() -> None:
+    """Testing hook: forget the cached manifest check."""
+    _manifest_state["checked"] = False
+    _manifest_state["manifest"] = None
+
+
+# ---------------------------------------------------------------------------
+# Requests
+# ---------------------------------------------------------------------------
+
+_STATUS_HINTS = {
+    400: "Validation error.",
+    401: "Authentication failed — run 'withfeedback login' or check your token.",
+    402: "Payment required — plan quota exceeded or billing blocked.",
+    403: (
+        "Forbidden — missing scope, insufficient role, or the team's plan "
+        "does not include API access."
+    ),
+    404: "Not found — unknown team/project/object, or no access to it.",
+    409: "Conflict — invalid state transition.",
+    429: "Rate limited — slow down and retry later.",
+}
+
+
+def _error_message(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+    except ValueError:
+        body = None
+
+    detail = ""
+    if isinstance(body, dict):
+        if "detail" in body:
+            detail = str(body["detail"])
+            if body.get("code"):
+                detail = f"[{body['code']}] {detail}"
+        else:
+            detail = "; ".join(f"{key}: {value}" for key, value in body.items())
+
+    hint = _STATUS_HINTS.get(resp.status_code, "API error.")
+    message = f"HTTP {resp.status_code}: {hint}"
+    if detail:
+        message = f"{message} {detail}"
+    return message
+
+
+def request(
+    method: str,
+    path: str,
+    token: str,
+    *,
+    params: dict | None = None,
+    json_body: dict | None = None,
+    data: dict | None = None,
+    files: dict | None = None,
+) -> Any:
+    """Authenticated request (JSON or multipart). Raises :class:`APIError`."""
+    check_compatibility()
+    url = f"{get_base_url()}{path}"
+    try:
+        resp = httpx.request(
+            method,
+            url,
+            params=params,
+            json=json_body,
+            data=data,
+            files=files,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "User-Agent": USER_AGENT,
+            },
+            timeout=TIMEOUT,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            0, f"Network error contacting {get_base_url()}: {exc}"
+        ) from exc
+
+    if resp.status_code >= 400:
+        raise APIError(resp.status_code, _error_message(resp))
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()

withfeedback_cli/main.py

@@ -0,0 +1,582 @@
+"""withfeedback — command-line client for withfeedback.com.
+
+Human output is plain text tables; pass ``--json`` on any data command for
+machine-readable output. API errors print the API's error detail to stderr
+and exit non-zero (see exit-code table in the README).
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import sys
+from typing import Any
+
+import click
+
+from . import auth
+from .client import APIError, request
+
+EXIT_GENERAL = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_FORBIDDEN = 4
+EXIT_NOT_FOUND = 5
+EXIT_VALIDATION = 6
+EXIT_NETWORK = 7
+
+
+def _exit_code(error: APIError) -> int:
+    status = error.status_code
+    if status == 401:
+        return EXIT_AUTH
+    if status in (402, 403):
+        return EXIT_FORBIDDEN
+    if status == 404:
+        return EXIT_NOT_FOUND
+    if status in (400, 409):
+        return EXIT_VALIDATION
+    if status == 0:
+        message = str(error)
+        if "Network error" in message:
+            return EXIT_NETWORK
+        if "Not authenticated" in message:
+            return EXIT_AUTH
+    return EXIT_GENERAL
+
+
+def _fail(error: APIError) -> None:
+    """Print the API's error detail to stderr and exit non-zero."""
+    click.echo(str(error), err=True)
+    sys.exit(_exit_code(error))
+
+
+def api_request(method: str, path: str, *, token_flag: str = "", **kwargs) -> Any:
+    """Authenticated request with a single 401-triggered token refresh.
+
+    Refresh only applies to keychain-stored OAuth tokens. A rejected PAT is
+    never "refreshed" — the stored refresh credentials would belong to a
+    different login — so a PAT 401 becomes a clear re-login instruction.
+    """
+    token, source = auth.resolve_token(token_flag)
+    try:
+        return request(method, path, token, **kwargs)
+    except APIError as error:
+        if error.status_code == 401 and source == "keyring":
+            kind = auth.stored_token_kind()
+            if kind == "pat":
+                raise APIError(
+                    401,
+                    "The stored personal access token was rejected (revoked "
+                    "or expired). Create a new token at /accounts/tokens/ and "
+                    "run 'withfeedback login --token <PAT>' again.",
+                ) from error
+            new_token = auth.refresh_access_token()
+            if new_token:
+                return request(method, path, new_token, **kwargs)
+        raise
+
+
+def _emit(data: Any, json_mode: bool, human) -> None:
+    """Print JSON in --json mode, else call the human formatter."""
+    if json_mode:
+        click.echo(json.dumps(data, indent=2))
+    else:
+        human(data)
+
+
+def _rows(data: Any) -> list[dict]:
+    """Unwrap DRF pagination envelopes into a plain list."""
+    if isinstance(data, dict):
+        return data.get("results", [])
+    return data or []
+
+
+def print_table(headers: list[str], rows: list[list[str]]) -> None:
+    """Plain fixed-width table (no external dependencies)."""
+    if not rows:
+        click.echo("(no results)")
+        return
+    table = [headers] + [[str(cell) for cell in row] for row in rows]
+    widths = [max(len(row[i]) for row in table) for i in range(len(headers))]
+    for index, row in enumerate(table):
+        click.echo("  ".join(cell.ljust(width) for cell, width in zip(row, widths)).rstrip())
+        if index == 0:
+            click.echo("  ".join("-" * width for width in widths))
+
+
+def _truncate(text: str, limit: int = 50) -> str:
+    text = (text or "").replace("\n", " ")
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+# ---------------------------------------------------------------------------
+# Root group + auth commands
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+@click.version_option(package_name="withfeedback", prog_name="withfeedback")
+def cli() -> None:
+    """withfeedback.com — testimonials, feedback, widgets, and NPS.
+
+    Base URL defaults to https://withfeedback.com; override with the
+    WITHFEEDBACK_API_URL environment variable.
+    """
+
+
+@cli.command()
+@click.option("--client-id", envvar="WITHFEEDBACK_CLIENT_ID",
+              default=auth.DEFAULT_CLIENT_ID, show_default=True,
+              help="OAuth2 device-flow client id (default: the official "
+                   "withfeedback.com public client).")
+@click.option("--token", default="",
+              help="Skip the device flow and store this personal access token instead.")
+@click.option("--scope", default=None, help="Scopes to request (device flow only).")
+def login(client_id: str, token: str, scope: str | None) -> None:
+    """Authenticate and store tokens in the OS keychain.
+
+    Default: OAuth2 device flow (opens a browser, you enter a code).
+    With --token, the personal access token is stored instead.
+    """
+    try:
+        if token:
+            auth.store_tokens(token, kind="pat")
+            click.echo("Personal access token stored in the OS keychain.")
+            return
+        if not client_id:
+            click.echo(
+                "Empty --client-id. Pass a device-flow client id or use "
+                "--token to store a personal access token.",
+                err=True,
+            )
+            sys.exit(EXIT_USAGE)
+        payload = auth.device_flow(client_id, scope)
+        auth.store_tokens(
+            payload["access_token"],
+            payload.get("refresh_token", ""),
+            kind="oauth",
+            client_id=client_id,
+        )
+        click.echo("Logged in. Tokens stored in the OS keychain.")
+    except APIError as error:
+        _fail(error)
+
+
+@cli.command()
+def logout() -> None:
+    """Remove stored tokens from the OS keychain."""
+    auth.clear_tokens()
+    click.echo("Logged out — stored tokens removed.")
+
+
+# ---------------------------------------------------------------------------
+# Testimonials
+# ---------------------------------------------------------------------------
+
+
+@cli.group()
+def testimonials() -> None:
+    """List, moderate, and create testimonials."""
+
+
+@testimonials.command(name="list")
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--status", default=None,
+              type=click.Choice(["pending", "approved", "rejected", "spam"]),
+              help="Filter by moderation status.")
+@click.option("--kind", default="testimonial",
+              type=click.Choice(["testimonial", "feedback", "survey_response", "all"]),
+              show_default=True, help="Submission kind ('all' disables the filter).")
+@click.option("--rating", type=click.IntRange(1, 5), default=None,
+              help="Filter by exact star rating.")
+@click.option("--q", "query", default=None, help="Search within the text.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def testimonials_list(team, project, status, kind, rating, query, json_mode, token_flag):
+    """List a project's testimonials (scope: read:feedback)."""
+    params: dict[str, Any] = {}
+    if kind != "all":
+        params["kind"] = kind
+    if status:
+        params["status"] = status
+    if rating is not None:
+        params["rating"] = rating
+    if query:
+        params["q"] = query
+    try:
+        data = api_request(
+            "GET",
+            f"/api/v1/teams/{team}/projects/{project}/submissions/",
+            params=params or None,
+            token_flag=token_flag,
+        )
+    except APIError as error:
+        _fail(error)
+
+    def human(data):
+        rows = [
+            [
+                item.get("id", ""),
+                item.get("status", ""),
+                item.get("rating") if item.get("rating") is not None else "-",
+                (item.get("contact") or {}).get("name") or "-",
+                (item.get("created_at") or "")[:10],
+                _truncate(item.get("text", "")),
+            ]
+            for item in _rows(data)
+        ]
+        print_table(["ID", "STATUS", "RATING", "NAME", "CREATED", "TEXT"], rows)
+        if isinstance(data, dict) and data.get("next"):
+            click.echo("(more results available — use --json to page with the cursor)")
+
+    _emit(data, json_mode, human)
+
+
+def _moderation_command(action: str):
+    @click.argument("submission_id", type=click.UUID)
+    @click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+    @click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+    @click.option("--token", "token_flag", default="", help="PAT override for this call.")
+    def command(submission_id, team, json_mode, token_flag):
+        try:
+            data = api_request(
+                "POST",
+                f"/api/v1/teams/{team}/submissions/{submission_id}/{action}/",
+                token_flag=token_flag,
+            )
+        except APIError as error:
+            _fail(error)
+        _emit(
+            data,
+            json_mode,
+            lambda d: click.echo(f"{action.capitalize()}d {d.get('id')} (status: {d.get('status')})"),
+        )
+
+    return command
+
+
+testimonials.command(name="approve", help=(
+    "Approve a submission (scope: moderate:submissions)."
+))(_moderation_command("approve"))
+testimonials.command(name="reject", help=(
+    "Reject or unpublish a submission (scope: moderate:submissions)."
+))(_moderation_command("reject"))
+
+
+@testimonials.command(name="create")
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--text", required=True, help="Testimonial text.")
+@click.option("--rating", type=click.IntRange(1, 5), default=None, help="Star rating (1-5).")
+@click.option("--name", default="", help="Author name.")
+@click.option("--email", default="", help="Author email.")
+@click.option("--title", "job_title", default="", help="Author job title.")
+@click.option("--company", default="", help="Author company.")
+@click.option("--consent/--no-consent", "consent_display", default=False,
+              help="Whether display consent was collected.")
+@click.option("--tag", "tags", multiple=True, help="Tag (repeatable).")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def testimonials_create(team, project, text, rating, name, email, job_title,
+                        company, consent_display, tags, json_mode, token_flag):
+    """Create a pending testimonial (scope: write:testimonials)."""
+    body: dict[str, Any] = {
+        "kind": "testimonial",
+        "text": text,
+        "consent_display": consent_display,
+    }
+    if rating is not None:
+        body["rating"] = rating
+    if tags:
+        body["tags"] = list(tags)
+    if email:
+        body["contact_email"] = email
+    if name:
+        body["contact_name"] = name
+    if job_title:
+        body["contact_title"] = job_title
+    if company:
+        body["contact_company"] = company
+    try:
+        data = api_request(
+            "POST",
+            f"/api/v1/teams/{team}/projects/{project}/submissions/",
+            json_body=body,
+            token_flag=token_flag,
+        )
+    except APIError as error:
+        _fail(error)
+    _emit(
+        data,
+        json_mode,
+        lambda d: click.echo(f"Created {d.get('id')} (status: {d.get('status')})"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# CSV import
+# ---------------------------------------------------------------------------
+
+
+@cli.group(name="import")
+def import_group() -> None:
+    """Bulk imports."""
+
+
+@import_group.command(name="csv")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--text-col", required=True, help="CSV column with the testimonial text.")
+@click.option("--rating-col", default=None, help="CSV column with the 1-5 rating.")
+@click.option("--name-col", default=None, help="CSV column with the author name.")
+@click.option("--email-col", default=None, help="CSV column with the author email.")
+@click.option("--consent/--no-consent", default=False,
+              help="Whether display consent was collected for these rows.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def import_csv(file, team, project, text_col, rating_col, name_col, email_col,
+               consent, json_mode, token_flag):
+    """Import testimonials from a CSV file (scope: write:feedback).
+
+    The file is validated locally (headers, row count), then uploaded to the
+    server's import endpoint; rows land as pending submissions and are
+    processed asynchronously.
+    """
+    try:
+        with open(file, "r", encoding="utf-8-sig", newline="") as handle:
+            content = handle.read()
+    except OSError as error:
+        click.echo(f"Cannot read {file}: {error}", err=True)
+        sys.exit(EXIT_USAGE)
+
+    reader = csv.DictReader(io.StringIO(content))
+    headers = reader.fieldnames or []
+    mapping = {"text": text_col}
+    if rating_col:
+        mapping["rating"] = rating_col
+    if name_col:
+        mapping["name"] = name_col
+    if email_col:
+        mapping["email"] = email_col
+
+    missing = [col for col in mapping.values() if col not in headers]
+    if missing:
+        click.echo(
+            f"Column(s) not found in the CSV header: {', '.join(missing)}. "
+            f"Available columns: {', '.join(headers) or '(none)'}",
+            err=True,
+        )
+        sys.exit(EXIT_USAGE)
+
+    row_count = sum(1 for _ in reader)
+    if row_count == 0:
+        click.echo("The CSV has a header but no data rows.", err=True)
+        sys.exit(EXIT_USAGE)
+
+    try:
+        data = api_request(
+            "POST",
+            f"/api/v1/teams/{team}/projects/{project}/imports/",
+            data={
+                "mapping": json.dumps(mapping),
+                "consent": "true" if consent else "false",
+            },
+            files={"file": (file.rsplit("/", 1)[-1], content.encode("utf-8"), "text/csv")},
+            token_flag=token_flag,
+        )
+    except APIError as error:
+        _fail(error)
+
+    def human(d):
+        click.echo(f"Import accepted: batch {d.get('id')} ({row_count} rows).")
+        click.echo(f"Status: {d.get('status')}")
+        if d.get("status_url"):
+            click.echo(f"Poll: {d['status_url']}")
+
+    _emit(data, json_mode, human)
+
+
+# ---------------------------------------------------------------------------
+# Surveys / NPS
+# ---------------------------------------------------------------------------
+
+
+@cli.group()
+def surveys() -> None:
+    """Surveys."""
+
+
+@surveys.command(name="list")
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def surveys_list(team, project, json_mode, token_flag):
+    """List a project's surveys (scope: read:surveys)."""
+    try:
+        data = api_request(
+            "GET",
+            f"/api/v1/teams/{team}/projects/{project}/surveys/",
+            token_flag=token_flag,
+        )
+    except APIError as error:
+        _fail(error)
+
+    def human(data):
+        rows = [
+            [
+                item.get("id", ""),
+                item.get("name", ""),
+                item.get("survey_type", ""),
+                item.get("status", ""),
+                item.get("current_version") if item.get("current_version") is not None else "-",
+            ]
+            for item in _rows(data)
+        ]
+        print_table(["ID", "NAME", "TYPE", "STATUS", "VERSION"], rows)
+
+    _emit(data, json_mode, human)
+
+
+@cli.group()
+def nps() -> None:
+    """NPS surveys."""
+
+
+@nps.command(name="summary")
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def nps_summary(team, project, json_mode, token_flag):
+    """NPS results per NPS survey (scope: read:surveys)."""
+    try:
+        surveys_data = api_request(
+            "GET",
+            f"/api/v1/teams/{team}/projects/{project}/surveys/",
+            token_flag=token_flag,
+        )
+        nps_surveys = [
+            s for s in _rows(surveys_data) if s.get("survey_type") == "nps"
+        ]
+        summaries = []
+        for survey in nps_surveys:
+            results = api_request(
+                "GET",
+                f"/api/v1/teams/{team}/projects/{project}/surveys/"
+                f"{survey['id']}/results/",
+                token_flag=token_flag,
+            )
+            summaries.append(
+                {
+                    "survey_id": survey["id"],
+                    "name": survey.get("name"),
+                    "status": survey.get("status"),
+                    "results": results,
+                }
+            )
+    except APIError as error:
+        _fail(error)
+
+    payload = {"project_id": project, "nps_surveys": summaries}
+
+    def human(payload):
+        if not payload["nps_surveys"]:
+            click.echo("This project has no NPS surveys.")
+            return
+        for entry in payload["nps_surveys"]:
+            results = entry["results"] or {}
+            current = next(
+                (v for v in results.get("versions", []) if v.get("is_current")),
+                None,
+            ) or (results.get("versions") or [{}])[-1]
+            nps_value = current.get("nps")
+            click.echo(f"{entry['name']}  ({entry['survey_id']})")
+            click.echo(f"  NPS:        {nps_value if nps_value is not None else 'n/a'}")
+            click.echo(f"  Promoters:  {current.get('promoters', 0)}")
+            click.echo(f"  Passives:   {current.get('passives', 0)}")
+            click.echo(f"  Detractors: {current.get('detractors', 0)}")
+            click.echo(f"  Responses:  {results.get('total', 0)}")
+
+    _emit(payload, json_mode, human)
+
+
+# ---------------------------------------------------------------------------
+# Widgets + usage
+# ---------------------------------------------------------------------------
+
+
+@cli.group()
+def widgets() -> None:
+    """Embeddable widgets."""
+
+
+@widgets.command(name="list")
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--project", required=True, type=click.UUID, help="Project UUID.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def widgets_list(team, project, json_mode, token_flag):
+    """List a project's widgets (scope: read:widgets)."""
+    try:
+        data = api_request(
+            "GET",
+            f"/api/v1/teams/{team}/projects/{project}/widgets/",
+            token_flag=token_flag,
+        )
+    except APIError as error:
+        _fail(error)
+
+    def human(data):
+        rows = [
+            [
+                item.get("id", ""),
+                item.get("name", ""),
+                item.get("widget_type", ""),
+                "yes" if item.get("is_active") else "no",
+            ]
+            for item in _rows(data)
+        ]
+        print_table(["ID", "NAME", "TYPE", "ACTIVE"], rows)
+
+    _emit(data, json_mode, human)
+
+
+@cli.command()
+@click.option("--team", required=True, type=click.UUID, help="Team UUID.")
+@click.option("--json", "json_mode", is_flag=True, help="Output JSON.")
+@click.option("--token", "token_flag", default="", help="PAT override for this call.")
+def usage(team, json_mode, token_flag):
+    """Quota usage vs plan limits (scope: read:feedback)."""
+    try:
+        data = api_request(
+            "GET", f"/api/v1/teams/{team}/usage/", token_flag=token_flag
+        )
+    except APIError as error:
+        _fail(error)
+
+    def human(data):
+        click.echo(f"Plan: {data.get('plan')}")
+        rows = []
+        for metric, entry in (data.get("usage") or {}).items():
+            used = (entry.get("settled") or 0) + (entry.get("reserved") or 0)
+            limit = entry.get("limit")
+            rows.append(
+                [
+                    metric,
+                    entry.get("period", ""),
+                    used,
+                    "unlimited" if limit is None else limit,
+                ]
+            )
+        print_table(["METRIC", "PERIOD", "USED", "LIMIT"], rows)
+
+    _emit(data, json_mode, human)
+
+
+if __name__ == "__main__":
+    cli()