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

ai_lls_lib/core/models.py

@@ -0,0 +1,77 @@
+"""
+Data models for phone verification
+"""
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class LineType(str, Enum):
+    """Phone line type enumeration"""
+    MOBILE = "mobile"
+    LANDLINE = "landline"
+    VOIP = "voip"
+    UNKNOWN = "unknown"
+
+
+class VerificationSource(str, Enum):
+    """Source of verification data"""
+    API = "api"
+    CACHE = "cache"
+    BULK_IMPORT = "bulk_import"
+
+
+class JobStatus(str, Enum):
+    """Bulk job status enumeration"""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class PhoneVerification(BaseModel):
+    """Result of phone number verification"""
+    phone_number: str = Field(..., description="E.164 formatted phone number")
+    line_type: LineType = Field(
+        ..., description="Type of phone line"
+    )
+    dnc: bool = Field(..., description="Whether number is on DNC list")
+    cached: bool = Field(..., description="Whether result came from cache")
+    verified_at: datetime = Field(..., description="When verification occurred")
+    source: VerificationSource = Field(
+        ..., description="Source of verification data"
+    )
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class BulkJob(BaseModel):
+    """Bulk processing job metadata"""
+    job_id: str = Field(..., description="Unique job identifier")
+    status: JobStatus = Field(
+        ..., description="Current job status"
+    )
+
+
+class BulkJobStatus(BulkJob):
+    """Extended bulk job status with progress info"""
+    total_rows: Optional[int] = Field(None, description="Total rows to process")
+    processed_rows: Optional[int] = Field(None, description="Rows processed so far")
+    result_url: Optional[str] = Field(None, description="S3 URL of results")
+    created_at: datetime = Field(..., description="Job creation time")
+    completed_at: Optional[datetime] = Field(None, description="Job completion time")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class CacheEntry(BaseModel):
+    """DynamoDB cache entry"""
+    phone_number: str
+    line_type: str  # Stored as string in DynamoDB
+    dnc: bool
+    verified_at: str  # ISO format string
+    source: str  # Stored as string in DynamoDB
+    ttl: int  # Unix timestamp for DynamoDB TTL

ai_lls_lib/core/processor.py

@@ -0,0 +1,295 @@
+"""
+Bulk CSV processing for phone verification
+"""
+import csv
+from io import StringIO
+from typing import List, Optional, Iterator, Iterable
+from aws_lambda_powertools import Logger
+from .models import PhoneVerification
+from .verifier import PhoneVerifier
+
+logger = Logger()
+
+
+class BulkProcessor:
+    """Process CSV files for bulk phone verification"""
+
+    def __init__(self, verifier: PhoneVerifier):
+        self.verifier = verifier
+
+    def process_csv(self, csv_text: str, phone_column: str = "phone") -> List[PhoneVerification]:
+        """
+        Process CSV text content.
+        Returns list of verification results.
+        """
+        results = []
+
+        try:
+            # Use StringIO to parse CSV text
+            csv_file = StringIO(csv_text)
+            reader = csv.DictReader(csv_file)
+
+            # Find phone column (case-insensitive)
+            headers = reader.fieldnames or []
+            phone_col = self._find_phone_column(headers, phone_column)
+
+            if not phone_col:
+                raise ValueError(f"Phone column '{phone_column}' not found in CSV")
+
+            for row_num, row in enumerate(reader, start=2):  # Start at 2 (header is 1)
+                try:
+                    phone = row.get(phone_col, "").strip()
+                    if not phone:
+                        logger.warning(f"Empty phone at row {row_num}")
+                        continue
+
+                    # Verify phone
+                    result = self.verifier.verify(phone)
+                    results.append(result)
+
+                    # Log progress every 100 rows
+                    if len(results) % 100 == 0:
+                        logger.info(f"Processed {len(results)} phones")
+
+                except ValueError as e:
+                    logger.warning(f"Invalid phone at row {row_num}: {str(e)}")
+                    continue
+                except Exception as e:
+                    logger.error(f"Error processing row {row_num}: {str(e)}")
+                    continue
+
+            logger.info(f"Completed processing {len(results)} valid phones")
+
+        except Exception as e:
+            logger.error(f"CSV processing failed: {str(e)}")
+            raise
+
+        return results
+
+    def _find_phone_column(self, headers: List[str], preferred: str) -> Optional[str]:
+        """Find phone column in headers (case-insensitive)"""
+        # First try exact match
+        for header in headers:
+            if header.lower() == preferred.lower():
+                return header
+
+        # Common phone column names
+        phone_patterns = [
+            "phone", "phone_number", "phonenumber", "mobile",
+            "cell", "telephone", "tel", "number", "contact"
+        ]
+
+        for header in headers:
+            header_lower = header.lower()
+            for pattern in phone_patterns:
+                if pattern in header_lower:
+                    logger.info(f"Using column '{header}' as phone column")
+                    return header
+
+        return None
+
+    def generate_results_csv(
+        self,
+        original_csv_text: str,
+        results: List[PhoneVerification]
+    ) -> str:
+        """
+        Generate CSV with original data plus verification results.
+        Adds columns: line_type, dnc, cached
+        Returns CSV text string.
+        """
+        # Create lookup dict
+        results_map = {r.phone_number: r for r in results}
+
+        # Parse original CSV
+        input_file = StringIO(original_csv_text)
+        reader = csv.DictReader(input_file)
+        headers = reader.fieldnames or []
+
+        # Add new columns
+        output_headers = headers + ["line_type", "dnc", "cached"]
+
+        # Create output CSV in memory
+        output = StringIO()
+        writer = csv.DictWriter(output, fieldnames=output_headers)
+        writer.writeheader()
+
+        phone_col = self._find_phone_column(headers, "phone")
+
+        for row in reader:
+            phone = row.get(phone_col, "").strip()
+
+            # Try to normalize for lookup
+            try:
+                normalized = self.verifier.normalize_phone(phone)
+                if normalized in results_map:
+                    result = results_map[normalized]
+                    row["line_type"] = result.line_type.value
+                    row["dnc"] = "true" if result.dnc else "false"
+                    row["cached"] = "true" if result.cached else "false"
+                else:
+                    row["line_type"] = "unknown"
+                    row["dnc"] = ""
+                    row["cached"] = ""
+            except:
+                row["line_type"] = "invalid"
+                row["dnc"] = ""
+                row["cached"] = ""
+
+            writer.writerow(row)
+
+        # Return CSV text
+        return output.getvalue()
+
+    def process_csv_stream(
+        self,
+        lines: Iterable[str],
+        phone_column: str = "phone",
+        batch_size: int = 100
+    ) -> Iterator[List[PhoneVerification]]:
+        """
+        Process CSV lines as a stream, yielding batches of results.
+        Memory-efficient for large files.
+
+        Args:
+            lines: Iterator of CSV lines (including header)
+            phone_column: Column name containing phone numbers
+            batch_size: Number of results to accumulate before yielding
+
+        Yields:
+            Batches of PhoneVerification results
+        """
+        lines_list = list(lines)  # Need to iterate twice - once for headers, once for data
+
+        if not lines_list:
+            logger.error("Empty CSV stream")
+            return
+
+        # Parse header
+        header_line = lines_list[0]
+        reader = csv.DictReader(StringIO(header_line))
+        headers = reader.fieldnames or []
+        phone_col = self._find_phone_column(headers, phone_column)
+
+        if not phone_col:
+            raise ValueError(f"Phone column '{phone_column}' not found in CSV")
+
+        batch = []
+        row_num = 2  # Start at 2 (header is 1)
+        total_processed = 0
+
+        # Process data lines
+        for line in lines_list[1:]:
+            if not line.strip():
+                continue
+
+            try:
+                # Parse single line
+                row = next(csv.DictReader(StringIO(line), fieldnames=headers))
+                phone = row.get(phone_col, "").strip()
+
+                if not phone:
+                    logger.warning(f"Empty phone at row {row_num}")
+                    row_num += 1
+                    continue
+
+                # Verify phone
+                result = self.verifier.verify(phone)
+                batch.append(result)
+                total_processed += 1
+
+                # Yield batch when full
+                if len(batch) >= batch_size:
+                    logger.info(f"Processed batch of {len(batch)} phones (total: {total_processed})")
+                    yield batch
+                    batch = []
+
+            except ValueError as e:
+                logger.warning(f"Invalid phone at row {row_num}: {str(e)}")
+            except Exception as e:
+                logger.error(f"Error processing row {row_num}: {str(e)}")
+            finally:
+                row_num += 1
+
+        # Yield remaining results
+        if batch:
+            logger.info(f"Processed final batch of {len(batch)} phones (total: {total_processed})")
+            yield batch
+
+        logger.info(f"Stream processing completed. Total processed: {total_processed}")
+
+    def generate_results_csv_stream(
+        self,
+        original_lines: Iterable[str],
+        results_stream: Iterator[List[PhoneVerification]],
+        phone_column: str = "phone"
+    ) -> Iterator[str]:
+        """
+        Generate CSV results as a stream, line by line.
+        Memory-efficient for large files.
+
+        Args:
+            original_lines: Iterator of original CSV lines
+            results_stream: Iterator of batched PhoneVerification results
+            phone_column: Column name containing phone numbers
+
+        Yields:
+            CSV lines with verification results added
+        """
+        lines_iter = iter(original_lines)
+
+        # Read and yield modified header
+        try:
+            header_line = next(lines_iter)
+            reader = csv.DictReader(StringIO(header_line))
+            headers = reader.fieldnames or []
+
+            # Add new columns
+            output_headers = headers + ["line_type", "dnc", "cached"]
+            yield ','.join(output_headers) + '\n'
+
+            phone_col = self._find_phone_column(headers, phone_column)
+
+        except StopIteration:
+            return
+
+        # Build results lookup from stream
+        results_map = {}
+        for batch in results_stream:
+            for result in batch:
+                results_map[result.phone_number] = result
+
+        # Reset lines iterator
+        lines_iter = iter(original_lines)
+        next(lines_iter)  # Skip header
+
+        # Process and yield data lines
+        for line in lines_iter:
+            if not line.strip():
+                continue
+
+            row = next(csv.DictReader(StringIO(line), fieldnames=headers))
+            phone = row.get(phone_col, "").strip()
+
+            # Add verification results
+            try:
+                normalized = self.verifier.normalize_phone(phone)
+                if normalized in results_map:
+                    result = results_map[normalized]
+                    row["line_type"] = result.line_type.value
+                    row["dnc"] = "true" if result.dnc else "false"
+                    row["cached"] = "true" if result.cached else "false"
+                else:
+                    row["line_type"] = "unknown"
+                    row["dnc"] = ""
+                    row["cached"] = ""
+            except:
+                row["line_type"] = "invalid"
+                row["dnc"] = ""
+                row["cached"] = ""
+
+            # Write row
+            output = StringIO()
+            writer = csv.DictWriter(output, fieldnames=output_headers)
+            writer.writerow(row)
+            yield output.getvalue()

ai_lls_lib/core/verifier.py

@@ -0,0 +1,90 @@
+"""
+Phone verification logic - checks line type and DNC status
+"""
+import os
+from datetime import datetime, timezone
+from typing import Optional
+import phonenumbers
+from aws_lambda_powertools import Logger
+from .models import PhoneVerification, LineType, VerificationSource
+from .cache import DynamoDBCache
+from ..providers import VerificationProvider, StubProvider, ExternalAPIProvider
+
+logger = Logger()
+
+
+class PhoneVerifier:
+    """Verifies phone numbers for line type and DNC status"""
+
+    def __init__(self, cache: Optional[DynamoDBCache] = None, provider: Optional[VerificationProvider] = None):
+        """
+        Initialize phone verifier.
+
+        Args:
+            cache: Optional DynamoDB cache for storing results
+            provider: Verification provider (defaults to ExternalAPIProvider)
+        """
+        self.cache = cache
+        self.provider = provider or ExternalAPIProvider()
+
+    def normalize_phone(self, phone: str) -> str:
+        """Normalize phone to E.164 format"""
+        try:
+            # Parse with US as default country
+            parsed = phonenumbers.parse(phone, "US")
+            if not phonenumbers.is_valid_number(parsed):
+                raise ValueError(f"Invalid phone number: {phone}")
+
+            # Format as E.164
+            return phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
+        except Exception as e:
+            logger.error(f"Phone normalization failed: {str(e)}")
+            raise ValueError(f"Invalid phone format: {phone}")
+
+    def verify(self, phone: str) -> PhoneVerification:
+        """Verify phone number for line type and DNC status"""
+        normalized = self.normalize_phone(phone)
+
+        # Check cache first if available
+        if self.cache:
+            cached = self.cache.get(normalized)
+            if cached:
+                return cached
+
+        # Use provider to verify
+        line_type, dnc_status = self.provider.verify_phone(normalized)
+
+        result = PhoneVerification(
+            phone_number=normalized,
+            line_type=line_type,
+            dnc=dnc_status,
+            cached=False,
+            verified_at=datetime.now(timezone.utc),
+            source=VerificationSource.API
+        )
+
+        # Store in cache if available
+        if self.cache:
+            try:
+                self.cache.set(normalized, result)
+            except Exception as e:
+                logger.warning(f"Failed to cache result: {e}")
+                # Continue without caching - don't fail the verification
+
+        return result
+
+    def _check_line_type(self, phone: str) -> LineType:
+        """
+        Check line type (for backwards compatibility with CLI).
+        Delegates to provider.
+        """
+        line_type, _ = self.provider.verify_phone(phone)
+        return line_type
+
+    def _check_dnc(self, phone: str) -> bool:
+        """
+        Check DNC status (for backwards compatibility with CLI).
+        Delegates to provider.
+        """
+        _, dnc_status = self.provider.verify_phone(phone)
+        return dnc_status

ai_lls_lib/payment/__init__.py

@@ -0,0 +1,13 @@
+"""Payment module for Landline Scrubber."""
+
+from .models import Plan, PlanType, SubscriptionStatus
+from .stripe_manager import StripeManager
+from .credit_manager import CreditManager
+
+__all__ = [
+    "Plan",
+    "PlanType",
+    "SubscriptionStatus",
+    "StripeManager",
+    "CreditManager",
+]

ai_lls_lib/payment/credit_manager.py

@@ -0,0 +1,186 @@
+"""Credit balance management with DynamoDB."""
+
+import os
+from typing import Optional, Dict, Any
+from decimal import Decimal
+import logging
+from datetime import datetime
+
+try:
+    import boto3
+    from botocore.exceptions import ClientError
+except ImportError:
+    boto3 = None  # Handle gracefully for testing
+
+logger = logging.getLogger(__name__)
+
+
+class CreditManager:
+    """
+    Manages user credit balances in DynamoDB CreditsTable.
+    """
+
+    def __init__(self, table_name: Optional[str] = None):
+        """Initialize with DynamoDB table."""
+        if not boto3:
+            raise RuntimeError("boto3 is required for CreditManager")
+
+        self.dynamodb = boto3.resource("dynamodb")
+        self.table_name = table_name if table_name else os.environ['CREDITS_TABLE']
+
+        try:
+            self.table = self.dynamodb.Table(self.table_name)
+        except Exception as e:
+            logger.error(f"Failed to connect to DynamoDB table {self.table_name}: {e}")
+            self.table = None
+
+    def get_balance(self, user_id: str) -> int:
+        """Get current credit balance for a user."""
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            response = self.table.get_item(Key={"user_id": user_id})
+            if "Item" in response:
+                return int(response["Item"].get("credits", 0))
+            return 0
+        except ClientError as e:
+            logger.error(f"Error getting balance for {user_id}: {e}")
+            return 0
+
+    def add_credits(self, user_id: str, amount: int) -> int:
+        """Add credits to user balance and return new balance."""
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            response = self.table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="ADD credits :amount SET updated_at = :now",
+                ExpressionAttributeValues={
+                    ":amount": Decimal(amount),
+                    ":now": datetime.utcnow().isoformat()
+                },
+                ReturnValues="ALL_NEW"
+            )
+            return int(response["Attributes"]["credits"])
+        except ClientError as e:
+            logger.error(f"Error adding credits for {user_id}: {e}")
+            raise
+
+    def deduct_credits(self, user_id: str, amount: int) -> bool:
+        """
+        Deduct credits from user balance.
+        Returns True if successful, False if insufficient balance.
+        """
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            # Conditional update - only deduct if balance >= amount
+            self.table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="ADD credits :negative_amount SET updated_at = :now",
+                ConditionExpression="credits >= :amount",
+                ExpressionAttributeValues={
+                    ":negative_amount": Decimal(-amount),
+                    ":amount": Decimal(amount),
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            return True
+        except ClientError as e:
+            if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
+                logger.info(f"Insufficient credits for {user_id}")
+                return False
+            logger.error(f"Error deducting credits for {user_id}: {e}")
+            raise
+
+    def set_subscription_state(
+        self,
+        user_id: str,
+        status: str,
+        stripe_customer_id: Optional[str] = None,
+        stripe_subscription_id: Optional[str] = None
+    ) -> None:
+        """Update subscription state in CreditsTable."""
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            update_expr = "SET subscription_status = :status, updated_at = :now"
+            expr_values = {
+                ":status": status,
+                ":now": datetime.utcnow().isoformat()
+            }
+
+            if stripe_customer_id:
+                update_expr += ", stripe_customer_id = :customer_id"
+                expr_values[":customer_id"] = stripe_customer_id
+
+            if stripe_subscription_id:
+                update_expr += ", stripe_subscription_id = :subscription_id"
+                expr_values[":subscription_id"] = stripe_subscription_id
+
+            self.table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression=update_expr,
+                ExpressionAttributeValues=expr_values
+            )
+        except ClientError as e:
+            logger.error(f"Error updating subscription state for {user_id}: {e}")
+            raise
+
+    def get_user_payment_info(self, user_id: str) -> Dict[str, Any]:
+        """Get user's payment-related information."""
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            response = self.table.get_item(Key={"user_id": user_id})
+            if "Item" in response:
+                item = response["Item"]
+                return {
+                    "credits": int(item.get("credits", 0)),
+                    "stripe_customer_id": item.get("stripe_customer_id"),
+                    "stripe_subscription_id": item.get("stripe_subscription_id"),
+                    "subscription_status": item.get("subscription_status")
+                }
+            return {
+                "credits": 0,
+                "stripe_customer_id": None,
+                "stripe_subscription_id": None,
+                "subscription_status": None
+            }
+        except ClientError as e:
+            logger.error(f"Error getting payment info for {user_id}: {e}")
+            return {
+                "credits": 0,
+                "stripe_customer_id": None,
+                "stripe_subscription_id": None,
+                "subscription_status": None
+            }
+
+    def has_unlimited_access(self, user_id: str) -> bool:
+        """Check if user has unlimited access via active subscription."""
+        info = self.get_user_payment_info(user_id)
+        return info.get("subscription_status") == "active"
+
+    def set_stripe_customer_id(self, user_id: str, stripe_customer_id: str) -> None:
+        """Store Stripe customer ID for a user."""
+        if not self.table:
+            raise RuntimeError(f"DynamoDB table {self.table_name} not accessible")
+
+        try:
+            self.table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="SET stripe_customer_id = :customer_id, updated_at = :now",
+                ExpressionAttributeValues={
+                    ":customer_id": stripe_customer_id,
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            logger.info(f"Stored Stripe customer ID {stripe_customer_id} for user {user_id}")
+        except ClientError as e:
+            logger.error(f"Error storing Stripe customer ID for {user_id}: {e}")
+            raise