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

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

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

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

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

{valentina_python_client-2.8.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.8.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.8.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.8.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.8.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.8.0 → valentina_python_client-2.9.0}/src/vclient/_sync/services/users.py

@@ -557,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 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.
@@ -583,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.8.0 → valentina_python_client-2.9.0}/src/vclient/endpoints.py

@@ -56,6 +56,7 @@ class Endpoints:
     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.8.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.8.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.8.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.8.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.8.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.8.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.8.0 → valentina_python_client-2.9.0}/src/vclient/services/users.py

@@ -656,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.
@@ -683,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.8.0 → valentina_python_client-2.9.0}/src/vclient/testing/_routes.py

@@ -164,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