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

svc_infra/__init__.py

@@ -1,3 +1,59 @@
-from . import api, app
+"""svc-infra: Service Infrastructure Toolkit.
 
-__all__ = ["app", "api"]
+A comprehensive backend infrastructure library providing:
+- API framework (FastAPI scaffolding, dual routers, auth)
+- Database (SQL/Mongo, migrations, repositories)
+- Caching (Redis, decorators)
+- Jobs (background tasks, queues)
+- Webhooks (delivery, subscriptions)
+- Billing (Stripe/Adyen integration)
+- Observability (logging, metrics)
+
+Example:
+    from svc_infra.api.fastapi import easy_service_app
+    from svc_infra.api.fastapi.auth import add_auth_users
+
+    app = easy_service_app(name="MyAPI")
+    add_auth_users(app)
+"""
+
+from __future__ import annotations
+
+# Core modules (lazy import pattern for optional dependencies)
+from . import api, app, cache, db, jobs, webhooks
+
+# Base exception
+from .exceptions import SvcInfraError
+
+# Content Loaders
+from .loaders import (
+    BaseLoader,
+    GitHubLoader,
+    LoadedContent,
+    URLLoader,
+    load_github,
+    load_github_sync,
+    load_url,
+    load_url_sync,
+)
+
+__all__ = [
+    # Core modules
+    "api",
+    "app",
+    "cache",
+    "db",
+    "jobs",
+    "webhooks",
+    # Base exception
+    "SvcInfraError",
+    # Loaders
+    "BaseLoader",
+    "GitHubLoader",
+    "LoadedContent",
+    "URLLoader",
+    "load_github",
+    "load_github_sync",
+    "load_url",
+    "load_url_sync",
+]

svc_infra/apf_payments/models.py

@@ -1,9 +1,17 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Optional
 
-from sqlalchemy import JSON, Boolean, DateTime, Index, Numeric, String, UniqueConstraint, text
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    Index,
+    Numeric,
+    String,
+    UniqueConstraint,
+    text,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from svc_infra.db.sql.authref import user_fk_constraint, user_id_type
@@ -21,7 +29,7 @@ class PayCustomer(ModelBase):
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
     # Always typed to match the actual auth PK; FK is enforced at table level
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
 
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_customer_id: Mapped[str] = mapped_column(
@@ -29,7 +37,9 @@ class PayCustomer(ModelBase):
     )
 
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (
@@ -46,7 +56,7 @@ class PayIntent(ModelBase):
 
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
 
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_intent_id: Mapped[str] = mapped_column(
@@ -55,11 +65,13 @@ class PayIntent(ModelBase):
     amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)  # minor units
     currency: Mapped[str] = mapped_column(String(8), nullable=False)
     status: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
-    client_secret: Mapped[Optional[str]] = mapped_column(String(255))
+    client_secret: Mapped[str | None] = mapped_column(String(255))
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
-    confirmed_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    confirmed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     captured: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
 
     __table_args__ = (
@@ -82,7 +94,9 @@ class PayEvent(ModelBase):
     )
     type: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
     received_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
     payload_json: Mapped[dict] = mapped_column(JSON, nullable=False)  # compact JSON string
 
@@ -102,8 +116,8 @@ class LedgerEntry(ModelBase):
     )
 
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
-    provider_ref: Mapped[Optional[str]] = mapped_column(String(128), index=True)
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    provider_ref: Mapped[str | None] = mapped_column(String(128), index=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
     amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
     currency: Mapped[str] = mapped_column(String(8), nullable=False)
     kind: Mapped[str] = mapped_column(String(24), nullable=False)  # payment|refund|fee|payout...
@@ -130,19 +144,21 @@ class PayPaymentMethod(ModelBase):
 
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_customer_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
     provider_method_id: Mapped[str] = mapped_column(
         String(128), unique=True, index=True, nullable=False
     )
-    brand: Mapped[Optional[str]] = mapped_column(String(32))
-    last4: Mapped[Optional[str]] = mapped_column(String(8))
-    exp_month: Mapped[Optional[int]] = mapped_column(Numeric(2, 0))
-    exp_year: Mapped[Optional[int]] = mapped_column(Numeric(4, 0))
+    brand: Mapped[str | None] = mapped_column(String(32))
+    last4: Mapped[str | None] = mapped_column(String(8))
+    exp_month: Mapped[int | None] = mapped_column(Numeric(2, 0))
+    exp_year: Mapped[int | None] = mapped_column(Numeric(4, 0))
     is_default: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (
@@ -170,7 +186,9 @@ class PayProduct(ModelBase):
     name: Mapped[str] = mapped_column(String(128), nullable=False)
     active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -188,11 +206,13 @@ class PayPrice(ModelBase):
     provider_product_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
     currency: Mapped[str] = mapped_column(String(8), nullable=False)
     unit_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)  # minor units
-    interval: Mapped[Optional[str]] = mapped_column(String(16))  # month|year|week|day
-    trial_days: Mapped[Optional[int]] = mapped_column(Numeric(5, 0))
+    interval: Mapped[str | None] = mapped_column(String(16))  # month|year|week|day
+    trial_days: Mapped[int | None] = mapped_column(Numeric(5, 0))
     active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -203,7 +223,7 @@ class PaySubscription(ModelBase):
 
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_customer_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
     provider_subscription_id: Mapped[str] = mapped_column(
@@ -215,9 +235,11 @@ class PaySubscription(ModelBase):
     )  # active|trialing|canceled|past_due|incomplete
     quantity: Mapped[int] = mapped_column(Numeric(10, 0), default=1, nullable=False)
     cancel_at_period_end: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    current_period_end: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    current_period_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (
@@ -238,7 +260,7 @@ class PayInvoice(ModelBase):
 
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_invoice_id: Mapped[str] = mapped_column(
         String(128), unique=True, index=True, nullable=False
@@ -249,10 +271,12 @@ class PayInvoice(ModelBase):
     )  # draft|open|paid|void|uncollectible
     amount_due: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
     currency: Mapped[str] = mapped_column(String(8), nullable=False)
-    hosted_invoice_url: Mapped[Optional[str]] = mapped_column(String(255))
-    pdf_url: Mapped[Optional[str]] = mapped_column(String(255))
+    hosted_invoice_url: Mapped[str | None] = mapped_column(String(255))
+    pdf_url: Mapped[str | None] = mapped_column(String(255))
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (
@@ -273,7 +297,7 @@ class PaySetupIntent(ModelBase):
 
     tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
 
-    user_id: Mapped[Optional[str]] = mapped_column(user_id_type(), index=True, nullable=True)
+    user_id: Mapped[str | None] = mapped_column(user_id_type(), index=True, nullable=True)
     provider: Mapped[str] = mapped_column(String(32), index=True, nullable=False)
     provider_setup_intent_id: Mapped[str] = mapped_column(
         String(128), unique=True, index=True, nullable=False
@@ -281,9 +305,11 @@ class PaySetupIntent(ModelBase):
     status: Mapped[str] = mapped_column(
         String(32), index=True, nullable=False
     )  # requires_action|succeeded|canceled|processing
-    client_secret: Mapped[Optional[str]] = mapped_column(String(255))
+    client_secret: Mapped[str | None] = mapped_column(String(255))
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
     __table_args__ = (
@@ -303,16 +329,18 @@ class PayDispute(ModelBase):
     provider_dispute_id: Mapped[str] = mapped_column(
         String(128), unique=True, index=True, nullable=False
     )
-    provider_charge_id: Mapped[Optional[str]] = mapped_column(String(128), index=True)
+    provider_charge_id: Mapped[str | None] = mapped_column(String(128), index=True)
     amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
     currency: Mapped[str] = mapped_column(String(8), nullable=False)
-    reason: Mapped[Optional[str]] = mapped_column(String(64))
+    reason: Mapped[str | None] = mapped_column(String(64))
     status: Mapped[str] = mapped_column(
         String(32), index=True, nullable=False
     )  # needs_response|under_review|won|lost|warning_closed
-    evidence_due_by: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    evidence_due_by: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )
 
 
@@ -332,8 +360,10 @@ class PayPayout(ModelBase):
     status: Mapped[str] = mapped_column(
         String(32), index=True, nullable=False
     )  # pending|in_transit|paid|canceled|failed
-    arrival_date: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
-    type: Mapped[Optional[str]] = mapped_column(String(32))  # bank_account|card|...
+    arrival_date: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    type: Mapped[str | None] = mapped_column(String(32))  # bank_account|card|...
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
     )

svc_infra/apf_payments/provider/__init__.py

@@ -1,4 +1,4 @@
-from .aiydan import AiydanAdapter  # noqa: F401
-from .stripe import StripeAdapter  # noqa: F401
+from .aiydan import AiydanAdapter
+from .stripe import StripeAdapter
 
 __all__ = ["AiydanAdapter", "StripeAdapter"]

svc_infra/apf_payments/provider/aiydan.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import inspect
-from datetime import date, datetime, timezone
-from typing import Any, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from datetime import UTC, date, datetime
+from typing import Any, Literal, cast
 
 from svc_infra.apf_payments.schemas import (
     BalanceAmount,
@@ -43,9 +44,9 @@ from svc_infra.apf_payments.settings import get_payments_settings
 from .base import ProviderAdapter
 
 try:  # pragma: no cover - optional dependency
-    import aiydan  # type: ignore
+    import aiydan
 except Exception:  # pragma: no cover - handled at runtime
-    aiydan = None  # type: ignore
+    aiydan = None
 
 
 async def _maybe_await(result: Any) -> Any:
@@ -62,24 +63,25 @@ def _coerce_id(data: dict[str, Any], *candidates: str) -> str:
     raise RuntimeError(f"Aiydan payload missing id fields: {candidates}")
 
 
-def _ensure_utc_isoformat(value: Any) -> Optional[str]:
+def _ensure_utc_isoformat(value: Any) -> str | None:
     if value is None:
         return None
     if isinstance(value, str):
         return value
     if isinstance(value, datetime):
-        if value.tzinfo is None:
-            value = value.replace(tzinfo=timezone.utc)
-        return value.astimezone(timezone.utc).isoformat()
+        dt: datetime = value
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=UTC)
+        return dt.astimezone(UTC).isoformat()
     if isinstance(value, date):
-        return datetime(value.year, value.month, value.day, tzinfo=timezone.utc).isoformat()
+        return datetime(value.year, value.month, value.day, tzinfo=UTC).isoformat()
     try:
         parsed = datetime.fromisoformat(str(value))
         if parsed.tzinfo is None:
-            parsed = parsed.replace(tzinfo=timezone.utc)
-        return parsed.astimezone(timezone.utc).isoformat()
+            parsed = parsed.replace(tzinfo=UTC)
+        return parsed.astimezone(UTC).isoformat()
     except Exception:
-        return str(value)
+        return cast("str", str(value))  # Cast needed since value is Any
 
 
 def _customer_to_out(data: dict[str, Any]) -> CustomerOut:
@@ -208,12 +210,15 @@ def _invoice_line_item_to_out(data: dict[str, Any]) -> InvoiceLineItemOut:
     price = data.get("price") or {}
     if not isinstance(price, dict):
         price = {"id": getattr(price, "id", None)}
+    quantity = int(data.get("quantity", 0) or 0)
+    unit_amount = int(data.get("unit_amount", 0) or 0)
+    amount = int(data.get("amount", unit_amount * quantity) or 0)
     return InvoiceLineItemOut(
         id=line_id,
         description=data.get("description"),
         currency=str(data.get("currency", price.get("currency", ""))).upper(),
-        quantity=int(data.get("quantity", 0) or 0),
-        unit_amount=int(data.get("unit_amount", data.get("amount", 0) or 0)),
+        quantity=quantity,
+        amount=amount,
         provider_price_id=price.get("id"),
     )
 
@@ -268,6 +273,10 @@ def _payout_to_out(data: dict[str, Any]) -> PayoutOut:
 
 
 def _usage_record_to_out(data: dict[str, Any]) -> UsageRecordOut:
+    action_raw = data.get("action")
+    action: Literal["increment", "set"] | None = None
+    if action_raw in ("increment", "set"):
+        action = cast("Literal['increment', 'set']", action_raw)
     return UsageRecordOut(
         id=str(data.get("id")),
         quantity=int(data.get("quantity", 0) or 0),
@@ -278,7 +287,7 @@ def _usage_record_to_out(data: dict[str, Any]) -> UsageRecordOut:
         provider_price_id=(
             str(data.get("provider_price_id")) if data.get("provider_price_id") else None
         ),
-        action=(str(data.get("action")) if data.get("action") else None),
+        action=action,
     )
 
 
@@ -315,33 +324,35 @@ def _balance_snapshot_to_out(data: dict[str, Any]) -> BalanceSnapshotOut:
 
 def _ensure_sequence(result: Any) -> Sequence[dict[str, Any]]:
     if isinstance(result, Sequence):
-        return result  # type: ignore[arg-type]
+        return result
     if isinstance(result, dict):
         items = result.get("items")
         if isinstance(items, Sequence):
-            return items  # type: ignore[arg-type]
+            return items
     raise RuntimeError("Expected sequence payload from Aiydan client")
 
 
-def _ensure_list_response(result: Any) -> Tuple[Sequence[dict[str, Any]], Optional[str]]:
+def _ensure_list_response(
+    result: Any,
+) -> tuple[Sequence[dict[str, Any]], str | None]:
     if isinstance(result, tuple) and len(result) == 2:
         items, cursor = result
         if isinstance(items, Sequence) or items is None:
-            return (items or []), cursor  # type: ignore[arg-type]
+            return (items or []), cursor
     if isinstance(result, dict):
         items = result.get("items")
         cursor = result.get("next_cursor") or result.get("cursor")
         if isinstance(items, Sequence):
             return items, cursor
     if isinstance(result, Sequence):
-        return result, None  # type: ignore[arg-type]
+        return result, None
     raise RuntimeError("Expected iterable response from Aiydan client")
 
 
 class AiydanAdapter(ProviderAdapter):
     name = "aiydan"
 
-    def __init__(self, *, client: Optional[Any] = None):
+    def __init__(self, *, client: Any | None = None):
         settings = get_payments_settings()
         cfg = settings.aiydan
         if client is not None:
@@ -777,7 +788,12 @@ class AiydanAdapter(ProviderAdapter):
         return _intent_to_out(result)
 
     async def list_customers(
-        self, *, provider: str | None, user_id: str | None, limit: int, cursor: str | None
+        self,
+        *,
+        provider: str | None,
+        user_id: str | None,
+        limit: int,
+        cursor: str | None,
     ) -> tuple[list[CustomerOut], str | None]:
         result = await _maybe_await(
             self._client.list_customers(
@@ -790,7 +806,7 @@ class AiydanAdapter(ProviderAdapter):
         items, next_cursor = _ensure_list_response(result)
         return [_customer_to_out(item) for item in items], next_cursor
 
-    async def get_customer(self, provider_customer_id: str) -> Optional[CustomerOut]:
+    async def get_customer(self, provider_customer_id: str) -> CustomerOut | None:
         result = await _maybe_await(self._client.get_customer(provider_customer_id))
         if result is None:
             return None

svc_infra/apf_payments/provider/base.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Optional, Protocol
+from typing import Any, Protocol
 
 from ..schemas import (
     BalanceSnapshotOut,
@@ -186,12 +186,17 @@ class ProviderAdapter(Protocol):
 
     # --- Customers ---
     async def list_customers(
-        self, *, provider: str | None, user_id: str | None, limit: int, cursor: str | None
+        self,
+        *,
+        provider: str | None,
+        user_id: str | None,
+        limit: int,
+        cursor: str | None,
     ) -> tuple[list[CustomerOut], str | None]:
         """Optional: if not implemented, the service will list from local DB."""
         pass
 
-    async def get_customer(self, provider_customer_id: str) -> Optional[CustomerOut]:
+    async def get_customer(self, provider_customer_id: str) -> CustomerOut | None:
         pass
 
     # --- Products / Prices ---

svc_infra/apf_payments/provider/registry.py

@@ -1,19 +1,17 @@
 from __future__ import annotations
 
-from typing import Dict, Optional
-
 from ..settings import get_payments_settings
 from .base import ProviderAdapter
 
 
 class ProviderRegistry:
     def __init__(self):
-        self._adapters: Dict[str, ProviderAdapter] = {}
+        self._adapters: dict[str, ProviderAdapter] = {}
 
     def register(self, adapter: ProviderAdapter):
         self._adapters[adapter.name] = adapter
 
-    def get(self, name: Optional[str] = None) -> ProviderAdapter:
+    def get(self, name: str | None = None) -> ProviderAdapter:
         settings = get_payments_settings()
         key = (name or settings.default_provider).lower()
         if key not in self._adapters:
@@ -21,7 +19,7 @@ class ProviderRegistry:
         return self._adapters[key]
 
 
-_REGISTRY: Optional[ProviderRegistry] = None
+_REGISTRY: ProviderRegistry | None = None
 
 
 def get_provider_registry() -> ProviderRegistry: