bloomy-python 0.12.1__py3-none-any.whl

bloomy/__init__.py

@@ -0,0 +1,78 @@
+"""Bloomy - Python SDK for Bloom Growth API."""
+
+import importlib.metadata
+
+from .client import Client
+from .configuration import Configuration
+from .exceptions import APIError, BloomyError
+from .models import (
+    ArchivedGoalInfo,
+    CreatedGoalInfo,
+    CreatedIssue,
+    CurrentWeek,
+    DirectReport,
+    Goal,
+    GoalInfo,
+    GoalListResponse,
+    Headline,
+    HeadlineDetails,
+    HeadlineInfo,
+    HeadlineListItem,
+    Issue,
+    IssueDetails,
+    IssueListItem,
+    Meeting,
+    MeetingAttendee,
+    MeetingDetails,
+    MeetingInfo,
+    MeetingListItem,
+    OwnerDetails,
+    Position,
+    ScorecardItem,
+    ScorecardMetric,
+    ScorecardWeek,
+    Todo,
+    UserDetails,
+    UserListItem,
+    UserSearchResult,
+)
+
+try:
+    __version__ = importlib.metadata.version("bloomy")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"
+__all__ = [
+    "Client",
+    "Configuration",
+    "APIError",
+    "BloomyError",
+    "ArchivedGoalInfo",
+    "CreatedGoalInfo",
+    "CreatedIssue",
+    "CurrentWeek",
+    "DirectReport",
+    "Goal",
+    "GoalInfo",
+    "GoalListResponse",
+    "Headline",
+    "HeadlineDetails",
+    "HeadlineInfo",
+    "HeadlineListItem",
+    "Issue",
+    "IssueDetails",
+    "IssueListItem",
+    "Meeting",
+    "MeetingAttendee",
+    "MeetingDetails",
+    "MeetingInfo",
+    "MeetingListItem",
+    "OwnerDetails",
+    "Position",
+    "ScorecardItem",
+    "ScorecardMetric",
+    "ScorecardWeek",
+    "Todo",
+    "UserDetails",
+    "UserListItem",
+    "UserSearchResult",
+]

bloomy/client.py

@@ -0,0 +1,95 @@
+"""Main client for interacting with the Bloom Growth API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from .configuration import Configuration
+from .operations.goals import GoalOperations
+from .operations.headlines import HeadlineOperations
+from .operations.issues import IssueOperations
+from .operations.meetings import MeetingOperations
+from .operations.scorecard import ScorecardOperations
+from .operations.todos import TodoOperations
+from .operations.users import UserOperations
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class Client:
+    """The Client class is the main entry point for interacting with the Bloomy API.
+
+    It provides methods for managing Bloom Growth features.
+
+    Example:
+        ```python
+        from bloomy import Client
+        client = Client()
+        client.meeting.list()
+        client.user.details()
+        client.meeting.delete(123)
+        client.scorecard.list()
+        client.issue.list()
+        client.headline.list()
+        ```
+    """
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize a new Client instance.
+
+        Args:
+            api_key: The API key to use. If not provided, will attempt to
+                     load from environment variable (BG_API_KEY) or configuration file.
+
+        Raises:
+            ValueError: If no API key is provided or found in configuration.
+        """
+        # Use Configuration class which handles priority:
+        # 1. Explicit api_key parameter
+        # 2. BG_API_KEY environment variable
+        # 3. Configuration file (~/.bloomy/config.yaml)
+        self.configuration = Configuration(api_key)
+
+        if not self.configuration.api_key:
+            raise ValueError(
+                "No API key provided. Set it explicitly, via BG_API_KEY "
+                "environment variable, or in ~/.bloomy/config.yaml configuration file."
+            )
+
+        self._api_key = self.configuration.api_key
+        self._base_url = "https://app.bloomgrowth.com/api/v1"
+
+        # Initialize HTTP client
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Accept": "*/*",
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._api_key}",
+            },
+            timeout=30.0,
+        )
+
+        # Initialize operation classes
+        self.user = UserOperations(self._client)
+        self.todo = TodoOperations(self._client)
+        self.meeting = MeetingOperations(self._client)
+        self.goal = GoalOperations(self._client)
+        self.scorecard = ScorecardOperations(self._client)
+        self.issue = IssueOperations(self._client)
+        self.headline = HeadlineOperations(self._client)
+
+    def __enter__(self) -> Client:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit - close the HTTP client."""
+        self._client.close()
+
+    def close(self) -> None:
+        """Close the HTTP client connection."""
+        self._client.close()

bloomy/configuration.py

@@ -0,0 +1,137 @@
+"""Configuration management for the Bloomy SDK."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import urlencode
+
+import httpx
+import yaml
+
+from .exceptions import AuthenticationError, ConfigurationError
+
+if TYPE_CHECKING:
+    pass
+
+
+class Configuration:
+    """The Configuration class is responsible for managing authentication."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize a new Configuration instance.
+
+        Args:
+            api_key: Optional API key. If not provided, will attempt to load from
+                     environment variable or configuration file.
+
+        Example:
+            ```python
+            config = Bloomy.Configuration(api_key)
+            ```
+        """
+        self.api_key = api_key or os.environ.get("BG_API_KEY") or self._load_api_key()
+
+    def configure_api_key(
+        self, username: str, password: str, store_key: bool = False
+    ) -> None:
+        """Configure the API key using the provided username and password.
+
+        Args:
+            username: The username for authentication
+            password: The password for authentication
+            store_key: Whether to store the API key (default: False)
+
+        Note:
+            This method only fetches and stores the API key if it is currently None.
+            It saves the key under '~/.bloomy/config.yaml' if 'store_key: True' is
+            passed.
+
+        Example:
+            ```python
+            config.configure_api_key("user", "pass", store_key=True)
+            config.api_key
+            # Returns: 'xxxx...'
+            ```
+        """
+        self.api_key = self._fetch_api_key(username, password)
+        if store_key:
+            self._store_api_key()
+
+    def _fetch_api_key(self, username: str, password: str) -> str:
+        """Fetch the API key using the provided username and password.
+
+        Args:
+            username: The username for authentication
+            password: The password for authentication
+
+        Returns:
+            The fetched API key
+
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        with httpx.Client() as client:
+            response = client.post(
+                "https://app.bloomgrowth.com/Token",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                content=urlencode(
+                    {
+                        "grant_type": "password",
+                        "userName": username,
+                        "password": password,
+                    }
+                ),
+            )
+
+        if not response.is_success:
+            raise AuthenticationError(
+                f"Failed to fetch API key: {response.status_code} - {response.text}"
+            )
+
+        data = response.json()
+        return data["access_token"]
+
+    def _store_api_key(self) -> None:
+        """Store the API key in a local configuration file.
+
+        Raises:
+            ConfigurationError: If the API key is None
+        """
+        if self.api_key is None:
+            raise ConfigurationError("API key is None")
+
+        config_file = self._config_file
+        config_file.parent.mkdir(parents=True, exist_ok=True)
+
+        config_data = {"version": 1, "api_key": self.api_key}
+        with open(config_file, "w") as f:
+            yaml.dump(config_data, f)
+
+    def _load_api_key(self) -> str | None:
+        """Load the API key from a local configuration file.
+
+        Returns:
+            The loaded API key or None if the file does not exist
+        """
+        config_file = self._config_file
+        if not config_file.exists():
+            return None
+
+        try:
+            with open(config_file) as f:
+                data = yaml.safe_load(f)
+                return data.get("api_key")
+        except Exception:
+            return None
+
+    @property
+    def _config_dir(self) -> Path:
+        """Return the directory path for the configuration file."""
+        return Path.home() / ".bloomy"
+
+    @property
+    def _config_file(self) -> Path:
+        """Return the file path for the configuration file."""
+        return self._config_dir / "config.yaml"

bloomy/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions for the Bloomy SDK."""
+
+
+class BloomyError(Exception):
+    """Base exception for all Bloomy-related errors."""
+
+    pass
+
+
+class ConfigurationError(BloomyError):
+    """Raised when there's an issue with configuration."""
+
+    pass
+
+
+class AuthenticationError(BloomyError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class APIError(BloomyError):
+    """Raised when API returns an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code

bloomy/models.py

@@ -0,0 +1,371 @@
+"""Pydantic models for the Bloomy SDK."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class BloomyBaseModel(BaseModel):
+    """Base model with common configuration for all Bloomy models."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        use_enum_values=True,
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+        str_strip_whitespace=True,
+    )
+
+
+class DirectReport(BloomyBaseModel):
+    """Model for direct report information."""
+
+    id: int
+    name: str
+    image_url: str
+
+
+class Position(BloomyBaseModel):
+    """Model for position information."""
+
+    id: int
+    name: str
+
+
+class UserDetails(BloomyBaseModel):
+    """Model for user details."""
+
+    id: int
+    name: str
+    image_url: str
+    direct_reports: list[DirectReport] | None = None
+    positions: list[Position] | None = None
+
+
+class UserSearchResult(BloomyBaseModel):
+    """Model for user search results."""
+
+    id: int
+    name: str
+    description: str
+    email: str
+    organization_id: int
+    image_url: str
+
+
+class UserListItem(BloomyBaseModel):
+    """Model for user list items."""
+
+    id: int
+    name: str
+    email: str
+    position: str
+    image_url: str
+
+
+class MeetingAttendee(BloomyBaseModel):
+    """Model for meeting attendee."""
+
+    user_id: int = Field(alias="UserId")
+    name: str = Field(alias="Name")
+    image_url: str = Field(alias="ImageUrl")
+
+
+class MeetingListItem(BloomyBaseModel):
+    """Model for meeting list item (simplified response)."""
+
+    id: int = Field(alias="Id")
+    type: str = Field(alias="Type")
+    key: str = Field(alias="Key")
+    name: str = Field(alias="Name")
+
+
+class Meeting(BloomyBaseModel):
+    """Model for meeting."""
+
+    id: int = Field(alias="Id")
+    name: str = Field(alias="Name")
+    start_date_utc: datetime = Field(alias="StartDateUtc")
+    created_date: datetime = Field(alias="CreateDate")
+    organization_id: int = Field(alias="OrganizationId")
+
+
+class MeetingDetails(BloomyBaseModel):
+    """Model for meeting details."""
+
+    id: int
+    name: str
+    start_date_utc: datetime | None = None
+    created_date: datetime | None = None
+    organization_id: int | None = None
+    attendees: list[MeetingAttendee] | None = None
+    issues: list[Issue] | None = None
+    todos: list[Todo] | None = None
+    metrics: list[ScorecardMetric] | None = None
+
+
+class Todo(BloomyBaseModel):
+    """Model for todo."""
+
+    id: int = Field(alias="Id")
+    name: str = Field(alias="Name")
+    details_url: str | None = Field(alias="DetailsUrl", default=None)
+    due_date: datetime | None = Field(alias="DueDate", default=None)
+    complete_date: datetime | None = Field(alias="CompleteTime", default=None)
+    create_date: datetime | None = Field(alias="CreateTime", default=None)
+    meeting_id: int | None = Field(alias="OriginId", default=None)
+    meeting_name: str | None = Field(alias="Origin", default=None)
+    complete: bool = Field(alias="Complete", default=False)
+
+    @field_validator("due_date", "complete_date", "create_date", mode="before")
+    @classmethod
+    def parse_optional_datetime(cls, v: Any) -> datetime | None:
+        """Parse optional datetime fields."""
+        if v is None or v == "":
+            return None
+        return v
+
+
+class Issue(BloomyBaseModel):
+    """Model for issue."""
+
+    id: int = Field(alias="Id")
+    name: str = Field(alias="Name")
+    details_url: str | None = Field(alias="DetailsUrl", default=None)
+    created_date: datetime = Field(alias="CreateDate")
+    meeting_id: int = Field(alias="MeetingId")
+    meeting_name: str = Field(alias="MeetingName")
+    owner_name: str = Field(alias="OwnerName")
+    owner_id: int = Field(alias="OwnerId")
+    owner_image_url: str = Field(alias="OwnerImageUrl")
+    closed_date: datetime | None = Field(alias="ClosedDate", default=None)
+    completion_date: datetime | None = Field(alias="CompletionDate", default=None)
+
+    @field_validator("closed_date", "completion_date", mode="before")
+    @classmethod
+    def parse_optional_datetime(cls, v: Any) -> datetime | None:
+        """Parse optional datetime fields."""
+        if v is None or v == "":
+            return None
+        return v
+
+
+class Headline(BloomyBaseModel):
+    """Model for headline."""
+
+    id: int = Field(alias="Id")
+    title: str = Field(alias="Title")
+    notes: str = Field(alias="Notes")
+    owner_name: str = Field(alias="OwnerName")
+    owner_id: int = Field(alias="OwnerId")
+    headline_type: str = Field(alias="HeadlineType")
+    create_date: datetime = Field(alias="CreateDate")
+    meeting_id: int = Field(alias="MeetingId")
+    is_archived: bool = Field(alias="IsArchived")
+
+
+class Goal(BloomyBaseModel):
+    """Model for goal (rock)."""
+
+    id: int = Field(alias="Id")
+    name: str = Field(alias="Name")
+    due_date: datetime = Field(alias="DueDate")
+    complete_date: datetime | None = Field(alias="CompleteDate", default=None)
+    create_date: datetime = Field(alias="CreateDate")
+    is_archived: bool = Field(alias="IsArchived", default=False)
+    percent_complete: float = Field(alias="PercentComplete", default=0.0)
+    accountable_user_id: int = Field(alias="AccountableUserId")
+    accountable_user_name: str | None = Field(alias="AccountableUserName", default=None)
+
+    @field_validator("complete_date", mode="before")
+    @classmethod
+    def parse_optional_datetime(cls, v: Any) -> datetime | None:
+        """Parse optional datetime fields."""
+        if v is None or v == "":
+            return None
+        return v
+
+
+class ScorecardMetric(BloomyBaseModel):
+    """Model for scorecard metric."""
+
+    id: int = Field(alias="Id")
+    title: str = Field(alias="Title")
+    target: float | None = Field(alias="Target", default=None)
+    unit: str | None = Field(alias="Unit", default=None)
+    week_number: int = Field(alias="WeekNumber")
+    value: float | None = Field(alias="Value", default=None)
+    metric_type: str = Field(alias="MetricType")
+    accountable_user_id: int = Field(alias="AccountableUserId")
+    accountable_user_name: str | None = Field(alias="AccountableUserName", default=None)
+    is_inverse: bool = Field(alias="IsInverse", default=False)
+
+    @field_validator("target", "value", mode="before")
+    @classmethod
+    def parse_optional_float(cls, v: Any) -> float | None:
+        """Parse optional float fields."""
+        if v is None or v == "":
+            return None
+        return float(v)
+
+
+class CurrentWeek(BloomyBaseModel):
+    """Model for current week information."""
+
+    week_number: int
+    start_date: datetime
+    end_date: datetime
+
+
+class GoalInfo(BloomyBaseModel):
+    """Model for goal information."""
+
+    id: int
+    user_id: int
+    user_name: str
+    title: str
+    created_at: str
+    due_date: str | None
+    status: str
+    meeting_id: int | None = None
+    meeting_title: str | None = None
+
+
+class ArchivedGoalInfo(BloomyBaseModel):
+    """Model for archived goal information."""
+
+    id: int
+    title: str
+    created_at: str
+    due_date: str | None
+    status: str
+
+
+class GoalListResponse(BloomyBaseModel):
+    """Model for goal list response with archived goals."""
+
+    active: list[GoalInfo]
+    archived: list[ArchivedGoalInfo]
+
+
+class CreatedGoalInfo(BloomyBaseModel):
+    """Model for created goal information."""
+
+    id: int
+    user_id: int
+    user_name: str
+    title: str
+    meeting_id: int
+    meeting_title: str
+    status: str
+    created_at: str
+
+
+class ScorecardWeek(BloomyBaseModel):
+    """Model for scorecard week details."""
+
+    id: int
+    week_number: int
+    week_start: str
+    week_end: str
+
+
+class ScorecardItem(BloomyBaseModel):
+    """Model for scorecard items."""
+
+    id: int
+    measurable_id: int
+    accountable_user_id: int
+    title: str
+    target: float
+    value: float | None = None
+    week: str  # Changed from int to str to handle "2024-W25" format
+    week_id: int
+    updated_at: str
+
+
+class IssueDetails(BloomyBaseModel):
+    """Model for issue details."""
+
+    id: int
+    title: str
+    notes_url: str
+    created_at: str
+    completed_at: str | None = None
+    meeting_id: int
+    meeting_title: str
+    user_id: int
+    user_name: str
+
+
+class IssueListItem(BloomyBaseModel):
+    """Model for issue list items."""
+
+    id: int
+    title: str
+    notes_url: str
+    created_at: str
+    meeting_id: int
+    meeting_title: str
+
+
+class CreatedIssue(BloomyBaseModel):
+    """Model for created issue response."""
+
+    id: int
+    meeting_id: int
+    meeting_title: str
+    title: str
+    user_id: int
+    notes_url: str
+
+
+class OwnerDetails(BloomyBaseModel):
+    """Model for owner details."""
+
+    id: int
+    name: str | None = None
+
+
+class MeetingInfo(BloomyBaseModel):
+    """Model for meeting information."""
+
+    id: int
+    title: str | None = None
+
+
+class HeadlineInfo(BloomyBaseModel):
+    """Model for headline information."""
+
+    id: int
+    title: str
+    notes_url: str
+    owner_details: OwnerDetails
+
+
+class HeadlineDetails(BloomyBaseModel):
+    """Model for detailed headline information."""
+
+    id: int
+    title: str
+    notes_url: str
+    meeting_details: MeetingInfo
+    owner_details: OwnerDetails
+    archived: bool
+    created_at: str
+    closed_at: str | None = None
+
+
+class HeadlineListItem(BloomyBaseModel):
+    """Model for headline list items."""
+
+    id: int
+    title: str
+    meeting_details: MeetingInfo
+    owner_details: OwnerDetails
+    archived: bool
+    created_at: str
+    closed_at: str | None = None