bloomy-python 0.12.1__py3-none-any.whl

bloomy/operations/meetings.py

@@ -0,0 +1,304 @@
+"""Meeting operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from ..exceptions import APIError
+from ..models import (
+    Issue,
+    MeetingAttendee,
+    MeetingDetails,
+    MeetingListItem,
+    ScorecardMetric,
+    Todo,
+)
+from ..utils.base_operations import BaseOperations
+
+
+class MeetingOperations(BaseOperations):
+    """Class to handle all operations related to meetings.
+
+    Note:
+        This class is already initialized via the client and usable as
+        `client.meeting.method`
+    """
+
+    def list(self, user_id: int | None = None) -> builtins.list[MeetingListItem]:
+        """List all meetings for a specific user.
+
+        Args:
+            user_id: The ID of the user (default is the initialized user ID)
+
+        Returns:
+            A list of MeetingListItem model instances
+
+        Example:
+            ```python
+            client.meeting.list()
+            # Returns: [MeetingListItem(id=123, name="Team Meeting", ...), ...]
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        response = self._client.get(f"L10/{user_id}/list")
+        response.raise_for_status()
+        data: Any = response.json()
+
+        return [MeetingListItem.model_validate(meeting) for meeting in data]
+
+    def attendees(self, meeting_id: int) -> builtins.list[MeetingAttendee]:
+        """List all attendees for a specific meeting.
+
+        Args:
+            meeting_id: The ID of the meeting
+
+        Returns:
+            A list of MeetingAttendee model instances
+
+        Example:
+            ```python
+            client.meeting.attendees(1)
+            # Returns: [MeetingAttendee(user_id=1, name='John Doe',
+            #          image_url='...'), ...]
+            ```
+        """
+        response = self._client.get(f"L10/{meeting_id}/attendees")
+        response.raise_for_status()
+        data: Any = response.json()
+
+        return [
+            MeetingAttendee(
+                UserId=attendee["Id"],
+                Name=attendee["Name"],
+                ImageUrl=attendee.get("ImageUrl", ""),
+            )
+            for attendee in data
+        ]
+
+    def issues(
+        self, meeting_id: int, include_closed: bool = False
+    ) -> builtins.list[Issue]:
+        """List all issues for a specific meeting.
+
+        Args:
+            meeting_id: The ID of the meeting
+            include_closed: Whether to include closed issues (default: False)
+
+        Returns:
+            A list of Issue model instances
+
+        Example:
+            ```python
+            client.meeting.issues(1)
+            # Returns: [Issue(id=1, name='Issue Title',
+            #          created_at='2024-06-10', ...), ...]
+            ```
+        """
+        response = self._client.get(
+            f"L10/{meeting_id}/issues",
+            params={"include_resolved": include_closed},
+        )
+        response.raise_for_status()
+        data: Any = response.json()
+
+        return [
+            Issue(
+                Id=issue["Id"],
+                Name=issue["Name"],
+                DetailsUrl=issue["DetailsUrl"],
+                CreateDate=issue["CreateTime"],
+                ClosedDate=issue["CloseTime"],
+                CompletionDate=issue["CloseTime"],
+                OwnerId=issue.get("Owner", {}).get("Id", 0),
+                OwnerName=issue.get("Owner", {}).get("Name", ""),
+                OwnerImageUrl=issue.get("Owner", {}).get("ImageUrl", ""),
+                MeetingId=meeting_id,
+                MeetingName=issue["Origin"],
+            )
+            for issue in data
+        ]
+
+    def todos(
+        self, meeting_id: int, include_closed: bool = False
+    ) -> builtins.list[Todo]:
+        """List all todos for a specific meeting.
+
+        Args:
+            meeting_id: The ID of the meeting
+            include_closed: Whether to include closed todos (default: False)
+
+        Returns:
+            A list of Todo model instances
+
+        Example:
+            ```python
+            client.meeting.todos(1)
+            # Returns: [Todo(id=1, name='Todo Title', due_date='2024-06-12', ...), ...]
+            ```
+        """
+        response = self._client.get(
+            f"L10/{meeting_id}/todos",
+            params={"INCLUDE_CLOSED": include_closed},
+        )
+        response.raise_for_status()
+        data: Any = response.json()
+
+        return [Todo.model_validate(todo) for todo in data]
+
+    def metrics(self, meeting_id: int) -> builtins.list[ScorecardMetric]:
+        """List all metrics for a specific meeting.
+
+        Args:
+            meeting_id: The ID of the meeting
+
+        Returns:
+            A list of ScorecardMetric model instances
+
+        Example:
+            ```python
+            client.meeting.metrics(1)
+            # Returns: [ScorecardMetric(id=1, title='Sales', target=100.0,
+            #           metric_type='>', unit='currency', ...), ...]
+            ```
+        """
+        response = self._client.get(f"L10/{meeting_id}/measurables")
+        response.raise_for_status()
+        raw_data = response.json()
+
+        if not isinstance(raw_data, list):
+            return []
+
+        metrics: list[ScorecardMetric] = []
+        # Type the list explicitly
+        data_list: list[Any] = raw_data  # type: ignore[assignment]
+        for item in data_list:
+            if not isinstance(item, dict):
+                continue
+
+            # Cast to Any dict to satisfy type checker
+            item_dict: dict[str, Any] = item  # type: ignore[assignment]
+            measurable_id = item_dict.get("Id")
+            measurable_name = item_dict.get("Name")
+
+            if not measurable_id or not measurable_name:
+                continue
+
+            owner_data = item_dict.get("Owner", {})
+            if not isinstance(owner_data, dict):
+                owner_data = {}
+            owner_dict: dict[str, Any] = owner_data  # type: ignore[assignment]
+
+            metrics.append(
+                ScorecardMetric(
+                    Id=int(measurable_id),
+                    Title=str(measurable_name).strip(),
+                    Target=float(item_dict.get("Target", 0)),
+                    Unit=str(item_dict.get("Modifiers", "")),
+                    WeekNumber=0,  # Not provided in this endpoint
+                    Value=None,
+                    MetricType=str(item_dict.get("Direction", "")),
+                    AccountableUserId=int(owner_dict.get("Id") or 0),
+                    AccountableUserName=str(owner_dict.get("Name") or ""),
+                    IsInverse=False,
+                )
+            )
+
+        return metrics
+
+    def details(self, meeting_id: int, include_closed: bool = False) -> MeetingDetails:
+        """Retrieve details of a specific meeting.
+
+        Args:
+            meeting_id: The ID of the meeting
+            include_closed: Whether to include closed issues and todos (default: False)
+
+        Returns:
+            A MeetingDetails model instance with comprehensive meeting information
+
+        Example:
+            ```python
+            client.meeting.details(1)
+            # Returns: MeetingDetails(id=1, name='Team Meeting', attendees=[...],
+            #                        issues=[...], todos=[...], metrics=[...])
+            ```
+        """
+        meetings = self.list()
+        meeting = next((m for m in meetings if m.id == meeting_id), None)
+
+        if not meeting:
+            raise APIError(f"Meeting with ID {meeting_id} not found", status_code=404)
+
+        return MeetingDetails(
+            id=meeting.id,
+            name=meeting.name,
+            start_date_utc=getattr(meeting, "start_date_utc", None),
+            created_date=getattr(meeting, "created_date", None),
+            organization_id=getattr(meeting, "organization_id", None),
+            attendees=self.attendees(meeting_id),
+            issues=self.issues(meeting_id, include_closed=include_closed),
+            todos=self.todos(meeting_id, include_closed=include_closed),
+            metrics=self.metrics(meeting_id),
+        )
+
+    def create(
+        self,
+        title: str,
+        add_self: bool = True,
+        attendees: builtins.list[int] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new meeting.
+
+        Args:
+            title: The title of the new meeting
+            add_self: Whether to add the current user as an attendee (default: True)
+            attendees: A list of user IDs to add as attendees
+
+        Returns:
+            A dictionary containing meeting_id, title and attendees array
+
+        Example:
+            ```python
+            client.meeting.create("New Meeting", attendees=[2, 3])
+            # Returns: {"meeting_id": 1, "title": "New Meeting", "attendees": [2, 3]}
+            ```
+        """
+        if attendees is None:
+            attendees = []
+
+        payload = {"title": title, "addSelf": add_self}
+        response = self._client.post("L10/create", json=payload)
+        response.raise_for_status()
+        data: Any = response.json()
+
+        meeting_id = data["meetingId"]
+
+        # Add attendees
+        for attendee_id in attendees:
+            attendee_response = self._client.post(
+                f"L10/{meeting_id}/attendees/{attendee_id}"
+            )
+            attendee_response.raise_for_status()
+
+        return {"meeting_id": meeting_id, "title": title, "attendees": attendees}
+
+    def delete(self, meeting_id: int) -> bool:
+        """Delete a meeting.
+
+        Args:
+            meeting_id: The ID of the meeting to delete
+
+        Returns:
+            True if deletion was successful
+
+        Example:
+            ```python
+            client.meeting.delete(1)
+            # Returns: True
+            ```
+        """
+        response = self._client.delete(f"L10/{meeting_id}")
+        response.raise_for_status()
+        return True

bloomy/operations/scorecard.py

@@ -0,0 +1,152 @@
+"""Scorecard operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+
+from ..models import ScorecardItem, ScorecardWeek
+from ..utils.base_operations import BaseOperations
+
+
+class ScorecardOperations(BaseOperations):
+    """Class to handle all operations related to scorecards.
+
+    Note:
+        This class is already initialized via the client and usable as
+        `client.scorecard.method`
+    """
+
+    def current_week(self) -> ScorecardWeek:
+        """Retrieve the current week details.
+
+        Returns:
+            A ScorecardWeek model instance containing current week details
+
+        Example:
+            ```python
+            client.scorecard.current_week()
+            # Returns: ScorecardWeek(id=123, week_number=24, week_start='2024-06-10',
+            #                       week_end='2024-06-16')
+            ```
+        """
+        response = self._client.get("weeks/current")
+        response.raise_for_status()
+        data = response.json()
+
+        return ScorecardWeek(
+            id=data["Id"],
+            week_number=data["ForWeekNumber"],
+            week_start=data["LocalDate"]["Date"],
+            week_end=data["ForWeek"],
+        )
+
+    def list(
+        self,
+        user_id: int | None = None,
+        meeting_id: int | None = None,
+        show_empty: bool = False,
+        week_offset: int | None = None,
+    ) -> builtins.list[ScorecardItem]:
+        """Retrieve the scorecards 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
+            show_empty: Whether to include scores with None values (default: False)
+            week_offset: Offset for the week number to filter scores
+
+        Returns:
+            A list of ScorecardItem model instances
+
+        Raises:
+            ValueError: If both user_id and meeting_id are provided
+
+        Example:
+            ```python
+            # Fetch scorecards for the current user
+            client.scorecard.list()
+
+            # Fetch scorecards for a specific user
+            client.scorecard.list(user_id=42)
+
+            # Fetch scorecards for a specific meeting
+            client.scorecard.list(meeting_id=99)
+            ```
+
+        Note:
+            The week_offset parameter is useful when fetching scores for
+            previous or future weeks.
+            For example, to fetch scores for the previous week, you can set
+            week_offset to -1.
+            To fetch scores for a future week, you can set week_offset to a
+            positive value.
+        """
+        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"scorecard/meeting/{meeting_id}")
+        else:
+            if user_id is None:
+                user_id = self.user_id
+            response = self._client.get(f"scorecard/user/{user_id}")
+
+        response.raise_for_status()
+        data = response.json()
+
+        scorecards: list[ScorecardItem] = [
+            ScorecardItem(
+                id=scorecard["Id"],
+                measurable_id=scorecard["MeasurableId"],
+                accountable_user_id=scorecard["AccountableUserId"],
+                title=scorecard["MeasurableName"],
+                target=scorecard["Target"],
+                value=scorecard["Measured"],
+                week=scorecard["Week"],
+                week_id=scorecard["ForWeek"],
+                updated_at=scorecard["DateEntered"],
+            )
+            for scorecard in data["Scores"]
+        ]
+
+        # Filter by week offset if provided
+        if week_offset is not None:
+            week_data = self.current_week()
+            target_week_id = week_data.week_number + week_offset
+            scorecards = [s for s in scorecards if s.week_id == target_week_id]
+
+        # Filter out empty values unless show_empty is True
+        if not show_empty:
+            scorecards = [s for s in scorecards if s.value is not None]
+
+        return scorecards
+
+    def score(self, measurable_id: int, score: float, week_offset: int = 0) -> bool:
+        """Update the score for a measurable item for a specific week.
+
+        Args:
+            measurable_id: The ID of the measurable item
+            score: The score to be assigned to the measurable item
+            week_offset: The number of weeks to offset from the current week
+                (default: 0)
+
+        Returns:
+            True if the score was successfully updated
+
+        Example:
+            ```python
+            client.scorecard.score(measurable_id=123, score=5)
+            # Returns: True
+            ```
+        """
+        week_data = self.current_week()
+        week_id = week_data.week_number + week_offset
+
+        response = self._client.put(
+            f"measurables/{measurable_id}/week/{week_id}",
+            json={"value": score},
+        )
+        response.raise_for_status()
+        return response.is_success

bloomy/operations/todos.py

@@ -0,0 +1,229 @@
+"""Todo operations for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import builtins
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from ..models import Todo
+from ..utils.base_operations import BaseOperations
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class TodoOperations(BaseOperations):
+    """Class to handle all operations related to todos.
+
+    Note:
+        This class is already initialized via the client and usable as
+        `client.todo.method`
+    """
+
+    def list(
+        self, user_id: int | None = None, meeting_id: int | None = None
+    ) -> builtins.list[Todo]:
+        """List all todos for a specific user or meeting.
+
+        Args:
+            user_id: The ID of the user (default is the initialized user ID)
+            meeting_id: The ID of the meeting
+
+        Returns:
+            A list of Todo model instances
+
+        Raises:
+            ValueError: If both user_id and meeting_id are provided
+
+        Example:
+            ```python
+            # Fetch todos for the current user
+            client.todo.list()
+            # Returns: [Todo(id=1, name='New Todo', due_date='2024-06-15', ...)]
+            ```
+        """
+        if user_id is not None and meeting_id is not None:
+            raise ValueError(
+                "Please provide either `user_id` or `meeting_id`, not both."
+            )
+
+        if meeting_id is not None:
+            response = self._client.get(f"l10/{meeting_id}/todos")
+        else:
+            if user_id is None:
+                user_id = self.user_id
+            response = self._client.get(f"todo/user/{user_id}")
+
+        response.raise_for_status()
+        data = response.json()
+
+        return [Todo.model_validate(todo) for todo in data]
+
+    def create(
+        self,
+        title: str,
+        meeting_id: int,
+        due_date: str | None = None,
+        user_id: int | None = None,
+        notes: str | None = None,
+    ) -> Todo:
+        """Create a new todo.
+
+        Args:
+            title: The title of the new todo
+            meeting_id: The ID of the meeting associated with the todo
+            due_date: The due date of the todo (optional)
+            user_id: The ID of the user responsible for the todo
+                (default: initialized user ID)
+            notes: Additional notes for the todo (optional)
+
+        Returns:
+            A Todo model instance representing the newly created todo
+
+        Example:
+            ```python
+            client.todo.create(
+                title="New Todo", meeting_id=1, due_date="2024-06-15"
+            )
+            # Returns: Todo(id=1, name='New Todo', due_date='2024-06-15', ...)
+            ```
+        """
+        if user_id is None:
+            user_id = self.user_id
+
+        payload: dict[str, Any] = {
+            "title": title,
+            "accountableUserId": user_id,
+            "notes": notes,
+        }
+
+        if due_date is not None:
+            payload["dueDate"] = due_date
+
+        response = self._client.post(f"L10/{meeting_id}/todos", json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        # Add default values for fields that might be missing in create response
+        todo_data = {
+            "Id": data["Id"],
+            "Name": data["Name"],
+            "DetailsUrl": data.get("DetailsUrl"),
+            "DueDate": data.get("DueDate"),
+            "CompleteTime": None,
+            "CreateTime": datetime.now().isoformat(),
+            "OriginId": meeting_id,
+            "Origin": None,
+            "Complete": False,
+        }
+
+        return Todo.model_validate(todo_data)
+
+    def complete(self, todo_id: int) -> bool:
+        """Mark a todo as complete.
+
+        Args:
+            todo_id: The ID of the todo to complete
+
+        Returns:
+            True if the operation was successful
+
+        Example:
+            ```python
+            client.todo.complete(1)
+            # Returns: True
+            ```
+        """
+        response = self._client.post(f"todo/{todo_id}/complete?status=true")
+        response.raise_for_status()
+        return response.is_success
+
+    def update(
+        self,
+        todo_id: int,
+        title: str | None = None,
+        due_date: str | None = None,
+    ) -> Todo:
+        """Update an existing todo.
+
+        Args:
+            todo_id: The ID of the todo to update
+            title: The new title of the todo (optional)
+            due_date: The new due date of the todo (optional)
+
+        Returns:
+            A Todo model instance containing the updated todo details
+
+        Raises:
+            ValueError: If no update fields are provided
+            RuntimeError: If the update request fails
+
+        Example:
+            ```python
+            client.todo.update(
+                todo_id=1, title="Updated Todo", due_date="2024-11-01"
+            )
+            # Returns: Todo(id=1, name='Updated Todo', due_date='2024-11-01', ...)
+            ```
+        """
+        payload: dict[str, Any] = {}
+
+        if title is not None:
+            payload["title"] = title
+
+        if due_date is not None:
+            payload["dueDate"] = due_date
+
+        if not payload:
+            raise ValueError("At least one field must be provided")
+
+        response = self._client.put(f"todo/{todo_id}", json=payload)
+
+        if response.status_code != 200:
+            raise RuntimeError(f"Failed to update todo. Status: {response.status_code}")
+
+        # Construct todo data for validation
+        todo_data = {
+            "Id": todo_id,
+            "Name": title or "",
+            "DetailsUrl": "",
+            "DueDate": due_date,
+            "CompleteTime": None,
+            "CreateTime": datetime.now().isoformat(),
+            "OriginId": None,
+            "Origin": None,
+            "Complete": False,
+        }
+
+        return Todo.model_validate(todo_data)
+
+    def details(self, todo_id: int) -> Todo:
+        """Retrieve the details of a specific todo item by its ID.
+
+        Args:
+            todo_id: The ID of the todo item to retrieve
+
+        Returns:
+            A Todo model instance containing the todo details
+
+        Raises:
+            RuntimeError: If the request to retrieve the todo details fails
+
+        Example:
+            ```python
+            client.todo.details(1)
+            # Returns: Todo(id=1, name='Updated Todo', due_date='2024-11-01', ...)
+            ```
+        """
+        response = self._client.get(f"todo/{todo_id}")
+
+        if not response.is_success:
+            raise RuntimeError(
+                f"Failed to get todo details. Status: {response.status_code}"
+            )
+
+        response.raise_for_status()
+        todo = response.json()
+
+        return Todo.model_validate(todo)