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

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

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

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

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

{valentina_python_client-1.20.0 → valentina_python_client-1.21.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.0"
+__version__ = "1.21.0"

{valentina_python_client-1.20.0 → valentina_python_client-1.21.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.0 → valentina_python_client-1.21.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.0 → valentina_python_client-1.21.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.0 → valentina_python_client-1.21.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.0 → valentina_python_client-1.21.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.21.0/src/vclient/_sync/services/user_lookup.py

@@ -0,0 +1,68 @@
+# AUTO-GENERATED — do not edit. Run 'uv run duty generate_sync' to regenerate.
+"""Service for cross-company user lookup."""
+
+from vclient._sync.services.base import SyncBaseService
+from vclient.endpoints import Endpoints
+from vclient.models import UserLookupResult
+
+
+class SyncUserLookupService(SyncBaseService):
+    """Service for looking up users across companies.
+
+    Discover which companies a person has a user record in by searching
+    via email, Discord ID, Google ID, or GitHub ID.
+
+    Example:
+        >>> async with SyncVClient() as client:
+        ...     results = await client.user_lookup.by_email("alice@example.com")
+        ...     for r in results:
+        ...         print(f"{r.company_name}: {r.role}")
+    """
+
+    def by_email(self, email: str) -> list[UserLookupResult]:
+        """Look up a user by email address.
+
+        Args:
+            email: Exact email address to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = self._get(Endpoints.USERS_LOOKUP, params={"email": email})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    def by_discord_id(self, discord_id: str) -> list[UserLookupResult]:
+        """Look up a user by Discord profile ID.
+
+        Args:
+            discord_id: Discord profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = self._get(Endpoints.USERS_LOOKUP, params={"discord_id": discord_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    def by_google_id(self, google_id: str) -> list[UserLookupResult]:
+        """Look up a user by Google profile ID.
+
+        Args:
+            google_id: Google profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = self._get(Endpoints.USERS_LOOKUP, params={"google_id": google_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    def by_github_id(self, github_id: str) -> list[UserLookupResult]:
+        """Look up a user by GitHub profile ID.
+
+        Args:
+            github_id: GitHub profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = self._get(Endpoints.USERS_LOOKUP, params={"github_id": github_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/_sync/services/users.py

@@ -65,13 +65,14 @@ class SyncUsersService(SyncBaseService):
         return endpoint.format(company_id=self._company_id, **kwargs)
 
     def get_unapproved_page(
-        self, *, limit: int = DEFAULT_PAGE_LIMIT, offset: int = 0
+        self, requesting_user_id: str, *, limit: int = DEFAULT_PAGE_LIMIT, offset: int = 0
     ) -> PaginatedResponse[User]:
         """Retrieve a paginated page of unapproved users within a company.
 
         Unapproved users have registered but have not yet been approved by an admin.
 
         Args:
+            requesting_user_id: ID of the user making the request (for permissions).
             limit: Maximum number of items to return (0-100, default 10).
             offset: Number of items to skip from the beginning (default 0).
 
@@ -79,40 +80,54 @@ class SyncUsersService(SyncBaseService):
             A PaginatedResponse containing User objects and pagination metadata.
         """
         return self._get_paginated_as(
-            self._format_endpoint(Endpoints.USERS_UNAPPROVED_LIST), User, limit=limit, offset=offset
+            self._format_endpoint(Endpoints.USERS_UNAPPROVED_LIST),
+            User,
+            limit=limit,
+            offset=offset,
+            params=self._build_params(requesting_user_id=requesting_user_id),
         )
 
-    def list_all_unapproved(self) -> list[User]:
+    def list_all_unapproved(self, requesting_user_id: str) -> list[User]:
         """Retrieve all unapproved users within a company.
 
         Automatically paginates through all results. Use `get_unapproved_page()` for
         paginated access or `iter_all_unapproved()` for memory-efficient streaming.
 
+        Args:
+            requesting_user_id: ID of the user making the request (for permissions).
+
         Returns:
             A list of all unapproved User objects.
         """
-        return [user for user in self.iter_all_unapproved()]
+        return [user for user in self.iter_all_unapproved(requesting_user_id)]
 
-    def iter_all_unapproved(self, *, limit: int = 100) -> Iterator[User]:
+    def iter_all_unapproved(self, requesting_user_id: str, *, limit: int = 100) -> Iterator[User]:
         """Iterate through all unapproved users within a company.
 
         Yields individual unapproved users, automatically fetching subsequent pages
         until all items have been retrieved.
 
         Args:
+            requesting_user_id: ID of the user making the request (for permissions).
             limit: Items per page (default 100 for efficiency).
 
         Yields:
             Individual User objects.
         """
         for item in self._iter_all_pages(
-            self._format_endpoint(Endpoints.USERS_UNAPPROVED_LIST), limit=limit
+            self._format_endpoint(Endpoints.USERS_UNAPPROVED_LIST),
+            limit=limit,
+            params=self._build_params(requesting_user_id=requesting_user_id),
         ):
             yield User.model_validate(item)
 
     def approve_user(self, user_id: str, role: UserRole, requesting_user_id: str) -> User:
         """Approve an unapproved user and assign them a role.
 
+        The assigned ``role`` is validated through the server-side role-assignment
+        hierarchy — for example, a STORYTELLER cannot approve a user directly to
+        ADMIN, and only ADMIN may approve a user to ADMIN or DEACTIVATED.
+
         Args:
             user_id: The ID of the unapproved user to approve.
             role: The role to assign to the approved user.
@@ -123,7 +138,8 @@ class SyncUsersService(SyncBaseService):
 
         Raises:
             NotFoundError: If the user does not exist.
-            AuthorizationError: If you don't have appropriate access.
+            AuthorizationError: If the requesting user lacks permission to assign
+                the requested role under the hierarchy.
         """
         body = UserApproveDTO(role=role, requesting_user_id=requesting_user_id)
         response = self._post(
@@ -285,6 +301,10 @@ class SyncUsersService(SyncBaseService):
         is optional and is not used for authentication but is included for Discord bot
         integration.
 
+        The initial ``role`` cannot be ``UNAPPROVED`` (use :meth:`register` for SSO
+        onboarding) or ``DEACTIVATED`` (not a creation path); either will surface as
+        ``ValidationError``.
+
         Args:
             request: A UserCreate model, OR pass fields as keyword arguments.
             **kwargs: Fields for UserCreate if request is not provided.
@@ -341,6 +361,14 @@ class SyncUsersService(SyncBaseService):
 
         Only include fields that need to be changed; omitted fields remain unchanged.
 
+        Setting ``role="DEACTIVATED"`` is the canonical way to deactivate a user:
+        the account can no longer log in or act, but their characters, assets, XP,
+        and notes remain intact and manageable by other users. Reactivate by calling
+        this same endpoint with any other valid role. Role changes are subject to a
+        server-side role-assignment hierarchy (e.g. only ADMIN may assign or remove
+        ADMIN/DEACTIVATED) and the server refuses to demote or deactivate the last
+        remaining active admin.
+
         Args:
             user_id: The ID of the user to update.
             request: A UserUpdate model, OR pass fields as keyword arguments.
@@ -354,7 +382,9 @@ class SyncUsersService(SyncBaseService):
 
         Raises:
             NotFoundError: If the user does not exist.
-            AuthorizationError: If you don't have appropriate access.
+            AuthorizationError: If the requesting user lacks permission to make
+                the change or to assign the requested role under the hierarchy.
+            ConflictError: If the change would remove the last active admin.
             RequestValidationError: If the input parameters fail client-side validation.
             ValidationError: If the request data is invalid.
         """

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/client.py

@@ -36,6 +36,7 @@ if TYPE_CHECKING:
         GlobalAdminService,
         OptionsService,
         SystemService,
+        UserLookupService,
         UsersService,
     )
 
@@ -150,6 +151,7 @@ class VClient:
         self._developer: DeveloperService | None = None
         self._global_admin: GlobalAdminService | None = None
         self._system: SystemService | None = None
+        self._user_lookup: UserLookupService | None = None
 
         if set_as_default:
             from vclient.registry import configure_default_client
@@ -290,6 +292,19 @@ class VClient:
             self._system = SystemService(self)
         return self._system
 
+    @property
+    def user_lookup(self) -> "UserLookupService":
+        """Access the User Lookup service for cross-company user discovery.
+
+        Returns:
+            The UserLookupService instance for user lookup operations.
+        """
+        if self._user_lookup is None:
+            from vclient.services.user_lookup import UserLookupService
+
+            self._user_lookup = UserLookupService(self)
+        return self._user_lookup
+
     def users(self, company_id: str | None = None) -> "UsersService":
         """Get a UsersService scoped to a specific company.
 

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/constants.py

@@ -63,7 +63,7 @@ RecoupXPPermission = Literal["UNRESTRICTED", "DENIED", "WITHIN_SESSION"]
 RollResultType = Literal["SUCCESS", "FAILURE", "BOTCH", "CRITICAL", "OTHER"]
 AssetType = Literal["image", "text", "audio", "video", "document", "archive", "other"]
 SpecialtyType = Literal["ACTION", "OTHER", "PASSIVE", "RITUAL", "SPELL"]
-UserRole = Literal["ADMIN", "STORYTELLER", "PLAYER", "UNAPPROVED"]
+UserRole = Literal["ADMIN", "STORYTELLER", "PLAYER", "UNAPPROVED", "DEACTIVATED"]
 WerewolfRenown = Literal["HONOR", "GLORY", "WISDOM"]
 BlueprintTraitOrderBy = Literal["NAME", "SHEET"]
 TraitModifyCurrency = Literal["XP", "STARTING_POINTS", "NO_COST"]

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/endpoints.py

@@ -19,6 +19,9 @@ class Endpoints:
     # System endpoints
     HEALTH = f"{_BASE}/health"
 
+    # User lookup (cross-company, not scoped)
+    USERS_LOOKUP = f"{_BASE}/users/lookup"
+
     # Global Admin endpoints
     ADMIN_DEVELOPERS = f"{_BASE}/admin/developers"
     ADMIN_DEVELOPER = f"{_BASE}/admin/developers/{{developer_id}}"

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

@@ -115,6 +115,9 @@ from .shared import (
     Trait,
 )
 from .system import SystemHealth
+from .user_lookup import (
+    UserLookupResult,
+)
 from .users import (
     CampaignExperience,
     DiscordProfile,
@@ -221,6 +224,7 @@ __all__ = [
     "UserCreate",
     "UserDenyDTO",
     "UserDetail",
+    "UserLookupResult",
     "UserMergeDTO",
     "UserRegisterDTO",
     "UserUpdate",

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/models/characters.py

@@ -152,12 +152,8 @@ class Character(BaseModel):
     """
 
     id: str = Field(..., description="MongoDB document ObjectID.")
-    date_created: datetime | None = Field(
-        default=None, description="Timestamp when the character was created."
-    )
-    date_modified: datetime | None = Field(
-        default=None, description="Timestamp when the character was last modified."
-    )
+    date_created: datetime
+    date_modified: datetime
     date_killed: datetime | None = Field(
         default=None, description="Timestamp when the character was killed."
     )

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/models/companies.py

@@ -43,7 +43,7 @@ class Company(BaseModel):
     description: str | None
     email: str
     resources_modified_at: datetime
-    settings: CompanySettings | None
+    settings: CompanySettings
 
 
 class CompanyPermissions(BaseModel):

valentina_python_client-1.21.0/src/vclient/models/user_lookup.py

@@ -0,0 +1,22 @@
+"""Pydantic models for User Lookup API responses."""
+
+from pydantic import BaseModel
+
+from vclient.constants import UserRole
+
+
+class UserLookupResult(BaseModel):
+    """A single result from a cross-company user lookup.
+
+    Each result represents a company where the looked-up person has a user record.
+    """
+
+    company_id: str
+    company_name: str
+    user_id: str
+    role: UserRole
+
+
+__all__ = [
+    "UserLookupResult",
+]

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/registry.py

@@ -37,6 +37,7 @@ if TYPE_CHECKING:
         GlobalAdminService,
         OptionsService,
         SystemService,
+        UserLookupService,
         UsersService,
     )
 
@@ -189,6 +190,29 @@ def system_service() -> "SystemService":
     return SystemService(default_client())
 
 
+def user_lookup_service() -> "UserLookupService":
+    """Create a UserLookupService 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:
+        UserLookupService: A service instance for cross-company user lookup.
+
+    Raises:
+        RuntimeError: If no default client has been configured.
+
+    Example:
+        ```python
+        lookup = user_lookup_service()
+        results = await lookup.by_email("alice@example.com")
+        ```
+    """
+    from vclient.services.user_lookup import UserLookupService
+
+    return UserLookupService(default_client())
+
+
 def users_service(company_id: str | None = None) -> "UsersService":
     """Create a UsersService scoped to a specific company using the default client.
 

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

@@ -15,6 +15,7 @@ from .dictionary import DictionaryService
 from .global_admin import GlobalAdminService
 from .options import OptionsService
 from .system import SystemService
+from .user_lookup import UserLookupService
 from .users import UsersService
 
 __all__ = [
@@ -33,5 +34,6 @@ __all__ = [
     "GlobalAdminService",
     "OptionsService",
     "SystemService",
+    "UserLookupService",
     "UsersService",
 ]

valentina_python_client-1.21.0/src/vclient/services/user_lookup.py

@@ -0,0 +1,67 @@
+"""Service for cross-company user lookup."""
+
+from vclient.endpoints import Endpoints
+from vclient.models import UserLookupResult
+from vclient.services.base import BaseService
+
+
+class UserLookupService(BaseService):
+    """Service for looking up users across companies.
+
+    Discover which companies a person has a user record in by searching
+    via email, Discord ID, Google ID, or GitHub ID.
+
+    Example:
+        >>> async with VClient() as client:
+        ...     results = await client.user_lookup.by_email("alice@example.com")
+        ...     for r in results:
+        ...         print(f"{r.company_name}: {r.role}")
+    """
+
+    async def by_email(self, email: str) -> list[UserLookupResult]:
+        """Look up a user by email address.
+
+        Args:
+            email: Exact email address to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = await self._get(Endpoints.USERS_LOOKUP, params={"email": email})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    async def by_discord_id(self, discord_id: str) -> list[UserLookupResult]:
+        """Look up a user by Discord profile ID.
+
+        Args:
+            discord_id: Discord profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = await self._get(Endpoints.USERS_LOOKUP, params={"discord_id": discord_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    async def by_google_id(self, google_id: str) -> list[UserLookupResult]:
+        """Look up a user by Google profile ID.
+
+        Args:
+            google_id: Google profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = await self._get(Endpoints.USERS_LOOKUP, params={"google_id": google_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]
+
+    async def by_github_id(self, github_id: str) -> list[UserLookupResult]:
+        """Look up a user by GitHub profile ID.
+
+        Args:
+            github_id: GitHub profile ID to search for.
+
+        Returns:
+            List of companies where a matching user was found. Empty list if no matches.
+        """
+        response = await self._get(Endpoints.USERS_LOOKUP, params={"github_id": github_id})
+        return [UserLookupResult.model_validate(item) for item in response.json()]

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/services/users.py

@@ -69,6 +69,7 @@ class UsersService(BaseService):
 
     async def get_unapproved_page(
         self,
+        requesting_user_id: str,
         *,
         limit: int = DEFAULT_PAGE_LIMIT,
         offset: int = 0,
@@ -78,6 +79,7 @@ class UsersService(BaseService):
         Unapproved users have registered but have not yet been approved by an admin.
 
         Args:
+            requesting_user_id: ID of the user making the request (for permissions).
             limit: Maximum number of items to return (0-100, default 10).
             offset: Number of items to skip from the beginning (default 0).
 
@@ -89,21 +91,26 @@ class UsersService(BaseService):
             User,
             limit=limit,
             offset=offset,
+            params=self._build_params(requesting_user_id=requesting_user_id),
         )
 
-    async def list_all_unapproved(self) -> list[User]:
+    async def list_all_unapproved(self, requesting_user_id: str) -> list[User]:
         """Retrieve all unapproved users within a company.
 
         Automatically paginates through all results. Use `get_unapproved_page()` for
         paginated access or `iter_all_unapproved()` for memory-efficient streaming.
 
+        Args:
+            requesting_user_id: ID of the user making the request (for permissions).
+
         Returns:
             A list of all unapproved User objects.
         """
-        return [user async for user in self.iter_all_unapproved()]
+        return [user async for user in self.iter_all_unapproved(requesting_user_id)]
 
     async def iter_all_unapproved(
         self,
+        requesting_user_id: str,
         *,
         limit: int = 100,
     ) -> AsyncIterator[User]:
@@ -113,6 +120,7 @@ class UsersService(BaseService):
         until all items have been retrieved.
 
         Args:
+            requesting_user_id: ID of the user making the request (for permissions).
             limit: Items per page (default 100 for efficiency).
 
         Yields:
@@ -121,6 +129,7 @@ class UsersService(BaseService):
         async for item in self._iter_all_pages(
             self._format_endpoint(Endpoints.USERS_UNAPPROVED_LIST),
             limit=limit,
+            params=self._build_params(requesting_user_id=requesting_user_id),
         ):
             yield User.model_validate(item)
 
@@ -132,6 +141,10 @@ class UsersService(BaseService):
     ) -> User:
         """Approve an unapproved user and assign them a role.
 
+        The assigned ``role`` is validated through the server-side role-assignment
+        hierarchy — for example, a STORYTELLER cannot approve a user directly to
+        ADMIN, and only ADMIN may approve a user to ADMIN or DEACTIVATED.
+
         Args:
             user_id: The ID of the unapproved user to approve.
             role: The role to assign to the approved user.
@@ -142,7 +155,8 @@ class UsersService(BaseService):
 
         Raises:
             NotFoundError: If the user does not exist.
-            AuthorizationError: If you don't have appropriate access.
+            AuthorizationError: If the requesting user lacks permission to assign
+                the requested role under the hierarchy.
         """
         body = UserApproveDTO(role=role, requesting_user_id=requesting_user_id)
         response = await self._post(
@@ -333,6 +347,10 @@ class UsersService(BaseService):
         is optional and is not used for authentication but is included for Discord bot
         integration.
 
+        The initial ``role`` cannot be ``UNAPPROVED`` (use :meth:`register` for SSO
+        onboarding) or ``DEACTIVATED`` (not a creation path); either will surface as
+        ``ValidationError``.
+
         Args:
             request: A UserCreate model, OR pass fields as keyword arguments.
             **kwargs: Fields for UserCreate if request is not provided.
@@ -398,6 +416,14 @@ class UsersService(BaseService):
 
         Only include fields that need to be changed; omitted fields remain unchanged.
 
+        Setting ``role="DEACTIVATED"`` is the canonical way to deactivate a user:
+        the account can no longer log in or act, but their characters, assets, XP,
+        and notes remain intact and manageable by other users. Reactivate by calling
+        this same endpoint with any other valid role. Role changes are subject to a
+        server-side role-assignment hierarchy (e.g. only ADMIN may assign or remove
+        ADMIN/DEACTIVATED) and the server refuses to demote or deactivate the last
+        remaining active admin.
+
         Args:
             user_id: The ID of the user to update.
             request: A UserUpdate model, OR pass fields as keyword arguments.
@@ -411,7 +437,9 @@ class UsersService(BaseService):
 
         Raises:
             NotFoundError: If the user does not exist.
-            AuthorizationError: If you don't have appropriate access.
+            AuthorizationError: If the requesting user lacks permission to make
+                the change or to assign the requested role under the hierarchy.
+            ConflictError: If the change would remove the last active admin.
             RequestValidationError: If the input parameters fail client-side validation.
             ValidationError: If the request data is invalid.
         """

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

@@ -57,6 +57,7 @@ from vclient.testing._factories import (
     TraitSubcategoryFactory,
     UserDetailFactory,
     UserFactory,
+    UserLookupResultFactory,
     VampireClanFactory,
     WerewolfAuspiceFactory,
     WerewolfTribeFactory,
@@ -110,6 +111,7 @@ __all__ = [
     "TraitSubcategoryFactory",
     "UserDetailFactory",
     "UserFactory",
+    "UserLookupResultFactory",
     "VampireClanFactory",
     "WerewolfAuspiceFactory",
     "WerewolfTribeFactory",

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/testing/_factories.py

@@ -43,6 +43,7 @@ from vclient.models import (
     TraitSubcategory,
     User,
     UserDetail,
+    UserLookupResult,
     VampireClan,
     WerewolfAuspice,
     WerewolfTribe,
@@ -259,6 +260,12 @@ class UserFactory(ModelFactory[User]):
     role = "PLAYER"
 
 
+class UserLookupResultFactory(ModelFactory[UserLookupResult]):
+    __model__ = UserLookupResult
+    __use_defaults__ = True
+    role = "PLAYER"
+
+
 class UserDetailFactory(ModelFactory[UserDetail]):
     __model__ = UserDetail
     __use_defaults__ = True
@@ -323,6 +330,7 @@ __all__ = [
     "TraitSubcategoryFactory",
     "UserDetailFactory",
     "UserFactory",
+    "UserLookupResultFactory",
     "VampireClanFactory",
     "WerewolfAuspiceFactory",
     "WerewolfTribeFactory",

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/testing/_router.py

@@ -48,6 +48,7 @@ from vclient.models import (
     TraitSubcategory,
     User,
     UserDetail,
+    UserLookupResult,
     VampireClan,
     WerewolfAuspice,
     WerewolfTribe,
@@ -91,6 +92,7 @@ from vclient.testing._factories import (
     TraitSubcategoryFactory,
     UserDetailFactory,
     UserFactory,
+    UserLookupResultFactory,
     VampireClanFactory,
     WerewolfAuspiceFactory,
     WerewolfTribeFactory,
@@ -133,6 +135,7 @@ _FACTORY_MAP: dict[type, type[ModelFactory]] = {
     TraitCategory: TraitCategoryFactory,
     TraitSubcategory: TraitSubcategoryFactory,
     User: UserFactory,
+    UserLookupResult: UserLookupResultFactory,
     UserDetail: UserDetailFactory,
     VampireClan: VampireClanFactory,
     WerewolfAuspice: WerewolfAuspiceFactory,

{valentina_python_client-1.20.0 → valentina_python_client-1.21.0}/src/vclient/testing/_routes.py

@@ -40,6 +40,7 @@ from vclient.models import (
     TraitSubcategory,
     User,
     UserDetail,
+    UserLookupResult,
     VampireClan,
     WerewolfAuspice,
     WerewolfTribe,
@@ -131,6 +132,8 @@ class Routes:
     USERS_REGISTER = RouteSpec("POST", Endpoints.USER_REGISTER, SINGLE, User)
     USERS_MERGE = RouteSpec("POST", Endpoints.USER_MERGE, SINGLE, User)
     USERS_STATISTICS = RouteSpec("GET", Endpoints.USER_STATISTICS, SINGLE, RollStatistics)
+    # User lookup (cross-company)
+    USERS_LOOKUP = RouteSpec("GET", Endpoints.USERS_LOOKUP, LIST, UserLookupResult)
 
     # User assets
     USERS_ASSETS_LIST = RouteSpec("GET", Endpoints.USER_ASSETS, PAGINATED, Asset)