ergon-framework-python 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

ergon/__init__.py

@@ -10,4 +10,4 @@ __all__ = [
     "manager",
 ]
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"

ergon/connector/__init__.py

@@ -7,13 +7,23 @@ from .transaction import Transaction
 
 if TYPE_CHECKING:
     from .ergon_platform import (
+        AsyncErgonPlatformChannelsConnector,
         AsyncErgonPlatformConnector,
         CreateItemInput,
+        ErgonPlatformChannelsConfig,
+        ErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConsumerConfig,
+        ErgonPlatformChannelsProducerConfig,
         ErgonPlatformClient,
         ErgonPlatformConnector,
         ErgonPlatformConsumerConfig,
         ErgonPlatformProducerConfig,
     )
+
+    # NOTE: ``SendMessageInput`` is defined by both Nylas and Channels with
+    # different shapes. The top-level alias here points to the Nylas type
+    # (matches the pre-split lazy-export map); channels users must import it
+    # from ``ergon.connector.ergon_platform.channels``.
     from .excel import ExcelConnector, ExcelFetchConfig, ExcelRow, ExcelService
     from .nylas import (
         AckActionConfig,
@@ -76,6 +86,7 @@ _CONNECTOR_SUBPACKAGES = (
 
 _LAZY_EXPORTS = {
     "AckActionConfig": "nylas",
+    "AsyncErgonPlatformChannelsConnector": "ergon_platform",
     "AsyncErgonPlatformConnector": "ergon_platform",
     "AsyncNylasAuthService": "nylas",
     "AsyncNylasConnector": "nylas",
@@ -94,6 +105,10 @@ _LAZY_EXPORTS = {
     "AuthUrlConfig": "nylas",
     "CodeExchangeInput": "nylas",
     "CreateItemInput": "ergon_platform",
+    "ErgonPlatformChannelsConfig": "ergon_platform",
+    "ErgonPlatformChannelsConnector": "ergon_platform",
+    "ErgonPlatformChannelsConsumerConfig": "ergon_platform",
+    "ErgonPlatformChannelsProducerConfig": "ergon_platform",
     "ErgonPlatformClient": "ergon_platform",
     "ErgonPlatformConnector": "ergon_platform",
     "ErgonPlatformConsumerConfig": "ergon_platform",
@@ -148,6 +163,7 @@ def __dir__() -> list[str]:
 __all__ = [
     "AckActionConfig",
     "AsyncConnector",
+    "AsyncErgonPlatformChannelsConnector",
     "AsyncErgonPlatformConnector",
     "AsyncNylasAuthService",
     "AsyncNylasConnector",
@@ -169,6 +185,10 @@ __all__ = [
     "Connector",
     "ConnectorConfig",
     "CreateItemInput",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
     "ErgonPlatformClient",
     "ErgonPlatformConnector",
     "ErgonPlatformConsumerConfig",

ergon/connector/ergon_platform/__init__.py

@@ -1,24 +1,81 @@
+"""Ergon Platform connectors — Workflows and Channels.
+
+The Ergon Platform SDK exposes several services (workflows, channels, agents,
+buckets, ...). This package groups every framework connector against that
+platform. Each service lives in its own sub-package (``workflows``,
+``channels``, ...) and reuses the shared credentials model
+(:class:`ErgonPlatformClient`) so a single API key drives every connector.
+
+Public workflow names are re-exported here for backward compatibility with the
+pre-split layout::
+
+    from ergon.connector.ergon_platform import ErgonPlatformConnector  # workflows
+
+New code is encouraged to import directly from the sub-package::
+
+    from ergon.connector.ergon_platform.workflows import ErgonPlatformConnector
+    from ergon.connector.ergon_platform.channels import ErgonPlatformChannelsConnector
+"""
+
+from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
 from .._lazy import exported_names, load_optional_export
-from .models import (
-    CreateItemInput,
-    ErgonPlatformClient,
-    ErgonPlatformConsumerConfig,
-    ErgonPlatformProducerConfig,
-)
+from .models import ErgonPlatformClient
 
 if TYPE_CHECKING:
-    from .async_connector import AsyncErgonPlatformConnector
-    from .connector import ErgonPlatformConnector
+    from .channels import (
+        AsyncErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConfig,
+        ErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConsumerConfig,
+        ErgonPlatformChannelsProducerConfig,
+        ErgonPlatformChannelsService,
+        SendMessageInput,
+        SendMessagePayload,
+    )
+    from .workflows import (
+        AsyncErgonPlatformConnector,
+        CreateItemInput,
+        CreateItemPayload,
+        ErgonPlatformConnector,
+        ErgonPlatformConsumerConfig,
+        ErgonPlatformProducerConfig,
+        ErgonPlatformWorkflowsService,
+    )
+
+_SUBPACKAGES = ("channels", "workflows")
 
+# Backward-compat aliases: names that used to live under
+# ``ergon.connector.ergon_platform`` before the workflows/ split, plus the new
+# channels API surface. Every entry is loaded lazily from its sub-package to
+# keep the platform SDK out of the core import path.
 _LAZY_EXPORTS = {
-    "AsyncErgonPlatformConnector": "async_connector",
-    "ErgonPlatformConnector": "connector",
+    # Workflows (pre-split names — kept for backward compatibility)
+    "AsyncErgonPlatformConnector": "workflows",
+    "CreateItemInput": "workflows",
+    "CreateItemPayload": "workflows",
+    "ErgonPlatformConnector": "workflows",
+    "ErgonPlatformConsumerConfig": "workflows",
+    "ErgonPlatformProducerConfig": "workflows",
+    "ErgonPlatformWorkflowsService": "workflows",
+    # Channels
+    "AsyncErgonPlatformChannelsConnector": "channels",
+    "ErgonPlatformChannelsConfig": "channels",
+    "ErgonPlatformChannelsConnector": "channels",
+    "ErgonPlatformChannelsConsumerConfig": "channels",
+    "ErgonPlatformChannelsProducerConfig": "channels",
+    "ErgonPlatformChannelsService": "channels",
+    "SendMessageInput": "channels",
+    "SendMessagePayload": "channels",
 }
 
 
 def __getattr__(name: str) -> Any:
+    if name in _SUBPACKAGES:
+        module = import_module(f".{name}", __name__)
+        globals()[name] = module
+        return module
     return load_optional_export(
         name=name,
         package=__name__,
@@ -30,14 +87,24 @@ def __getattr__(name: str) -> Any:
 
 
 def __dir__() -> list[str]:
-    return exported_names(globals(), _LAZY_EXPORTS)
+    return sorted(set(exported_names(globals(), _LAZY_EXPORTS)) | set(_SUBPACKAGES))
 
 
 __all__ = [
+    "AsyncErgonPlatformChannelsConnector",
     "AsyncErgonPlatformConnector",
     "CreateItemInput",
+    "CreateItemPayload",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
+    "ErgonPlatformChannelsService",
     "ErgonPlatformClient",
     "ErgonPlatformConnector",
     "ErgonPlatformConsumerConfig",
     "ErgonPlatformProducerConfig",
+    "ErgonPlatformWorkflowsService",
+    "SendMessageInput",
+    "SendMessagePayload",
 ]

ergon/connector/ergon_platform/async_connector.py

@@ -1,223 +1,5 @@
-import asyncio
-import logging
-from typing import Any, Dict, List, Optional
+"""Deprecated compatibility import for the async Workflows connector."""
 
-from ..connector import AsyncConnector
-from ..transaction import Transaction
-from ._client import create_ergon_client
-from ._operations import _ErgonPlatformOperations
-from .models import (
-    CreateItemPayload,
-    ErgonPlatformClient,
-    ErgonPlatformConsumerConfig,
-    ErgonPlatformProducerConfig,
-)
-from .utils import get_value, normalize_create_payload
+from .workflows.async_connector import AsyncErgonPlatformConnector
 
-logger = logging.getLogger(__name__)
-
-
-class AsyncErgonPlatformConnector(AsyncConnector):
-    def __init__(
-        self,
-        client: ErgonPlatformClient,
-        consumer_config: Optional[ErgonPlatformConsumerConfig] = None,
-        producer_config: Optional[ErgonPlatformProducerConfig] = None,
-    ) -> None:
-        self.client = create_ergon_client(client)
-        self._operations = _ErgonPlatformOperations(client, self.client)
-        self._consumer_config = consumer_config
-        self._producer_config = producer_config or ErgonPlatformProducerConfig()
-
-    async def fetch_transactions_async(
-        self,
-        batch_size: Optional[int] = None,
-        *args,
-        **kwargs,
-    ) -> List[Transaction]:
-        if self._consumer_config is None:
-            raise ValueError("AsyncErgonPlatformConnector requires a consumer_config to fetch transactions")
-
-        config = self._consumer_config
-        limit = batch_size or config.batch_size
-        params: Dict[str, Any] = {**config.list_params, **kwargs}
-        if config.unassigned:
-            params.pop("assigned_to", None)
-            params["assigned"] = "no"
-
-        transactions = await asyncio.to_thread(
-            lambda: self._operations.fetch_items(
-                config.workflow_id,
-                config.phase_id,
-                limit=limit,
-                offset=config.offset,
-                **params,
-            )
-        )
-        if not config.unassigned:
-            return transactions
-
-        claimed_transactions: List[Transaction] = []
-        for transaction in transactions:
-            try:
-                await asyncio.to_thread(lambda: self.client.workflows.items.claim(transaction.id, {}))
-                claimed_transactions.append(await self.fetch_transaction_by_id_async(transaction.id))
-            except Exception:
-                logger.warning(
-                    "Failed to claim item %s during unassigned fetch; skipping it",
-                    transaction.id,
-                    exc_info=True,
-                )
-        return claimed_transactions
-
-    async def dispatch_transactions_async(
-        self,
-        transactions: List[Transaction],
-        *args,
-        **kwargs,
-    ) -> List[str]:
-        created_ids: List[str] = []
-        for transaction in transactions:
-            result = await self._create_from_payload(transaction.payload)
-            created_ids.append(self._created_item_id(result))
-        return created_ids
-
-    async def fetch_child_transactions_async(
-        self,
-        parent_item_id: str,
-        *args,
-        **kwargs,
-    ) -> List[Transaction]:
-        return await asyncio.to_thread(lambda: self._operations.fetch_child_items(parent_item_id, **kwargs))
-
-    async def fetch_transaction_by_id_async(self, transaction_id: str, *args, **kwargs) -> Transaction:
-        workflow_id = self._consumer_config.workflow_id if self._consumer_config else ""
-        return await asyncio.to_thread(
-            lambda: self._operations.get_item_transaction(transaction_id, workflow_id, **kwargs)
-        )
-
-    async def fetch_items_by_query(
-        self, workflow_id: str, query: Optional[Dict[str, Any]] = None, **fields: Any
-    ) -> List[Transaction]:
-        return await asyncio.to_thread(lambda: self._operations.fetch_items_by_query(workflow_id, query, **fields))
-
-    async def get_transactions_count_async(self, *args, **kwargs) -> int:
-        if self._consumer_config is None:
-            raise ValueError("AsyncErgonPlatformConnector requires a consumer_config to count transactions")
-
-        config = self._consumer_config
-        params: Dict[str, Any] = {**config.list_params, **kwargs}
-        return await asyncio.to_thread(
-            lambda: self._operations.get_phase_items_count(
-                config.workflow_id,
-                config.phase_id,
-                **params,
-            )
-        )
-
-    async def ack_transaction(self, transaction: Transaction, phase_id: Optional[str] = None) -> None:
-        target_phase = phase_id
-        if target_phase is None and self._consumer_config is not None:
-            target_phase = self._consumer_config.ack_phase_id
-        if not target_phase:
-            return
-        await asyncio.to_thread(lambda: self.client.workflows.items.route(transaction.id, to_phase_id=target_phase))
-
-    async def release_item(
-        self,
-        item_id: str,
-        data: Optional[Dict[str, Any]] = None,
-        *,
-        delay_seconds: Optional[int] = None,
-        **fields: Any,
-    ) -> Any:
-        return await asyncio.to_thread(
-            lambda: self._operations.release_item(
-                item_id,
-                data,
-                delay_seconds=delay_seconds,
-                **fields,
-            )
-        )
-
-    async def nack_transaction(self, transaction: Transaction, requeue: bool = True, delay_seconds: int = 10) -> None:
-        if requeue:
-            await asyncio.to_thread(lambda: self._operations.release_item(transaction.id, delay_seconds=delay_seconds))
-            return
-
-        target_phase = self._consumer_config.nack_phase_id if self._consumer_config is not None else None
-        if not target_phase:
-            raise ValueError("nack_phase_id is required when nack_transaction is called with requeue=False")
-
-        await asyncio.to_thread(lambda: self.client.workflows.items.route(transaction.id, to_phase_id=target_phase))
-
-    async def close(self) -> None:
-        await asyncio.to_thread(self.client.close)
-
-    async def list_phase_fields(
-        self,
-        phase_id: str,
-        *,
-        workflow_id: Optional[str] = None,
-        include_workflow_fields: bool = True,
-        **params: Any,
-    ) -> Any:
-        return await asyncio.to_thread(
-            lambda: self._operations.list_phase_fields(
-                phase_id,
-                workflow_id=workflow_id,
-                include_workflow_fields=include_workflow_fields,
-                **params,
-            )
-        )
-
-    async def get_pipeline_result(
-        self,
-        workflow_id: str,
-        item_id: str,
-        field_id: str,
-        buckets_file_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return await asyncio.to_thread(
-            self._operations.get_pipeline_result,
-            workflow_id,
-            item_id,
-            field_id,
-            buckets_file_id,
-        )
-
-    async def _create_from_payload(self, payload: CreateItemPayload) -> Any:
-        data = normalize_create_payload(payload)
-        producer = self._producer_config
-
-        workflow_id = data.get("workflow_id") or producer.workflow_id
-        phase_id = data.get("phase_id") or producer.phase_id
-        if not workflow_id:
-            raise ValueError("workflow_id is required to create an item (set it in payload or producer_config)")
-        if not phase_id:
-            raise ValueError("phase_id is required to create an item (set it in payload or producer_config)")
-
-        attachment = data.get("attachment")
-        attachment_field_id = data.get("attachment_field_id") or producer.attachment_field_id
-        content_type = data.get("content_type") or producer.default_content_type
-        parent_item_id = data.get("parent_item_id") or producer.parent_item_id
-
-        return await asyncio.to_thread(
-            lambda: self._operations.create_item(
-                workflow_id,
-                phase_id,
-                data["title"],
-                parent_item_id=parent_item_id,
-                field_values=data.get("field_values"),
-                attachment=attachment,
-                attachment_field_id=attachment_field_id,
-                content_type=content_type,
-                **data.get("fields", {}),
-            )
-        )
-
-    @staticmethod
-    def _created_item_id(result: Any) -> str:
-        if isinstance(result, dict) and "item" in result:
-            return str(get_value(result["item"], "id", ""))
-        return str(get_value(result, "id", ""))
+__all__ = ["AsyncErgonPlatformConnector"]

ergon/connector/ergon_platform/channels/__init__.py

@@ -0,0 +1,54 @@
+from typing import TYPE_CHECKING, Any
+
+from ..._lazy import exported_names, load_optional_export
+from .models import (
+    ChannelsActivityFilter,
+    ErgonPlatformChannelsConfig,
+    ErgonPlatformChannelsConsumerConfig,
+    ErgonPlatformChannelsProducerConfig,
+    InboxAttachmentFile,
+    SendMessageAttachment,
+    SendMessageInput,
+    SendMessagePayload,
+)
+
+if TYPE_CHECKING:
+    from .async_connector import AsyncErgonPlatformChannelsConnector
+    from .connector import ErgonPlatformChannelsConnector
+    from .services import ErgonPlatformChannelsService
+
+_LAZY_EXPORTS = {
+    "AsyncErgonPlatformChannelsConnector": "async_connector",
+    "ErgonPlatformChannelsConnector": "connector",
+    "ErgonPlatformChannelsService": "services",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return load_optional_export(
+        name=name,
+        package=__name__,
+        exports=_LAZY_EXPORTS,
+        namespace=globals(),
+        extra="ergon-platform",
+        dependencies=("ergon_platform", "httpx"),
+    )
+
+
+def __dir__() -> list[str]:
+    return exported_names(globals(), _LAZY_EXPORTS)
+
+
+__all__ = [
+    "AsyncErgonPlatformChannelsConnector",
+    "ChannelsActivityFilter",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
+    "ErgonPlatformChannelsService",
+    "InboxAttachmentFile",
+    "SendMessageAttachment",
+    "SendMessageInput",
+    "SendMessagePayload",
+]

ergon/connector/ergon_platform/channels/adapters.py

@@ -0,0 +1,230 @@
+from typing import Any, Dict, List, Optional
+
+from ...transaction import Transaction
+from .models import ErgonPlatformChannelsConsumerConfig
+from .services.records import SdkRecord
+
+
+class ActivityAdapter:
+    """Map Channels activity events into the connector Transaction shape."""
+
+    _META_KEYS = (
+        "event_type",
+        "channel",
+        "direction",
+        "status",
+        "thread_id",
+        "correlation_id",
+        "provider_message_id",
+        "subject",
+        "from_address",
+        "to_addresses",
+        "address_id",
+        "consumption_status",
+        "acked_at",
+        "available_at",
+        "consumer_id",
+        "attempt_count",
+    )
+    _DELIVERY_KEYS = (
+        "subscription_id",
+        "lease_token",
+        "lease_expires_at",
+        "consumer_id",
+        "attempt_count",
+    )
+
+    @classmethod
+    def to_transaction(cls, event: Any, *, source: str) -> Transaction:
+        """To transaction."""
+        payload = SdkRecord.serialize(event)
+        payload = payload if isinstance(payload, dict) else {"value": payload}
+        metadata: Dict[str, Any] = {"source": source}
+        for key in cls._META_KEYS:
+            value = payload.get(key)
+            if value is not None:
+                metadata[key] = value
+        nested = payload.get("payload")
+        if isinstance(nested, dict):
+            metadata["message_payload"] = nested
+            attachments = cls.public_attachments(nested.get("attachments"))
+            if attachments:
+                metadata["attachments"] = attachments
+                metadata["has_attachment"] = True
+        return Transaction(
+            id=SdkRecord.first_id(
+                payload,
+                "id",
+                "log_id",
+                "message_id",
+                "provider_message_id",
+            ),
+            payload=payload,
+            metadata=metadata,
+        )
+
+    @classmethod
+    def claimed_transaction(cls, item: Any) -> Transaction:
+        """Claimed transaction."""
+        claimed = SdkRecord.serialize(item)
+        claimed = claimed if isinstance(claimed, dict) else {}
+        transaction = cls.to_transaction(
+            claimed.get("event"),
+            source="config_activity_claim",
+        )
+        metadata = dict(transaction.metadata or {})
+        delivery = claimed.get("delivery")
+        if isinstance(delivery, dict):
+            metadata["delivery"] = {key: delivery[key] for key in cls._DELIVERY_KEYS if delivery.get(key) is not None}
+        return transaction.model_copy(update={"metadata": metadata})
+
+    @staticmethod
+    def delivery(transaction: Transaction) -> Dict[str, Any]:
+        """Delivery."""
+        metadata = transaction.metadata or {}
+        delivery = metadata.get("delivery")
+        if not isinstance(delivery, dict):
+            raise ValueError("Transaction was not claimed and cannot be acknowledged or nacked")
+        if not delivery.get("subscription_id") or not delivery.get("lease_token"):
+            raise ValueError("Transaction claim is missing subscription_id or lease_token")
+        return delivery
+
+    @staticmethod
+    def belongs_to_address(
+        transaction: Transaction,
+        address_id: str,
+    ) -> bool:
+        """Belongs to address."""
+        metadata = transaction.metadata or {}
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            candidate = nested.get("address_id") or nested.get("channel_address_id")
+            if candidate is not None:
+                return str(candidate) == address_id
+        event = transaction.payload if isinstance(transaction.payload, dict) else {}
+        candidate = event.get("address_id") or event.get("channel_address_id")
+        if candidate is not None:
+            return str(candidate) == address_id
+        return True
+
+    @staticmethod
+    def attachment_id(attachment: Any) -> Optional[str]:
+        """Attachment id."""
+        if not isinstance(attachment, dict):
+            return None
+        for key in ("id", "resend_attachment_id", "attachment_id"):
+            value = attachment.get(key)
+            if value:
+                return str(value)
+        return None
+
+    @classmethod
+    def public_attachment(
+        cls,
+        item: Any,
+    ) -> Optional[Dict[str, Any]]:
+        """Public attachment."""
+        if not isinstance(item, dict):
+            return None
+        filename = str(item.get("filename") or item.get("name") or "").strip()
+        if not filename:
+            return None
+        attachment: Dict[str, Any] = {"filename": filename}
+        attachment_id = cls.attachment_id(item)
+        if attachment_id:
+            attachment["id"] = attachment_id
+        content_type = item.get("content_type")
+        if content_type:
+            attachment["content_type"] = content_type
+        size = item.get("size")
+        if size is not None:
+            attachment["size"] = size
+        content = item.get("content")
+        if isinstance(content, bytes):
+            attachment["content"] = content
+        return attachment
+
+    @classmethod
+    def public_attachments(cls, items: Any) -> List[Dict[str, Any]]:
+        """Public attachments."""
+        if not isinstance(items, list):
+            return []
+        attachments: List[Dict[str, Any]] = []
+        for item in items:
+            attachment = cls.public_attachment(item)
+            if attachment is not None:
+                attachments.append(attachment)
+        return attachments
+
+    @classmethod
+    def attachments(
+        cls,
+        transaction: Transaction,
+    ) -> List[Dict[str, Any]]:
+        """Attachments."""
+        metadata = transaction.metadata or {}
+        items = metadata.get("attachments")
+        if isinstance(items, list):
+            return [item for item in items if isinstance(item, dict)]
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            return cls.public_attachments(nested.get("attachments"))
+        payload = transaction.payload
+        if isinstance(payload, dict):
+            nested = payload.get("payload")
+            if isinstance(nested, dict):
+                return cls.public_attachments(nested.get("attachments"))
+        return []
+
+    @staticmethod
+    def with_attachments(
+        transaction: Transaction,
+        attachments: List[Dict[str, Any]],
+    ) -> Transaction:
+        """With the attachments."""
+        metadata = dict(transaction.metadata or {})
+        metadata["attachments"] = attachments
+        metadata["has_attachment"] = bool(attachments)
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            metadata["message_payload"] = {
+                **nested,
+                "attachments": attachments,
+            }
+        payload = transaction.payload
+        if isinstance(payload, dict):
+            payload = dict(payload)
+            inner = payload.get("payload")
+            if isinstance(inner, dict):
+                payload["payload"] = {
+                    **inner,
+                    "attachments": attachments,
+                }
+        return transaction.model_copy(update={"payload": payload, "metadata": metadata})
+
+    @staticmethod
+    def unseen(
+        transactions: List[Transaction],
+        seen_ids: set[str],
+    ) -> List[Transaction]:
+        fresh: List[Transaction] = []
+        """Unseen transactions."""
+        for transaction in transactions:
+            if not transaction.id or transaction.id in seen_ids:
+                continue
+            seen_ids.add(transaction.id)
+            fresh.append(transaction)
+        return fresh
+
+    @classmethod
+    def finalize_fetch(
+        cls,
+        transactions: List[Transaction],
+        config: ErgonPlatformChannelsConsumerConfig,
+        seen_ids: Optional[set[str]] = None,
+    ) -> List[Transaction]:
+        """Finalize the fetched transactions."""
+        transactions = config.effective_activity_filter().select(transactions)
+        if seen_ids is not None:
+            transactions = cls.unseen(transactions, seen_ids)
+        return transactions