fh-saas 0.9.5__py3-none-any.whl

fh_saas/utils_email.py

@@ -0,0 +1,327 @@
+"""Send emails via SMTP using markdown templates with markdown_merge."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/05_utils_email.ipynb.
+
+# %% ../nbs/05_utils_email.ipynb 2
+from __future__ import annotations
+from typing import Optional, List, Dict, Any
+import os
+import logging
+from pathlib import Path
+from nbdev.showdoc import show_doc
+
+logger = logging.getLogger(__name__)
+
+# %% auto 0
+__all__ = ['logger', 'get_smtp_config', 'get_template_path', 'load_template', 'send_email', 'send_batch_emails',
+           'send_welcome_email', 'send_invitation_email', 'send_password_reset_email']
+
+# %% ../nbs/05_utils_email.ipynb 5
+def get_smtp_config() -> Dict[str, Any]:
+    """Load SMTP configuration from environment variables."""
+    smtp_host = os.getenv('SMTP_HOST')
+    smtp_port = int(os.getenv('SMTP_PORT', '587'))
+    smtp_user = os.getenv('SMTP_USER')
+    smtp_pass = os.getenv('SMTP_PASSWORD')
+    from_email = os.getenv('SMTP_MAIL_FROM')
+    
+    # SSL and TLS settings - check string and boolean values
+    smtp_ssl = os.getenv('SMTP_SSL', 'False')
+    use_ssl = smtp_ssl.lower() in ('true', '1', 'yes') if isinstance(smtp_ssl, str) else bool(smtp_ssl)
+    
+    smtp_starttls = os.getenv('SMTP_STARTTLS', 'True')
+    use_tls = smtp_starttls.lower() in ('true', '1', 'yes') if isinstance(smtp_starttls, str) else bool(smtp_starttls)
+    
+    # If SSL is enabled, disable TLS
+    if use_ssl:
+        use_tls = False
+    
+    # Validate required fields
+    if not all([smtp_host, smtp_user, smtp_pass, from_email]):
+        raise ValueError(
+            "SMTP_HOST, SMTP_USER, SMTP_PASSWORD, and SMTP_MAIL_FROM "
+            "environment variables are required"
+        )
+    
+    return {
+        'host': smtp_host,
+        'port': smtp_port,
+        'user': smtp_user,
+        'password': smtp_pass,
+        'from_email': from_email,
+        'from_name': '',  # Optional, can be added as SMTP_FROM_NAME if needed
+        'use_ssl': use_ssl,
+        'use_tls': use_tls
+    }
+
+# %% ../nbs/05_utils_email.ipynb 8
+def get_template_path(
+    template_name: str,  # Template basename (e.g., 'welcome', 'invitation')
+    custom_template_path: Optional[str | Path] = None  # Custom path overrides package templates
+) -> Path:
+    """Get absolute path to email template file."""
+    if custom_template_path:
+        custom_path = Path(custom_template_path)
+        if not custom_path.exists():
+            raise FileNotFoundError(f"Custom template not found: {custom_path}")
+        return custom_path
+    else:
+        package_dir = Path(__file__).parent if '__file__' in globals() else Path.cwd()
+        template_path = package_dir / 'templates' / f'{template_name}.md'
+        
+        if not template_path.exists():
+            raise FileNotFoundError(
+                f"Template not found: {template_path}\n"
+                f"Available templates: welcome, invitation, password_reset\n"
+                f"Or provide custom_template_path parameter"
+            )
+        
+        return template_path
+
+
+def load_template(
+    template_name: str,  # Template basename (e.g., 'welcome')
+    custom_template_path: Optional[str | Path] = None  # Custom path overrides package templates
+) -> str:
+    """Load markdown email template as string."""
+    template_path = get_template_path(template_name, custom_template_path)
+    return template_path.read_text(encoding='utf-8')
+
+# %% ../nbs/05_utils_email.ipynb 12
+def send_email(
+    to_email: str,  # Recipient email address
+    to_name: str,  # Recipient display name
+    subject: str,  # Email subject line
+    template_name: str,  # Template name: 'welcome', 'invitation', 'password_reset'
+    template_vars: Dict[str, str],  # Variables to substitute in template
+    test: bool = False,  # If True, prints email instead of sending
+    smtp_config: Optional[Dict[str, Any]] = None,  # Custom SMTP config (defaults to env vars)
+    custom_template_path: Optional[str | Path] = None  # Custom template path
+) -> Dict[str, Any]:
+    """Send single email using markdown template with variable substitution."""
+    try:
+        from markdown_merge import MarkdownMerge, get_addr
+    except ImportError:
+        raise ImportError(
+            "markdown_merge not installed. Install with: pip install markdown_merge"
+        )
+    
+    # Load SMTP config
+    if smtp_config is None:
+        config = get_smtp_config()
+    else:
+        config = smtp_config
+    
+    # Prepare SMTP config for markdown_merge
+    mm_smtp_cfg = {
+        'host': config['host'],
+        'port': config['port'],
+        'user': config['user'],
+        'password': config['password'],
+        'use_ssl': config.get('use_ssl', False),
+        'use_tls': config.get('use_tls', True)
+    }
+    
+    # Load template (supports custom path)
+    template = load_template(template_name, custom_template_path)
+    
+    # Prepare addresses
+    from_addr = get_addr(config['from_email'], config.get('from_name', ''))
+    to_addr = get_addr(to_email, to_name)
+    
+    # Create MarkdownMerge instance
+    mm = MarkdownMerge(
+        [to_addr],
+        from_addr,
+        subject,
+        template,
+        smtp_cfg=mm_smtp_cfg,
+        inserts=[template_vars],
+        test=test
+    )
+    
+    # Send email
+    try:
+        mm.send_msgs()
+        
+        if test:
+            logger.info(f"Test email printed for {to_email}")
+            return {
+                "status": "test",
+                "to_email": to_email,
+                "message": "Email printed (test mode)"
+            }
+        else:
+            logger.info(f"Email sent successfully to {to_email}")
+            return {
+                "status": "success",
+                "to_email": to_email,
+                "subject": subject
+            }
+    except Exception as e:
+        logger.error(f"Failed to send email to {to_email}: {str(e)}")
+        return {
+            "status": "error",
+            "to_email": to_email,
+            "error": str(e)
+        }
+
+# %% ../nbs/05_utils_email.ipynb 15
+def send_batch_emails(
+    recipients: List[Dict[str, str]],  # List of dicts with 'email' and 'name' keys
+    subject: str,  # Email subject line
+    template_name: str,  # Template name: 'welcome', 'invitation', 'password_reset'
+    template_vars_list: List[Dict[str, str]],  # List of variable dicts, one per recipient
+    test: bool = False,  # If True, prints emails instead of sending
+    pause: float = 0.2,  # Seconds between emails (rate limiting)
+    smtp_config: Optional[Dict[str, Any]] = None,  # Custom SMTP config
+    custom_template_path: Optional[str | Path] = None  # Custom template path
+) -> List[Dict[str, Any]]:
+    """Send personalized emails to multiple recipients."""
+    try:
+        from markdown_merge import MarkdownMerge, get_addr
+    except ImportError:
+        raise ImportError(
+            "markdown_merge not installed. Install with: pip install markdown_merge"
+        )
+    
+    # Load SMTP config
+    if smtp_config is None:
+        config = get_smtp_config()
+    else:
+        config = smtp_config
+    
+    # Prepare SMTP config for markdown_merge
+    mm_smtp_cfg = {
+        'host': config['host'],
+        'port': config['port'],
+        'user': config['user'],
+        'password': config['password'],
+        'use_ssl': config.get('use_ssl', False),
+        'use_tls': config.get('use_tls', True)
+    }
+    
+    # Load template (supports custom path)
+    template = load_template(template_name, custom_template_path)
+    
+    # Prepare addresses
+    from_addr = get_addr(config['from_email'], config.get('from_name', ''))
+    to_addrs = [get_addr(r['email'], r['name']) for r in recipients]
+    
+    # Create MarkdownMerge instance
+    mm = MarkdownMerge(
+        to_addrs,
+        from_addr,
+        subject,
+        template,
+        smtp_cfg=mm_smtp_cfg,
+        inserts=template_vars_list,
+        test=test
+    )
+    
+    # Send emails
+    results = []
+    try:
+        mm.send_msgs(pause=pause)
+        
+        for recipient in recipients:
+            if test:
+                results.append({
+                    "status": "test",
+                    "to_email": recipient['email'],
+                    "message": "Email printed (test mode)"
+                })
+            else:
+                results.append({
+                    "status": "success",
+                    "to_email": recipient['email'],
+                    "subject": subject
+                })
+        
+        logger.info(f"Sent {len(recipients)} emails successfully")
+    except Exception as e:
+        logger.error(f"Batch send failed: {str(e)}")
+        for recipient in recipients:
+            results.append({
+                "status": "error",
+                "to_email": recipient['email'],
+                "error": str(e)
+            })
+    
+    return results
+
+# %% ../nbs/05_utils_email.ipynb 18
+def send_welcome_email(
+    to_email: str,  # Recipient email address
+    to_name: str,  # Recipient display name
+    user_name: str,  # User's name for personalization
+    tenant_name: str,  # Tenant/organization name
+    dashboard_url: str,  # URL to user's dashboard
+    test: bool = False,  # If True, prints email instead of sending
+    custom_template_path: Optional[str | Path] = None  # Custom welcome.md template path
+) -> Dict[str, Any]:
+    """Send welcome email to new user. Template vars: {user_name}, {tenant_name}, {dashboard_url}, {to_email}"""
+    return send_email(
+        to_email=to_email,
+        to_name=to_name,
+        subject=f"Welcome to {tenant_name}!",
+        template_name='welcome',
+        template_vars={
+            'user_name': user_name,
+            'tenant_name': tenant_name,
+            'dashboard_url': dashboard_url,
+            'to_email': to_email
+        },
+        test=test,
+        custom_template_path=custom_template_path
+    )
+
+# %% ../nbs/05_utils_email.ipynb 20
+def send_invitation_email(
+    to_email: str,  # Recipient email address
+    to_name: str,  # Recipient display name
+    inviter_name: str,  # Name of person sending invitation
+    tenant_name: str,  # Tenant/organization name
+    invitation_url: str,  # URL to accept invitation
+    test: bool = False,  # If True, prints email instead of sending
+    custom_template_path: Optional[str | Path] = None  # Custom invitation.md template path
+) -> Dict[str, Any]:
+    """Send invitation email. Template vars: {inviter_name}, {tenant_name}, {invitation_url}, {to_email}"""
+    return send_email(
+        to_email=to_email,
+        to_name=to_name,
+        subject=f"{inviter_name} invited you to join {tenant_name}",
+        template_name='invitation',
+        template_vars={
+            'inviter_name': inviter_name,
+            'tenant_name': tenant_name,
+            'invitation_url': invitation_url,
+            'to_email': to_email
+        },
+        test=test,
+        custom_template_path=custom_template_path
+    )
+
+# %% ../nbs/05_utils_email.ipynb 22
+def send_password_reset_email(
+    to_email: str,  # Recipient email address
+    to_name: str,  # Recipient display name
+    user_name: str,  # User's name for personalization
+    reset_url: str,  # Secure password reset URL
+    test: bool = False,  # If True, prints email instead of sending
+    custom_template_path: Optional[str | Path] = None  # Custom password_reset.md template path
+) -> Dict[str, Any]:
+    """Send password reset email. Template vars: {user_name}, {reset_url}, {to_email}"""
+    return send_email(
+        to_email=to_email,
+        to_name=to_name,
+        subject="Reset Your Password",
+        template_name='password_reset',
+        template_vars={
+            'user_name': user_name,
+            'reset_url': reset_url,
+            'to_email': to_email
+        },
+        test=test,
+        custom_template_path=custom_template_path
+    )

fh_saas/utils_graphql.py

@@ -0,0 +1,257 @@
+"""GraphQL client with streaming pagination for memory-efficient data fetching."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/08_utils_graphql.ipynb.
+
+# %% ../nbs/08_utils_graphql.ipynb 2
+from __future__ import annotations
+from .utils_api import AsyncAPIClient, bearer_token_auth
+from typing import AsyncGenerator, Dict, Any, List, Optional
+from contextlib import asynccontextmanager
+import logging
+from nbdev.showdoc import show_doc
+
+logger = logging.getLogger(__name__)
+
+# %% auto 0
+__all__ = ['logger', 'GraphQLClient', 'execute_graphql']
+
+# %% ../nbs/08_utils_graphql.ipynb 5
+class GraphQLClient:
+    """GraphQL client with streaming pagination for memory-efficient data fetching."""
+    
+    def __init__(
+        self,
+        api_client: AsyncAPIClient, # Initialized AsyncAPIClient instance
+        endpoint: str = '' # GraphQL endpoint path (default: '' for base URL)
+    ):
+        self.api_client = api_client
+        self.endpoint = endpoint
+        self._owns_api = False  # Track if we created the API client
+    
+    @classmethod
+    @asynccontextmanager
+    async def from_url(
+        cls,
+        url: str, # GraphQL endpoint URL
+        bearer_token: str | None = None, # Optional bearer token for Authorization header
+        headers: dict | None = None # Optional additional headers
+    ):
+        """Create GraphQL client directly from URL with optional bearer token.
+        
+        Usage:
+            async with GraphQLClient.from_url(url, bearer_token=token) as gql:
+                result = await gql.execute(query)
+        """
+        # Merge auth with any additional headers
+        auth_headers = {}
+        if bearer_token:
+            auth_headers.update(bearer_token_auth(bearer_token))
+        if headers:
+            auth_headers.update(headers)
+        
+        async with AsyncAPIClient(
+            url,
+            auth_headers=auth_headers or None
+        ) as api:
+            client = cls(api)
+            client._owns_api = True
+            yield client
+    
+    async def execute(
+        self,
+        query: str, # GraphQL query or mutation string
+        variables: dict = None # Query/mutation variables
+    ) -> Dict[str, Any]:
+        """Execute a GraphQL query or mutation and return the data portion.
+        
+        This is a unified method that works for both queries and mutations.
+        Returns only the 'data' portion of the response for convenience.
+        """
+        payload = {'query': query}
+        if variables:
+            payload['variables'] = variables
+        
+        response = await self.api_client.request(
+            method='POST',
+            endpoint=self.endpoint,
+            json=payload
+        )
+        
+        data = response.json()
+        
+        # Check for GraphQL errors
+        if 'errors' in data:
+            error_msg = data['errors'][0].get('message', 'Unknown GraphQL error')
+            raise ValueError(f"GraphQL error: {error_msg}")
+        
+        return data.get('data', {})
+    
+    async def execute_query(
+        self,
+        query: str, # GraphQL query string
+        variables: dict = None # Query variables
+    ) -> Dict[str, Any]:
+        """Execute a single GraphQL query and return the JSON response."""
+        payload = {'query': query}
+        if variables:
+            payload['variables'] = variables
+        
+        response = await self.api_client.request(
+            method='POST',
+            endpoint=self.endpoint,
+            json=payload
+        )
+        
+        data = response.json()
+        
+        # Check for GraphQL errors
+        if 'errors' in data:
+            error_msg = data['errors'][0].get('message', 'Unknown GraphQL error')
+            raise ValueError(f"GraphQL error: {error_msg}")
+        
+        return data
+    
+    async def execute_mutation(
+        self,
+        mutation: str, # GraphQL mutation string
+        variables: dict = None # Mutation variables
+    ) -> Dict[str, Any]:
+        """Execute a GraphQL mutation (alias for execute_query)."""
+        return await self.execute_query(mutation, variables)
+    
+    async def fetch_pages_relay(
+        self,
+        query: str, # GraphQL query with $first and $after variables
+        connection_path: str, # Dot-notation path to connection object (e.g., "transactionsConnection")
+        variables: dict | None = None, # Base variables for the query (excluding first/after)
+        page_size: int = 100, # Number of items per page
+        max_pages: int | None = None # Maximum pages to fetch (None for unlimited)
+    ) -> list[dict]:
+        """Fetch all pages from a Relay-style paginated GraphQL query.
+        
+        Example query structure:
+            query($first: Int, $after: String, $filter: TransactionFilter) {
+                transactionsConnection(first: $first, after: $after, filter: $filter) {
+                    edges { node { id amount } }
+                    pageInfo { hasNextPage endCursor }
+                }
+            }
+        
+        Returns:
+            List of all nodes from all pages
+        """
+        all_nodes = []
+        cursor = None
+        page_count = 0
+        base_vars = variables or {}
+        
+        while True:
+            if max_pages and page_count >= max_pages:
+                logger.info(f"Reached max_pages limit of {max_pages}")
+                break
+            
+            page_vars = {**base_vars, "first": page_size, "after": cursor}
+            result = await self.execute(query, page_vars)
+            
+            # Navigate to connection using dot-notation path
+            connection = result
+            for key in connection_path.split('.'):
+                connection = connection.get(key, {})
+            
+            edges = connection.get('edges', [])
+            page_info = connection.get('pageInfo', {})
+            
+            for edge in edges:
+                all_nodes.append(edge['node'])
+            
+            page_count += 1
+            logger.info(f"Fetched page {page_count} with {len(edges)} edges")
+            
+            if not page_info.get('hasNextPage'):
+                break
+            
+            cursor = page_info.get('endCursor')
+        
+        return all_nodes
+    
+    async def fetch_pages_generator(
+        self,
+        query_template: str, # GraphQL query with $variables placeholders
+        variables: dict, # Initial variables (must include cursor key)
+        items_path: list[str], # JSONPath to list of items (e.g., ['data', 'users', 'nodes'])
+        cursor_path: list[str], # JSONPath to next cursor (e.g., ['data', 'users', 'pageInfo', 'endCursor'])
+        has_next_path: list[str] = None, # Optional path to hasNextPage boolean (if None, checks cursor != None)
+        cursor_var: str = 'cursor' # Variable name for cursor in query (default: 'cursor')
+    ) -> AsyncGenerator[List[Dict], None]:
+        """Stream paginated GraphQL data page-by-page using async generator."""
+        has_next = True
+        page_count = 0
+        
+        while has_next:
+            # Execute query with current cursor
+            response = await self.execute_query(query_template, variables)
+            
+            # Extract items using path
+            items = self._get_nested_value(response, items_path)
+            if not items:
+                logger.warning(f"No items found at path {items_path}")
+                break
+            
+            page_count += 1
+            logger.info(f"Fetched page {page_count} with {len(items)} items")
+            
+            # Yield batch (CRITICAL: do not accumulate)
+            yield items
+            
+            # Check if there's a next page
+            if has_next_path:
+                has_next = self._get_nested_value(response, has_next_path)
+            else:
+                # Fallback: check if cursor exists
+                next_cursor = self._get_nested_value(response, cursor_path)
+                has_next = next_cursor is not None
+            
+            # Update cursor for next iteration
+            if has_next:
+                next_cursor = self._get_nested_value(response, cursor_path)
+                variables[cursor_var] = next_cursor
+    
+    def _get_nested_value(
+        self, 
+        data: dict, 
+        path: list[str]
+    ) -> Any:
+        """Extract nested value from dict using path list."""
+        result = data
+        for key in path:
+            if isinstance(result, dict) and key in result:
+                result = result[key]
+            else:
+                return None
+        return result
+
+# %% ../nbs/08_utils_graphql.ipynb 14
+async def execute_graphql(
+    url: str, # GraphQL endpoint URL
+    query: str, # GraphQL query string
+    variables: dict | None = None, # Optional query variables
+    bearer_token: str | None = None, # Optional bearer token for Authorization header
+    headers: dict | None = None # Optional additional headers
+) -> dict:
+    """Execute a single GraphQL query without managing client lifecycle.
+    
+    This is a convenience function for one-off queries. For multiple queries,
+    use GraphQLClient.from_url() to reuse the connection.
+    
+    Usage:
+        result = await execute_graphql(
+            url="https://api.example.com/graphql",
+            query="query { users { id name } }",
+            bearer_token="your-token"
+        )
+    
+    Raises:
+        ValueError: If the response contains GraphQL errors
+    """
+    async with GraphQLClient.from_url(url, bearer_token=bearer_token, headers=headers) as gql:
+        return await gql.execute(query, variables)

fh_saas/utils_log.py

@@ -0,0 +1,56 @@
+"""One-time logging configuration for all fh_saas modules."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/06_utils_log.ipynb.
+
+# %% auto 0
+__all__ = ['configure_logging']
+
+# %% ../nbs/06_utils_log.ipynb 2
+import os
+import logging
+import logging.handlers
+from pathlib import Path
+
+# %% ../nbs/06_utils_log.ipynb 5
+def configure_logging(
+    log_file: str = None,
+    level: str = None,
+    max_bytes: int = 10_000_000,
+    backup_count: int = 5,
+):
+    """Configure logging for all fh_saas modules - call once at app startup."""
+    # Resolve level from env var or parameter
+    if level is None:
+        level = os.getenv('FH_SAAS_LOG_LEVEL', 'WARNING')
+    log_level = getattr(logging, level.upper(), logging.WARNING)
+    
+    # Resolve log file from env var or parameter
+    if log_file is None:
+        log_file = os.getenv('FH_SAAS_LOG_FILE')
+    
+    # Create formatter
+    formatter = logging.Formatter(
+        '%(asctime)s | %(name)s | %(levelname)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    # Create handlers
+    handlers = []
+    handlers.append(logging.StreamHandler())  # Always console
+    
+    # File handler (if specified)
+    if log_file:
+        Path(log_file).parent.mkdir(parents=True, exist_ok=True)
+        handlers.append(logging.handlers.RotatingFileHandler(
+            log_file, maxBytes=max_bytes, backupCount=backup_count
+        ))
+    
+    # Apply formatter to all handlers
+    for handler in handlers:
+        handler.setFormatter(formatter)
+    
+    # Configure fh_saas package logger
+    package_logger = logging.getLogger('fh_saas')
+    package_logger.setLevel(log_level)
+    package_logger.handlers = handlers
+    package_logger.propagate = False