geek-cafe-saas-sdk 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

geek_cafe_saas_sdk/domains/payments/handlers/payment_intents/get/app.py

@@ -0,0 +1,60 @@
+"""
+Lambda handler for getting payment intent by ID.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get payment intent by ID.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Path parameters:
+    - intentId: Payment intent reference ID
+    
+    Returns 200 with payment intent data
+    """
+    return handler_wrapper.execute(event, context, get_payment_intent, injected_service)
+
+
+def get_payment_intent(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for getting payment intent.
+    """
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract intent ID from path parameters
+    path_params = event.get("pathParameters", {})
+    intent_id = path_params.get("intentId")
+    
+    if not intent_id:
+        raise ValueError("intentId path parameter is required")
+    
+    # Get payment intent
+    result = service.get_payment_intent(
+        intent_ref_id=intent_id,
+        tenant_id=tenant_id
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/payments/get/app.py

@@ -0,0 +1,60 @@
+"""
+Lambda handler for getting payment by ID.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get payment by ID.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Path parameters:
+    - paymentId: Payment ID
+    
+    Returns 200 with payment data
+    """
+    return handler_wrapper.execute(event, context, get_payment, injected_service)
+
+
+def get_payment(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for getting payment.
+    """
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract payment ID from path parameters
+    path_params = event.get("pathParameters", {})
+    payment_id = path_params.get("paymentId")
+    
+    if not payment_id:
+        raise ValueError("paymentId path parameter is required")
+    
+    # Get payment
+    result = service.get_payment(
+        payment_id=payment_id,
+        tenant_id=tenant_id
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/payments/list/app.py

@@ -0,0 +1,68 @@
+"""
+Lambda handler for listing payments.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    List payments for a tenant or billing account.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Query parameters:
+    - billingAccountId: Optional billing account ID to filter by
+    - limit: Optional page size (default: 50, max: 100)
+    
+    Returns 200 with list of payments
+    """
+    return handler_wrapper.execute(event, context, list_payments, injected_service)
+
+
+def list_payments(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for listing payments.
+    """
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract query parameters
+    query_params = event.get("queryStringParameters") or {}
+    billing_account_id = query_params.get("billingAccountId")
+    limit = query_params.get("limit", "50")
+    
+    # Validate and convert limit
+    try:
+        limit = int(limit)
+        if limit < 1 or limit > 100:
+            raise ValueError("limit must be between 1 and 100")
+    except ValueError as e:
+        raise ValueError(f"Invalid limit parameter: {str(e)}")
+    
+    # List payments
+    result = service.list_payments(
+        tenant_id=tenant_id,
+        billing_account_id=billing_account_id,
+        limit=limit
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/payments/record/app.py

@@ -0,0 +1,118 @@
+"""
+Lambda handler for recording settled payments.
+
+Typically called from Stripe webhooks or payment processor callbacks.
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Record a settled payment.
+    
+    Args:
+        event: Lambda event from API Gateway or webhook
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Expected body (camelCase from frontend/webhook):
+    {
+        "billingAccountId": "account-123",
+        "paymentIntentRefId": "intent-123",  // Optional
+        "grossAmountCents": 5000,  // $50.00
+        "feeAmountCents": 145,  // $1.45 (Stripe fee)
+        "currencyCode": "USD",
+        "pspType": "stripe",
+        "pspTransactionId": "txn_xxx",
+        "pspChargeId": "ch_xxx",
+        "pspBalanceTransactionId": "txn_balance_xxx",
+        "paymentMethodId": "pm_xxx",
+        "paymentMethodType": "card",
+        "paymentMethodLast4": "4242",
+        "paymentMethodBrand": "visa",
+        "paymentMethodFunding": "credit",
+        "description": "Subscription payment",
+        "statementDescriptor": "ACME SUBSCRIPTION",
+        "receiptEmail": "user@example.com",
+        "receiptUrl": "https://stripe.com/receipt/xxx",
+        "customerId": "user-123",  // Optional
+        "invoiceId": "inv-123",  // Optional
+        "subscriptionId": "sub-123"  // Optional
+    }
+    
+    Returns 201 with recorded payment
+    """
+    return handler_wrapper.execute(event, context, record_payment, injected_service)
+
+
+def record_payment(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for recording payments.
+    """
+    payload = event["parsed_body"]
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract required fields
+    billing_account_id = payload.get("billing_account_id")
+    gross_amount_cents = payload.get("gross_amount_cents")
+    fee_amount_cents = payload.get("fee_amount_cents")
+    
+    if not billing_account_id:
+        raise ValueError("billing_account_id is required")
+    if gross_amount_cents is None or gross_amount_cents <= 0:
+        raise ValueError("gross_amount_cents must be greater than 0")
+    if fee_amount_cents is None or fee_amount_cents < 0:
+        raise ValueError("fee_amount_cents must be non-negative")
+    
+    # Extract optional fields
+    payment_intent_ref_id = payload.get("payment_intent_ref_id")
+    currency_code = payload.get("currency_code", "USD")
+    psp_type = payload.get("psp_type", "stripe")
+    
+    # Build kwargs for optional fields
+    kwargs = {}
+    optional_fields = [
+        "psp_transaction_id", "psp_charge_id", "psp_balance_transaction_id",
+        "fee_details",
+        "payment_method_id", "payment_method_type", "payment_method_last4",
+        "payment_method_brand", "payment_method_funding",
+        "settlement_date", "payout_id",
+        "customer_id", "invoice_id", "subscription_id",
+        "description", "statement_descriptor",
+        "receipt_number", "receipt_email", "receipt_url",
+        "psp_metadata", "application_fee_amount_cents"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    # Record payment
+    result = service.record_payment(
+        tenant_id=tenant_id,
+        billing_account_id=billing_account_id,
+        payment_intent_ref_id=payment_intent_ref_id,
+        gross_amount_cents=gross_amount_cents,
+        fee_amount_cents=fee_amount_cents,
+        currency_code=currency_code,
+        psp_type=psp_type,
+        **kwargs
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/refunds/create/app.py

@@ -0,0 +1,89 @@
+"""
+Lambda handler for creating refunds.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Create a refund for a payment.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Expected body (camelCase from frontend):
+    {
+        "paymentId": "payment-123",
+        "amountCents": 5000,  // Amount to refund (must not exceed remaining)
+        "reason": "requested_by_customer",  // "duplicate", "fraudulent", "requested_by_customer"
+        "description": "Customer requested refund",
+        "pspRefundId": "re_xxx",  // Optional - PSP refund ID if already created
+        "disputeId": "dp_xxx"  // Optional - if related to dispute
+    }
+    
+    Returns 201 with created refund
+    """
+    return handler_wrapper.execute(event, context, create_refund, injected_service)
+
+
+def create_refund(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for creating refunds.
+    """
+    payload = event["parsed_body"]
+    tenant_id = user_context.get("tenant_id")
+    user_id = user_context.get("user_id")
+    
+    # Extract required fields
+    payment_id = payload.get("payment_id")
+    amount_cents = payload.get("amount_cents")
+    
+    if not payment_id:
+        raise ValueError("payment_id is required")
+    if amount_cents is None or amount_cents <= 0:
+        raise ValueError("amount_cents must be greater than 0")
+    
+    # Extract optional fields
+    reason = payload.get("reason")
+    
+    # Build kwargs for optional fields
+    kwargs = {}
+    optional_fields = [
+        "description", "psp_refund_id", "psp_balance_transaction_id",
+        "dispute_id", "notes"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    # Create refund
+    result = service.create_refund(
+        tenant_id=tenant_id,
+        payment_id=payment_id,
+        amount_cents=amount_cents,
+        reason=reason,
+        initiated_by_id=user_id,
+        **kwargs
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/refunds/get/app.py

@@ -0,0 +1,60 @@
+"""
+Lambda handler for getting refund by ID.
+
+Requires authentication (secure mode).
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.payments.services import PaymentService
+
+
+# Factory creates handler (defaults to secure auth)
+handler_wrapper = create_handler(
+    service_class=PaymentService,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get refund by ID.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Path parameters:
+    - refundId: Refund ID
+    
+    Returns 200 with refund data
+    """
+    return handler_wrapper.execute(event, context, get_refund, injected_service)
+
+
+def get_refund(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for getting refund.
+    """
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract refund ID from path parameters
+    path_params = event.get("pathParameters", {})
+    refund_id = path_params.get("refundId")
+    
+    if not refund_id:
+        raise ValueError("refundId path parameter is required")
+    
+    # Get refund
+    result = service.get_refund(
+        refund_id=refund_id,
+        tenant_id=tenant_id
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/models/__init__.py

@@ -0,0 +1,17 @@
+"""Payment models.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from .billing_account import BillingAccount
+from .payment_intent_ref import PaymentIntentRef
+from .payment import Payment
+from .refund import Refund
+
+__all__ = [
+    "BillingAccount",
+    "PaymentIntentRef",
+    "Payment",
+    "Refund",
+]