@cachly-dev/mcp-server 0.10.56 → 0.10.57

package/apps/travel-chaos-organizer/backend/app/routers/mail.py

@@ -0,0 +1,108 @@
+"""
+Mail import endpoint — paste raw email text or forward as plain text.
+Gmail / Outlook share-to-app flows send the body as plain text;
+we strip headers and run it through the same Ollama parsing pipeline.
+Results are Cachly-cached by content hash when CACHLY_REDIS_URL is configured.
+"""
+import json
+import re
+from datetime import datetime
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, Query
+from pydantic import ValidationError
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.keycloak import user_id
+from app.config import get_settings
+from app.db.database import get_db
+from app.models.schemas import ParseResponse, ParsedTravelData
+from app.services import ollama as ollama_svc
+
+router = APIRouter(prefix="/mail", tags=["mail"])
+settings = get_settings()
+
+_HEADER_RE = re.compile(
+    r"^(From|To|Cc|Bcc|Subject|Date|Message-ID|MIME-Version|Content-Type"
+    r"|Content-Transfer-Encoding|Delivered-To|Received|Return-Path|X-[^:]+)"
+    r":\s.*$",
+    re.MULTILINE | re.IGNORECASE,
+)
+_BLANK_LINES_RE = re.compile(r"\n{3,}")
+
+
+def _safe_dt(val: str | None) -> datetime | None:
+    """Parse an Ollama-produced datetime string to a proper datetime object.
+    asyncpg requires a datetime object (not a string) for TIMESTAMPTZ columns.
+    Returns None on missing or unparseable input."""
+    if val is None:
+        return None
+    try:
+        return datetime.fromisoformat(val.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+
+
+def _build_parsed(parsed_dict: dict) -> ParsedTravelData:
+    """Build a ParsedTravelData, falling back to safe defaults on ValidationError.
+    Matches the same pattern as parse.py to avoid a double-fail scenario."""
+    try:
+        return ParsedTravelData(**{k: parsed_dict.get(k) for k in ParsedTravelData.model_fields})
+    except ValidationError:
+        return ParsedTravelData(
+            type="other",
+            title=str(parsed_dict.get("title") or "E-Mail"),
+            booking_ref=parsed_dict.get("booking_ref"),
+            provider=parsed_dict.get("provider"),
+            event_at=parsed_dict.get("event_at"),
+            raw_summary=parsed_dict.get("raw_summary"),
+        )
+
+
+def strip_email_headers(raw: str) -> str:
+    cleaned = _HEADER_RE.sub("", raw)
+    cleaned = _BLANK_LINES_RE.sub("\n\n", cleaned)
+    return cleaned.strip()
+
+
+@router.post("/import", response_model=ParseResponse)
+async def import_mail(
+    uid: Annotated[str, Depends(user_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    raw_email: str = Body(..., media_type="text/plain", description="Raw email body (paste or share)"),
+    trip_id: UUID | None = Query(None, description="Assign directly to this trip (optional)"),
+):
+    body_text = strip_email_headers(raw_email)
+    parsed_dict, _was_cached = await ollama_svc.parse_text(body_text)
+    parsed = _build_parsed(parsed_dict)
+
+    if trip_id:
+        await db.execute(
+            text("""
+                INSERT INTO trip_items
+                  (trip_id, user_id, type, title, raw_text, parsed_data,
+                   event_at, event_end_at, booking_ref, provider)
+                VALUES (:trip_id, :uid, :type, :title, :raw, :pd,
+                        :event_at, :event_end_at, :booking_ref, :provider)
+            """),
+            {
+                "trip_id": str(trip_id), "uid": uid, "type": parsed.type, "title": parsed.title,
+                "raw": body_text, "pd": json.dumps(parsed.model_dump()),
+                "event_at": _safe_dt(parsed.event_at),
+                "event_end_at": _safe_dt(parsed.event_end_at),
+                "booking_ref": parsed.booking_ref, "provider": parsed.provider,
+            },
+        )
+    else:
+        await db.execute(
+            text("""
+                INSERT INTO chaos_inbox (user_id, raw_content, parsed_data, source)
+                VALUES (:uid, :raw, :pd, 'mail')
+            """),
+            {"uid": uid, "raw": body_text, "pd": json.dumps(parsed.model_dump())},
+        )
+    await db.commit()
+
+    return ParseResponse(parsed=parsed, raw_text=body_text, model_used=settings.ollama_model)

package/apps/travel-chaos-organizer/backend/app/routers/parse.py

@@ -0,0 +1,303 @@
+"""
+Parse endpoint — accepts file upload, raw text, or a public URL.
+Returns structured travel data via Ollama AI.
+Results are deduplicated via Cachly Redis when CACHLY_REDIS_URL is configured.
+"""
+from datetime import datetime, timezone
+from typing import Annotated
+from uuid import UUID
+import aiofiles
+import os
+from pathlib import Path
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile, status
+from pydantic import BaseModel, ValidationError
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.auth.keycloak import user_id, user_id_or_bot
+from app.config import get_settings
+from app.db.database import get_db
+from app.models.schemas import ParseResponse, ParsedTravelData
+from app.services import ollama as ollama_svc
+from app.services.parser import extract_text_from_pdf, is_image, is_pdf, is_text
+from app.services.cache import cachly_configured
+from app.services import quota
+from app.limiter import limiter
+
+router = APIRouter(prefix="/parse", tags=["parse"])
+settings = get_settings()
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+def _safe_dt(val: str | None) -> datetime | None:
+    """Parse an ISO 8601 datetime string from Ollama to a proper datetime.
+    Returns None if the value is missing, empty, or not parseable.
+    asyncpg requires a proper datetime object or None for TIMESTAMPTZ columns.
+    """
+    if not val or not isinstance(val, str):
+        return None
+    try:
+        # Python 3.11+ fromisoformat handles most ISO 8601 variants.
+        # Replace trailing Z (UTC) so older code paths also work.
+        return datetime.fromisoformat(val.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _build_parsed(parsed_dict: dict) -> ParsedTravelData:
+    """Construct ParsedTravelData from Ollama output.
+    Falls back to safe defaults if Ollama returns an unexpected 'type' value
+    (e.g. 'taxi', 'parking') that is not in the Literal enum — which would
+    otherwise raise an unhandled Pydantic ValidationError and return a 500.
+    """
+    try:
+        return ParsedTravelData(**{k: parsed_dict.get(k) for k in ParsedTravelData.model_fields})
+    except ValidationError:
+        return ParsedTravelData(
+            type="other",
+            title=str(parsed_dict.get("title") or "Dokument"),
+            booking_ref=parsed_dict.get("booking_ref"),
+            provider=parsed_dict.get("provider"),
+            event_at=parsed_dict.get("event_at"),
+            raw_summary=parsed_dict.get("raw_summary"),
+        )
+
+
+async def _save_file(content: bytes, filename: str, uid: str) -> str:
+    dest_dir = Path(settings.upload_dir) / uid
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / filename
+    async with aiofiles.open(dest, "wb") as f:
+        await f.write(content)
+    return str(dest)
+
+
+async def _insert_item_from_parsed(
+    uid: str, trip_id: UUID, parsed: ParsedTravelData,
+    raw_text: str | None, file_path: str | None,
+    mime: str | None, filename: str | None,
+    db: AsyncSession,
+) -> None:
+    import json
+    result = await db.execute(
+        text("""
+            INSERT INTO trip_items
+              (trip_id, user_id, type, title, raw_text, parsed_data,
+               event_at, event_end_at, booking_ref, provider)
+            VALUES (:trip_id, :uid, :type, :title, :raw_text, :pd,
+                    :event_at, :event_end_at, :booking_ref, :provider)
+            RETURNING id
+        """),
+        {
+            "trip_id": str(trip_id), "uid": uid, "type": parsed.type, "title": parsed.title,
+            "raw_text": raw_text, "pd": json.dumps(parsed.model_dump()),
+            # _safe_dt converts Ollama's freeform date strings to proper datetime objects.
+            # asyncpg / PostgreSQL rejects non-ISO strings for TIMESTAMPTZ columns,
+            # which would crash the INSERT and roll back the whole transaction.
+            "event_at": _safe_dt(parsed.event_at), "event_end_at": _safe_dt(parsed.event_end_at),
+            "booking_ref": parsed.booking_ref, "provider": parsed.provider,
+        },
+    )
+    item_id = result.fetchone()[0]
+
+    if file_path:
+        await db.execute(
+            text("""
+                INSERT INTO attachments (trip_item_id, user_id, file_path, file_name, mime_type)
+                VALUES (:item_id, :uid, :fp, :fn, :mime)
+            """),
+            # file_name is NOT NULL in the schema. Use a fallback to avoid a constraint
+            # violation that would roll back the trip_item insert in the same transaction.
+            {"item_id": item_id, "uid": uid, "fp": file_path, "fn": filename or "attachment", "mime": mime or "application/octet-stream"},
+        )
+    await db.commit()
+
+
+async def _insert_inbox(
+    uid: str, raw_text: str | None, parsed_dict: dict,
+    file_path: str | None, mime: str | None, filename: str | None,
+    db: AsyncSession,
+) -> dict:
+    import json
+    result = await db.execute(
+        text("""
+            INSERT INTO chaos_inbox (user_id, raw_content, parsed_data, source)
+            VALUES (:uid, :raw, :pd, :source)
+            RETURNING id
+        """),
+        {"uid": uid, "raw": raw_text, "pd": json.dumps(parsed_dict), "source": filename or "text"},
+    )
+    inbox_id = result.fetchone()[0]
+
+    if file_path:
+        await db.execute(
+            text("""
+                INSERT INTO attachments (inbox_id, user_id, file_path, file_name, mime_type)
+                VALUES (:inbox_id, :uid, :fp, :fn, :mime)
+            """),
+            {"inbox_id": inbox_id, "uid": uid, "fp": file_path, "fn": filename or "attachment", "mime": mime or "application/octet-stream"},
+        )
+    await db.commit()
+    return {"inbox_id": str(inbox_id)}
+
+# ── endpoints ──────────────────────────────────────────────────────────────────
+
+@limiter.limit("10/minute")
+@router.post("/file", response_model=ParseResponse)
+async def parse_file(
+    request: Request,
+    uid: Annotated[str, Depends(user_id_or_bot)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    file: UploadFile = File(...),
+    trip_id: UUID | None = Form(None),
+):
+    await quota.check_parse(db, uid)
+    _s = get_settings()
+    content = await file.read()
+    if len(content) > _s.max_upload_bytes:
+        raise HTTPException(status_code=413, detail=f"File too large. Max {_s.max_upload_bytes // 1024 // 1024} MB.")
+    mime = file.content_type or "application/octet-stream"
+    raw_text: str | None = None
+    parsed_dict: dict = {}
+
+    was_cached = False
+    if is_pdf(mime):
+        raw_text = extract_text_from_pdf(content)
+        parsed_dict, was_cached = await ollama_svc.parse_text(raw_text)
+    elif is_image(mime):
+        parsed_dict, raw_text, was_cached = await ollama_svc.parse_image(content, mime)
+    elif is_text(mime):
+        raw_text = content.decode("utf-8", errors="replace")
+        parsed_dict, was_cached = await ollama_svc.parse_text(raw_text)
+    else:
+        raise HTTPException(status_code=415, detail=f"Unsupported file type: {mime}")
+
+    file_path = await _save_file(content, file.filename or "upload", uid)
+    parsed = _build_parsed(parsed_dict)
+
+    if trip_id:
+        await _insert_item_from_parsed(uid, trip_id, parsed, raw_text, file_path, mime, file.filename, db)
+    else:
+        await _insert_inbox(uid, raw_text, parsed_dict, file_path, mime, file.filename, db)
+
+    from app.services import telemetry, notifier as notifier_svc
+    await telemetry.track(db, uid, "parse_file", {"mime": mime, "trip_id": str(trip_id) if trip_id else None, "cached": was_cached})
+    if not was_cached:
+        dest = f"Trip zugewiesen" if trip_id else "Chaos Inbox"
+        await notifier_svc.notify_user(db, uid, f"✅ *{parsed.title or 'Dokument'}* geparst\nTyp: {parsed.type} · {dest}")
+    return ParseResponse(parsed=parsed, raw_text=raw_text, model_used=settings.ollama_model)
+
+
+@limiter.limit("20/minute")
+@router.post("/text", response_model=ParseResponse)
+async def parse_text_endpoint(
+    request: Request,
+    uid: Annotated[str, Depends(user_id_or_bot)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    raw_text: str = Form(...),
+    trip_id: UUID | None = Form(None),
+):
+    await quota.check_parse(db, uid)
+    parsed_dict, was_cached = await ollama_svc.parse_text(raw_text)
+    parsed = _build_parsed(parsed_dict)
+
+    if trip_id:
+        await _insert_item_from_parsed(uid, trip_id, parsed, raw_text, None, None, None, db)
+    else:
+        await _insert_inbox(uid, raw_text, parsed_dict, None, None, None, db)
+
+    from app.services import telemetry
+    await telemetry.track(db, uid, "parse_text", {"mime": None, "trip_id": str(trip_id) if trip_id else None, "cached": was_cached})
+    return ParseResponse(parsed=parsed, raw_text=raw_text, model_used=settings.ollama_model)
+
+
+class ParseUrlRequest(BaseModel):
+    url: str
+    trip_id: UUID | None = None
+
+
+@limiter.limit("5/minute")
+@router.post("/url")
+async def parse_url(
+    request: Request,
+    body: ParseUrlRequest,
+    uid: Annotated[str, Depends(user_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """
+    Fetch a public URL and parse its content with Ollama.
+    Useful for online booking confirmation pages.
+    Cached in Cachly Redis when CACHLY_REDIS_URL is configured.
+    """
+    import httpx as _httpx
+    from html.parser import HTMLParser
+
+    class _TextExtractor(HTMLParser):
+        def __init__(self):
+            super().__init__()
+            self._parts: list[str] = []
+            self._skip = False
+        def handle_starttag(self, tag, attrs):
+            if tag in ("script", "style", "nav", "footer"):
+                self._skip = True
+        def handle_endtag(self, tag):
+            if tag in ("script", "style", "nav", "footer"):
+                self._skip = False
+        def handle_data(self, data):
+            if not self._skip and data.strip():
+                self._parts.append(data.strip())
+        def text(self) -> str:
+            return " ".join(self._parts)[:8000]
+
+    # SSRF protection: only allow http/https, block private/loopback IP ranges
+    import ipaddress as _ip
+    try:
+        _parsed = _httpx.URL(body.url)
+        if _parsed.scheme not in ("http", "https"):
+            raise HTTPException(status_code=422, detail="Only http/https URLs are allowed")
+        import socket as _socket
+        try:
+            _addr = _socket.gethostbyname(_parsed.host)
+            _net = _ip.ip_address(_addr)
+            if _net.is_private or _net.is_loopback or _net.is_link_local or _net.is_reserved:
+                raise HTTPException(status_code=422, detail="URL resolves to a private/internal address")
+        except HTTPException:
+            raise
+        except Exception:
+            pass  # DNS failure handled below
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(status_code=422, detail="Invalid URL")
+
+    try:
+        async with _httpx.AsyncClient(timeout=20, follow_redirects=True) as client:
+            resp = await client.get(body.url, headers={"User-Agent": "Mozilla/5.0 TCO/0.1"})
+            resp.raise_for_status()
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(status_code=422, detail="Could not fetch URL")
+
+    await quota.check_parse(db, uid)
+    ct = resp.headers.get("content-type", "")
+    if "html" in ct:
+        extractor = _TextExtractor()
+        extractor.feed(resp.text)
+        raw_text = extractor.text()
+    elif "pdf" in ct:
+        raw_text = extract_text_from_pdf(resp.content)
+    else:
+        raw_text = resp.text[:8000]
+
+    parsed_dict, was_cached = await ollama_svc.parse_text(raw_text)
+    parsed = _build_parsed(parsed_dict)
+
+    from app.services import telemetry
+    if body.trip_id:
+        await _insert_item_from_parsed(uid, body.trip_id, parsed, raw_text, None, None, body.url, db)
+        await telemetry.track(db, uid, "parse_url", {"mime": None, "trip_id": str(body.trip_id) if body.trip_id else None, "cached": was_cached})
+        return ParseResponse(parsed=parsed, raw_text=raw_text, model_used=settings.ollama_model)
+    else:
+        result = await _insert_inbox(uid, raw_text, parsed_dict, None, None, body.url, db)
+        await telemetry.track(db, uid, "parse_url", {"mime": None, "trip_id": None, "cached": was_cached})
+        return {**ParseResponse(parsed=parsed, raw_text=raw_text, model_used=settings.ollama_model).model_dump(), **result}

package/apps/travel-chaos-organizer/backend/app/routers/payments.py

@@ -0,0 +1,179 @@
+"""
+Stripe payment endpoints.
+POST /api/v1/payments/checkout  — create Stripe Checkout session for Pro upgrade
+POST /api/v1/payments/webhook   — handle Stripe webhook events
+"""
+from typing import Annotated
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import text
+from datetime import datetime, timedelta, timezone
+from app.auth.keycloak import user_id
+from app.db.database import get_db
+from app.config import get_settings
+from app.limiter import limiter
+
+router = APIRouter(prefix="/payments", tags=["payments"])
+
+
+@limiter.limit("5/minute")
+@router.post("/checkout")
+async def create_checkout(
+    request: Request,
+    uid: Annotated[str, Depends(user_id)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    s = get_settings()
+    if not s.stripe_secret_key:
+        raise HTTPException(status_code=503, detail="Payments not configured")
+
+    import stripe
+    stripe.api_key = s.stripe_secret_key
+
+    # Get user email from DB if available
+    row = await db.execute(text("SELECT email FROM users WHERE id = :uid"), {"uid": uid})
+    r = row.fetchone()
+    customer_email = r[0] if r and r[0] else None
+
+    session = stripe.checkout.Session.create(
+        mode="subscription",
+        line_items=[{"price": s.stripe_pro_price_id, "quantity": 1}],
+        success_url=s.stripe_success_url + "?session_id={CHECKOUT_SESSION_ID}",
+        cancel_url=s.stripe_cancel_url,
+        client_reference_id=uid,
+        **({"customer_email": customer_email} if customer_email else {}),
+        metadata={"user_id": uid},
+    )
+    from app.services import telemetry
+    await telemetry.track(db, uid, "stripe_checkout_initiated", {"price_id": s.stripe_pro_price_id})
+    return {"checkout_url": session.url, "session_id": session.id}
+
+
+@router.post("/webhook")
+async def stripe_webhook(request: Request, db: Annotated[AsyncSession, Depends(get_db)]):
+    s = get_settings()
+    if not s.stripe_secret_key:
+        return {"ok": True}
+
+    import stripe
+    stripe.api_key = s.stripe_secret_key
+
+    payload = await request.body()
+    sig = request.headers.get("stripe-signature", "")
+    if not sig:
+        raise HTTPException(status_code=400, detail="Missing Stripe-Signature header")
+
+    try:
+        event = stripe.Webhook.construct_event(payload, sig, s.stripe_webhook_secret)
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid webhook signature")
+
+    if event["type"] == "checkout.session.completed":
+        obj = event["data"]["object"]
+        uid = obj.get("metadata", {}).get("user_id") or obj.get("client_reference_id")
+        if uid:
+            expires_at = datetime.now(timezone.utc) + timedelta(days=365)
+            await db.execute(
+                text("""
+                    INSERT INTO users (id, plan, plan_expires_at, updated_at)
+                    VALUES (:uid, 'pro', :exp, :now)
+                    ON CONFLICT (id) DO UPDATE
+                      SET plan = 'pro', plan_expires_at = EXCLUDED.plan_expires_at,
+                          updated_at = EXCLUDED.updated_at
+                """),
+                {"uid": uid, "exp": expires_at, "now": datetime.now(timezone.utc)},
+            )
+            await db.commit()
+            # Store Stripe customer ID for future subscription management
+            stripe_cust = obj.get("customer")
+            if stripe_cust:
+                await db.execute(
+                    text("UPDATE users SET stripe_customer_id = :cid WHERE id = :uid"),
+                    {"cid": stripe_cust, "uid": uid},
+                )
+                await db.commit()
+            from app.services import telemetry as tel_svc
+            from app.services import notifier as notifier_svc
+            await tel_svc.track(db, uid, "stripe_payment_completed", {"amount": obj.get("amount_total"), "currency": obj.get("currency")})
+            await notifier_svc.notify("tco", "stripe_payment", {"user_id": uid, "amount": obj.get("amount_total"), "currency": obj.get("currency")})
+            await notifier_svc.notify_user(db, uid, "🎉 *Du bist jetzt Pro!*\n\nAlle Features sind freigeschaltet. Viel Spaß beim Reisen ✈️")
+
+    elif event["type"] in ("customer.subscription.deleted", "customer.subscription.paused"):
+        cust_id = event["data"]["object"].get("customer")
+        if cust_id:
+            result = await db.execute(
+                text("SELECT id FROM users WHERE stripe_customer_id = :cid"),
+                {"cid": cust_id},
+            )
+            row = result.fetchone()
+            if row:
+                downgrade_uid = row[0]
+                await db.execute(
+                    text("""
+                        UPDATE users SET plan = 'free', plan_expires_at = NULL, updated_at = :now
+                        WHERE id = :uid
+                    """),
+                    {"uid": downgrade_uid, "now": datetime.now(timezone.utc)},
+                )
+                await db.commit()
+                from app.services import telemetry as tel_svc, notifier as notifier_svc
+                await tel_svc.track(db, downgrade_uid, "stripe_subscription_cancelled", {"customer": cust_id})
+                await notifier_svc.notify_user(db, downgrade_uid, "ℹ️ *Dein Pro-Abo wurde beendet.*\n\nDu bist jetzt wieder im Free-Plan. Deine Daten bleiben erhalten.")
+                await notifier_svc.notify("tco", "stripe_payment", {"event": "cancelled", "user_id": downgrade_uid[:8]})
+
+    elif event["type"] == "invoice.payment_succeeded":
+        # Extend plan by 1 year on renewal
+        sub = event["data"]["object"].get("subscription")
+        cust_id = event["data"]["object"].get("customer")
+        if sub and cust_id:
+            result = await db.execute(
+                text("SELECT id, plan_expires_at FROM users WHERE stripe_customer_id = :cid"),
+                {"cid": cust_id},
+            )
+            row = result.fetchone()
+            if row:
+                renewal_uid = row[0]
+                new_expiry = datetime.now(timezone.utc) + timedelta(days=366)
+                await db.execute(
+                    text("""
+                        UPDATE users SET plan = 'pro', plan_expires_at = :exp, updated_at = :now
+                        WHERE id = :uid
+                    """),
+                    {"uid": renewal_uid, "exp": new_expiry, "now": datetime.now(timezone.utc)},
+                )
+                await db.commit()
+
+    elif event["type"] == "invoice.payment_failed":
+        cust_id = event["data"]["object"].get("customer")
+        attempt_count = event["data"]["object"].get("attempt_count", 1)
+        if cust_id:
+            result = await db.execute(
+                text("SELECT id, email FROM users WHERE stripe_customer_id = :cid"),
+                {"cid": cust_id},
+            )
+            row = result.fetchone()
+            if row:
+                failed_uid, user_email = row[0], row[1]
+                if attempt_count >= 3:
+                    # Too many failures — downgrade to free immediately
+                    await db.execute(
+                        text("""
+                            UPDATE users SET plan = 'free', plan_expires_at = NULL, updated_at = :now
+                            WHERE id = :uid
+                        """),
+                        {"uid": failed_uid, "now": datetime.now(timezone.utc)},
+                    )
+                    await db.commit()
+                # else: keep pro, Stripe will retry (grace period)
+                from app.services import telemetry as tel_svc, notifier as notifier_svc
+                await tel_svc.track(db, failed_uid, "stripe_payment_failed", {"customer": cust_id, "attempt_count": attempt_count})
+                await notifier_svc.notify("tco", "stripe_payment", {"event": "payment_failed", "user_id": failed_uid[:8], "attempt": attempt_count})
+                if attempt_count < 3:
+                    await notifier_svc.notify_user(db, failed_uid, f"⚠️ *Zahlung fehlgeschlagen* (Versuch {attempt_count}/3)\n\nBitte aktualisiere deine Zahlungsmethode in Stripe. Dein Pro-Zugang bleibt noch aktiv.")
+                else:
+                    await notifier_svc.notify_user(db, failed_uid, "🔴 *Pro-Zugang deaktiviert*\n\nNach 3 fehlgeschlagenen Zahlungsversuchen wurde dein Abo beendet. Bitte erneuere dein Abo in der App.")
+                if user_email and attempt_count == 1:
+                    # TODO: send payment failure email via notifier_svc or a dedicated email service
+                    pass
+
+    return {"ok": True}