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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 2.2.0
+Version: 2.4.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.2.0 → valentina_python_client-2.4.0}/pyproject.toml

@@ -16,7 +16,7 @@
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "2.2.0"
+    version = "2.4.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]
@@ -34,10 +34,10 @@
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.16.2",
-        "coverage>=7.14.0",
+        "commitizen>=4.16.3",
+        "coverage>=7.14.1",
         "duty>=1.9.0",
-        "prek>=0.4.1",
+        "prek>=0.4.3",
         "pytest-anyio>=0.0.0",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
@@ -48,10 +48,10 @@
         "pytest-xdist>=3.8.0",
         "pytest>=9.0.3",
         "respx>=0.23.1",
-        "ruff>=0.15.14",
+        "ruff>=0.15.15",
         "shellcheck-py>=0.11.0.1",
-        "ty>=0.0.39",
-        "typos>=1.46.2",
+        "ty>=0.0.42",
+        "typos>=1.47.0",
         "vulture>=2.16",
         "yamllint>=1.38.0",
     ]

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

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

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/_sync/registry.py

@@ -160,7 +160,7 @@ def sync_global_admin_service() -> "SyncGlobalAdminService":
     Example:
         ```python
         admins = sync_global_admin_service()
-        developers = await admins.list_all()
+        developers = await admins.list_all_developers()
         ```
     """
     from vclient._sync.services.global_admin import SyncGlobalAdminService

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

@@ -15,9 +15,13 @@ from vclient.constants import (
     AuditLogInclude,
     AuditOperation,
     LogLevel,
+    UserRole,
 )
 from vclient.endpoints import Endpoints
 from vclient.models import (
+    AdminUser,
+    AdminUserCreate,
+    AdminUserUpdate,
     AuditLog,
     AuditLogDetail,
     Developer,
@@ -57,16 +61,16 @@ def _filename_from_content_disposition(header: str | None, *, fallback: str) ->
 class SyncGlobalAdminService(SyncBaseService):
     """Service for global admin operations in the Valentina API.
 
-    Provides methods to create, retrieve, update, and delete developer accounts,
-    as well as manage API keys. Requires global admin privileges.
+    Provides cross-company management of developer accounts and their API keys,
+    plus server log access. Requires global admin privileges.
 
     Example:
         >>> async with SyncVClient() as client:
-        ...     developers = await client.global_admin.list_all()
-        ...     developer = await client.global_admin.get("developer_id")
+        ...     developers = await client.global_admin.list_all_developers()
+        ...     developer = await client.global_admin.get_developer("developer_id")
     """
 
-    def get_page(
+    def get_developer_page(
         self,
         *,
         limit: int = DEFAULT_PAGE_LIMIT,
@@ -90,11 +94,11 @@ class SyncGlobalAdminService(SyncBaseService):
             Endpoints.ADMIN_DEVELOPERS, Developer, limit=limit, offset=offset, params=params
         )
 
-    def list_all(self, *, is_global_admin: bool | None = None) -> list[Developer]:
+    def list_all_developers(self, *, is_global_admin: bool | None = None) -> list[Developer]:
         """Retrieve all developer accounts.
 
-        Automatically paginates through all results. Use `get_page()` for paginated access
-        or `iter_all()` for memory-efficient streaming of large datasets.
+        Automatically paginates through all results. Use `get_developer_page()` for paginated
+        access or `iter_all_developers()` for memory-efficient streaming of large datasets.
 
         Args:
             is_global_admin: Optional filter by global admin status.
@@ -102,9 +106,11 @@ class SyncGlobalAdminService(SyncBaseService):
         Returns:
             A list of all Developer objects.
         """
-        return [developer for developer in self.iter_all(is_global_admin=is_global_admin)]
+        return [
+            developer for developer in self.iter_all_developers(is_global_admin=is_global_admin)
+        ]
 
-    def iter_all(
+    def iter_all_developers(
         self, *, limit: int = 100, is_global_admin: bool | None = None
     ) -> Iterator[Developer]:
         """Iterate through all developer accounts.
@@ -120,18 +126,14 @@ class SyncGlobalAdminService(SyncBaseService):
             Individual Developer objects.
 
         Example:
-            >>> async for developer in client.global_admin.iter_all():
+            >>> async for developer in client.global_admin.iter_all_developers():
             ...     print(developer.username)
         """
-        params = {}
-        if is_global_admin is not None:
-            params["is_global_admin"] = is_global_admin
-        for item in self._iter_all_pages(
-            Endpoints.ADMIN_DEVELOPERS, limit=limit, params=params or None
-        ):
+        params = self._build_params(is_global_admin=is_global_admin)
+        for item in self._iter_all_pages(Endpoints.ADMIN_DEVELOPERS, limit=limit, params=params):
             yield Developer.model_validate(item)
 
-    def get(self, developer_id: str) -> Developer:
+    def get_developer(self, developer_id: str) -> Developer:
         """Retrieve detailed information about a specific developer.
 
         Args:
@@ -147,7 +149,7 @@ class SyncGlobalAdminService(SyncBaseService):
         response = self._get(Endpoints.ADMIN_DEVELOPER.format(developer_id=developer_id))
         return Developer.model_validate(response.json())
 
-    def create(self, request: DeveloperCreate | None = None, **kwargs) -> Developer:
+    def create_developer(self, request: DeveloperCreate | None = None, **kwargs) -> Developer:
         """Create a new developer account.
 
         This creates the account but does not create an API key or grant access to any
@@ -174,7 +176,7 @@ class SyncGlobalAdminService(SyncBaseService):
         )
         return Developer.model_validate(response.json())
 
-    def update(
+    def update_developer(
         self, developer_id: str, request: DeveloperUpdate | None = None, **kwargs
     ) -> Developer:
         """Modify a developer account's properties.
@@ -204,7 +206,7 @@ class SyncGlobalAdminService(SyncBaseService):
         )
         return Developer.model_validate(response.json())
 
-    def delete(self, developer_id: str) -> None:
+    def delete_developer(self, developer_id: str) -> None:
         """Remove a developer account from the system.
 
         The developer's API key will be invalidated immediately.
@@ -218,6 +220,165 @@ class SyncGlobalAdminService(SyncBaseService):
         """
         self._delete(Endpoints.ADMIN_DEVELOPER.format(developer_id=developer_id))
 
+    def get_user_page(
+        self,
+        *,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        offset: int = 0,
+    ) -> PaginatedResponse[AdminUser]:
+        """Retrieve a paginated page of users across all companies.
+
+        Authenticates with the global-admin API key only; no On-Behalf-Of header
+        is sent. Archived (soft-deleted) users are included when
+        ``is_archived=True``.
+
+        Args:
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+            limit: Maximum number of items to return (0-100, default 10).
+            offset: Number of items to skip from the beginning (default 0).
+
+        Returns:
+            A PaginatedResponse containing AdminUser objects and pagination metadata.
+        """
+        params = self._build_params(
+            company_id=company_id, role=role, email=email, is_archived=is_archived
+        )
+        return self._get_paginated_as(
+            Endpoints.ADMIN_USERS, AdminUser, limit=limit, offset=offset, params=params
+        )
+
+    def list_all_users(
+        self,
+        *,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+    ) -> list[AdminUser]:
+        """Retrieve all users across all companies.
+
+        Automatically paginates through all results. Use ``get_user_page()`` for
+        paginated access or ``iter_all_users()`` for memory-efficient streaming.
+
+        Args:
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+
+        Returns:
+            A list of all matching AdminUser objects.
+        """
+        return [
+            user
+            for user in self.iter_all_users(
+                company_id=company_id, role=role, email=email, is_archived=is_archived
+            )
+        ]
+
+    def iter_all_users(
+        self,
+        *,
+        limit: int = 100,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+    ) -> Iterator[AdminUser]:
+        """Iterate through all users across all companies.
+
+        Yields individual users, automatically fetching subsequent pages until all
+        matching users have been retrieved.
+
+        Args:
+            limit: Items per page (default 100 for efficiency).
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+
+        Yields:
+            Individual AdminUser objects.
+        """
+        params = self._build_params(
+            company_id=company_id, role=role, email=email, is_archived=is_archived
+        )
+        for item in self._iter_all_pages(Endpoints.ADMIN_USERS, limit=limit, params=params):
+            yield AdminUser.model_validate(item)
+
+    def get_user(self, user_id: str) -> AdminUser:
+        """Retrieve a single user by ID, including archived users.
+
+        Args:
+            user_id: The ID of the user to retrieve.
+
+        Returns:
+            The AdminUser object, with ``is_archived`` reflecting soft-delete state.
+        """
+        response = self._get(Endpoints.ADMIN_USER.format(user_id=user_id))
+        return AdminUser.model_validate(response.json())
+
+    def create_user(self, request: AdminUserCreate | None = None, **kwargs) -> AdminUser:
+        """Create a user in a target company.
+
+        The role assignment matrix enforced on company-scoped endpoints does not
+        apply here, but the server still rejects ``UNAPPROVED``/``DEACTIVATED`` on
+        create.
+
+        Args:
+            request: An AdminUserCreate model, OR pass fields as keyword arguments.
+            **kwargs: Fields for AdminUserCreate if request is not provided.
+                Requires: company_id, username, email, role.
+
+        Returns:
+            The newly created AdminUser object.
+        """
+        body = request if request is not None else self._validate_request(AdminUserCreate, **kwargs)
+        response = self._post(
+            Endpoints.ADMIN_USERS,
+            json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
+        )
+        return AdminUser.model_validate(response.json())
+
+    def update_user(
+        self, user_id: str, request: AdminUserUpdate | None = None, **kwargs
+    ) -> AdminUser:
+        """Update any user by ID, bypassing the company-scoped role hierarchy.
+
+        Set ``is_archived=False`` to restore a soft-deleted user.
+
+        Args:
+            user_id: The ID of the user to update.
+            request: An AdminUserUpdate model, OR pass fields as keyword arguments.
+            **kwargs: Fields for AdminUserUpdate if request is not provided.
+
+        Returns:
+            The updated AdminUser object.
+        """
+        body = request if request is not None else self._validate_request(AdminUserUpdate, **kwargs)
+        response = self._patch(
+            Endpoints.ADMIN_USER.format(user_id=user_id),
+            json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
+        )
+        return AdminUser.model_validate(response.json())
+
+    def delete_user(self, user_id: str) -> None:
+        """Soft-delete a user by ID.
+
+        The deletion is reversible via ``update_user(user_id, is_archived=False)``.
+
+        Args:
+            user_id: The ID of the user to soft-delete.
+        """
+        self._delete(Endpoints.ADMIN_USER.format(user_id=user_id))
+
     def create_api_key(self, developer_id: str) -> DeveloperWithApiKey:
         """Generate a new API key for a developer.
 

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

@@ -84,6 +84,7 @@ HunterCreed = Literal["ENTREPRENEURIAL", "FAITHFUL", "INQUISITIVE", "MARTIAL", "
 HunterEdgeType = Literal["ASSETS", "APTITUDES", "ENDOWMENTS"]
 LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 ManageCampaignPermission = Literal["UNRESTRICTED", "STORYTELLER"]
+ManageNPCPermission = Literal["UNRESTRICTED", "STORYTELLER"]
 PermissionLevel = Literal["USER", "ADMIN", "OWNER", "REVOKE"]
 RecoupXPPermission = Literal["UNRESTRICTED", "DENIED", "WITHIN_SESSION"]
 RollResultType = Literal["SUCCESS", "FAILURE", "BOTCH", "CRITICAL", "OTHER"]

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

@@ -29,6 +29,8 @@ class Endpoints:
     ADMIN_DEVELOPER_AUDIT_LOGS = f"{ADMIN_DEVELOPER}/audit-logs"
     ADMIN_LOGS = f"{_BASE}/admin/logs"
     ADMIN_LOGS_DOWNLOAD = f"{ADMIN_LOGS}/download"
+    ADMIN_USERS = f"{_BASE}/admin/users"
+    ADMIN_USER = f"{_BASE}/admin/users/{{user_id}}"
 
     # Developer endpoints (self-service)
     DEVELOPER_ME = f"{_BASE}/developers/me"

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

@@ -127,6 +127,9 @@ from .user_lookup import (
     UserLookupResult,
 )
 from .users import (
+    AdminUser,
+    AdminUserCreate,
+    AdminUserUpdate,
     CampaignExperience,
     DiscordProfile,
     DiscordProfileUpdate,
@@ -146,6 +149,9 @@ from .users import (
 )
 
 __all__ = [
+    "AdminUser",
+    "AdminUserCreate",
+    "AdminUserUpdate",
     "Asset",
     "AuditLog",
     "AuditLogDetail",

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/models/books.py

@@ -22,6 +22,9 @@ class CampaignBook(BaseModel):
     asset_ids: list[str] = Field(default_factory=list, description="List of associated asset IDs.")
     number: int = Field(..., description="Book number within the campaign.")
     campaign_id: str = Field(..., description="ID of the parent campaign.")
+    num_chapters: int = Field(default=0, description="Number of active chapters in the book.")
+    num_notes: int = Field(default=0, description="Number of active notes on the book.")
+    num_assets: int = Field(default=0, description="Number of active assets on the book.")
 
 
 class CampaignBookDetail(CampaignBook):

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/models/campaigns.py

@@ -26,6 +26,12 @@ class Campaign(BaseModel):
     desperation: int = 0
     danger: int = 0
     company_id: str
+    num_books: int = 0
+    num_chapters: int = 0
+    num_notes: int = 0
+    num_player_characters: int = 0
+    num_storyteller_characters: int = 0
+    num_npc_characters: int = 0
 
 
 # -----------------------------------------------------------------------------

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/models/chapters.py

@@ -23,6 +23,8 @@ class CampaignChapter(BaseModel):
     asset_ids: list[str] = Field(default_factory=list, description="List of associated asset IDs.")
     number: int = Field(..., description="Chapter number within the book.")
     book_id: str = Field(..., description="ID of the parent book.")
+    num_notes: int = Field(default=0, description="Number of active notes on the chapter.")
+    num_assets: int = Field(default=0, description="Number of active assets on the chapter.")
 
 
 class CampaignChapterDetail(CampaignChapter):

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

@@ -222,6 +222,13 @@ class Character(BaseModel):
         default=None, description="Hunter-specific attributes."
     )
 
+    # Child-resource counts
+    num_inventory_items: int = Field(
+        default=0, description="Number of active inventory items on the character."
+    )
+    num_notes: int = Field(default=0, description="Number of active notes on the character.")
+    num_assets: int = Field(default=0, description="Number of active assets on the character.")
+
 
 class CharacterDetail(Character):
     """Character response with optional embedded child resources.

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/models/companies.py

@@ -9,6 +9,7 @@ from vclient.constants import (
     FreeTraitChangesPermission,
     GrantXPPermission,
     ManageCampaignPermission,
+    ManageNPCPermission,
     PermissionLevel,
     RecoupXPPermission,
 )
@@ -27,6 +28,7 @@ class CompanySettings(BaseModel):
     character_autogen_num_choices: int
     character_autogen_starting_points: int
     permission_manage_campaign: ManageCampaignPermission
+    permission_manage_npc: ManageNPCPermission
     permission_grant_xp: GrantXPPermission
     permission_free_trait_changes: FreeTraitChangesPermission
     permission_recoup_xp: RecoupXPPermission
@@ -42,6 +44,7 @@ class CompanySettingsCreate(BaseModel):
     character_autogen_num_choices: int | None = None
     character_autogen_starting_points: int | None = None
     permission_manage_campaign: ManageCampaignPermission | None = None
+    permission_manage_npc: ManageNPCPermission | None = None
     permission_grant_xp: GrantXPPermission | None = None
     permission_free_trait_changes: FreeTraitChangesPermission | None = None
     permission_recoup_xp: RecoupXPPermission | None = None
@@ -57,6 +60,7 @@ class CompanySettingsUpdate(BaseModel):
     character_autogen_num_choices: int | None = None
     character_autogen_starting_points: int | None = None
     permission_manage_campaign: ManageCampaignPermission | None = None
+    permission_manage_npc: ManageNPCPermission | None = None
     permission_grant_xp: GrantXPPermission | None = None
     permission_free_trait_changes: FreeTraitChangesPermission | None = None
     permission_recoup_xp: RecoupXPPermission | None = None

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/models/users.py

@@ -96,6 +96,10 @@ class User(BaseModel):
     asset_ids: list[str] = Field(default_factory=list)
     lifetime_xp: int = 0
     lifetime_cool_points: int = 0
+    num_quickrolls: int = 0
+    num_notes: int = 0
+    num_assets: int = 0
+    num_characters: int = 0
 
 
 class UserDetail(User):
@@ -122,6 +126,17 @@ class UserDetail(User):
     )
 
 
+class AdminUser(User):
+    """Response model for a user returned by the global-admin user endpoints.
+
+    Extends the tenant-scoped ``User`` with ``is_archived``, which is always
+    present on the admin endpoints so callers can identify soft-deleted users
+    directly from the response body.
+    """
+
+    is_archived: bool
+
+
 # -----------------------------------------------------------------------------
 # User Request Models
 # -----------------------------------------------------------------------------
@@ -194,6 +209,27 @@ class UserUpdate(BaseModel):
     github_profile: GitHubProfile | None = None
 
 
+class AdminUserCreate(UserCreate):
+    """Request body for creating a user as a global admin.
+
+    Extends the tenant-scoped ``UserCreate`` with an explicit ``company_id`` for
+    the target company. The server rejects ``UNAPPROVED``/``DEACTIVATED`` roles
+    on create, so no client-side role restriction is applied here.
+    """
+
+    company_id: str
+
+
+class AdminUserUpdate(UserUpdate):
+    """Request body for updating any user as a global admin.
+
+    Extends the tenant-scoped ``UserUpdate`` with ``is_archived``. Set it to
+    ``False`` to restore a soft-deleted user.
+    """
+
+    is_archived: bool | None = None
+
+
 class UserApproveDTO(BaseModel):
     """Approve an unapproved user and assign a role."""
 
@@ -262,6 +298,9 @@ class _ExperienceAddRemove(BaseModel):
 
 
 __all__ = [
+    "AdminUser",
+    "AdminUserCreate",
+    "AdminUserUpdate",
     "CampaignExperience",
     "DiscordProfile",
     "GitHubProfile",

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/registry.py

@@ -160,7 +160,7 @@ def global_admin_service() -> "GlobalAdminService":
     Example:
         ```python
         admins = global_admin_service()
-        developers = await admins.list_all()
+        developers = await admins.list_all_developers()
         ```
     """
     from vclient.services.global_admin import GlobalAdminService

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

@@ -13,9 +13,13 @@ from vclient.constants import (
     AuditLogInclude,
     AuditOperation,
     LogLevel,
+    UserRole,
 )
 from vclient.endpoints import Endpoints
 from vclient.models import (
+    AdminUser,
+    AdminUserCreate,
+    AdminUserUpdate,
     AuditLog,
     AuditLogDetail,
     Developer,
@@ -56,16 +60,16 @@ def _filename_from_content_disposition(header: str | None, *, fallback: str) ->
 class GlobalAdminService(BaseService):
     """Service for global admin operations in the Valentina API.
 
-    Provides methods to create, retrieve, update, and delete developer accounts,
-    as well as manage API keys. Requires global admin privileges.
+    Provides cross-company management of developer accounts and their API keys,
+    plus server log access. Requires global admin privileges.
 
     Example:
         >>> async with VClient() as client:
-        ...     developers = await client.global_admin.list_all()
-        ...     developer = await client.global_admin.get("developer_id")
+        ...     developers = await client.global_admin.list_all_developers()
+        ...     developer = await client.global_admin.get_developer("developer_id")
     """
 
-    async def get_page(
+    async def get_developer_page(
         self,
         *,
         limit: int = DEFAULT_PAGE_LIMIT,
@@ -93,11 +97,11 @@ class GlobalAdminService(BaseService):
             params=params,
         )
 
-    async def list_all(self, *, is_global_admin: bool | None = None) -> list[Developer]:
+    async def list_all_developers(self, *, is_global_admin: bool | None = None) -> list[Developer]:
         """Retrieve all developer accounts.
 
-        Automatically paginates through all results. Use `get_page()` for paginated access
-        or `iter_all()` for memory-efficient streaming of large datasets.
+        Automatically paginates through all results. Use `get_developer_page()` for paginated
+        access or `iter_all_developers()` for memory-efficient streaming of large datasets.
 
         Args:
             is_global_admin: Optional filter by global admin status.
@@ -105,9 +109,12 @@ class GlobalAdminService(BaseService):
         Returns:
             A list of all Developer objects.
         """
-        return [developer async for developer in self.iter_all(is_global_admin=is_global_admin)]
+        return [
+            developer
+            async for developer in self.iter_all_developers(is_global_admin=is_global_admin)
+        ]
 
-    async def iter_all(
+    async def iter_all_developers(
         self,
         *,
         limit: int = 100,
@@ -126,21 +133,19 @@ class GlobalAdminService(BaseService):
             Individual Developer objects.
 
         Example:
-            >>> async for developer in client.global_admin.iter_all():
+            >>> async for developer in client.global_admin.iter_all_developers():
             ...     print(developer.username)
         """
-        params = {}
-        if is_global_admin is not None:
-            params["is_global_admin"] = is_global_admin
+        params = self._build_params(is_global_admin=is_global_admin)
 
         async for item in self._iter_all_pages(
             Endpoints.ADMIN_DEVELOPERS,
             limit=limit,
-            params=params or None,
+            params=params,
         ):
             yield Developer.model_validate(item)
 
-    async def get(self, developer_id: str) -> Developer:
+    async def get_developer(self, developer_id: str) -> Developer:
         """Retrieve detailed information about a specific developer.
 
         Args:
@@ -156,7 +161,7 @@ class GlobalAdminService(BaseService):
         response = await self._get(Endpoints.ADMIN_DEVELOPER.format(developer_id=developer_id))
         return Developer.model_validate(response.json())
 
-    async def create(
+    async def create_developer(
         self,
         request: DeveloperCreate | None = None,
         **kwargs,
@@ -187,7 +192,7 @@ class GlobalAdminService(BaseService):
         )
         return Developer.model_validate(response.json())
 
-    async def update(
+    async def update_developer(
         self,
         developer_id: str,
         request: DeveloperUpdate | None = None,
@@ -220,7 +225,7 @@ class GlobalAdminService(BaseService):
         )
         return Developer.model_validate(response.json())
 
-    async def delete(self, developer_id: str) -> None:
+    async def delete_developer(self, developer_id: str) -> None:
         """Remove a developer account from the system.
 
         The developer's API key will be invalidated immediately.
@@ -234,6 +239,180 @@ class GlobalAdminService(BaseService):
         """
         await self._delete(Endpoints.ADMIN_DEVELOPER.format(developer_id=developer_id))
 
+    async def get_user_page(
+        self,
+        *,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+        offset: int = 0,
+    ) -> PaginatedResponse[AdminUser]:
+        """Retrieve a paginated page of users across all companies.
+
+        Authenticates with the global-admin API key only; no On-Behalf-Of header
+        is sent. Archived (soft-deleted) users are included when
+        ``is_archived=True``.
+
+        Args:
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+            limit: Maximum number of items to return (0-100, default 10).
+            offset: Number of items to skip from the beginning (default 0).
+
+        Returns:
+            A PaginatedResponse containing AdminUser objects and pagination metadata.
+        """
+        params = self._build_params(
+            company_id=company_id, role=role, email=email, is_archived=is_archived
+        )
+        return await self._get_paginated_as(
+            Endpoints.ADMIN_USERS,
+            AdminUser,
+            limit=limit,
+            offset=offset,
+            params=params,
+        )
+
+    async def list_all_users(
+        self,
+        *,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+    ) -> list[AdminUser]:
+        """Retrieve all users across all companies.
+
+        Automatically paginates through all results. Use ``get_user_page()`` for
+        paginated access or ``iter_all_users()`` for memory-efficient streaming.
+
+        Args:
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+
+        Returns:
+            A list of all matching AdminUser objects.
+        """
+        return [
+            user
+            async for user in self.iter_all_users(
+                company_id=company_id, role=role, email=email, is_archived=is_archived
+            )
+        ]
+
+    async def iter_all_users(
+        self,
+        *,
+        limit: int = 100,
+        company_id: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+        is_archived: bool | None = None,
+    ) -> AsyncIterator[AdminUser]:
+        """Iterate through all users across all companies.
+
+        Yields individual users, automatically fetching subsequent pages until all
+        matching users have been retrieved.
+
+        Args:
+            limit: Items per page (default 100 for efficiency).
+            company_id: Filter to a single company.
+            role: Filter by user role.
+            email: Filter by exact email match.
+            is_archived: Filter by archived state.
+
+        Yields:
+            Individual AdminUser objects.
+        """
+        params = self._build_params(
+            company_id=company_id, role=role, email=email, is_archived=is_archived
+        )
+        async for item in self._iter_all_pages(
+            Endpoints.ADMIN_USERS,
+            limit=limit,
+            params=params,
+        ):
+            yield AdminUser.model_validate(item)
+
+    async def get_user(self, user_id: str) -> AdminUser:
+        """Retrieve a single user by ID, including archived users.
+
+        Args:
+            user_id: The ID of the user to retrieve.
+
+        Returns:
+            The AdminUser object, with ``is_archived`` reflecting soft-delete state.
+        """
+        response = await self._get(Endpoints.ADMIN_USER.format(user_id=user_id))
+        return AdminUser.model_validate(response.json())
+
+    async def create_user(
+        self,
+        request: AdminUserCreate | None = None,
+        **kwargs,
+    ) -> AdminUser:
+        """Create a user in a target company.
+
+        The role assignment matrix enforced on company-scoped endpoints does not
+        apply here, but the server still rejects ``UNAPPROVED``/``DEACTIVATED`` on
+        create.
+
+        Args:
+            request: An AdminUserCreate model, OR pass fields as keyword arguments.
+            **kwargs: Fields for AdminUserCreate if request is not provided.
+                Requires: company_id, username, email, role.
+
+        Returns:
+            The newly created AdminUser object.
+        """
+        body = request if request is not None else self._validate_request(AdminUserCreate, **kwargs)
+        response = await self._post(
+            Endpoints.ADMIN_USERS,
+            json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
+        )
+        return AdminUser.model_validate(response.json())
+
+    async def update_user(
+        self,
+        user_id: str,
+        request: AdminUserUpdate | None = None,
+        **kwargs,
+    ) -> AdminUser:
+        """Update any user by ID, bypassing the company-scoped role hierarchy.
+
+        Set ``is_archived=False`` to restore a soft-deleted user.
+
+        Args:
+            user_id: The ID of the user to update.
+            request: An AdminUserUpdate model, OR pass fields as keyword arguments.
+            **kwargs: Fields for AdminUserUpdate if request is not provided.
+
+        Returns:
+            The updated AdminUser object.
+        """
+        body = request if request is not None else self._validate_request(AdminUserUpdate, **kwargs)
+        response = await self._patch(
+            Endpoints.ADMIN_USER.format(user_id=user_id),
+            json=body.model_dump(exclude_none=True, exclude_unset=True, mode="json"),
+        )
+        return AdminUser.model_validate(response.json())
+
+    async def delete_user(self, user_id: str) -> None:
+        """Soft-delete a user by ID.
+
+        The deletion is reversible via ``update_user(user_id, is_archived=False)``.
+
+        Args:
+            user_id: The ID of the user to soft-delete.
+        """
+        await self._delete(Endpoints.ADMIN_USER.format(user_id=user_id))
+
     async def create_api_key(self, developer_id: str) -> DeveloperWithApiKey:
         """Generate a new API key for a developer.
 

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

@@ -15,6 +15,7 @@ except ImportError as e:
 from vclient._sync.testing import SyncFakeVClient
 from vclient.testing._client import FakeVClient
 from vclient.testing._factories import (
+    AdminUserFactory,
     AssetFactory,
     AuditLogDetailFactory,
     AuditLogFactory,
@@ -68,6 +69,7 @@ from vclient.testing._factories import (
 from vclient.testing._routes import Routes, RouteSpec
 
 __all__ = [
+    "AdminUserFactory",
     "AssetFactory",
     "AuditLogDetailFactory",
     "AuditLogFactory",

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

@@ -3,6 +3,7 @@
 from polyfactory.factories.pydantic_factory import ModelFactory
 
 from vclient.models import (
+    AdminUser,
     Asset,
     AuditLog,
     AuditLogDetail,
@@ -272,6 +273,12 @@ class TraitFactory(ModelFactory[Trait]):
     __use_defaults__ = True
 
 
+class AdminUserFactory(ModelFactory[AdminUser]):
+    __model__ = AdminUser
+    __use_defaults__ = True
+    role = "PLAYER"
+
+
 class UserFactory(ModelFactory[User]):
     __model__ = User
     __use_defaults__ = True
@@ -306,6 +313,7 @@ class WerewolfTribeFactory(ModelFactory[WerewolfTribe]):
 
 
 __all__ = [
+    "AdminUserFactory",
     "AssetFactory",
     "AuditLogDetailFactory",
     "AuditLogFactory",

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

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
 
 from vclient.constants import REQUEST_ID_HEADER
 from vclient.models import (
+    AdminUser,
     Asset,
     AuditLog,
     AuditLogDetail,
@@ -59,6 +60,7 @@ from vclient.models import (
 from vclient.models.character_autogen import ChargenSessionResponse
 from vclient.models.users import CampaignExperience
 from vclient.testing._factories import (
+    AdminUserFactory,
     AssetFactory,
     AuditLogDetailFactory,
     AuditLogFactory,
@@ -106,6 +108,7 @@ from vclient.testing._factories import (
 from vclient.testing._routes import BYTES, LIST, NO_CONTENT, PAGINATED, RAW_JSON, Routes, RouteSpec
 
 _FACTORY_MAP: dict[type, type[ModelFactory]] = {
+    AdminUser: AdminUserFactory,
     AuditLog: AuditLogFactory,
     AuditLogDetail: AuditLogDetailFactory,
     Asset: AssetFactory,

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

@@ -6,6 +6,7 @@ from typing import NamedTuple
 
 from vclient.endpoints import Endpoints
 from vclient.models import (
+    AdminUser,
     Asset,
     AuditLog,
     BulkAssignTraitResponse,
@@ -112,6 +113,13 @@ class Routes:
     ADMIN_LOGS_TAIL = RouteSpec("GET", Endpoints.ADMIN_LOGS, LIST, ServerLogEntry)
     ADMIN_LOGS_DOWNLOAD = RouteSpec("GET", Endpoints.ADMIN_LOGS_DOWNLOAD, BYTES, None)
 
+    # Admin users (cross-company, global-admin only)
+    ADMIN_USERS_LIST = RouteSpec("GET", Endpoints.ADMIN_USERS, PAGINATED, AdminUser)
+    ADMIN_USERS_GET = RouteSpec("GET", Endpoints.ADMIN_USER, SINGLE, AdminUser)
+    ADMIN_USERS_CREATE = RouteSpec("POST", Endpoints.ADMIN_USERS, SINGLE, AdminUser)
+    ADMIN_USERS_UPDATE = RouteSpec("PATCH", Endpoints.ADMIN_USER, SINGLE, AdminUser)
+    ADMIN_USERS_DELETE = RouteSpec("DELETE", Endpoints.ADMIN_USER, NO_CONTENT, None)
+
     # Developer self-service
     DEVELOPERS_ME_GET = RouteSpec("GET", Endpoints.DEVELOPER_ME, SINGLE, MeDeveloper)
     DEVELOPERS_ME_UPDATE = RouteSpec("PATCH", Endpoints.DEVELOPER_ME, SINGLE, MeDeveloper)

{valentina_python_client-2.2.0 → valentina_python_client-2.4.0}/src/vclient/validate_constants.py

@@ -77,6 +77,7 @@ CONSTANT_MAP: dict[str, ConstantMapping] = {
     "HunterCreed": ConstantMapping("characters", "HunterCreed"),
     "HunterEdgeType": ConstantMapping("characters", "HunterEdgeType"),
     "ManageCampaignPermission": ConstantMapping("companies", "PermissionManageCampaign"),
+    "ManageNPCPermission": ConstantMapping("companies", "PermissionManageNPC"),
     "PermissionLevel": ConstantMapping("companies", "CompanyPermission"),
     "RecoupXPPermission": ConstantMapping("companies", "PermissionsRecoupXP"),
     "RollResultType": ConstantMapping("gameplay", "RollResultType"),