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

ai_lls_lib/__init__.py

@@ -0,0 +1,32 @@
+"""
+AI LLS Library - Core business logic for Landline Scrubber.
+
+This library provides phone verification and DNC checking capabilities.
+
+Version 2.0.0 establishes clean semantic versioning baseline.
+All version management now controlled by Python Semantic Release.
+"""
+from ai_lls_lib.core.models import (
+    PhoneVerification,
+    BulkJob,
+    BulkJobStatus,
+    LineType,
+    VerificationSource,
+    JobStatus
+)
+from ai_lls_lib.core.verifier import PhoneVerifier
+from ai_lls_lib.core.processor import BulkProcessor
+from ai_lls_lib.core.cache import DynamoDBCache
+
+__version__ = "2.0.0-rc.2"
+__all__ = [
+    "PhoneVerification",
+    "BulkJob",
+    "BulkJobStatus",
+    "LineType",
+    "VerificationSource",
+    "JobStatus",
+    "PhoneVerifier",
+    "BulkProcessor",
+    "DynamoDBCache",
+]

ai_lls_lib/auth/__init__.py

@@ -0,0 +1,4 @@
+"""Auth module for handling authentication and authorization."""
+from .context_parser import get_email_from_event, get_user_from_event
+
+__all__ = ["get_user_from_event", "get_email_from_event"]

ai_lls_lib/auth/context_parser.py

@@ -0,0 +1,68 @@
+"""Auth context parser for HTTP API v2.0 events."""
+from typing import Any, Dict, Optional
+
+
+def get_user_from_event(event: Dict[str, Any]) -> Optional[str]:
+    """
+    Extract user ID from HTTP API v2.0 event with all possible paths.
+    Handles both JWT and API key authentication contexts.
+
+    This function handles the complexities of AWS API Gateway authorizer contexts,
+    especially when EnableSimpleResponses is set to false, which wraps the
+    context in a 'lambda' key.
+
+    Args:
+        event: The Lambda event from API Gateway HTTP API v2.0
+
+    Returns:
+        User ID string if found, None otherwise
+    """
+    request_context = event.get("requestContext", {})
+    auth = request_context.get("authorizer", {})
+
+    # Handle lambda-wrapped context (EnableSimpleResponses: false)
+    # When EnableSimpleResponses is false, the authorizer context is wrapped
+    lam_ctx = auth.get("lambda", auth) if isinstance(auth.get("lambda"), dict) else auth
+
+    # Try all possible paths for user_id in priority order
+    user_id = (
+        # Lambda authorizer paths (most common with current setup)
+        lam_ctx.get("principal_id") or
+        lam_ctx.get("principalId") or
+        lam_ctx.get("sub") or
+        lam_ctx.get("user_id") or
+        # JWT paths (when using JWT authorizer directly)
+        auth.get("jwt", {}).get("claims", {}).get("sub") or
+        # Direct auth paths (fallback)
+        auth.get("principal_id") or
+        auth.get("principalId") or
+        auth.get("sub")
+    )
+
+    return user_id
+
+
+def get_email_from_event(event: Dict[str, Any]) -> Optional[str]:
+    """
+    Extract email from HTTP API v2.0 event.
+
+    Args:
+        event: The Lambda event from API Gateway HTTP API v2.0
+
+    Returns:
+        Email string if found, None otherwise
+    """
+    request_context = event.get("requestContext", {})
+    auth = request_context.get("authorizer", {})
+
+    # Handle lambda-wrapped context
+    lam_ctx = auth.get("lambda", auth) if isinstance(auth.get("lambda"), dict) else auth
+
+    # Try to get email from various locations
+    email = (
+        lam_ctx.get("email") or
+        auth.get("jwt", {}).get("claims", {}).get("email") or
+        auth.get("email")
+    )
+
+    return email

ai_lls_lib/cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+Landline Scrubber CLI - Infrastructure-aware administrative tools
+"""

ai_lls_lib/cli/__main__.py

@@ -0,0 +1,63 @@
+"""
+Landline Scrubber CLI entry point
+"""
+import click
+import sys
+import os
+from pathlib import Path
+from ai_lls_lib.cli.commands import verify, cache, admin, test_stack, stripe, monitor
+from ai_lls_lib.cli.env_loader import load_env_file
+
+def load_env_files(verbose=False):
+    """Load .env files from ~/.lls and current directory"""
+    # Load from ~/.lls/.env
+    home_env = Path.home() / '.lls' / '.env'
+    if home_env.exists():
+        env_vars = load_env_file(home_env)
+        for key, value in env_vars.items():
+            if key not in os.environ:  # Don't override existing env vars
+                os.environ[key] = value
+        if env_vars and verbose:
+            click.echo(f"Loaded {len(env_vars)} variables from {home_env}", err=True)
+
+    # Load from current directory .env
+    local_env = Path('.env')
+    if local_env.exists():
+        env_vars = load_env_file(local_env)
+        for key, value in env_vars.items():
+            if key not in os.environ:  # Don't override existing env vars
+                os.environ[key] = value
+        if env_vars and verbose:
+            click.echo(f"Loaded {len(env_vars)} variables from {local_env}", err=True)
+
+    # Set default environment to 'prod' if not set
+    if 'ENVIRONMENT' not in os.environ:
+        os.environ['ENVIRONMENT'] = 'prod'
+        if verbose:
+            click.echo(f"Set default ENVIRONMENT=prod", err=True)
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="ai-lls")
+def cli():
+    """Landline Scrubber CLI - Administrative and debugging tools"""
+    # Load environment files at startup
+    load_env_files()
+
+# Register command groups
+cli.add_command(verify.verify_group)
+cli.add_command(cache.cache_group)
+cli.add_command(admin.admin_group)
+cli.add_command(test_stack.test_stack_group)
+cli.add_command(stripe.stripe_group)
+cli.add_command(monitor.monitor_group)
+
+def main():
+    """Main entry point"""
+    try:
+        cli()
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

ai_lls_lib/cli/aws_client.py

@@ -0,0 +1,123 @@
+"""
+AWS client utilities for CLI operations
+"""
+import os
+import boto3
+from typing import Optional, Any, Dict
+from botocore.exceptions import ClientError
+import click
+
+class AWSClient:
+    """Wrapper for AWS operations with proper error handling"""
+
+    def __init__(self, region: Optional[str] = None, profile: Optional[str] = None):
+        """Initialize AWS clients"""
+        self.region = region or os.environ.get("AWS_REGION", "us-east-1")
+        self.profile = profile
+
+        # Create session
+        if profile:
+            self.session = boto3.Session(profile_name=profile, region_name=self.region)
+        else:
+            self.session = boto3.Session(region_name=self.region)
+
+        # Lazy-load clients
+        self._dynamodb = None
+        self._s3 = None
+        self._sqs = None
+        self._secretsmanager = None
+        self._cloudformation = None
+        self._logs = None
+
+    @property
+    def dynamodb(self):
+        """Get DynamoDB client"""
+        if not self._dynamodb:
+            self._dynamodb = self.session.resource('dynamodb')
+        return self._dynamodb
+
+    @property
+    def s3(self):
+        """Get S3 client"""
+        if not self._s3:
+            self._s3 = self.session.client('s3')
+        return self._s3
+
+    @property
+    def sqs(self):
+        """Get SQS client"""
+        if not self._sqs:
+            self._sqs = self.session.client('sqs')
+        return self._sqs
+
+    @property
+    def secretsmanager(self):
+        """Get Secrets Manager client"""
+        if not self._secretsmanager:
+            self._secretsmanager = self.session.client('secretsmanager')
+        return self._secretsmanager
+
+    @property
+    def cloudformation(self):
+        """Get CloudFormation client"""
+        if not self._cloudformation:
+            self._cloudformation = self.session.client('cloudformation')
+        return self._cloudformation
+
+    @property
+    def logs(self):
+        """Get CloudWatch Logs client"""
+        if not self._logs:
+            self._logs = self.session.client('logs')
+        return self._logs
+
+    def get_stack_outputs(self, stack_name: str) -> Dict[str, str]:
+        """Get CloudFormation stack outputs"""
+        try:
+            response = self.cloudformation.describe_stacks(StackName=stack_name)
+            stack = response['Stacks'][0]
+            outputs = {}
+            for output in stack.get('Outputs', []):
+                outputs[output['OutputKey']] = output['OutputValue']
+            return outputs
+        except ClientError as e:
+            if e.response['Error']['Code'] == 'ValidationError':
+                raise click.ClickException(f"Stack '{stack_name}' not found")
+            raise
+
+    def get_table_name(self, stack_name: str, logical_name: str) -> str:
+        """Get actual table name from stack"""
+        try:
+            response = self.cloudformation.describe_stack_resource(
+                StackName=stack_name,
+                LogicalResourceId=logical_name
+            )
+            return response['StackResourceDetail']['PhysicalResourceId']
+        except ClientError:
+            # Fallback to conventional naming
+            return f"{stack_name}-{logical_name.lower()}"
+
+    def scan_table(self, table_name: str, limit: int = 100) -> list:
+        """Scan DynamoDB table"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            response = table.scan(Limit=limit)
+            return response.get('Items', [])
+        except ClientError as e:
+            raise click.ClickException(f"Error scanning table: {e}")
+
+    def put_item(self, table_name: str, item: dict) -> None:
+        """Put item to DynamoDB"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            table.put_item(Item=item)
+        except ClientError as e:
+            raise click.ClickException(f"Error putting item: {e}")
+
+    def delete_item(self, table_name: str, key: dict) -> None:
+        """Delete item from DynamoDB"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            table.delete_item(Key=key)
+        except ClientError as e:
+            raise click.ClickException(f"Error deleting item: {e}")

ai_lls_lib/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""
+CLI command modules
+"""

ai_lls_lib/cli/commands/admin.py

@@ -0,0 +1,174 @@
+"""
+Administrative commands for user and credit management
+"""
+import click
+import json
+from datetime import datetime
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="admin")
+def admin_group():
+    """Administrative commands"""
+    pass
+
+@admin_group.command(name="user-credits")
+@click.argument("user_id")
+@click.option("--add", type=int, help="Add credits")
+@click.option("--set", "set_credits", type=int, help="Set credits to specific value")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def user_credits(user_id, add, set_credits, stack, profile, region):
+    """Manage user credits"""
+    aws = AWSClient(region=region, profile=profile)
+    credits_table = aws.get_table_name(stack, "CreditsTable")
+
+    try:
+        table = aws.dynamodb.Table(credits_table)
+
+        # Get current credits
+        response = table.get_item(Key={"user_id": user_id})
+        current = response.get('Item', {}).get('credits', 0)
+
+        click.echo(f"User {user_id} - Current credits: {current}")
+
+        if add:
+            new_credits = current + add
+            table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="SET credits = :val, updated_at = :now",
+                ExpressionAttributeValues={
+                    ":val": new_credits,
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            click.echo(f"Added {add} credits. New balance: {new_credits}")
+
+        elif set_credits is not None:
+            table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="SET credits = :val, updated_at = :now",
+                ExpressionAttributeValues={
+                    ":val": set_credits,
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            click.echo(f"Set credits to {set_credits}")
+
+    except Exception as e:
+        click.echo(f"Error managing credits: {e}", err=True)
+
+@admin_group.command(name="api-keys")
+@click.option("--user", help="Filter by user ID")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def list_api_keys(user, stack, profile, region):
+    """List API keys"""
+    aws = AWSClient(region=region, profile=profile)
+    keys_table = aws.get_table_name(stack, "ApiKeysTable")
+
+    try:
+        if user:
+            # Query by user using GSI
+            table = aws.dynamodb.Table(keys_table)
+            response = table.query(
+                IndexName='gsi_user',
+                KeyConditionExpression='user_id = :uid',
+                ExpressionAttributeValues={':uid': user}
+            )
+            items = response.get('Items', [])
+        else:
+            # Scan all
+            items = aws.scan_table(keys_table)
+
+        if not items:
+            click.echo("No API keys found")
+            return
+
+        click.echo(f"\nAPI Keys ({len(items)} total):")
+        click.echo("=" * 60)
+
+        for item in items:
+            click.echo(f"Key ID: {item.get('api_key_id', 'N/A')}")
+            click.echo(f"User: {item.get('user_id', 'N/A')}")
+            click.echo(f"Created: {item.get('created_at', 'N/A')}")
+            click.echo(f"Last Used: {item.get('last_used', 'Never')}")
+            click.echo("-" * 60)
+
+    except Exception as e:
+        click.echo(f"Error listing API keys: {e}", err=True)
+
+@admin_group.command(name="queue-stats")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def queue_stats(stack, profile, region):
+    """Show SQS queue statistics"""
+    aws = AWSClient(region=region, profile=profile)
+
+    try:
+        # Get queue URLs from stack
+        outputs = aws.get_stack_outputs(stack)
+
+        # Find queue URLs or construct them
+        queue_name = f"{stack}-bulk-processing"
+        dlq_name = f"{stack}-bulk-processing-dlq"
+
+        # Get queue attributes
+        queues = [
+            ("Processing Queue", queue_name),
+            ("Dead Letter Queue", dlq_name)
+        ]
+
+        for display_name, queue in queues:
+            try:
+                response = aws.sqs.get_queue_url(QueueName=queue)
+                queue_url = response['QueueUrl']
+
+                attrs = aws.sqs.get_queue_attributes(
+                    QueueUrl=queue_url,
+                    AttributeNames=['All']
+                )['Attributes']
+
+                click.echo(f"\n{display_name}:")
+                click.echo(f"  Messages Available: {attrs.get('ApproximateNumberOfMessages', 0)}")
+                click.echo(f"  Messages In Flight: {attrs.get('ApproximateNumberOfMessagesNotVisible', 0)}")
+                click.echo(f"  Messages Delayed: {attrs.get('ApproximateNumberOfMessagesDelayed', 0)}")
+
+            except aws.sqs.exceptions.QueueDoesNotExist:
+                click.echo(f"\n{display_name}: Not found")
+
+    except Exception as e:
+        click.echo(f"Error getting queue stats: {e}", err=True)
+
+@admin_group.command(name="secrets")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--show", is_flag=True, help="Show secret values (CAREFUL!)")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def manage_secrets(stack, show, profile, region):
+    """Manage secrets"""
+    aws = AWSClient(region=region, profile=profile)
+    secret_name = f"{stack}-secrets"
+
+    try:
+        response = aws.secretsmanager.describe_secret(SecretId=secret_name)
+        click.echo(f"\nSecret: {secret_name}")
+        click.echo(f"ARN: {response['ARN']}")
+        click.echo(f"Last Updated: {response.get('LastChangedDate', 'N/A')}")
+
+        if show and click.confirm("Show secret values? This will display sensitive data!"):
+            secret_value = aws.secretsmanager.get_secret_value(SecretId=secret_name)
+            secrets = json.loads(secret_value['SecretString'])
+
+            click.echo("\nSecret Values:")
+            for key, value in secrets.items():
+                # Mask most of the value
+                masked = value[:4] + "*" * (len(value) - 8) + value[-4:] if len(value) > 8 else "*" * len(value)
+                click.echo(f"  {key}: {masked}")
+
+    except aws.secretsmanager.exceptions.ResourceNotFoundException:
+        click.echo(f"Secret '{secret_name}' not found")
+    except Exception as e:
+        click.echo(f"Error managing secrets: {e}", err=True)

ai_lls_lib/cli/commands/cache.py

@@ -0,0 +1,142 @@
+"""
+Cache management commands
+"""
+import click
+import json
+from datetime import datetime, timedelta
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="cache")
+def cache_group():
+    """Cache management commands"""
+    pass
+
+@cache_group.command(name="stats")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def cache_stats(stack, profile, region):
+    """Show cache statistics"""
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    try:
+        # Get table description for item count
+        table = aws.dynamodb.Table(cache_table)
+        desc = table.meta.client.describe_table(TableName=cache_table)
+
+        click.echo(f"\nCache Table: {cache_table}")
+        click.echo("=" * 50)
+        click.echo(f"Item Count: {desc['Table']['ItemCount']:,}")
+        click.echo(f"Table Size: {desc['Table']['TableSizeBytes']:,} bytes")
+        click.echo(f"Status: {desc['Table']['TableStatus']}")
+
+        # Sample some items to show age distribution
+        items = aws.scan_table(cache_table, limit=100)
+        if items:
+            now = datetime.utcnow()
+            ages = []
+            for item in items:
+                if 'verified_at' in item:
+                    verified = datetime.fromisoformat(item['verified_at'].replace('Z', '+00:00'))
+                    age = (now - verified.replace(tzinfo=None)).days
+                    ages.append(age)
+
+            if ages:
+                click.echo(f"\nCache Age (sample of {len(ages)} items):")
+                click.echo(f"  Newest: {min(ages)} days")
+                click.echo(f"  Oldest: {max(ages)} days")
+                click.echo(f"  Average: {sum(ages)/len(ages):.1f} days")
+
+    except Exception as e:
+        click.echo(f"Error getting cache stats: {e}", err=True)
+
+@cache_group.command(name="get")
+@click.argument("phone_number")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def cache_get(phone_number, stack, profile, region):
+    """Get cached entry for a phone number"""
+    from ai_lls_lib.core.verifier import PhoneVerifier
+    from ai_lls_lib.core.cache import DynamoDBCache
+
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    # Normalize phone first
+    verifier = PhoneVerifier(cache=DynamoDBCache(table_name=cache_table))
+    try:
+        normalized = verifier.normalize_phone(phone_number)
+    except ValueError as e:
+        click.echo(f"Invalid phone: {e}", err=True)
+        return
+
+    # Get from cache
+    cache = DynamoDBCache(table_name=cache_table)
+    result = cache.get(normalized)
+
+    if result:
+        click.echo(f"\nCached entry for {normalized}:")
+        click.echo(json.dumps(result.dict() if hasattr(result, 'dict') else result, indent=2, default=str))
+    else:
+        click.echo(f"No cache entry found for {normalized}")
+
+@cache_group.command(name="invalidate")
+@click.argument("phone_number")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+@click.confirmation_option(prompt="Are you sure you want to invalidate this cache entry?")
+def cache_invalidate(phone_number, stack, profile, region):
+    """Invalidate cached entry for a phone number"""
+    from ai_lls_lib.core.verifier import PhoneVerifier
+    from ai_lls_lib.core.cache import DynamoDBCache
+
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    # Normalize phone
+    verifier = PhoneVerifier(cache=DynamoDBCache(table_name=cache_table))
+    try:
+        normalized = verifier.normalize_phone(phone_number)
+    except ValueError as e:
+        click.echo(f"Invalid phone: {e}", err=True)
+        return
+
+    # Delete from cache
+    try:
+        aws.delete_item(cache_table, {"phone_number": normalized})
+        click.echo(f"Cache entry invalidated for {normalized}")
+    except Exception as e:
+        click.echo(f"Error invalidating cache: {e}", err=True)
+
+@cache_group.command(name="clear")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--older-than", type=int, help="Clear entries older than N days")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+@click.confirmation_option(prompt="This will clear cache entries. Continue?")
+def cache_clear(stack, older_than, profile, region):
+    """Clear cache entries"""
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    if older_than:
+        click.echo(f"Clearing entries older than {older_than} days...")
+        cutoff = datetime.utcnow() - timedelta(days=older_than)
+
+        # Scan and delete old entries
+        items = aws.scan_table(cache_table, limit=1000)
+        deleted = 0
+
+        for item in items:
+            if 'verified_at' in item:
+                verified = datetime.fromisoformat(item['verified_at'].replace('Z', '+00:00'))
+                if verified.replace(tzinfo=None) < cutoff:
+                    aws.delete_item(cache_table, {"phone_number": item['phone_number']})
+                    deleted += 1
+
+        click.echo(f"Deleted {deleted} entries older than {older_than} days")
+    else:
+        click.echo("Full cache clear not implemented for safety. Use --older-than option.")