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

geek_cafe_saas_sdk/domains/payments/handlers/README.md

@@ -0,0 +1,334 @@
+# Payment Handlers
+
+Lambda handlers for payment operations.
+
+## Structure
+
+```
+handlers/
+├── billing_accounts/
+│   ├── create/app.py    - POST /billing-accounts
+│   ├── get/app.py       - GET /billing-accounts/{accountId}
+│   └── update/app.py    - PATCH /billing-accounts/{accountId}
+├── payment_intents/
+│   ├── create/app.py    - POST /payment-intents
+│   └── get/app.py       - GET /payment-intents/{intentId}
+├── payments/
+│   ├── record/app.py    - POST /payments (webhook handler)
+│   ├── get/app.py       - GET /payments/{paymentId}
+│   └── list/app.py      - GET /payments
+└── refunds/
+    ├── create/app.py    - POST /refunds
+    └── get/app.py       - GET /refunds/{refundId}
+```
+
+## Billing Account Handlers
+
+### POST /billing-accounts
+**Handler:** `billing_accounts/create/app.py`  
+**Purpose:** Create a new billing account
+
+**Request Body:**
+```json
+{
+  "accountHolderId": "user-123",
+  "accountHolderType": "user",
+  "currencyCode": "USD",
+  "billingEmail": "user@example.com",
+  "billingName": "John Doe",
+  "addressLine1": "123 Main St",
+  "addressCity": "San Francisco",
+  "addressState": "CA",
+  "addressPostalCode": "94105",
+  "addressCountry": "US",
+  "stripeCustomerId": "cus_xxx"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "success": true,
+  "data": {
+    "accountId": "account-123",
+    "accountHolderId": "user-123",
+    "currencyCode": "USD",
+    "status": "active",
+    ...
+  }
+}
+```
+
+---
+
+### GET /billing-accounts/{accountId}
+**Handler:** `billing_accounts/get/app.py`  
+**Purpose:** Retrieve billing account details
+
+**Path Parameters:**
+- `accountId` - Billing account ID
+
+**Response:** 200 OK
+```json
+{
+  "success": true,
+  "data": {
+    "accountId": "account-123",
+    "accountHolderId": "user-123",
+    "status": "active",
+    ...
+  }
+}
+```
+
+---
+
+### PATCH /billing-accounts/{accountId}
+**Handler:** `billing_accounts/update/app.py`  
+**Purpose:** Update billing account
+
+**Path Parameters:**
+- `accountId` - Billing account ID
+
+**Request Body:**
+```json
+{
+  "billingEmail": "newemail@example.com",
+  "defaultPaymentMethodId": "pm_xxx",
+  "autoChargeEnabled": true
+}
+```
+
+**Response:** 200 OK
+
+---
+
+## Payment Intent Handlers
+
+### POST /payment-intents
+**Handler:** `payment_intents/create/app.py`  
+**Purpose:** Create a payment intent for frontend payment flow
+
+**Request Body:**
+```json
+{
+  "billingAccountId": "account-123",
+  "amountCents": 5000,
+  "currencyCode": "USD",
+  "description": "Subscription payment",
+  "receiptEmail": "user@example.com"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "success": true,
+  "data": {
+    "intentRefId": "intent-123",
+    "pspClientSecret": "pi_xxx_secret_yyy",
+    "status": "created",
+    "amountCents": 5000,
+    ...
+  }
+}
+```
+
+---
+
+### GET /payment-intents/{intentId}
+**Handler:** `payment_intents/get/app.py`  
+**Purpose:** Retrieve payment intent status
+
+**Path Parameters:**
+- `intentId` - Payment intent reference ID
+
+**Response:** 200 OK
+
+---
+
+## Payment Handlers
+
+### POST /payments
+**Handler:** `payments/record/app.py`  
+**Purpose:** Record a settled payment (typically called from webhooks)
+
+**Request Body:**
+```json
+{
+  "billingAccountId": "account-123",
+  "paymentIntentRefId": "intent-123",
+  "grossAmountCents": 5000,
+  "feeAmountCents": 145,
+  "currencyCode": "USD",
+  "pspType": "stripe",
+  "pspTransactionId": "txn_xxx",
+  "pspChargeId": "ch_xxx",
+  "paymentMethodLast4": "4242",
+  "paymentMethodBrand": "visa"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "success": true,
+  "data": {
+    "paymentId": "payment-123",
+    "grossAmountCents": 5000,
+    "feeAmountCents": 145,
+    "netAmountCents": 4855,
+    "status": "succeeded",
+    ...
+  }
+}
+```
+
+---
+
+### GET /payments/{paymentId}
+**Handler:** `payments/get/app.py`  
+**Purpose:** Retrieve payment details
+
+**Path Parameters:**
+- `paymentId` - Payment ID
+
+**Response:** 200 OK
+
+---
+
+### GET /payments
+**Handler:** `payments/list/app.py`  
+**Purpose:** List payments for tenant or billing account
+
+**Query Parameters:**
+- `billingAccountId` (optional) - Filter by billing account
+- `limit` (optional) - Page size (default: 50, max: 100)
+
+**Response:** 200 OK
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "paymentId": "payment-123",
+      "grossAmountCents": 5000,
+      "settledUtcTs": 1697500000.0,
+      ...
+    }
+  ]
+}
+```
+
+---
+
+## Refund Handlers
+
+### POST /refunds
+**Handler:** `refunds/create/app.py`  
+**Purpose:** Create a refund for a payment
+
+**Request Body:**
+```json
+{
+  "paymentId": "payment-123",
+  "amountCents": 5000,
+  "reason": "requested_by_customer",
+  "description": "Customer requested refund"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "success": true,
+  "data": {
+    "refundId": "refund-123",
+    "paymentId": "payment-123",
+    "amountCents": 5000,
+    "status": "pending",
+    ...
+  }
+}
+```
+
+---
+
+### GET /refunds/{refundId}
+**Handler:** `refunds/get/app.py`  
+**Purpose:** Retrieve refund status
+
+**Path Parameters:**
+- `refundId` - Refund ID
+
+**Response:** 200 OK
+
+---
+
+## Authentication
+
+All handlers require authentication. The `create_handler` factory automatically:
+- Validates JWT tokens
+- Extracts tenant_id and user_id from the token
+- Returns 401 Unauthorized for invalid/missing tokens
+
+## Error Handling
+
+Handlers use the ServiceResult pattern for consistent error responses:
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "message": "Error description",
+  "errorCode": "ERROR_CODE",
+  "statusCode": 400
+}
+```
+
+## Common HTTP Status Codes
+
+- **200 OK** - Successful GET/LIST operation
+- **201 Created** - Successful POST/CREATE operation
+- **400 Bad Request** - Validation error
+- **401 Unauthorized** - Authentication failed
+- **404 Not Found** - Resource not found
+- **500 Internal Server Error** - Unexpected error
+
+## Deployment
+
+Each handler is packaged as a separate Lambda function:
+
+```yaml
+# SAM/CloudFormation template
+CreateBillingAccountFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    Handler: app.handler
+    Runtime: python3.11
+    CodeUri: domains/payments/handlers/billing_accounts/create/
+    Events:
+      Api:
+        Type: Api
+        Properties:
+          Path: /billing-accounts
+          Method: post
+```
+
+## Testing
+
+See `tests/test_payment_handlers.py` for handler integration tests.
+
+## Related Documentation
+
+- **Service Layer:** `../services/payment_service.py`
+- **Models:** `../models/`
+- **User Guide:** `/docs/help/payments/`

geek_cafe_saas_sdk/domains/payments/handlers/__init__.py

@@ -0,0 +1,6 @@
+"""
+Payment handlers.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""

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

@@ -0,0 +1,105 @@
+"""
+Lambda handler for creating billing accounts.
+
+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 new billing account.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Expected body (camelCase from frontend):
+    {
+        "accountHolderId": "user-123",
+        "accountHolderType": "user",  // "user", "organization", "property"
+        "currencyCode": "USD",
+        "billingEmail": "user@example.com",
+        "billingName": "John Doe",
+        "billingPhone": "+1234567890",
+        "addressLine1": "123 Main St",
+        "addressLine2": "Apt 4B",
+        "addressCity": "San Francisco",
+        "addressState": "CA",
+        "addressPostalCode": "94105",
+        "addressCountry": "US",
+        "stripeCustomerId": "cus_xxx",  // Optional
+        "taxId": "12-3456789",  // Optional
+        "taxIdType": "us_ein",  // Optional
+        "taxExempt": false  // Optional
+    }
+    
+    Returns 201 with created billing account
+    """
+    return handler_wrapper.execute(event, context, create_billing_account, injected_service)
+
+
+def create_billing_account(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for creating billing accounts.
+    """
+    payload = event["parsed_body"]
+    
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract required fields
+    account_holder_id = payload.get("account_holder_id")
+    if not account_holder_id:
+        raise ValueError("account_holder_id is required")
+    
+    # Extract optional fields with defaults
+    account_holder_type = payload.get("account_holder_type", "user")
+    currency_code = payload.get("currency_code", "USD")
+    billing_email = payload.get("billing_email")
+    
+    # Build kwargs for optional fields
+    kwargs = {}
+    optional_fields = [
+        "billing_name", "billing_phone",
+        "address_line1", "address_line2", "address_city", 
+        "address_state", "address_postal_code", "address_country",
+        "stripe_customer_id", "stripe_account_id",
+        "country_code", "locale",
+        "tax_id", "tax_id_type", "tax_exempt", "tax_metadata",
+        "default_payment_method_id", "allowed_payment_methods",
+        "auto_charge_enabled", "require_cvv", "send_receipts",
+        "balance_cents", "credit_limit_cents",
+        "notes", "external_reference"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    # Create billing account
+    result = service.create_billing_account(
+        tenant_id=tenant_id,
+        account_holder_id=account_holder_id,
+        account_holder_type=account_holder_type,
+        currency_code=currency_code,
+        billing_email=billing_email,
+        **kwargs
+    )
+    
+    return result

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

@@ -0,0 +1,60 @@
+"""
+Lambda handler for getting billing account 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 billing account by ID.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Path parameters:
+    - accountId: Billing account ID
+    
+    Returns 200 with billing account data
+    """
+    return handler_wrapper.execute(event, context, get_billing_account, injected_service)
+
+
+def get_billing_account(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for getting billing account.
+    """
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract account ID from path parameters
+    path_params = event.get("pathParameters", {})
+    account_id = path_params.get("accountId")
+    
+    if not account_id:
+        raise ValueError("accountId path parameter is required")
+    
+    # Get billing account
+    result = service.get_billing_account(
+        account_id=account_id,
+        tenant_id=tenant_id
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/payments/handlers/billing_accounts/update/app.py

@@ -0,0 +1,97 @@
+"""
+Lambda handler for updating billing accounts.
+
+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]:
+    """
+    Update a billing account.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Path parameters:
+    - accountId: Billing account ID
+    
+    Expected body (camelCase from frontend):
+    {
+        "billingEmail": "newemail@example.com",
+        "billingName": "Jane Doe",
+        "addressLine1": "456 New St",
+        "stripeCustomerId": "cus_yyy",
+        "defaultPaymentMethodId": "pm_xxx",
+        "autoChargeEnabled": true,
+        "status": "active"
+        // Any updateable field from BillingAccount
+    }
+    
+    Returns 200 with updated billing account
+    """
+    return handler_wrapper.execute(event, context, update_billing_account, injected_service)
+
+
+def update_billing_account(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for updating billing account.
+    """
+    payload = event["parsed_body"]
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract account ID from path parameters
+    path_params = event.get("pathParameters", {})
+    account_id = path_params.get("accountId")
+    
+    if not account_id:
+        raise ValueError("accountId path parameter is required")
+    
+    # All payload fields are treated as updates
+    updates = {}
+    updatable_fields = [
+        "billing_email", "billing_name", "billing_phone",
+        "address_line1", "address_line2", "address_city",
+        "address_state", "address_postal_code", "address_country",
+        "stripe_customer_id", "stripe_account_id",
+        "country_code", "locale",
+        "tax_id", "tax_id_type", "tax_exempt", "tax_metadata",
+        "default_payment_method_id", "allowed_payment_methods",
+        "auto_charge_enabled", "require_cvv", "send_receipts",
+        "balance_cents", "credit_limit_cents",
+        "status", "status_reason",
+        "notes", "external_reference"
+    ]
+    
+    for field in updatable_fields:
+        if field in payload:
+            updates[field] = payload[field]
+    
+    if not updates:
+        raise ValueError("No valid fields to update")
+    
+    # Update billing account
+    result = service.update_billing_account(
+        account_id=account_id,
+        tenant_id=tenant_id,
+        updates=updates
+    )
+    
+    return result

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

@@ -0,0 +1,97 @@
+"""
+Lambda handler for creating payment intents.
+
+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 payment intent.
+    
+    Args:
+        event: Lambda event from API Gateway
+        context: Lambda context
+        injected_service: Optional PaymentService for testing
+    
+    Expected body (camelCase from frontend):
+    {
+        "billingAccountId": "account-123",
+        "amountCents": 5000,  // $50.00
+        "currencyCode": "USD",
+        "pspType": "stripe",  // "stripe", "paypal", "square"
+        "description": "Subscription payment",
+        "statementDescriptor": "ACME SUBSCRIPTION",
+        "receiptEmail": "user@example.com",
+        "setupFutureUsage": "off_session",  // Optional
+        "captureMethod": "automatic",  // Optional
+        "invoiceId": "inv-123",  // Optional
+        "subscriptionId": "sub-123"  // Optional
+    }
+    
+    Returns 201 with created payment intent
+    """
+    return handler_wrapper.execute(event, context, create_payment_intent, injected_service)
+
+
+def create_payment_intent(
+    event: Dict[str, Any],
+    service: PaymentService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for creating payment intents.
+    """
+    payload = event["parsed_body"]
+    tenant_id = user_context.get("tenant_id")
+    
+    # Extract required fields
+    billing_account_id = payload.get("billing_account_id")
+    amount_cents = payload.get("amount_cents")
+    
+    if not billing_account_id:
+        raise ValueError("billing_account_id is required")
+    if amount_cents is None or amount_cents <= 0:
+        raise ValueError("amount_cents must be greater than 0")
+    
+    # Extract optional fields with defaults
+    currency_code = payload.get("currency_code", "USD")
+    psp_type = payload.get("psp_type", "stripe")
+    
+    # Build kwargs for optional fields
+    kwargs = {}
+    optional_fields = [
+        "psp_intent_id", "psp_client_secret",
+        "payment_method_id", "payment_method_type",
+        "description", "statement_descriptor", "receipt_email",
+        "setup_future_usage", "capture_method", "confirmation_method",
+        "invoice_id", "subscription_id"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    # Create payment intent
+    result = service.create_payment_intent(
+        tenant_id=tenant_id,
+        billing_account_id=billing_account_id,
+        amount_cents=amount_cents,
+        currency_code=currency_code,
+        psp_type=psp_type,
+        **kwargs
+    )
+    
+    return result