gsuite-sdk 0.1.0__py3-none-any.whl

gsuite_core/api_utils.py

@@ -0,0 +1,167 @@
+"""API utilities for consistent error handling and retries."""
+
+import logging
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import TypeVar
+
+from googleapiclient.errors import HttpError
+
+from gsuite_core.exceptions import (
+    APIError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def map_http_error(error: HttpError, service: str, resource_type: str = "resource") -> APIError:
+    """
+    Map Google API HttpError to domain exception.
+
+    Args:
+        error: The HttpError from Google API
+        service: Service name (gmail, calendar, drive, sheets)
+        resource_type: Type of resource for NotFoundError
+
+    Returns:
+        Appropriate GSuiteError subclass
+    """
+    status = error.resp.status
+    message = str(error)
+
+    if status == 404:
+        # Extract resource ID from error if possible
+        resource_id = "unknown"
+        return NotFoundError(service, resource_type, resource_id)
+    elif status == 403:
+        if "quota" in message.lower():
+            return QuotaExceededError(service)
+        return PermissionDeniedError(service, "operation")
+    elif status == 429:
+        # Try to extract retry-after header
+        retry_after = error.resp.get("retry-after")
+        return RateLimitError(service, int(retry_after) if retry_after else None)
+    else:
+        return APIError(message, service, status, cause=error)
+
+
+def api_call(
+    service: str,
+    resource_type: str = "resource",
+    retry_on_rate_limit: bool | None = None,
+    max_retries: int | None = None,
+    retry_delay: float | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorator for API calls with consistent error handling and retry logic.
+
+    Args:
+        service: Service name for error messages
+        resource_type: Resource type for NotFoundError
+        retry_on_rate_limit: Whether to retry on 429 errors
+        max_retries: Maximum retry attempts
+        retry_delay: Base delay between retries (exponential backoff)
+
+    Example:
+        @api_call("gmail", "message")
+        def get_message(self, message_id: str) -> Message:
+            ...
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            # Import here to avoid circular imports
+            from gsuite_core.config import get_settings
+
+            settings = get_settings()
+
+            # Use provided values or fall back to settings
+            _retry_on_rate_limit = (
+                retry_on_rate_limit
+                if retry_on_rate_limit is not None
+                else settings.retry_on_rate_limit
+            )
+            _max_retries = max_retries if max_retries is not None else settings.max_retries
+            _retry_delay = retry_delay if retry_delay is not None else settings.retry_delay
+
+            last_error = None
+
+            for attempt in range(_max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except HttpError as e:
+                    last_error = e
+                    status = e.resp.status
+
+                    # Retry on rate limit
+                    if status == 429 and _retry_on_rate_limit and attempt < _max_retries:
+                        wait_time = _retry_delay * (2**attempt)
+                        logger.warning(
+                            f"{service}: Rate limited, retrying in {wait_time:.1f}s "
+                            f"(attempt {attempt + 1}/{_max_retries})"
+                        )
+                        time.sleep(wait_time)
+                        continue
+
+                    # Retry on server errors (5xx)
+                    if 500 <= status < 600 and attempt < _max_retries:
+                        wait_time = _retry_delay * (2**attempt)
+                        logger.warning(
+                            f"{service}: Server error {status}, retrying in {wait_time:.1f}s "
+                            f"(attempt {attempt + 1}/{_max_retries})"
+                        )
+                        time.sleep(wait_time)
+                        continue
+
+                    # Don't retry other errors
+                    raise map_http_error(e, service, resource_type)
+
+            # Exhausted retries
+            if last_error:
+                raise map_http_error(last_error, service, resource_type)
+
+            # Should never reach here
+            raise RuntimeError("Unexpected state in api_call")
+
+        return wrapper
+
+    return decorator
+
+
+def api_call_optional(
+    service: str,
+    resource_type: str = "resource",
+) -> Callable[[Callable[..., T | None]], Callable[..., T | None]]:
+    """
+    Decorator for API calls that return None on 404 instead of raising.
+
+    Use for get-by-id operations where not-found is expected.
+
+    Example:
+        @api_call_optional("drive", "file")
+        def get(self, file_id: str) -> File | None:
+            ...
+    """
+
+    def decorator(func: Callable[..., T | None]) -> Callable[..., T | None]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> T | None:
+            try:
+                return func(*args, **kwargs)
+            except HttpError as e:
+                if e.resp.status == 404:
+                    logger.debug(f"{service}: {resource_type} not found")
+                    return None
+                raise map_http_error(e, service, resource_type)
+
+        return wrapper
+
+    return decorator

gsuite_core/auth/__init__.py

@@ -0,0 +1,6 @@
+"""Authentication module."""
+
+from gsuite_core.auth.oauth import GoogleAuth
+from gsuite_core.auth.scopes import Scopes
+
+__all__ = ["GoogleAuth", "Scopes"]

gsuite_core/auth/oauth.py

@@ -0,0 +1,249 @@
+"""Google OAuth2 authentication."""
+
+from pathlib import Path
+
+from google.auth.exceptions import RefreshError
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from gsuite_core.auth.scopes import Scopes
+from gsuite_core.config import get_settings
+from gsuite_core.exceptions import (
+    CredentialsNotFoundError,
+    TokenRefreshError,
+)
+from gsuite_core.storage import SQLiteTokenStore, TokenStore
+
+
+class GoogleAuth:
+    """
+    Google OAuth2 authentication handler.
+
+    Manages credential acquisition, refresh, and storage.
+    Supports both OAuth (interactive) and Service Account (server-to-server).
+
+    Example:
+        # OAuth (interactive)
+        auth = GoogleAuth()
+        auth.authenticate()  # Opens browser
+
+        # Service Account
+        auth = GoogleAuth.from_service_account("service-account.json")
+
+        # Use credentials
+        service = build("gmail", "v1", credentials=auth.credentials)
+    """
+
+    def __init__(
+        self,
+        token_store: TokenStore | None = None,
+        credentials_file: str | None = None,
+        scopes: list[str] | None = None,
+        user_id: str = "default",
+    ):
+        """
+        Initialize OAuth authenticator.
+
+        Args:
+            token_store: Storage backend for tokens (default: SQLite)
+            credentials_file: Path to OAuth credentials JSON
+            scopes: OAuth scopes to request (default: Gmail + Calendar)
+            user_id: User identifier for multi-user setups
+        """
+        settings = get_settings()
+
+        self.token_store = token_store or SQLiteTokenStore(settings.token_db_path)
+        self.credentials_file = Path(credentials_file or settings.credentials_file)
+        self.scopes = scopes or Scopes.default()
+        self.user_id = user_id
+        self._credentials: Credentials | None = None
+
+    @classmethod
+    def from_service_account(
+        cls,
+        service_account_file: str,
+        scopes: list[str] | None = None,
+        subject: str | None = None,
+    ) -> "GoogleAuth":
+        """
+        Create authenticator from service account.
+
+        Args:
+            service_account_file: Path to service account JSON
+            scopes: OAuth scopes
+            subject: Email to impersonate (for domain-wide delegation)
+
+        Returns:
+            GoogleAuth instance with service account credentials
+        """
+        instance = cls.__new__(cls)
+        instance.token_store = None
+        instance.credentials_file = Path(service_account_file)
+        instance.scopes = scopes or Scopes.default()
+        instance.user_id = "service_account"
+
+        creds = service_account.Credentials.from_service_account_file(
+            service_account_file,
+            scopes=instance.scopes,
+        )
+
+        if subject:
+            creds = creds.with_subject(subject)
+
+        instance._credentials = creds
+        return instance
+
+    @property
+    def credentials(self) -> Credentials | None:
+        """Get current credentials, loading from store if needed."""
+        if self._credentials is None:
+            self._load_credentials()
+        return self._credentials
+
+    def _load_credentials(self) -> None:
+        """Load credentials from token store."""
+        if self.token_store is None:
+            return
+
+        token_data = self.token_store.get_token(self.user_id)
+
+        if token_data:
+            self._credentials = Credentials.from_authorized_user_info(
+                token_data,
+                self.scopes,
+            )
+
+    def _save_credentials(self) -> None:
+        """Save current credentials to token store."""
+        if self._credentials and self.token_store:
+            token_data = {
+                "token": self._credentials.token,
+                "refresh_token": self._credentials.refresh_token,
+                "token_uri": self._credentials.token_uri,
+                "client_id": self._credentials.client_id,
+                "client_secret": self._credentials.client_secret,
+                "scopes": list(self._credentials.scopes or self.scopes),
+            }
+            self.token_store.save_token(token_data, self.user_id)
+
+    def is_authenticated(self) -> bool:
+        """Check if we have valid credentials."""
+        creds = self.credentials
+        return creds is not None and creds.valid
+
+    def needs_refresh(self) -> bool:
+        """Check if credentials need refresh."""
+        creds = self.credentials
+        if creds is None:
+            return False
+        return creds.expired and creds.refresh_token is not None
+
+    def refresh(self) -> bool:
+        """
+        Refresh expired credentials.
+
+        Returns:
+            True if refresh succeeded
+
+        Raises:
+            TokenRefreshError: If refresh fails
+        """
+        if not self.needs_refresh():
+            return False
+
+        try:
+            self._credentials.refresh(Request())
+            self._save_credentials()
+            return True
+        except RefreshError as e:
+            raise TokenRefreshError(cause=e) from e
+        except Exception as e:
+            raise TokenRefreshError(cause=e) from e
+
+    def authenticate(self, force: bool = False) -> Credentials:
+        """
+        Get valid credentials, running OAuth flow if needed.
+
+        Args:
+            force: Force new authentication even if credentials exist
+
+        Returns:
+            Valid Google credentials
+
+        Raises:
+            FileNotFoundError: If credentials file doesn't exist
+        """
+        if not force:
+            if self.is_authenticated():
+                return self._credentials
+
+            if self.needs_refresh() and self.refresh():
+                return self._credentials
+
+        if not self.credentials_file.exists():
+            raise CredentialsNotFoundError(str(self.credentials_file))
+
+        flow = InstalledAppFlow.from_client_secrets_file(
+            str(self.credentials_file),
+            self.scopes,
+        )
+
+        self._credentials = flow.run_local_server(
+            port=0,
+            prompt="consent",
+            access_type="offline",
+        )
+
+        self._save_credentials()
+        return self._credentials
+
+    def revoke(self) -> bool:
+        """
+        Revoke and delete stored credentials.
+
+        Returns:
+            True if credentials were deleted
+        """
+        self._credentials = None
+        if self.token_store:
+            return self.token_store.delete_token(self.user_id)
+        return False
+
+    def export_token(self) -> dict | None:
+        """
+        Export token data for external storage.
+
+        Returns:
+            Token data dict or None if not authenticated
+        """
+        if self._credentials:
+            return {
+                "token": self._credentials.token,
+                "refresh_token": self._credentials.refresh_token,
+                "token_uri": self._credentials.token_uri,
+                "client_id": self._credentials.client_id,
+                "client_secret": self._credentials.client_secret,
+                "scopes": list(self._credentials.scopes or self.scopes),
+            }
+        return None
+
+    def get_user_email(self) -> str | None:
+        """
+        Get authenticated user's email.
+
+        Returns:
+            Email address or None
+        """
+        if not self.is_authenticated():
+            return None
+
+        from googleapiclient.discovery import build
+
+        try:
+            service = build("oauth2", "v2", credentials=self._credentials)
+            user_info = service.userinfo().get().execute()
+            return user_info.get("email")
+        except Exception:
+            return None

gsuite_core/auth/scopes.py

@@ -0,0 +1,84 @@
+"""Google API OAuth scopes."""
+
+
+class Scopes:
+    """
+    Google API OAuth scopes.
+
+    Use these constants to request specific permissions.
+    """
+
+    # Gmail
+    GMAIL_READONLY = "https://www.googleapis.com/auth/gmail.readonly"
+    GMAIL_SEND = "https://www.googleapis.com/auth/gmail.send"
+    GMAIL_MODIFY = "https://www.googleapis.com/auth/gmail.modify"
+    GMAIL_LABELS = "https://www.googleapis.com/auth/gmail.labels"
+    GMAIL_FULL = "https://mail.google.com/"
+
+    # Calendar
+    CALENDAR_FULL = "https://www.googleapis.com/auth/calendar"
+    CALENDAR_EVENTS = "https://www.googleapis.com/auth/calendar.events"
+    CALENDAR_READONLY = "https://www.googleapis.com/auth/calendar.readonly"
+
+    # Drive
+    DRIVE_FULL = "https://www.googleapis.com/auth/drive"
+    DRIVE_FILE = "https://www.googleapis.com/auth/drive.file"
+    DRIVE_READONLY = "https://www.googleapis.com/auth/drive.readonly"
+    DRIVE_METADATA = "https://www.googleapis.com/auth/drive.metadata.readonly"
+
+    # Sheets
+    SHEETS_FULL = "https://www.googleapis.com/auth/spreadsheets"
+    SHEETS_READONLY = "https://www.googleapis.com/auth/spreadsheets.readonly"
+
+    # Tasks
+    TASKS_FULL = "https://www.googleapis.com/auth/tasks"
+    TASKS_READONLY = "https://www.googleapis.com/auth/tasks.readonly"
+
+    # Contacts/People
+    CONTACTS_READONLY = "https://www.googleapis.com/auth/contacts.readonly"
+
+    # User info
+    USERINFO_EMAIL = "https://www.googleapis.com/auth/userinfo.email"
+    USERINFO_PROFILE = "https://www.googleapis.com/auth/userinfo.profile"
+
+    @classmethod
+    def gmail(cls) -> list[str]:
+        """Standard Gmail scopes for read, send, modify."""
+        return [
+            cls.GMAIL_READONLY,
+            cls.GMAIL_SEND,
+            cls.GMAIL_MODIFY,
+            cls.GMAIL_LABELS,
+        ]
+
+    @classmethod
+    def calendar(cls) -> list[str]:
+        """Standard Calendar scopes."""
+        return [
+            cls.CALENDAR_FULL,
+            cls.CALENDAR_EVENTS,
+        ]
+
+    @classmethod
+    def drive(cls) -> list[str]:
+        """Standard Drive scopes."""
+        return [
+            cls.DRIVE_FULL,
+        ]
+
+    @classmethod
+    def sheets(cls) -> list[str]:
+        """Standard Sheets scopes."""
+        return [
+            cls.SHEETS_FULL,
+        ]
+
+    @classmethod
+    def all(cls) -> list[str]:
+        """All standard scopes for full access."""
+        return cls.gmail() + cls.calendar() + cls.drive() + cls.sheets()
+
+    @classmethod
+    def default(cls) -> list[str]:
+        """Default scopes (Gmail + Calendar)."""
+        return cls.gmail() + cls.calendar()

gsuite_core/config.py

@@ -0,0 +1,73 @@
+"""Application configuration."""
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """
+    Application settings loaded from environment variables.
+
+    Prefix: GSUITE_
+    Example: GSUITE_API_KEY=secret
+    """
+
+    # API settings
+    api_key: str | None = Field(default=None, description="API key for REST endpoints")
+    host: str = Field(default="0.0.0.0", description="Server host")
+    port: int = Field(default=8080, description="Server port")
+    version: str = Field(default="dev", description="API version")
+
+    # Google OAuth
+    credentials_file: str = Field(
+        default="credentials.json", description="Path to Google OAuth credentials file"
+    )
+
+    # Token storage backend
+    token_storage: Literal["sqlite", "secretmanager"] = Field(
+        default="sqlite", description="Token storage backend"
+    )
+
+    # SQLite storage
+    token_db_path: str = Field(default="tokens.db", description="Path to SQLite token database")
+
+    # Secret Manager (for Cloud Run)
+    gcp_project_id: str | None = Field(default=None, description="GCP project ID")
+    token_secret_name: str = Field(
+        default="gsuite-token", description="Secret name in Secret Manager"
+    )
+    token_secret_auto_create: bool = Field(
+        default=False, description="Auto-create secret if it doesn't exist"
+    )
+
+    # API behavior
+    default_timezone: str = Field(default="UTC", description="Default timezone for calendar events")
+    request_timeout: int = Field(default=30, description="HTTP request timeout in seconds")
+    max_retries: int = Field(default=3, description="Maximum retry attempts for failed requests")
+    retry_delay: float = Field(
+        default=1.0, description="Base delay between retries in seconds (exponential backoff)"
+    )
+    retry_on_rate_limit: bool = Field(
+        default=True, description="Whether to automatically retry on rate limit errors"
+    )
+
+    model_config = {
+        "env_prefix": "GSUITE_",
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "extra": "ignore",
+    }
+
+    def validate_for_secretmanager(self) -> None:
+        """Validate settings when using Secret Manager."""
+        if self.token_storage == "secretmanager" and not self.gcp_project_id:
+            raise ValueError("GSUITE_GCP_PROJECT_ID is required when using secretmanager storage")
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

gsuite_core/exceptions.py

@@ -0,0 +1,125 @@
+"""Google Suite exceptions."""
+
+
+class GSuiteError(Exception):
+    """Base exception for all Google Suite errors."""
+
+    def __init__(self, message: str, cause: Exception | None = None):
+        super().__init__(message)
+        self.message = message
+        self.cause = cause
+
+
+class AuthenticationError(GSuiteError):
+    """Authentication-related errors."""
+
+    pass
+
+
+class CredentialsNotFoundError(AuthenticationError):
+    """OAuth credentials file not found."""
+
+    def __init__(self, path: str):
+        super().__init__(
+            f"Credentials file not found: {path}\n"
+            "Download from Google Cloud Console -> APIs & Services -> Credentials"
+        )
+        self.path = path
+
+
+class TokenExpiredError(AuthenticationError):
+    """Token is expired and cannot be refreshed."""
+
+    def __init__(self):
+        super().__init__("Token expired and no refresh token available")
+
+
+class TokenRefreshError(AuthenticationError):
+    """Failed to refresh token."""
+
+    def __init__(self, cause: Exception | None = None):
+        super().__init__("Failed to refresh token", cause)
+
+
+class NotAuthenticatedError(AuthenticationError):
+    """Operation requires authentication but not authenticated."""
+
+    def __init__(self):
+        super().__init__("Not authenticated. Run authenticate() first")
+
+
+class APIError(GSuiteError):
+    """Google API call errors."""
+
+    def __init__(
+        self,
+        message: str,
+        service: str,
+        status_code: int | None = None,
+        cause: Exception | None = None,
+    ):
+        super().__init__(message, cause)
+        self.service = service
+        self.status_code = status_code
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded."""
+
+    def __init__(self, service: str, retry_after: int | None = None):
+        super().__init__(
+            f"Rate limit exceeded for {service}",
+            service=service,
+            status_code=429,
+        )
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(APIError):
+    """API quota exceeded."""
+
+    def __init__(self, service: str):
+        super().__init__(
+            f"API quota exceeded for {service}",
+            service=service,
+            status_code=403,
+        )
+
+
+class NotFoundError(APIError):
+    """Resource not found."""
+
+    def __init__(self, service: str, resource_type: str, resource_id: str):
+        super().__init__(
+            f"{resource_type} not found: {resource_id}",
+            service=service,
+            status_code=404,
+        )
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+
+
+class PermissionDeniedError(APIError):
+    """Permission denied for operation."""
+
+    def __init__(self, service: str, operation: str):
+        super().__init__(
+            f"Permission denied for {operation}",
+            service=service,
+            status_code=403,
+        )
+        self.operation = operation
+
+
+class ValidationError(GSuiteError):
+    """Input validation error."""
+
+    def __init__(self, field: str, message: str):
+        super().__init__(f"Validation error on {field}: {message}")
+        self.field = field
+
+
+class ConfigurationError(GSuiteError):
+    """Configuration error."""
+
+    pass