valentina-python-client 1.21.0__tar.gz → 1.22.0__tar.gz

{valentina_python_client-1.21.0 → valentina_python_client-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 1.21.0
+Version: 1.22.0
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -47,6 +47,18 @@ This client is a supported and up-to-date reference implementation for the [Vale
 
 The full documentation is available at https://natelandau.github.io/valentina-python-client/.
 
+## Claude Code Skill
+
+This repo includes a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that gives Claude deep knowledge of vclient's services, models, constants, and testing utilities. Install it so Claude can help you build applications against the Valentina API.
+
+### Install
+
+```bash
+claude install-skill /path/to/valentina-python-client/vclient-guide-skill
+```
+
+Once installed, Claude will automatically activate the skill when you're working with vclient imports, Valentina API endpoints, or FakeVClient testing.
+
 ## Development Tools
 
 ### Validate Constants

{valentina_python_client-1.21.0 → valentina_python_client-1.22.0}/README.md

@@ -18,6 +18,18 @@ This client is a supported and up-to-date reference implementation for the [Vale
 
 The full documentation is available at https://natelandau.github.io/valentina-python-client/.
 
+## Claude Code Skill
+
+This repo includes a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that gives Claude deep knowledge of vclient's services, models, constants, and testing utilities. Install it so Claude can help you build applications against the Valentina API.
+
+### Install
+
+```bash
+claude install-skill /path/to/valentina-python-client/vclient-guide-skill
+```
+
+Once installed, Claude will automatically activate the skill when you're working with vclient imports, Valentina API endpoints, or FakeVClient testing.
+
 ## Development Tools
 
 ### Validate Constants

{valentina_python_client-1.21.0 → valentina_python_client-1.22.0}/pyproject.toml

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

{valentina_python_client-1.21.0 → valentina_python_client-1.22.0}/src/vclient/__init__.py

@@ -109,4 +109,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "1.21.0"
+__version__ = "1.22.0"

valentina_python_client-1.22.0/src/vclient/_sync/services/_audit_params.py

@@ -0,0 +1,63 @@
+# AUTO-GENERATED — do not edit. Run 'uv run duty generate_sync' to regenerate.
+"""Shared query parameter builder for audit log endpoints."""
+
+from collections.abc import Sequence
+from datetime import datetime
+
+
+def _build_audit_params(
+    *,
+    acting_user_id: str | None = None,
+    user_id: str | None = None,
+    campaign_id: str | None = None,
+    book_id: str | None = None,
+    chapter_id: str | None = None,
+    character_id: str | None = None,
+    entity_type: str | None = None,
+    operation: str | None = None,
+    date_from: datetime | None = None,
+    date_to: datetime | None = None,
+    include: Sequence[str] | None = None,
+    company_id: str | None = None,
+) -> dict[str, str]:
+    """Build query parameter dict from audit log filter kwargs.
+
+    Only include non-None values. Serialize datetimes to ISO 8601 and
+    join include lists with commas.
+
+    Args:
+        acting_user_id: Filter by the user who performed the action.
+        user_id: Filter by the user affected by the action.
+        campaign_id: Filter by campaign ID.
+        book_id: Filter by book ID.
+        chapter_id: Filter by chapter ID.
+        character_id: Filter by character ID.
+        entity_type: Filter by entity type (e.g., "CAMPAIGN", "CHARACTER").
+        operation: Filter by operation type (CREATE, UPDATE, DELETE).
+        date_from: Return logs on or after this datetime (ISO 8601 serialized).
+        date_to: Return logs on or before this datetime (ISO 8601 serialized).
+        include: Additional data to include (e.g., ("request_details",)).
+        company_id: Filter by company ID (used for global admin endpoint).
+
+    Returns:
+        A dict of query parameters with only non-None values included.
+    """
+    string_params: dict[str, str | None] = {
+        "acting_user_id": acting_user_id,
+        "user_id": user_id,
+        "campaign_id": campaign_id,
+        "book_id": book_id,
+        "chapter_id": chapter_id,
+        "character_id": character_id,
+        "entity_type": entity_type,
+        "operation": operation,
+        "company_id": company_id,
+    }
+    params: dict[str, str] = {k: v for k, v in string_params.items() if v is not None}
+    if date_from is not None:
+        params["date_from"] = date_from.isoformat()
+    if date_to is not None:
+        params["date_to"] = date_to.isoformat()
+    if include is not None:
+        params["include"] = ",".join(include)
+    return params

{valentina_python_client-1.21.0 → valentina_python_client-1.22.0}/src/vclient/_sync/services/companies.py

@@ -1,12 +1,21 @@
 # AUTO-GENERATED — do not edit. Run 'uv run duty generate_sync' to regenerate.
 """Service for interacting with the Companies API."""
 
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
+from datetime import datetime
 
 from vclient._sync.services.base import SyncBaseService
-from vclient.constants import DEFAULT_PAGE_LIMIT, PermissionLevel
+from vclient.constants import (
+    DEFAULT_PAGE_LIMIT,
+    AuditEntityType,
+    AuditLogInclude,
+    AuditOperation,
+    PermissionLevel,
+)
 from vclient.endpoints import Endpoints
 from vclient.models import (
+    AuditLog,
+    AuditLogDetail,
     Company,
     CompanyCreate,
     CompanyPermissions,
@@ -16,6 +25,7 @@ from vclient.models import (
     RollStatistics,
     _GrantAccess,
 )
+from vclient.services._audit_params import _build_audit_params
 
 
 class SyncCompaniesService(SyncBaseService):
@@ -216,3 +226,195 @@ class SyncCompaniesService(SyncBaseService):
             params={"num_top_traits": num_top_traits},
         )
         return RollStatistics.model_validate(response.json())
+
+    def get_audit_log_page(
+        self,
+        company_id: str,
+        *,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        offset: int = 0,
+        acting_user_id: str | None = None,
+        user_id: str | None = None,
+        campaign_id: str | None = None,
+        book_id: str | None = None,
+        chapter_id: str | None = None,
+        character_id: str | None = None,
+        entity_type: AuditEntityType | None = None,
+        operation: AuditOperation | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+        include: Sequence[AuditLogInclude] | None = None,
+    ) -> PaginatedResponse[AuditLog] | PaginatedResponse[AuditLogDetail]:
+        """Retrieve a paginated page of audit log entries for a company.
+
+        Use filter parameters to narrow results by entity, operation, user, or time range.
+        Pass ``include=["request_details"]`` to receive full HTTP request forensics in each
+        entry (returns AuditLogDetail instead of AuditLog).
+
+        Args:
+            company_id: The ID of the company whose audit logs to retrieve.
+            limit: Maximum number of items to return (0-100, default 10).
+            offset: Number of items to skip from the beginning (default 0).
+            acting_user_id: Filter by the user who performed the action.
+            user_id: Filter by the user affected by the action.
+            campaign_id: Filter by campaign ID.
+            book_id: Filter by book ID.
+            chapter_id: Filter by chapter ID.
+            character_id: Filter by character ID.
+            entity_type: Filter by entity type (e.g., "CAMPAIGN", "CHARACTER").
+            operation: Filter by operation type (CREATE, UPDATE, DELETE).
+            date_from: Return logs on or after this datetime.
+            date_to: Return logs on or before this datetime.
+            include: Additional data to include. Pass ["request_details"] for HTTP forensics.
+
+        Returns:
+            A PaginatedResponse containing AuditLog (or AuditLogDetail) objects.
+
+        Raises:
+            NotFoundError: If the company does not exist.
+            AuthorizationError: If you don't have access to the company.
+        """
+        model = AuditLogDetail if include and "request_details" in include else AuditLog
+        params = _build_audit_params(
+            acting_user_id=acting_user_id,
+            user_id=user_id,
+            campaign_id=campaign_id,
+            book_id=book_id,
+            chapter_id=chapter_id,
+            character_id=character_id,
+            entity_type=entity_type,
+            operation=operation,
+            date_from=date_from,
+            date_to=date_to,
+            include=include,
+        )
+        return self._get_paginated_as(
+            Endpoints.COMPANY_AUDIT_LOGS.format(company_id=company_id),
+            model,
+            limit=limit,
+            offset=offset,
+            params=params,
+        )
+
+    def list_all_audit_logs(
+        self,
+        company_id: str,
+        *,
+        acting_user_id: str | None = None,
+        user_id: str | None = None,
+        campaign_id: str | None = None,
+        book_id: str | None = None,
+        chapter_id: str | None = None,
+        character_id: str | None = None,
+        entity_type: AuditEntityType | None = None,
+        operation: AuditOperation | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+        include: Sequence[AuditLogInclude] | None = None,
+    ) -> list[AuditLog] | list[AuditLogDetail]:
+        """Retrieve all audit log entries for a company.
+
+        Automatically paginates through all results. Use ``get_audit_log_page()`` for
+        paginated access or ``iter_all_audit_logs()`` for memory-efficient streaming.
+
+        Args:
+            company_id: The ID of the company whose audit logs to retrieve.
+            acting_user_id: Filter by the user who performed the action.
+            user_id: Filter by the user affected by the action.
+            campaign_id: Filter by campaign ID.
+            book_id: Filter by book ID.
+            chapter_id: Filter by chapter ID.
+            character_id: Filter by character ID.
+            entity_type: Filter by entity type (e.g., "CAMPAIGN", "CHARACTER").
+            operation: Filter by operation type (CREATE, UPDATE, DELETE).
+            date_from: Return logs on or after this datetime.
+            date_to: Return logs on or before this datetime.
+            include: Additional data to include. Pass ["request_details"] for HTTP forensics.
+
+        Returns:
+            A list of all AuditLog (or AuditLogDetail) objects.
+
+        Raises:
+            NotFoundError: If the company does not exist.
+            AuthorizationError: If you don't have access to the company.
+        """
+        return [
+            log
+            for log in self.iter_all_audit_logs(
+                company_id,
+                acting_user_id=acting_user_id,
+                user_id=user_id,
+                campaign_id=campaign_id,
+                book_id=book_id,
+                chapter_id=chapter_id,
+                character_id=character_id,
+                entity_type=entity_type,
+                operation=operation,
+                date_from=date_from,
+                date_to=date_to,
+                include=include,
+            )
+        ]
+
+    def iter_all_audit_logs(
+        self,
+        company_id: str,
+        *,
+        limit: int = 100,
+        acting_user_id: str | None = None,
+        user_id: str | None = None,
+        campaign_id: str | None = None,
+        book_id: str | None = None,
+        chapter_id: str | None = None,
+        character_id: str | None = None,
+        entity_type: AuditEntityType | None = None,
+        operation: AuditOperation | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+        include: Sequence[AuditLogInclude] | None = None,
+    ) -> Iterator[AuditLog] | Iterator[AuditLogDetail]:
+        """Iterate through all audit log entries for a company.
+
+        Yields individual audit log entries, automatically fetching subsequent pages
+        until all matching entries have been retrieved.
+
+        Args:
+            company_id: The ID of the company whose audit logs to retrieve.
+            limit: Items per page (default 100 for efficiency).
+            acting_user_id: Filter by the user who performed the action.
+            user_id: Filter by the user affected by the action.
+            campaign_id: Filter by campaign ID.
+            book_id: Filter by book ID.
+            chapter_id: Filter by chapter ID.
+            character_id: Filter by character ID.
+            entity_type: Filter by entity type (e.g., "CAMPAIGN", "CHARACTER").
+            operation: Filter by operation type (CREATE, UPDATE, DELETE).
+            date_from: Return logs on or after this datetime.
+            date_to: Return logs on or before this datetime.
+            include: Additional data to include. Pass ["request_details"] for HTTP forensics.
+
+        Yields:
+            Individual AuditLog (or AuditLogDetail) objects.
+
+        Raises:
+            NotFoundError: If the company does not exist.
+            AuthorizationError: If you don't have access to the company.
+        """
+        model = AuditLogDetail if include and "request_details" in include else AuditLog
+        params = _build_audit_params(
+            acting_user_id=acting_user_id,
+            user_id=user_id,
+            campaign_id=campaign_id,
+            book_id=book_id,
+            chapter_id=chapter_id,
+            character_id=character_id,
+            entity_type=entity_type,
+            operation=operation,
+            date_from=date_from,
+            date_to=date_to,
+            include=include,
+        )
+        for item in self._iter_all_pages(
+            Endpoints.COMPANY_AUDIT_LOGS.format(company_id=company_id), limit=limit, params=params
+        ):
+            yield model.model_validate(item)