mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/adapters/jira.py

@@ -6,20 +6,28 @@ import logging
 import re
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any, Union
 
 import httpx
 from httpx import AsyncClient, HTTPStatusError, TimeoutException
 
 from ..core.adapter import BaseAdapter
 from ..core.env_loader import load_adapter_config, validate_adapter_config
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
+from ..core.models import (
+    Attachment,
+    Comment,
+    Epic,
+    Priority,
+    SearchQuery,
+    Task,
+    TicketState,
+)
 from ..core.registry import AdapterRegistry
 
 logger = logging.getLogger(__name__)
 
 
-def parse_jira_datetime(date_str: str) -> Optional[datetime]:
+def parse_jira_datetime(date_str: str) -> datetime | None:
     """Parse JIRA datetime strings which can be in various formats.
 
     JIRA can return dates in formats like:
@@ -47,7 +55,7 @@ def parse_jira_datetime(date_str: str) -> Optional[datetime]:
         return None
 
 
-def extract_text_from_adf(adf_content: Union[str, dict[str, Any]]) -> str:
+def extract_text_from_adf(adf_content: str | dict[str, Any]) -> str:
     """Extract plain text from Atlassian Document Format (ADF).
 
     Args:
@@ -221,8 +229,8 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         self,
         method: str,
         endpoint: str,
-        data: Optional[dict[str, Any]] = None,
-        params: Optional[dict[str, Any]] = None,
+        data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
         retry_count: int = 0,
     ) -> dict[str, Any]:
         """Make HTTP request to JIRA API with retry logic.
@@ -287,7 +295,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         return self._priority_cache
 
     async def _get_issue_types(
-        self, project_key: Optional[str] = None
+        self, project_key: str | None = None
     ) -> list[dict[str, Any]]:
         """Get available issue types for a project."""
         key = project_key or self.project_key
@@ -380,9 +388,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         }
         return mapping.get(priority, JiraPriority.MEDIUM)
 
-    def _map_priority_from_jira(
-        self, jira_priority: Optional[dict[str, Any]]
-    ) -> Priority:
+    def _map_priority_from_jira(self, jira_priority: dict[str, Any] | None) -> Priority:
         """Map JIRA priority to universal priority."""
         if not jira_priority:
             return Priority.MEDIUM
@@ -432,7 +438,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         else:
             return TicketState.OPEN
 
-    def _issue_to_ticket(self, issue: dict[str, Any]) -> Union[Epic, Task]:
+    def _issue_to_ticket(self, issue: dict[str, Any]) -> Epic | Task:
         """Convert JIRA issue to universal ticket model."""
         fields = issue.get("fields", {})
 
@@ -507,7 +513,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
             )
 
     def _ticket_to_issue_fields(
-        self, ticket: Union[Epic, Task], issue_type: Optional[str] = None
+        self, ticket: Epic | Task, issue_type: str | None = None
     ) -> dict[str, Any]:
         """Convert universal ticket to JIRA issue fields."""
         # Convert description to ADF format for JIRA Cloud
@@ -556,7 +562,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
         return fields
 
-    async def create(self, ticket: Union[Epic, Task]) -> Union[Epic, Task]:
+    async def create(self, ticket: Epic | Task) -> Epic | Task:
         """Create a new JIRA issue."""
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
@@ -576,7 +582,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         created_issue = await self._make_request("GET", f"issue/{ticket.id}")
         return self._issue_to_ticket(created_issue)
 
-    async def read(self, ticket_id: str) -> Optional[Union[Epic, Task]]:
+    async def read(self, ticket_id: str) -> Epic | Task | None:
         """Read a JIRA issue by key."""
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
@@ -595,7 +601,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
     async def update(
         self, ticket_id: str, updates: dict[str, Any]
-    ) -> Optional[Union[Epic, Task]]:
+    ) -> Epic | Task | None:
         """Update a JIRA issue."""
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
@@ -652,8 +658,8 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
             raise
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
-    ) -> list[Union[Epic, Task]]:
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
+    ) -> list[Epic | Task]:
         """List JIRA issues with pagination."""
         # Build JQL query
         jql_parts = []
@@ -692,7 +698,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         issues = data.get("issues", [])
         return [self._issue_to_ticket(issue) for issue in issues]
 
-    async def search(self, query: SearchQuery) -> builtins.list[Union[Epic, Task]]:
+    async def search(self, query: SearchQuery) -> builtins.list[Epic | Task]:
         """Search JIRA issues using JQL."""
         # Build JQL query
         jql_parts = []
@@ -744,7 +750,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Union[Epic, Task]]:
+    ) -> Epic | Task | None:
         """Transition JIRA issue to a new state."""
         # Get available transitions
         transitions = await self._get_transitions(ticket_id)
@@ -858,9 +864,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
         return comments
 
-    async def get_project_info(
-        self, project_key: Optional[str] = None
-    ) -> dict[str, Any]:
+    async def get_project_info(self, project_key: str | None = None) -> dict[str, Any]:
         """Get JIRA project information including workflows and fields."""
         key = project_key or self.project_key
         if not key:
@@ -882,7 +886,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
     async def execute_jql(
         self, jql: str, limit: int = 50
-    ) -> builtins.list[Union[Epic, Task]]:
+    ) -> builtins.list[Epic | Task]:
         """Execute a raw JQL query.
 
         Args:
@@ -908,7 +912,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         return [self._issue_to_ticket(issue) for issue in issues]
 
     async def get_sprints(
-        self, board_id: Optional[int] = None
+        self, board_id: int | None = None
     ) -> builtins.list[dict[str, Any]]:
         """Get active sprints for a board (requires JIRA Software).
 
@@ -992,13 +996,255 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
             except Exception:
                 return []
 
-    async def get_current_user(self) -> Optional[dict[str, Any]]:
+    async def get_current_user(self) -> dict[str, Any] | None:
         """Get current authenticated user information."""
         try:
             return await self._make_request("GET", "myself")
         except Exception:
             return None
 
+    async def list_labels(self) -> builtins.list[dict[str, Any]]:
+        """List all labels used in the project.
+
+        JIRA doesn't have a direct "list all labels" endpoint, so we query
+        recent issues and extract unique labels from them.
+
+        Returns:
+            List of label dictionaries with 'id' and 'name' fields
+
+        """
+        try:
+            # Query recent issues to get labels in use
+            jql = f"project = {self.project_key} ORDER BY updated DESC"
+            data = await self._make_request(
+                "GET",
+                "search/jql",
+                params={
+                    "jql": jql,
+                    "maxResults": 100,  # Sample from recent 100 issues
+                    "fields": "labels",
+                },
+            )
+
+            # Collect unique labels
+            unique_labels = set()
+            for issue in data.get("issues", []):
+                labels = issue.get("fields", {}).get("labels", [])
+                for label in labels:
+                    if isinstance(label, dict):
+                        unique_labels.add(label.get("name", ""))
+                    else:
+                        unique_labels.add(str(label))
+
+            # Transform to standardized format
+            return [
+                {"id": label, "name": label} for label in sorted(unique_labels) if label
+            ]
+
+        except Exception:
+            # Fallback: return empty list if query fails
+            return []
+
+    async def update_epic(self, epic_id: str, updates: dict[str, Any]) -> Epic | None:
+        """Update a JIRA Epic with epic-specific field handling.
+
+        Args:
+            epic_id: Epic identifier (key like PROJ-123 or ID)
+            updates: Dictionary with fields to update:
+                - title: Epic title (maps to summary)
+                - description: Epic description (auto-converted to ADF)
+                - state: TicketState value (transitions via workflow)
+                - tags: List of labels
+                - priority: Priority level
+
+        Returns:
+            Updated Epic object or None if not found
+
+        Raises:
+            ValueError: If no fields provided for update
+            HTTPStatusError: If update fails
+
+        """
+        fields = {}
+
+        # Map title to summary
+        if "title" in updates:
+            fields["summary"] = updates["title"]
+
+        # Convert description to ADF format
+        if "description" in updates:
+            fields["description"] = self._convert_to_adf(updates["description"])
+
+        # Map tags to labels
+        if "tags" in updates:
+            fields["labels"] = updates["tags"]
+
+        # Map priority (some JIRA configs allow priority on Epics)
+        if "priority" in updates:
+            priority_value = updates["priority"]
+            if isinstance(priority_value, Priority):
+                fields["priority"] = {
+                    "name": self._map_priority_to_jira(priority_value)
+                }
+            else:
+                # String priority passed directly
+                fields["priority"] = {"name": priority_value}
+
+        if not fields and "state" not in updates:
+            raise ValueError("At least one field must be updated")
+
+        # Apply field updates if any
+        if fields:
+            await self._make_request("PUT", f"issue/{epic_id}", data={"fields": fields})
+
+        # Handle state transitions separately (JIRA uses workflow transitions)
+        if "state" in updates:
+            await self.transition_state(epic_id, updates["state"])
+
+        # Fetch and return updated epic
+        return await self.read(epic_id)
+
+    async def add_attachment(
+        self, ticket_id: str, file_path: str, description: str | None = None
+    ) -> Attachment:
+        """Attach file to JIRA issue (including Epic).
+
+        Args:
+            ticket_id: Issue key (e.g., PROJ-123) or ID
+            file_path: Path to file to attach
+            description: Optional description (stored in metadata, not used by JIRA directly)
+
+        Returns:
+            Attachment object with metadata
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If credentials invalid
+            HTTPStatusError: If upload fails
+
+        """
+        from pathlib import Path
+
+        # Validate credentials before attempting operation
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # JIRA requires special header for attachment upload
+        headers = {
+            "X-Atlassian-Token": "no-check",
+            # Don't set Content-Type - let httpx handle multipart
+        }
+
+        # Prepare multipart file upload
+        with open(file_path_obj, "rb") as f:
+            files = {"file": (file_path_obj.name, f, "application/octet-stream")}
+
+            url = f"{self.api_base}/issue/{ticket_id}/attachments"
+
+            # Use existing client infrastructure
+            async with await self._get_client() as client:
+                response = await client.post(
+                    url, files=files, headers={**self.headers, **headers}
+                )
+                response.raise_for_status()
+
+                # JIRA returns array with single attachment
+                attachment_data = response.json()[0]
+
+                return Attachment(
+                    id=attachment_data["id"],
+                    ticket_id=ticket_id,
+                    filename=attachment_data["filename"],
+                    url=attachment_data["content"],
+                    content_type=attachment_data["mimeType"],
+                    size_bytes=attachment_data["size"],
+                    created_at=parse_jira_datetime(attachment_data["created"]),
+                    created_by=attachment_data["author"]["displayName"],
+                    description=description,
+                    metadata={"jira": attachment_data},
+                )
+
+    async def get_attachments(self, ticket_id: str) -> builtins.list[Attachment]:
+        """Get all attachments for a JIRA issue.
+
+        Args:
+            ticket_id: Issue key or ID
+
+        Returns:
+            List of Attachment objects
+
+        Raises:
+            ValueError: If credentials invalid
+            HTTPStatusError: If request fails
+
+        """
+        # Validate credentials before attempting operation
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        # Fetch issue with attachment field
+        issue = await self._make_request(
+            "GET", f"issue/{ticket_id}", params={"fields": "attachment"}
+        )
+
+        attachments = []
+        for att_data in issue.get("fields", {}).get("attachment", []):
+            attachments.append(
+                Attachment(
+                    id=att_data["id"],
+                    ticket_id=ticket_id,
+                    filename=att_data["filename"],
+                    url=att_data["content"],
+                    content_type=att_data["mimeType"],
+                    size_bytes=att_data["size"],
+                    created_at=parse_jira_datetime(att_data["created"]),
+                    created_by=att_data["author"]["displayName"],
+                    metadata={"jira": att_data},
+                )
+            )
+
+        return attachments
+
+    async def delete_attachment(self, ticket_id: str, attachment_id: str) -> bool:
+        """Delete an attachment from a JIRA issue.
+
+        Args:
+            ticket_id: Issue key or ID (for validation/context)
+            attachment_id: Attachment ID to delete
+
+        Returns:
+            True if deleted successfully, False otherwise
+
+        Raises:
+            ValueError: If credentials invalid
+
+        """
+        # Validate credentials before attempting operation
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            await self._make_request("DELETE", f"attachment/{attachment_id}")
+            return True
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                logger.warning(f"Attachment {attachment_id} not found")
+                return False
+            logger.error(
+                f"Failed to delete attachment {attachment_id}: {e.response.status_code} - {e.response.text}"
+            )
+            return False
+        except Exception as e:
+            logger.error(f"Unexpected error deleting attachment {attachment_id}: {e}")
+            return False
+
     async def close(self) -> None:
         """Close the adapter and cleanup resources."""
         # Clear caches