ai-lls-lib 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

ai_lls_lib/payment/webhook_processor.py

@@ -0,0 +1,163 @@
+"""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 == "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)
+
+        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"}

ai_lls_lib/providers/__init__.py

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

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,87 @@
+"""
+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.
+    """
+
+    def __init__(
+        self,
+        phone_api_key: Optional[str] = None,
+        dnc_api_key: Optional[str] = None,
+        timeout: float = 10.0
+    ):
+        """
+        Initialize external API provider.
+
+        Args:
+            phone_api_key: API key for phone line type verification
+            dnc_api_key: API key for DNC list checking
+            timeout: HTTP request timeout in seconds
+        """
+        self.phone_api_key = phone_api_key or os.environ.get("PHONE_VERIFY_API_KEY", "")
+        self.dnc_api_key = dnc_api_key or os.environ.get("DNC_API_KEY", "")
+        self.http_client = httpx.Client(timeout=timeout)
+
+    def verify_phone(self, phone: str) -> Tuple[LineType, bool]:
+        """
+        Verify phone using external APIs.
+
+        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
+        """
+        line_type = self._check_line_type(phone)
+        is_dnc = self._check_dnc(phone)
+        return line_type, is_dnc
+
+    def _check_line_type(self, phone: str) -> LineType:
+        """
+        Check line type via external API.
+
+        TODO: Implement actual API call
+        - Use self.phone_api_key for authentication
+        - Parse API response
+        - Map to LineType enum
+        """
+        logger.info(f"External line type check for {phone[:6]}***")
+
+        # Placeholder implementation
+        # In production, this would make an actual API call
+        raise NotImplementedError("External line type API not yet configured")
+
+    def _check_dnc(self, phone: str) -> bool:
+        """
+        Check DNC status via external API.
+
+        TODO: Implement actual API call
+        - Use self.dnc_api_key for authentication
+        - Parse API response
+        - Return boolean status
+        """
+        logger.info(f"External DNC check for {phone[:6]}***")
+
+        # Placeholder implementation
+        # In production, this would make an actual API call
+        raise NotImplementedError("External DNC API not yet configured")
+
+    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.info(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-1.0.0.dist-info → ai_lls_lib-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ai-lls-lib
-Version: 1.0.0
+Version: 1.2.0
 Summary: Landline Scrubber core library - phone verification and DNC checking
 Author: LandlineScrubber Team
 Requires-Python: >=3.12,<4.0
@@ -14,12 +14,28 @@ Requires-Dist: httpx (>=0.25.0,<0.26.0)
 Requires-Dist: phonenumbers (>=8.13.0,<9.0.0)
 Requires-Dist: pydantic (>=2.5.0,<3.0.0)
 Requires-Dist: rich (>=14.0,<15.0)
+Requires-Dist: stripe (>=12.5.1,<13.0.0)
 Description-Content-Type: text/markdown
 
 # AI LLS Library
 
 Core business logic library and CLI tools for Landline Scrubber - phone verification and DNC checking.
 
+## Version 2.1.0 - Streaming & Provider Architecture
+
+New features:
+- **Streaming support** for large CSV files to reduce memory usage
+- **Provider architecture** for clean separation of verification logic
+- **Contract tests** ensuring all providers behave consistently
+
+## Version 2.0.0 - Breaking Changes
+
+This is a greenfield rewrite with no backwards compatibility:
+- All file-based CSV processing replaced with text-based methods
+- Removed `_sync` suffix from all methods (everything is sync)
+- `process_csv_sync(file_path)` → `process_csv(csv_text)`
+- `generate_results_csv(...)` now returns CSV string instead of writing to file
+
 ## Features
 
 - Phone number normalization (E.164 format)
@@ -50,7 +66,7 @@ from ai_lls_lib import PhoneVerifier, DynamoDBCache
 cache = DynamoDBCache(table_name="phone-cache")
 verifier = PhoneVerifier(cache)
 
-result = verifier.verify_sync("+15551234567")
+result = verifier.verify("+15551234567")
 print(f"Line type: {result.line_type}")
 print(f"DNC: {result.dnc}")
 print(f"From cache: {result.cached}")
@@ -65,12 +81,49 @@ cache = DynamoDBCache(table_name="phone-cache")
 verifier = PhoneVerifier(cache)
 processor = BulkProcessor(verifier)
 
-results = processor.process_csv_sync("/path/to/phones.csv")
-processor.generate_results_csv(
-    original_path="/path/to/phones.csv",
-    results=results,
-    output_path="/path/to/results.csv"
-)
+# Process CSV text content
+csv_text = "name,phone\nJohn,+15551234567\nJane,+15551234568"
+results = processor.process_csv(csv_text)
+
+# Generate results CSV
+results_csv = processor.generate_results_csv(csv_text, results)
+print(results_csv)  # CSV string with added line_type, dnc, cached columns
+```
+
+### Streaming Large Files
+
+For memory-efficient processing of large CSV files:
+
+```python
+from ai_lls_lib import BulkProcessor, PhoneVerifier, DynamoDBCache
+
+cache = DynamoDBCache(table_name="phone-cache")
+verifier = PhoneVerifier(cache)
+processor = BulkProcessor(verifier)
+
+# Process CSV as a stream, yielding batches
+csv_lines = open('large_file.csv').readlines()
+for batch in processor.process_csv_stream(csv_lines, batch_size=100):
+    print(f"Processed batch of {len(batch)} phones")
+    # Each batch is a list of PhoneVerification objects
+```
+
+### Custom Verification Providers
+
+Use different verification providers based on your needs:
+
+```python
+from ai_lls_lib import PhoneVerifier, DynamoDBCache
+from ai_lls_lib.providers import StubProvider
+
+# Use stub provider for testing
+cache = DynamoDBCache(table_name="phone-cache")
+provider = StubProvider()  # Deterministic testing provider
+verifier = PhoneVerifier(cache, provider=provider)
+
+# When external APIs are ready, switch to:
+# from ai_lls_lib.providers.external import ExternalAPIProvider
+# provider = ExternalAPIProvider(phone_api_key="...", dnc_api_key="...")
 ```
 
 ## CLI Usage

ai_lls_lib-1.2.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+ai_lls_lib/__init__.py,sha256=vX28RZKgWt_4PDkQ_H69AwCCp7Jt9nHwhxt4RhKOotU,584
+ai_lls_lib/auth/__init__.py,sha256=c6zomHSB6y9Seakf84ciGsD3XgWarIty9xty6P8fxVw,194
+ai_lls_lib/auth/context_parser.py,sha256=8I0vGbtykNLWqm8ldedxXjE-E3nqsCy113JgeyuiJoM,2222
+ai_lls_lib/cli/__init__.py,sha256=m9qjZTW1jpENwXAUeuRrlP0b66BWRcqSO28MSjvOyCs,74
+ai_lls_lib/cli/__main__.py,sha256=8tUdq4GJwzIiTC1pvCsTkwmq8iNujdFTbI45_wm3d7A,716
+ai_lls_lib/cli/aws_client.py,sha256=YcCWCpTNOW9JPLxSNLRy5-F5HPKguJJk7dPNrPqhJv0,3952
+ai_lls_lib/cli/commands/__init__.py,sha256=_kROrYuR_p2i110c0OvNeArfEFQbn15zR1c3pdeZOoo,28
+ai_lls_lib/cli/commands/admin.py,sha256=bNBJi2fZBP0J40JQP6HP7NYadNmI214iII1TeLhooyE,6687
+ai_lls_lib/cli/commands/cache.py,sha256=vWt0vy4L9CEgUEWUzfdehU6u43PE8vUvHx7xxg4e5tw,5680
+ai_lls_lib/cli/commands/stripe.py,sha256=x5QtirbCPiBrjdMRVTR0aeQN2gy0_p6jcGzELObFfzg,12006
+ai_lls_lib/cli/commands/test_stack.py,sha256=rNq4mhRXX7Ixo67kSoEPWlxqgXCzM9e2PR96qTAG7pE,7378
+ai_lls_lib/cli/commands/verify.py,sha256=V5ucjmjCUxqN8_AeEJWWgrmYin8BNV3h4WbZ-iX3loU,4238
+ai_lls_lib/cli/env_loader.py,sha256=YTCB6QDyknOuedPbQsW4bezB5SgHzJMGjhpSPArHFVc,3762
+ai_lls_lib/core/__init__.py,sha256=QUaeQHIyvknkgMxIbfXRo1a5jSQpiJkB84dId5ubuEk,36
+ai_lls_lib/core/cache.py,sha256=MubgyAF3y7BBF9am39Ni98NgikZ9UBZUG-KtbE3XWX4,3711
+ai_lls_lib/core/models.py,sha256=ABRYaeMCWahQh4WdbkCxt3AO0-EvPWZwlL-JITQSnEM,2381
+ai_lls_lib/core/processor.py,sha256=6752IPDQ-Mz5i_CU7aBM0UjvV7IjyZFl35LKVPkHMpc,9974
+ai_lls_lib/core/verifier.py,sha256=6uB_jawWoIqsNYAadTKr0lSolIWygg2gK6ykf8lrul0,2716
+ai_lls_lib/payment/__init__.py,sha256=xhUWgfLnk3syXXQItswmDXdfXUyJTXTQAA0zIUuCVII,295
+ai_lls_lib/payment/credit_manager.py,sha256=TDrdW7BYjhtlg8MX_EJEnMNct1SU_6Tdb_k19_e8kpo,6343
+ai_lls_lib/payment/models.py,sha256=JjSmWKwpuFF85Jzmabj6y7UyolJlJlsh5CmOWRg21B8,3339
+ai_lls_lib/payment/stripe_manager.py,sha256=-L329stuu-6V_QKzRdkm9qnoi74SbWzST0fuf2WAJXA,17111
+ai_lls_lib/payment/webhook_processor.py,sha256=UVngeAGcou5ieRAp-49pqdWh0wsJQVwpiRoLmyl5Adc,6448
+ai_lls_lib/providers/__init__.py,sha256=AEv3ARenWDwDo5PLCoszP2fQ70RgSHkrSLSUz7xHJDk,179
+ai_lls_lib/providers/base.py,sha256=344XYOg7bxDQMWJ6Lle8U7NOHpabnCp0XYbZpeWpPAk,681
+ai_lls_lib/providers/external.py,sha256=-Hhnlm8lQWRcWr5vG0dmD3sca2rohURrx0usOR2y1MM,2623
+ai_lls_lib/providers/stub.py,sha256=847Tmw522B3HQ2j38BH1sdcZQy--RdtDcXsrIrFKNBQ,1150
+ai_lls_lib/testing/__init__.py,sha256=RUxRYBzzPCPS15Umb6bUrE6rL5BQXBQf4SJM2E3ffrg,39
+ai_lls_lib/testing/fixtures.py,sha256=_n6bbr95LnQf9Dvu1qKs2HsvHEA7AAbe59B75qxE10w,3310
+ai_lls_lib-1.2.0.dist-info/METADATA,sha256=o76nenDApQ5pITFYnlmX7IS-maEi39JgU75iUyI9udk,7248
+ai_lls_lib-1.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+ai_lls_lib-1.2.0.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
+ai_lls_lib-1.2.0.dist-info/RECORD,,

ai_lls_lib-1.0.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-ai_lls_lib/__init__.py,sha256=XfIG376ImlT_OH0R75BNpoqcxsx0fIp6cSFpQw_XhL8,584
-ai_lls_lib/cli/__init__.py,sha256=m9qjZTW1jpENwXAUeuRrlP0b66BWRcqSO28MSjvOyCs,74
-ai_lls_lib/cli/__main__.py,sha256=DH9x08k6GWBSqVWspHgWTxGM7NkTBZ2OS2KrVW-XQaA,671
-ai_lls_lib/cli/aws_client.py,sha256=YcCWCpTNOW9JPLxSNLRy5-F5HPKguJJk7dPNrPqhJv0,3952
-ai_lls_lib/cli/commands/__init__.py,sha256=_kROrYuR_p2i110c0OvNeArfEFQbn15zR1c3pdeZOoo,28
-ai_lls_lib/cli/commands/admin.py,sha256=bNBJi2fZBP0J40JQP6HP7NYadNmI214iII1TeLhooyE,6687
-ai_lls_lib/cli/commands/cache.py,sha256=vWt0vy4L9CEgUEWUzfdehU6u43PE8vUvHx7xxg4e5tw,5680
-ai_lls_lib/cli/commands/test_stack.py,sha256=rNq4mhRXX7Ixo67kSoEPWlxqgXCzM9e2PR96qTAG7pE,7378
-ai_lls_lib/cli/commands/verify.py,sha256=tKHkSghrtnqkjAQGvTs-5uDUgstQO0HMW04EddRPgJU,4253
-ai_lls_lib/core/__init__.py,sha256=QUaeQHIyvknkgMxIbfXRo1a5jSQpiJkB84dId5ubuEk,36
-ai_lls_lib/core/cache.py,sha256=MubgyAF3y7BBF9am39Ni98NgikZ9UBZUG-KtbE3XWX4,3711
-ai_lls_lib/core/models.py,sha256=ABRYaeMCWahQh4WdbkCxt3AO0-EvPWZwlL-JITQSnEM,2381
-ai_lls_lib/core/processor.py,sha256=s49fVlZt6lnfWNgboiHsC6ruman4oIXzgVqzuwExKBQ,4916
-ai_lls_lib/core/verifier.py,sha256=fglRDoFgrQyX4UuYknZLYX4t9HlpTS2HMVsfszSNXQ4,3257
-ai_lls_lib/testing/__init__.py,sha256=RUxRYBzzPCPS15Umb6bUrE6rL5BQXBQf4SJM2E3ffrg,39
-ai_lls_lib/testing/fixtures.py,sha256=_n6bbr95LnQf9Dvu1qKs2HsvHEA7AAbe59B75qxE10w,3310
-ai_lls_lib-1.0.0.dist-info/METADATA,sha256=q4xSigc2_m2Jmv45SfXFfH9dBbFOVDcfIBa0Uzaw48w,5344
-ai_lls_lib-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-ai_lls_lib-1.0.0.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
-ai_lls_lib-1.0.0.dist-info/RECORD,,