ergon-framework-python 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

ergon/connector/ergon_platform/channels/services/attachments.py

@@ -0,0 +1,283 @@
+import logging
+import re
+import unicodedata
+from concurrent.futures import Future, ThreadPoolExecutor
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from ....transaction import Transaction
+from ..adapters import ActivityAdapter
+from ..models import InboxAttachmentFile
+
+logger = logging.getLogger(__name__)
+
+
+class ChannelsAttachmentService:
+    """Hydrate or download inbound attachment files."""
+
+    _MAX_CONCURRENT_DOWNLOADS = 4
+
+    def __init__(
+        self,
+        client: Any,
+        download_client: Optional[Any] = None,
+    ) -> None:
+        self._client = download_client or client
+
+    def download_bytes(
+        self,
+        config_id: str,
+        event_id: str,
+        attachment_id: str,
+    ) -> bytes:
+        """Download the bytes of the attachment."""
+        return self._client.channels.configs.activity_attachment_file(
+            config_id,
+            event_id,
+            attachment_id,
+        )
+
+    def _download_attachment(
+        self,
+        config_id: str,
+        event_id: str,
+        attachment_id: str,
+        filename: str,
+    ) -> bytes:
+        logger.info(
+            "Downloading attachment %s (%s)",
+            filename,
+            attachment_id,
+        )
+        return self.download_bytes(config_id, event_id, attachment_id)
+
+    def hydrate_inbox_attachments(
+        self,
+        config_id: str,
+        transaction: Transaction,
+        failure_policy: Literal["raise", "best_effort"] = "raise",
+    ) -> Transaction:
+        """Hydrate the inbox attachments."""
+        return self.hydrate_inbox_transactions(
+            config_id,
+            [transaction],
+            failure_policy=failure_policy,
+        )[0]
+
+    def hydrate_inbox_transactions(
+        self,
+        config_id: str,
+        transactions: List[Transaction],
+        failure_policy: Literal["raise", "best_effort"] = "raise",
+    ) -> List[Transaction]:
+        """Hydrate a batch with bounded concurrent attachment downloads."""
+        hydrated = list(transactions)
+        enriched: Dict[int, List[Dict[str, Any]]] = {}
+        failures: Dict[int, List[Dict[str, str]]] = {}
+        jobs: List[tuple[int, int, str, str, str]] = []
+
+        for transaction_index, transaction in enumerate(transactions):
+            event_id = transaction.id
+            if not event_id:
+                continue
+            attachments = ActivityAdapter.attachments(transaction)
+            enriched[transaction_index] = list(attachments)
+            for attachment_index, metadata in enumerate(attachments):
+                if metadata.get("content") is not None:
+                    continue
+                attachment_id = ActivityAdapter.attachment_id(metadata)
+                if not attachment_id:
+                    continue
+                filename = str(metadata.get("filename") or attachment_id)
+                jobs.append(
+                    (
+                        transaction_index,
+                        attachment_index,
+                        event_id,
+                        attachment_id,
+                        filename,
+                    )
+                )
+
+        if not jobs:
+            return hydrated
+
+        max_workers = min(self._MAX_CONCURRENT_DOWNLOADS, len(jobs))
+        future_jobs: List[tuple[int, int, str, str, str, Future[bytes]]] = []
+        with ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix="channels-attachment",
+        ) as executor:
+            for job in jobs:
+                transaction_index, attachment_index, event_id, attachment_id, filename = job
+                future = executor.submit(
+                    self._download_attachment,
+                    config_id,
+                    event_id,
+                    attachment_id,
+                    filename,
+                )
+                future_jobs.append((*job, future))
+
+            changed: set[int] = set()
+            for (
+                transaction_index,
+                attachment_index,
+                event_id,
+                attachment_id,
+                filename,
+                future,
+            ) in future_jobs:
+                try:
+                    content = future.result()
+                except Exception as exc:
+                    if failure_policy == "raise":
+                        raise
+                    logger.warning(
+                        "Skipping attachment %s (%s) for event %s",
+                        filename,
+                        attachment_id,
+                        event_id,
+                        exc_info=True,
+                    )
+                    failures.setdefault(transaction_index, []).append(
+                        {
+                            "attachment_id": attachment_id,
+                            "filename": filename,
+                            "error": f"{type(exc).__name__}: {exc}",
+                        }
+                    )
+                    continue
+                original = enriched[transaction_index][attachment_index]
+                enriched[transaction_index][attachment_index] = {
+                    **original,
+                    "content": content,
+                }
+                changed.add(transaction_index)
+
+        for transaction_index in changed | failures.keys():
+            transaction = ActivityAdapter.with_attachments(
+                transactions[transaction_index],
+                enriched[transaction_index],
+            )
+            transaction_failures = failures.get(transaction_index)
+            if transaction_failures:
+                metadata = dict(transaction.metadata or {})
+                metadata["attachment_failures"] = transaction_failures
+                transaction = transaction.model_copy(update={"metadata": metadata})
+            hydrated[transaction_index] = transaction
+        return hydrated
+
+    @staticmethod
+    def _safe_component(value: str, *, fallback: str) -> str:
+        """Safe component."""
+        normalized = unicodedata.normalize("NFKC", value).replace("\\", "/").strip()
+        windows = PureWindowsPath(value)
+        if normalized.startswith("/") or value.startswith(("\\\\", "//")) or windows.drive:
+            raise ValueError(f"Unsafe absolute attachment filename: {value!r}")
+        name = PurePosixPath(normalized).name
+        if name in {"", ".", ".."}:
+            name = fallback
+        name = "".join("_" if unicodedata.category(char).startswith("C") else char for char in name)
+        name = re.sub(r"[/\\:*?\"<>|]", "_", name).strip(" .")
+        return name or fallback
+
+    @classmethod
+    def _output_filename(
+        cls,
+        filename: str,
+        attachment_id: str,
+    ) -> str:
+        """Output filename."""
+        safe_id = cls._safe_component(
+            attachment_id,
+            fallback="attachment",
+        )
+        safe_name = cls._safe_component(filename, fallback=safe_id)
+        path = PurePosixPath(safe_name)
+        return f"{path.stem}--{safe_id}{path.suffix}"
+
+    def download_inbox_attachments(
+        self,
+        config_id: str,
+        transaction: Transaction,
+        dest: Optional[Union[str, Path]] = None,
+    ) -> List[InboxAttachmentFile]:
+        """Download the inbox attachments."""
+        event_id = transaction.id
+        if not event_id:
+            raise ValueError("transaction.id is required to download attachments")
+
+        dest_root = Path(dest).resolve() if dest is not None else None
+        event_component = self._safe_component(
+            str(event_id),
+            fallback="event",
+        )
+        dest_dir = dest_root / event_component if dest_root is not None else None
+        jobs: List[tuple[str, str, Optional[str]]] = []
+        for metadata in ActivityAdapter.attachments(transaction):
+            attachment_id = ActivityAdapter.attachment_id(metadata)
+            if not attachment_id:
+                continue
+            filename = self._output_filename(
+                str(metadata.get("filename") or attachment_id),
+                attachment_id,
+            )
+            jobs.append(
+                (
+                    attachment_id,
+                    filename,
+                    metadata.get("content_type"),
+                )
+            )
+
+        if not jobs:
+            return []
+
+        max_workers = min(self._MAX_CONCURRENT_DOWNLOADS, len(jobs))
+        futures: List[tuple[str, str, Optional[str], Future[bytes]]] = []
+        with ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix="channels-attachment",
+        ) as executor:
+            for attachment_id, filename, content_type in jobs:
+                future = executor.submit(
+                    self._download_attachment,
+                    config_id,
+                    event_id,
+                    attachment_id,
+                    filename,
+                )
+                futures.append(
+                    (
+                        attachment_id,
+                        filename,
+                        content_type,
+                        future,
+                    )
+                )
+
+        downloaded: List[InboxAttachmentFile] = []
+        for attachment_id, filename, content_type, future in futures:
+            content = future.result()
+            path: Optional[str] = None
+            if dest_dir is not None:
+                dest_dir.mkdir(parents=True, exist_ok=True)
+                resolved_dir = dest_dir.resolve()
+                file_path = (resolved_dir / filename).resolve()
+                try:
+                    file_path.relative_to(resolved_dir)
+                except ValueError as exc:
+                    raise ValueError("Attachment destination escapes the event directory") from exc
+                file_path.write_bytes(content)
+                path = str(file_path)
+            downloaded.append(
+                InboxAttachmentFile(
+                    attachment_id=attachment_id,
+                    filename=filename,
+                    content=content,
+                    content_type=content_type,
+                    path=path,
+                )
+            )
+        return downloaded

ergon/connector/ergon_platform/channels/services/messages.py

@@ -0,0 +1,127 @@
+import html as html_module
+from typing import Any, Dict, List, Optional, Union
+
+from ....transaction import Transaction
+from ..adapters import ActivityAdapter
+from ..models import SendMessageInput
+from .records import SdkRecord
+
+
+class ChannelsMessageService:
+    """Thread reads and outbound message operations."""
+
+    def __init__(self, client: Any) -> None:
+        self.client = client
+
+    def fetch_thread_messages(
+        self,
+        thread_id: str,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        **params: Any,
+    ) -> List[Transaction]:
+        """Fetch the thread messages."""
+        response = self.client.channels.thread_messages(thread_id, **params)
+        messages = SdkRecord.items(
+            response,
+            keys=["messages", "items", "data"],
+        )
+        if limit is not None:
+            messages = messages[offset : offset + limit]
+        elif offset:
+            messages = messages[offset:]
+        return [ActivityAdapter.to_transaction(message, source="thread") for message in messages]
+
+    def send_message(
+        self,
+        address_id: str,
+        channel: str,
+        config: Dict[str, Any],
+        resource_id: Optional[str] = None,
+        service_name: Optional[str] = None,
+    ) -> Any:
+        """Send the message."""
+        if not address_id:
+            raise ValueError("address_id is required to send a channel message")
+        if not channel:
+            raise ValueError("channel is required to send a channel message")
+        request: Dict[str, Any] = {
+            "address_id": address_id,
+            "channel": channel,
+            "config": config,
+        }
+        if resource_id is not None:
+            request["resource_id"] = resource_id
+        if service_name is not None:
+            request["service_name"] = service_name
+        return self.client.channels.send(request)
+
+    @staticmethod
+    def normalize_recipients(to: Union[str, List[str]]) -> List[str]:
+        """Normalize the recipients."""
+        if isinstance(to, str):
+            return [to]
+        return list(to)
+
+    @staticmethod
+    def _drop_none(mapping: Dict[str, Any]) -> Dict[str, Any]:
+        """Drop the none values."""
+        return {key: value for key, value in mapping.items() if value is not None}
+
+    @classmethod
+    def normalize_send_payload(
+        cls,
+        payload: object,
+    ) -> Dict[str, Any]:
+        if isinstance(payload, SendMessageInput):
+            config: Dict[str, Any] = cls._drop_none(
+                {
+                    "to": list(payload.to) if payload.to else None,
+                    "subject": payload.subject,
+                    "html": payload.html,
+                    "text": payload.text,
+                    "cc": list(payload.cc) if payload.cc else None,
+                    "bcc": list(payload.bcc) if payload.bcc else None,
+                    "reply_to": payload.reply_to,
+                    "in_reply_to": payload.in_reply_to,
+                    "attachments": (
+                        [attachment.model_dump(mode="json") for attachment in payload.attachments]
+                        if payload.attachments
+                        else None
+                    ),
+                }
+            )
+            if config.get("text") and not config.get("html"):
+                config["html"] = f"<p>{html_module.escape(config['text'])}</p>"
+            return {"top": {}, "config": config}
+
+        if isinstance(payload, dict):
+            data = dict(payload)
+            config = dict(data.pop("config", {}) or {})
+            top = {
+                "address_id": data.pop("address_id", None),
+                "channel": data.pop("channel", None),
+                "resource_id": data.pop("resource_id", None),
+                "service_name": data.pop("service_name", None),
+            }
+            for key, value in data.items():
+                config.setdefault(key, value)
+            return {"top": top, "config": cls._drop_none(config)}
+
+        raise TypeError(f"Unsupported send payload type: {type(payload)}")
+
+    @staticmethod
+    def send_response_id(result: Any) -> str:
+        """Send the response id."""
+        record = SdkRecord(result)
+        for key in (
+            "log_id",
+            "provider_message_id",
+            "thread_id",
+            "provider_id",
+            "id",
+        ):
+            value = record.get(key)
+            if value:
+                return str(value)
+        return ""

ergon/connector/ergon_platform/channels/services/records.py

@@ -0,0 +1,75 @@
+from typing import Any, List, Optional
+
+
+class SdkRecord:
+    """Uniform read API over dict-or-object SDK payloads."""
+
+    def __init__(self, raw: Any) -> None:
+        self.raw = raw
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from the record."""
+        if isinstance(self.raw, dict):
+            return self.raw.get(key, default)
+        return getattr(self.raw, key, default)
+
+    @classmethod
+    def items(
+        cls,
+        response: Any,
+        keys: Optional[List[str]] = None,
+    ) -> List[Any]:
+        """Get items from a response."""
+        candidate_keys = keys or ["items", "messages", "data", "results"]
+        if isinstance(response, list):
+            return response
+        if isinstance(response, dict):
+            for key in candidate_keys:
+                value = response.get(key)
+                if isinstance(value, list):
+                    return value
+            return []
+        for key in candidate_keys:
+            value = getattr(response, key, None)
+            if isinstance(value, (list, tuple)):
+                return list(value)
+        return []
+
+    @classmethod
+    def total(cls, response: Any) -> int:
+        """Get the total from a response."""
+        record = cls(response)
+        for key in ("total", "total_count", "count"):
+            value = record.get(key)
+            if value is not None:
+                return int(value)
+        return 0
+
+    @classmethod
+    def serialize(cls, obj: Any) -> Any:
+        """Serialize an object to a dictionary."""
+        if obj is None or isinstance(
+            obj,
+            (str, int, float, bool, bytes),
+        ):
+            return obj
+        if isinstance(obj, dict):
+            return {key: cls.serialize(value) for key, value in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [cls.serialize(item) for item in obj]
+        if hasattr(obj, "model_dump"):
+            return obj.model_dump(mode="json")
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+        if hasattr(obj, "__dict__"):
+            return {key: cls.serialize(value) for key, value in obj.__dict__.items() if not key.startswith("_")}
+        return obj
+
+    @classmethod
+    def first_id(cls, mapping: dict, *keys: str) -> str:
+        """Get the first id from a mapping."""
+        for key in keys:
+            value = mapping.get(key)
+            if value:
+                return str(value)
+        return ""

ergon/connector/ergon_platform/channels/services/service.py

@@ -0,0 +1,34 @@
+from typing import Any, Optional
+
+from ...models import ErgonPlatformClient
+from .activity import ChannelsActivityService
+from .addresses import ChannelsAddressService
+from .attachments import ChannelsAttachmentService
+from .messages import ChannelsMessageService
+
+
+class ErgonPlatformChannelsService:
+    """Domain-organized services over one shared Channels SDK client."""
+
+    def __init__(
+        self,
+        config: ErgonPlatformClient,
+        client: Any,
+        download_client: Optional[Any] = None,
+    ) -> None:
+        self.config = config
+        self.client = client
+        self._download_client = download_client
+        self.activity = ChannelsActivityService(client)
+        self.addresses = ChannelsAddressService(client)
+        self.attachments = ChannelsAttachmentService(
+            client,
+            download_client=download_client,
+        )
+        self.messages = ChannelsMessageService(client)
+
+    def close(self) -> None:
+        """Close the services."""
+        download = self._download_client
+        if download is not None and download is not self.client and hasattr(download, "close"):
+            download.close()