integrations

External Integration Rules

Every external boundary in this codebase is shaped by 5 rules. Apply them every time you add or modify an integration.

1. Anti-Corruption Layer (ACL): provider returns GenerateResult | ProviderError

Provider adapters MUST translate vendor responses into our domain types. Never return dict, never let the vendor's field names cross the boundary.

# app/providers/_types.py
from dataclasses import dataclass
from decimal import Decimal

@dataclass(frozen=True)
class GenerateResult:
    url: str
    cost_usd: Decimal
    latency_ms: int
    provider_request_id: str

class ProviderError(Exception):
    def __init__(self, message: str, *, retryable: bool, code: str | None = None):
        super().__init__(message); self.retryable = retryable; self.code = code

class ProviderTimeout(ProviderError):
    def __init__(self, message: str): super().__init__(message, retryable=True, code="timeout")

class ProviderQuotaExceeded(ProviderError):
    def __init__(self, message: str): super().__init__(message, retryable=False, code="quota")

class ProviderInvalidRequest(ProviderError):
    def __init__(self, message: str): super().__init__(message, retryable=False, code="invalid_request")

# ✅ GOOD — adapter maps to ACL
class FalImageAdapter:
    def __init__(self, client: FalClient): self._c = client

    async def generate(self, req: ImageRequest) -> GenerateResult | ProviderError:
        try:
            data = await self._c.request("/v1/image", req.model_dump())
        except httpx.TimeoutException as e:
            return ProviderTimeout(str(e))
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                return ProviderQuotaExceeded(e.response.text)
            return ProviderError(e.response.text, retryable=False, code=str(e.response.status_code))
        return GenerateResult(
            url=data["images"][0]["url"],
            cost_usd=Decimal(str(data["billing"]["cost_usd"])),
            latency_ms=int(data["meta"]["latency_ms"]),
            provider_request_id=data["request_id"],
        )