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

geek_cafe_saas_sdk/domains/subscriptions/handlers/README.md

@@ -0,0 +1,408 @@
+# Subscriptions Domain Handlers
+
+Lambda handlers for subscription management operations.
+
+## Directory Structure
+
+```
+handlers/
+├── plans/
+│   ├── list/app.py          # GET /plans
+│   ├── get/app.py           # GET /plans/{planId}
+│   ├── create/app.py        # POST /plans (admin)
+│   └── update/app.py        # PATCH /plans/{planId} (admin)
+├── addons/
+│   ├── list/app.py          # GET /addons
+│   ├── get/app.py           # GET /addons/{addonId}
+│   ├── create/app.py        # POST /addons (admin)
+│   └── update/app.py        # PATCH /addons/{addonId} (admin)
+├── discounts/
+│   ├── validate/app.py      # POST /discounts/validate
+│   ├── create/app.py        # POST /discounts (admin)
+│   └── get/app.py           # GET /discounts/{discountId} (admin)
+└── usage/
+    ├── record/app.py        # POST /usage
+    └── aggregate/app.py     # GET /usage/aggregate
+```
+
+---
+
+## Plan Handlers
+
+### GET /plans
+List public subscription plans.
+
+**Authentication:** None (public endpoint)
+
+**Query Parameters:**
+- `status` (string, optional) - Filter by status (default: "active")
+- `isPublic` (boolean, optional) - Filter by visibility (default: true)
+- `limit` (integer, optional) - Max results (default: 50)
+
+**Response:** 200 OK
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "plan-123",
+      "planCode": "pro",
+      "planName": "Pro Plan",
+      "priceMonthly Cents": 2999,
+      "priceAnnualCents": 29990,
+      "features": {...},
+      "limits": {...}
+    }
+  ]
+}
+```
+
+### GET /plans/{planId}
+Get a specific plan.
+
+**Authentication:** None (public endpoint)
+
+**Path Parameters:**
+- `planId` (string, required) - Plan ID
+
+**Response:** 200 OK
+
+### POST /plans (Admin)
+Create a new plan.
+
+**Authentication:** Required (admin)
+
+**Request Body:**
+```json
+{
+  "planCode": "enterprise",
+  "planName": "Enterprise Plan",
+  "priceMonthly Cents": 9999,
+  "description": "For large teams",
+  "features": {
+    "api_access": true,
+    "sso": true,
+    "white_label": true
+  },
+  "limits": {
+    "max_projects": -1,
+    "max_storage_gb": 1000
+  }
+}
+```
+
+**Response:** 201 Created
+
+### PATCH /plans/{planId} (Admin)
+Update a plan.
+
+**Authentication:** Required (admin)
+
+**Request Body:** Fields to update
+
+**Response:** 200 OK
+
+---
+
+## Addon Handlers
+
+### GET /addons
+List public addons.
+
+**Authentication:** None (public endpoint)
+
+**Query Parameters:**
+- `status` (string, optional) - Filter by status
+- `category` (string, optional) - Filter by category
+- `limit` (integer, optional) - Max results
+
+**Response:** 200 OK
+
+### GET /addons/{addonId}
+Get a specific addon.
+
+**Authentication:** None (public endpoint)
+
+**Response:** 200 OK
+
+### POST /addons (Admin)
+Create a new addon.
+
+**Authentication:** Required (admin)
+
+**Request Body:**
+```json
+{
+  "addonCode": "chat",
+  "addonName": "Chat Module",
+  "pricingModel": "fixed",
+  "priceMonthly Cents": 1500,
+  "description": "Real-time chat",
+  "category": "communication",
+  "features": {
+    "realtime_messaging": true,
+    "file_sharing": true
+  }
+}
+```
+
+**Response:** 201 Created
+
+### PATCH /addons/{addonId} (Admin)
+Update an addon.
+
+**Authentication:** Required (admin)
+
+**Response:** 200 OK
+
+---
+
+## Discount Handlers
+
+### POST /discounts/validate
+Validate a discount code.
+
+**Authentication:** None (public endpoint)
+
+**Request Body:**
+```json
+{
+  "discountCode": "SUMMER25",
+  "planCode": "pro",
+  "amountCents": 2999,
+  "isFirstPurchase": false
+}
+```
+
+**Response:** 200 OK (if valid)
+```json
+{
+  "success": true,
+  "data": {
+    "id": "discount-123",
+    "discountCode": "SUMMER25",
+    "discountType": "percentage",
+    "percentOff": 25.0,
+    "duration": "repeating",
+    "durationInMonths": 3
+  }
+}
+```
+
+**Error Response:** 400 Bad Request (if invalid)
+```json
+{
+  "success": false,
+  "message": "Discount code is not currently valid"
+}
+```
+
+### POST /discounts (Admin)
+Create a new discount.
+
+**Authentication:** Required (admin)
+
+**Request Body:**
+```json
+{
+  "discountCode": "WELCOME50",
+  "discountName": "Welcome Discount",
+  "discountType": "percentage",
+  "percentOff": 50.0,
+  "duration": "once",
+  "maxRedemptions": 1000,
+  "firstTimeTransaction": true
+}
+```
+
+**Response:** 201 Created
+
+### GET /discounts/{discountId} (Admin)
+Get a discount by ID.
+
+**Authentication:** Required (admin)
+
+**Response:** 200 OK
+
+---
+
+## Usage Handlers
+
+### POST /usage
+Record a usage event for metered billing.
+
+**Authentication:** Required
+
+**Request Body:**
+```json
+{
+  "subscriptionId": "sub-123",
+  "addonCode": "extra_storage",
+  "meterEventName": "storage_gb",
+  "quantity": 50.5,
+  "action": "increment",
+  "idempotencyKey": "unique-key-123",
+  "metadata": {
+    "source": "api"
+  }
+}
+```
+
+**Response:** 201 Created
+
+### GET /usage/aggregate
+Get aggregated usage for a period.
+
+**Authentication:** Required
+
+**Query Parameters:**
+- `subscriptionId` (string, required)
+- `addonCode` (string, required)
+- `periodStart` (timestamp, required)
+- `periodEnd` (timestamp, required)
+
+**Response:** 200 OK
+```json
+{
+  "success": true,
+  "data": 150.75
+}
+```
+
+---
+
+## Authentication
+
+**Public Endpoints (no auth):**
+- GET /plans
+- GET /plans/{planId}
+- GET /addons
+- GET /addons/{addonId}
+- POST /discounts/validate
+
+**User Endpoints (auth required):**
+- POST /usage
+- GET /usage/aggregate
+
+**Admin Endpoints (admin auth required):**
+- POST /plans
+- PATCH /plans/{planId}
+- POST /addons
+- PATCH /addons/{addonId}
+- POST /discounts
+- GET /discounts/{discountId}
+
+---
+
+## Error Handling
+
+All handlers return standardized error responses:
+
+```json
+{
+  "success": false,
+  "message": "Error description",
+  "errorCode": "ERROR_CODE"
+}
+```
+
+**Common Error Codes:**
+- `VALIDATION_ERROR` - Invalid input
+- `NOT_FOUND` - Resource not found
+- `INTERNAL_ERROR` - Server error
+
+---
+
+## Deployment
+
+Each handler is designed to be deployed as a separate Lambda function with API Gateway integration.
+
+### Example SAM Template
+
+```yaml
+PlanListFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    CodeUri: src/geek_cafe_saas_sdk/domains/subscriptions/handlers/plans/list/
+    Handler: app.handler
+    Runtime: python3.11
+    Events:
+      ListPlans:
+        Type: Api
+        Properties:
+          Path: /plans
+          Method: get
+```
+
+---
+
+## Testing
+
+Handlers support dependency injection for testing:
+
+```python
+from handlers.plans.list.app import handler
+
+# Mock service
+class MockService:
+    def list_plans(self, **kwargs):
+        return ServiceResult.success_result([])
+
+# Test
+event = {"queryStringParameters": {"status": "active"}}
+response = handler(event, None, injected_service=MockService())
+```
+
+---
+
+## Request/Response Format
+
+### Request Format
+
+Handlers automatically convert camelCase to snake_case:
+
+```json
+{
+  "planCode": "pro",        // Converted to plan_code
+  "priceMonthly Cents": 2999  // Converted to price_monthly_cents
+}
+```
+
+### Response Format
+
+All responses follow the ServiceResult pattern:
+
+**Success:**
+```json
+{
+  "success": true,
+  "data": {...}
+}
+```
+
+**Error:**
+```json
+{
+  "success": false,
+  "message": "Error message",
+  "errorCode": "ERROR_CODE"
+}
+```
+
+---
+
+## Environment Variables
+
+Required environment variables:
+
+- `DYNAMODB_TABLE_NAME` - DynamoDB table name
+- `AWS_REGION` - AWS region
+
+---
+
+## Notes
+
+- Plan and addon handlers are public to allow pricing page display
+- Usage handlers require authentication to prevent abuse
+- Discount validation is public but discount management is admin-only
+- All admin operations should implement proper authorization checks

geek_cafe_saas_sdk/domains/subscriptions/handlers/__init__.py

@@ -0,0 +1 @@
+# Subscriptions Domain Handlers

geek_cafe_saas_sdk/domains/subscriptions/handlers/addons/create/app.py

@@ -0,0 +1,81 @@
+"""
+Lambda handler for creating addons.
+
+Admin endpoint - requires authentication.
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.subscriptions.services import SubscriptionManagerService
+
+
+handler_wrapper = create_handler(
+    service_class=SubscriptionManagerService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Create a new addon.
+    
+    Expected body:
+    {
+        "addonCode": "chat",
+        "addonName": "Chat Module",
+        "pricingModel": "fixed",
+        "priceMonthly Cents": 1500,
+        "description": "Real-time chat for your app",
+        "category": "communication"
+    }
+    
+    Returns 201 with created addon
+    """
+    return handler_wrapper.execute(event, context, create_addon, injected_service)
+
+
+def create_addon(
+    event: Dict[str, Any],
+    service: SubscriptionManagerService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for creating an addon.
+    """
+    payload = event["parsed_body"]
+    
+    # Extract required fields
+    addon_code = payload.get("addon_code")
+    if not addon_code:
+        raise ValueError("addon_code is required")
+    
+    addon_name = payload.get("addon_name")
+    if not addon_name:
+        raise ValueError("addon_name is required")
+    
+    pricing_model = payload.get("pricing_model", "fixed")
+    
+    # Build kwargs for optional fields
+    kwargs = {}
+    optional_fields = [
+        "description", "category", "status", "is_public", "sort_order",
+        "price_monthly_cents", "price_annual_cents", "currency",
+        "price_per_unit_cents", "unit_name", "included_units", "min_units", "max_units",
+        "pricing_tiers", "trial_days", "features", "limits",
+        "compatible_plan_codes", "incompatible_addon_codes", "feature_list",
+        "icon", "color", "is_metered", "meter_event_name", "billing_scheme"
+    ]
+    
+    for field in optional_fields:
+        if field in payload:
+            kwargs[field] = payload[field]
+    
+    result = service.create_addon(
+        addon_code=addon_code,
+        addon_name=addon_name,
+        pricing_model=pricing_model,
+        **kwargs
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/subscriptions/handlers/addons/get/app.py

@@ -0,0 +1,48 @@
+"""
+Lambda handler for getting an addon.
+
+Public endpoint - no authentication required.
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.subscriptions.services import SubscriptionManagerService
+
+
+handler_wrapper = create_handler(
+    service_class=SubscriptionManagerService,
+    require_auth=False,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Get an addon by ID.
+    
+    Path parameters:
+    - addonId: Addon ID
+    
+    Returns 200 with addon details
+    """
+    return handler_wrapper.execute(event, context, get_addon, injected_service)
+
+
+def get_addon(
+    event: Dict[str, Any],
+    service: SubscriptionManagerService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for getting an addon.
+    """
+    path_params = event.get("pathParameters") or {}
+    addon_id = path_params.get("addon_id")
+    
+    if not addon_id:
+        raise ValueError("addon_id is required in path")
+    
+    result = service.get_addon(addon_id=addon_id)
+    
+    return result

geek_cafe_saas_sdk/domains/subscriptions/handlers/addons/list/app.py

@@ -0,0 +1,54 @@
+"""
+Lambda handler for listing addons.
+
+Public endpoint - no authentication required.
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.subscriptions.services import SubscriptionManagerService
+
+
+handler_wrapper = create_handler(
+    service_class=SubscriptionManagerService,
+    require_auth=False,
+    require_body=False,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    List public addons.
+    
+    Query parameters:
+    - status: Filter by status (default: "active")
+    - category: Filter by category
+    - limit: Max results (default: 50)
+    
+    Returns 200 with list of addons
+    """
+    return handler_wrapper.execute(event, context, list_addons, injected_service)
+
+
+def list_addons(
+    event: Dict[str, Any],
+    service: SubscriptionManagerService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for listing addons.
+    """
+    params = event.get("queryStringParameters") or {}
+    
+    status = params.get("status", "active")
+    category = params.get("category")
+    limit = int(params.get("limit", "50"))
+    
+    result = service.list_addons(
+        status=status,
+        category=category,
+        limit=limit
+    )
+    
+    return result

geek_cafe_saas_sdk/domains/subscriptions/handlers/addons/update/app.py

@@ -0,0 +1,54 @@
+"""
+Lambda handler for updating addons.
+
+Admin endpoint - requires authentication.
+"""
+
+from typing import Dict, Any
+from geek_cafe_saas_sdk.lambda_handlers import create_handler
+from geek_cafe_saas_sdk.domains.subscriptions.services import SubscriptionManagerService
+
+
+handler_wrapper = create_handler(
+    service_class=SubscriptionManagerService,
+    require_body=True,
+    convert_case=True
+)
+
+
+def handler(event: Dict[str, Any], context: Any, injected_service=None) -> Dict[str, Any]:
+    """
+    Update an addon.
+    
+    Path parameters:
+    - addonId: Addon ID
+    
+    Body contains fields to update
+    
+    Returns 200 with updated addon
+    """
+    return handler_wrapper.execute(event, context, update_addon, injected_service)
+
+
+def update_addon(
+    event: Dict[str, Any],
+    service: SubscriptionManagerService,
+    user_context: Dict[str, str]
+) -> Any:
+    """
+    Business logic for updating an addon.
+    """
+    path_params = event.get("pathParameters") or {}
+    addon_id = path_params.get("addon_id")
+    
+    if not addon_id:
+        raise ValueError("addon_id is required in path")
+    
+    payload = event["parsed_body"]
+    
+    result = service.update_addon(
+        addon_id=addon_id,
+        updates=payload
+    )
+    
+    return result