valentina-python-client 2.1.0__tar.gz → 2.2.0__tar.gz

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 2.1.0
+Version: 2.2.0
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/pyproject.toml

@@ -16,7 +16,7 @@
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "2.1.0"
+    version = "2.2.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/__init__.py

@@ -113,4 +113,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/_sync/services/base.py

@@ -381,17 +381,24 @@ class SyncBaseService:
             return None
         return SyncBaseService._parse_rate_limit_header_value(rate_limit_header, "r")
 
-    def _get(self, path: str, *, params: dict[str, Any] | None = None) -> httpx.Response:
+    def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
         """Make a GET request.
 
         Args:
             path: API endpoint path.
             params: Query parameters.
+            headers: Additional headers (e.g. an Accept override for binary downloads).
 
         Returns:
             The HTTP response.
         """
-        return self._request("GET", path, params=params)
+        return self._request("GET", path, params=params, headers=headers)
 
     def _merge_on_behalf_of_header(self, headers: dict[str, str] | None) -> dict[str, str] | None:
         """Merge the On-Behalf-Of header into headers when _on_behalf_of is set.

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/_sync/services/global_admin.py

@@ -1,11 +1,21 @@
 # AUTO-GENERATED — do not edit. Run 'uv run duty generate_sync' to regenerate.
 """Service for interacting with the Global Admin API."""
 
+import re
 from collections.abc import Iterator, Sequence
 from datetime import datetime
 
 from vclient._sync.services.base import SyncBaseService
-from vclient.constants import DEFAULT_PAGE_LIMIT, AuditEntityType, AuditLogInclude, AuditOperation
+from vclient.constants import (
+    DEFAULT_LOG_TAIL_LIMIT,
+    DEFAULT_PAGE_LIMIT,
+    MAX_LOG_TAIL_LIMIT,
+    MIN_LOG_TAIL_LIMIT,
+    AuditEntityType,
+    AuditLogInclude,
+    AuditOperation,
+    LogLevel,
+)
 from vclient.endpoints import Endpoints
 from vclient.models import (
     AuditLog,
@@ -15,9 +25,34 @@ from vclient.models import (
     DeveloperUpdate,
     DeveloperWithApiKey,
     PaginatedResponse,
+    ServerLogArchive,
+    ServerLogEntry,
 )
 from vclient.services._audit_params import _build_audit_params
 
+_CONTENT_DISPOSITION_FILENAME = re.compile('filename=(?:"([^"]+)"|([^;]+))', re.IGNORECASE)
+
+
+def _filename_from_content_disposition(header: str | None, *, fallback: str) -> str:
+    """Extract the attachment filename from a Content-Disposition header.
+
+    Return ``fallback`` when the header is absent or contains no filename so callers
+    always get a usable name for the downloaded archive.
+
+    Args:
+        header: The raw Content-Disposition header value, or None.
+        fallback: Filename to return when none can be parsed.
+
+    Returns:
+        The parsed filename, or the fallback.
+    """
+    if not header:
+        return fallback
+    match = _CONTENT_DISPOSITION_FILENAME.search(header)
+    if not match:
+        return fallback
+    return (match.group(1) or match.group(2)).strip()
+
 
 class SyncGlobalAdminService(SyncBaseService):
     """Service for global admin operations in the Valentina API.
@@ -404,3 +439,47 @@ class SyncGlobalAdminService(SyncBaseService):
             params=params,
         ):
             yield model.model_validate(item)
+
+    def tail_logs(
+        self, *, level: LogLevel | None = None, limit: int = DEFAULT_LOG_TAIL_LIMIT
+    ) -> list[ServerLogEntry]:
+        """Tail the most recent server log entries, newest first.
+
+        Inspect on-disk server logs without shelling into the host. Requires global
+        admin privileges and that file logging is enabled on the server.
+
+        Args:
+            level: Minimum log level to include. Defaults to the server's configured
+                level when omitted.
+            limit: Maximum number of entries to return. Clamped to 1-500 (default 100).
+
+        Returns:
+            A list of ServerLogEntry objects, newest first.
+
+        Raises:
+            AuthorizationError: If you don't have global admin privileges.
+            ConflictError: If file logging is not enabled on the server.
+        """
+        clamped_limit = min(max(limit, MIN_LOG_TAIL_LIMIT), MAX_LOG_TAIL_LIMIT)
+        params = self._build_params(level=level, limit=clamped_limit)
+        response = self._get(Endpoints.ADMIN_LOGS, params=params)
+        return [ServerLogEntry.model_validate(item) for item in response.json()]
+
+    def download_logs(self) -> ServerLogArchive:
+        """Download a zip archive of the server log files.
+
+        Stream the active log file plus rotated backups as a single zip. Requires
+        global admin privileges and that file logging is enabled on the server.
+
+        Returns:
+            A ServerLogArchive with the server-provided filename and raw zip bytes.
+
+        Raises:
+            AuthorizationError: If you don't have global admin privileges.
+            ConflictError: If file logging is not enabled or no log files exist.
+        """
+        response = self._get(Endpoints.ADMIN_LOGS_DOWNLOAD, headers={"Accept": "application/zip"})
+        filename = _filename_from_content_disposition(
+            response.headers.get("Content-Disposition"), fallback="vapi-logs.zip"
+        )
+        return ServerLogArchive(filename=filename, content=response.content)

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/constants.py

@@ -21,6 +21,11 @@ IDEMPOTENT_HTTP_METHODS: frozenset[str] = frozenset({"GET", "PUT", "DELETE"})
 DEFAULT_PAGE_LIMIT = 10
 MAX_PAGE_LIMIT = 100
 
+# Server log tail defaults
+DEFAULT_LOG_TAIL_LIMIT = 100
+MIN_LOG_TAIL_LIMIT = 1
+MAX_LOG_TAIL_LIMIT = 500
+
 # HTTP Status Code Ranges (5xx Server Errors)
 HTTP_500_INTERNAL_SERVER_ERROR = 500
 HTTP_600_UPPER_BOUND = 600
@@ -70,13 +75,14 @@ CharacterInventoryType = Literal[
     "WEAPON",
 ]
 CharacterStatus = Literal["ALIVE", "DEAD"]
-CharacterType = Literal["PLAYER", "NPC", "STORYTELLER", "DEVELOPER"]
+CharacterType = Literal["PLAYER", "NPC", "STORYTELLER"]
 DiceSize = Literal[4, 6, 8, 10, 20, 100]
 FreeTraitChangesPermission = Literal["UNRESTRICTED", "WITHIN_24_HOURS", "STORYTELLER"]
 GameVersion = Literal["V4", "V5"]
 GrantXPPermission = Literal["UNRESTRICTED", "PLAYER", "STORYTELLER"]
 HunterCreed = Literal["ENTREPRENEURIAL", "FAITHFUL", "INQUISITIVE", "MARTIAL", "UNDERGROUND"]
 HunterEdgeType = Literal["ASSETS", "APTITUDES", "ENDOWMENTS"]
+LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 ManageCampaignPermission = Literal["UNRESTRICTED", "STORYTELLER"]
 PermissionLevel = Literal["USER", "ADMIN", "OWNER", "REVOKE"]
 RecoupXPPermission = Literal["UNRESTRICTED", "DENIED", "WITHIN_SESSION"]

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/endpoints.py

@@ -27,6 +27,8 @@ class Endpoints:
     ADMIN_DEVELOPER = f"{_BASE}/admin/developers/{{developer_id}}"
     ADMIN_DEVELOPER_NEW_KEY = f"{_BASE}/admin/developers/{{developer_id}}/new-key"
     ADMIN_DEVELOPER_AUDIT_LOGS = f"{ADMIN_DEVELOPER}/audit-logs"
+    ADMIN_LOGS = f"{_BASE}/admin/logs"
+    ADMIN_LOGS_DOWNLOAD = f"{ADMIN_LOGS}/download"
 
     # Developer endpoints (self-service)
     DEVELOPER_ME = f"{_BASE}/developers/me"

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/models/__init__.py

@@ -107,6 +107,8 @@ from .global_admin import (
     DeveloperCreate,
     DeveloperUpdate,
     DeveloperWithApiKey,
+    ServerLogArchive,
+    ServerLogEntry,
 )
 from .pagination import PaginatedResponse
 from .shared import (
@@ -222,6 +224,8 @@ __all__ = [
     "QuickrollCreate",
     "QuickrollUpdate",
     "RollStatistics",
+    "ServerLogArchive",
+    "ServerLogEntry",
     "SheetSection",
     "SystemHealth",
     "Trait",

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/models/characters.py

@@ -190,8 +190,12 @@ class Character(BaseModel):
     concept_name: str | None = Field(default=None, description="Name of the character concept.")
 
     # Relationships
-    user_creator_id: str = Field(..., description="ID of the user who created the character.")
-    user_player_id: str = Field(..., description="ID of the user who plays the character.")
+    user_creator_id: str | None = Field(
+        default=None, description="ID of the user who created the character."
+    )
+    user_player_id: str | None = Field(
+        default=None, description="ID of the user who plays the character."
+    )
     company_id: str = Field(..., description="ID of the company.")
     campaign_id: str = Field(..., description="ID of the campaign.")
 

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/models/global_admin.py

@@ -1,8 +1,10 @@
 """Pydantic models for Global Admin API responses."""
 
+from dataclasses import dataclass
 from datetime import datetime
+from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from vclient.constants import PermissionLevel
 
@@ -70,10 +72,40 @@ class DeveloperUpdate(BaseModel):
     is_global_admin: bool | None = None
 
 
+class ServerLogEntry(BaseModel):
+    """A single parsed server log entry from the admin logs tail endpoint.
+
+    Every field is nullable because individual log lines may omit values or fail
+    to parse as structured JSON (in which case ``raw`` holds the original line).
+    """
+
+    timestamp: str | None = None
+    level: str | None = None
+    name: str | None = None
+    message: str | None = None
+    exception: str | None = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+    raw: str | None = None
+
+
+@dataclass(frozen=True)
+class ServerLogArchive:
+    """A downloaded server-log zip archive.
+
+    Pairs the server-provided ``Content-Disposition`` filename with the raw zip
+    bytes so callers can write the archive straight to disk.
+    """
+
+    filename: str
+    content: bytes
+
+
 __all__ = [
     "Developer",
     "DeveloperCompanyPermission",
     "DeveloperCreate",
     "DeveloperUpdate",
     "DeveloperWithApiKey",
+    "ServerLogArchive",
+    "ServerLogEntry",
 ]

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/services/base.py

@@ -430,17 +430,19 @@ class BaseService:
         path: str,
         *,
         params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
         """Make a GET request.
 
         Args:
             path: API endpoint path.
             params: Query parameters.
+            headers: Additional headers (e.g. an Accept override for binary downloads).
 
         Returns:
             The HTTP response.
         """
-        return await self._request("GET", path, params=params)
+        return await self._request("GET", path, params=params, headers=headers)
 
     def _merge_on_behalf_of_header(
         self,

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/services/global_admin.py

@@ -1,13 +1,18 @@
 """Service for interacting with the Global Admin API."""
 
+import re
 from collections.abc import AsyncIterator, Sequence
 from datetime import datetime
 
 from vclient.constants import (
+    DEFAULT_LOG_TAIL_LIMIT,
     DEFAULT_PAGE_LIMIT,
+    MAX_LOG_TAIL_LIMIT,
+    MIN_LOG_TAIL_LIMIT,
     AuditEntityType,
     AuditLogInclude,
     AuditOperation,
+    LogLevel,
 )
 from vclient.endpoints import Endpoints
 from vclient.models import (
@@ -18,10 +23,35 @@ from vclient.models import (
     DeveloperUpdate,
     DeveloperWithApiKey,
     PaginatedResponse,
+    ServerLogArchive,
+    ServerLogEntry,
 )
 from vclient.services._audit_params import _build_audit_params
 from vclient.services.base import BaseService
 
+_CONTENT_DISPOSITION_FILENAME = re.compile(r'filename=(?:"([^"]+)"|([^;]+))', re.IGNORECASE)
+
+
+def _filename_from_content_disposition(header: str | None, *, fallback: str) -> str:
+    """Extract the attachment filename from a Content-Disposition header.
+
+    Return ``fallback`` when the header is absent or contains no filename so callers
+    always get a usable name for the downloaded archive.
+
+    Args:
+        header: The raw Content-Disposition header value, or None.
+        fallback: Filename to return when none can be parsed.
+
+    Returns:
+        The parsed filename, or the fallback.
+    """
+    if not header:
+        return fallback
+    match = _CONTENT_DISPOSITION_FILENAME.search(header)
+    if not match:
+        return fallback
+    return (match.group(1) or match.group(2)).strip()
+
 
 class GlobalAdminService(BaseService):
     """Service for global admin operations in the Valentina API.
@@ -427,3 +457,52 @@ class GlobalAdminService(BaseService):
             params=params,
         ):
             yield model.model_validate(item)
+
+    async def tail_logs(
+        self,
+        *,
+        level: LogLevel | None = None,
+        limit: int = DEFAULT_LOG_TAIL_LIMIT,
+    ) -> list[ServerLogEntry]:
+        """Tail the most recent server log entries, newest first.
+
+        Inspect on-disk server logs without shelling into the host. Requires global
+        admin privileges and that file logging is enabled on the server.
+
+        Args:
+            level: Minimum log level to include. Defaults to the server's configured
+                level when omitted.
+            limit: Maximum number of entries to return. Clamped to 1-500 (default 100).
+
+        Returns:
+            A list of ServerLogEntry objects, newest first.
+
+        Raises:
+            AuthorizationError: If you don't have global admin privileges.
+            ConflictError: If file logging is not enabled on the server.
+        """
+        clamped_limit = min(max(limit, MIN_LOG_TAIL_LIMIT), MAX_LOG_TAIL_LIMIT)
+        params = self._build_params(level=level, limit=clamped_limit)
+        response = await self._get(Endpoints.ADMIN_LOGS, params=params)
+        return [ServerLogEntry.model_validate(item) for item in response.json()]
+
+    async def download_logs(self) -> ServerLogArchive:
+        """Download a zip archive of the server log files.
+
+        Stream the active log file plus rotated backups as a single zip. Requires
+        global admin privileges and that file logging is enabled on the server.
+
+        Returns:
+            A ServerLogArchive with the server-provided filename and raw zip bytes.
+
+        Raises:
+            AuthorizationError: If you don't have global admin privileges.
+            ConflictError: If file logging is not enabled or no log files exist.
+        """
+        response = await self._get(
+            Endpoints.ADMIN_LOGS_DOWNLOAD, headers={"Accept": "application/zip"}
+        )
+        filename = _filename_from_content_disposition(
+            response.headers.get("Content-Disposition"), fallback="vapi-logs.zip"
+        )
+        return ServerLogArchive(filename=filename, content=response.content)

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/testing/__init__.py

@@ -52,6 +52,7 @@ from vclient.testing._factories import (
     NoteFactory,
     QuickrollFactory,
     RollStatisticsFactory,
+    ServerLogEntryFactory,
     SheetSectionFactory,
     SystemHealthFactory,
     TraitCategoryFactory,
@@ -107,6 +108,7 @@ __all__ = [
     "RollStatisticsFactory",
     "RouteSpec",
     "Routes",
+    "ServerLogEntryFactory",
     "SheetSectionFactory",
     "SyncFakeVClient",
     "SystemHealthFactory",

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/testing/_factories.py

@@ -38,6 +38,7 @@ from vclient.models import (
     Note,
     Quickroll,
     RollStatistics,
+    ServerLogEntry,
     SheetSection,
     SystemHealth,
     Trait,
@@ -241,6 +242,11 @@ class RollStatisticsFactory(ModelFactory[RollStatistics]):
     __use_defaults__ = True
 
 
+class ServerLogEntryFactory(ModelFactory[ServerLogEntry]):
+    __model__ = ServerLogEntry
+    __use_defaults__ = True
+
+
 class SheetSectionFactory(ModelFactory[SheetSection]):
     __model__ = SheetSection
     __use_defaults__ = True
@@ -337,6 +343,7 @@ __all__ = [
     "NoteFactory",
     "QuickrollFactory",
     "RollStatisticsFactory",
+    "ServerLogEntryFactory",
     "SheetSectionFactory",
     "SystemHealthFactory",
     "TraitCategoryFactory",

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/testing/_router.py

@@ -43,6 +43,7 @@ from vclient.models import (
     Note,
     Quickroll,
     RollStatistics,
+    ServerLogEntry,
     SheetSection,
     SystemHealth,
     Trait,
@@ -89,6 +90,7 @@ from vclient.testing._factories import (
     NoteFactory,
     QuickrollFactory,
     RollStatisticsFactory,
+    ServerLogEntryFactory,
     SheetSectionFactory,
     SystemHealthFactory,
     TraitCategoryFactory,
@@ -101,7 +103,7 @@ from vclient.testing._factories import (
     WerewolfAuspiceFactory,
     WerewolfTribeFactory,
 )
-from vclient.testing._routes import LIST, NO_CONTENT, PAGINATED, RAW_JSON, Routes, RouteSpec
+from vclient.testing._routes import BYTES, LIST, NO_CONTENT, PAGINATED, RAW_JSON, Routes, RouteSpec
 
 _FACTORY_MAP: dict[type, type[ModelFactory]] = {
     AuditLog: AuditLogFactory,
@@ -135,6 +137,7 @@ _FACTORY_MAP: dict[type, type[ModelFactory]] = {
     Note: NoteFactory,
     Quickroll: QuickrollFactory,
     RollStatistics: RollStatisticsFactory,
+    ServerLogEntry: ServerLogEntryFactory,
     SheetSection: SheetSectionFactory,
     SystemHealth: SystemHealthFactory,
     Trait: TraitFactory,
@@ -208,7 +211,7 @@ class _Route:
 
         return True
 
-    def respond(self) -> httpx.Response:
+    def respond(self) -> httpx.Response:  # noqa: PLR0911
         """Generate an httpx.Response for this route."""
         if self.override_json is not None:
             return httpx.Response(
@@ -222,6 +225,13 @@ class _Route:
         if self.style == RAW_JSON:
             return httpx.Response(status_code=200, json={})
 
+        if self.style == BYTES:
+            return httpx.Response(
+                status_code=200,
+                content=b"PK\x03\x04fake-log-archive",
+                headers={"Content-Disposition": 'attachment; filename="vapi-logs-fake.zip"'},
+            )
+
         if self.model_class is None:
             msg = f"model_class required for style {self.style}"
             raise RuntimeError(msg)

{valentina_python_client-2.1.0 → valentina_python_client-2.2.0}/src/vclient/testing/_routes.py

@@ -34,6 +34,7 @@ from vclient.models import (
     Note,
     Quickroll,
     RollStatistics,
+    ServerLogEntry,
     SheetSection,
     SystemHealth,
     Trait,
@@ -55,6 +56,7 @@ SINGLE = "single"
 NO_CONTENT = "no_content"
 RAW_JSON = "raw_json"
 LIST = "list"
+BYTES = "bytes"
 
 
 class RouteSpec(NamedTuple):
@@ -63,9 +65,9 @@ class RouteSpec(NamedTuple):
     Attributes:
         method: HTTP method (GET, POST, PATCH, PUT, DELETE).
         pattern: Endpoint URL pattern from the Endpoints class.
-        style: Response style — one of PAGINATED, SINGLE, LIST, NO_CONTENT, or RAW_JSON.
+        style: Response style: one of PAGINATED, SINGLE, LIST, NO_CONTENT, RAW_JSON, or BYTES.
         model_class: The Pydantic model class used for auto-generating responses,
-            or None for NO_CONTENT and RAW_JSON routes.
+            or None for NO_CONTENT, RAW_JSON, and BYTES routes.
     """
 
     method: str
@@ -107,6 +109,8 @@ class Routes:
     ADMIN_DEVELOPER_AUDIT_LOGS_LIST = RouteSpec(
         "GET", Endpoints.ADMIN_DEVELOPER_AUDIT_LOGS, PAGINATED, AuditLog
     )
+    ADMIN_LOGS_TAIL = RouteSpec("GET", Endpoints.ADMIN_LOGS, LIST, ServerLogEntry)
+    ADMIN_LOGS_DOWNLOAD = RouteSpec("GET", Endpoints.ADMIN_LOGS_DOWNLOAD, BYTES, None)
 
     # Developer self-service
     DEVELOPERS_ME_GET = RouteSpec("GET", Endpoints.DEVELOPER_ME, SINGLE, MeDeveloper)