cloudflare-saas 1.0.0__tar.gz

cloudflare_saas-1.0.0/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: cloudflare-saas
+Version: 1.0.0
+Summary: Production-ready async library for multi-tenant SaaS platforms with Cloudflare R2 and Workers
+Home-page: https://github.com/innerkorehq/cloudflare-saas
+Author: innerkore
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cloudflare>=4.0.0
+Requires-Dist: aioboto3>=12.0.0
+Requires-Dist: aiodns>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-terraform>=0.10.1
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: pycares>=4.3.0
+Requires-Dist: botocore>=1.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.104.0; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "web"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Cloudflare R2 SaaS Platform Library
+
+A production-ready Python async library for building multi-tenant SaaS platforms with Cloudflare R2, Workers, and Custom Hostnames.
+
+[![Documentation Status](https://readthedocs.org/projects/cloudflare-saas/badge/?version=latest)](https://cloudflare-saas.readthedocs.io/en/latest/?badge=latest)
+
+## Features
+
+- ✅ Async R2 bucket operations (upload, delete, list)
+- ✅ Tenant management with namespace isolation
+- ✅ Custom domain onboarding with DNS verification
+- ✅ Cloudflare for SaaS custom hostname provisioning
+- ✅ Worker deployment automation via Terraform
+- ✅ **Configurable logging system** (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- ✅ **Multiple log formats** (simple, detailed, JSON)
+- ✅ Full error handling and retry logic
+- ✅ Type-safe with Pydantic models
+- ✅ Comprehensive documentation
+
+## Installation
+
+```bash
+pip install cloudflare aiodns aioboto3 pydantic python-terraform httpx tenacity
+```
+
+For PostgreSQL storage:
+
+```bash
+pip install asyncpg
+```
+
+For development:
+
+```bash
+pip install -e ".[dev,web]"
+```
+
+## Quick Start
+
+### Basic Usage with Logging
+
+```python
+import asyncio
+from cloudflare_saas import (
+    CloudflareSaaSPlatform, 
+    Config, 
+    configure_logging, 
+    LogLevel
+)
+
+async def main():
+    # Configure logging
+    configure_logging(level=LogLevel.INFO)
+    
+    # Load config from environment
+    config = Config.from_env()
+    
+    # Initialize platform
+    platform = CloudflareSaaSPlatform(config)
+    
+    # Create tenant
+    tenant = await platform.create_tenant("Acme Inc", "acme-123")
+    
+    # Deploy site
+    await platform.deploy_tenant_site(
+        tenant.tenant_id,
+        local_path="./acme-site"
+    )
+    
+    # Add custom domain
+    domain_status = await platform.add_custom_domain(
+        tenant.tenant_id,
+        "www.acme.com"
+    )
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+Required:
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_ZONE_ID`
+- `R2_ACCESS_KEY_ID`
+- `R2_SECRET_ACCESS_KEY`
+- `R2_BUCKET_NAME`
+- `PLATFORM_DOMAIN`
+
+Optional - Logging:
+- `LOG_LEVEL` (default: INFO) - DEBUG, INFO, WARNING, ERROR, CRITICAL
+- `LOG_FORMAT` (default: detailed) - simple, detailed, json
+- `LOG_FILE` - Path to log file (optional)
+- `ENABLE_CONSOLE_LOGGING` (default: true) - Enable console output
+
+### Programmatic Configuration
+
+```python
+from cloudflare_saas import Config
+
+config = Config(
+    cloudflare_api_token="your-token",
+    cloudflare_account_id="your-account",
+    cloudflare_zone_id="your-zone",
+    r2_access_key_id="your-r2-key",
+    r2_secret_access_key="your-r2-secret",
+    r2_bucket_name="yourplatform-sites",
+    platform_domain="yourplatform.com",
+    log_level="DEBUG",
+    log_format="json",
+    log_file="app.log"
+)
+```
+
+## Logging
+
+### Configure Logging
+
+```python
+from cloudflare_saas import configure_logging, LogLevel, LogFormat
+
+# Simple console logging
+configure_logging(level=LogLevel.INFO)
+
+# Detailed file logging
+configure_logging(
+    level=LogLevel.DEBUG,
+    log_format=LogFormat.DETAILED,
+    log_file="cloudflare-saas.log"
+)
+
+# JSON logging for production
+configure_logging(
+    level=LogLevel.WARNING,
+    log_format=LogFormat.JSON,
+    log_file="/var/log/cloudflare-saas.log",
+    enable_console=False
+)
+```
+
+### Log Levels
+
+- **DEBUG**: Detailed diagnostic information
+- **INFO**: General informational messages
+- **WARNING**: Warning messages
+- **ERROR**: Error messages
+- **CRITICAL**: Critical errors
+
+### Log Formats
+
+- **simple**: Minimal output `INFO: message`
+- **detailed**: With timestamps and source `2025-12-17 10:30:45 - Module - INFO - [file.py:65] - message`
+- **json**: Structured JSON for log aggregation
+
+### Using Loggers in Your Code
+
+```python
+from cloudflare_saas import get_logger, LoggerMixin
+
+# Get a logger
+logger = get_logger(__name__)
+logger.info("Starting operation")
+
+# Use in a class
+class MyService(LoggerMixin):
+    def do_work(self):
+        self.logger.info("Working...")
+```
+
+## Documentation
+
+Comprehensive documentation is available at [Read the Docs](https://cloudflare-saas.readthedocs.io/).
+
+### Build Documentation Locally
+
+```bash
+# Install documentation dependencies
+make install-docs
+
+# Build HTML documentation
+make docs
+
+# Serve documentation locally
+make docs-serve
+```
+
+Documentation includes:
+
+- **Getting Started Guide**: Quick start and installation
+- **Configuration Guide**: All configuration options
+- **Logging Guide**: Comprehensive logging documentation
+- **API Reference**: Complete API documentation
+- **Examples**: Practical code examples
+- **Deployment Guide**: Production deployment
+- **Contributing Guide**: Development guidelines
+
+## Development
+
+### Available Make Commands
+
+```bash
+make help          # Show all available commands
+
+# Development
+make install       # Install package
+make install-dev   # Install with dev dependencies
+make install-docs  # Install documentation dependencies
+
+# Testing
+make test          # Run tests
+make test-cov      # Run tests with coverage
+make test-watch    # Run tests in watch mode
+
+# Code Quality
+make lint          # Run linters (ruff, mypy)
+make format        # Format code (black, ruff)
+make check         # Run all checks (lint + test)
+
+# Documentation
+make docs          # Build documentation
+make docs-serve    # Build and serve documentation
+make docs-clean    # Clean documentation build
+
+# Docker
+make docker-build  # Build Docker image
+make docker-run    # Run Docker container
+make docker-stop   # Stop Docker containers
+
+# API
+make run-api       # Run FastAPI development server
+
+# Utilities
+make clean         # Clean build artifacts
+make clean-all     # Clean all generated files
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific test
+pytest tests/test_platform.py::test_create_tenant -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+make format
+
+# Check linting
+make lint
+
+# Run all checks
+make check
+```
+
+## Architecture
+
+See [cloudflare_r2_plan.md](./cloudflare_r2_plan.md) for detailed architecture.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./docs/source/contributing.rst) for guidelines.
+
+### Development Setup
+
+1. Fork and clone the repository
+2. Install development dependencies: `make install-dev`
+3. Create a branch for your feature
+4. Make your changes with tests
+5. Run tests and linting: `make check`
+6. Submit a pull request
+
+## License
+
+[Add your license here]
+
+## Support
+
+- **Documentation**: https://cloudflare-saas.readthedocs.io/
+- **Issues**: https://github.com/yourusername/cloudflare-saas/issues
+- **Discussions**: https://github.com/yourusername/cloudflare-saas/discussions

cloudflare_saas-1.0.0/README.md

@@ -0,0 +1,290 @@
+# Cloudflare R2 SaaS Platform Library
+
+A production-ready Python async library for building multi-tenant SaaS platforms with Cloudflare R2, Workers, and Custom Hostnames.
+
+[![Documentation Status](https://readthedocs.org/projects/cloudflare-saas/badge/?version=latest)](https://cloudflare-saas.readthedocs.io/en/latest/?badge=latest)
+
+## Features
+
+- ✅ Async R2 bucket operations (upload, delete, list)
+- ✅ Tenant management with namespace isolation
+- ✅ Custom domain onboarding with DNS verification
+- ✅ Cloudflare for SaaS custom hostname provisioning
+- ✅ Worker deployment automation via Terraform
+- ✅ **Configurable logging system** (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- ✅ **Multiple log formats** (simple, detailed, JSON)
+- ✅ Full error handling and retry logic
+- ✅ Type-safe with Pydantic models
+- ✅ Comprehensive documentation
+
+## Installation
+
+```bash
+pip install cloudflare aiodns aioboto3 pydantic python-terraform httpx tenacity
+```
+
+For PostgreSQL storage:
+
+```bash
+pip install asyncpg
+```
+
+For development:
+
+```bash
+pip install -e ".[dev,web]"
+```
+
+## Quick Start
+
+### Basic Usage with Logging
+
+```python
+import asyncio
+from cloudflare_saas import (
+    CloudflareSaaSPlatform, 
+    Config, 
+    configure_logging, 
+    LogLevel
+)
+
+async def main():
+    # Configure logging
+    configure_logging(level=LogLevel.INFO)
+    
+    # Load config from environment
+    config = Config.from_env()
+    
+    # Initialize platform
+    platform = CloudflareSaaSPlatform(config)
+    
+    # Create tenant
+    tenant = await platform.create_tenant("Acme Inc", "acme-123")
+    
+    # Deploy site
+    await platform.deploy_tenant_site(
+        tenant.tenant_id,
+        local_path="./acme-site"
+    )
+    
+    # Add custom domain
+    domain_status = await platform.add_custom_domain(
+        tenant.tenant_id,
+        "www.acme.com"
+    )
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+Required:
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_ZONE_ID`
+- `R2_ACCESS_KEY_ID`
+- `R2_SECRET_ACCESS_KEY`
+- `R2_BUCKET_NAME`
+- `PLATFORM_DOMAIN`
+
+Optional - Logging:
+- `LOG_LEVEL` (default: INFO) - DEBUG, INFO, WARNING, ERROR, CRITICAL
+- `LOG_FORMAT` (default: detailed) - simple, detailed, json
+- `LOG_FILE` - Path to log file (optional)
+- `ENABLE_CONSOLE_LOGGING` (default: true) - Enable console output
+
+### Programmatic Configuration
+
+```python
+from cloudflare_saas import Config
+
+config = Config(
+    cloudflare_api_token="your-token",
+    cloudflare_account_id="your-account",
+    cloudflare_zone_id="your-zone",
+    r2_access_key_id="your-r2-key",
+    r2_secret_access_key="your-r2-secret",
+    r2_bucket_name="yourplatform-sites",
+    platform_domain="yourplatform.com",
+    log_level="DEBUG",
+    log_format="json",
+    log_file="app.log"
+)
+```
+
+## Logging
+
+### Configure Logging
+
+```python
+from cloudflare_saas import configure_logging, LogLevel, LogFormat
+
+# Simple console logging
+configure_logging(level=LogLevel.INFO)
+
+# Detailed file logging
+configure_logging(
+    level=LogLevel.DEBUG,
+    log_format=LogFormat.DETAILED,
+    log_file="cloudflare-saas.log"
+)
+
+# JSON logging for production
+configure_logging(
+    level=LogLevel.WARNING,
+    log_format=LogFormat.JSON,
+    log_file="/var/log/cloudflare-saas.log",
+    enable_console=False
+)
+```
+
+### Log Levels
+
+- **DEBUG**: Detailed diagnostic information
+- **INFO**: General informational messages
+- **WARNING**: Warning messages
+- **ERROR**: Error messages
+- **CRITICAL**: Critical errors
+
+### Log Formats
+
+- **simple**: Minimal output `INFO: message`
+- **detailed**: With timestamps and source `2025-12-17 10:30:45 - Module - INFO - [file.py:65] - message`
+- **json**: Structured JSON for log aggregation
+
+### Using Loggers in Your Code
+
+```python
+from cloudflare_saas import get_logger, LoggerMixin
+
+# Get a logger
+logger = get_logger(__name__)
+logger.info("Starting operation")
+
+# Use in a class
+class MyService(LoggerMixin):
+    def do_work(self):
+        self.logger.info("Working...")
+```
+
+## Documentation
+
+Comprehensive documentation is available at [Read the Docs](https://cloudflare-saas.readthedocs.io/).
+
+### Build Documentation Locally
+
+```bash
+# Install documentation dependencies
+make install-docs
+
+# Build HTML documentation
+make docs
+
+# Serve documentation locally
+make docs-serve
+```
+
+Documentation includes:
+
+- **Getting Started Guide**: Quick start and installation
+- **Configuration Guide**: All configuration options
+- **Logging Guide**: Comprehensive logging documentation
+- **API Reference**: Complete API documentation
+- **Examples**: Practical code examples
+- **Deployment Guide**: Production deployment
+- **Contributing Guide**: Development guidelines
+
+## Development
+
+### Available Make Commands
+
+```bash
+make help          # Show all available commands
+
+# Development
+make install       # Install package
+make install-dev   # Install with dev dependencies
+make install-docs  # Install documentation dependencies
+
+# Testing
+make test          # Run tests
+make test-cov      # Run tests with coverage
+make test-watch    # Run tests in watch mode
+
+# Code Quality
+make lint          # Run linters (ruff, mypy)
+make format        # Format code (black, ruff)
+make check         # Run all checks (lint + test)
+
+# Documentation
+make docs          # Build documentation
+make docs-serve    # Build and serve documentation
+make docs-clean    # Clean documentation build
+
+# Docker
+make docker-build  # Build Docker image
+make docker-run    # Run Docker container
+make docker-stop   # Stop Docker containers
+
+# API
+make run-api       # Run FastAPI development server
+
+# Utilities
+make clean         # Clean build artifacts
+make clean-all     # Clean all generated files
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific test
+pytest tests/test_platform.py::test_create_tenant -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+make format
+
+# Check linting
+make lint
+
+# Run all checks
+make check
+```
+
+## Architecture
+
+See [cloudflare_r2_plan.md](./cloudflare_r2_plan.md) for detailed architecture.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./docs/source/contributing.rst) for guidelines.
+
+### Development Setup
+
+1. Fork and clone the repository
+2. Install development dependencies: `make install-dev`
+3. Create a branch for your feature
+4. Make your changes with tests
+5. Run tests and linting: `make check`
+6. Submit a pull request
+
+## License
+
+[Add your license here]
+
+## Support
+
+- **Documentation**: https://cloudflare-saas.readthedocs.io/
+- **Issues**: https://github.com/yourusername/cloudflare-saas/issues
+- **Discussions**: https://github.com/yourusername/cloudflare-saas/discussions

cloudflare_saas-1.0.0/cloudflare_saas/__init__.py

@@ -0,0 +1,70 @@
+"""
+Cloudflare R2 SaaS Platform Library
+
+A production-ready async library for multi-tenant SaaS platforms.
+"""
+
+from .platform import CloudflareSaaSPlatform
+from .config import Config
+from .logging_config import (
+    configure_logging,
+    get_logger,
+    LogLevel,
+    LogFormat,
+    LoggerMixin,
+)
+from .models import (
+    Tenant,
+    CustomDomain,
+    DomainStatus,
+    DeploymentResult,
+    VerificationMethod,
+    HostnameVerificationInstructions,
+)
+from .exceptions import (
+    CloudflareSaaSException,
+    TenantNotFoundError,
+    DomainVerificationError,
+    DeploymentError,
+    R2OperationError,
+    CustomHostnameError,
+    DNSError,
+)
+from .storage_adapter import StorageAdapter, InMemoryStorageAdapter
+from .postgres_adapter import PostgresStorageAdapter
+from .r2_client import R2Client
+from .cloudflare_client import CloudflareClient
+from .dns_verifier import DNSVerifier
+from .terraform_deployer import TerraformDeployer
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CloudflareSaaSPlatform",
+    "Config",
+    "configure_logging",
+    "get_logger",
+    "LogLevel",
+    "LogFormat",
+    "LoggerMixin",
+    "Tenant",
+    "CustomDomain",
+    "DomainStatus",
+    "DeploymentResult",
+    "VerificationMethod",
+    "HostnameVerificationInstructions",
+    "CloudflareSaaSException",
+    "TenantNotFoundError",
+    "DomainVerificationError",
+    "DeploymentError",
+    "R2OperationError",
+    "CustomHostnameError",
+    "DNSError",
+    "StorageAdapter",
+    "InMemoryStorageAdapter",
+    "PostgresStorageAdapter",
+    "R2Client",
+    "CloudflareClient",
+    "DNSVerifier",
+    "TerraformDeployer",
+]