add Twilio SMS messaging functionality

Author: tayabsoomro

README.md

@@ -59,6 +59,32 @@ python setup.py
 
 This will start the application with the default configuration. The frontend will be available at http://localhost:3000 and the backend at http://localhost:5007.
 
+## Setting Up Twilio for SMS Alerts
+
+nanoCAS supports sending SMS alerts using Twilio when a sequence of interest meets the specified coverage threshold. Since nanoCAS is open-source, you’ll need to set up your own Twilio account and configure it yourself. Follow these steps to enable SMS notifications:
+
+### 1. Create a Twilio Account
+- Visit [Twilio's website](https://www.twilio.com/try-twilio) and sign up for a free account.
+- Complete the verification process by providing your email and phone number.
+
+### 2. Obtain a Twilio Phone Number
+- Log in to your Twilio Console at [https://console.twilio.com/](https://console.twilio.com/).
+- Navigate to the **"Phone Numbers"** section under **"All Products & Services"**.
+- Click **"Buy a Number"**, search for a number that supports SMS (check the capabilities), and purchase it.
+- Note down your Twilio phone number (e.g., `+12345678901`).
+
+### 3. Get Your Account SID and Auth Token
+- In the Twilio Console dashboard, locate your **"Account SID"** and **"Auth Token"** under the **"Account Info"** section.
+- These credentials are required to authenticate API requests. Keep them secure.
+
+### 4. Configure the `.env` File
+- In the root directory of your nanoCAS project, create or edit the `.env` file to include the following Twilio configuration:
+  ```plaintext
+  TWILIO_ACCOUNT_SID=your_account_sid
+  TWILIO_AUTH_TOKEN=your_auth_token
+  TWILIO_PHONE_NUMBER=your_twilio_phone_number
+  ALERT_RECIPIENT_PHONE=recipient_phone_number
+
 ### Manual Installation
 
 For environments where Docker is not available or for development purposes:

frontend/.tool-versions

@@ -0,0 +1 @@
+nodejs 16.20.2

server/app/main/utils/FileHandler.py

@@ -11,6 +11,7 @@
 from app import socketio
 from .LinuxNotification import LinuxNotification
 from .email import send_email
+from .sms import send_sms
 
 logger = logging.getLogger('nanocas')
 
@@ -186,6 +187,7 @@ def calculate_and_record_coverage(self):
             logger.error(f"Error calculating coverage: {e}")
 
     def check_breadth_alert(self, ref: str, breadth: float):
+        """Check if breadth exceeds threshold and send alerts."""
         print(f"Checking breadth alert for {ref} with breadth {breadth:.2f}%")
         alertinfo_cfg_file = os.path.join(self.app_loc, 'alertinfo.cfg')
         try:
@@ -206,16 +208,20 @@ def check_breadth_alert(self, ref: str, breadth: float):
                         logger.critical(alert_str)
                         if device:
                             LinuxNotification.send_notification(device, alert_str)
+                        # Send alerts if configured
                         if "alertNotifConfig" in alertinfo_cfg_data:
                             print("Sending email")
                             email_config = alertinfo_cfg_data['alertNotifConfig']
                             subject = "nanoCAS Alert"
                             body = alert_str
                             send_email(subject, body, email_config)
+                        # Send SMS via Twilio if configured in .env
+                        if os.getenv('TWILIO_ACCOUNT_SID'):
+                            print("Sending SMS")
+                            send_sms(alert_str)
                         else:
-                            print("No email config found")
-                            logger.error("No email config found in alertinfo.cfg")
-                            
+                            print("Twilio not configured; skipping SMS")
+                            logger.debug("Twilio not configured in .env; SMS skipped")
                     # Update current_breadth after checking
                     if breadth > current_breadth:
                         query["current_breadth"] = breadth

server/app/main/utils/__init__.py

@@ -1 +1,2 @@
-from .LinuxNotification import LinuxNotification
+from .LinuxNotification import LinuxNotification
+from .sms import send_sms

server/app/main/utils/sms.py

@@ -0,0 +1,33 @@
+import os
+from twilio.rest import Client
+from twilio.base.exceptions import TwilioRestException
+import logging
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+logger = logging.getLogger('nanocas')
+
+def send_sms(body):
+    """Send an SMS alert using Twilio."""
+    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
+    auth_token = os.getenv('TWILIO_AUTH_TOKEN')
+    twilio_phone = os.getenv('TWILIO_PHONE_NUMBER')
+    recipient_phone = os.getenv('ALERT_RECIPIENT_PHONE')
+
+    # Check if all required Twilio credentials are provided
+    if not all([account_sid, auth_token, twilio_phone, recipient_phone]):
+        logger.error("Twilio configuration missing in .env file. SMS not sent.")
+        return
+
+    try:
+        client = Client(account_sid, auth_token)
+        message = client.messages.create(
+            body=body,
+            from_=twilio_phone,
+            to=recipient_phone
+        )
+        logger.info(f"SMS sent successfully: {message.sid}")
+    except TwilioRestException as e:
+        logger.error(f"Failed to send SMS: {e}")

server/requirements.txt

@@ -50,4 +50,5 @@ watchdog==6.0.0
 wcwidth==0.2.13
 Werkzeug==3.1.3
 wheel==0.45.1
-wsproto==1.2.0
+wsproto==1.2.0
+load-dotenv==0.1.0

setup.sh

@@ -143,6 +143,16 @@ EOF
         echo "ENABLE_DISTRIBUTED=false" >> .env
     fi
 
+    # Optional Twilio configuration
+    if [ -n "$TWILIO_ACCOUNT_SID" ] && [ -n "$TWILIO_AUTH_TOKEN" ] && [ -n "$TWILIO_PHONE_NUMBER" ] && [ -n "$ALERT_RECIPIENT_PHONE" ]; then
+        cat >> .env << EOF
+TWILIO_ACCOUNT_SID=$TWILIO_ACCOUNT_SID
+TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN
+TWILIO_PHONE_NUMBER=$TWILIO_PHONE_NUMBER
+ALERT_RECIPIENT_PHONE=$ALERT_RECIPIENT_PHONE
+EOF
+    fi
+
     # Start the containers
     if [ "$ENV" == "production" ]; then
         docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
@@ -177,6 +187,16 @@ EOF
     else
         echo "ENABLE_DISTRIBUTED=false" >> .env
     fi
+
+    # Optional Twilio configuration
+    if [ -n "$TWILIO_ACCOUNT_SID" ] && [ -n "$TWILIO_AUTH_TOKEN" ] && [ -n "$TWILIO_PHONE_NUMBER" ] && [ -n "$ALERT_RECIPIENT_PHONE" ]; then
+        cat >> .env << EOF
+TWILIO_ACCOUNT_SID=$TWILIO_ACCOUNT_SID
+TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN
+TWILIO_PHONE_NUMBER=$TWILIO_PHONE_NUMBER
+ALERT_RECIPIENT_PHONE=$ALERT_RECIPIENT_PHONE
+EOF
+    fi
 
     echo "Local setup complete."
     echo "To start the backend server: cd server && python nanocas.py"