bloomy-python 0.12.1__py3-none-any.whl

bloomy/operations/__init__.py

@@ -0,0 +1,19 @@
+"""API operations for the Bloomy SDK."""
+
+from .goals import GoalOperations
+from .headlines import HeadlineOperations
+from .issues import IssueOperations
+from .meetings import MeetingOperations
+from .scorecard import ScorecardOperations
+from .todos import TodoOperations
+from .users import UserOperations
+
+__all__ = [
+    "GoalOperations",
+    "HeadlineOperations",
+    "IssueOperations",
+    "MeetingOperations",
+    "ScorecardOperations",
+    "TodoOperations",
+    "UserOperations",
+]

bloomy/operations/goals.py

@@ -0,0 +1,270 @@
+"""Goal operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING
+
+from ..models import ArchivedGoalInfo, CreatedGoalInfo, GoalInfo, GoalListResponse
+from ..utils.base_operations import BaseOperations
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class GoalOperations(BaseOperations):
+    """Class to handle all the operations related to goals (also known as "rocks").
+
+    Note:
+        This class is already initialized via the client and usable as
+        `client.goal.method`
+    """
+
+    def list(
+        self, user_id: int | None = None, archived: bool = False
+    ) -> builtins.list[GoalInfo] | GoalListResponse:
+        """List all goals for a specific user.
+
+        Args:
+            user_id: The ID of the user (default is the initialized user ID)
+            archived: Whether to include archived goals (default: False)
+
+        Returns:
+            Either:
+            - A list of GoalInfo model instances if archived is false
+            - A GoalListResponse model with 'active' and 'archived' lists of
+                GoalInfo instances if archived is true
+
+        Examples:
+            List active goals:
+            ```python
+            client.goal.list()
+            # Returns: [GoalInfo(id=1, title='Complete project', ...)]
+            ```
+
+            List both active and archived goals:
+            ```python
+            client.goal.list(archived=True)
+            # Returns: GoalListResponse(
+            #     active=[GoalInfo(id=1, ...)],
+            #     archived=[ArchivedGoalInfo(id=2, ...)]
+            # )
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        response = self._client.get(
+            f"rocks/user/{user_id}", params={"include_origin": True}
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        active_goals: list[GoalInfo] = []
+        for goal in data:
+            active_goals.append(
+                GoalInfo(
+                    id=goal["Id"],
+                    user_id=goal["Owner"]["Id"],
+                    user_name=goal["Owner"]["Name"],
+                    title=goal["Name"],
+                    created_at=goal["CreateTime"],
+                    due_date=goal["DueDate"],
+                    status="Completed" if goal.get("Complete") else "Incomplete",
+                    meeting_id=goal["Origins"][0]["Id"]
+                    if goal.get("Origins")
+                    else None,
+                    meeting_title=goal["Origins"][0]["Name"]
+                    if goal.get("Origins")
+                    else None,
+                )
+            )
+
+        if archived:
+            archived_goals = self._get_archived_goals(user_id)
+            return GoalListResponse(active=active_goals, archived=archived_goals)
+
+        return active_goals
+
+    def create(
+        self, title: str, meeting_id: int, user_id: int | None = None
+    ) -> CreatedGoalInfo:
+        """Create a new goal.
+
+        Args:
+            title: The title of the new goal
+            meeting_id: The ID of the meeting associated with the goal
+            user_id: The ID of the user responsible for the goal (default:
+                initialized user ID)
+
+        Returns:
+            A CreatedGoalInfo model instance representing the newly created goal
+
+        Example:
+            ```python
+            client.goal.create(title="New Goal", meeting_id=1)
+            # Returns: CreatedGoalInfo(id=1, title='New Goal', meeting_id=1, ...)
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        payload = {"title": title, "accountableUserId": user_id}
+        response = self._client.post(f"L10/{meeting_id}/rocks", json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        # Map completion status
+        completion_map = {2: "complete", 1: "on", 0: "off"}
+        status = completion_map.get(data.get("Completion", 0), "off")
+
+        return CreatedGoalInfo(
+            id=data["Id"],
+            user_id=user_id,
+            user_name=data["Owner"]["Name"],
+            title=title,
+            meeting_id=meeting_id,
+            meeting_title=data["Origins"][0]["Name"],
+            status=status,
+            created_at=data["CreateTime"],
+        )
+
+    def delete(self, goal_id: int) -> bool:
+        """Delete a goal.
+
+        Args:
+            goal_id: The ID of the goal to delete
+
+        Returns:
+            True if deletion was successful
+
+        Example:
+            ```python
+            client.goal.delete(1)
+            # Returns: True
+            ```
+        """
+        response = self._client.delete(f"rocks/{goal_id}")
+        response.raise_for_status()
+        return True
+
+    def update(
+        self,
+        goal_id: int,
+        title: str | None = None,
+        accountable_user: int | None = None,
+        status: str | None = None,
+    ) -> bool:
+        """Update a goal.
+
+        Args:
+            goal_id: The ID of the goal to update
+            title: The new title of the goal
+            accountable_user: The ID of the user responsible for the goal
+                (default: initialized user ID)
+            status: The status value ('on', 'off', or 'complete')
+
+        Returns:
+            True if the update was successful
+
+        Raises:
+            ValueError: If an invalid status value is provided
+
+        Example:
+            ```python
+            client.goal.update(goal_id=1, title="Updated Goal", status='on')
+            # Returns: True
+            ```
+        """
+        if accountable_user is None:
+            accountable_user = self.user_id
+
+        payload: dict[str, Any] = {"accountableUserId": accountable_user}
+
+        if title is not None:
+            payload["title"] = title
+
+        if status is not None:
+            valid_status = {"on": "OnTrack", "off": "AtRisk", "complete": "Complete"}
+            status_key = status.lower()
+            if status_key not in valid_status:
+                raise ValueError(
+                    "Invalid status value. Must be 'on', 'off', or 'complete'."
+                )
+            payload["completion"] = valid_status[status_key]
+
+        response = self._client.put(f"rocks/{goal_id}", json=payload)
+        response.raise_for_status()
+        return True
+
+    def archive(self, goal_id: int) -> bool:
+        """Archive a rock with the specified goal ID.
+
+        Args:
+            goal_id: The ID of the goal/rock to archive
+
+        Returns:
+            True if the archival was successful, False otherwise
+
+        Example:
+            ```python
+            goals.archive(123)
+            # Returns: True
+            ```
+        """
+        response = self._client.put(f"rocks/{goal_id}/archive")
+        response.raise_for_status()
+        return True
+
+    def restore(self, goal_id: int) -> bool:
+        """Restore a previously archived goal identified by the provided goal ID.
+
+        Args:
+            goal_id: The unique identifier of the goal to restore
+
+        Returns:
+            True if the restore operation was successful, False otherwise
+
+        Example:
+            ```python
+            goals.restore(123)
+            # Returns: True
+            ```
+        """
+        response = self._client.put(f"rocks/{goal_id}/restore")
+        response.raise_for_status()
+        return True
+
+    def _get_archived_goals(self, user_id: int | None = None) -> list[ArchivedGoalInfo]:
+        """Retrieve all archived goals for a specific user (private method).
+
+        Args:
+            user_id: The ID of the user (default is the initialized user ID)
+
+        Returns:
+            A list of ArchivedGoalInfo model instances containing archived goal details
+
+        Example:
+            ```python
+            goal._get_archived_goals()
+            # Returns: [ArchivedGoalInfo(id=1, title='Archived Goal',
+            #                           created_at='2024-06-10', ...), ...]
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        response = self._client.get(f"archivedrocks/user/{user_id}")
+        response.raise_for_status()
+        data = response.json()
+
+        return [
+            ArchivedGoalInfo(
+                id=goal["Id"],
+                title=goal["Name"],
+                created_at=goal["CreateTime"],
+                due_date=goal["DueDate"],
+                status="Complete" if goal.get("Complete") else "Incomplete",
+            )
+            for goal in data
+        ]

bloomy/operations/headlines.py

@@ -0,0 +1,199 @@
+"""Headline operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+
+from ..models import (
+    HeadlineDetails,
+    HeadlineInfo,
+    HeadlineListItem,
+    MeetingInfo,
+    OwnerDetails,
+)
+from ..utils.base_operations import BaseOperations
+
+
+class HeadlineOperations(BaseOperations):
+    """Class to handle all operations related to headlines."""
+
+    def create(
+        self,
+        meeting_id: int,
+        title: str,
+        owner_id: int | None = None,
+        notes: str | None = None,
+    ) -> HeadlineInfo:
+        """Create a new headline.
+
+        Args:
+            meeting_id: The ID of the meeting
+            title: The title of the headline
+            owner_id: The ID of the headline owner (default: current user ID)
+            notes: Additional notes for the headline
+
+        Returns:
+            A HeadlineInfo model instance containing id, title, owner_details,
+            and notes_url
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails
+        """
+        if owner_id is None:
+            owner_id = self.user_id
+
+        payload = {"title": title, "ownerId": owner_id}
+        if notes is not None:
+            payload["notes"] = notes
+
+        response = self._client.post(f"L10/{meeting_id}/headlines", json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        return HeadlineInfo(
+            id=data["Id"],
+            title=data["Name"],
+            owner_details=OwnerDetails(id=owner_id, name=None),
+            notes_url=data.get("DetailsUrl", ""),
+        )
+
+    def update(self, headline_id: int, title: str) -> bool:
+        """Update a headline.
+
+        Args:
+            headline_id: The ID of the headline to update
+            title: The new title of the headline
+
+        Returns:
+            True if update was successful
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails
+        """
+        payload = {"title": title}
+        response = self._client.put(f"headline/{headline_id}", json=payload)
+        response.raise_for_status()
+        return True
+
+    def details(self, headline_id: int) -> HeadlineDetails:
+        """Get headline details.
+
+        Args:
+            headline_id: The ID of the headline
+
+        Returns:
+            A HeadlineDetails model instance containing id, title, notes_url,
+            meeting_details, owner_details, archived, created_at, and closed_at
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails
+        """
+        response = self._client.get(
+            f"headline/{headline_id}", params={"Include_Origin": "true"}
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        return HeadlineDetails(
+            id=data["Id"],
+            title=data["Name"],
+            notes_url=data["DetailsUrl"],
+            meeting_details=MeetingInfo(
+                id=data["OriginId"],
+                title=data["Origin"],
+            ),
+            owner_details=OwnerDetails(
+                id=data["Owner"]["Id"],
+                name=data["Owner"]["Name"],
+            ),
+            archived=data["Archived"],
+            created_at=data["CreateTime"],
+            closed_at=data["CloseTime"],
+        )
+
+    def list(
+        self, user_id: int | None = None, meeting_id: int | None = None
+    ) -> builtins.list[HeadlineListItem]:
+        """Get headlines for a user or a meeting.
+
+        Args:
+            user_id: The ID of the user (defaults to initialized user_id)
+            meeting_id: The ID of the meeting
+
+        Returns:
+            A list of HeadlineListItem model instances containing:
+            - id
+            - title
+            - meeting_details
+            - owner_details
+            - archived
+            - created_at
+            - closed_at
+
+        Raises:
+            ValueError: If both user_id and meeting_id are provided
+            httpx.HTTPStatusError: If the API request fails
+
+        Example:
+            ```python
+            client.headline.list()
+            # Returns: [
+            #     HeadlineListItem(
+            #         id=1,
+            #         title='Headline Title',
+            #         meeting_details=MeetingInfo(id=1, title='Team Meeting'),
+            #         owner_details=OwnerDetails(id=1, name='John Doe'),
+            #         archived=False,
+            #         created_at='2023-01-01',
+            #         closed_at=None
+            #     )
+            # ]
+            ```
+        """
+        if user_id and meeting_id:
+            raise ValueError("Please provide either user_id or meeting_id, not both.")
+
+        if meeting_id:
+            response = self._client.get(f"l10/{meeting_id}/headlines")
+        else:
+            if user_id is None:
+                user_id = self.user_id
+            response = self._client.get(f"headline/users/{user_id}")
+
+        response.raise_for_status()
+        data = response.json()
+
+        return [
+            HeadlineListItem(
+                id=headline["Id"],
+                title=headline["Name"],
+                meeting_details=MeetingInfo(
+                    id=headline["OriginId"],
+                    title=headline["Origin"],
+                ),
+                owner_details=OwnerDetails(
+                    id=headline["Owner"]["Id"],
+                    name=headline["Owner"]["Name"],
+                ),
+                archived=headline["Archived"],
+                created_at=headline["CreateTime"],
+                closed_at=headline["CloseTime"],
+            )
+            for headline in data
+        ]
+
+    def delete(self, headline_id: int) -> bool:
+        """Delete a headline.
+
+        Args:
+            headline_id: The ID of the headline to delete
+
+        Returns:
+            True if the deletion was successful
+
+        Raises:
+            httpx.HTTPStatusError: If the API request fails
+        """
+        response = self._client.delete(f"headline/{headline_id}")
+        response.raise_for_status()
+        return True

bloomy/operations/issues.py

@@ -0,0 +1,187 @@
+"""Issue operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+
+from ..models import CreatedIssue, IssueDetails, IssueListItem
+from ..utils.base_operations import BaseOperations
+
+
+class IssueOperations(BaseOperations):
+    """Class to handle all operations related to issues.
+
+    Provides functionality to create, retrieve, list, and solve issues
+    associated with meetings and users.
+    """
+
+    def details(self, issue_id: int) -> IssueDetails:
+        """Retrieve detailed information about a specific issue.
+
+        Args:
+            issue_id: Unique identifier of the issue
+
+        Returns:
+            An IssueDetails model instance containing detailed information
+            about the issue
+
+        Raises:
+            httpx.HTTPError: When the API request fails or returns invalid data
+
+        Example:
+            ```python
+            client.issue.details(123)
+            # Returns: IssueDetails(id=123, title='Issue Title',
+            #          created_at='2024-06-10', ...)
+            ```
+        """
+        response = self._client.get(f"issues/{issue_id}")
+        response.raise_for_status()
+        data = response.json()
+
+        return IssueDetails(
+            id=data["Id"],
+            title=data["Name"],
+            notes_url=data["DetailsUrl"],
+            created_at=data["CreateTime"],
+            completed_at=data["CloseTime"],
+            meeting_id=data["OriginId"],
+            meeting_title=data["Origin"],
+            user_id=data["Owner"]["Id"],
+            user_name=data["Owner"]["Name"],
+        )
+
+    def list(
+        self, user_id: int | None = None, meeting_id: int | None = None
+    ) -> builtins.list[IssueListItem]:
+        """List issues filtered by user or meeting.
+
+        Args:
+            user_id: Unique identifier of the user (optional)
+            meeting_id: Unique identifier of the meeting (optional)
+
+        Returns:
+            A list of IssueListItem model instances matching the filter criteria
+
+        Raises:
+            ValueError: When both user_id and meeting_id are provided
+            httpx.HTTPError: When the API request fails or returns invalid data
+
+        Example:
+            ```python
+            # List issues for current user
+            client.issue.list()
+            # Returns: [IssueListItem(id=1, title='Issue 1', ...), ...]
+
+            # List issues for specific meeting
+            client.issue.list(meeting_id=456)
+            # Returns: [IssueListItem(id=2, title='Issue 2', ...), ...]
+            ```
+        """
+        if user_id and meeting_id:
+            raise ValueError(
+                "Please provide either `user_id` or `meeting_id`, not both."
+            )
+
+        if meeting_id:
+            response = self._client.get(f"l10/{meeting_id}/issues")
+        else:
+            if user_id is None:
+                user_id = self.user_id
+            response = self._client.get(f"issues/users/{user_id}")
+
+        response.raise_for_status()
+        data = response.json()
+
+        return [
+            IssueListItem(
+                id=issue["Id"],
+                title=issue["Name"],
+                notes_url=issue["DetailsUrl"],
+                created_at=issue["CreateTime"],
+                meeting_id=issue["OriginId"],
+                meeting_title=issue["Origin"],
+            )
+            for issue in data
+        ]
+
+    def solve(self, issue_id: int) -> bool:
+        """Mark an issue as completed/solved.
+
+        Args:
+            issue_id: Unique identifier of the issue to be solved
+
+        Returns:
+            True if issue was successfully solved
+
+        Raises:
+            httpx.HTTPError: When the API request fails
+
+        Example:
+            ```python
+            client.issue.solve(123)
+            # Returns: True
+            ```
+        """
+        response = self._client.post(
+            f"issues/{issue_id}/complete", json={"complete": True}
+        )
+        response.raise_for_status()
+        return True
+
+    def create(
+        self,
+        meeting_id: int,
+        title: str,
+        user_id: int | None = None,
+        notes: str | None = None,
+    ) -> CreatedIssue:
+        """Create a new issue in the system.
+
+        Args:
+            meeting_id: Unique identifier of the associated meeting
+            title: Title/name of the issue
+            user_id: Unique identifier of the issue owner (defaults to current user)
+            notes: Additional notes or description for the issue (optional)
+
+        Returns:
+            A CreatedIssue model instance containing the newly created issue details
+
+        Raises:
+            httpx.HTTPError: When the API request fails or returns invalid data
+            ValueError: When required parameters are missing or invalid
+
+        Example:
+            ```python
+            client.issue.create(
+                meeting_id=123,
+                title="New Issue",
+                notes="This is a detailed description"
+            )
+            # Returns: CreatedIssue(id=456, title='New Issue', meeting_id=123, ...)
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        payload = {
+            "title": title,
+            "meetingid": meeting_id,
+            "ownerid": user_id,
+        }
+
+        if notes is not None:
+            payload["notes"] = notes
+
+        response = self._client.post("issues/create", json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        return CreatedIssue(
+            id=data["Id"],
+            meeting_id=data["OriginId"],
+            meeting_title=data["Origin"],
+            title=data["Name"],
+            user_id=data["Owner"]["Id"],
+            notes_url=data["DetailsUrl"],
+        )