ai-lls-lib 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

ai_lls_lib/payment/stripe_manager.py

@@ -0,0 +1,486 @@
+"""Stripe API management with metadata conventions."""
+
+import os
+from typing import List, Optional, Dict, Any
+import logging
+
+try:
+    import stripe
+except ImportError:
+    stripe = None  # Handle gracefully for testing
+
+from .models import Plan
+
+logger = logging.getLogger(__name__)
+
+
+class StripeManager:
+    """
+    Manages Stripe resources with metadata conventions.
+    Uses metadata to discover and filter products/prices.
+    """
+
+    METADATA_SCHEMA = {
+        "product_type": "landline_scrubber",
+        "environment": None,  # Set at runtime
+        "tier": None,
+        "credits": None,
+        "active": "true"
+    }
+
+    def __init__(self, api_key: Optional[str] = None, environment: Optional[str] = None):
+        """Initialize with Stripe API key and environment."""
+        if not stripe:
+            raise ImportError("stripe package not installed. Run: pip install stripe")
+
+        self.api_key = api_key or os.environ.get("STRIPE_SECRET_KEY")
+        if not self.api_key:
+            raise ValueError("Stripe API key not provided and STRIPE_SECRET_KEY not set")
+
+        stripe.api_key = self.api_key
+        self.environment = environment or os.environ.get("ENVIRONMENT", "staging")
+
+    def list_plans(self) -> List[Plan]:
+        """
+        Fetch active plans from Stripe using metadata.
+        Returns list of Plan objects sorted by price.
+        """
+        try:
+            # Fetch all active prices with expanded product data
+            prices = stripe.Price.list(
+                active=True,
+                expand=["data.product"],
+                limit=100
+            )
+
+            plans = []
+            for price in prices.data:
+                metadata = price.metadata or {}
+
+                # Filter by our metadata conventions
+                if (metadata.get("product_type") == "landline_scrubber" and
+                    metadata.get("environment") == self.environment and
+                    metadata.get("active") == "true"):
+
+                    # Convert to Plan object
+                    plan = Plan.from_stripe_price(price, price.product)
+                    plans.append(plan)
+
+            # Sort by price amount
+            plans.sort(key=lambda p: p.plan_amount)
+
+            logger.info(f"Found {len(plans)} active plans for environment {self.environment}")
+            return plans
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error listing plans: {e}")
+            # Return mock data for development/testing
+            return self._get_mock_plans()
+
+    def create_setup_intent(self, user_id: str) -> Dict[str, str]:
+        """
+        Create a SetupIntent for secure payment method collection.
+        Frontend will confirm this with Stripe Elements.
+        """
+        try:
+            # Get or create customer
+            customer = self._get_or_create_customer(user_id)
+
+            # Create SetupIntent
+            setup_intent = stripe.SetupIntent.create(
+                customer=customer.id,
+                metadata={
+                    "user_id": user_id,
+                    "environment": self.environment
+                }
+            )
+
+            return {
+                "client_secret": setup_intent.client_secret,
+                "setup_intent_id": setup_intent.id
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error creating setup intent: {e}")
+            raise
+
+    def attach_payment_method(self, user_id: str, payment_method_id: str, billing_details: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Attach a payment method to customer (legacy path).
+        Returns whether this is the first card.
+        """
+        try:
+            # Get or create customer
+            customer = self._get_or_create_customer(user_id)
+
+            # Attach payment method to customer
+            payment_method = stripe.PaymentMethod.attach(
+                payment_method_id,
+                customer=customer.id
+            )
+
+            # Update billing details if provided
+            if billing_details:
+                stripe.PaymentMethod.modify(
+                    payment_method_id,
+                    billing_details=billing_details
+                )
+
+            # Check if this is the first payment method
+            payment_methods = stripe.PaymentMethod.list(
+                customer=customer.id,
+                type="card"
+            )
+
+            first_card = len(payment_methods.data) == 1
+
+            # Set as default if first card
+            if first_card:
+                stripe.Customer.modify(
+                    customer.id,
+                    invoice_settings={"default_payment_method": payment_method_id}
+                )
+
+            return {
+                "payment_method_id": payment_method_id,
+                "first_card": first_card,
+                "customer_id": customer.id
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error attaching payment method: {e}")
+            raise
+
+    def verify_payment_method(self, user_id: str, payment_method_id: str) -> Dict[str, Any]:
+        """
+        Perform $1 verification charge on new payment method.
+        """
+        try:
+            customer = self._get_or_create_customer(user_id)
+
+            # Create $1 verification charge
+            payment_intent = stripe.PaymentIntent.create(
+                amount=100,  # $1.00 in cents
+                currency="usd",
+                customer=customer.id,
+                payment_method=payment_method_id,
+                off_session=True,
+                confirm=True,
+                description="Card verification - $1 charge",
+                metadata={
+                    "user_id": user_id,
+                    "type": "verification",
+                    "environment": self.environment
+                }
+            )
+
+            return {
+                "status": payment_intent.status,
+                "payment_intent_id": payment_intent.id
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error verifying payment method: {e}")
+            raise
+
+    def charge_prepaid(self, user_id: str, reference_code: str, amount: Optional[float] = None) -> Dict[str, Any]:
+        """
+        Charge saved payment method for credit purchase.
+        Supports both fixed-price and metadata-based variable-amount plans.
+        """
+        try:
+            customer = self._get_or_create_customer(user_id)
+
+            # Look up price from Stripe
+            prices = stripe.Price.list(active=True, limit=100, expand=["data.product"])
+            price = None
+
+            for p in prices.data:
+                metadata = p.metadata or {}
+                # Match by price ID or plan_reference in metadata
+                if (p.id == reference_code or
+                    metadata.get("plan_reference") == reference_code or
+                    (metadata.get("tier") == reference_code and
+                     metadata.get("environment") == self.environment)):
+                    price = p
+                    break
+
+            if not price:
+                raise ValueError(f"Invalid plan reference: {reference_code}")
+
+            price_metadata = price.metadata or {}
+
+            # Check if this is a variable amount plan
+            if price_metadata.get("variable_amount") == "true":
+                # Variable amount plan - validate amount
+                if not amount:
+                    raise ValueError("Amount required for variable-amount plan")
+
+                # Get validation rules from metadata
+                min_amount = float(price_metadata.get("min_amount", "5"))
+                if amount < min_amount:
+                    raise ValueError(f"Amount ${amount} is below minimum ${min_amount}")
+
+                # Check against default amounts if specified
+                default_amounts_str = price_metadata.get("default_amounts", "")
+                if default_amounts_str:
+                    allowed_amounts = [float(x.strip()) for x in default_amounts_str.split(",")]
+                    # Allow default amounts OR any amount >= minimum
+                    if amount not in allowed_amounts and amount < max(allowed_amounts):
+                        logger.info(f"Amount ${amount} not in defaults {allowed_amounts}, but allowed as >= ${min_amount}")
+
+                # Calculate credits based on credits_per_dollar
+                credits_per_dollar = float(price_metadata.get("credits_per_dollar", "285"))
+                credits_to_add = int(amount * credits_per_dollar)
+                charge_amount = int(amount * 100)  # Convert to cents
+
+            else:
+                # Fixed price plan
+                charge_amount = price.unit_amount
+                credits_str = price_metadata.get("credits", "0")
+                if credits_str.lower() == "unlimited":
+                    credits_to_add = 0  # Subscription handles this differently
+                else:
+                    credits_to_add = int(credits_str)
+
+            # Get default payment method
+            default_pm = customer.invoice_settings.get("default_payment_method")
+            if not default_pm:
+                # Try to get first payment method
+                payment_methods = stripe.PaymentMethod.list(
+                    customer=customer.id,
+                    type="card",
+                    limit=1
+                )
+                if not payment_methods.data:
+                    raise ValueError("No payment method on file")
+                default_pm = payment_methods.data[0].id
+
+            # Create payment intent
+            payment_intent = stripe.PaymentIntent.create(
+                amount=charge_amount,
+                currency="usd",
+                customer=customer.id,
+                payment_method=default_pm,
+                off_session=True,
+                confirm=True,
+                description=f"Credit purchase - {credits_to_add} credits",
+                metadata={
+                    "user_id": user_id,
+                    "credits": credits_to_add,
+                    "reference_code": reference_code,
+                    "environment": self.environment
+                }
+            )
+
+            return {
+                "id": payment_intent.id,
+                "status": payment_intent.status,
+                "credits_added": credits_to_add,
+                "amount_charged": charge_amount / 100  # Convert back to dollars
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error processing payment: {e}")
+            raise
+
+    def customer_has_payment_method(self, stripe_customer_id: str) -> bool:
+        """
+        Check if customer has any saved payment methods.
+        """
+        try:
+            payment_methods = stripe.PaymentMethod.list(
+                customer=stripe_customer_id,
+                type="card",
+                limit=1
+            )
+            return len(payment_methods.data) > 0
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error checking payment methods: {e}")
+            return False
+
+    def list_payment_methods(self, stripe_customer_id: str) -> Dict[str, Any]:
+        """
+        List all payment methods for a customer.
+        """
+        try:
+            # Get customer to find default payment method
+            customer = stripe.Customer.retrieve(stripe_customer_id)
+            default_pm_id = customer.invoice_settings.get("default_payment_method")
+
+            # List all payment methods
+            payment_methods = stripe.PaymentMethod.list(
+                customer=stripe_customer_id,
+                type="card"
+            )
+
+            items = []
+            for pm in payment_methods.data:
+                items.append({
+                    "id": pm.id,
+                    "brand": pm.card.brand,
+                    "last4": pm.card.last4,
+                    "exp_month": pm.card.exp_month,
+                    "exp_year": pm.card.exp_year,
+                    "is_default": pm.id == default_pm_id
+                })
+
+            return {
+                "items": items,
+                "default_payment_method_id": default_pm_id
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error listing payment methods: {e}")
+            return {"items": [], "default_payment_method_id": None}
+
+    def _get_or_create_customer(self, user_id: str, email: Optional[str] = None) -> Any:
+        """
+        Get existing Stripe customer or create new one.
+        First checks by user_id in metadata, then by email if provided.
+        """
+        try:
+            # First try to find by user_id in metadata
+            customers = stripe.Customer.search(
+                query=f'metadata["user_id"]:"{user_id}"',
+                limit=1
+            )
+
+            if customers.data:
+                return customers.data[0]
+
+            # If email provided, try to find by email
+            if email:
+                customers = stripe.Customer.list(email=email, limit=1)
+                if customers.data:
+                    # Update metadata with user_id
+                    customer = customers.data[0]
+                    stripe.Customer.modify(
+                        customer.id,
+                        metadata={"user_id": user_id}
+                    )
+                    return customer
+
+            # Create new customer
+            return stripe.Customer.create(
+                email=email,
+                metadata={
+                    "user_id": user_id,
+                    "environment": self.environment
+                }
+            )
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error getting/creating customer: {e}")
+            raise
+
+    def create_subscription(self, user_id: str, email: str, price_id: str) -> Dict[str, Any]:
+        """Create a subscription for unlimited access."""
+        try:
+            # Create or retrieve customer
+            customers = stripe.Customer.list(email=email, limit=1)
+            if customers.data:
+                customer = customers.data[0]
+            else:
+                customer = stripe.Customer.create(
+                    email=email,
+                    metadata={"user_id": user_id}
+                )
+
+            # Create subscription
+            subscription = stripe.Subscription.create(
+                customer=customer.id,
+                items=[{"price": price_id}],
+                metadata={
+                    "user_id": user_id,
+                    "environment": self.environment
+                }
+            )
+
+            return {
+                "subscription_id": subscription.id,
+                "status": subscription.status,
+                "customer_id": customer.id
+            }
+
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error creating subscription: {e}")
+            raise
+
+    def pause_subscription(self, subscription_id: str) -> Dict[str, str]:
+        """Pause a subscription."""
+        try:
+            subscription = stripe.Subscription.modify(
+                subscription_id,
+                pause_collection={"behavior": "mark_uncollectible"}
+            )
+            return {"message": "Subscription paused", "status": "paused"}
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error pausing subscription: {e}")
+            raise
+
+    def resume_subscription(self, subscription_id: str) -> Dict[str, str]:
+        """Resume a paused subscription."""
+        try:
+            subscription = stripe.Subscription.modify(
+                subscription_id,
+                pause_collection=""  # Remove pause
+            )
+            return {"message": "Subscription resumed", "status": "active"}
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error resuming subscription: {e}")
+            raise
+
+    def cancel_subscription(self, subscription_id: str) -> Dict[str, str]:
+        """Cancel a subscription."""
+        try:
+            subscription = stripe.Subscription.delete(subscription_id)
+            return {"message": "Subscription cancelled", "status": "cancelled"}
+        except stripe.error.StripeError as e:
+            logger.error(f"Stripe error cancelling subscription: {e}")
+            raise
+
+    def _get_mock_plans(self) -> List[Plan]:
+        """Return mock plans for development/testing."""
+        return [
+            Plan(
+                plan_reference="79541679412215",
+                plan_type="prepaid",
+                plan_name="STANDARD",
+                plan_subtitle="One-time purchase",
+                plan_amount=10.0,
+                plan_credits=5000,
+                plan_credits_text="5,000 credits",
+                percent_off=""
+            ),
+            Plan(
+                plan_reference="79541679412216",
+                plan_type="prepaid",
+                plan_name="POWER",
+                plan_subtitle="Best value",
+                plan_amount=50.0,
+                plan_credits=28500,
+                plan_credits_text="28,500 credits",
+                percent_off="12.5% OFF"
+            ),
+            Plan(
+                plan_reference="79541679412217",
+                plan_type="prepaid",
+                plan_name="ELITE",
+                plan_subtitle="Maximum savings",
+                plan_amount=100.0,
+                plan_credits=66666,
+                plan_credits_text="66,666 credits",
+                percent_off="25% OFF"
+            ),
+            Plan(
+                plan_reference="price_unlimited",
+                plan_type="postpaid",
+                plan_name="UNLIMITED",
+                plan_subtitle="Monthly subscription",
+                plan_amount=299.0,
+                plan_credits=None,
+                plan_credits_text="Unlimited",
+                percent_off=""
+            )
+        ]

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}