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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 1.20.1
+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.20.1 → 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.20.1 → 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.20.1"
+    version = "1.22.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]

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

@@ -49,6 +49,7 @@ from vclient._sync import (  # noqa: E402
     sync_global_admin_service,
     sync_options_service,
     sync_system_service,
+    sync_user_lookup_service,
     sync_users_service,
 )
 from vclient.client import VClient  # noqa: E402
@@ -67,6 +68,7 @@ from vclient.registry import (  # noqa: E402
     global_admin_service,
     options_service,
     system_service,
+    user_lookup_service,
     users_service,
 )
 
@@ -100,9 +102,11 @@ __all__ = (
     "sync_global_admin_service",
     "sync_options_service",
     "sync_system_service",
+    "sync_user_lookup_service",
     "sync_users_service",
     "system_service",
+    "user_lookup_service",
     "users_service",
 )
 
-__version__ = "1.20.1"
+__version__ = "1.22.0"

{valentina_python_client-1.20.1 → valentina_python_client-1.22.0}/src/vclient/_codegen.py

@@ -28,6 +28,7 @@ RENAME_CLASSES: dict[str, str] = {
     "GlobalAdminService": "SyncGlobalAdminService",
     "OptionsService": "SyncOptionsService",
     "SystemService": "SyncSystemService",
+    "UserLookupService": "SyncUserLookupService",
     "UsersService": "SyncUsersService",
     "VClient": "SyncVClient",
     "FakeVClient": "SyncFakeVClient",
@@ -49,6 +50,7 @@ FACTORY_RENAMES: dict[str, str] = {
     "dicerolls_service": "sync_dicerolls_service",
     "options_service": "sync_options_service",
     "character_autogen_service": "sync_character_autogen_service",
+    "user_lookup_service": "sync_user_lookup_service",
     "configure_default_client": "sync_configure_default_client",
     "clear_default_client": "sync_clear_default_client",
     "default_client": "sync_default_client",
@@ -73,6 +75,7 @@ IMPORT_REWRITES: dict[str, str] = {
     "vclient.services.dicerolls": "vclient._sync.services.dicerolls",
     "vclient.services.options": "vclient._sync.services.options",
     "vclient.services.character_autogen": "vclient._sync.services.character_autogen",
+    "vclient.services.user_lookup": "vclient._sync.services.user_lookup",
     "vclient.registry": "vclient._sync.registry",
     "vclient.testing._client": "vclient._sync.testing._client",
 }
@@ -307,6 +310,7 @@ def _write_sync_init(path: Path) -> None:
         "    sync_global_admin_service,",
         "    sync_options_service,",
         "    sync_system_service,",
+        "    sync_user_lookup_service,",
         "    sync_users_service,",
         ")",
         "",
@@ -329,6 +333,7 @@ def _write_sync_init(path: Path) -> None:
         '    "sync_global_admin_service",',
         '    "sync_options_service",',
         '    "sync_system_service",',
+        '    "sync_user_lookup_service",',
         '    "sync_users_service",',
         "]",
         "",

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

@@ -19,6 +19,7 @@ from vclient._sync.registry import (
     sync_global_admin_service,
     sync_options_service,
     sync_system_service,
+    sync_user_lookup_service,
     sync_users_service,
 )
 
@@ -41,5 +42,6 @@ __all__ = [
     "sync_global_admin_service",
     "sync_options_service",
     "sync_system_service",
+    "sync_user_lookup_service",
     "sync_users_service",
 ]

{valentina_python_client-1.20.1 → valentina_python_client-1.22.0}/src/vclient/_sync/client.py

@@ -37,6 +37,7 @@ if TYPE_CHECKING:
         SyncGlobalAdminService,
         SyncOptionsService,
         SyncSystemService,
+        SyncUserLookupService,
         SyncUsersService,
     )
 
@@ -147,6 +148,7 @@ class SyncVClient:
         self._developer: SyncDeveloperService | None = None
         self._global_admin: SyncGlobalAdminService | None = None
         self._system: SyncSystemService | None = None
+        self._user_lookup: SyncUserLookupService | None = None
         if set_as_default:
             from vclient._sync.registry import sync_configure_default_client
 
@@ -278,6 +280,19 @@ class SyncVClient:
             self._system = SyncSystemService(self)
         return self._system
 
+    @property
+    def user_lookup(self) -> "SyncUserLookupService":
+        """Access the User Lookup service for cross-company user discovery.
+
+        Returns:
+            The SyncUserLookupService instance for user lookup operations.
+        """
+        if self._user_lookup is None:
+            from vclient._sync.services.user_lookup import SyncUserLookupService
+
+            self._user_lookup = SyncUserLookupService(self)
+        return self._user_lookup
+
     def users(self, company_id: str | None = None) -> "SyncUsersService":
         """Get a SyncUsersService scoped to a specific company.
 

{valentina_python_client-1.20.1 → valentina_python_client-1.22.0}/src/vclient/_sync/registry.py

@@ -38,6 +38,7 @@ if TYPE_CHECKING:
         SyncGlobalAdminService,
         SyncOptionsService,
         SyncSystemService,
+        SyncUserLookupService,
         SyncUsersService,
     )
 _default_client: "SyncVClient | None" = None
@@ -189,6 +190,29 @@ def sync_system_service() -> "SyncSystemService":
     return SyncSystemService(sync_default_client())
 
 
+def sync_user_lookup_service() -> "SyncUserLookupService":
+    """Create a SyncUserLookupService using the default client.
+
+    Discover which companies a person has a user record in by searching
+    via email, Discord ID, Google ID, or GitHub ID.
+
+    Returns:
+        SyncUserLookupService: A service instance for cross-company user lookup.
+
+    Raises:
+        RuntimeError: If no default client has been configured.
+
+    Example:
+        ```python
+        lookup = sync_user_lookup_service()
+        results = await lookup.by_email("alice@example.com")
+        ```
+    """
+    from vclient._sync.services.user_lookup import SyncUserLookupService
+
+    return SyncUserLookupService(sync_default_client())
+
+
 def sync_users_service(company_id: str | None = None) -> "SyncUsersService":
     """Create a SyncUsersService scoped to a specific company using the default client.
 

{valentina_python_client-1.20.1 → valentina_python_client-1.22.0}/src/vclient/_sync/services/__init__.py

@@ -16,6 +16,7 @@ from .dictionary import SyncDictionaryService
 from .global_admin import SyncGlobalAdminService
 from .options import SyncOptionsService
 from .system import SyncSystemService
+from .user_lookup import SyncUserLookupService
 from .users import SyncUsersService
 
 __all__ = [
@@ -34,5 +35,6 @@ __all__ = [
     "SyncGlobalAdminService",
     "SyncOptionsService",
     "SyncSystemService",
+    "SyncUserLookupService",
     "SyncUsersService",
 ]

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.20.1 → 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)