valentina-python-client 2.7.0__tar.gz → 2.9.0__tar.gz

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 2.7.0
+Version: 2.9.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.7.0 → valentina_python_client-2.9.0}/pyproject.toml

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

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/__init__.py

@@ -116,4 +116,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "2.7.0"
+__version__ = "2.9.0"

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/base.py

@@ -592,6 +592,34 @@ class SyncBaseService:
             headers=self._build_idempotency_headers(idempotency_key),
         )
 
+    def _put_file(
+        self, path: str, *, file: tuple[str, bytes, str], idempotency_key: str | None = None
+    ) -> httpx.Response:
+        """Make a PUT request with a file upload (multipart/form-data).
+
+        Mirrors ``_post_file``: an idempotency key is sent only when supplied.
+
+        Args:
+            path: API endpoint path.
+            file: Tuple of (filename, content, content_type) for the file to upload.
+            idempotency_key: Optional idempotency key for safe retries.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            ServerError: When server error occurs and max retries are exhausted.
+            RateLimitError: When rate limit is exceeded and max retries are exhausted.
+            APIError: For other API error responses.
+        """
+        filename, content, content_type = file
+        return self._request(
+            "PUT",
+            path,
+            files={"data": (filename, content, content_type)},
+            headers=self._build_idempotency_headers(idempotency_key),
+        )
+
     def _get_paginated(
         self,
         path: str,

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/campaign_book_chapters.py

@@ -406,9 +406,17 @@ class SyncChaptersService(SyncBaseService):
     def upload_asset(
         self, chapter_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a chapter.
+        """Upload a new image asset for a chapter.
 
-        Uploads a file to S3 storage and associates it with the chapter.
+        Uploads an image to S3 storage and associates it with the chapter.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             chapter_id: The ID of the chapter to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/campaign_books.py

@@ -470,9 +470,17 @@ class SyncBooksService(SyncBaseService):
     def upload_asset(
         self, book_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a book.
+        """Upload a new image asset for a book.
 
-        Uploads a file to S3 storage and associates it with the book.
+        Uploads an image to S3 storage and associates it with the book.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             book_id: The ID of the book to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/campaigns.py

@@ -316,9 +316,17 @@ class SyncCampaignsService(SyncBaseService):
     def upload_asset(
         self, campaign_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a campaign.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the campaign.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             campaign_id: The ID of the campaign to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/characters.py

@@ -499,9 +499,17 @@ class SyncCharactersService(SyncBaseService):
     def upload_asset(
         self, character_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a character.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the character.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             character_id: The ID of the character to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/users.py

@@ -208,6 +208,37 @@ class SyncUsersService(SyncBaseService):
         )
         return User.model_validate(response.json())
 
+    def unlink_identity(self, user_id: str, *, provider: IdentityProvider) -> User:
+        """Disconnect a verified provider identity from a user.
+
+        The counterpart to link_identity for "disconnect your account" settings
+        flows: remove a single OAuth provider identity so it can no longer be
+        used to log in. Only the acting user themselves or a company ADMIN may
+        unlink identities. The provider's profile field on the returned User is
+        cleared to None.
+
+        The final remaining identity cannot be removed, since that would leave
+        the account unable to authenticate. Link another provider first.
+
+        Args:
+            user_id: The ID of the user losing the identity.
+            provider: The identity provider to disconnect.
+
+        Returns:
+            The updated User object with the provider's profile field cleared.
+
+        Raises:
+            AuthorizationError: If the acting user is neither the target user nor an admin.
+            NotFoundError: If the user has no identity from this provider
+                (code IDENTITY_NOT_LINKED).
+            ConflictError: If the provider is the user's only linked identity,
+                which cannot be removed (code LAST_IDENTITY).
+        """
+        response = self._delete(
+            self._format_endpoint(Endpoints.USER_IDENTITY, user_id=user_id, provider=provider)
+        )
+        return User.model_validate(response.json())
+
     def get_page(
         self,
         *,
@@ -526,9 +557,17 @@ class SyncUsersService(SyncBaseService):
     def upload_asset(
         self, user_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a user.
+        """Upload a new image asset for a user.
+
+        Uploads an image to S3 storage and associates it with the user.
 
-        Uploads a file to S3 storage and associates it with the user.
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             user_id: The ID of the user to upload the asset for.
@@ -552,6 +591,50 @@ class SyncUsersService(SyncBaseService):
         )
         return Asset.model_validate(response.json())
 
+    def upload_avatar(
+        self, user_id: str, filename: str, content: bytes, content_type: str | None = None
+    ) -> User:
+        """Upload a custom avatar for a user, replacing any existing one.
+
+        Accepts PNG, JPEG, WEBP, or GIF (first frame) up to 5 MB. The server
+        normalizes the image to a 512x512 WebP and it overrides any
+        identity-provider-derived avatar. Requires the ``On-Behalf-Of`` header
+        (permitted for the user themselves or an admin).
+
+        Args:
+            user_id: The ID of the user to set the avatar for.
+            filename: The original filename of the image.
+            content: The raw bytes of the image to upload.
+            content_type: The MIME type. If not provided, inferred from filename.
+
+        Returns:
+            The updated User object with the new ``avatar_url``.
+        """
+        if content_type is None:
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        response = self._put_file(
+            self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id),
+            file=(filename, content, content_type),
+        )
+        return User.model_validate(response.json())
+
+    def delete_avatar(self, user_id: str) -> User:
+        """Remove a user's custom avatar.
+
+        The avatar falls back to the identity-provider avatar, or ``None`` if
+        none exists. Requires the ``On-Behalf-Of`` header (permitted for the
+        user themselves or an admin). Responds 200 OK with the updated user
+        body (not 204).
+
+        Args:
+            user_id: The ID of the user whose custom avatar to remove.
+
+        Returns:
+            The updated User object with the resolved ``avatar_url``.
+        """
+        response = self._delete(self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id))
+        return User.model_validate(response.json())
+
     def get_experience(self, user_id: str, campaign_id: str) -> CampaignExperience:
         """Retrieve a user's experience points and cool points for a specific campaign.
 

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/endpoints.py

@@ -49,12 +49,14 @@ class Endpoints:
     USER = f"{USERS}/{{user_id}}"
     USER_MERGE = f"{USERS}/merge"
     USER_IDENTITIES = f"{USER}/identities"
+    USER_IDENTITY = f"{USER_IDENTITIES}/{{provider}}"
     USER_APPROVE = f"{USER}/approve"
     USER_DENY = f"{USER}/deny"
     USER_STATISTICS = f"{USER}/statistics"
     USER_ASSETS = f"{USER}/assets"
     USER_ASSET = f"{USER_ASSETS}/{{asset_id}}"
     USER_ASSET_UPLOAD = f"{USER_ASSETS}/upload"
+    USER_AVATAR = f"{USER}/avatar"
     USER_EXPERIENCE_CAMPAIGN = f"{USER}/experience/{{campaign_id}}"
     USER_EXPERIENCE_XP_ADD = f"{USER}/experience/xp/add"
     USER_EXPERIENCE_XP_REMOVE = f"{USER}/experience/xp/remove"

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/models/users.py

@@ -101,6 +101,10 @@ class User(BaseModel):
     google_profile: GoogleProfile | None = None
     github_profile: GitHubProfile | None = None
     apple_profile: AppleProfile | None = None
+    avatar_url: str | None = None
+    """Resolved avatar URL. Precedence: custom uploaded avatar (CloudFront URL),
+    then the identity-provider-derived avatar (currently Discord), else ``None``.
+    Prefer this over ``discord_profile.avatar_url`` for display."""
     campaign_experience: list[CampaignExperience] = Field(default_factory=list)
     asset_ids: list[str] = Field(default_factory=list)
     lifetime_xp: int = 0

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/base.py

@@ -667,6 +667,39 @@ class BaseService:
             headers=self._build_idempotency_headers(idempotency_key),
         )
 
+    async def _put_file(
+        self,
+        path: str,
+        *,
+        file: tuple[str, bytes, str],
+        idempotency_key: str | None = None,
+    ) -> httpx.Response:
+        """Make a PUT request with a file upload (multipart/form-data).
+
+        Mirrors ``_post_file``: an idempotency key is sent only when supplied.
+
+        Args:
+            path: API endpoint path.
+            file: Tuple of (filename, content, content_type) for the file to upload.
+            idempotency_key: Optional idempotency key for safe retries.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            ServerError: When server error occurs and max retries are exhausted.
+            RateLimitError: When rate limit is exceeded and max retries are exhausted.
+            APIError: For other API error responses.
+        """
+        filename, content, content_type = file
+
+        return await self._request(
+            "PUT",
+            path,
+            files={"data": (filename, content, content_type)},
+            headers=self._build_idempotency_headers(idempotency_key),
+        )
+
     # -------------------------------------------------------------------------
     # Pagination Methods
     # -------------------------------------------------------------------------

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/campaign_book_chapters.py

@@ -486,9 +486,17 @@ class ChaptersService(BaseService):
         content: bytes,
         content_type: str | None = None,
     ) -> Asset:
-        """Upload a new asset for a chapter.
+        """Upload a new image asset for a chapter.
 
-        Uploads a file to S3 storage and associates it with the chapter.
+        Uploads an image to S3 storage and associates it with the chapter.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             chapter_id: The ID of the chapter to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/campaign_books.py

@@ -562,9 +562,17 @@ class BooksService(BaseService):
         content: bytes,
         content_type: str | None = None,
     ) -> Asset:
-        """Upload a new asset for a book.
+        """Upload a new image asset for a book.
 
-        Uploads a file to S3 storage and associates it with the book.
+        Uploads an image to S3 storage and associates it with the book.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             book_id: The ID of the book to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/campaigns.py

@@ -380,9 +380,17 @@ class CampaignsService(BaseService):
         content: bytes,
         content_type: str | None = None,
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a campaign.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the campaign.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             campaign_id: The ID of the campaign to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/characters.py

@@ -555,9 +555,17 @@ class CharactersService(BaseService):
         content: bytes,
         content_type: str | None = None,
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a character.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the character.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             character_id: The ID of the character to upload the asset for.

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/services/users.py

@@ -242,6 +242,42 @@ class UsersService(BaseService):
         )
         return User.model_validate(response.json())
 
+    async def unlink_identity(
+        self,
+        user_id: str,
+        *,
+        provider: IdentityProvider,
+    ) -> User:
+        """Disconnect a verified provider identity from a user.
+
+        The counterpart to link_identity for "disconnect your account" settings
+        flows: remove a single OAuth provider identity so it can no longer be
+        used to log in. Only the acting user themselves or a company ADMIN may
+        unlink identities. The provider's profile field on the returned User is
+        cleared to None.
+
+        The final remaining identity cannot be removed, since that would leave
+        the account unable to authenticate. Link another provider first.
+
+        Args:
+            user_id: The ID of the user losing the identity.
+            provider: The identity provider to disconnect.
+
+        Returns:
+            The updated User object with the provider's profile field cleared.
+
+        Raises:
+            AuthorizationError: If the acting user is neither the target user nor an admin.
+            NotFoundError: If the user has no identity from this provider
+                (code IDENTITY_NOT_LINKED).
+            ConflictError: If the provider is the user's only linked identity,
+                which cannot be removed (code LAST_IDENTITY).
+        """
+        response = await self._delete(
+            self._format_endpoint(Endpoints.USER_IDENTITY, user_id=user_id, provider=provider),
+        )
+        return User.model_validate(response.json())
+
     # User CRUD Methods
 
     async def get_page(
@@ -620,9 +656,17 @@ class UsersService(BaseService):
         content: bytes,
         content_type: str | None = None,
     ) -> Asset:
-        """Upload a new asset for a user.
+        """Upload a new image asset for a user.
 
-        Uploads a file to S3 storage and associates it with the user.
+        Uploads an image to S3 storage and associates it with the user.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             user_id: The ID of the user to upload the asset for.
@@ -647,6 +691,59 @@ class UsersService(BaseService):
         )
         return Asset.model_validate(response.json())
 
+    # Avatar Methods
+
+    async def upload_avatar(
+        self,
+        user_id: str,
+        filename: str,
+        content: bytes,
+        content_type: str | None = None,
+    ) -> User:
+        """Upload a custom avatar for a user, replacing any existing one.
+
+        Accepts PNG, JPEG, WEBP, or GIF (first frame) up to 5 MB. The server
+        normalizes the image to a 512x512 WebP and it overrides any
+        identity-provider-derived avatar. Requires the ``On-Behalf-Of`` header
+        (permitted for the user themselves or an admin).
+
+        Args:
+            user_id: The ID of the user to set the avatar for.
+            filename: The original filename of the image.
+            content: The raw bytes of the image to upload.
+            content_type: The MIME type. If not provided, inferred from filename.
+
+        Returns:
+            The updated User object with the new ``avatar_url``.
+        """
+        if content_type is None:
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+        response = await self._put_file(
+            self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id),
+            file=(filename, content, content_type),
+        )
+        return User.model_validate(response.json())
+
+    async def delete_avatar(self, user_id: str) -> User:
+        """Remove a user's custom avatar.
+
+        The avatar falls back to the identity-provider avatar, or ``None`` if
+        none exists. Requires the ``On-Behalf-Of`` header (permitted for the
+        user themselves or an admin). Responds 200 OK with the updated user
+        body (not 204).
+
+        Args:
+            user_id: The ID of the user whose custom avatar to remove.
+
+        Returns:
+            The updated User object with the resolved ``avatar_url``.
+        """
+        response = await self._delete(
+            self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id),
+        )
+        return User.model_validate(response.json())
+
     # Experience Methods
 
     async def get_experience(

{valentina_python_client-2.7.0 → valentina_python_client-2.9.0}/src/vclient/testing/_routes.py

@@ -149,6 +149,7 @@ class Routes:
     USERS_DENY = RouteSpec("POST", Endpoints.USER_DENY, NO_CONTENT, None)
     USERS_MERGE = RouteSpec("POST", Endpoints.USER_MERGE, SINGLE, User)
     USERS_IDENTITY_LINK = RouteSpec("POST", Endpoints.USER_IDENTITIES, SINGLE, User)
+    USERS_IDENTITY_UNLINK = RouteSpec("DELETE", Endpoints.USER_IDENTITY, SINGLE, User)
 
     USERS_STATISTICS = RouteSpec("GET", Endpoints.USER_STATISTICS, SINGLE, RollStatistics)
     # User lookup (cross-company)
@@ -163,6 +164,10 @@ class Routes:
     USERS_ASSETS_DELETE = RouteSpec("DELETE", Endpoints.USER_ASSET, NO_CONTENT, None)
     USERS_ASSETS_UPLOAD = RouteSpec("POST", Endpoints.USER_ASSET_UPLOAD, SINGLE, Asset)
 
+    # User avatar
+    USERS_AVATAR_UPLOAD = RouteSpec("PUT", Endpoints.USER_AVATAR, SINGLE, User)
+    USERS_AVATAR_DELETE = RouteSpec("DELETE", Endpoints.USER_AVATAR, SINGLE, User)
+
     # User experience
     USERS_EXPERIENCE_GET = RouteSpec(
         "GET", Endpoints.USER_EXPERIENCE_CAMPAIGN, SINGLE, CampaignExperience