mcp-ticketer 0.1.39__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_ticketer/adapters/linear/client.py

@@ -0,0 +1,257 @@
+"""GraphQL client management for Linear API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+try:
+    from gql import Client, gql
+    from gql.transport.aiohttp import AIOHTTPTransport
+    from gql.transport.exceptions import TransportError
+except ImportError:
+    # Handle missing gql dependency gracefully
+    Client = None
+    gql = None
+    AIOHTTPTransport = None
+    TransportError = Exception
+
+from ...core.exceptions import AdapterError, AuthenticationError, RateLimitError
+
+
+class LinearGraphQLClient:
+    """GraphQL client for Linear API with error handling and retry logic."""
+    
+    def __init__(self, api_key: str, timeout: int = 30):
+        """Initialize the Linear GraphQL client.
+        
+        Args:
+            api_key: Linear API key
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.timeout = timeout
+        self._base_url = "https://api.linear.app/graphql"
+    
+    def create_client(self) -> "Client":
+        """Create a new GraphQL client instance.
+
+        Returns:
+            Configured GraphQL client
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            AdapterError: If client creation fails
+        """
+        if Client is None:
+            raise AdapterError("gql library not installed. Install with: pip install gql[aiohttp]", "linear")
+
+        if not self.api_key:
+            raise AuthenticationError("Linear API key is required", "linear")
+
+        try:
+            # Create transport with authentication
+            transport = AIOHTTPTransport(
+                url=self._base_url,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=self.timeout,
+            )
+
+            # Create client
+            client = Client(transport=transport, fetch_schema_from_transport=False)
+            return client
+
+        except Exception as e:
+            raise AdapterError(f"Failed to create Linear client: {e}", "linear")
+    
+    async def execute_query(
+        self,
+        query_string: str,
+        variables: Optional[Dict[str, Any]] = None,
+        retries: int = 3,
+    ) -> Dict[str, Any]:
+        """Execute a GraphQL query with error handling and retries.
+        
+        Args:
+            query_string: GraphQL query string
+            variables: Query variables
+            retries: Number of retry attempts
+            
+        Returns:
+            Query result data
+            
+        Raises:
+            AuthenticationError: If authentication fails
+            RateLimitError: If rate limit is exceeded
+            AdapterError: If query execution fails
+        """
+        query = gql(query_string)
+        
+        for attempt in range(retries + 1):
+            try:
+                client = self.create_client()
+                async with client as session:
+                    result = await session.execute(query, variable_values=variables or {})
+                return result
+                
+            except TransportError as e:
+                # Handle HTTP errors
+                if hasattr(e, 'response') and e.response:
+                    status_code = e.response.status
+                    
+                    if status_code == 401:
+                        raise AuthenticationError("Invalid Linear API key", "linear")
+                    elif status_code == 403:
+                        raise AuthenticationError("Insufficient permissions", "linear")
+                    elif status_code == 429:
+                        # Rate limit exceeded
+                        retry_after = e.response.headers.get("Retry-After", "60")
+                        raise RateLimitError(
+                            "Linear API rate limit exceeded",
+                            "linear",
+                            retry_after
+                        )
+                    elif status_code >= 500:
+                        # Server error - retry
+                        if attempt < retries:
+                            await asyncio.sleep(2 ** attempt)  # Exponential backoff
+                            continue
+                        raise AdapterError(f"Linear API server error: {status_code}", "linear")
+                
+                # Network or other transport error
+                if attempt < retries:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                raise AdapterError(f"Linear API transport error: {e}", "linear")
+                
+            except Exception as e:
+                # GraphQL or other errors
+                error_msg = str(e)
+                
+                # Check for specific GraphQL errors
+                if "authentication" in error_msg.lower() or "unauthorized" in error_msg.lower():
+                    raise AuthenticationError(f"Linear authentication failed: {error_msg}", "linear")
+                elif "rate limit" in error_msg.lower():
+                    raise RateLimitError("Linear API rate limit exceeded", "linear")
+                
+                # Generic error
+                if attempt < retries:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                raise AdapterError(f"Linear GraphQL error: {error_msg}", "linear")
+        
+        # Should never reach here
+        raise AdapterError("Maximum retries exceeded", "linear")
+    
+    async def execute_mutation(
+        self,
+        mutation_string: str,
+        variables: Optional[Dict[str, Any]] = None,
+        retries: int = 3,
+    ) -> Dict[str, Any]:
+        """Execute a GraphQL mutation with error handling.
+        
+        Args:
+            mutation_string: GraphQL mutation string
+            variables: Mutation variables
+            retries: Number of retry attempts
+            
+        Returns:
+            Mutation result data
+            
+        Raises:
+            AuthenticationError: If authentication fails
+            RateLimitError: If rate limit is exceeded
+            AdapterError: If mutation execution fails
+        """
+        return await self.execute_query(mutation_string, variables, retries)
+    
+    async def test_connection(self) -> bool:
+        """Test the connection to Linear API.
+        
+        Returns:
+            True if connection is successful, False otherwise
+        """
+        try:
+            # Simple query to test authentication
+            test_query = """
+                query TestConnection {
+                    viewer {
+                        id
+                        name
+                    }
+                }
+            """
+            
+            result = await self.execute_query(test_query)
+            return bool(result.get("viewer"))
+            
+        except Exception:
+            return False
+    
+    async def get_team_info(self, team_id: str) -> Optional[Dict[str, Any]]:
+        """Get team information by ID.
+        
+        Args:
+            team_id: Linear team ID
+            
+        Returns:
+            Team information or None if not found
+        """
+        try:
+            query = """
+                query GetTeam($teamId: String!) {
+                    team(id: $teamId) {
+                        id
+                        name
+                        key
+                        description
+                    }
+                }
+            """
+            
+            result = await self.execute_query(query, {"teamId": team_id})
+            return result.get("team")
+            
+        except Exception:
+            return None
+    
+    async def get_user_by_email(self, email: str) -> Optional[Dict[str, Any]]:
+        """Get user information by email.
+        
+        Args:
+            email: User email address
+            
+        Returns:
+            User information or None if not found
+        """
+        try:
+            query = """
+                query GetUserByEmail($email: String!) {
+                    users(filter: { email: { eq: $email } }) {
+                        nodes {
+                            id
+                            name
+                            email
+                            displayName
+                            avatarUrl
+                        }
+                    }
+                }
+            """
+            
+            result = await self.execute_query(query, {"email": email})
+            users = result.get("users", {}).get("nodes", [])
+            return users[0] if users else None
+            
+        except Exception:
+            return None
+    
+    async def close(self) -> None:
+        """Close the client connection.
+        
+        Since we create fresh clients for each operation, there's no persistent
+        connection to close. Each client's transport is automatically closed when
+        the async context manager exits.
+        """
+        pass

mcp_ticketer/adapters/linear/mappers.py

@@ -0,0 +1,307 @@
+"""Data transformation mappers for Linear API responses."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from ...core.models import Comment, Epic, Priority, Task, TicketState
+from .types import (
+    extract_linear_metadata,
+    get_universal_priority,
+    get_universal_state,
+)
+
+
+def map_linear_issue_to_task(issue_data: Dict[str, Any]) -> Task:
+    """Convert Linear issue data to universal Task model.
+    
+    Args:
+        issue_data: Raw Linear issue data from GraphQL
+        
+    Returns:
+        Universal Task model
+    """
+    # Extract basic fields
+    task_id = issue_data["identifier"]
+    title = issue_data["title"]
+    description = issue_data.get("description", "")
+    
+    # Map priority
+    linear_priority = issue_data.get("priority", 3)
+    priority = get_universal_priority(linear_priority)
+    
+    # Map state
+    state_data = issue_data.get("state", {})
+    state_type = state_data.get("type", "unstarted")
+    state = get_universal_state(state_type)
+    
+    # Extract assignee
+    assignee = None
+    if issue_data.get("assignee"):
+        assignee_data = issue_data["assignee"]
+        assignee = assignee_data.get("email") or assignee_data.get("displayName")
+    
+    # Extract creator
+    creator = None
+    if issue_data.get("creator"):
+        creator_data = issue_data["creator"]
+        creator = creator_data.get("email") or creator_data.get("displayName")
+    
+    # Extract tags (labels)
+    tags = []
+    if issue_data.get("labels", {}).get("nodes"):
+        tags = [label["name"] for label in issue_data["labels"]["nodes"]]
+    
+    # Extract parent epic (project)
+    parent_epic = None
+    if issue_data.get("project"):
+        parent_epic = issue_data["project"]["id"]
+    
+    # Extract parent issue
+    parent_issue = None
+    if issue_data.get("parent"):
+        parent_issue = issue_data["parent"]["identifier"]
+    
+    # Extract dates
+    created_at = None
+    if issue_data.get("createdAt"):
+        created_at = datetime.fromisoformat(issue_data["createdAt"].replace("Z", "+00:00"))
+    
+    updated_at = None
+    if issue_data.get("updatedAt"):
+        updated_at = datetime.fromisoformat(issue_data["updatedAt"].replace("Z", "+00:00"))
+    
+    # Extract Linear-specific metadata
+    linear_metadata = extract_linear_metadata(issue_data)
+    metadata = {"linear": linear_metadata} if linear_metadata else None
+    
+    return Task(
+        id=task_id,
+        title=title,
+        description=description,
+        state=state,
+        priority=priority,
+        assignee=assignee,
+        creator=creator,
+        tags=tags,
+        parent_epic=parent_epic,
+        parent_issue=parent_issue,
+        created_at=created_at,
+        updated_at=updated_at,
+        metadata=metadata,
+    )
+
+
+def map_linear_project_to_epic(project_data: Dict[str, Any]) -> Epic:
+    """Convert Linear project data to universal Epic model.
+    
+    Args:
+        project_data: Raw Linear project data from GraphQL
+        
+    Returns:
+        Universal Epic model
+    """
+    # Extract basic fields
+    epic_id = project_data["id"]
+    title = project_data["name"]
+    description = project_data.get("description", "")
+    
+    # Map state based on project state
+    project_state = project_data.get("state", "planned")
+    if project_state == "completed":
+        state = TicketState.DONE
+    elif project_state == "started":
+        state = TicketState.IN_PROGRESS
+    elif project_state == "canceled":
+        state = TicketState.CLOSED
+    else:
+        state = TicketState.OPEN
+    
+    # Extract dates
+    created_at = None
+    if project_data.get("createdAt"):
+        created_at = datetime.fromisoformat(project_data["createdAt"].replace("Z", "+00:00"))
+    
+    updated_at = None
+    if project_data.get("updatedAt"):
+        updated_at = datetime.fromisoformat(project_data["updatedAt"].replace("Z", "+00:00"))
+    
+    # Extract Linear-specific metadata
+    metadata = {"linear": {}}
+    if project_data.get("url"):
+        metadata["linear"]["linear_url"] = project_data["url"]
+    if project_data.get("icon"):
+        metadata["linear"]["icon"] = project_data["icon"]
+    if project_data.get("color"):
+        metadata["linear"]["color"] = project_data["color"]
+    if project_data.get("targetDate"):
+        metadata["linear"]["target_date"] = project_data["targetDate"]
+    
+    return Epic(
+        id=epic_id,
+        title=title,
+        description=description,
+        state=state,
+        priority=Priority.MEDIUM,  # Projects don't have priority in Linear
+        created_at=created_at,
+        updated_at=updated_at,
+        metadata=metadata if metadata["linear"] else None,
+    )
+
+
+def map_linear_comment_to_comment(comment_data: Dict[str, Any], ticket_id: str) -> Comment:
+    """Convert Linear comment data to universal Comment model.
+    
+    Args:
+        comment_data: Raw Linear comment data from GraphQL
+        ticket_id: ID of the ticket this comment belongs to
+        
+    Returns:
+        Universal Comment model
+    """
+    # Extract basic fields
+    comment_id = comment_data["id"]
+    body = comment_data.get("body", "")
+    
+    # Extract author
+    author = None
+    if comment_data.get("user"):
+        user_data = comment_data["user"]
+        author = user_data.get("email") or user_data.get("displayName")
+    
+    # Extract dates
+    created_at = None
+    if comment_data.get("createdAt"):
+        created_at = datetime.fromisoformat(comment_data["createdAt"].replace("Z", "+00:00"))
+    
+    updated_at = None
+    if comment_data.get("updatedAt"):
+        updated_at = datetime.fromisoformat(comment_data["updatedAt"].replace("Z", "+00:00"))
+    
+    return Comment(
+        id=comment_id,
+        ticket_id=ticket_id,
+        body=body,
+        author=author,
+        created_at=created_at,
+        updated_at=updated_at,
+    )
+
+
+def build_linear_issue_input(task: Task, team_id: str) -> Dict[str, Any]:
+    """Build Linear issue input from universal Task model.
+    
+    Args:
+        task: Universal Task model
+        team_id: Linear team ID
+        
+    Returns:
+        Linear issue input dictionary
+    """
+    from .types import get_linear_priority
+    
+    issue_input = {
+        "title": task.title,
+        "teamId": team_id,
+    }
+    
+    # Add description if provided
+    if task.description:
+        issue_input["description"] = task.description
+    
+    # Add priority
+    if task.priority:
+        issue_input["priority"] = get_linear_priority(task.priority)
+    
+    # Add assignee if provided (assumes it's a user ID)
+    if task.assignee:
+        issue_input["assigneeId"] = task.assignee
+    
+    # Add parent issue if provided
+    if task.parent_issue:
+        issue_input["parentId"] = task.parent_issue
+    
+    # Add project (epic) if provided
+    if task.parent_epic:
+        issue_input["projectId"] = task.parent_epic
+    
+    # Add labels (tags) if provided
+    if task.tags:
+        # Note: Linear requires label IDs, not names
+        # This would need to be resolved by the adapter
+        pass
+    
+    # Add Linear-specific metadata
+    if task.metadata and "linear" in task.metadata:
+        linear_meta = task.metadata["linear"]
+        if "due_date" in linear_meta:
+            issue_input["dueDate"] = linear_meta["due_date"]
+        if "cycle_id" in linear_meta:
+            issue_input["cycleId"] = linear_meta["cycle_id"]
+        if "estimate" in linear_meta:
+            issue_input["estimate"] = linear_meta["estimate"]
+    
+    return issue_input
+
+
+def build_linear_issue_update_input(updates: Dict[str, Any]) -> Dict[str, Any]:
+    """Build Linear issue update input from update dictionary.
+    
+    Args:
+        updates: Dictionary of fields to update
+        
+    Returns:
+        Linear issue update input dictionary
+    """
+    from .types import get_linear_priority
+    
+    update_input = {}
+    
+    # Map standard fields
+    if "title" in updates:
+        update_input["title"] = updates["title"]
+    
+    if "description" in updates:
+        update_input["description"] = updates["description"]
+    
+    if "priority" in updates:
+        priority = Priority(updates["priority"]) if isinstance(updates["priority"], str) else updates["priority"]
+        update_input["priority"] = get_linear_priority(priority)
+    
+    if "assignee" in updates:
+        update_input["assigneeId"] = updates["assignee"]
+    
+    # Handle state transitions (would need workflow state mapping)
+    if "state" in updates:
+        # This would need to be handled by the adapter with proper state mapping
+        pass
+    
+    # Handle metadata updates
+    if "metadata" in updates and "linear" in updates["metadata"]:
+        linear_meta = updates["metadata"]["linear"]
+        if "due_date" in linear_meta:
+            update_input["dueDate"] = linear_meta["due_date"]
+        if "cycle_id" in linear_meta:
+            update_input["cycleId"] = linear_meta["cycle_id"]
+        if "project_id" in linear_meta:
+            update_input["projectId"] = linear_meta["project_id"]
+        if "estimate" in linear_meta:
+            update_input["estimate"] = linear_meta["estimate"]
+    
+    return update_input
+
+
+def extract_child_issue_ids(issue_data: Dict[str, Any]) -> List[str]:
+    """Extract child issue IDs from Linear issue data.
+    
+    Args:
+        issue_data: Raw Linear issue data from GraphQL
+        
+    Returns:
+        List of child issue identifiers
+    """
+    child_ids = []
+    if issue_data.get("children", {}).get("nodes"):
+        child_ids = [child["identifier"] for child in issue_data["children"]["nodes"]]
+    return child_ids