svc-infra 0.1.595__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/api/fastapi/versioned.py

@@ -0,0 +1,101 @@
+"""
+Utilities for capturing routers from add_* functions for versioned routing.
+
+This module provides helpers to use integration functions (add_banking, add_payments, etc.)
+under versioned routing without creating separate documentation cards.
+
+See: svc-infra/docs/versioned-integrations.md
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+from unittest.mock import patch
+
+from fastapi import APIRouter, FastAPI
+
+__all__ = ["extract_router"]
+
+T = TypeVar("T")
+
+
+def extract_router(
+    add_function: Callable[..., T],
+    *,
+    prefix: str,
+    **kwargs: Any,
+) -> tuple[APIRouter, T]:
+    """
+    Capture the router from an add_* function for versioned mounting.
+
+    This allows you to use integration functions like add_banking(), add_payments(),
+    etc. under versioned routing (e.g., /v0/banking) without creating separate
+    documentation cards.
+
+    Args:
+        add_function: The add_* function to capture from (e.g., add_banking)
+        prefix: URL prefix for the routes (e.g., "/banking")
+        **kwargs: Arguments to pass to the add_function
+
+    Returns:
+        Tuple of (router, return_value) where:
+        - router: The captured APIRouter with all routes
+        - return_value: The original return value from add_function (e.g., provider instance)
+
+    Example:
+        ```python
+        # In routers/v0/banking.py
+        from svc_infra.api.fastapi.versioned import extract_router
+        from fin_infra.banking import add_banking
+
+        router, banking_provider = extract_router(
+            add_banking,
+            prefix="/banking",
+            provider="plaid",
+            cache_ttl=60,
+        )
+
+        # svc-infra auto-discovers 'router' and mounts at /v0/banking
+        ```
+
+    Pattern:
+        1. Creates a mock FastAPI app
+        2. Intercepts include_router to capture the router
+        3. Patches add_prefixed_docs to prevent separate card creation
+        4. Calls the add_function which creates all routes
+        5. Returns the captured router for auto-discovery
+
+    See Also:
+        - docs/versioned-integrations.md: Full pattern documentation
+        - api/fastapi/dual/public.py: Similar pattern for dual routers
+    """
+    # Create mock app to capture router
+    mock_app = FastAPI()
+    captured_router: APIRouter | None = None
+
+    def _capture_router(router: APIRouter, **_kwargs: Any) -> None:
+        """Intercept include_router to capture instead of mount."""
+        nonlocal captured_router
+        captured_router = router
+
+    setattr(mock_app, "include_router", _capture_router)
+
+    # Patch add_prefixed_docs to prevent separate card (no-op if function doesn't call it)
+    def _noop_docs(*args: Any, **kwargs: Any) -> None:
+        pass
+
+    # Call add_function with patches active
+    with patch("svc_infra.api.fastapi.docs.scoped.add_prefixed_docs", _noop_docs):
+        result = add_function(
+            mock_app,
+            prefix=prefix,
+            **kwargs,
+        )
+
+    if captured_router is None:
+        raise RuntimeError(
+            f"Failed to capture router from {add_function.__name__}. "
+            f"The function may not call app.include_router()."
+        )
+
+    return captured_router, result

svc_infra/app/README.md

@@ -14,9 +14,8 @@ This README shows:
 
 ```python
 # main.py (or wherever your app starts)
-from svc_infra.logging.logging import setup_logging
+from svc_infra.app.logging import setup_logging, LogLevelOptions
 from svc_infra.app.env import pick
-from svc_infra.logging.logging import LogLevelOptions
 ```
 
 ---
@@ -39,7 +38,8 @@ What you get by default:
 Set via code:
 
 ```python
-from svc_infra.logging.logging import LogFormatOptions, LogLevelOptions
+from svc_infra.app.logging.formats import LogFormatOptions
+from svc_infra.app.logging import LogLevelOptions
 
 setup_logging(
     level=LogLevelOptions.INFO,          # or "INFO"
@@ -119,7 +119,7 @@ Old (pre-filter) example:
 
 ```python
 from svc_infra.app.env import pick
-from svc_infra.logging.logging import setup_logging, LogLevelOptions
+from svc_infra.app.logging import setup_logging, LogLevelOptions
 
 setup_logging(
     level=pick(
@@ -183,7 +183,7 @@ LOG_DROP_PATHS=/metrics,/health,/healthz
 ## 7) One-liner quickstart
 
 ```python
-from svc_infra.logging import setup_logging
+from svc_infra.app.logging import setup_logging
 setup_logging()  # done: sensible defaults + filters in prod/test
 ```
 

svc_infra/app/__init__.py

@@ -1,4 +1,4 @@
-from .env import pick
+from .env import MissingSecretError, pick, require_secret
 from .logging import setup_logging
 from .logging.formats import LoggingConfig, LogLevelOptions
 
@@ -7,4 +7,6 @@ __all__ = [
     "LoggingConfig",
     "LogLevelOptions",
     "pick",
+    "require_secret",
+    "MissingSecretError",
 ]

svc_infra/app/env.py

@@ -129,7 +129,9 @@ def pick(*, prod, nonprod=None, dev=None, test=None, local=None):
         return local
     if nonprod is not None:
         return nonprod
-    raise ValueError("pick(): No value found for environment and 'nonprod' was not provided.")
+    raise ValueError(
+        "pick(): No value found for environment and 'nonprod' was not provided."
+    )
 
 
 def find_env_file(start: Optional[Path] = None) -> Optional[Path]:
@@ -166,3 +168,69 @@ def prepare_env() -> Path:
     env_file = find_env_file(start=root)
     load_env_if_present(env_file, override=False)
     return root
+
+
+class MissingSecretError(RuntimeError):
+    """Raised when a required secret is not configured in production/staging."""
+
+    pass
+
+
+def require_secret(
+    value: str | None,
+    name: str,
+    *,
+    dev_default: str | None = None,
+    environments: tuple[str, ...] = ("prod", "production", "staging", "test"),
+) -> str:
+    """Require a secret to be set in production environments.
+
+    In development/local environments, falls back to dev_default if provided.
+    In production environments, raises MissingSecretError if not set.
+
+    Args:
+        value: The secret value (may be None or empty)
+        name: Name of the secret for error messages (e.g., "SESSION_SECRET")
+        dev_default: Default value to use in development (NEVER in production)
+        environments: Environments where the secret is required
+
+    Returns:
+        The secret value
+
+    Raises:
+        MissingSecretError: If secret is not set in production environments
+
+    Example:
+        >>> secret = require_secret(
+        ...     os.getenv("SESSION_SECRET"),
+        ...     "SESSION_SECRET",
+        ...     dev_default="dev-only-secret",
+        ... )
+    """
+    if value:
+        return value
+
+    current_env = get_current_environment()
+
+    # Check if we're in a production-like environment
+    raw_env = os.getenv("APP_ENV") or os.getenv("RAILWAY_ENVIRONMENT_NAME") or ""
+    is_production_like = (
+        current_env == PROD_ENV
+        or current_env == TEST_ENV  # staging/preview
+        or raw_env.lower() in environments
+    )
+
+    if is_production_like:
+        raise MissingSecretError(
+            f"SECURITY ERROR: {name} must be set in production/staging environments. "
+            f"Current environment: {current_env} (raw: {raw_env!r})"
+        )
+
+    # In development, use the dev default if provided
+    if dev_default is not None:
+        return dev_default
+
+    raise MissingSecretError(
+        f"{name} is not set and no dev_default was provided. "
+        "Either set the environment variable or provide a dev_default."
+    )

svc_infra/app/logging/add.py

@@ -3,10 +3,13 @@ from __future__ import annotations
 import logging
 import os
 from logging.config import dictConfig
-from typing import Sequence
+from typing import TYPE_CHECKING, Sequence, cast
 
 from svc_infra.app.env import CURRENT_ENVIRONMENT
 
+if TYPE_CHECKING:
+    from .formats import LogFormatOptions, LogLevelOptions
+
 from .filter import filter_logs_for_paths
 from .formats import (
     JsonFormatter,
@@ -27,7 +30,11 @@ def setup_logging(
 ) -> None:
     """Configure logging + optional access-log path filtering."""
     if fmt is not None or level is not None:
-        LoggingConfig(fmt=fmt, level=level)  # pydantic validation
+        # Cast to expected Literal types after validation
+        LoggingConfig(
+            fmt=cast("LogFormatOptions | None", fmt),
+            level=cast("LogLevelOptions | None", level),
+        )  # pydantic validation
 
     if level is None:
         level = _read_level()

svc_infra/app/logging/formats.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 import os
 from enum import StrEnum
-from typing import Sequence
+from typing import Sequence, cast
 
 from pydantic import BaseModel
 
@@ -35,7 +35,7 @@ class LoggingConfig(BaseModel):
 class JsonFormatter(logging.Formatter):
     """Structured JSON formatter for prod and CI logs."""
 
-    def format(self, record: logging.LogRecord) -> str:  # type: ignore[override]
+    def format(self, record: logging.LogRecord) -> str:
         import json
         import os as _os
         from traceback import format_exception
@@ -50,15 +50,19 @@ class JsonFormatter(logging.Formatter):
 
         # Add these two lines:
         if getattr(record, "trace_id", None):
-            payload["trace_id"] = record.trace_id
+            payload["trace_id"] = record.trace_id  # type: ignore[attr-defined]
         if getattr(record, "span_id", None):
-            payload["span_id"] = record.span_id
+            payload["span_id"] = record.span_id  # type: ignore[attr-defined]
 
         # Optional correlation id
         req_id = getattr(record, "request_id", None)
         if req_id is not None:
             payload["request_id"] = req_id
 
+        tenant_id = getattr(record, "tenant_id", None)
+        if tenant_id is not None:
+            payload["tenant_id"] = tenant_id
+
         # Optional HTTP context
         http_ctx = {
             k: v
@@ -103,7 +107,10 @@ def _read_level() -> str:
         return explicit.upper()
     from svc_infra.app.env import pick
 
-    return pick(prod="INFO", nonprod="DEBUG", dev="DEBUG", test="DEBUG", local="DEBUG").upper()
+    return cast(
+        str,
+        pick(prod="INFO", nonprod="DEBUG", dev="DEBUG", test="DEBUG", local="DEBUG"),
+    ).upper()
 
 
 def _read_format() -> str:

svc_infra/billing/__init__.py

@@ -0,0 +1,23 @@
+from .models import (
+    Invoice,
+    InvoiceLine,
+    Plan,
+    PlanEntitlement,
+    Price,
+    Subscription,
+    UsageAggregate,
+    UsageEvent,
+)
+from .service import BillingService
+
+__all__ = [
+    "UsageEvent",
+    "UsageAggregate",
+    "Plan",
+    "PlanEntitlement",
+    "Subscription",
+    "Price",
+    "Invoice",
+    "InvoiceLine",
+    "BillingService",
+]

svc_infra/billing/async_service.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+
+class AsyncBillingService:
+    def __init__(self, session: AsyncSession, tenant_id: str):
+        self.session = session
+        self.tenant_id = tenant_id
+
+    async def record_usage(
+        self,
+        *,
+        metric: str,
+        amount: int,
+        at: datetime,
+        idempotency_key: str,
+        metadata: dict | None,
+    ) -> str:
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        await self.session.flush()
+        return evt.id
+
+    async def aggregate_daily(self, *, metric: str, day_start: datetime) -> int:
+        day_start = day_start.replace(
+            hour=0, minute=0, second=0, microsecond=0, tzinfo=timezone.utc
+        )
+        next_day = day_start + timedelta(days=1)
+        total = 0
+        rows: Sequence[UsageEvent] = (
+            (
+                await self.session.execute(
+                    select(UsageEvent).where(
+                        UsageEvent.tenant_id == self.tenant_id,
+                        UsageEvent.metric == metric,
+                        UsageEvent.at_ts >= day_start,
+                        UsageEvent.at_ts < next_day,
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in rows:
+            total += int(r.amount)
+
+        agg = (
+            await self.session.execute(
+                select(UsageAggregate).where(
+                    UsageAggregate.tenant_id == self.tenant_id,
+                    UsageAggregate.metric == metric,
+                    UsageAggregate.period_start == day_start,
+                    UsageAggregate.granularity == "day",
+                )
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+        return total
+
+    async def list_daily_aggregates(
+        self, *, metric: str, date_from: Optional[datetime], date_to: Optional[datetime]
+    ) -> list[UsageAggregate]:
+        q = select(UsageAggregate).where(
+            UsageAggregate.tenant_id == self.tenant_id,
+            UsageAggregate.metric == metric,
+            UsageAggregate.granularity == "day",
+        )
+        if date_from is not None:
+            q = q.where(UsageAggregate.period_start >= date_from)
+        if date_to is not None:
+            q = q.where(UsageAggregate.period_start < date_to)
+        rows = list((await self.session.execute(q)).scalars().all())
+        return rows
+
+    async def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        total = 0
+        aggs: Sequence[UsageAggregate] = (
+            (
+                await self.session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == self.tenant_id,
+                        UsageAggregate.period_start >= period_start,
+                        UsageAggregate.period_start < period_end,
+                        UsageAggregate.granularity == "day",
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in aggs:
+            total += int(r.total)
+
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        await self.session.flush()
+
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        return inv.id