paper-stuff 0.2.0__tar.gz

paper_stuff-0.2.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+*.pywz
+*.pyzwz
+*.pyzwzw
+*.pyzwzwz
+*.pyzwzwzw
+*.pyzwzwzwz
+__pycache__/
+.venv/
+
+# Environment files
+.env
+.env.local
+env/*.env
+!env/*.env.example
+
+# Node.js
+node_modules/
+.next/
+*.log
+
+# HTTPS certificates
+certs/
+*.pem
+*.key
+*.crt
+
+# Secrets (service account keys, etc.)
+secrets/
+
+# Logs directory (contains sensitive Azure response data)
+logs/
+*.log
+
+# Terraform
+*.tfstate
+*.tfstate.*
+.terraform/
+terraform.tfvars
+secrets.auto.tfvars
+!*.tfvars.example
+
+# Test databases
+test.db
+
+# Database backups (never commit dumps — they contain all user PII)
+backups/
+*.dump
+*.sql.gz
+
+# Fixtures (may contain PII)
+fixtures/
+
+# Prompts (may contain secrets)
+prompts/
+
+# IDE
+.idea/
+.vscode/
+
+# Local dev FileStore
+.local-storage/

paper_stuff-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: paper-stuff
+Version: 0.2.0
+Summary: CLI and MCP server for Paper Stuff document management
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: mcp<2,>=1.8
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: typer[all]<1.0,>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'

paper_stuff-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "paper-stuff"
+version = "0.2.0"
+description = "CLI and MCP server for Paper Stuff document management"
+requires-python = ">=3.11"
+dependencies = [
+    "typer[all]>=0.15,<1.0",
+    "httpx>=0.28,<1.0",
+    "pydantic>=2.0,<3.0",
+    "mcp>=1.8,<2",  # 1.8 = first release with streamable HTTP (--transport http); tested on 1.30
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "respx>=0.22", "pytest-cov>=5.0"]
+
+[project.scripts]
+paper-stuff = "paper_stuff_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paper_stuff_cli"]

paper_stuff-0.2.0/src/paper_stuff_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Paper Stuff CLI — programmatic interface for Paper Stuff document management."""
+
+__version__ = "0.2.0"

paper_stuff-0.2.0/src/paper_stuff_cli/client.py

@@ -0,0 +1,145 @@
+"""HTTP client: auth injection, error mapping, verbose logging."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import httpx
+
+from paper_stuff_cli.config import redact_key, resolve_config
+from paper_stuff_cli.errors import CLIError, cli_error_from_exception, cli_error_from_status
+
+
+class APIClient:
+    """Paper Stuff API client with auth injection and error handling."""
+
+    def __init__(
+        self,
+        *,
+        api_url: str | None = None,
+        api_key: str | None = None,
+        token: str | None = None,
+        profile: str | None = None,
+        verbose: bool = False,
+        timeout: float = 30.0,
+    ):
+        resolved = resolve_config(
+            cli_api_url=api_url,
+            cli_api_key=api_key,
+            cli_token=token,
+            cli_profile=profile,
+        )
+        self.api_url = resolved["api_url"].rstrip("/")
+        self._api_key = resolved["api_key"]
+        self._token = resolved["token"]
+        self._profile = profile
+        self._verbose = verbose
+        self._client = httpx.Client(
+            base_url=self.api_url,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    def reload_credentials(self) -> None:
+        """Re-resolve key/token from the config chain (env, dir config, profile) — used after a 401."""
+        resolved = resolve_config(cli_profile=self._profile)
+        self._api_key, self._token = resolved["api_key"], resolved["token"]
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Build auth headers. Priority: API key > JWT token."""
+        if self._api_key:
+            return {"X-API-Key": self._api_key}
+        if self._token:
+            return {"Authorization": f"Bearer {self._token}"}
+        return {}
+
+    def _log_request(self, method: str, path: str) -> None:
+        if self._verbose:
+            auth_info = ""
+            if self._api_key:
+                auth_info = f" [key={redact_key(self._api_key)}]"
+            elif self._token:
+                auth_info = " [jwt=****]"
+            print(f"  {method} {self.api_url}{path}{auth_info}", file=sys.stderr)
+
+    def _log_response(self, resp: httpx.Response) -> None:
+        if self._verbose:
+            print(f"  → {resp.status_code} ({len(resp.content)} bytes)", file=sys.stderr)
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        """Raise a CLIError from the response body if the status is non-2xx."""
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                body = resp.json()
+                detail = body.get("detail", "") if isinstance(body, dict) else str(body)
+            except (ValueError, KeyError):
+                detail = resp.text[:200]
+            raise cli_error_from_status(resp.status_code, detail, resp.headers.get("Retry-After"))
+
+    def _handle_response(self, resp: httpx.Response) -> Any:
+        """Parse JSON response; raise CLIError on non-2xx."""
+        self._log_response(resp)
+        self._raise_for_status(resp)
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Make an authenticated API request. ``timeout`` overrides the client default for this call only."""
+        merged_headers = {**self._auth_headers(), **(headers or {})}
+        self._log_request(method, path)
+        extra = {"timeout": timeout} if timeout is not None else {}
+        try:
+            resp = self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                content=data,
+                files=files,
+                headers=merged_headers,
+                **extra,
+            )
+        except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            raise cli_error_from_exception(exc)
+        return self._handle_response(resp)
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def download(self, path: str) -> httpx.Response:
+        """Download a file (returns raw response for streaming)."""
+        merged_headers = self._auth_headers()
+        self._log_request("GET", path)
+        try:
+            resp = self._client.get(path, headers=merged_headers)
+        except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            raise cli_error_from_exception(exc)
+        self._log_response(resp)
+        self._raise_for_status(resp)
+        return resp
+
+    def close(self) -> None:
+        self._client.close()

paper_stuff-0.2.0/src/paper_stuff_cli/commands/api_key.py

@@ -0,0 +1,93 @@
+"""api-key — create, list, rename, revoke."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from paper_stuff_cli.decorators import handle_cli_errors
+from paper_stuff_cli.output import print_error, print_success
+
+api_key_app = typer.Typer(help="API key management.")
+
+_KEY_COLUMNS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Prefix", "prefix"),
+    ("Scopes", "scopes"),
+    ("Created", "created_at"),
+    ("Last Used", "last_used_at"),
+    ("Expires", "expires_at"),
+]
+
+_VALID_SCOPES = {"upload", "read", "read_detail", "write", "delete", "export", "admin"}
+
+
+@api_key_app.command()
+@handle_cli_errors
+def create(
+    ctx: typer.Context,
+    name: str = typer.Argument(help="Key name"),
+    group_id: Optional[str] = typer.Option(None, "--group-id", help="Group ID"),
+    expires_in_days: Optional[int] = typer.Option(None, "--expires-in-days", help="Expiry in days"),
+    scopes: Optional[list[str]] = typer.Option(None, "--scope", help="Scopes (repeatable). Valid: upload, read, read_detail, write, delete, export, admin"),
+) -> None:
+    """Create a new API key."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    body: dict = {"name": name}
+    if group_id:
+        body["group_id"] = group_id
+    if expires_in_days:
+        body["expires_in_days"] = expires_in_days
+    if scopes:
+        invalid = set(scopes) - _VALID_SCOPES
+        if invalid:
+            print_error("VALIDATION_ERROR", f"Invalid scopes: {', '.join(sorted(invalid))}", 400, fmt=fmt)
+            raise typer.Exit(1)
+        body["scopes"] = list(set(scopes))
+    data = client.post("/api-keys", json=body)
+    print_success(data, fmt=fmt)
+
+
+@api_key_app.command("list")
+@handle_cli_errors
+def list_keys(ctx: typer.Context) -> None:
+    """List all API keys."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    data = client.get("/api-keys")
+    items = data.get("api_keys", [])
+    # Format scopes for table display
+    for item in items:
+        s = item.get("scopes")
+        item["scopes"] = ", ".join(s) if s else "all"
+    print_success(items, fmt=fmt, columns=_KEY_COLUMNS)
+
+
+@api_key_app.command()
+@handle_cli_errors
+def rename(
+    ctx: typer.Context,
+    key_id: str = typer.Argument(help="API key ID"),
+    name: str = typer.Argument(help="New name"),
+) -> None:
+    """Rename an API key."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    data = client.patch(f"/api-keys/{key_id}", json={"name": name})
+    print_success(data, fmt=fmt)
+
+
+@api_key_app.command()
+@handle_cli_errors
+def revoke(
+    ctx: typer.Context,
+    key_id: str = typer.Argument(help="API key ID"),
+) -> None:
+    """Revoke an API key."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    data = client.delete(f"/api-keys/{key_id}")
+    print_success(data, fmt=fmt)

paper_stuff-0.2.0/src/paper_stuff_cli/commands/auth.py

@@ -0,0 +1,82 @@
+"""auth — login, status, logout."""
+
+import typer
+
+from paper_stuff_cli.errors import CLIError
+from paper_stuff_cli.config import (
+    load_global_config,
+    redact_key,
+    save_global_config,
+    set_profile_value,
+)
+from paper_stuff_cli.output import print_error, print_message, print_success
+
+auth_app = typer.Typer(help="Authentication management.")
+
+
+@auth_app.command()
+def login(
+    ctx: typer.Context,
+    api_key: str = typer.Option(..., "--api-key", help="API key (pst_...)"),
+) -> None:
+    """Store an API key and verify it works."""
+    client = ctx.obj["client"]
+    client._api_key = api_key
+    fmt = ctx.obj["format"]
+    quiet = ctx.obj["quiet"]
+    profile = ctx.obj["profile"]
+
+    try:
+        data = client.get("/user/settings")
+        set_profile_value(profile, "api_key", api_key)
+        set_profile_value(profile, "api_url", client.api_url)
+        print_message(f"Authenticated. Key stored in profile '{profile}'.", quiet=quiet)
+        print_success({"authenticated": True, "profile": profile}, fmt=fmt)
+    except CLIError as e:
+        print_error("UNAUTHORIZED", f"API key validation failed: {e}", fmt=fmt)
+        raise typer.Exit(1)
+
+
+@auth_app.command()
+def status(ctx: typer.Context) -> None:
+    """Show current authentication state."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    profile = ctx.obj["profile"]
+
+    info = {
+        "profile": profile,
+        "api_url": client.api_url,
+        "api_key": redact_key(client._api_key),
+        "jwt": "set" if client._token else "(not set)",
+    }
+
+    # Try to verify auth
+    if client._api_key or client._token:
+        try:
+            client.get("/user/settings")
+            info["authenticated"] = True
+        except CLIError:
+            info["authenticated"] = False
+    else:
+        info["authenticated"] = False
+
+    print_success(info, fmt=fmt)
+
+
+@auth_app.command()
+def logout(ctx: typer.Context) -> None:
+    """Clear stored credentials from the active profile."""
+    profile = ctx.obj["profile"]
+    fmt = ctx.obj["format"]
+    quiet = ctx.obj["quiet"]
+
+    config = load_global_config()
+    profiles = config.get("profiles", {})
+    if profile in profiles:
+        profiles[profile].pop("api_key", None)
+        profiles[profile].pop("token", None)
+        save_global_config(config)
+
+    print_message(f"Credentials cleared for profile '{profile}'.", quiet=quiet)
+    print_success({"logged_out": True, "profile": profile}, fmt=fmt)

paper_stuff-0.2.0/src/paper_stuff_cli/commands/batch.py

@@ -0,0 +1,76 @@
+"""batch — bulk operations on multiple documents."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from paper_stuff_cli.decorators import handle_cli_errors
+from paper_stuff_cli.output import print_success
+
+batch_app = typer.Typer(help="Batch operations on documents.")
+
+
+@batch_app.command()
+@handle_cli_errors
+def delete(
+    ctx: typer.Context,
+    ids: list[str] = typer.Argument(help="Document IDs"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete multiple documents."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    if not yes:
+        typer.confirm(f"Delete {len(ids)} documents?", abort=True)
+    data = client.post("/documents/batch/delete", json={"document_ids": ids})
+    print_success(data, fmt=fmt)
+
+
+@batch_app.command("payment-status")
+@handle_cli_errors
+def payment_status(
+    ctx: typer.Context,
+    status: str = typer.Argument(help="PAID or UNPAID"),
+    ids: list[str] = typer.Argument(help="Document IDs"),
+) -> None:
+    """Update payment status for multiple documents."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    data = client.post(
+        "/documents/batch/payment-status",
+        json={"document_ids": ids, "payment_status": status.upper()},
+    )
+    print_success(data, fmt=fmt)
+
+
+@batch_app.command()
+@handle_cli_errors
+def category(
+    ctx: typer.Context,
+    ids: list[str] = typer.Argument(help="Document IDs"),
+    main: str = typer.Option(..., "--main", help="Main category"),
+    sub: Optional[str] = typer.Option(None, "--sub", help="Subcategory"),
+) -> None:
+    """Update category for multiple documents."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    body: dict = {"document_ids": ids, "main_category": main}
+    if sub:
+        body["subcategory"] = sub
+    data = client.post("/documents/batch/category", json=body)
+    print_success(data, fmt=fmt)
+
+
+@batch_app.command()
+@handle_cli_errors
+def review(
+    ctx: typer.Context,
+    ids: list[str] = typer.Argument(help="Document IDs"),
+) -> None:
+    """Mark multiple documents as reviewed."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    data = client.post("/documents/batch/review", json={"document_ids": ids})
+    print_success(data, fmt=fmt)

paper_stuff-0.2.0/src/paper_stuff_cli/commands/dashboard.py

@@ -0,0 +1,28 @@
+"""dashboard — show dashboard summary."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from paper_stuff_cli.decorators import handle_cli_errors
+from paper_stuff_cli.output import print_success
+
+dashboard_app = typer.Typer(help="Dashboard overview.")
+
+
+@dashboard_app.callback(invoke_without_command=True)
+@handle_cli_errors
+def dashboard(
+    ctx: typer.Context,
+    year: Optional[int] = typer.Option(None, "--year", help="Filter by year"),
+) -> None:
+    """Show dashboard summary."""
+    client = ctx.obj["client"]
+    fmt = ctx.obj["format"]
+    params: dict = {}
+    if year:
+        params["year"] = year
+    data = client.get("/dashboard/summary", params=params)
+    print_success(data, fmt=fmt)