cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/jira/__init__.py

@@ -0,0 +1,298 @@
+"""
+Jira connector for CortexDB.
+
+Polls Jira projects for recently updated issues using JQL and ingests
+them as CortexDB Episodes.  Uses the ``jira`` library for API access.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from cortexdb_connectors.base import (
+    Actor,
+    CortexConnector,
+    EntityRef,
+    Episode,
+    EpisodeType,
+    RawEvent,
+    Source,
+    Visibility,
+    VisibilityLevel,
+)
+
+logger = logging.getLogger(__name__)
+
+_SOURCE = Source(system="jira")
+
+_PAGE_SIZE = 50
+
+
+class JiraConnector(CortexConnector):
+    """Connector that syncs Jira issues into CortexDB.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB API.
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    jira_url:
+        Base URL of the Jira instance (e.g. ``https://myteam.atlassian.net``).
+    jira_email:
+        Email address for Jira authentication.
+    jira_api_token:
+        Jira API token (Atlassian account token).
+    project_keys:
+        List of Jira project keys to sync (e.g. ``["ENG", "INFRA"]``).
+    tenant_id:
+        CortexDB tenant identifier.
+    """
+
+    connector_name: str = "jira"
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        jira_url: str,
+        jira_email: str,
+        jira_api_token: str,
+        project_keys: list[str] | None = None,
+        tenant_id: str = "default",
+    ) -> None:
+        super().__init__(cortex_url, cortex_api_key, tenant_id)
+        self.jira_url = jira_url.rstrip("/")
+        self.jira_email = jira_email
+        self.jira_api_token = jira_api_token
+        self.project_keys = project_keys or []
+
+    # -- CortexConnector interface -------------------------------------------
+
+    async def fetch_events(
+        self, since: datetime | None = None
+    ) -> list[RawEvent]:
+        """Fetch issues updated since *since* from configured Jira projects.
+
+        Uses JQL ``project in (...) AND updated >= "..."`` with pagination.
+        """
+        from jira import JIRA
+
+        client = JIRA(
+            server=self.jira_url,
+            basic_auth=(self.jira_email, self.jira_api_token),
+        )
+
+        jql_parts: list[str] = []
+        if self.project_keys:
+            keys_str = ", ".join(self.project_keys)
+            jql_parts.append(f"project in ({keys_str})")
+        if since:
+            jql_date = since.strftime("%Y-%m-%d %H:%M")
+            jql_parts.append(f'updated >= "{jql_date}"')
+
+        jql = " AND ".join(jql_parts) if jql_parts else "ORDER BY updated DESC"
+        if jql_parts:
+            jql += " ORDER BY updated DESC"
+
+        raw_events: list[RawEvent] = []
+        start_at = 0
+
+        while True:
+            results = client.search_issues(
+                jql,
+                startAt=start_at,
+                maxResults=_PAGE_SIZE,
+                expand="changelog",
+            )
+
+            for issue in results:
+                fields = issue.fields
+                updated_str = getattr(fields, "updated", None) or ""
+                try:
+                    updated_at = datetime.fromisoformat(
+                        updated_str.replace("Z", "+00:00")
+                    )
+                except (ValueError, TypeError):
+                    updated_at = datetime.now(timezone.utc)
+
+                issue_data = self._serialize_issue(issue)
+                project_data = issue_data.get("project", {})
+
+                raw_events.append(
+                    RawEvent(
+                        source="jira",
+                        external_id=issue.key,
+                        timestamp=updated_at,
+                        data=issue_data,
+                        permissions={
+                            "project_key": project_data.get("key", ""),
+                            "project_type": project_data.get(
+                                "projectTypeKey", "software"
+                            ),
+                        },
+                    )
+                )
+
+            if start_at + _PAGE_SIZE >= results.total:
+                break
+            start_at += _PAGE_SIZE
+
+        return raw_events
+
+    def normalize(self, raw: RawEvent) -> Episode:
+        """Convert a Jira issue ``RawEvent`` into a CortexDB ``Episode``."""
+        data = raw.data
+        actor = self._extract_actor(data)
+        entities = self._extract_entities(data)
+
+        status = data.get("status", "Unknown")
+        priority = data.get("priority", "Medium")
+        summary = data.get("summary", "Untitled")
+        issue_key = data.get("key", raw.external_id)
+        issue_type = data.get("issuetype", "Task")
+        description = data.get("description", "") or ""
+
+        content = f"[{issue_key}] {summary}"
+        if description:
+            content += f"\n\n{description[:500]}"
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.ISSUE,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace="jira",
+            entities=entities,
+            tags=["jira", status.lower().replace(" ", "_"), issue_type.lower()],
+            metadata={
+                "issue_key": issue_key,
+                "status": status,
+                "priority": priority,
+                "issue_type": issue_type,
+                "labels": data.get("labels", []),
+                "components": data.get("components", []),
+                "sprint": data.get("sprint"),
+                "story_points": data.get("story_points"),
+            },
+            thread_id=f"jira:{issue_key}",
+            idempotency_key=f"{raw.external_id}:{raw.timestamp.isoformat()}",
+        )
+
+    def map_permissions(self, raw: RawEvent) -> Visibility:
+        """Map Jira project visibility to CortexDB visibility.
+
+        Projects with ``projectTypeKey`` of ``service_desk`` are treated as
+        potentially customer-facing and marked ``Restricted``.  All others
+        default to ``Organization``.
+        """
+        project_type = raw.permissions.get("project_type", "software")
+        if project_type == "service_desk":
+            return Visibility(level=VisibilityLevel.RESTRICTED)
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- helpers -------------------------------------------------------------
+
+    @staticmethod
+    def _serialize_issue(issue: Any) -> dict[str, Any]:
+        """Flatten a ``jira.Issue`` into a plain dict."""
+        fields = issue.fields
+        assignee = getattr(fields, "assignee", None)
+        reporter = getattr(fields, "reporter", None)
+        priority = getattr(fields, "priority", None)
+        status = getattr(fields, "status", None)
+        issuetype = getattr(fields, "issuetype", None)
+        project = getattr(fields, "project", None)
+
+        return {
+            "key": issue.key,
+            "id": issue.id,
+            "summary": getattr(fields, "summary", ""),
+            "description": getattr(fields, "description", ""),
+            "status": str(status) if status else "Unknown",
+            "priority": str(priority) if priority else "Medium",
+            "issuetype": str(issuetype) if issuetype else "Task",
+            "assignee": {
+                "name": getattr(assignee, "displayName", "Unassigned"),
+                "email": getattr(assignee, "emailAddress", None),
+                "account_id": getattr(assignee, "accountId", None),
+            }
+            if assignee
+            else None,
+            "reporter": {
+                "name": getattr(reporter, "displayName", "Unknown"),
+                "email": getattr(reporter, "emailAddress", None),
+                "account_id": getattr(reporter, "accountId", None),
+            }
+            if reporter
+            else None,
+            "project": {
+                "key": getattr(project, "key", ""),
+                "name": getattr(project, "name", ""),
+                "projectTypeKey": getattr(project, "projectTypeKey", "software"),
+            }
+            if project
+            else {},
+            "labels": list(getattr(fields, "labels", []) or []),
+            "components": [
+                str(c) for c in (getattr(fields, "components", []) or [])
+            ],
+            "created": getattr(fields, "created", ""),
+            "updated": getattr(fields, "updated", ""),
+            "sprint": None,  # Populated from custom fields if available.
+            "story_points": None,
+        }
+
+    @staticmethod
+    def _extract_actor(data: dict[str, Any]) -> Actor:
+        """Extract the primary actor (reporter) from issue data."""
+        reporter = data.get("reporter")
+        if reporter:
+            return Actor(
+                id=reporter.get("account_id", "unknown"),
+                name=reporter.get("name", "Unknown"),
+                email=reporter.get("email"),
+            )
+        return Actor(id="unknown", name="Unknown")
+
+    @staticmethod
+    def _extract_entities(data: dict[str, Any]) -> list[EntityRef]:
+        """Extract entity references from issue data."""
+        entities: list[EntityRef] = []
+
+        project = data.get("project", {})
+        if project.get("key"):
+            entities.append(
+                EntityRef(
+                    entity_type="project",
+                    entity_id=project["key"],
+                    display_name=project.get("name", project["key"]),
+                )
+            )
+
+        assignee = data.get("assignee")
+        if assignee and assignee.get("account_id"):
+            entities.append(
+                EntityRef(
+                    entity_type="user",
+                    entity_id=assignee["account_id"],
+                    display_name=assignee.get("name", ""),
+                )
+            )
+
+        reporter = data.get("reporter")
+        if reporter and reporter.get("account_id"):
+            entities.append(
+                EntityRef(
+                    entity_type="user",
+                    entity_id=reporter["account_id"],
+                    display_name=reporter.get("name", ""),
+                )
+            )
+
+        return entities