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

geek_cafe_saas_sdk/utilities/string_functions.py

@@ -0,0 +1,180 @@
+import hashlib
+import secrets
+import string
+import uuid
+import time
+from geek_cafe_saas_sdk.utilities.logging_utility import LoggingUtility
+from geek_cafe_saas_sdk.utilities.datetime_utility import DatetimeUtility
+
+logger = LoggingUtility(__name__).logger
+
+
+class StringFunctions:
+    SPECIAL_CHARACTERS = "!\\#$%&()*+,-.:;<=>?@[]^_{|}~"
+
+    @staticmethod
+    def generate_random_string(length=12, digits=True, letters=True, special=False):
+        characters = ""
+        if letters:
+            characters += string.ascii_letters
+        if digits:
+            characters += string.digits
+        if special:
+            characters += StringFunctions.SPECIAL_CHARACTERS
+
+        random_string = "".join(secrets.choice(characters) for _ in range(length))
+        return random_string
+
+    @staticmethod
+    def generate_random_password(length=15, digits=True, letters=True, special=True):
+        characters = ""
+        # we have a min lenght requirement of 8
+        if length < 8:
+            length = 8
+
+        if letters:
+            characters += string.ascii_letters
+        if digits:
+            characters += string.digits
+        if special:
+            characters += StringFunctions.SPECIAL_CHARACTERS
+
+        if len(characters) == 0:
+            raise RuntimeError(
+                "You must choose at least one of the options: digits, letters, special"
+            )
+
+        # Ensure at least two characters from each selected set are included
+        password = []
+        if letters:
+            # lower
+            password.append(secrets.choice(string.ascii_lowercase))
+            password.append(secrets.choice(string.ascii_lowercase))
+            # upper
+            password.append(secrets.choice(string.ascii_uppercase))
+            password.append(secrets.choice(string.ascii_uppercase))
+        if digits:
+            password.append(secrets.choice(string.digits))
+            password.append(secrets.choice(string.digits))
+        if special:
+            password.append(secrets.choice(StringFunctions.SPECIAL_CHARACTERS))
+            password.append(secrets.choice(StringFunctions.SPECIAL_CHARACTERS))
+
+        # Fill the remaining length with random characters from the selected sets
+        remaining_length = length - len(password)
+        password.extend(secrets.choice(characters) for _ in range(remaining_length))
+
+        # Shuffle the password to randomize the order of characters
+        secrets.SystemRandom().shuffle(password)
+
+        return "".join(password)
+
+    @staticmethod
+    def wrap_text(text: str, max_width: int):
+        """Wrap text at a specified width."""
+        wrapped_text = ""
+        if not text:
+            return text
+
+        while len(text) > max_width:
+            # Find the maximum width position, breaking at max_width
+            # If there are no spaces to break on, break at max_width directly
+            break_point = (
+                text.rfind(" ", 0, max_width) if " " in text[0:max_width] else max_width
+            )
+            if break_point == -1:  # no spaces found, hard break
+                break_point = max_width
+            wrapped_text += text[:break_point] + "\n"
+            text = text[break_point:].lstrip()  # remove any leading space
+        wrapped_text += text
+        return wrapped_text
+
+    @staticmethod
+    def generate_uuid():
+        return str(uuid.uuid4())
+
+    @staticmethod
+    def generate_hash(input_string: str) -> str:
+        """
+        Generates a SHA-256 hash for the given input string.
+
+        Args:
+        input_string (str): The string to hash.
+
+        Returns:
+        str: The resulting hash value as a hexadecimal string.
+        """
+        # Encode the input string to bytes
+        encoded_string = input_string.encode()
+
+        # Create a SHA-256 hash object
+        hash_object = hashlib.sha256()
+
+        # Update the hash object with the encoded string
+        hash_object.update(encoded_string)
+
+        # Get the hexadecimal representation of the hash
+        hash_hex = hash_object.hexdigest()
+
+        return hash_hex
+
+    @staticmethod
+    def generate_sortable_uuid():
+        """
+        Generates a unique id for the execution event
+        """
+        epoch_time = time.time()
+        sortable_uuid: uuid.UUID = DatetimeUtility.uuid1_utc(timestamp=epoch_time)
+
+        time_stamp = str(epoch_time).replace(".", "-")
+        sortable_id = f"{time_stamp}:{str(sortable_uuid)}"
+        return sortable_id
+
+    @staticmethod
+    def to_bool(value: str | bool | int | None) -> bool:
+        """
+        Converts a string or boolean value to a boolean.
+
+        Args:
+            value (str | bool | int | None): The value to convert.
+
+        Returns:
+            bool: The converted boolean value.
+
+        Raises:
+            ValueError: If the input value is not a valid boolean or string representation.
+        """
+        return StringFunctions.to_boolean(value)
+
+    @staticmethod
+    def to_boolean(value: str | bool | int | None) -> bool:
+        """
+        Converts a string or boolean value to a boolean.
+
+        Args:
+            value (str | bool | int | None): The value to convert.
+
+        Returns:
+            bool: The converted boolean value.
+
+        Raises:
+            ValueError: If the input value is not a valid boolean or string representation.
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            value = str(value).lower().strip()
+            if value in ("true", "1", "t", "y", "yes"):
+                return True
+            if value in ("false", "0", "f", "n", "no"):
+                return False
+            else:
+                logger.warning(f"Invalid boolean value: {value}; returning False.")
+                return False
+
+        elif isinstance(value, int):
+            return bool(value)
+        elif value is None:
+            return False
+        else:
+            raise ValueError(f"Invalid boolean value: {value}")

geek_cafe_saas_sdk-0.6.0.dist-info/METADATA

@@ -0,0 +1,397 @@
+Metadata-Version: 2.4
+Name: geek_cafe_saas_sdk
+Version: 0.6.0
+Summary: Base Reusable Services for SaaS
+Project-URL: Homepage, https://github.com/geekcafe/geek-cafe-services
+Project-URL: Documentation, https://github.com/geekcafe/geek-cafe-services/blob/main/README.md
+Project-URL: Source Code, https://github.com/geekcafe/geek-cafe-services
+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.4.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/)
+
+> **⚠️ Pre-1.0 Notice**: This library is under active development. Breaking changes may occur until we reach a stable 1.0 GA release. We recommend pinning to specific versions in production.
+
+> **✨ New in v0.3.0**: Complete CRUDL Lambda handlers for all core resources (Events, Users, Groups, Messages, Votes)!
+
+<!-- COVERAGE-BADGE:START -->
+## Test Coverage
+
+![Tests](https://img.shields.io/badge/tests-1127%20passed-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-82.9%25-green)
+
+**Overall Coverage:** 82.9% (9325/11242 statements)
+
+### Coverage Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Statements | 11,242 |
+| Covered Statements | 9,325 |
+| Missing Statements | 1,917 |
+| Coverage Percentage | 82.9% |
+| Total Tests | 1127 |
+| Test Status | ✅ All Passing |
+
+### Files Needing Attention (< 80% coverage)
+
+| Coverage | Missing Lines | File |
+|----------|---------------|------|
+| 17.5% | 47 | `lambda_handlers/_base/authorized_secure_handler.py` |
+| 25.3% | 133 | `domains/communities/services/community_member_service.py` |
+| 46.3% | 58 | `domains/auth/models/role.py` |
+| 46.9% | 34 | `domains/auth/models/permission.py` |
+| 46.9% | 85 | `domains/auth/services/resource_permission_service.py` |
+| 56.2% | 7 | `lambda_handlers/_base/secure_handler.py` |
+| 58.5% | 17 | `domains/messaging/handlers/contact_threads/update/app.py` |
+| 62.3% | 118 | `utilities/lambda_event_utility.py` |
+| 63.4% | 86 | `domains/communities/services/community_service.py` |
+| 64.0% | 41 | `domains/files/services/s3_file_service.py` |
+
+*... and 20 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: 2025-10-15 22:38:06*
+
+---
+
+<!-- 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
+
+```python
+from geek_cafe_saas_sdk.message_service import MessageService
+
+# Initialize service
+service = MessageService()
+
+# Create a message
+result = service.create(
+    tenant_id="your_tenant",
+    user_id="your_user",
+    type="notification",
+    content={"title": "Welcome!", "body": "Thanks for joining us."}
+)
+
+if result.success:
+    print(f"Created message: {result.data.id}")
+```
+
+## 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
+
+📖 **[Complete Documentation](./docs/services_overview.md)**
+
+- **[DynamoDB Models](./docs/dynamodb_models.md)** - Model definition patterns and best practices
+- **[Services Pattern](./docs/services_pattern.md)** - Service layer architecture and CRUD operations
+- **[Lambda Handlers](./docs/lambda_handlers.md)** - 🆕 Eliminate Lambda boilerplate (70-80% code reduction)
+- [Services Overview](./docs/services_overview.md) - Architecture and common patterns
+- [MessageService](./docs/message_service.md) - Message management API
+- [Voting Services](./docs/voting_services.md) - Complete voting system documentation
+- [A/B Testing Guide](./docs/ab_testing_guide.md) - Using voting services for A/B testing and experimentation
+- [Development Roadmap](./docs/roadmap.md) - Planned improvements and enhancements
+
+## 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**