bookstack-cli 0.1.0__py3-none-any.whl

bookstack_cli/__init__.py

@@ -0,0 +1,3 @@
+"""bookstack-cli: CLI tool for coding agents to interact with BookStack wiki."""
+
+__version__ = "0.1.0"

bookstack_cli/client.py

@@ -0,0 +1,211 @@
+"""Async HTTP client for BookStack API with auth, retry, pagination."""
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from bookstack_cli.config import get_config
+from bookstack_cli.exceptions import (
+    BookStackRateLimitError,
+    map_status_to_error,
+)
+
+logger = logging.getLogger(__name__)
+
+BASE_DELAY = 1.0
+MAX_RETRIES = 5
+MAX_PAGE_SIZE = 500
+
+
+class BookStackClient:
+    """Async HTTP client for BookStack REST API.
+
+    Handles:
+    - Auth header injection (Token token_id:token_secret)
+    - Rate-limit retry with exponential backoff
+    - Auto-pagination via async generator
+    - Error mapping to typed exceptions
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token_id: str | None = None,
+        token_secret: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if base_url and token_id and token_secret:
+            self._base_url = base_url.rstrip("/")
+            self._token_id = token_id
+            self._token_secret = token_secret
+        else:
+            cfg = get_config()
+            self._base_url = cfg.url
+            self._token_id = cfg.token_id
+            self._token_secret = cfg.token_secret
+
+        auth_header_value = f"Token {self._token_id}:{self._token_secret}"
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": auth_header_value,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "BookStackClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def __enter__(self) -> "BookStackClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        loop.run_until_complete(self.close())
+
+    # ------------------------------------------------------------------
+    # Request with retry
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        retry_count: int = 0,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Send HTTP request with rate-limit retry."""
+        url = f"/api/{path.lstrip('/')}"
+        # Remove Content-Type for multipart (httpx sets correct boundary)
+        has_files = "files" in kwargs
+        if has_files:
+            old_ct = self._client.headers.pop("Content-Type", None)
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        finally:
+            if has_files and old_ct is not None:
+                self._client.headers["Content-Type"] = old_ct
+
+        if response.status_code == 429 and retry_count < MAX_RETRIES:
+            retry_after = _parse_retry_after(response)
+            delay = max(retry_after, BASE_DELAY * (2**retry_count))
+            logger.warning(
+                "Rate limited. Retry %d/%d after %.1fs",
+                retry_count + 1,
+                MAX_RETRIES,
+                delay,
+            )
+            await asyncio.sleep(delay)
+            return await self._request(method, path, retry_count + 1, **kwargs)
+
+        if response.is_error:
+            _raise_for_status(response)
+
+        return response
+
+    # ------------------------------------------------------------------
+    # CRUD helpers
+    # ------------------------------------------------------------------
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """GET request returning parsed JSON."""
+        response = await self._request("GET", path, params=params)
+        return response.json()
+
+    async def get_raw(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """GET request returning raw response (e.g. for binary downloads)."""
+        return await self._request("GET", path, params=params)
+
+    async def post(
+        self, path: str, json: dict[str, Any] | None = None, data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """POST request returning parsed JSON."""
+        response = await self._request("POST", path, json=json, data=data)
+        return response.json()
+
+    async def put(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """PUT request returning parsed JSON."""
+        response = await self._request("PUT", path, json=json)
+        return response.json()
+
+    async def delete(self, path: str) -> None:
+        """DELETE request."""
+        await self._request("DELETE", path)
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    async def paginate(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        page_size: int = 100,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Iterate over all pages of a list endpoint.
+
+        Yields individual items from ``data`` across all pages.
+        """
+        params = dict(params or {})
+        params.setdefault("count", min(page_size, MAX_PAGE_SIZE))
+        page = 1
+
+        while True:
+            params["page"] = page
+            data = await self.get(path, params=params)
+            items: list[dict[str, Any]] = data.get("data", [])
+            for item in items:
+                yield item
+
+            total: int = data.get("total", 0)
+            per_page = data.get("per_page")
+            if per_page is None:
+                per_page = len(items) or page_size
+            if page * per_page >= total:
+                break
+            page += 1
+
+
+def _parse_retry_after(response: httpx.Response) -> float:
+    """Extract Retry-After header value as float."""
+    val = response.headers.get("Retry-After", "1")
+    try:
+        return float(val)
+    except ValueError:
+        return 1.0
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP status to typed BookStack exception."""
+    try:
+        body = response.json()
+        error = body.get("error", {})
+        message = str(error.get("message", response.reason_phrase))
+        validation = error.get("validation")
+        if validation:
+            details = "; ".join(
+                f"{k}: {', '.join(v)}" for k, v in validation.items()
+            )
+            message = f"{message} ({details})"
+    except Exception:
+        message = response.reason_phrase or "Unknown error"
+
+    raise map_status_to_error(response.status_code, message)

bookstack_cli/config.py

@@ -0,0 +1,131 @@
+"""Configuration loader for BookStack connection settings.
+
+Config file: ~/.config/bookstack-cli/config.toml
+
+```toml
+[connection]
+url = "http://10.0.0.1:8080"              # API endpoint (internal)
+resolve_url = "https://wiki.example.com"  # Public web URL (optional, falls back to url)
+token_id = "<your-token-id>"
+token_secret = "<your-token-secret>"
+```
+
+Env vars override file values:
+- BOOKSTACK_URL
+- BOOKSTACK_RESOLVE_URL
+- BOOKSTACK_TOKEN_ID
+- BOOKSTACK_TOKEN_SECRET
+"""
+
+import os
+import tomllib
+from pathlib import Path
+from typing import NamedTuple
+
+from bookstack_cli.exceptions import BookStackConfigError
+
+
+class BookStackConfig(NamedTuple):
+    """Connection configuration for a BookStack instance."""
+
+    url: str
+    token_id: str
+    token_secret: str
+    resolve_url: str | None = None
+
+
+CONFIG_DIR = Path.home() / ".config" / "bookstack-cli"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def _load_env() -> BookStackConfig | None:
+    """Load config from environment variables."""
+    url = os.environ.get("BOOKSTACK_URL")
+    token_id = os.environ.get("BOOKSTACK_TOKEN_ID")
+    token_secret = os.environ.get("BOOKSTACK_TOKEN_SECRET")
+    if url and token_id and token_secret:
+        resolve_url = os.environ.get("BOOKSTACK_RESOLVE_URL") or url
+        return BookStackConfig(
+            url=url.rstrip("/"),
+            token_id=token_id,
+            token_secret=token_secret,
+            resolve_url=resolve_url.rstrip("/"),
+        )
+    return None
+
+
+def _load_toml() -> BookStackConfig | None:
+    """Load config from ~/.config/bookstack-cli/config.toml."""
+    if not CONFIG_FILE.exists():
+        return None
+    with open(CONFIG_FILE, "rb") as f:
+        data = tomllib.load(f)
+    conn = data.get("connection", {})
+    url = conn.get("url")
+    token_id = conn.get("token_id")
+    token_secret = conn.get("token_secret")
+    if url and token_id and token_secret:
+        resolve_url = conn.get("resolve_url") or url
+        return BookStackConfig(
+            url=url.rstrip("/"),
+            token_id=token_id,
+            token_secret=token_secret,
+            resolve_url=resolve_url.rstrip("/"),
+        )
+    return None
+
+
+def get_config() -> BookStackConfig:
+    """Load config from env vars (priority) or TOML file.
+
+    Precedence:
+    1. BOOKSTACK_URL, BOOKSTACK_RESOLVE_URL, BOOKSTACK_TOKEN_ID,
+       BOOKSTACK_TOKEN_SECRET env vars
+    2. ~/.config/bookstack-cli/config.toml
+
+    Raises BookStackConfigError if neither source has complete config.
+    """
+    env_cfg = _load_env()
+    if env_cfg:
+        return env_cfg
+
+    toml_cfg = _load_toml()
+    if toml_cfg:
+        return toml_cfg
+
+    raise BookStackConfigError(
+        "BookStack config not found. "
+        "Run `bookstack auth` or set BOOKSTACK_URL, BOOKSTACK_TOKEN_ID, "
+        "BOOKSTACK_TOKEN_SECRET env vars."
+    )
+
+
+def save_config(url: str, token_id: str, token_secret: str, resolve_url: str | None = None) -> Path:
+    """Save connection to ~/.config/bookstack-cli/config.toml.
+
+    Creates parent directories if needed.
+    Returns the path to the written file.
+    """
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines = [
+        '[connection]',
+        f'url = "{_escape_toml(url.rstrip("/"))}"',
+    ]
+    if resolve_url:
+        lines.append(f'resolve_url = "{_escape_toml(resolve_url.rstrip("/"))}"')
+    lines.extend([
+        f'token_id = "{_escape_toml(token_id)}"',
+        f'token_secret = "{_escape_toml(token_secret)}"',
+    ])
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+    return CONFIG_FILE
+
+
+def _escape_toml(value: str) -> str:
+    """Escape special chars for TOML basic string."""
+    return (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+    )

bookstack_cli/exceptions.py

@@ -0,0 +1,45 @@
+"""Custom exceptions for BookStack API errors."""
+
+
+class BookStackError(Exception):
+    """Base exception for all BookStack API errors."""
+
+
+class BookStackAuthError(BookStackError):
+    """Authentication failed (401)."""
+
+
+class BookStackNotFoundError(BookStackError):
+    """Resource not found (404)."""
+
+
+class BookStackRateLimitError(BookStackError):
+    """Rate limit exceeded (429)."""
+
+
+class BookStackServerError(BookStackError):
+    """Server error (5xx)."""
+
+
+class BookStackValidationError(BookStackError):
+    """Validation error (422)."""
+
+
+class BookStackConfigError(BookStackError):
+    """Configuration error (missing URL or credentials)."""
+
+
+STATUS_ERROR_MAP: dict[int, type[BookStackError]] = {
+    401: BookStackAuthError,
+    404: BookStackNotFoundError,
+    422: BookStackValidationError,
+    429: BookStackRateLimitError,
+}
+
+
+def map_status_to_error(status_code: int, message: str) -> BookStackError:
+    """Map HTTP status code to appropriate exception."""
+    exc_cls = STATUS_ERROR_MAP.get(status_code, BookStackError)
+    if status_code >= 500:
+        return BookStackServerError(message)
+    return exc_cls(message)