msaas-integrations 0.1.0__tar.gz

msaas_integrations-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_integrations-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: msaas-integrations
+Version: 0.1.0
+Summary: Third-party integration framework for SaaS applications
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=44.0.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
+Provides-Extra: oauth
+Requires-Dist: httpx>=0.28.0; extra == 'oauth'

msaas_integrations-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "msaas-integrations"
+version = "0.1.0"
+description = "Third-party integration framework for SaaS applications"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "pydantic>=2.0",
+    "cryptography>=44.0.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115.0"]
+oauth = ["httpx>=0.28.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+    "fastapi>=0.115.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/integrations"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_integrations-0.1.0/src/integrations/__init__.py

@@ -0,0 +1,42 @@
+"""Willian Integrations -- Third-party integration framework for SaaS applications."""
+
+from integrations.config import (
+    IntegrationsConfig,
+    get_integrations,
+    init_integrations,
+    reset,
+)
+from integrations.crypto import CredentialEncryptor, FernetEncryptor
+from integrations.manager import IntegrationManager
+from integrations.models import (
+    APIKeyCredentials,
+    AuthType,
+    ConnectionStatus,
+    Integration,
+    IntegrationProvider,
+    IntegrationStatus,
+    OAuthCredentials,
+)
+from integrations.registry import ProviderRegistry, default_registry
+from integrations.store import InMemoryIntegrationStore, IntegrationStore
+
+__all__ = [
+    "APIKeyCredentials",
+    "AuthType",
+    "ConnectionStatus",
+    "CredentialEncryptor",
+    "FernetEncryptor",
+    "InMemoryIntegrationStore",
+    "Integration",
+    "IntegrationManager",
+    "IntegrationProvider",
+    "IntegrationStatus",
+    "IntegrationsConfig",
+    "IntegrationStore",
+    "OAuthCredentials",
+    "ProviderRegistry",
+    "default_registry",
+    "get_integrations",
+    "init_integrations",
+    "reset",
+]

msaas_integrations-0.1.0/src/integrations/config.py

@@ -0,0 +1,78 @@
+"""Module configuration and global singleton access."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+_config: IntegrationsConfig | None = None
+_manager: object | None = None
+
+
+class IntegrationsConfig(BaseModel):
+    """Configuration for the integrations module.
+
+    Args:
+        encryption_key: Fernet-compatible key used to encrypt credentials at rest.
+        oauth_redirect_base_url: Base URL appended with provider name for OAuth callbacks.
+        health_check_interval_seconds: Default interval between automatic health checks.
+    """
+
+    encryption_key: str
+    oauth_redirect_base_url: str = "http://localhost:8000/integrations/oauth/callback"
+    health_check_interval_seconds: int = 300
+
+
+def init_integrations(config: IntegrationsConfig) -> IntegrationsConfig:
+    """Initialize the integrations module.
+
+    Args:
+        config: Module configuration.
+
+    Returns:
+        The active IntegrationsConfig.
+    """
+    global _config, _manager
+    _config = config
+    _manager = None
+    return _config
+
+
+def get_config() -> IntegrationsConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_integrations() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Integrations module not initialized. Call init_integrations() first.")
+    return _config
+
+
+def get_integrations():
+    """Return or create the singleton IntegrationManager.
+
+    Raises:
+        RuntimeError: If init_integrations() has not been called.
+    """
+    global _manager
+    if _config is None:
+        raise RuntimeError("Integrations module not initialized. Call init_integrations() first.")
+    if _manager is None:
+        from integrations.manager import IntegrationManager
+        from integrations.registry import default_registry
+        from integrations.store import InMemoryIntegrationStore
+
+        _manager = IntegrationManager(
+            config=_config,
+            registry=default_registry(),
+            store=InMemoryIntegrationStore(),
+        )
+    return _manager
+
+
+def reset() -> None:
+    """Reset module state (useful for testing)."""
+    global _config, _manager
+    _config = None
+    _manager = None

msaas_integrations-0.1.0/src/integrations/crypto.py

@@ -0,0 +1,39 @@
+"""Credential encryption and decryption utilities.
+
+Uses Fernet symmetric encryption from the `cryptography` library behind
+a thin protocol so callers are not coupled to the concrete implementation.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol, runtime_checkable
+
+from cryptography.fernet import Fernet
+
+
+@runtime_checkable
+class CredentialEncryptor(Protocol):
+    """Protocol for encrypting / decrypting credential payloads."""
+
+    def encrypt(self, data: dict[str, Any]) -> bytes: ...
+    def decrypt(self, token: bytes) -> dict[str, Any]: ...
+
+
+class FernetEncryptor:
+    """Fernet-based credential encryptor.
+
+    Args:
+        key: A URL-safe base64-encoded 32-byte key (``Fernet.generate_key()``).
+    """
+
+    def __init__(self, key: str) -> None:
+        self._fernet = Fernet(key.encode() if isinstance(key, str) else key)
+
+    def encrypt(self, data: dict[str, Any]) -> bytes:
+        """Serialize *data* to JSON and return the Fernet-encrypted token."""
+        return self._fernet.encrypt(json.dumps(data).encode())
+
+    def decrypt(self, token: bytes) -> dict[str, Any]:
+        """Decrypt a Fernet token and deserialize the JSON payload."""
+        return json.loads(self._fernet.decrypt(token).decode())

msaas_integrations-0.1.0/src/integrations/manager.py

@@ -0,0 +1,221 @@
+"""Integration connection manager -- orchestrates connect/disconnect/refresh flows."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import urlencode
+
+from integrations.config import IntegrationsConfig
+from integrations.crypto import FernetEncryptor
+from integrations.models import (
+    APIKeyCredentials,
+    AuthType,
+    ConnectionStatus,
+    Integration,
+    IntegrationStatus,
+    OAuthCredentials,
+)
+from integrations.registry import ProviderRegistry
+from integrations.store import IntegrationStore
+
+
+class IntegrationManager:
+    """High-level manager for creating, refreshing, and checking integrations.
+
+    Args:
+        config: Module-level configuration (encryption key, redirect URL).
+        registry: Provider definitions catalogue.
+        store: Persistence backend for integration records.
+    """
+
+    def __init__(
+        self,
+        config: IntegrationsConfig,
+        registry: ProviderRegistry,
+        store: IntegrationStore,
+    ) -> None:
+        self._config = config
+        self._registry = registry
+        self._store = store
+        self._encryptor = FernetEncryptor(config.encryption_key)
+
+    # ── Properties ──────────────────────────────────────────────────────────
+
+    @property
+    def registry(self) -> ProviderRegistry:
+        return self._registry
+
+    @property
+    def store(self) -> IntegrationStore:
+        return self._store
+
+    # ── OAuth helpers ───────────────────────────────────────────────────────
+
+    def generate_auth_url(
+        self,
+        provider_name: str,
+        *,
+        client_id: str,
+        state: str | None = None,
+        extra_params: dict[str, str] | None = None,
+    ) -> str:
+        """Build the OAuth authorization redirect URL for a provider.
+
+        Args:
+            provider_name: Registered provider name.
+            client_id: OAuth application client ID.
+            state: Opaque state for CSRF protection.
+            extra_params: Additional query parameters.
+
+        Returns:
+            Full authorization URL ready for redirect.
+
+        Raises:
+            KeyError: If the provider is not registered.
+            ValueError: If the provider does not support OAuth.
+        """
+        provider = self._registry.get(provider_name)
+        if provider.auth_type != AuthType.OAUTH or not provider.oauth_authorize_url:
+            raise ValueError(f"Provider '{provider_name}' does not support OAuth")
+
+        params: dict[str, str] = {
+            "client_id": client_id,
+            "redirect_uri": f"{self._config.oauth_redirect_base_url}/{provider_name}",
+            "response_type": "code",
+        }
+        if provider.required_scopes:
+            params["scope"] = " ".join(provider.required_scopes)
+        if state:
+            params["state"] = state
+        if extra_params:
+            params.update(extra_params)
+
+        return f"{provider.oauth_authorize_url}?{urlencode(params)}"
+
+    # ── Connect flows ───────────────────────────────────────────────────────
+
+    async def connect_oauth(
+        self,
+        provider_name: str,
+        credentials: OAuthCredentials,
+        *,
+        name: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> Integration:
+        """Create an integration from an OAuth code exchange result.
+
+        The caller is responsible for exchanging the authorization code with
+        the provider's token endpoint; this method stores the resulting tokens.
+        """
+        provider = self._registry.get(provider_name)
+        encrypted = self._encryptor.encrypt(credentials.model_dump(mode="json"))
+
+        integration = Integration(
+            id=str(uuid.uuid4()),
+            name=name or provider.name,
+            provider=provider.name,
+            auth_type=AuthType.OAUTH,
+            status=IntegrationStatus.ACTIVE,
+            config=config or {},
+            credentials_encrypted=encrypted,
+        )
+        return await self._store.save(integration)
+
+    async def connect_api_key(
+        self,
+        provider_name: str,
+        credentials: APIKeyCredentials,
+        *,
+        name: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> Integration:
+        """Create an integration using an API key."""
+        provider = self._registry.get(provider_name)
+        encrypted = self._encryptor.encrypt(credentials.model_dump())
+
+        integration = Integration(
+            id=str(uuid.uuid4()),
+            name=name or provider.name,
+            provider=provider.name,
+            auth_type=AuthType.API_KEY,
+            status=IntegrationStatus.ACTIVE,
+            config=config or {},
+            credentials_encrypted=encrypted,
+        )
+        return await self._store.save(integration)
+
+    # ── Credential management ───────────────────────────────────────────────
+
+    def get_credentials(self, integration: Integration) -> dict[str, Any]:
+        """Decrypt and return credentials for an integration.
+
+        Raises:
+            ValueError: If the integration has no stored credentials.
+        """
+        if integration.credentials_encrypted is None:
+            raise ValueError("Integration has no stored credentials")
+        return self._encryptor.decrypt(integration.credentials_encrypted)
+
+    async def refresh_credentials(
+        self, integration_id: str, new_credentials: OAuthCredentials
+    ) -> Integration:
+        """Replace the stored credentials for an existing OAuth integration.
+
+        Raises:
+            KeyError: If the integration does not exist.
+        """
+        integration = await self._store.get(integration_id)
+        if integration is None:
+            raise KeyError(f"Integration '{integration_id}' not found")
+
+        encrypted = self._encryptor.encrypt(new_credentials.model_dump(mode="json"))
+        integration.credentials_encrypted = encrypted
+        integration.status = IntegrationStatus.ACTIVE
+        integration.updated_at = datetime.now(UTC)
+        return await self._store.save(integration)
+
+    # ── Disconnect ──────────────────────────────────────────────────────────
+
+    async def disconnect(self, integration_id: str) -> bool:
+        """Remove an integration.
+
+        Returns:
+            True if the integration was found and deleted.
+        """
+        return await self._store.delete(integration_id)
+
+    # ── Health ──────────────────────────────────────────────────────────────
+
+    async def check_health(self, integration_id: str) -> ConnectionStatus:
+        """Perform a basic health check on an integration.
+
+        Currently validates that the integration exists and has credentials.
+        Real implementations would call the provider's API to verify access.
+        """
+        integration = await self._store.get(integration_id)
+        now = datetime.now(UTC)
+
+        if integration is None:
+            return ConnectionStatus(
+                connected=False, last_checked=now, error_message="Integration not found"
+            )
+
+        if integration.credentials_encrypted is None:
+            return ConnectionStatus(
+                connected=False, last_checked=now, error_message="No credentials stored"
+            )
+
+        try:
+            self._encryptor.decrypt(integration.credentials_encrypted)
+        except Exception as exc:
+            integration.status = IntegrationStatus.ERROR
+            await self._store.save(integration)
+            return ConnectionStatus(
+                connected=False,
+                last_checked=now,
+                error_message=f"Credential decryption failed: {exc}",
+            )
+
+        return ConnectionStatus(connected=True, last_checked=now)

msaas_integrations-0.1.0/src/integrations/models.py

@@ -0,0 +1,83 @@
+"""Domain models for third-party integrations."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AuthType(StrEnum):
+    """Supported authentication mechanisms."""
+
+    OAUTH = "oauth"
+    API_KEY = "api_key"
+    WEBHOOK = "webhook"
+
+
+class IntegrationStatus(StrEnum):
+    """Lifecycle status of an integration connection."""
+
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    ERROR = "error"
+
+
+class OAuthCredentials(BaseModel):
+    """OAuth 2.0 credential set."""
+
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: datetime | None = None
+    scopes: list[str] = Field(default_factory=list)
+
+
+class APIKeyCredentials(BaseModel):
+    """API key credential set."""
+
+    api_key: str
+    header_name: str = "Authorization"
+
+
+class ConnectionStatus(BaseModel):
+    """Health check result for an integration connection."""
+
+    connected: bool
+    last_checked: datetime
+    error_message: str | None = None
+
+
+class IntegrationProvider(BaseModel):
+    """Definition of a third-party service provider.
+
+    Providers are registered in the ProviderRegistry and define
+    what is needed to connect to a service (auth type, scopes, URLs).
+    """
+
+    name: str
+    description: str = ""
+    auth_type: AuthType
+    oauth_authorize_url: str | None = None
+    oauth_token_url: str | None = None
+    required_scopes: list[str] = Field(default_factory=list)
+    config_schema: dict[str, Any] = Field(default_factory=dict)
+
+
+class Integration(BaseModel):
+    """A user's connection to a third-party provider.
+
+    Represents a configured and (optionally) authenticated link
+    between the application and an external service.
+    """
+
+    id: str
+    name: str
+    provider: str
+    auth_type: AuthType
+    status: IntegrationStatus = IntegrationStatus.INACTIVE
+    config: dict[str, Any] = Field(default_factory=dict)
+    credentials_encrypted: bytes | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

msaas_integrations-0.1.0/src/integrations/registry.py

@@ -0,0 +1,118 @@
+"""Provider registry -- catalogue of available third-party integrations."""
+
+from __future__ import annotations
+
+from integrations.models import AuthType, IntegrationProvider
+
+
+class ProviderRegistry:
+    """Thread-safe registry of IntegrationProvider definitions.
+
+    Providers are looked up by name (case-insensitive).
+    """
+
+    def __init__(self) -> None:
+        self._providers: dict[str, IntegrationProvider] = {}
+
+    def register(self, provider: IntegrationProvider) -> None:
+        """Register a provider definition.
+
+        Args:
+            provider: The provider to register.
+
+        Raises:
+            ValueError: If a provider with the same name already exists.
+        """
+        key = provider.name.lower()
+        if key in self._providers:
+            raise ValueError(f"Provider '{provider.name}' is already registered")
+        self._providers[key] = provider
+
+    def get(self, name: str) -> IntegrationProvider:
+        """Look up a provider by name (case-insensitive).
+
+        Raises:
+            KeyError: If the provider is not registered.
+        """
+        key = name.lower()
+        if key not in self._providers:
+            raise KeyError(f"Provider '{name}' not found")
+        return self._providers[key]
+
+    def list_providers(self) -> list[IntegrationProvider]:
+        """Return all registered providers sorted by name."""
+        return sorted(self._providers.values(), key=lambda p: p.name)
+
+    def __contains__(self, name: str) -> bool:
+        return name.lower() in self._providers
+
+    def __len__(self) -> int:
+        return len(self._providers)
+
+
+# ── Built-in provider definitions ───────────────────────────────────────────
+
+SLACK_PROVIDER = IntegrationProvider(
+    name="slack",
+    description="Slack workspace messaging",
+    auth_type=AuthType.OAUTH,
+    oauth_authorize_url="https://slack.com/oauth/v2/authorize",
+    oauth_token_url="https://slack.com/api/oauth.v2.access",
+    required_scopes=["chat:write", "channels:read"],
+    config_schema={
+        "type": "object",
+        "properties": {"team_id": {"type": "string"}},
+    },
+)
+
+GITHUB_PROVIDER = IntegrationProvider(
+    name="github",
+    description="GitHub repositories and issues",
+    auth_type=AuthType.OAUTH,
+    oauth_authorize_url="https://github.com/login/oauth/authorize",
+    oauth_token_url="https://github.com/login/oauth/access_token",
+    required_scopes=["repo", "read:user"],
+    config_schema={
+        "type": "object",
+        "properties": {"org": {"type": "string"}},
+    },
+)
+
+GOOGLE_PROVIDER = IntegrationProvider(
+    name="google",
+    description="Google Workspace (Drive, Calendar, Gmail)",
+    auth_type=AuthType.OAUTH,
+    oauth_authorize_url="https://accounts.google.com/o/oauth2/v2/auth",
+    oauth_token_url="https://oauth2.googleapis.com/token",
+    required_scopes=["openid", "email", "profile"],
+    config_schema={
+        "type": "object",
+        "properties": {"domain": {"type": "string"}},
+    },
+)
+
+STRIPE_PROVIDER = IntegrationProvider(
+    name="stripe",
+    description="Stripe payment processing",
+    auth_type=AuthType.API_KEY,
+    required_scopes=[],
+    config_schema={
+        "type": "object",
+        "properties": {"webhook_secret": {"type": "string"}},
+    },
+)
+
+BUILTIN_PROVIDERS: list[IntegrationProvider] = [
+    SLACK_PROVIDER,
+    GITHUB_PROVIDER,
+    GOOGLE_PROVIDER,
+    STRIPE_PROVIDER,
+]
+
+
+def default_registry() -> ProviderRegistry:
+    """Create a registry pre-loaded with all built-in providers."""
+    registry = ProviderRegistry()
+    for provider in BUILTIN_PROVIDERS:
+        registry.register(provider)
+    return registry