Add Turn client

Author: erikh360

README.md

@@ -101,5 +101,7 @@ There is a [docker image](https://github.com/praekeltfoundation/mc-intent-classi
 | CELERY_BROKER_URL | RabbitMQ connection URL (e.g., amqp://user:pass@host:5672/) | Yes (for async processing) |
 | CELERY_RESULT_BACKEND | Result backend URL (e.g., rpc://) | No (defaults to rpc://) |
 | CELERY_TASK_ALWAYS_EAGER | Set to "true" for synchronous task execution (testing only) | No |
+| TURN_API_BASE_URL | Turn API base URL (e.g., https://whatsapp.turn.io) | Yes (for Turn integration) |
+| TURN_API_TOKEN | Turn API authentication token (Bearer token) | Yes (for Turn integration) |
 
 **Note:** You need to run both the Flask app (webhook receiver) and Celery worker (task processor) containers for full functionality.

poetry.lock

@@ -20,7 +20,7 @@ numpy = "2.2.5"
 torch = "2.6.0"
 sentence-transformers = "^3.1.1"
 celery = {extras = ["amqp"], version = "^5.4.0"}
-httpx = "^0.27.0"
+requests = "^2.32.0"
 pydantic = "^2.9.0"
 
 [tool.poetry.group.dev.dependencies]

pyproject.toml

@@ -0,0 +1,101 @@
+"""Turn API client for updating message labels."""
+
+import logging
+import os
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class TurnAPIError(Exception):
+    """Base exception for Turn API errors."""
+
+
+class TurnAPIClientError(TurnAPIError):
+    """Exception for 4xx client errors (won't retry)."""
+
+
+class TurnAPIServerError(TurnAPIError):
+    """Exception for 5xx server errors (can retry)."""
+
+
+class TurnAPIClient:
+    """Client for interacting with Turn API to update message labels."""
+
+    def __init__(self):
+        """
+        Initialize Turn API client.
+
+        Raises:
+            ValueError: If TURN_API_BASE_URL or TURN_API_TOKEN are not set
+        """
+        self.base_url = os.environ.get("TURN_API_BASE_URL", "").rstrip("/")
+        self.api_token = os.environ.get("TURN_API_TOKEN", "")
+
+        if not self.base_url:
+            msg = "TURN_API_BASE_URL must be set"
+            raise ValueError(msg)
+
+        if not self.api_token:
+            msg = "TURN_API_TOKEN must be set"
+            raise ValueError(msg)
+
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_token}",
+                "Accept": "application/vnd.v1+json",
+                "Content-Type": "application/json",
+            }
+        )
+
+    def update_message_label(self, message_id: str, label: str) -> dict:
+        """
+        Update a message label in Turn.
+
+        Args:
+            message_id: Turn message ID
+            label: Intent label to assign
+
+        Returns:
+            dict: Response from Turn API
+
+        Raises:
+            TurnAPIClientError: For 4xx errors (invalid request)
+            TurnAPIServerError: For 5xx errors (server issues)
+            TurnAPIError: For other errors
+        """
+        endpoint = f"{self.base_url}/v1/messages/{message_id}/labels"
+
+        payload = {"labels": [label]}
+
+        try:
+            logger.info(f"Updating Turn message {message_id} with label: {label}")
+
+            response = self.session.post(endpoint, json=payload)
+
+            # Check for errors
+            if response.status_code >= 500:
+                error_msg = f"Turn API server error (HTTP {response.status_code}): {response.text}"
+                logger.error(error_msg)
+                raise TurnAPIServerError(error_msg)
+
+            if response.status_code >= 400:
+                error_msg = f"Turn API client error (HTTP {response.status_code}): {response.text}"
+                logger.error(error_msg)
+                raise TurnAPIClientError(error_msg)
+
+            # Success
+            logger.info(f"Successfully updated message {message_id} label to {label}")
+            return response.json() if response.text else {}
+
+        except requests.Timeout as e:
+            error_msg = f"Turn API request timeout for message {message_id}: {e}"
+            logger.error(error_msg)
+            raise TurnAPIServerError(error_msg) from e
+
+        except requests.RequestException as e:
+            error_msg = f"Turn API request error for message {message_id}: {e}"
+            logger.error(error_msg)
+            raise TurnAPIError(error_msg) from e

src/turn_client.py

@@ -0,0 +1,135 @@
+"""Tests for Turn API client."""
+
+import pytest
+
+from src.turn_client import (
+    TurnAPIClient,
+    TurnAPIClientError,
+    TurnAPIError,
+    TurnAPIServerError,
+)
+
+
+@pytest.fixture(autouse=True)
+def setup_turn_env(monkeypatch):
+    """Set up Turn API environment variables for all tests."""
+    monkeypatch.setenv("TURN_API_BASE_URL", "https://api.turn.io")
+    monkeypatch.setenv("TURN_API_TOKEN", "test-token")
+
+
+class TestTurnAPIClient:
+    """Tests for TurnAPIClient class."""
+
+    def test_client_initialization_with_env_vars(self):
+        """Test client initialization with environment variables."""
+        client = TurnAPIClient()
+        assert client.base_url == "https://api.turn.io"
+        assert client.api_token == "test-token"  # noqa: S105
+
+    def test_client_initialization_strips_trailing_slash(self, monkeypatch):
+        """Test that trailing slash is removed from base URL."""
+        monkeypatch.setenv("TURN_API_BASE_URL", "https://api.turn.io/")
+        monkeypatch.setenv("TURN_API_TOKEN", "test-token")
+
+        client = TurnAPIClient()
+        assert client.base_url == "https://api.turn.io"
+
+    def test_client_initialization_missing_base_url(self, monkeypatch):
+        """Test that ValueError is raised if base URL is missing."""
+        monkeypatch.delenv("TURN_API_BASE_URL", raising=False)
+        monkeypatch.setenv("TURN_API_TOKEN", "test-token")
+
+        with pytest.raises(ValueError, match="TURN_API_BASE_URL must be set"):
+            TurnAPIClient()
+
+    def test_client_initialization_missing_token(self, monkeypatch):
+        """Test that ValueError is raised if token is missing."""
+        monkeypatch.setenv("TURN_API_BASE_URL", "https://api.turn.io")
+        monkeypatch.delenv("TURN_API_TOKEN", raising=False)
+
+        with pytest.raises(ValueError, match="TURN_API_TOKEN must be set"):
+            TurnAPIClient()
+
+    def test_update_message_label_success(self, mocker):
+        """Test successful label update."""
+        client = TurnAPIClient()
+
+        # Mock successful response
+        mock_response = mocker.Mock()
+        mock_response.status_code = 200
+        mock_response.text = '{"status": "success", "message_id": "msg-123"}'
+        mock_response.json.return_value = {"status": "success", "message_id": "msg-123"}
+        mock_post = mocker.patch.object(
+            client.session, "post", return_value=mock_response
+        )
+
+        result = client.update_message_label("msg-123", "compliment")
+
+        # Verify request
+        mock_post.assert_called_once_with(
+            "https://api.turn.io/v1/messages/msg-123/labels",
+            json={"labels": ["compliment"]},
+        )
+
+        # Verify response
+        assert result == {"status": "success", "message_id": "msg-123"}
+
+    def test_update_message_label_client_error(self, mocker):
+        """Test 4xx client error handling."""
+        client = TurnAPIClient()
+
+        # Mock 400 Bad Request
+        mock_response = mocker.Mock()
+        mock_response.status_code = 400
+        mock_response.text = "Invalid label format"
+        mocker.patch.object(client.session, "post", return_value=mock_response)
+
+        with pytest.raises(
+            TurnAPIClientError, match="Turn API client error \\(HTTP 400\\)"
+        ):
+            client.update_message_label("msg-123", "invalid-label")
+
+    def test_update_message_label_server_error(self, mocker):
+        """Test 5xx server error handling."""
+        client = TurnAPIClient()
+
+        # Mock 500 Internal Server Error
+        mock_response = mocker.Mock()
+        mock_response.status_code = 500
+        mock_response.text = "Internal server error"
+        mocker.patch.object(client.session, "post", return_value=mock_response)
+
+        with pytest.raises(
+            TurnAPIServerError, match="Turn API server error \\(HTTP 500\\)"
+        ):
+            client.update_message_label("msg-123", "label")
+
+    def test_update_message_label_request_error(self, mocker):
+        """Test general request error handling."""
+        import requests
+
+        client = TurnAPIClient()
+
+        # Mock request exception
+        mocker.patch.object(
+            client.session,
+            "post",
+            side_effect=requests.RequestException("Connection failed"),
+        )
+
+        with pytest.raises(
+            TurnAPIError, match="Turn API request error for message msg-123"
+        ):
+            client.update_message_label("msg-123", "label")
+
+    def test_client_headers(self, monkeypatch):
+        """Test that client has correct headers."""
+        monkeypatch.setenv("TURN_API_BASE_URL", "https://api.turn.io")
+        monkeypatch.setenv("TURN_API_TOKEN", "test-token-123")
+
+        client = TurnAPIClient()
+
+        headers = client.session.headers
+        assert headers["Authorization"] == "Bearer test-token-123"
+        assert headers["Accept"] == "application/vnd.v1+json"
+        assert headers["Content-Type"] == "application/json"