codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/app.py

@@ -0,0 +1,123 @@
+"""WhatsApp Cloud API - Flask Application with Webhook Handler."""
+
+import asyncio
+import logging
+import os
+
+from dotenv import load_dotenv
+from flask import Flask, request, jsonify
+
+from whatsapp_client import WhatsAppClient
+from webhook_handler import (
+    validate_hmac_signature,
+    verify_webhook,
+    parse_webhook_payload,
+    extract_message_content,
+)
+
+load_dotenv()
+
+app = Flask(__name__)
+logger = logging.getLogger(__name__)
+
+# Initialize WhatsApp client
+whatsapp = WhatsAppClient()
+
+
+def _is_debug_enabled() -> bool:
+    """Allow debug only when explicitly enabled for local development."""
+    return os.environ.get("FLASK_DEBUG", "").lower() in {"1", "true", "yes", "on"}
+
+
+# === Webhook Routes ===
+
+
+@app.route("/webhook", methods=["GET"])
+def webhook_verify():
+    """Handle webhook verification (GET challenge from Meta)."""
+    return verify_webhook()
+
+
+@app.route("/webhook", methods=["POST"])
+@validate_hmac_signature()
+def webhook_receive():
+    """Handle incoming messages and status updates."""
+    data = request.get_json()
+
+    # Parse webhook payload
+    parsed = parse_webhook_payload(data)
+
+    # Process messages
+    for message in parsed["messages"]:
+        asyncio.run(handle_incoming_message(message))
+
+    # Process status updates
+    for status in parsed["statuses"]:
+        handle_status_update(status)
+
+    # Always return 200 within 5 seconds
+    return "OK", 200
+
+
+# === Message Handler ===
+
+
+async def handle_incoming_message(message: dict) -> None:
+    """Process an incoming message and send a response."""
+    from_number = message["from"]
+    content = extract_message_content(message)
+
+    logger.info("Received WhatsApp message")
+
+    # Mark as read
+    await whatsapp.mark_as_read(message["id"])
+
+    # Example responses intentionally avoid reflecting user-provided content.
+    match content["type"]:
+        case "text":
+            await whatsapp.send_text(from_number, "Recebi sua mensagem. Como posso ajudar?")
+
+        case "button":
+            await whatsapp.send_text(from_number, "Recebi sua selecao com sucesso.")
+
+        case "list":
+            await whatsapp.send_text(from_number, "Recebi sua escolha com sucesso.")
+
+        case "image" | "document" | "video" | "audio":
+            await whatsapp.send_text(from_number, "Recebi sua midia com sucesso.")
+
+        case _:
+            await whatsapp.send_text(from_number, "Desculpe, nao entendi. Como posso ajudar?")
+
+
+# === Status Handler ===
+
+
+def handle_status_update(status: dict) -> None:
+    """Process a message status update."""
+    logger.info("WhatsApp status update id=%s status=%s", status["id"], status["status"])
+
+    if status["status"] == "failed":
+        errors = status.get("errors", [])
+        logger.warning("WhatsApp message delivery failed with %d error(s)", len(errors))
+
+
+# === Health Check ===
+
+
+@app.route("/health")
+def health():
+    """Health check endpoint."""
+    return jsonify({"status": "ok"})
+
+
+# === Start Server ===
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 3000))
+    logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"))
+    logger.info("WhatsApp webhook server running on port %s", port)
+    logger.info("Webhook URL: http://localhost:%s/webhook", port)
+    logger.info("Health check: http://localhost:%s/health", port)
+    # Keep debug disabled by default so the boilerplate is safe in shared environments.
+    app.run(host="0.0.0.0", port=port, debug=_is_debug_enabled())

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/requirements.txt

@@ -0,0 +1,4 @@
+flask>=3.0.0
+httpx>=0.27.0
+python-dotenv>=1.0.0
+gunicorn>=22.0.0

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/template_manager.py

@@ -0,0 +1,100 @@
+"""WhatsApp Template Management - CRUD operations via API."""
+
+import os
+from typing import Any
+
+import httpx
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+
+class TemplateManager:
+    """Manage WhatsApp message templates programmatically."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        waba_id: str | None = None,
+    ):
+        self.token = token or os.environ["WHATSAPP_TOKEN"]
+        self.waba_id = waba_id or os.environ["WABA_ID"]
+        self.headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    async def list_templates(self, status: str | None = None) -> list[dict[str, Any]]:
+        """List all templates, optionally filtered by status (APPROVED, PENDING, REJECTED)."""
+        params: dict[str, Any] = {"limit": 100}
+        if status:
+            params["status"] = status
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                f"{GRAPH_API}/{self.waba_id}/message_templates",
+                params=params,
+                headers=self.headers,
+            )
+            response.raise_for_status()
+            return response.json()["data"]
+
+    async def create_template(
+        self,
+        name: str,
+        category: str,
+        language: str,
+        components: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """
+        Create a new message template.
+
+        Args:
+            name: Template name (lowercase, underscores, no spaces)
+            category: MARKETING, UTILITY, or AUTHENTICATION
+            language: Language code (e.g., 'pt_BR')
+            components: List of template components (HEADER, BODY, FOOTER, BUTTONS)
+
+        Returns:
+            Dict with id, status, and category of created template.
+        """
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{GRAPH_API}/{self.waba_id}/message_templates",
+                json={
+                    "name": name,
+                    "category": category,
+                    "language": language,
+                    "components": components,
+                },
+                headers=self.headers,
+            )
+            response.raise_for_status()
+            return response.json()
+
+    async def delete_template(self, template_name: str) -> None:
+        """
+        Delete a template by name.
+
+        Note: This deletes ALL translations of the template.
+        Templates cannot be edited - delete and recreate instead.
+        """
+        async with httpx.AsyncClient() as client:
+            response = await client.request(
+                "DELETE",
+                f"{GRAPH_API}/{self.waba_id}/message_templates",
+                json={"name": template_name},
+                headers=self.headers,
+            )
+            response.raise_for_status()
+
+    async def get_approved(self) -> list[dict[str, Any]]:
+        """List only approved templates ready for use."""
+        return await self.list_templates("APPROVED")
+
+    async def get_pending(self) -> list[dict[str, Any]]:
+        """List templates awaiting approval."""
+        return await self.list_templates("PENDING")
+
+    async def get_rejected(self) -> list[dict[str, Any]]:
+        """List rejected templates."""
+        return await self.list_templates("REJECTED")

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/webhook_handler.py

@@ -0,0 +1,139 @@
+"""WhatsApp Webhook Handler with HMAC-SHA256 validation."""
+
+import hashlib
+import hmac
+import os
+import re
+from functools import wraps
+from typing import Any
+
+from flask import Response, abort, request
+
+
+_SAFE_CHALLENGE_RE = re.compile(r"^[A-Za-z0-9._-]{1,200}$")
+
+
+def validate_hmac_signature(app_secret: str | None = None):
+    """
+    Flask decorator to validate HMAC-SHA256 signature on webhook requests.
+
+    A Meta assina cada request com o App Secret no header X-Hub-Signature-256.
+    Validar esta assinatura previne requests falsificados.
+    Usa hmac.compare_digest para comparacao constant-time (previne timing attacks).
+    """
+    secret = app_secret or os.environ["APP_SECRET"]
+
+    def decorator(f):
+        @wraps(f)
+        def decorated_function(*args, **kwargs):
+            signature = request.headers.get("X-Hub-Signature-256", "")
+            if not signature:
+                abort(401, "Missing signature header")
+
+            raw_body = request.get_data()
+            expected = "sha256=" + hmac.new(
+                secret.encode(), raw_body, hashlib.sha256
+            ).hexdigest()
+
+            if not hmac.compare_digest(signature, expected):
+                abort(401, "Invalid signature")
+
+            return f(*args, **kwargs)
+
+        return decorated_function
+
+    return decorator
+
+
+def verify_webhook(verify_token: str | None = None):
+    """
+    Handle webhook verification (GET request from Meta).
+    Returns the challenge to confirm the webhook endpoint.
+    """
+    token = verify_token or os.environ["VERIFY_TOKEN"]
+
+    mode = request.args.get("hub.mode")
+    req_token = request.args.get("hub.verify_token")
+    challenge = request.args.get("hub.challenge")
+
+    if mode != "subscribe" or req_token != token:
+        abort(403, "Verification failed")
+
+    if not challenge or not _SAFE_CHALLENGE_RE.fullmatch(challenge):
+        abort(400, "Invalid challenge")
+
+    return Response(challenge, status=200, mimetype="text/plain")
+
+
+def parse_webhook_payload(data: dict[str, Any]) -> dict[str, list]:
+    """
+    Parse webhook payload and extract messages and status updates.
+
+    Returns dict with 'messages' and 'statuses' lists.
+    """
+    messages: list[dict] = []
+    statuses: list[dict] = []
+
+    for entry in data.get("entry", []):
+        for change in entry.get("changes", []):
+            value = change.get("value", {})
+            if "messages" in value:
+                messages.extend(value["messages"])
+            if "statuses" in value:
+                statuses.extend(value["statuses"])
+
+    return {"messages": messages, "statuses": statuses}
+
+
+def extract_message_content(message: dict[str, Any]) -> dict[str, Any]:
+    """
+    Extract readable content from an incoming message.
+
+    Returns dict with 'type' and relevant fields (text, button_id, media_id, etc.).
+    """
+    msg_type = message.get("type", "unknown")
+
+    if msg_type == "text":
+        return {"type": "text", "text": message.get("text", {}).get("body")}
+
+    if msg_type == "interactive":
+        interactive = message.get("interactive", {})
+        int_type = interactive.get("type")
+
+        if int_type == "button_reply":
+            reply = interactive.get("button_reply", {})
+            return {"type": "button", "button_id": reply.get("id"), "text": reply.get("title")}
+
+        if int_type == "list_reply":
+            reply = interactive.get("list_reply", {})
+            return {"type": "list", "list_id": reply.get("id"), "text": reply.get("title")}
+
+        if int_type == "nfm_reply":
+            return {
+                "type": "flow",
+                "text": interactive.get("nfm_reply", {}).get("response_json"),
+            }
+
+        return {"type": "interactive"}
+
+    if msg_type in ("image", "document", "video", "audio"):
+        media_data = message.get(msg_type, {})
+        return {"type": msg_type, "media_id": media_data.get("id")}
+
+    if msg_type == "location":
+        loc = message.get("location", {})
+        return {
+            "type": "location",
+            "latitude": loc.get("latitude"),
+            "longitude": loc.get("longitude"),
+        }
+
+    if msg_type == "reaction":
+        reaction = message.get("reaction", {})
+        return {
+            "type": "reaction",
+            "emoji": reaction.get("emoji"),
+            "message_id": reaction.get("message_id"),
+        }
+
+    return {"type": msg_type}

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/whatsapp_client.py

@@ -0,0 +1,219 @@
+"""WhatsApp Cloud API Client with async support and retry logic."""
+
+import os
+import asyncio
+from typing import Any
+
+import httpx
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+
+class WhatsAppClient:
+    """Client for WhatsApp Cloud API with retry and error handling."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        phone_number_id: str | None = None,
+        waba_id: str | None = None,
+    ):
+        self.token = token or os.environ["WHATSAPP_TOKEN"]
+        self.phone_number_id = phone_number_id or os.environ["PHONE_NUMBER_ID"]
+        self.waba_id = waba_id or os.environ["WABA_ID"]
+        self.headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    async def send_message(self, payload: dict[str, Any]) -> dict:
+        """Send a message with retry logic."""
+        return await self._send_with_retry(payload)
+
+    async def send_text(self, to: str, body: str, preview_url: bool = False) -> dict:
+        """Send a text message."""
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "text",
+            "text": {"body": body, "preview_url": preview_url},
+        })
+
+    async def send_template(
+        self,
+        to: str,
+        template_name: str,
+        language_code: str,
+        components: list[dict] | None = None,
+    ) -> dict:
+        """Send a template message."""
+        payload: dict[str, Any] = {
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "template",
+            "template": {
+                "name": template_name,
+                "language": {"code": language_code},
+            },
+        }
+        if components:
+            payload["template"]["components"] = components
+        return await self.send_message(payload)
+
+    async def send_image(self, to: str, image_url: str, caption: str | None = None) -> dict:
+        """Send an image message."""
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "image",
+            "image": {"link": image_url, **({"caption": caption} if caption else {})},
+        })
+
+    async def send_document(
+        self, to: str, document_url: str, filename: str, caption: str | None = None
+    ) -> dict:
+        """Send a document message."""
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "document",
+            "document": {
+                "link": document_url,
+                "filename": filename,
+                **({"caption": caption} if caption else {}),
+            },
+        })
+
+    async def send_interactive_buttons(
+        self,
+        to: str,
+        body_text: str,
+        buttons: list[dict[str, str]],
+        header_text: str | None = None,
+        footer_text: str | None = None,
+    ) -> dict:
+        """Send interactive button message (max 3 buttons)."""
+        interactive: dict[str, Any] = {
+            "type": "button",
+            "body": {"text": body_text},
+            "action": {
+                "buttons": [
+                    {"type": "reply", "reply": {"id": b["id"], "title": b["title"]}}
+                    for b in buttons
+                ]
+            },
+        }
+        if header_text:
+            interactive["header"] = {"type": "text", "text": header_text}
+        if footer_text:
+            interactive["footer"] = {"text": footer_text}
+
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "interactive",
+            "interactive": interactive,
+        })
+
+    async def send_interactive_list(
+        self,
+        to: str,
+        body_text: str,
+        button_text: str,
+        sections: list[dict],
+        header_text: str | None = None,
+        footer_text: str | None = None,
+    ) -> dict:
+        """Send interactive list message (max 10 options across sections)."""
+        interactive: dict[str, Any] = {
+            "type": "list",
+            "body": {"text": body_text},
+            "action": {"button": button_text, "sections": sections},
+        }
+        if header_text:
+            interactive["header"] = {"type": "text", "text": header_text}
+        if footer_text:
+            interactive["footer"] = {"text": footer_text}
+
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "interactive",
+            "interactive": interactive,
+        })
+
+    async def send_reaction(self, to: str, message_id: str, emoji: str) -> dict:
+        """React to a message with an emoji."""
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "reaction",
+            "reaction": {"message_id": message_id, "emoji": emoji},
+        })
+
+    async def send_location(
+        self,
+        to: str,
+        latitude: float,
+        longitude: float,
+        name: str | None = None,
+        address: str | None = None,
+    ) -> dict:
+        """Send a location message."""
+        return await self.send_message({
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "location",
+            "location": {
+                "latitude": latitude,
+                "longitude": longitude,
+                **({"name": name} if name else {}),
+                **({"address": address} if address else {}),
+            },
+        })
+
+    async def mark_as_read(self, message_id: str) -> None:
+        """Mark a message as read (blue checkmarks)."""
+        async with httpx.AsyncClient() as client:
+            await client.post(
+                f"{GRAPH_API}/{self.phone_number_id}/messages",
+                json={
+                    "messaging_product": "whatsapp",
+                    "status": "read",
+                    "message_id": message_id,
+                },
+                headers=self.headers,
+            )
+
+    async def _send_with_retry(self, payload: dict, max_retries: int = 3) -> dict:
+        """Send message with exponential backoff retry."""
+        non_retryable_codes = {100, 131026, 131051, 132000, 132001, 132005, 133010}
+
+        for attempt in range(1, max_retries + 1):
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.post(
+                        f"{GRAPH_API}/{self.phone_number_id}/messages",
+                        json=payload,
+                        headers=self.headers,
+                    )
+                    response.raise_for_status()
+                    return response.json()
+            except httpx.HTTPStatusError as e:
+                error_data = e.response.json().get("error", {})
+                error_code = error_data.get("code", 0)
+                error_message = error_data.get("message", str(e))
+
+                if error_code in non_retryable_codes:
+                    raise RuntimeError(f"WhatsApp API Error {error_code}: {error_message}")
+
+                if attempt < max_retries:
+                    delay = 2**attempt
+                    await asyncio.sleep(delay)
+                    continue
+
+                raise RuntimeError(
+                    f"WhatsApp API Error after {max_retries} retries: {error_message}"
+                )
+
+        raise RuntimeError("Unexpected: retry loop exited without return or raise")