Habiticalib 0.1.0a2__py3-none-any.whl → 0.2.0__py3-none-any.whl

habiticalib/lib.py

@@ -6,29 +6,40 @@ import asyncio
 from http import HTTPStatus
 from io import BytesIO
 import logging
-from typing import IO, TYPE_CHECKING, Self
+from typing import IO, TYPE_CHECKING, Any, Self
 
 from aiohttp import ClientError, ClientResponseError, ClientSession
+from habitipy.aio import HabitipyAsync  # type: ignore[import-untyped]
 from PIL import Image
 from yarl import URL
 
-from .const import ASSETS_URL, BACKER_ONLY_GEAR, DEFAULT_URL
+from .const import ASSETS_URL, BACKER_ONLY_GEAR, DEFAULT_URL, PAGE_LIMIT
 from .exceptions import (
     BadRequestError,
     NotAuthorizedError,
     NotFoundError,
     TooManyRequestsError,
 )
-from .helpers import extract_user_styles, get_user_agent, get_x_client, join_fields
+from .helpers import (
+    deserialize_task,
+    extract_user_styles,
+    get_user_agent,
+    get_x_client,
+    join_fields,
+)
 from .types import (
     Attributes,
-    Class,
     Direction,
+    HabiticaClass,
     HabiticaClassSystemResponse,
+    HabiticaContentResponse,
     HabiticaErrorResponse,
+    HabiticaGroupMembersResponse,
     HabiticaLoginResponse,
+    HabiticaQuestResponse,
     HabiticaResponse,
     HabiticaScoreResponse,
+    HabiticaSleepResponse,
     HabiticaStatsResponse,
     HabiticaTagResponse,
     HabiticaTagsResponse,
@@ -254,14 +265,15 @@ class Habitica:
         self,
         task_type: TaskFilter | None = None,
         due_date: datetime | None = None,
-    ) -> HabiticaResponse:
+    ) -> HabiticaTasksResponse:
         """Get the authenticated user's tasks.
 
         Parameters
         ----------
         task_type : TaskFilter | None
             The type of task to retrieve, defined in TaskFilter enum.
-            If `None`, all task types will be retrieved (default is None).
+            If `None`, all task types will be retrieved except completed to-dos
+            (default is None).
 
         due_date : datetime | None
             Optional date to use for computing the nextDue field for each returned task.
@@ -378,14 +390,16 @@ class Habitica:
 
         Examples
         --------
-        >>> new_task = Task(name="New Task", ...)
+        >>> new_task = Task(text="New Task", type=TaskType.TODO ...)
         >>> create_response = await habitica.create_task(new_task)
         >>> print(create_response.data)  # Displays the created task information
         """
         url = self.url / "api/v3/tasks/user"
 
+        json = deserialize_task(task)
+
         return HabiticaTaskResponse.from_json(
-            await self._request("post", url=url, json=task.to_dict()),
+            await self._request("post", url=url, json=json),
         )
 
     async def update_task(self, task_id: UUID, task: Task) -> HabiticaTaskResponse:
@@ -421,14 +435,16 @@ class Habitica:
         Examples
         --------
         >>> task_id = UUID("12345678-1234-5678-1234-567812345678")
-        >>> updated_task = Task(name="Updated Task", ...)
+        >>> updated_task = Task(text="Updated Task", ...)
         >>> update_response = await habitica.update_task(task_id, updated_task)
         >>> print(update_response.data)  # Displays the updated task information
         """
         url = self.url / "api/v3/tasks" / str(task_id)
 
+        json = deserialize_task(task)
+
         return HabiticaTaskResponse.from_json(
-            await self._request("put", url=url, json=task.to_dict()),
+            await self._request("put", url=url, json=json),
         )
 
     async def delete_task(self, task_id: UUID) -> HabiticaResponse:
@@ -445,7 +461,7 @@ class Habitica:
         Returns
         -------
         HabiticaTaskResponse
-            A response object containing the data for the deleted task.
+            A response containing an empty data object.
 
         Raises
         ------
@@ -549,7 +565,7 @@ class Habitica:
     async def get_content(
         self,
         language: Language | None = None,
-    ) -> HabiticaResponse:
+    ) -> HabiticaContentResponse:
         """
         Fetch game content from the Habitica API.
 
@@ -591,7 +607,7 @@ class Habitica:
         if language:
             params.update({"language": language.value})
 
-        return HabiticaResponse.from_json(
+        return HabiticaContentResponse.from_json(
             await self._request("get", url=url, params=params),
         )
 
@@ -799,14 +815,14 @@ class Habitica:
 
     async def cast_skill(
         self,
-        spell: Skill,
+        skill: Skill,
         target_id: UUID | None = None,
     ) -> HabiticaUserResponse:
         """Cast a skill (spell) in Habitica, optionally targeting a specific user, task or party.
 
         Parameters
         ----------
-        spell : Skill
+        skill : Skill
             The skill (or spell) to be cast. This should be a valid `Skill` enum value.
         target_id : UUID, optional
             The unique identifier of the target for the skill. If the skill does not require a target,
@@ -832,23 +848,23 @@ class Habitica:
         TimeoutError
             If the connection times out.
         """
-        url = self.url / "api/v3/class/cast" / spell
+        url = self.url / "api/v3/user/class/cast" / skill
         params = {}
 
         if target_id:
             params.update({"targetId": str(target_id)})
         return HabiticaUserResponse.from_json(
-            await self._request("post", url=url, json=params),
+            await self._request("post", url=url, params=params),
         )
 
     async def toggle_sleep(
         self,
-    ) -> HabiticaResponse:
+    ) -> HabiticaSleepResponse:
         """Toggles the user's sleep mode in Habitica.
 
         Returns
         -------
-        HabiticaResponse
+        HabiticaSleepResponse
             A response object containing the result of the sleep mode toggle,
             and the new sleep state (True if sleeping, False if not).
 
@@ -865,7 +881,7 @@ class Habitica:
         """
         url = self.url / "api/v3/user/sleep"
 
-        return HabiticaResponse.from_json(await self._request("post", url=url))
+        return HabiticaSleepResponse.from_json(await self._request("post", url=url))
 
     async def revive(
         self,
@@ -889,7 +905,7 @@ class Habitica:
 
         return HabiticaResponse.from_json(await self._request("post", url=url))
 
-    async def change_class(self, Class: Class) -> HabiticaClassSystemResponse:  # noqa: N803
+    async def change_class(self, Class: HabiticaClass) -> HabiticaClassSystemResponse:  # noqa: N803
         """Change the user's class in Habitica.
 
         This method sends a request to the Habitica API to change the user's class
@@ -920,7 +936,7 @@ class Habitica:
 
         Examples
         --------
-        >>> new_class = Class.WARRIOR
+        >>> new_class = HabiticaClass.WARRIOR
         >>> change_response = await habitica.change_class(new_class)
         >>> print(change_response.data.stats)  # Displays the user's stats after class change
         """
@@ -1068,7 +1084,7 @@ class Habitica:
         url = self.url / "api/v3/tags"
 
         return HabiticaTagsResponse.from_json(
-            await self._request("post", url=url),
+            await self._request("get", url=url),
         )
 
     async def get_tag(self, tag_id: UUID) -> HabiticaTagResponse:
@@ -1106,7 +1122,7 @@ class Habitica:
         url = self.url / "api/v3/tags" / str(tag_id)
 
         return HabiticaTagResponse.from_json(
-            await self._request("post", url=url),
+            await self._request("get", url=url),
         )
 
     async def delete_tag(self, tag_id: UUID) -> HabiticaResponse:
@@ -1266,10 +1282,447 @@ class Habitica:
         url = self.url / "api/v3/reorder-tags"
         json = {"tagId": str(tag_id), "to": to}
 
-        return HabiticaTagResponse.from_json(
+        return HabiticaResponse.from_json(
             await self._request("post", url=url, json=json),
         )
 
+    async def get_group_members(
+        self,
+        group_id: UUID | None = None,
+        *,
+        limit: int | None = None,
+        tasks: bool = False,
+        public_fields: bool = False,
+        last_id: UUID | None = None,
+    ) -> HabiticaGroupMembersResponse:
+        """Get members of the party or a specific group.
+
+        This method retrieves a list of members for a party or a specified group
+        from the Habitica API. Additional options allow including tasks or public
+        through results if necessary to collect all members. If the API rate limit is
+        exceeded, the method will pause for the duration specified in the `retry-after`
+        header and retry the request.
+
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group. Defaults to the user's party if not specified.
+        limit : int, optional
+            Maximum number of members per request (default: 30, max: 60).
+        tasks : bool, optional
+            Whether to include tasks associated with the group.
+        public_fields : bool, optional
+            Whether to include all public fields for group members.
+        last_id : UUID, optional
+            For paginated requests, the UUID of the last member retrieved.
+
+        Returns
+        -------
+        HabiticaGroupMembersResponse
+            A response object containing the group member data.
+
+        Raises
+        ------
+        aiohttp.ClientResponseError
+            For HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            For any other exceptions raised by aiohttp during the request.
+        TimeoutError
+            If the connection times out.
+
+        Examples
+        --------
+        >>> members_response = await habitica.get_group_members()
+        >>> for member in members_response.data:
+        ...     print(member.profile.name)
+        """
+
+        if limit is not None and (limit < 1 or limit > PAGE_LIMIT):
+            msg = f"The 'limit' parameter must be between 1 and {PAGE_LIMIT}."
+            raise ValueError(msg)
+
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "members"
+
+        params: dict[str, str | int] = {}
+
+        if tasks:
+            params["includeTasks"] = "true"
+        if public_fields:
+            params["includeAllPublicFields"] = "true"
+        if last_id:
+            params["lastId"] = str(last_id)
+        if limit:
+            params["limit"] = limit
+
+        while True:
+            try:
+                response = HabiticaGroupMembersResponse.from_json(
+                    await self._request("get", url=url, params=params),
+                )
+                break
+            except TooManyRequestsError as e:
+                await asyncio.sleep(e.retry_after)
+
+        if len(response.data) == limit:
+            next_page = await self.get_group_members(
+                group_id=group_id,
+                limit=limit,
+                tasks=tasks,
+                public_fields=public_fields,
+                last_id=response.data[-1].id,
+            )
+            response.data.extend(next_page.data)
+
+        return response
+
+    async def abort_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Abort an active quest for the party or a specific group.
+
+        Prematurely terminates an ongoing quest, causing all progress to be lost.
+        The quest scroll will be returned to the owner's inventory.
+        Only the quest leader or group leader is allowed to perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the specific group whose quest should be aborted.
+            Defaults to the user's party if not specified.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to abort the quest.
+        aiohttp.ClientResponseError
+            For HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            For any other exceptions raised by aiohttp during the request.
+        TimeoutError
+            If the connection times out.
+
+        Examples
+        --------
+        Abort the party's current quest:
+        >>> response = await habitica.abort_quest()
+        >>> print(response.success)  # True if the quest was successfully aborted.
+
+        Abort a quest for a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.abort_quest(group_id)
+        >>> print(response.success)  # True if the quest was successfully aborted.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/abort"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def accept_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Accept a pending invitation to a quest from the party or a specific group.
+
+        Allows a user to accept an invitation to participate in a quest within a
+        specified group.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitation is being accepted.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Accept a pending quest invitation from the party:
+        >>> response = await habitica.accept_quest()
+        >>> print(response.success)  # True if the quest invitation was successfully accepted.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/accept"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def reject_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Reject a pending quest invitation from the party or a specific group.
+
+        Allows a user to reject an invitation to participate in a quest within a
+        specified group. The user will not join the quest and will be excluded from
+        its progress and rewards.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitation is being rejected.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Reject a pending quest invitation from the party:
+        >>> response = await habitica.reject_quest()
+        >>> print(response.success)  # True if the quest invitation was successfully rejected.
+
+        Reject a pending quest invitation from a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.reject_quest(group_id)
+        >>> print(response.success)  # True if the quest invitation was successfully rejected.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/reject"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def cancel_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Cancel a pending quest for the party or a specific group.
+
+        Cancel a quest that has not yet startet. All accepted and pending invitations
+        will be canceled and the quest roll returned to the owner's inventory.
+        Only quest leader or group leader can perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest is being canceled.
+            Defaults to the user's party if not specified.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing details about the canceled quest.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to cancel the quest.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Cancel a pending quest for the party:
+        >>> response = await habitica.cancel_quest()
+        >>> print(response.success)  # True if the quest was successfully canceled.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/cancel"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def start_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Force-start a quest for the party or a specific group.
+
+        Begins a quest immediately, bypassing any pending invitations that haven't been
+        accepted or rejected.
+        Only quest leader or group leader can perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest should be started.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to start the quest.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Cancel a pending quest for the party:
+        >>> response = await habitica.cancel_quest()
+        >>> print(response.success)  # True if the quest was successfully canceled.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/force-start"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def invite_quest(
+        self,
+        group_id: UUID | None = None,
+        *,
+        quest_key: str,
+    ) -> HabiticaQuestResponse:
+        """Invite members of the party or a specific group to participate in a quest.
+
+        Sends invitations for a quest to all eligible members of the specified group.
+        The quest is started when all members accept or reject the invitation.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitations should be sent.
+            Defaults to the user's party if not specified.
+        quest_key : str
+            The unique key identifying the quest to invite members to.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Send a quest invitation to the party:
+        >>> response = await habitica.invite_quest(quest_key="dilatory_derby")
+        >>> print(response.success)  # True if invitations were successfully sent.
+
+        Send a quest invitation to a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.invite_quest(group_id, quest_key="golden_knight")
+        >>> print(response.success)  # True if invitations were successfully sent.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/invite" / quest_key
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def leave_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Leave the current quest from the party or a specific group.
+
+        Allows a user to exit an ongoing quest they are part of. This action removes
+        them from the quest but does not affect its progress for other participants.
+        Users who leave a quest will not contribute to its completion or receive rewards.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group associated with the quest the user is leaving.
+            Defaults to the user's party if not specified.
+        quest_key : str
+            The unique key identifying the quest to invite members to.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Leave the current quest in the user's party:
+        >>> response = await habitica.leave_quest()
+        >>> print(response.success)  # True if the user successfully left the quest.
+
+        Leave the current quest in a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.leave_quest(group_id)
+        >>> print(response.success)  # True if the user successfully left the quest.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/leave"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
     def _cache_asset(self, asset: str, asset_data: IO[bytes]) -> None:
         """Cache an asset and maintain the cache size limit by removing older entries.
 
@@ -1546,3 +1999,33 @@ class Habitica:
             image.save(fp, fmt)
 
         return user_styles
+
+    async def habitipy(self) -> HabitipyAsync:
+        """Create a Habitipy instance."""
+
+        _session = self._session
+        _headers = self._headers
+        loop = asyncio.get_running_loop()
+
+        class HAHabitipyAsync(HabitipyAsync):
+            """Closure API class to hold session."""
+
+            def __call__(self, **kwargs) -> Any:
+                """Pass session to habitipy."""
+                return super().__call__(_session, **kwargs)
+
+            def _make_headers(self) -> dict[str, str]:
+                """Inject headers."""
+                headers = super()._make_headers()
+                headers.update(_headers)
+                return headers
+
+        return await loop.run_in_executor(
+            None,
+            HAHabitipyAsync,
+            {
+                "url": str(self.url),
+                "login": self._headers.get("X-API-USER"),
+                "password": self._headers.get("X-API-KEY"),
+            },  # type: ignore[var-annotated]
+        )