Metadata-Version: 2.4
Name: geek_cafe_saas_sdk
Version: 0.118.0
Summary: Base Reusable Services for SaaS
Project-URL: Homepage, https://github.com/geek-cafe-saas-sdk
Project-URL: Documentation, https://github.com/geek-cafe-saas-sdk/blob/main/README.md
Project-URL: Source Code, https://github.com/geek-cafe-saas-sdk
Author-email: Eric Wilson <eric.wilson@geekcafe.com>
License: Geek Cafe Services Business Source License 1.0
        
        Copyright (c) 2025 Geek Cafe, LLC. All rights reserved.
        
        The "Geek Cafe Services" software (the "Software") is made available under this
        Business Source License (the "License"). This License allows you to view,
        study, and modify the source code, and to use it for personal, educational,
        research, or non-commercial purposes, subject to the following terms.
        
        1. Grant of Rights
           a. You may copy and modify the Software for your own personal,
              educational, or internal development use.
           b. You may not use the Software, or modified versions of it,
              to provide any commercial service or product, including
              software-as-a-service, consulting, hosting, or resale,
              without a separate commercial license from Geek Cafe LLC.
        
        2. Change Date
           Three (3) years from the date of first public release of a specific
           version of the Software (the “Change Date”), that version will
           automatically be made available under the Apache License 2.0.
           Later versions may have different Change Dates.
        
        3. Attribution
           All copies or substantial portions of the Software must retain this
           License text, the copyright notice above, and a clear reference to
           the original source repository (https://github.com/geekcafe/geek-cafe-services).
        
        4. Trademarks
           The names “Geek Cafe”, “Geek Cafe Services”, and any related logos are
           trademarks of Geek Cafe LLC and may not be used to endorse or promote
           derivative products without prior written permission.
        
        5. Disclaimer of Warranty
           THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
           EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
           OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
        6. Limitation of Liability
           IN NO EVENT SHALL GEEK Cafe LLC OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM,
           DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
           OTHERWISE, ARISING FROM OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
        
        ---
        
        For commercial licensing inquiries, contact:
        legal@geekcafe.com
License-File: LICENSE
Keywords: api gateway,aws,dynamodb,lambda,saas,serverless,services
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AWS CDK
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: boto3-assist
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# Geek Cafe Services

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-0.78.0-green.svg)](https://github.com/geekcafe/geek-cafe-services)
[![DynamoDB](https://img.shields.io/badge/database-DynamoDB-orange.svg)](https://aws.amazon.com/dynamodb/)
[![AWS Lambda](https://img.shields.io/badge/runtime-AWS%20Lambda-yellow.svg)](https://aws.amazon.com/lambda/)

> **⚠️ Beta Notice**: This library is under active development. Breaking changes may occur until we reach a stable 1.0 release. We recommend pinning to specific versions in production.

> **✨ New in v0.78.0**: Automatic security model, simplified handler patterns, and comprehensive pattern guides!

<!-- COVERAGE-BADGE:START -->
## Test Coverage

![Tests](https://img.shields.io/badge/tests-1929%20passed-brightgreen)
![Coverage](https://img.shields.io/badge/coverage-78.1%25-yellow)

**Overall Coverage:** 78.1% (20284/25964 statements)

### Coverage Summary

| Metric | Value |
|--------|-------|
| Total Statements | 25,964 |
| Covered Statements | 20,284 |
| Missing Statements | 5,680 |
| Coverage Percentage | 78.1% |
| Total Tests | 1929 |
| Test Status | ✅ All Passing |

### Files Needing Attention (< 80% coverage)

| Coverage | Missing Lines | File |
|----------|---------------|------|
| 0.0% | 2 | `modules/executions/handlers/__init__.py` |
| 0.0% | 2 | `modules/executions/handlers/get_status/__init__.py` |
| 0.0% | 2 | `modules/feature_flags/models/__init__.py` |
| 0.0% | 2 | `modules/feature_flags/services/__init__.py` |
| 0.0% | 2 | `modules/file_system/handlers/unarchive/__init__.py` |
| 0.0% | 10 | `modules/executions/handlers/get_status/app.py` |
| 0.0% | 12 | `modules/file_system/handlers/unarchive/app.py` |
| 0.0% | 21 | `core/models/base_async_event_model.py` |
| 0.0% | 115 | `modules/feature_flags/models/feature_flag.py` |
| 0.0% | 135 | `modules/executions/handlers/workflow_step_handler.py` |

*... and 60 more files with < 80% coverage*

### Running Tests

```bash
# Run all tests with coverage
./run_unit_tests.sh

# View detailed coverage report
open reports/coverage/index.html
```

*Last updated: 2026-01-01 15:14:41*

---

<!-- COVERAGE-BADGE:END -->

## Description

**Geek Cafe Services** is a production-ready, enterprise-grade library that provides reusable database services specifically designed for multi-tenant SaaS applications. Built on top of AWS DynamoDB, this library offers a prescriptive approach to building scalable, maintainable backend services with consistent patterns and best practices.

### Why Geek Cafe Services?

🏗️ **Consistent Architecture**: All services follow the same proven patterns for CRUD operations, error handling, and access control  
🔒 **Multi-Tenant by Design**: Built-in tenant isolation ensures secure data separation across customers  
⚡ **DynamoDB Optimized**: Leverages DynamoDB's strengths with efficient GSI indexes and query patterns  
🛡️ **Production Ready**: Comprehensive error handling, logging, pagination, and batch operations  
🧪 **Fully Tested**: 100% test coverage with comprehensive test suites for reliability  
📖 **Well Documented**: Extensive documentation with practical examples and best practices  

### Perfect For

- **SaaS Applications** requiring multi-tenant data isolation
- **Serverless Architectures** built on AWS Lambda and DynamoDB
- **Teams** wanting consistent, proven patterns across services
- **Rapid Development** with pre-built, tested service components

## Installation

```bash
# Clone the repository
git clone https://github.com/geekcafe/geek-cafe-services.git
cd geek-cafe-services

# Setup the development environment
./pysetup.sh

# Install dependencies
pip install -r requirements.txt
```

## Quick Start

### For Lambda Handlers (Recommended)

```python
from geek_cafe_saas_sdk.lambda_handlers import create_handler
from geek_cafe_saas_sdk.modules.workflows.services import WorkflowService

# Module-level handler for connection pooling
handler_wrapper = create_handler(
    service_class=WorkflowService,
    convert_request_case=True,   # camelCase → snake_case
    convert_response_case=True   # snake_case → camelCase
)

def lambda_handler(event, context, injected_service=None):
    return handler_wrapper.execute(event, context, business_logic, injected_service)

def business_logic(event, service):
    # Your business logic - security and case conversion are automatic!
    body = event.get("parsed_body") or {}
    result = service.create(**body)
    return {"execution_id": result.data.id, "status": "created"}
```

### For Direct Service Usage

```python
from geek_cafe_saas_sdk.modules.messaging.services import MessageService
from geek_cafe_saas_sdk.core import AnonymousContextFactory

# Create request context
context = AnonymousContextFactory.create_test_context(
    user_id='user_123',
    tenant_id='tenant_456'
)

# Initialize service with context
service = MessageService(request_context=context)

# Create a message - security is automatic!
result = service.create(
    type="notification",
    content={"title": "Welcome!", "body": "Thanks for joining."}
)

if result.success:
    print(f"Created message: {result.data.id}")
```

📖 **[Complete Quick Start Guide](./docs/help/QUICK_START.md)**

## Available Services

### 🚀 Lambda Handler Wrappers (NEW in v0.2.0)
**Purpose**: Eliminate 70-80% of boilerplate code in AWS Lambda functions

**Key Capabilities**:
- ✅ Automatic API key validation from environment
- ✅ Request body parsing and camelCase → snake_case conversion
- ✅ Service initialization with connection pooling for warm starts
- ✅ Built-in CORS and error handling
- ✅ User context extraction from authorizers
- ✅ Service injection for easy testing
- ✅ Support for public and secured endpoints

**Available Handlers**:
- `ApiKeyLambdaHandler` - API key validation (most common)
- `PublicLambdaHandler` - No authentication (config endpoints)
- `BaseLambdaHandler` - Extensible base for custom handlers

**Quick Example**:
```python
from geek_cafe_saas_sdk.lambda_handlers import ApiKeyLambdaHandler
from geek_cafe_saas_sdk.vote_service import VoteService

# All boilerplate handled in 3 lines
handler = ApiKeyLambdaHandler(
    service_class=VoteService,
    require_body=True,
    convert_case=True
)

def lambda_handler(event, context):
    return handler.execute(event, context, create_vote)

def create_vote(event, service, user_context):
    # Just your business logic - everything else is handled!
    payload = event["parsed_body"]  # Already parsed & converted
    return service.create_vote(
        tenant_id=user_context.get("tenant_id", "anonymous"),
        user_id=user_context.get("user_id", "anonymous"),
        **payload
    )
```

**Use Cases**: Any AWS Lambda function with API key auth, reducing code by 70-80% while maintaining all functionality

📖 **[Complete Lambda Handlers Documentation](./docs/lambda_handlers.md)**

### 📧 MessageService
**Purpose**: Complete message and notification management system

**Key Capabilities**:
- ✅ Full CRUD operations with tenant isolation
- ✅ Flexible JSON content storage for any message type
- ✅ Efficient querying by user, tenant, and message type
- ✅ Automatic audit trails and timestamps
- ✅ Built-in access control and validation

**Use Cases**: User notifications, system alerts, communication logs, announcement management

### 🗳️ Voting Services Suite
**Purpose**: Complete voting and rating system with real-time aggregation

**Architecture**: Three interconnected services working together:

#### VoteService
- ✅ Individual vote management with automatic upsert behavior
- ✅ One vote per user per target enforcement
- ✅ Support for up/down votes or custom vote types
- ✅ Comprehensive querying by user, target, and tenant

#### VoteSummaryService  
- ✅ Pre-calculated vote totals for instant retrieval
- ✅ Target-based optimization for high-performance lookups
- ✅ Metadata tracking (last tallied timestamp, vote counts)
- ✅ Tenant-scoped summary management

#### VoteTallyService
- ✅ Intelligent vote aggregation with pagination support
- ✅ Batch processing for multiple targets
- ✅ Stale target detection and automated re-tallying
- ✅ Comprehensive error handling and resilience

**Use Cases**: Product ratings, content voting, feedback systems, community polls, recommendation engines

## Documentation

📖 **[Documentation Index](./docs/DOCUMENTATION_INDEX.md)** - Complete documentation roadmap

### Core Pattern Guides (Start Here)
- **[DatabaseService Patterns](./docs/patterns/DATABASE_SERVICE_PATTERNS.md)** ⭐ - CRUD, security, queries, models
- **[Lambda Handler Patterns](./docs/patterns/LAMBDA_HANDLER_PATTERNS.md)** ⭐ - API Gateway & SQS handlers
- **[Security Architecture](./docs/SECURITY_ARCHITECTURE.md)** - Automatic security model
- **[Case Conversion Guide](./docs/CASE_CONVERSION_GUIDE.md)** - camelCase ↔ snake_case

### Module-Specific Guides
- **[File System](./docs/file-system/README_FILE_SYSTEM_SDK_USAGE.md)** - File management
- **[Workflows](./src/geek_cafe_saas_sdk/modules/workflows/)** - Execution & step models
- **[Messaging](./docs/api/CHAT_API.md)** - Chat & contact threads
- **[Events](./docs/events/EVENTS_DOMAIN.md)** - Event management
- **[Analytics](./docs/analytics/website_analytics_readme.md)** - Analytics tracking

### Configuration & Architecture
- **[Configuration Guide](./docs/CONFIG.md)** - Environment variables
- **[Architecture Overview](./docs/ARCHITECTURE.md)** - System design
- **[Service Pool Telemetry](./docs/SERVICE_POOL_TELEMETRY.md)** - Connection pooling

## Core Features

### 🏛️ **Enterprise Architecture**
- **Multi-Tenant by Design**: Complete tenant isolation with automatic access control
- **Consistent Patterns**: All services follow identical CRUD interfaces and conventions
- **Scalable Design**: Built for high-throughput, multi-customer SaaS applications

### 🔧 **Developer Experience**
- **Type Safety**: Full Python type hints for better IDE support and fewer bugs
- **Comprehensive Testing**: 100% test coverage with realistic test scenarios
- **Rich Documentation**: Detailed API docs, examples, and best practices
- **Easy Integration**: Simple initialization and consistent error handling

### ⚡ **Performance & Reliability**
- **DynamoDB Optimized**: Efficient GSI indexes and query patterns for fast operations
- **Pagination Support**: Handle large datasets without memory issues
- **Batch Operations**: Process multiple items efficiently
- **Error Resilience**: Graceful handling of partial failures and edge cases

### 🛡️ **Production Ready**
- **Structured Logging**: AWS Lambda Powertools integration for observability
- **Comprehensive Validation**: Input validation with detailed error messages  
- **Access Control**: Automatic tenant and user-based security enforcement
- **Audit Trails**: Complete tracking of who did what and when

## Environment Setup

```bash
# Required environment variables
export DYNAMODB_TABLE_NAME=your_table_name

# Optional AWS configuration (if not using IAM roles)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
```

## Testing

```bash
# Run all tests
pytest tests/ -v

# Run specific service tests
pytest tests/test_message_service.py -v
pytest tests/test_vote_*_service.py -v

# Run with coverage
pytest tests/ --cov=geek_cafe_saas_sdk --cov-report=html
```

## Project Structure

```
geek-cafe-services/
├── src/geek_cafe_saas_sdk/
│   ├── lambda_handlers/     # 🆕 Lambda handler wrappers (v0.2.0)
│   │   ├── base.py          # Base handler with common functionality
│   │   ├── api_key_handler.py    # API key validation handler
│   │   ├── public_handler.py     # Public (no auth) handler
│   │   └── service_pool.py       # Service connection pooling
│   ├── middleware/          # CORS, auth, error handling decorators
│   ├── utilities/           # Request/response helpers
│   ├── models/              # Data models with DynamoDB mapping
│   ├── *_service.py         # Service implementations
│   ├── database_service.py  # Base service class
│   └── service_result.py    # Standardized response wrapper
├── tests/                   # Comprehensive test suite
├── docs/                    # Detailed documentation
│   └── lambda_handlers.md   # 🆕 Lambda wrapper documentation
├── examples/                # Working code examples
│   └── lambda_handlers/     # 🆕 Handler examples
└── README.md               # This file
```

## Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository** and create a feature branch
2. **Follow the existing patterns** - consistency is key
3. **Add comprehensive tests** for any new functionality  
4. **Update documentation** for API changes
5. **Submit a Pull Request** with a clear description

### Development Guidelines

- Follow existing code style and patterns
- Maintain 100% test coverage for new code
- Update documentation for any API changes
- Use meaningful commit messages
- Test against multiple Python versions if possible

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📖 **Documentation**: [Complete docs](./docs/services_overview.md)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/geekcafe/geek-cafe-services/issues)
- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/geekcafe/geek-cafe-services/discussions)
- 📧 **Questions**: Create an issue with the "question" label

---

**Built with ❤️ for the SaaS development community**
