cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/pagerduty/__init__.py

@@ -0,0 +1,298 @@
+"""
+PagerDuty connector for CortexDB.
+
+Polls PagerDuty for incidents and log entries, converting them into
+CortexDB Episodes.  Uses the ``pdpyras`` 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="pagerduty")
+
+
+class PagerDutyConnector(CortexConnector):
+    """Connector that syncs PagerDuty incidents into CortexDB.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB API.
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    pagerduty_api_key:
+        PagerDuty REST API key (v2).
+    service_ids:
+        Optional list of PagerDuty service IDs to restrict the sync to.
+        If empty, all incidents visible to the API key are synced.
+    tenant_id:
+        CortexDB tenant identifier.
+    """
+
+    connector_name: str = "pagerduty"
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        pagerduty_api_key: str,
+        service_ids: list[str] | None = None,
+        tenant_id: str = "default",
+    ) -> None:
+        super().__init__(cortex_url, cortex_api_key, tenant_id)
+        self.pagerduty_api_key = pagerduty_api_key
+        self.service_ids = service_ids or []
+
+    # -- CortexConnector interface -------------------------------------------
+
+    async def fetch_events(
+        self, since: datetime | None = None
+    ) -> list[RawEvent]:
+        """Fetch incidents and their log entries from PagerDuty.
+
+        Returns one ``RawEvent`` per incident state-change (triggered,
+        acknowledged, resolved) as recorded in the incident log entries.
+        """
+        from pdpyras import APISession
+
+        session = APISession(self.pagerduty_api_key)
+        raw_events: list[RawEvent] = []
+
+        params: dict[str, Any] = {
+            "sort_by": "created_at:desc",
+        }
+        if since:
+            params["since"] = since.isoformat()
+        if self.service_ids:
+            params["service_ids[]"] = self.service_ids
+
+        try:
+            incidents = session.list_all("incidents", params=params)
+        except Exception:
+            logger.exception("Failed to list PagerDuty incidents")
+            return raw_events
+
+        for incident in incidents:
+            created_str = incident.get("created_at", "")
+            try:
+                created_at = datetime.fromisoformat(
+                    created_str.replace("Z", "+00:00")
+                )
+            except (ValueError, TypeError):
+                created_at = datetime.now(timezone.utc)
+
+            raw_events.append(
+                RawEvent(
+                    source="pagerduty",
+                    external_id=incident.get("id", ""),
+                    timestamp=created_at,
+                    data={
+                        "type": "incident",
+                        "incident": incident,
+                    },
+                    permissions={},
+                )
+            )
+
+            # Fetch log entries for state-change tracking.
+            try:
+                log_entries = session.list_all(
+                    f"incidents/{incident['id']}/log_entries"
+                )
+            except Exception:
+                logger.debug(
+                    "Could not fetch log entries for %s", incident.get("id")
+                )
+                continue
+
+            for entry in log_entries:
+                entry_ts_str = entry.get("created_at", "")
+                try:
+                    entry_ts = datetime.fromisoformat(
+                        entry_ts_str.replace("Z", "+00:00")
+                    )
+                except (ValueError, TypeError):
+                    entry_ts = created_at
+
+                if since and entry_ts <= since:
+                    continue
+
+                raw_events.append(
+                    RawEvent(
+                        source="pagerduty",
+                        external_id=entry.get("id", ""),
+                        timestamp=entry_ts,
+                        data={
+                            "type": "log_entry",
+                            "log_entry": entry,
+                            "incident_id": incident.get("id", ""),
+                            "incident_title": incident.get("title", ""),
+                        },
+                        permissions={},
+                    )
+                )
+
+        return raw_events
+
+    def normalize(self, raw: RawEvent) -> Episode:
+        """Convert a PagerDuty event into a CortexDB ``Episode``."""
+        data = raw.data
+        event_kind = data.get("type", "incident")
+
+        if event_kind == "incident":
+            return self._normalize_incident(raw)
+        return self._normalize_log_entry(raw)
+
+    def map_permissions(self, raw: RawEvent) -> Visibility:
+        """PagerDuty data is internal; always ``Organization`` visibility."""
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- normalization helpers -----------------------------------------------
+
+    def _normalize_incident(self, raw: RawEvent) -> Episode:
+        """Normalize an incident-level event."""
+        incident = raw.data.get("incident", {})
+        title = incident.get("title", "Untitled incident")
+        status = incident.get("status", "unknown")
+        urgency = incident.get("urgency", "unknown")
+        service = incident.get("service", {})
+
+        actor = self._extract_actor(incident)
+        entities = self._extract_entities(incident)
+
+        content = f"[{status.upper()}] {title}"
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.INCIDENT,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=raw.data,
+            tenant_id=self.tenant_id,
+            namespace="pagerduty",
+            entities=entities,
+            tags=["pagerduty", "incident", status],
+            metadata={
+                "status": status,
+                "urgency": urgency,
+                "severity": incident.get("severity", {}).get("value", "unknown"),
+                "service_id": service.get("id", ""),
+                "service_name": service.get("summary", ""),
+                "incident_number": incident.get("incident_number"),
+                "escalation_policy": incident.get("escalation_policy", {}).get(
+                    "summary", ""
+                ),
+            },
+            thread_id=f"pd:incident:{incident.get('id', '')}",
+            idempotency_key=raw.external_id,
+        )
+
+    def _normalize_log_entry(self, raw: RawEvent) -> Episode:
+        """Normalize an incident log-entry event."""
+        entry = raw.data.get("log_entry", {})
+        incident_id = raw.data.get("incident_id", "")
+        incident_title = raw.data.get("incident_title", "")
+        entry_type = entry.get("type", "unknown")
+
+        agent = entry.get("agent", {})
+        actor = Actor(
+            id=agent.get("id", "system"),
+            name=agent.get("summary", "PagerDuty"),
+        )
+
+        summary = entry.get("summary", entry_type)
+        content = f"{summary} on incident: {incident_title}"
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.INCIDENT,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=raw.data,
+            tenant_id=self.tenant_id,
+            namespace="pagerduty",
+            entities=[
+                EntityRef(
+                    entity_type="incident",
+                    entity_id=incident_id,
+                    display_name=incident_title,
+                ),
+            ],
+            tags=["pagerduty", "log_entry", entry_type],
+            metadata={
+                "log_entry_type": entry_type,
+                "channel_type": entry.get("channel", {}).get("type", ""),
+            },
+            thread_id=f"pd:incident:{incident_id}",
+            parent_id=f"pd:incident:{incident_id}",
+            idempotency_key=raw.external_id,
+        )
+
+    @staticmethod
+    def _extract_actor(incident: dict[str, Any]) -> Actor:
+        """Extract the primary actor from an incident payload."""
+        assignments = incident.get("assignments", [])
+        if assignments:
+            assignee = assignments[0].get("assignee", {})
+            return Actor(
+                id=assignee.get("id", "unassigned"),
+                name=assignee.get("summary", "Unknown"),
+            )
+        return Actor(id="system", name="PagerDuty")
+
+    @staticmethod
+    def _extract_entities(incident: dict[str, Any]) -> list[EntityRef]:
+        """Extract entity references from an incident."""
+        entities: list[EntityRef] = []
+
+        service = incident.get("service", {})
+        if service.get("id"):
+            entities.append(
+                EntityRef(
+                    entity_type="service",
+                    entity_id=service["id"],
+                    display_name=service.get("summary", ""),
+                )
+            )
+
+        for assignment in incident.get("assignments", []):
+            assignee = assignment.get("assignee", {})
+            if assignee.get("id"):
+                entities.append(
+                    EntityRef(
+                        entity_type="user",
+                        entity_id=assignee["id"],
+                        display_name=assignee.get("summary", ""),
+                    )
+                )
+
+        escalation = incident.get("escalation_policy", {})
+        if escalation.get("id"):
+            entities.append(
+                EntityRef(
+                    entity_type="escalation_policy",
+                    entity_id=escalation["id"],
+                    display_name=escalation.get("summary", ""),
+                )
+            )
+
+        return entities

cortexdb_connectors/salesforce/__init__.py

@@ -0,0 +1,399 @@
+"""
+Salesforce connector for CortexDB.
+
+Polls Salesforce for Cases, Opportunities, Accounts, Tasks, Chatter feed,
+and Notes, converting them into CortexDB Episodes.  Uses the
+``simple-salesforce`` library for REST API / SOQL access with OAuth2
+authentication.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, 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="salesforce")
+
+_DEFAULT_OBJECTS = frozenset(
+    ["Case", "Opportunity", "Account", "Task", "FeedItem", "Note"]
+)
+
+_OBJECT_TYPE_MAP: dict[str, EpisodeType] = {
+    "Case": EpisodeType.ISSUE,
+    "Opportunity": EpisodeType.DOCUMENT,
+    "Account": EpisodeType.DOCUMENT,
+    "Task": EpisodeType.ISSUE,
+    "FeedItem": EpisodeType.MESSAGE,
+    "Note": EpisodeType.COMMENT,
+}
+
+
+class SalesforceConnector(CortexConnector):
+    """Connector that syncs Salesforce objects into CortexDB.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB API.
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    instance_url:
+        Salesforce instance URL (e.g. ``https://myorg.salesforce.com``).
+    client_id:
+        OAuth2 connected-app client ID.
+    client_secret:
+        OAuth2 connected-app client secret.
+    username:
+        Salesforce username for password-based OAuth flow.
+    password:
+        Salesforce password (with security token appended if required).
+    objects:
+        Salesforce object types to ingest.  Defaults to Case, Opportunity,
+        Account, Task, FeedItem, Note.
+    namespace:
+        CortexDB namespace for ingested episodes.
+    backfill_days:
+        Number of days of historical data to backfill on first sync.
+    tenant_id:
+        CortexDB tenant identifier.
+    """
+
+    connector_name: str = "salesforce"
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        instance_url: str,
+        client_id: str,
+        client_secret: str,
+        username: str,
+        password: str,
+        objects: list[str] | None = None,
+        namespace: str = "salesforce",
+        backfill_days: int = 90,
+        tenant_id: str = "default",
+    ) -> None:
+        super().__init__(cortex_url, cortex_api_key, tenant_id)
+        self.instance_url = instance_url.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.username = username
+        self.password = password
+        self.object_filter = set(objects) if objects else set(_DEFAULT_OBJECTS)
+        self.namespace = namespace
+        self.backfill_days = backfill_days
+        self._sf_client: Any = None
+
+    # -- Salesforce client management ----------------------------------------
+
+    def _get_client(self) -> Any:
+        """Lazy-initialise and return the simple-salesforce client."""
+        if self._sf_client is not None:
+            return self._sf_client
+
+        from simple_salesforce import Salesforce
+
+        self._sf_client = Salesforce(
+            username=self.username,
+            password=self.password,
+            consumer_key=self.client_id,
+            consumer_secret=self.client_secret,
+            instance_url=self.instance_url,
+        )
+        return self._sf_client
+
+    # -- CortexConnector interface -------------------------------------------
+
+    async def fetch_events(
+        self, since: datetime | None = None
+    ) -> list[RawEvent]:
+        """Fetch records from configured Salesforce objects via SOQL.
+
+        Uses ``LastModifiedDate`` for incremental sync and handles
+        query-more pagination for large result sets.
+        """
+        sf = self._get_client()
+        cutoff = since or datetime.now(timezone.utc) - timedelta(
+            days=self.backfill_days
+        )
+        cutoff_str = cutoff.strftime("%Y-%m-%dT%H:%M:%SZ")
+        raw_events: list[RawEvent] = []
+
+        for obj_type in self.object_filter:
+            try:
+                fields = self._fields_for(obj_type)
+                soql = (
+                    f"SELECT {fields} FROM {obj_type} "
+                    f"WHERE LastModifiedDate > {cutoff_str} "
+                    f"ORDER BY LastModifiedDate DESC"
+                )
+                result = sf.query(soql)
+                raw_events.extend(
+                    self._records_to_events(obj_type, result.get("records", []))
+                )
+
+                # Handle query-more pagination.
+                while not result.get("done", True):
+                    next_url = result.get("nextRecordsUrl", "")
+                    if not next_url:
+                        break
+                    result = sf.query_more(next_url, identifier_is_url=True)
+                    raw_events.extend(
+                        self._records_to_events(
+                            obj_type, result.get("records", [])
+                        )
+                    )
+            except Exception:
+                logger.exception(
+                    "Failed to fetch Salesforce %s records", obj_type
+                )
+                continue
+
+        return raw_events
+
+    def normalize(self, raw: RawEvent) -> Episode:
+        """Convert a Salesforce record ``RawEvent`` into a CortexDB ``Episode``."""
+        data = raw.data
+        obj_type = data.get("object_type", "Unknown")
+        record = data.get("record", {})
+        episode_type = _OBJECT_TYPE_MAP.get(obj_type, EpisodeType.CUSTOM)
+
+        actor = self._extract_actor(record)
+        content = self._build_content(obj_type, record)
+        entities = self._extract_entities(obj_type, record)
+        tags = ["salesforce", obj_type.lower()]
+        thread_id = self._derive_thread_id(obj_type, record)
+
+        metadata: dict[str, Any] = {
+            "salesforce_object": obj_type,
+            "salesforce_id": record.get("Id", ""),
+        }
+        if record.get("Status"):
+            metadata["status"] = record["Status"]
+        if record.get("StageName"):
+            metadata["stage"] = record["StageName"]
+        if record.get("Priority"):
+            metadata["priority"] = record["Priority"]
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=episode_type,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace=self.namespace,
+            entities=entities,
+            tags=tags,
+            metadata=metadata,
+            thread_id=thread_id,
+            idempotency_key=f"sf:{obj_type}:{record.get('Id', raw.external_id)}",
+        )
+
+    def map_permissions(self, raw: RawEvent) -> Visibility:
+        """Map Salesforce record visibility.
+
+        Records linked to portal users are ``Restricted``; everything else
+        is ``Organization``.
+        """
+        record = raw.data.get("record", {})
+        if record.get("IsEscalated") or record.get("ContactId"):
+            return Visibility(level=VisibilityLevel.RESTRICTED)
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- helpers -------------------------------------------------------------
+
+    @staticmethod
+    def _fields_for(obj_type: str) -> str:
+        """Return the SOQL field list for a given object type."""
+        base = "Id, LastModifiedDate, LastModifiedById, OwnerId"
+        fields_map: dict[str, str] = {
+            "Case": (
+                f"{base}, Subject, Description, Status, Priority, "
+                "CaseNumber, ContactId, AccountId, IsEscalated"
+            ),
+            "Opportunity": (
+                f"{base}, Name, StageName, Amount, CloseDate, "
+                "AccountId, Probability"
+            ),
+            "Account": f"{base}, Name, Industry, Type, BillingCity, Website",
+            "Task": (
+                f"{base}, Subject, Description, Status, Priority, "
+                "ActivityDate, WhoId, WhatId"
+            ),
+            "FeedItem": (
+                f"{base}, Body, Title, Type, ParentId, "
+                "CreatedById, CreatedDate"
+            ),
+            "Note": f"{base}, Title, Body, ParentId",
+        }
+        return fields_map.get(obj_type, base)
+
+    def _records_to_events(
+        self, obj_type: str, records: list[dict[str, Any]]
+    ) -> list[RawEvent]:
+        """Convert a batch of Salesforce records to RawEvents."""
+        events: list[RawEvent] = []
+        for rec in records:
+            ts_str = rec.get("LastModifiedDate", "")
+            try:
+                ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                ts = datetime.now(timezone.utc)
+
+            events.append(
+                RawEvent(
+                    source="salesforce",
+                    external_id=rec.get("Id", ""),
+                    timestamp=ts,
+                    data={
+                        "object_type": obj_type,
+                        "record": rec,
+                    },
+                    permissions={
+                        "owner_id": rec.get("OwnerId", ""),
+                        "is_escalated": rec.get("IsEscalated", False),
+                        "contact_id": rec.get("ContactId"),
+                    },
+                )
+            )
+        return events
+
+    @staticmethod
+    def _extract_actor(record: dict[str, Any]) -> Actor:
+        """Extract the actor from a Salesforce record."""
+        owner_id = record.get("OwnerId") or record.get("CreatedById") or ""
+        modifier_id = record.get("LastModifiedById") or owner_id
+        return Actor(
+            id=modifier_id,
+            name=modifier_id,  # Resolved to name during enrichment
+        )
+
+    @staticmethod
+    def _build_content(obj_type: str, record: dict[str, Any]) -> str:
+        """Build human-readable content from a Salesforce record."""
+        if obj_type == "Case":
+            subject = record.get("Subject", "Untitled case")
+            status = record.get("Status", "")
+            desc = (record.get("Description") or "")[:500]
+            return f"Case [{status}]: {subject}\n{desc}".strip()
+
+        if obj_type == "Opportunity":
+            name = record.get("Name", "Untitled opportunity")
+            stage = record.get("StageName", "")
+            amount = record.get("Amount")
+            amount_str = f" (${amount:,.2f})" if amount else ""
+            return f"Opportunity [{stage}]: {name}{amount_str}"
+
+        if obj_type == "Account":
+            name = record.get("Name", "Unnamed account")
+            industry = record.get("Industry", "")
+            acct_type = record.get("Type", "")
+            return f"Account: {name} | {industry} | {acct_type}".rstrip(" | ")
+
+        if obj_type == "Task":
+            subject = record.get("Subject", "Untitled task")
+            status = record.get("Status", "")
+            desc = (record.get("Description") or "")[:300]
+            return f"Task [{status}]: {subject}\n{desc}".strip()
+
+        if obj_type == "FeedItem":
+            title = record.get("Title") or ""
+            body = (record.get("Body") or "")[:500]
+            prefix = f"{title}: " if title else ""
+            return f"Chatter: {prefix}{body}"
+
+        if obj_type == "Note":
+            title = record.get("Title", "Untitled note")
+            body = (record.get("Body") or "")[:500]
+            return f"Note: {title}\n{body}".strip()
+
+        return f"Salesforce {obj_type}: {record.get('Id', '')}"
+
+    @staticmethod
+    def _extract_entities(
+        obj_type: str, record: dict[str, Any]
+    ) -> list[EntityRef]:
+        """Extract entity references from a Salesforce record."""
+        entities: list[EntityRef] = []
+
+        sf_id = record.get("Id", "")
+        if sf_id:
+            entities.append(
+                EntityRef(
+                    entity_type=obj_type.lower(),
+                    entity_id=sf_id,
+                    display_name=record.get("Name")
+                    or record.get("Subject")
+                    or record.get("CaseNumber")
+                    or sf_id,
+                )
+            )
+
+        account_id = record.get("AccountId")
+        if account_id:
+            entities.append(
+                EntityRef(
+                    entity_type="account",
+                    entity_id=account_id,
+                    display_name=account_id,
+                )
+            )
+
+        contact_id = record.get("ContactId")
+        if contact_id:
+            entities.append(
+                EntityRef(
+                    entity_type="contact",
+                    entity_id=contact_id,
+                    display_name=contact_id,
+                )
+            )
+
+        owner_id = record.get("OwnerId")
+        if owner_id:
+            entities.append(
+                EntityRef(
+                    entity_type="user",
+                    entity_id=owner_id,
+                    display_name=owner_id,
+                )
+            )
+
+        return entities
+
+    @staticmethod
+    def _derive_thread_id(
+        obj_type: str, record: dict[str, Any]
+    ) -> str | None:
+        """Derive a thread_id for grouping related records."""
+        sf_id = record.get("Id", "")
+        if not sf_id:
+            return None
+
+        if obj_type in ("Case", "Opportunity", "Account"):
+            return f"sf:{obj_type.lower()}:{sf_id}"
+
+        # Tasks and notes thread to their parent.
+        parent_id = record.get("WhatId") or record.get("ParentId")
+        if parent_id:
+            return f"sf:parent:{parent_id}"
+
+        return f"sf:{obj_type.lower()}:{sf_id}"