hyperagents 1.2.3rc5.post3__py3-none-any.whl

integrations/messaging/telegram.py

@@ -0,0 +1,260 @@
+"""TelegramConnector — Telegram Bot API integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import AsyncIterator
+
+import httpx
+
+from integrations.base import (
+    BaseConnector,
+    ConnectorCapability,
+    ConnectorInfo,
+    InboundMessage,
+    OutboundMessage,
+)
+
+logger = logging.getLogger("hyperclaw.integrations.telegram")
+
+
+from hyperclaw.tools.egress import telegram_payload  # noqa: E402  (link previews off)
+
+
+class TelegramConnector(BaseConnector):
+    """
+    Telegram Bot API connector.
+
+    Required config:
+        - bot_token: Telegram Bot API token
+    """
+
+    BASE_URL = "https://api.telegram.org"
+
+    def __init__(self, config: dict) -> None:
+        self.config = config
+        self.bot_token = config.get("bot_token", "")
+
+        if config.get("enabled", False) and not self.bot_token:
+            raise ValueError("TelegramConnector requires bot_token")
+
+        self._last_update_id = 0
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            connector_id="telegram",
+            platform="telegram",
+            category="messaging",
+            capabilities=frozenset(
+                [
+                    ConnectorCapability.SEND_MESSAGE,
+                    ConnectorCapability.RECEIVE_MESSAGE,
+                    ConnectorCapability.FILE_UPLOAD,
+                    ConnectorCapability.FILE_DOWNLOAD,
+                    ConnectorCapability.WEBHOOKS,
+                    ConnectorCapability.NOTIFY,
+                    ConnectorCapability.ACTION,
+                ]
+            ),
+            auth_type="api_key",
+            rate_limit_per_minute=30,
+            supports_threads=True,
+            supports_attachments=True,
+            supports_reactions=True,
+        )
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=30.0)
+        return self._client
+
+    def _api_url(self, method: str) -> str:
+        return f"{self.BASE_URL}/bot{self.bot_token}/{method}"
+
+    async def health(self) -> bool:
+        """Check if bot token is valid."""
+        try:
+            client = await self._get_client()
+            response = await client.get(self._api_url("getMe"))
+            data = response.json()
+            return data.get("ok", False)
+        except Exception as e:
+            logger.error(f"Telegram health check failed: {e}")
+            return False
+
+    async def _send_impl(self, message: OutboundMessage) -> str:
+        """Send a message via Telegram."""
+        client = await self._get_client()
+
+        payload = {
+            "chat_id": message.recipient_id,
+            "text": message.content,
+        }
+
+        if message.thread_id:
+            payload["reply_to_message_id"] = message.thread_id
+
+        if message.format == "markdown":
+            payload["parse_mode"] = "MarkdownV2"
+        elif message.format == "html":
+            payload["parse_mode"] = "HTML"
+
+        response = await client.post(self._api_url("sendMessage"), json=telegram_payload(payload))
+        data = response.json()
+
+        if not data.get("ok"):
+            raise Exception(f"Telegram send failed: {data.get('description')}")
+
+        return str(data["result"]["message_id"])
+
+    async def _receive_impl(self) -> AsyncIterator[InboundMessage]:
+        """Poll for updates using long polling."""
+        client = await self._get_client()
+
+        params = {
+            "offset": self._last_update_id + 1,
+            "timeout": 30,
+            "allowed_updates": ["message"],
+        }
+
+        response = await client.get(self._api_url("getUpdates"), params=params)
+        data = response.json()
+
+        if not data.get("ok"):
+            return
+
+        for update in data.get("result", []):
+            self._last_update_id = update["update_id"]
+
+            msg = update.get("message", {})
+            if not msg:
+                continue
+
+            sender = msg.get("from", {})
+            attachments = []
+
+            # Handle attachments
+            for attach_type in ["photo", "document", "video", "audio", "voice"]:
+                if attach_type in msg:
+                    attach_data = msg[attach_type]
+                    if isinstance(attach_data, list):
+                        attach_data = attach_data[-1]  # Get largest photo
+                    attachments.append({"type": attach_type, "data": attach_data})
+
+            yield InboundMessage(
+                message_id=str(msg.get("message_id", "")),
+                platform="telegram",
+                sender_id=str(sender.get("id", "")),
+                sender_name=sender.get("first_name", "")
+                + " "
+                + sender.get("last_name", ""),
+                content=msg.get("text", "") or msg.get("caption", ""),
+                thread_id=str(msg.get("reply_to_message", {}).get("message_id", ""))
+                or None,
+                channel_id=str(msg.get("chat", {}).get("id", "")),
+                attachments=attachments,
+                raw=msg,
+            )
+
+    async def send_photo(
+        self,
+        chat_id: str,
+        photo_url: str,
+        caption: str = "",
+    ) -> str:
+        """Send a photo to a chat."""
+        client = await self._get_client()
+
+        payload = {
+            "chat_id": chat_id,
+            "photo": photo_url,
+        }
+        if caption:
+            payload["caption"] = caption
+
+        response = await client.post(self._api_url("sendPhoto"), json=payload)
+        data = response.json()
+
+        if not data.get("ok"):
+            raise Exception(f"Telegram sendPhoto failed: {data.get('description')}")
+
+        return str(data["result"]["message_id"])
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: str = "",
+    ) -> str:
+        """Send a document to a chat."""
+        client = await self._get_client()
+
+        with open(file_path, "rb") as f:
+            files = {"document": f}
+            data = {"chat_id": chat_id}
+            if caption:
+                data["caption"] = caption
+
+            response = await client.post(
+                self._api_url("sendDocument"),
+                data=data,
+                files=files,
+            )
+
+        result = response.json()
+
+        if not result.get("ok"):
+            raise Exception(f"Telegram sendDocument failed: {result.get('description')}")
+
+        return str(result["result"]["message_id"])
+
+    async def send_keyboard(
+        self,
+        chat_id: str,
+        text: str,
+        buttons: list[list[str]],
+    ) -> str:
+        """Send a message with an inline keyboard."""
+        client = await self._get_client()
+
+        keyboard = {
+            "inline_keyboard": [
+                [{"text": btn, "callback_data": btn} for btn in row] for row in buttons
+            ]
+        }
+
+        payload = {
+            "chat_id": chat_id,
+            "text": text,
+            "reply_markup": keyboard,
+        }
+
+        response = await client.post(self._api_url("sendMessage"), json=telegram_payload(payload))
+        data = response.json()
+
+        if not data.get("ok"):
+            raise Exception(f"Telegram sendKeyboard failed: {data.get('description')}")
+
+        return str(data["result"]["message_id"])
+
+    async def _action_impl(self, action_name: str, params: dict) -> dict:
+        """Execute Telegram-specific actions."""
+        client = await self._get_client()
+
+        if action_name == "send_chat_action":
+            response = await client.post(
+                self._api_url("sendChatAction"),
+                json={"chat_id": params["chat_id"], "action": params.get("action", "typing")},
+            )
+            return response.json()
+
+        elif action_name == "get_chat":
+            response = await client.get(
+                self._api_url("getChat"),
+                params={"chat_id": params["chat_id"]},
+            )
+            return response.json()
+
+        raise ValueError(f"Unknown action: {action_name}")

integrations/messaging/whatsapp.py

@@ -0,0 +1,203 @@
+"""WhatsAppConnector — Meta WhatsApp Business API integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import AsyncIterator
+
+import httpx
+
+from integrations.base import (
+    BaseConnector,
+    ConnectorCapability,
+    ConnectorInfo,
+    InboundMessage,
+    OutboundMessage,
+)
+
+logger = logging.getLogger("hyperclaw.integrations.whatsapp")
+
+
+class WhatsAppConnector(BaseConnector):
+    """
+    WhatsApp Business API connector via Meta Graph API.
+
+    Required config:
+        - access_token: Meta Graph API access token
+        - phone_number_id: WhatsApp Business phone number ID
+
+    Note: This connector handles health data and sets hypershield_context accordingly.
+    """
+
+    BASE_URL = "https://graph.facebook.com/v17.0"
+
+    # HyperShield context for health data protection
+    hypershield_context = "health_data"
+
+    def __init__(self, config: dict) -> None:
+        self.config = config
+        self.access_token = config.get("access_token", "")
+        self.phone_number_id = config.get("phone_number_id", "")
+
+        if config.get("enabled", False):
+            if not self.access_token:
+                raise ValueError("WhatsAppConnector requires access_token")
+            if not self.phone_number_id:
+                raise ValueError("WhatsAppConnector requires phone_number_id")
+
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            connector_id="whatsapp",
+            platform="whatsapp",
+            category="messaging",
+            capabilities=frozenset(
+                [
+                    ConnectorCapability.SEND_MESSAGE,
+                    ConnectorCapability.RECEIVE_MESSAGE,
+                    ConnectorCapability.FILE_UPLOAD,
+                    ConnectorCapability.FILE_DOWNLOAD,
+                    ConnectorCapability.WEBHOOKS,
+                ]
+            ),
+            auth_type="bearer",
+            rate_limit_per_minute=80,
+            supports_threads=False,
+            supports_attachments=True,
+            supports_reactions=True,
+        )
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=30.0,
+                headers={
+                    "Authorization": f"Bearer {self.access_token}",
+                    "Content-Type": "application/json",
+                },
+            )
+        return self._client
+
+    async def health(self) -> bool:
+        """Check if credentials are valid."""
+        try:
+            client = await self._get_client()
+            response = await client.get(
+                f"{self.BASE_URL}/{self.phone_number_id}",
+            )
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f"WhatsApp health check failed: {e}")
+            return False
+
+    async def _send_impl(self, message: OutboundMessage) -> str:
+        """Send a text message via WhatsApp."""
+        client = await self._get_client()
+
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": message.recipient_id,
+            "type": "text",
+            "text": {"body": message.content},
+        }
+
+        response = await client.post(
+            f"{self.BASE_URL}/{self.phone_number_id}/messages",
+            json=payload,
+        )
+
+        if response.status_code not in (200, 201):
+            raise Exception(f"WhatsApp send failed: {response.text}")
+
+        data = response.json()
+        messages = data.get("messages", [])
+        return messages[0].get("id", "") if messages else ""
+
+    async def _receive_impl(self) -> AsyncIterator[InboundMessage]:
+        """
+        Receive messages. WhatsApp uses webhooks for incoming messages.
+        This is a stub; implement webhook handler separately.
+        """
+        return
+        yield
+
+    async def send_template(
+        self,
+        to: str,
+        template_name: str,
+        language_code: str = "en",
+        components: list[dict] | None = None,
+    ) -> str:
+        """Send a pre-approved message template."""
+        client = await self._get_client()
+
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": to,
+            "type": "template",
+            "template": {
+                "name": template_name,
+                "language": {"code": language_code},
+            },
+        }
+
+        if components:
+            payload["template"]["components"] = components
+
+        response = await client.post(
+            f"{self.BASE_URL}/{self.phone_number_id}/messages",
+            json=payload,
+        )
+
+        if response.status_code not in (200, 201):
+            raise Exception(f"WhatsApp send_template failed: {response.text}")
+
+        data = response.json()
+        messages = data.get("messages", [])
+        return messages[0].get("id", "") if messages else ""
+
+    async def send_media(
+        self,
+        to: str,
+        media_type: str,
+        url: str,
+        caption: str = "",
+    ) -> str:
+        """
+        Send media (image, video, audio, document).
+
+        Args:
+            to: Recipient phone number
+            media_type: One of "image", "video", "audio", "document"
+            url: Public URL of the media
+            caption: Optional caption (for image/video/document)
+        """
+        client = await self._get_client()
+
+        media_object = {"link": url}
+        if caption and media_type in ("image", "video", "document"):
+            media_object["caption"] = caption
+
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": to,
+            "type": media_type,
+            media_type: media_object,
+        }
+
+        response = await client.post(
+            f"{self.BASE_URL}/{self.phone_number_id}/messages",
+            json=payload,
+        )
+
+        if response.status_code not in (200, 201):
+            raise Exception(f"WhatsApp send_media failed: {response.text}")
+
+        data = response.json()
+        messages = data.get("messages", [])
+        return messages[0].get("id", "") if messages else ""

integrations/productivity/__init__.py

@@ -0,0 +1,17 @@
+"""HyperClaw Productivity Connectors."""
+
+from integrations.productivity.notion import NotionConnector
+from integrations.productivity.airtable import AirtableConnector
+from integrations.productivity.trello import TrelloConnector
+from integrations.productivity.asana import AsanaConnector
+from integrations.productivity.linear import LinearConnector
+from integrations.productivity.todoist import TodoistConnector
+
+__all__ = [
+    "NotionConnector",
+    "AirtableConnector",
+    "TrelloConnector",
+    "AsanaConnector",
+    "LinearConnector",
+    "TodoistConnector",
+]

integrations/productivity/airtable.py

@@ -0,0 +1,217 @@
+"""AirtableConnector — Airtable API integration."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from integrations.base import (
+    BaseConnector,
+    ConnectorCapability,
+    ConnectorInfo,
+)
+
+logger = logging.getLogger("hyperclaw.integrations.airtable")
+
+
+class AirtableConnector(BaseConnector):
+    """
+    Airtable API connector.
+
+    Required config:
+        - api_key: Airtable API key or Personal Access Token
+        - base_id: Airtable base ID
+    """
+
+    BASE_URL = "https://api.airtable.com/v0"
+
+    def __init__(self, config: dict) -> None:
+        self.config = config
+        self.api_key = config.get("api_key", "")
+        self.base_id = config.get("base_id", "")
+
+        if config.get("enabled", False):
+            if not self.api_key:
+                raise ValueError("AirtableConnector requires api_key")
+            if not self.base_id:
+                raise ValueError("AirtableConnector requires base_id")
+
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            connector_id="airtable",
+            platform="airtable",
+            category="productivity",
+            capabilities=frozenset(
+                [
+                    ConnectorCapability.READ_DATA,
+                    ConnectorCapability.WRITE_DATA,
+                    ConnectorCapability.DELETE_DATA,
+                    ConnectorCapability.LIST_DATA,
+                    ConnectorCapability.SEARCH,
+                ]
+            ),
+            auth_type="bearer",
+            rate_limit_per_minute=100,
+        )
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=30.0,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+        return self._client
+
+    async def health(self) -> bool:
+        """Check if Airtable API is accessible."""
+        try:
+            client = await self._get_client()
+            response = await client.get(f"{self.BASE_URL}/meta/bases")
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f"Airtable health check failed: {e}")
+            return False
+
+    async def list_records(
+        self,
+        table_name: str,
+        filter_formula: str | None = None,
+        sort: list[dict] | None = None,
+        max_records: int = 100,
+    ) -> list[dict]:
+        """List records in a table."""
+        client = await self._get_client()
+
+        params = {"maxRecords": max_records}
+        if filter_formula:
+            params["filterByFormula"] = filter_formula
+        if sort:
+            for i, s in enumerate(sort):
+                params[f"sort[{i}][field]"] = s.get("field")
+                params[f"sort[{i}][direction]"] = s.get("direction", "asc")
+
+        response = await client.get(
+            f"{self.BASE_URL}/{self.base_id}/{table_name}",
+            params=params,
+        )
+
+        if response.status_code != 200:
+            raise Exception(f"Airtable list records failed: {response.text}")
+
+        return response.json().get("records", [])
+
+    async def get_record(
+        self,
+        table_name: str,
+        record_id: str,
+    ) -> dict:
+        """Get a single record."""
+        client = await self._get_client()
+
+        response = await client.get(
+            f"{self.BASE_URL}/{self.base_id}/{table_name}/{record_id}"
+        )
+
+        if response.status_code != 200:
+            raise Exception(f"Airtable get record failed: {response.text}")
+
+        return response.json()
+
+    async def create_record(
+        self,
+        table_name: str,
+        fields: dict,
+    ) -> dict:
+        """Create a new record."""
+        client = await self._get_client()
+
+        response = await client.post(
+            f"{self.BASE_URL}/{self.base_id}/{table_name}",
+            json={"fields": fields},
+        )
+
+        if response.status_code not in (200, 201):
+            raise Exception(f"Airtable create record failed: {response.text}")
+
+        return response.json()
+
+    async def update_record(
+        self,
+        table_name: str,
+        record_id: str,
+        fields: dict,
+    ) -> dict:
+        """Update a record."""
+        client = await self._get_client()
+
+        response = await client.patch(
+            f"{self.BASE_URL}/{self.base_id}/{table_name}/{record_id}",
+            json={"fields": fields},
+        )
+
+        if response.status_code != 200:
+            raise Exception(f"Airtable update record failed: {response.text}")
+
+        return response.json()
+
+    async def delete_record(
+        self,
+        table_name: str,
+        record_id: str,
+    ) -> bool:
+        """Delete a record."""
+        client = await self._get_client()
+
+        response = await client.delete(
+            f"{self.BASE_URL}/{self.base_id}/{table_name}/{record_id}"
+        )
+
+        return response.status_code == 200
+
+    async def _read_impl(self, resource_id: str, **kwargs) -> dict:
+        """Read a record."""
+        return await self.get_record(
+            table_name=kwargs.get("table_name"),
+            record_id=resource_id,
+        )
+
+    async def _write_impl(self, resource_type: str, data: dict, **kwargs) -> dict:
+        """Create a record."""
+        return await self.create_record(
+            table_name=data.get("table_name"),
+            fields=data.get("fields", {}),
+        )
+
+    async def _delete_impl(self, resource_id: str, **kwargs) -> bool:
+        """Delete a record."""
+        return await self.delete_record(
+            table_name=kwargs.get("table_name"),
+            record_id=resource_id,
+        )
+
+    async def _list_impl(
+        self, resource_type: str, filters: dict, **kwargs
+    ) -> list[dict]:
+        """List records."""
+        return await self.list_records(
+            table_name=filters.get("table_name"),
+            filter_formula=filters.get("filter_formula"),
+            sort=filters.get("sort"),
+            max_records=filters.get("max_records", 100),
+        )
+
+    async def _search_impl(self, query: str, **kwargs) -> list[dict]:
+        """Search records using filter formula."""
+        table_name = kwargs.get("table_name")
+        field = kwargs.get("field", "Name")
+        return await self.list_records(
+            table_name=table_name,
+            filter_formula=f"SEARCH('{query}', {{{field}}})",
+        )