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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 2.0.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>
@@ -15,11 +15,11 @@ License: MIT License
          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: anyio>=4.13.0
+Requires-Dist: anyio>=4.13.0,<5.0.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: loguru>=0.7.3
-Requires-Dist: polyfactory>=3.3.0
-Requires-Dist: pydantic[email]>=2.13.1
+Requires-Dist: polyfactory>=3.3.0,<4.0.0
+Requires-Dist: pydantic[email]>=2.13.4,<3.0.0
 Requires-Dist: polyfactory>=3.3.0 ; extra == 'testing'
 Requires-Python: >=3.13
 Project-URL: Homepage, https://docs.valentina-noir.com/python-api-client/

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

@@ -5,18 +5,18 @@
         "Programming Language :: Python :: 3.14",
     ]
     dependencies = [
-        "anyio>=4.13.0",
+        "anyio>=4.13.0, <5.0.0",
         "httpx>=0.28.1",
         "loguru>=0.7.3",
-        "polyfactory>=3.3.0",
-        "pydantic[email]>=2.13.1",
+        "polyfactory>=3.3.0, <4.0.0",
+        "pydantic[email]>=2.13.4, <3.0.0",
     ]
     description = "Async Python client library for the Valentina Noir API"
     license = { file = "LICENSE" }
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "2.0.0"
+    version = "2.2.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]
@@ -27,35 +27,35 @@
 
 [build-system]
     build-backend = "uv_build"
-    requires      = ["uv_build>=0.9.26,<0.10.0"]
+    requires      = ["uv_build>=0.11.15,<0.12.0"]
 
 [tool.uv.build-backend]
     module-name = "vclient"
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.13.10",
-        "coverage>=7.13.5",
+        "commitizen>=4.16.2",
+        "coverage>=7.14.0",
         "duty>=1.9.0",
-        "prek>=0.3.9",
+        "prek>=0.4.1",
         "pytest-anyio>=0.0.0",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
-        "pytest-devtools>=1.0.0",
+        "pytest-devtools>=1.2.0",
         "pytest-mock>=3.15.1",
         "pytest-repeat>=0.9.4",
         "pytest-sugar>=1.1.1",
         "pytest-xdist>=3.8.0",
         "pytest>=9.0.3",
         "respx>=0.23.1",
-        "ruff>=0.15.10",
+        "ruff>=0.15.14",
         "shellcheck-py>=0.11.0.1",
-        "ty>=0.0.31",
-        "typos>=1.45.1",
+        "ty>=0.0.39",
+        "typos>=1.46.2",
         "vulture>=2.16",
         "yamllint>=1.38.0",
     ]
-    docs = ["zensical>=0.0.33"]
+    docs = ["zensical>=0.0.43"]
 
 [tool.commitizen]
     bump_message               = "bump(release): v$current_version → v$new_version"

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

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

{valentina_python_client-2.0.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.0.0 → valentina_python_client-2.2.0}/src/vclient/_sync/services/dicerolls.py

@@ -5,7 +5,7 @@ from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 from vclient._sync.services.base import SyncBaseService
-from vclient.constants import DEFAULT_PAGE_LIMIT
+from vclient.constants import DEFAULT_PAGE_LIMIT, CharacterType
 from vclient.endpoints import Endpoints
 from vclient.models import Diceroll, DicerollCreate, PaginatedResponse, _DicerollQuickrollCreate
 
@@ -40,15 +40,32 @@ class SyncDicerollService(SyncBaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
     ) -> PaginatedResponse[Diceroll]:
-        """Retrieve a paginated page of dice rolls."""
+        """Retrieve a paginated page of dice rolls.
+
+        Args:
+            limit: Maximum number of items to return (0-100, default 10).
+            offset: Number of items to skip from the beginning (default 0).
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+
+        Returns:
+            A PaginatedResponse containing Diceroll objects and pagination metadata.
+        """
         return self._get_paginated_as(
             self._format_endpoint(Endpoints.DICEROLLS),
             Diceroll,
             limit=limit,
             offset=offset,
             params=self._build_params(
-                userid=userid, characterid=characterid, campaignid=campaignid
+                userid=userid,
+                characterid=characterid,
+                campaignid=campaignid,
+                character_type=character_type,
             ),
         )
 
@@ -58,12 +75,27 @@ class SyncDicerollService(SyncBaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
     ) -> list[Diceroll]:
-        """Retrieve all dice rolls."""
+        """Retrieve all dice rolls.
+
+        Args:
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+
+        Returns:
+            A list of all Diceroll objects.
+        """
         return [
             diceroll
             for diceroll in self.iter_all(
-                userid=userid, characterid=characterid, campaignid=campaignid
+                userid=userid,
+                characterid=characterid,
+                campaignid=campaignid,
+                character_type=character_type,
             )
         ]
 
@@ -73,14 +105,30 @@ class SyncDicerollService(SyncBaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
         limit: int = 100,
     ) -> Iterator[Diceroll]:
-        """Iterate through all dice rolls."""
+        """Iterate through all dice rolls.
+
+        Args:
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+            limit: Items per page (default 100 for efficiency).
+
+        Yields:
+            Individual Diceroll objects.
+        """
         for item in self._iter_all_pages(
             self._format_endpoint(Endpoints.DICEROLLS),
             limit=limit,
             params=self._build_params(
-                userid=userid, characterid=characterid, campaignid=campaignid
+                userid=userid,
+                characterid=characterid,
+                campaignid=campaignid,
+                character_type=character_type,
             ),
         ):
             yield Diceroll.model_validate(item)

{valentina_python_client-2.0.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.0.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.0.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.0.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.0.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.0.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.0.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.0.0 → valentina_python_client-2.2.0}/src/vclient/services/dicerolls.py

@@ -3,7 +3,7 @@
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING
 
-from vclient.constants import DEFAULT_PAGE_LIMIT
+from vclient.constants import DEFAULT_PAGE_LIMIT, CharacterType
 from vclient.endpoints import Endpoints
 from vclient.models import (
     Diceroll,
@@ -48,8 +48,22 @@ class DicerollService(BaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
     ) -> PaginatedResponse[Diceroll]:
-        """Retrieve a paginated page of dice rolls."""
+        """Retrieve a paginated page of dice rolls.
+
+        Args:
+            limit: Maximum number of items to return (0-100, default 10).
+            offset: Number of items to skip from the beginning (default 0).
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+
+        Returns:
+            A PaginatedResponse containing Diceroll objects and pagination metadata.
+        """
         return await self._get_paginated_as(
             self._format_endpoint(Endpoints.DICEROLLS),
             Diceroll,
@@ -59,6 +73,7 @@ class DicerollService(BaseService):
                 userid=userid,
                 characterid=characterid,
                 campaignid=campaignid,
+                character_type=character_type,
             ),
         )
 
@@ -68,12 +83,27 @@ class DicerollService(BaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
     ) -> list[Diceroll]:
-        """Retrieve all dice rolls."""
+        """Retrieve all dice rolls.
+
+        Args:
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+
+        Returns:
+            A list of all Diceroll objects.
+        """
         return [
             diceroll
             async for diceroll in self.iter_all(
-                userid=userid, characterid=characterid, campaignid=campaignid
+                userid=userid,
+                characterid=characterid,
+                campaignid=campaignid,
+                character_type=character_type,
             )
         ]
 
@@ -83,9 +113,22 @@ class DicerollService(BaseService):
         userid: str | None = None,
         characterid: str | None = None,
         campaignid: str | None = None,
+        character_type: CharacterType | None = None,
         limit: int = 100,
     ) -> AsyncIterator[Diceroll]:
-        """Iterate through all dice rolls."""
+        """Iterate through all dice rolls.
+
+        Args:
+            userid: Filter by user ID.
+            characterid: Filter by character ID.
+            campaignid: Filter by campaign ID.
+            character_type: Filter by the associated character's type. Rolls with
+                no character are excluded when this filter is set.
+            limit: Items per page (default 100 for efficiency).
+
+        Yields:
+            Individual Diceroll objects.
+        """
         async for item in self._iter_all_pages(
             self._format_endpoint(Endpoints.DICEROLLS),
             limit=limit,
@@ -93,6 +136,7 @@ class DicerollService(BaseService):
                 userid=userid,
                 characterid=characterid,
                 campaignid=campaignid,
+                character_type=character_type,
             ),
         ):
             yield Diceroll.model_validate(item)

{valentina_python_client-2.0.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.0.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.0.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.0.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.0.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)