# aiel_sdk/jira/client.py
from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any, Dict, Optional, Sequence, List

from .types import (
    JiraMyself,
    JiraAccessibleSite,
    JiraCreateIssueRequest,
    JiraAddCommentRequest,
    JiraTransitionIssueRequest,
    DEFAULT_JIRA_CAPABILITIES,
    JiraCapabilities,
)

Json = Dict[str, Any]


class JiraClient(ABC):
    """
    Framework-agnostic Jira client (CONNECTION_ID-first).

    Your platform routes by:
      - connection_id
      - action (e.g. "jira.create_issue")
      - params (JSON dict)

    This interface is intentionally small and stable so it can be used by
    LangChain tools, LangGraph nodes, or any custom agent runtime.
    """

    @property
    def capabilities(self) -> JiraCapabilities:
        return DEFAULT_JIRA_CAPABILITIES

    # ---- Identity / discovery ----
    @abstractmethod
    def myself(self) -> JiraMyself:
        """Return the current Jira/Atlassian user profile."""
        raise NotImplementedError

    @abstractmethod
    def list_sites(self) -> List[JiraAccessibleSite]:
        """Return Atlassian accessible resources for the current connection."""
        raise NotImplementedError

    # ---- Issues ----
    @abstractmethod
    def create_issue(self, *, req: JiraCreateIssueRequest) -> Json:
        """
        Create a Jira issue.

        Backend behavior:
          - if req.fields is set, it is passed through
          - else project_key+summary are required, issue_type defaults to "Task"
        Returns the raw Jira issue creation response as JSON.
        """
        raise NotImplementedError

    @abstractmethod
    def add_comment(self, *, req: JiraAddCommentRequest) -> Json:
        """Add a comment to an issue. Returns raw provider response JSON."""
        raise NotImplementedError

    @abstractmethod
    def transition_issue(self, *, req: JiraTransitionIssueRequest) -> Json:
        """Transition an issue. Returns raw provider response JSON."""
        raise NotImplementedError