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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 1.20.0
+Version: 1.20.1
 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.20.1}/pyproject.toml

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

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

@@ -105,4 +105,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "1.20.0"
+__version__ = "1.20.1"

{valentina_python_client-1.20.0 → valentina_python_client-1.20.1}/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.20.1}/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.20.1}/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.20.1}/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.20.0 → valentina_python_client-1.20.1}/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.
         """