ai-lls-lib 2.0.0rc2__py3-none-any.whl

ai_lls_lib/payment/webhook_processor.py

@@ -0,0 +1,215 @@
+"""Stripe webhook event processing."""
+
+import json
+import logging
+from typing import Dict, Any
+
+try:
+    import stripe
+except ImportError:
+    stripe = None
+
+from .credit_manager import CreditManager
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookProcessor:
+    """Process Stripe webhook events."""
+
+    def __init__(self, webhook_secret: str, credit_manager: CreditManager):
+        """Initialize with webhook secret and credit manager."""
+        self.webhook_secret = webhook_secret
+        self.credit_manager = credit_manager
+
+    def verify_and_parse(self, payload: str, signature: str) -> Dict[str, Any]:
+        """Verify webhook signature and parse event."""
+        if not stripe:
+            raise ImportError("stripe package not installed")
+
+        try:
+            event = stripe.Webhook.construct_event(
+                payload, signature, self.webhook_secret
+            )
+            return event
+        except ValueError as e:
+            logger.error(f"Invalid webhook payload: {e}")
+            raise
+        except stripe.error.SignatureVerificationError as e:
+            logger.error(f"Invalid webhook signature: {e}")
+            raise
+
+    def process_event(self, event: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process a verified webhook event.
+        Returns response data.
+        """
+        event_type = event.get("type")
+        event_data = event.get("data", {}).get("object", {})
+
+        logger.info(f"Processing webhook event: {event_type}")
+
+        if event_type == "payment_intent.succeeded":
+            return self._handle_payment_intent_succeeded(event_data)
+
+        elif event_type == "checkout.session.completed":
+            return self._handle_checkout_completed(event_data)
+
+        elif event_type == "customer.subscription.created":
+            return self._handle_subscription_created(event_data)
+
+        elif event_type == "customer.subscription.updated":
+            return self._handle_subscription_updated(event_data)
+
+        elif event_type == "customer.subscription.deleted":
+            return self._handle_subscription_deleted(event_data)
+
+        elif event_type == "invoice.payment_succeeded":
+            return self._handle_invoice_paid(event_data)
+
+        elif event_type == "invoice.payment_failed":
+            return self._handle_invoice_failed(event_data)
+
+        elif event_type == "charge.dispute.created":
+            return self._handle_dispute_created(event_data)
+
+        else:
+            logger.info(f"Unhandled event type: {event_type}")
+            return {"message": f"Event {event_type} received but not processed"}
+
+    def _handle_checkout_completed(self, session: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle successful checkout session for credit purchase."""
+        metadata = session.get("metadata", {})
+        user_id = metadata.get("user_id")
+
+        if not user_id:
+            logger.error("No user_id in checkout session metadata")
+            return {"error": "Missing user_id"}
+
+        # Get line items to determine credits purchased
+        if session.get("mode") == "payment":
+            # One-time payment for credits
+            # In production, fetch line items from Stripe to get price metadata
+            # For now, extract from session metadata if available
+            credits = int(metadata.get("credits", 0))
+
+            if credits > 0:
+                new_balance = self.credit_manager.add_credits(user_id, credits)
+                logger.info(f"Added {credits} credits to user {user_id}, new balance: {new_balance}")
+                return {"credits_added": credits, "new_balance": new_balance}
+
+        return {"message": "Checkout processed"}
+
+    def _handle_subscription_created(self, subscription: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle new subscription creation."""
+        metadata = subscription.get("metadata", {})
+        user_id = metadata.get("user_id")
+        customer_id = subscription.get("customer")
+        subscription_id = subscription.get("id")
+        status = subscription.get("status")
+
+        if user_id:
+            self.credit_manager.set_subscription_state(
+                user_id=user_id,
+                status=status,
+                stripe_customer_id=customer_id,
+                stripe_subscription_id=subscription_id
+            )
+            logger.info(f"Created subscription {subscription_id} for user {user_id}")
+
+        return {"subscription_id": subscription_id, "status": status}
+
+    def _handle_subscription_updated(self, subscription: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle subscription updates (pause/resume/etc)."""
+        metadata = subscription.get("metadata", {})
+        user_id = metadata.get("user_id")
+        subscription_id = subscription.get("id")
+        status = subscription.get("status")
+
+        if user_id:
+            self.credit_manager.set_subscription_state(
+                user_id=user_id,
+                status=status,
+                stripe_subscription_id=subscription_id
+            )
+            logger.info(f"Updated subscription {subscription_id} status to {status}")
+
+        return {"subscription_id": subscription_id, "status": status}
+
+    def _handle_subscription_deleted(self, subscription: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle subscription cancellation."""
+        metadata = subscription.get("metadata", {})
+        user_id = metadata.get("user_id")
+        subscription_id = subscription.get("id")
+
+        if user_id:
+            self.credit_manager.set_subscription_state(
+                user_id=user_id,
+                status="cancelled",
+                stripe_subscription_id=subscription_id
+            )
+            logger.info(f"Cancelled subscription {subscription_id} for user {user_id}")
+
+        return {"subscription_id": subscription_id, "status": "cancelled"}
+
+    def _handle_invoice_paid(self, invoice: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle successful subscription payment."""
+        # For monthly subscriptions, could grant monthly credit allotment here
+        # For now, just log the payment
+        customer_id = invoice.get("customer")
+        amount = invoice.get("amount_paid", 0) / 100.0
+        logger.info(f"Invoice paid: ${amount} from customer {customer_id}")
+        return {"amount_paid": amount}
+
+    def _handle_invoice_failed(self, invoice: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle failed subscription payment."""
+        customer_id = invoice.get("customer")
+        logger.warning(f"Invoice payment failed for customer {customer_id}")
+        # Could pause subscription or send notification here
+        return {"status": "payment_failed"}
+
+    def _handle_payment_intent_succeeded(self, payment_intent: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle successful payment intent (credit purchase)."""
+        metadata = payment_intent.get("metadata", {})
+        user_id = metadata.get("user_id")
+
+        if not user_id:
+            logger.error("No user_id in payment_intent metadata")
+            return {"error": "Missing user_id"}
+
+        # Check if this is a verification charge ($1)
+        if metadata.get("type") == "verification":
+            # This was the $1 verification, credits already added in payment_setup handler
+            logger.info(f"Verification charge completed for user {user_id}")
+            return {"type": "verification", "status": "completed"}
+
+        # Get credits from metadata (set during payment creation)
+        credits = int(metadata.get("credits", 0))
+
+        if credits > 0:
+            new_balance = self.credit_manager.add_credits(user_id, credits)
+            logger.info(f"Added {credits} credits to user {user_id}, new balance: {new_balance}")
+            return {"credits_added": credits, "new_balance": new_balance}
+
+        return {"message": "Payment processed"}
+
+    def _handle_dispute_created(self, dispute: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle charge dispute (mark account as disputed)."""
+        # Get the charge and its metadata
+        charge_id = dispute.get("charge")
+
+        if not charge_id:
+            logger.error("No charge_id in dispute")
+            return {"error": "Missing charge_id"}
+
+        # In production, would fetch the charge from Stripe to get metadata
+        # For now, log the dispute for manual handling
+        amount = dispute.get("amount", 0) / 100.0
+        reason = dispute.get("reason", "unknown")
+
+        logger.warning(f"Dispute created for charge {charge_id}: ${amount}, reason: {reason}")
+
+        # TODO: Mark user account as disputed in CreditsTable
+        # This would prevent new purchases until resolved
+
+        return {"dispute_id": dispute.get("id"), "status": "created", "amount": amount}

ai_lls_lib/providers/__init__.py

@@ -0,0 +1,8 @@
+"""
+Verification providers for phone number checking
+"""
+from .base import VerificationProvider
+from .stub import StubProvider
+from .external import ExternalAPIProvider
+
+__all__ = ["VerificationProvider", "StubProvider", "ExternalAPIProvider"]

ai_lls_lib/providers/base.py

@@ -0,0 +1,28 @@
+"""
+Base protocol for verification providers
+"""
+from typing import Protocol, Tuple
+from ..core.models import LineType
+
+
+class VerificationProvider(Protocol):
+    """
+    Protocol for phone verification providers.
+    All providers must implement this interface.
+    """
+
+    def verify_phone(self, phone: str) -> Tuple[LineType, bool]:
+        """
+        Verify a phone number's line type and DNC status.
+
+        Args:
+            phone: E.164 formatted phone number
+
+        Returns:
+            Tuple of (line_type, is_on_dnc_list)
+
+        Raises:
+            ValueError: If phone format is invalid
+            Exception: For provider-specific errors
+        """
+        ...

ai_lls_lib/providers/external.py

@@ -0,0 +1,151 @@
+"""
+External API provider for production phone verification
+"""
+import os
+from typing import Tuple, Optional
+import httpx
+from aws_lambda_powertools import Logger
+from ..core.models import LineType
+
+logger = Logger()
+
+
+class ExternalAPIProvider:
+    """
+    Production provider that calls external verification APIs.
+    Uses landlineremover.com which returns both line type and DNC status in a single call.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        timeout: float = 10.0
+    ):
+        """
+        Initialize external API provider.
+
+        Args:
+            api_key: API key for landlineremover.com (if not provided, uses environment)
+            timeout: HTTP request timeout in seconds
+        """
+        # Get environment-specific API key
+        # Default to 'prod' if not specified
+        env = os.environ.get("ENVIRONMENT", "prod").upper()
+
+        # Try environment-specific key first, then fall back to provided key
+        self.api_key = (
+            api_key or
+            os.environ.get(f"{env}_LANDLINE_API_KEY") or
+            os.environ.get("PHONE_VERIFY_API_KEY", "")
+        )
+
+        if not self.api_key:
+            logger.warning(f"No API key found for environment {env}")
+
+        self.api_url = "https://app.landlineremover.com/api/check-number"
+        self.timeout = timeout
+        self.http_client = httpx.Client(timeout=timeout)
+
+    def verify_phone(self, phone: str) -> Tuple[LineType, bool]:
+        """
+        Verify phone using landlineremover.com API.
+
+        This API returns both line type and DNC status in a single call,
+        which is more efficient than making two separate API calls.
+
+        Args:
+            phone: E.164 formatted phone number
+
+        Returns:
+            Tuple of (line_type, is_on_dnc_list)
+
+        Raises:
+            httpx.HTTPError: For API communication errors
+            ValueError: For invalid responses
+        """
+        logger.debug(f"Verifying phone {phone[:6]}*** via external API")
+
+        if not self.api_key:
+            raise ValueError("API key not configured")
+
+        try:
+            # Make single API call that returns both line type and DNC status
+            # The API may redirect, so we need to follow redirects
+            response = self.http_client.get(
+                self.api_url,
+                params={
+                    "apikey": self.api_key,
+                    "number": phone
+                },
+                follow_redirects=True
+            )
+
+            # Raise for HTTP errors
+            response.raise_for_status()
+
+            # Parse response
+            json_response = response.json()
+
+            # Extract data from response wrapper
+            if "data" in json_response:
+                data = json_response["data"]
+            else:
+                data = json_response
+
+            # Map line type from API response
+            line_type = self._map_line_type(data)
+
+            # Map DNC status - API uses "DNCType" field
+            # Values can be "dnc", "clean", etc.
+            dnc_type = data.get("DNCType", data.get("dnc_type", "")).lower()
+            is_dnc = dnc_type != "clean" and dnc_type != ""
+
+            logger.debug(
+                f"Verification complete for {phone[:6]}***",
+                extra={
+                    "line_type": line_type.value,
+                    "is_dnc": is_dnc,
+                    "dnc_type": dnc_type
+                }
+            )
+
+            return line_type, is_dnc
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"API error: {e.response.status_code} - {e.response.text}")
+            raise ValueError(f"API request failed with status {e.response.status_code}")
+        except httpx.RequestError as e:
+            logger.error(f"Network error: {str(e)}")
+            raise ValueError(f"Network error during API call: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error during verification: {str(e)}")
+            raise
+
+    def _map_line_type(self, data: dict) -> LineType:
+        """
+        Map API response to LineType enum.
+
+        Args:
+            data: API response dictionary
+
+        Returns:
+            LineType enum value
+        """
+        # API uses "LineType" (capitalized) field
+        line_type_str = data.get("LineType", data.get("line_type", "")).lower()
+
+        # Map common line types
+        line_type_map = {
+            "mobile": LineType.MOBILE,
+            "landline": LineType.LANDLINE,
+            "voip": LineType.VOIP,
+            "wireless": LineType.MOBILE,  # Some APIs return "wireless" for mobile
+            "fixed": LineType.LANDLINE,    # Some APIs return "fixed" for landline
+        }
+
+        return line_type_map.get(line_type_str, LineType.UNKNOWN)
+
+    def __del__(self):
+        """Cleanup HTTP client"""
+        if hasattr(self, 'http_client'):
+            self.http_client.close()

ai_lls_lib/providers/stub.py

@@ -0,0 +1,48 @@
+"""
+Stub provider for development and testing
+"""
+from typing import Tuple
+from aws_lambda_powertools import Logger
+from ..core.models import LineType
+
+logger = Logger()
+
+
+class StubProvider:
+    """
+    Stub implementation for development and testing.
+    Uses deterministic rules based on phone number digits.
+    """
+
+    def verify_phone(self, phone: str) -> Tuple[LineType, bool]:
+        """
+        Verify using stub logic based on last digit.
+
+        Line type:
+        - Ends in 2 or 0: LANDLINE
+        - Otherwise: MOBILE
+
+        DNC status:
+        - Ends in 1 or 0: on DNC list
+        - Otherwise: not on DNC
+
+        Args:
+            phone: E.164 formatted phone number
+
+        Returns:
+            Tuple of (line_type, is_on_dnc_list)
+        """
+        logger.debug(f"Stub verification for {phone[:6]}***")
+
+        last_digit = phone[-1] if phone else '5'
+
+        # Determine line type
+        if last_digit in ['2', '0']:
+            line_type = LineType.LANDLINE
+        else:
+            line_type = LineType.MOBILE
+
+        # Determine DNC status
+        is_dnc = last_digit in ['1', '0']
+
+        return line_type, is_dnc

ai_lls_lib/testing/__init__.py

@@ -0,0 +1,3 @@
+"""
+Testing utilities and fixtures
+"""

ai_lls_lib/testing/fixtures.py

@@ -0,0 +1,104 @@
+"""
+Test fixtures and utilities for ai-lls-lib
+"""
+from datetime import datetime, timedelta, timezone
+from typing import List, Dict, Any
+from ai_lls_lib.core.models import PhoneVerification, LineType, VerificationSource
+
+# Sample phone numbers for testing
+# Using 201-555-01XX format which is designated for testing
+TEST_PHONES = {
+    "valid_mobile": "+12015550153",  # Ends in 3 - mobile, not on DNC
+    "valid_landline": "+12015550152",  # Ends in 2 - landline, not on DNC
+    "dnc_mobile": "+12015550151",  # Ends in 1 - mobile, on DNC
+    "dnc_landline": "+12015550150",  # Ends in 0 - landline, on DNC
+    "invalid": "not-a-phone",
+    "missing_country": "2015550123",
+    "international": "+442071234567",
+}
+
+def create_test_verification(
+    phone: str = TEST_PHONES["valid_mobile"],
+    line_type: LineType = LineType.MOBILE,
+    dnc: bool = False,
+    cached: bool = False,
+    source: VerificationSource = VerificationSource.API
+) -> PhoneVerification:
+    """Create a test PhoneVerification object"""
+    return PhoneVerification(
+        phone_number=phone,
+        line_type=line_type,
+        dnc=dnc,
+        cached=cached,
+        verified_at=datetime.now(timezone.utc),
+        source=source
+    )
+
+def create_test_csv_content(phones: List[str] = None) -> str:
+    """Create CSV content for testing bulk processing"""
+    if phones is None:
+        phones = [
+            TEST_PHONES["valid_mobile"],
+            TEST_PHONES["valid_landline"],
+            TEST_PHONES["dnc_mobile"],
+        ]
+
+    lines = ["name,phone,email"]
+    for i, phone in enumerate(phones):
+        lines.append(f"Test User {i},{phone},test{i}@example.com")
+
+    return "\n".join(lines)
+
+def create_dynamodb_item(phone: str, line_type: LineType = LineType.MOBILE, dnc: bool = False) -> Dict[str, Any]:
+    """Create a DynamoDB item for testing"""
+    ttl = int((datetime.now(timezone.utc) + timedelta(days=30)).timestamp())
+
+    return {
+        "phone_number": phone,
+        "line_type": line_type.value,  # Store as string in DynamoDB
+        "dnc": dnc,
+        "cached": True,
+        "verified_at": datetime.now(timezone.utc).isoformat(),
+        "source": VerificationSource.CACHE.value,  # Store as string in DynamoDB
+        "ttl": ttl
+    }
+
+def create_sqs_message(file_id: str, bucket: str, key: str, user_id: str) -> Dict[str, Any]:
+    """Create an SQS message for bulk processing"""
+    return {
+        "file_id": file_id,
+        "bucket": bucket,
+        "key": key,
+        "user_id": user_id,
+        "created_at": datetime.now(timezone.utc).isoformat()
+    }
+
+def create_api_gateway_event(
+    phone: str = None,
+    user_id: str = "test-user",
+    method: str = "GET",
+    path: str = "/verify"
+) -> Dict[str, Any]:
+    """Create an API Gateway event for Lambda testing"""
+    event = {
+        "httpMethod": method,
+        "path": path,
+        "headers": {
+            "Authorization": "Bearer test-token"
+        },
+        "requestContext": {
+            "authorizer": {
+                "lambda": {
+                    "principal_id": user_id,
+                    "claims": {
+                        "email": f"{user_id}@example.com"
+                    }
+                }
+            }
+        }
+    }
+
+    if phone:
+        event["queryStringParameters"] = {"p": phone}
+
+    return event