Villa SMS Service - Developer Guide

import boto3
import json

# Initialize Lambda client
lambda_client = boto3.client('lambda', region_name='ap-southeast-1')

# Send SMS
response = lambda_client.invoke(
    FunctionName='villa-sms-dev',  # or 'villa-sms-prod'
    InvocationType='RequestResponse',
    Payload=json.dumps({
        'phone': '+66812345678',
        'message': 'Your verification code is: 123456'
    })
)

# Parse response
result = json.loads(response['Payload'].read())

if result['success']:
    print('SMS sent successfully!')
else:
    print(f"Failed: {result['error']} - {result['message']}")

response = lambda_client.invoke(
    FunctionName='villa-sms-prod',
    InvocationType='Event',  # Async - returns immediately
    Payload=json.dumps({
        'phone': '+66812345678',
        'message': 'Your order has been shipped!'
    })
)
# Returns 202 status if queued successfully

{
    "success": true,
    "message": "SMS sent successfully",
    "rateLimited": false
}

{
    "success": false,
    "error": "RATE_LIMITED",
    "message": "Please wait 1 minute before requesting another code.",
    "rateLimited": true,
    "retryAfterSeconds": 45
}

{
    "username": "your-clicksend-username",
    "api_key": "your-clicksend-api-key"
}

aws secretsmanager put-secret-value \
    --secret-id villa-sms/clicksend-prod \
    --secret-string '{"username": "new-user", "api_key": "new-key"}'

{
    "success": false,
    "error": "RATE_LIMITED",
    "message": "Please wait 5 minutes before requesting another code.",
    "rateLimited": true,
    "retryAfterSeconds": 287
}

response = lambda_client.invoke(
    FunctionName='villa-sms-prod',
    Payload=json.dumps({
        'phone': '+66812345678',
        'message': 'Your order has been shipped!',
        'skipRateLimit': True  # Use with caution!
    })
)

Environment:
  Variables:
    BLOCKED_COUNTRY_CODES: "228,996,992,998"  # Custom list

sam deploy --parameter-overrides BlockedCountryCodes="228,996,992,880"

import boto3
import json
from botocore.exceptions import ClientError

def send_sms(phone: str, message: str) -> dict:
    lambda_client = boto3.client('lambda')

    try:
        response = lambda_client.invoke(
            FunctionName='villa-sms-prod',
            InvocationType='RequestResponse',
            Payload=json.dumps({
                'phone': phone,
                'message': message
            })
        )

        result = json.loads(response['Payload'].read())

        if result['success']:
            return {'sent': True}

        # Handle specific errors
        error = result.get('error')

        if error == 'RATE_LIMITED':
            retry_after = result.get('retryAfterSeconds', 60)
            return {'sent': False, 'retry_after': retry_after}

        if error == 'INVALID_PHONE':
            return {'sent': False, 'invalid_phone': True, 'reason': result['message']}

        if error == 'BLOCKED_COUNTRY':
            return {'sent': False, 'blocked': True}

        # Generic failure
        return {'sent': False, 'error': result['message']}

    except ClientError as e:
        # Lambda invocation failed
        return {'sent': False, 'error': str(e)}

import time

def send_with_retry(phone: str, message: str, max_retries: int = 3) -> bool:
    for attempt in range(max_retries):
        result = send_sms(phone, message)

        if result.get('sent'):
            return True

        if result.get('invalid_phone') or result.get('blocked'):
            # Don't retry for permanent failures
            return False

        if result.get('retry_after'):
            # Rate limited - respect the cooldown
            time.sleep(result['retry_after'])
            continue

        # Exponential backoff for other failures
        time.sleep(2 ** attempt)

    return False

# Build the application
sam build

# Deploy (first time - guided)
sam deploy --guided

# Deploy (subsequent times)
sam deploy

# Deploy to specific environment
sam deploy --parameter-overrides Environment=prod

# Get the secret ARN from stack outputs
SECRET_ARN=$(aws cloudformation describe-stacks \
    --stack-name villa-sms \
    --query 'Stacks[0].Outputs[?OutputKey==`ClickSendSecretArn`].OutputValue' \
    --output text)

# Update with real credentials
aws secretsmanager put-secret-value \
    --secret-id $SECRET_ARN \
    --secret-string '{"username": "your-username", "api_key": "your-api-key"}'

# Start local DynamoDB
docker run -d -p 8000:8000 amazon/dynamodb-local

# Create test table
aws dynamodb create-table \
    --endpoint-url http://localhost:8000 \
    --table-name villa-sms-rate-limit-dev \
    --attribute-definitions AttributeName=pk,AttributeType=S \
    --key-schema AttributeName=pk,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

# Invoke locally (requires SAM CLI)
sam local invoke VillaSmsFunction -e events/send_sms.json

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::394922924679:role/villa-sms-github-actions
    aws-region: ap-southeast-1

gh workflow run deploy.yml -f environment=prod

{
    "level": "INFO",
    "message": "SMS sent via ClickSend",
    "phone_hash": 1234,
    "message_id": "abc123"
}

aws cloudwatch put-dashboard \
    --dashboard-name villa-sms-monitoring \
    --dashboard-body file://dashboards/villa-sms.json

import logging
logger = logging.getLogger()
logger.setLevel(logging.DEBUG)