wappa 0.1.0__py3-none-any.whl

wappa/api/routes/whatsapp/whatsapp_media.py

@@ -0,0 +1,440 @@
+"""
+WhatsApp media messaging API endpoints.
+
+Provides REST API endpoints for WhatsApp media operations:
+- POST /api/whatsapp/media/upload: Upload media files
+- POST /api/whatsapp/media/send-image: Send image messages
+- POST /api/whatsapp/media/send-video: Send video messages
+- POST /api/whatsapp/media/send-audio: Send audio messages
+- POST /api/whatsapp/media/send-document: Send document messages
+- POST /api/whatsapp/media/send-sticker: Send sticker messages
+- GET /api/whatsapp/media/info/{media_id}: Get media information
+- GET /api/whatsapp/media/download/{media_id}: Download media
+- DELETE /api/whatsapp/media/{media_id}: Delete media
+
+Router configuration:
+- Prefix: /whatsapp/media
+- Tags: ["WhatsApp - Media"]
+- Full URL: /api/whatsapp/media/ (when included with /api prefix)
+"""
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import StreamingResponse
+
+from wappa.api.dependencies.whatsapp_dependencies import (
+    get_whatsapp_media_handler,
+    get_whatsapp_messenger,
+)
+from wappa.api.dependencies.whatsapp_media_dependencies import (
+    get_whatsapp_media_factory,
+)
+from wappa.domain.factories.media_factory import MediaFactory
+from wappa.domain.interfaces.media_interface import IMediaHandler
+from wappa.domain.interfaces.messaging_interface import IMessenger
+from wappa.domain.models.media_result import (
+    MediaDeleteResult,
+    MediaInfoResult,
+    MediaUploadResult,
+)
+from wappa.messaging.whatsapp.models.basic_models import MessageResult
+from wappa.messaging.whatsapp.models.media_models import (
+    AudioMessage,
+    DocumentMessage,
+    ImageMessage,
+    StickerMessage,
+    VideoMessage,
+)
+
+# Create router with WhatsApp Media configuration
+router = APIRouter(
+    prefix="/whatsapp/media",
+    tags=["WhatsApp - Media"],
+    responses={
+        400: {"description": "Bad Request - Invalid media format or size"},
+        401: {"description": "Unauthorized - Invalid tenant credentials"},
+        404: {"description": "Not Found - Media not found"},
+        413: {"description": "Payload Too Large - Media file too large"},
+        415: {"description": "Unsupported Media Type - Invalid file type"},
+        429: {"description": "Rate Limited - Too many requests"},
+        500: {"description": "Internal Server Error"},
+    },
+)
+
+
+@router.post(
+    "/upload",
+    response_model=MediaUploadResult,
+    summary="Upload Media",
+    description="Upload a media file to WhatsApp servers and get media ID for sending",
+)
+async def upload_media(
+    file: UploadFile = File(..., description="Media file to upload"),
+    media_type: str | None = Form(
+        None, description="MIME type (auto-detected if not provided)"
+    ),
+    media_handler: IMediaHandler = Depends(get_whatsapp_media_handler),
+) -> MediaUploadResult:
+    """Upload media file to WhatsApp servers.
+
+    Based on existing WhatsAppServiceMedia.upload_media() functionality.
+    Supports all WhatsApp media types with proper validation.
+    """
+    try:
+        # Read file data
+        file_data = await file.read()
+
+        # Use provided MIME type or file's content type
+        content_type = media_type or file.content_type
+
+        if not content_type:
+            raise HTTPException(
+                status_code=400,
+                detail="Could not determine media type. Please provide media_type parameter.",
+            )
+
+        # Upload using media handler
+        result = await media_handler.upload_media_from_bytes(
+            file_data=file_data,
+            media_type=content_type,
+            filename=file.filename or "uploaded_file",
+        )
+
+        if not result.success:
+            if result.error_code == "MIME_TYPE_UNSUPPORTED":
+                raise HTTPException(status_code=415, detail=result.error)
+            elif result.error_code == "FILE_SIZE_EXCEEDED":
+                raise HTTPException(status_code=413, detail=result.error)
+            else:
+                raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Upload failed: {str(e)}")
+
+
+@router.post(
+    "/send-image",
+    response_model=MessageResult,
+    summary="Send Image Message",
+    description="Send an image message with optional caption and reply context",
+)
+async def send_image_message(
+    request: ImageMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send image message via WhatsApp.
+
+    Supports JPEG and PNG images up to 5MB with optional captions.
+    """
+    try:
+        result = await messenger.send_image(
+            image_source=request.media_source,
+            recipient=request.recipient,
+            caption=request.caption,
+            reply_to_message_id=request.reply_to_message_id,
+        )
+
+        if not result.success:
+            raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to send image: {str(e)}")
+
+
+@router.post(
+    "/send-video",
+    response_model=MessageResult,
+    summary="Send Video Message",
+    description="Send a video message with optional caption and reply context",
+)
+async def send_video_message(
+    request: VideoMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send video message via WhatsApp.
+
+    Supports MP4 and 3GP videos up to 16MB with optional captions.
+    """
+    try:
+        result = await messenger.send_video(
+            video_source=request.media_source,
+            recipient=request.recipient,
+            caption=request.caption,
+            reply_to_message_id=request.reply_to_message_id,
+        )
+
+        if not result.success:
+            raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to send video: {str(e)}")
+
+
+@router.post(
+    "/send-audio",
+    response_model=MessageResult,
+    summary="Send Audio Message",
+    description="Send an audio message with optional reply context",
+)
+async def send_audio_message(
+    request: AudioMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send audio message via WhatsApp.
+
+    Supports AAC, AMR, MP3, M4A, and OGG audio up to 16MB.
+    Note: Audio messages do not support captions.
+    """
+    try:
+        result = await messenger.send_audio(
+            audio_source=request.media_source,
+            recipient=request.recipient,
+            reply_to_message_id=request.reply_to_message_id,
+        )
+
+        if not result.success:
+            raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to send audio: {str(e)}")
+
+
+@router.post(
+    "/send-document",
+    response_model=MessageResult,
+    summary="Send Document Message",
+    description="Send a document message with optional filename and reply context",
+)
+async def send_document_message(
+    request: DocumentMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send document message via WhatsApp.
+
+    Supports TXT, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX up to 100MB.
+    """
+    try:
+        result = await messenger.send_document(
+            document_source=request.media_source,
+            recipient=request.recipient,
+            filename=request.filename,
+            reply_to_message_id=request.reply_to_message_id,
+        )
+
+        if not result.success:
+            raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to send document: {str(e)}"
+        )
+
+
+@router.post(
+    "/send-sticker",
+    response_model=MessageResult,
+    summary="Send Sticker Message",
+    description="Send a sticker message with optional reply context",
+)
+async def send_sticker_message(
+    request: StickerMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send sticker message via WhatsApp.
+
+    Supports WebP images only (100KB static, 500KB animated).
+    Note: Sticker messages do not support captions.
+    """
+    try:
+        result = await messenger.send_sticker(
+            sticker_source=request.media_source,
+            recipient=request.recipient,
+            reply_to_message_id=request.reply_to_message_id,
+        )
+
+        if not result.success:
+            raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to send sticker: {str(e)}")
+
+
+@router.get(
+    "/info/{media_id}",
+    response_model=MediaInfoResult,
+    summary="Get Media Information",
+    description="Retrieve media information including URL, MIME type, and file size",
+)
+async def get_media_info(
+    media_id: str, media_handler: IMediaHandler = Depends(get_whatsapp_media_handler)
+) -> MediaInfoResult:
+    """Get media information by ID.
+
+    Returns media URL (valid for 5 minutes), MIME type, file size, and SHA256 hash.
+    """
+    try:
+        result = await media_handler.get_media_info(media_id)
+
+        if not result.success:
+            if "not found" in result.error.lower():
+                raise HTTPException(status_code=404, detail=result.error)
+            else:
+                raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to get media info: {str(e)}"
+        )
+
+
+@router.get(
+    "/download/{media_id}",
+    summary="Download Media",
+    description="Download media file by ID as streaming response",
+)
+async def download_media(
+    media_id: str, media_handler: IMediaHandler = Depends(get_whatsapp_media_handler)
+):
+    """Download media by ID as streaming response.
+
+    Returns media file as streaming download with appropriate headers.
+    """
+    try:
+        # Get media info first for headers
+        info_result = await media_handler.get_media_info(media_id)
+        if not info_result.success:
+            if "not found" in info_result.error.lower():
+                raise HTTPException(status_code=404, detail=info_result.error)
+            else:
+                raise HTTPException(status_code=400, detail=info_result.error)
+
+        # Download media
+        download_result = await media_handler.download_media(media_id)
+        if not download_result.success:
+            raise HTTPException(status_code=400, detail=download_result.error)
+
+        # Create streaming response
+        def generate_content():
+            yield download_result.file_data
+
+        # Determine filename
+        filename = f"media_{media_id}"
+        if download_result.mime_type:
+            # Simple extension mapping
+            ext_map = {
+                "image/jpeg": ".jpg",
+                "image/png": ".png",
+                "video/mp4": ".mp4",
+                "audio/mpeg": ".mp3",
+                "application/pdf": ".pdf",
+            }
+            if download_result.mime_type in ext_map:
+                filename += ext_map[download_result.mime_type]
+
+        return StreamingResponse(
+            generate_content(),
+            media_type=download_result.mime_type or "application/octet-stream",
+            headers={
+                "Content-Disposition": f"attachment; filename={filename}",
+                "Content-Length": str(download_result.file_size)
+                if download_result.file_size
+                else "",
+            },
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to download media: {str(e)}"
+        )
+
+
+@router.delete(
+    "/{media_id}",
+    response_model=MediaDeleteResult,
+    summary="Delete Media",
+    description="Delete media from WhatsApp servers",
+)
+async def delete_media(
+    media_id: str, media_handler: IMediaHandler = Depends(get_whatsapp_media_handler)
+) -> MediaDeleteResult:
+    """Delete media by ID.
+
+    Permanently removes media from WhatsApp servers.
+    Media files persist for 30 days unless deleted earlier.
+    """
+    try:
+        result = await media_handler.delete_media(media_id)
+
+        if not result.success:
+            if "not found" in result.error.lower():
+                raise HTTPException(status_code=404, detail=result.error)
+            else:
+                raise HTTPException(status_code=400, detail=result.error)
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to delete media: {str(e)}")
+
+
+@router.get(
+    "/limits",
+    summary="Get Media Limits",
+    description="Get platform-specific media limits and supported types",
+)
+async def get_media_limits(
+    media_factory: MediaFactory = Depends(get_whatsapp_media_factory),
+) -> dict:
+    """Get WhatsApp media limits and constraints.
+
+    Returns supported MIME types, file size limits, and platform constraints.
+    """
+    return media_factory.get_media_limits()
+
+
+@router.get(
+    "/health",
+    summary="Media Service Health Check",
+    description="Check health status of media services",
+)
+async def health_check(
+    media_handler: IMediaHandler = Depends(get_whatsapp_media_handler),
+) -> dict:
+    """Health check for media services.
+
+    Returns service status and configuration information.
+    """
+    return {
+        "status": "healthy",
+        "service": "whatsapp-media",
+        "platform": media_handler.platform.value,
+        "tenant_id": media_handler.tenant_id,
+        "supported_types": len(media_handler.supported_media_types),
+        "max_file_sizes": media_handler.max_file_size,
+    }

wappa/api/routes/whatsapp/whatsapp_messages.py

@@ -0,0 +1,195 @@
+"""
+WhatsApp messaging API endpoints.
+
+Provides REST API endpoints for WhatsApp messaging operations:
+- POST /api/whatsapp/messages/send-text: Send text messages
+- POST /api/whatsapp/messages/mark-as-read: Mark messages as read with optional typing
+
+Router configuration:
+- Prefix: /whatsapp/messages
+- Tags: ["WhatsApp - Messages"]
+- Full URL: /api/whatsapp/messages/ (when included with /api prefix)
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from wappa.api.dependencies.whatsapp_dependencies import (
+    get_whatsapp_message_factory,
+    get_whatsapp_messenger,
+)
+from wappa.core.logging.logger import get_logger
+from wappa.domain.factories.message_factory import MessageFactory
+from wappa.domain.interfaces.messaging_interface import IMessenger
+from wappa.messaging.whatsapp.models.basic_models import (
+    BasicTextMessage,
+    MessageResult,
+    ReadStatusMessage,
+)
+
+# Create router with WhatsApp Messages configuration
+router = APIRouter(
+    prefix="/whatsapp/messages",
+    tags=["WhatsApp - Messages"],
+    responses={
+        400: {"description": "Bad Request - Invalid message format"},
+        401: {"description": "Unauthorized - Invalid tenant credentials"},
+        429: {"description": "Rate Limited - Too many requests"},
+        500: {"description": "Internal Server Error"},
+    },
+)
+
+
+@router.post(
+    "/send-text",
+    response_model=MessageResult,
+    summary="Send Text Message",
+    description="Send a text message via WhatsApp with optional reply and preview control",
+)
+async def send_text_message(
+    request: BasicTextMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Send a text message via WhatsApp.
+
+    Sends a text message through WhatsApp Business API with support for:
+    - Reply to existing messages (threading)
+    - URL preview control
+    - Automatic URL detection and preview handling
+
+    Args:
+        request: Text message payload with recipient, content, and options
+        messenger: WhatsApp messenger implementation (injected)
+
+    Returns:
+        MessageResult with operation status, message ID, and metadata
+
+    Raises:
+        HTTPException 400: If message validation fails
+        HTTPException 401: If tenant credentials are invalid
+        HTTPException 500: If WhatsApp API call fails
+    """
+    logger = get_logger(__name__)
+
+    try:
+        logger.info(f"Sending text message to {request.recipient}")
+
+        result = await messenger.send_text(
+            text=request.text,
+            recipient=request.recipient,
+            reply_to_message_id=request.reply_to_message_id,
+            disable_preview=request.disable_preview,
+        )
+
+        if result.success:
+            logger.info(f"Text message sent successfully: {result.message_id}")
+        else:
+            logger.error(f"Failed to send text message: {result.error}")
+
+        return result
+
+    except ValueError as e:
+        logger.error(f"Validation error sending text message: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Unexpected error sending text message: {str(e)}")
+        raise HTTPException(status_code=500, detail="Failed to send message")
+
+
+@router.post(
+    "/mark-as-read",
+    response_model=MessageResult,
+    summary="Mark Message as Read",
+    description="Mark a WhatsApp message as read with optional typing indicator",
+)
+async def mark_message_as_read(
+    request: ReadStatusMessage, messenger: IMessenger = Depends(get_whatsapp_messenger)
+) -> MessageResult:
+    """Mark a WhatsApp message as read with optional typing indicator.
+
+    Marks a message as read through WhatsApp Business API with support for:
+    - Simple read receipt (typing=false)
+    - Read receipt with typing indicator (typing=true) - Key requirement
+
+    Args:
+        request: Read status payload with message ID and typing flag
+        messenger: WhatsApp messenger implementation (injected)
+
+    Returns:
+        MessageResult with operation status and metadata
+
+    Raises:
+        HTTPException 400: If message ID is invalid
+        HTTPException 401: If tenant credentials are invalid
+        HTTPException 500: If WhatsApp API call fails
+    """
+    logger = get_logger(__name__)
+
+    try:
+        action_desc = "with typing indicator" if request.typing else "without typing"
+        logger.info(f"Marking message {request.message_id} as read {action_desc}")
+
+        result = await messenger.mark_as_read(
+            message_id=request.message_id,
+            typing=request.typing,  # Key requirement: typing boolean support
+        )
+
+        if result.success:
+            logger.info(f"Message marked as read successfully: {request.message_id}")
+        else:
+            logger.error(f"Failed to mark message as read: {result.error}")
+
+        return result
+
+    except ValueError as e:
+        logger.error(f"Validation error marking message as read: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Unexpected error marking message as read: {str(e)}")
+        raise HTTPException(status_code=500, detail="Failed to mark message as read")
+
+
+@router.get(
+    "/limits",
+    summary="Get Message Limits",
+    description="Get WhatsApp platform-specific message limits and constraints",
+)
+async def get_message_limits(
+    factory: MessageFactory = Depends(get_whatsapp_message_factory),
+) -> dict:
+    """Get WhatsApp platform-specific message limits.
+
+    Returns current WhatsApp Business API limits for message validation
+    including text length limits, media size limits, and interactive message constraints.
+
+    Args:
+        factory: WhatsApp message factory (injected)
+
+    Returns:
+        Dictionary containing platform-specific limits and constraints
+    """
+    return factory.get_message_limits()
+
+
+@router.get(
+    "/health",
+    summary="Health Check",
+    description="Check WhatsApp messaging service health",
+)
+async def health_check(messenger: IMessenger = Depends(get_whatsapp_messenger)) -> dict:
+    """Health check for WhatsApp messaging service.
+
+    Verifies that the WhatsApp messaging service is properly configured
+    and ready to handle requests.
+
+    Args:
+        messenger: WhatsApp messenger implementation (injected)
+
+    Returns:
+        Health status information
+    """
+    return {
+        "status": "healthy",
+        "service": "whatsapp-messages",
+        "platform": messenger.platform.value,
+        "tenant_id": messenger.tenant_id,
+        "timestamp": "2025-01-26T00:00:00Z",
+    }