bookstack-cli 0.1.0__py3-none-any.whl

bookstack_cli/models.py

@@ -0,0 +1,276 @@
+"""Pydantic models for BookStack API entities."""
+
+from datetime import datetime
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Field, BeforeValidator
+
+
+# ------------------------------------------------------------------
+# Shared / Nested
+# ------------------------------------------------------------------
+
+
+class Tag(BaseModel):
+    """A key-value tag attached to content entities."""
+
+    name: str
+    value: str | None = None
+
+
+class UserSummary(BaseModel):
+    """Minimal user reference (created_by / updated_by)."""
+
+    id: int
+    name: str
+
+
+def _coerce_user_ref(v: Any) -> Any:
+    """BookStack sometimes returns user ID int instead of {id, name} object."""
+    if isinstance(v, int):
+        return UserSummary(id=v, name="")
+    return v
+
+
+UserRef = Annotated[UserSummary | None, BeforeValidator(_coerce_user_ref)]
+
+
+# ------------------------------------------------------------------
+# Paginated List Response
+# ------------------------------------------------------------------
+
+
+class PaginatedList(BaseModel):
+    """Wrapper for paginated list responses from the API."""
+
+    data: list[dict[str, Any]]
+    total: int
+    count: int
+    per_page: int = Field(alias="per_page")
+    current_page: int = Field(alias="current_page")
+    last_page: int = Field(alias="last_page")
+    next_page_url: str | None = Field(default=None, alias="next_page_url")
+    prev_page_url: str | None = Field(default=None, alias="prev_page_url")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# ------------------------------------------------------------------
+# Shelves (Bookshelves)
+# ------------------------------------------------------------------
+
+
+class Shelf(BaseModel):
+    """A bookshelf containing books."""
+
+    id: int
+    name: str
+    description: str = ""
+    tags: list[Tag] = []
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    created_by: UserRef = None
+    updated_by: UserRef = None
+
+
+class ShelfCreate(BaseModel):
+    """Payload for creating/updating a shelf."""
+
+    name: str
+    description: str = ""
+    books: list[int] = []
+    tags: list[Tag] = []
+
+
+# ------------------------------------------------------------------
+# Books
+# ------------------------------------------------------------------
+
+
+class Book(BaseModel):
+    """A book containing chapters and pages."""
+
+    id: int
+    name: str
+    description: str = ""
+    tags: list[Tag] = []
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    created_by: UserRef = None
+    updated_by: UserRef = None
+
+
+class BookCreate(BaseModel):
+    """Payload for creating/updating a book."""
+
+    name: str
+    description: str = ""
+    tags: list[Tag] = []
+
+
+# ------------------------------------------------------------------
+# Chapters
+# ------------------------------------------------------------------
+
+
+class Chapter(BaseModel):
+    """A chapter within a book."""
+
+    id: int
+    book_id: int
+    name: str
+    description: str = ""
+    tags: list[Tag] = []
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    created_by: UserRef = None
+    updated_by: UserRef = None
+
+
+class ChapterCreate(BaseModel):
+    """Payload for creating/updating a chapter."""
+
+    book_id: int
+    name: str
+    description: str = ""
+    tags: list[Tag] = []
+
+
+# ------------------------------------------------------------------
+# Pages
+# ------------------------------------------------------------------
+
+
+class Page(BaseModel):
+    """A wiki page."""
+
+    id: int
+    book_id: int
+    chapter_id: int | None = None
+    name: str
+    slug: str = ""
+    html: str = ""
+    markdown: str = ""
+    draft: bool = False
+    tags: list[Tag] = []
+    priority: int = 0
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    created_by: UserRef = None
+    updated_by: UserRef = None
+
+
+class PageCreate(BaseModel):
+    """Payload for creating a page."""
+
+    book_id: int
+    chapter_id: int | None = None
+    name: str
+    html: str = ""
+    markdown: str = ""
+    tags: list[Tag] = []
+    draft: bool = False
+    priority: int = 0
+
+
+class PageUpdate(BaseModel):
+    """Payload for updating a page."""
+
+    name: str | None = None
+    html: str | None = None
+    markdown: str | None = None
+    tags: list[Tag] | None = None
+    draft: bool | None = None
+    priority: int | None = None
+
+
+class PageMove(BaseModel):
+    """Payload for moving a page."""
+
+    book_id: int
+    chapter_id: int | None = None
+
+
+# ------------------------------------------------------------------
+# Attachments
+# ------------------------------------------------------------------
+
+
+class Attachment(BaseModel):
+    """A file or link attachment on a page."""
+
+    id: int
+    name: str
+    page_id: int = Field(alias="uploaded_to", default=0)
+    link: str | None = None
+    file_path: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    created_by: UserRef = None
+    updated_by: UserRef = None
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class AttachmentCreate(BaseModel):
+    """Payload for creating a link or file attachment."""
+
+    name: str
+    page_id: int
+    link: str | None = None
+    # For file uploads, use multipart with ``uploaded_file``
+
+
+# ------------------------------------------------------------------
+# Users
+# ------------------------------------------------------------------
+
+
+class User(BaseModel):
+    """A BookStack user."""
+
+    id: int
+    name: str
+    email: str = ""
+    language: str = ""
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+# ------------------------------------------------------------------
+# Roles
+# ------------------------------------------------------------------
+
+
+class Role(BaseModel):
+    """A user role."""
+
+    id: int
+    name: str
+    description: str = ""
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+# ------------------------------------------------------------------
+# Search
+# ------------------------------------------------------------------
+
+
+class SearchResult(BaseModel):
+    """A single search result."""
+
+    id: int
+    name: str
+    type: str  # page, book, chapter, shelf
+    url: str = ""
+    preview_html: dict[str, str] | str = ""
+    tags: list[Tag] = []
+    score: float = 0.0
+
+    @property
+    def preview_text(self) -> str:
+        """Get preview text regardless of whether API returns string or object."""
+        if isinstance(self.preview_html, dict):
+            return self.preview_html.get("content", "")
+        return self.preview_html

bookstack_cli/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource API modules for BookStack entities."""

bookstack_cli/resources/attachments.py

@@ -0,0 +1,90 @@
+"""Attachments resource CRUD."""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from bookstack_cli.client import BookStackClient
+from bookstack_cli.models import Attachment, AttachmentCreate
+
+
+async def list_attachments(
+    client: BookStackClient,
+    page_size: int = 100,
+    page_id: int | None = None,
+) -> AsyncIterator[Attachment]:
+    """Iterate all attachments, optionally filtered by page."""
+    params: dict[str, Any] = {}
+    if page_id is not None:
+        params["page_id"] = page_id
+
+    async for item in client.paginate("attachments", params=params, page_size=page_size):
+        yield Attachment(**item)
+
+
+async def get_attachment(client: BookStackClient, attachment_id: int) -> Attachment:
+    """Get a single attachment by ID."""
+    data = await client.get(f"attachments/{attachment_id}")
+    return Attachment(**data)
+
+
+async def create_attachment_link(
+    client: BookStackClient, payload: AttachmentCreate
+) -> Attachment:
+    """Create a link-type attachment."""
+    data = await client.post("attachments", json=payload.model_dump(exclude_unset=True))
+    return Attachment(**data)
+
+
+async def upload_attachment(
+    client: BookStackClient,
+    name: str,
+    page_id: int,
+    file_content: bytes,
+    filename: str,
+) -> Attachment:
+    """Upload a file attachment using multipart."""
+    data = {
+        "name": name,
+        "uploaded_to": str(page_id),
+    }
+    files = {
+        "file": (filename, file_content),
+    }
+    response = await client._request("POST", "attachments", data=data, files=files)
+    return Attachment(**response.json())
+
+
+async def update_attachment(
+    client: BookStackClient, attachment_id: int, payload: AttachmentCreate
+) -> Attachment:
+    """Update an attachment."""
+    data = await client.put(
+        f"attachments/{attachment_id}", json=payload.model_dump(exclude_unset=True)
+    )
+    return Attachment(**data)
+
+
+async def delete_attachment(client: BookStackClient, attachment_id: int) -> None:
+    """Delete an attachment."""
+    await client.delete(f"attachments/{attachment_id}")
+
+
+async def download_attachment(
+    client: BookStackClient,
+    attachment_id: int,
+) -> tuple[str, bytes]:
+    """Download an attachment's file content.
+
+    Returns (filename, file_bytes).
+    The API returns file content as base64-encoded string in the ``content`` field.
+    """
+    import base64
+
+    data = await client.get(f"attachments/{attachment_id}")
+    name: str = data.get("name", f"attachment-{attachment_id}")
+    raw_content: str = data.get("content", "")
+    ext: str = data.get("extension", "")
+    if ext and not name.endswith(f".{ext}"):
+        name = f"{name}.{ext}"
+    file_bytes = base64.b64decode(raw_content)
+    return (name, file_bytes)

bookstack_cli/resources/books.py

@@ -0,0 +1,64 @@
+"""Books resource CRUD."""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from bookstack_cli.client import BookStackClient
+from bookstack_cli.models import Book, BookCreate
+
+
+async def list_books(
+    client: BookStackClient,
+    page_size: int = 100,
+    sort: str | None = None,
+    order: str | None = None,
+) -> AsyncIterator[Book]:
+    """Iterate all books."""
+    params: dict[str, Any] = {}
+    if sort:
+        params["sort"] = sort
+    if order:
+        params["order"] = order
+
+    async for item in client.paginate("books", params=params, page_size=page_size):
+        yield Book(**item)
+
+
+async def get_book(client: BookStackClient, book_id: int) -> Book:
+    """Get a single book by ID."""
+    data = await client.get(f"books/{book_id}")
+    return Book(**data)
+
+
+async def create_book(client: BookStackClient, payload: BookCreate) -> Book:
+    """Create a new book."""
+    data = await client.post("books", json=payload.model_dump(exclude_unset=True))
+    return Book(**data)
+
+
+async def update_book(client: BookStackClient, book_id: int, payload: BookCreate) -> Book:
+    """Update an existing book."""
+    data = await client.put(f"books/{book_id}", json=payload.model_dump(exclude_unset=True))
+    return Book(**data)
+
+
+async def delete_book(client: BookStackClient, book_id: int) -> None:
+    """Delete a book."""
+    await client.delete(f"books/{book_id}")
+
+
+async def upload_book_cover(
+    client: BookStackClient,
+    book_id: int,
+    file_content: bytes,
+    filename: str,
+) -> dict[str, Any]:
+    """Upload a cover image for a book using multipart PUT."""
+    old_ct = client._client.headers.pop("Content-Type", None)
+    try:
+        files = {"image": (filename, file_content)}
+        resp = await client._client.put(f"/api/books/{book_id}", files=files)
+        return resp.json()
+    finally:
+        if old_ct is not None:
+            client._client.headers["Content-Type"] = old_ct

bookstack_cli/resources/chapters.py

@@ -0,0 +1,46 @@
+"""Chapters resource CRUD."""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from bookstack_cli.client import BookStackClient
+from bookstack_cli.models import Chapter, ChapterCreate
+
+
+async def list_chapters(
+    client: BookStackClient,
+    page_size: int = 100,
+    book_id: int | None = None,
+) -> AsyncIterator[Chapter]:
+    """Iterate all chapters, optionally filtered by book."""
+    params: dict[str, Any] = {}
+    if book_id is not None:
+        params["book_id"] = book_id
+
+    async for item in client.paginate("chapters", params=params, page_size=page_size):
+        yield Chapter(**item)
+
+
+async def get_chapter(client: BookStackClient, chapter_id: int) -> Chapter:
+    """Get a single chapter by ID."""
+    data = await client.get(f"chapters/{chapter_id}")
+    return Chapter(**data)
+
+
+async def create_chapter(client: BookStackClient, payload: ChapterCreate) -> Chapter:
+    """Create a new chapter."""
+    data = await client.post("chapters", json=payload.model_dump(exclude_unset=True))
+    return Chapter(**data)
+
+
+async def update_chapter(
+    client: BookStackClient, chapter_id: int, payload: ChapterCreate
+) -> Chapter:
+    """Update an existing chapter."""
+    data = await client.put(f"chapters/{chapter_id}", json=payload.model_dump(exclude_unset=True))
+    return Chapter(**data)
+
+
+async def delete_chapter(client: BookStackClient, chapter_id: int) -> None:
+    """Delete a chapter."""
+    await client.delete(f"chapters/{chapter_id}")