feat(update): track buzz prices and alert below a threshold

CivitAI's public API deliberately omits prices — paidAccess is trimmed to
{permanent, endsAt} because "pricing belongs to the purchase flow" — but the
public model page embeds the site's own model.getById result, including
paidAccess.terms, in its server-rendered payload. That is read anonymously
(no API key, no internal endpoint, no forged Origin), one request per gated
model, so only the ~2% of models that actually carry a gate pay for it.

- optional capture, off by default: price_tracking_enabled,
  price_alert_threshold_buzz (0 = alert on "became free" only) and
  price_check_ttl_hours; prices refresh on their own TTL and immediately when a
  gate changes, and a failed fetch keeps the stored price instead of blanking it
- versions that stop carrying a gate are marked free (persisted gate_lapsed_at)
  and gate transitions are reported as events on the refresh response, so a
  version already in the library can announce that it became free
- price_alert_state plus a price_drop edge event; new
  GET /api/lm/{type}/updates/price-alerts lists what is under the threshold
- versions tab shows the price (effective, with the list price struck through
  and a Blue Buzz note) and a Free Now badge; an update check toasts the
  transitions in one message
- the parser and the alerts query are unit-tested against a trimmed page
  fixture, and every route definition is now asserted to resolve to a handler

Plan, verification notes and the deviations from it are in
docs/plans/paid-model-price-tracking.md.

py/routes/handlers/model_handlers.py

@@ -50,6 +50,7 @@ from ...services.errors import RateLimitError, ResourceNotFoundError
 from ...utils.civitai_utils import resolve_license_payload
 from ...utils.file_utils import calculate_sha256
 from ...utils.metadata_manager import MetadataManager
+from ...utils.paid_access import is_early_access_deadline_active
 from ...utils.sidecar_paths import get_metadata_path
 from ...utils.url_utils import relative_root_prefix
 
@@ -2941,6 +2942,20 @@ class ModelUpdateHandler:
 
         same_base_scope = self._uses_same_base_update_scope()
 
+        # Gate/price transitions are reported for every refreshed model, not only
+        # for the ones that qualify as updates: "this version became free" matters
+        # for a version the user already has, which never shows up as an update.
+        events = []
+        for record in records.values():
+            for event in getattr(record, "events", None) or []:
+                events.append(
+                    {
+                        "modelId": record.model_id,
+                        "modelType": record.model_type,
+                        **event,
+                    }
+                )
+
         serialized_records = []
         for record in records.values():
             has_update_fn = getattr(record, "has_update", None)
@@ -2962,6 +2977,7 @@ class ModelUpdateHandler:
             {
                 "success": True,
                 "records": serialized_records,
+                "events": events,
             }
         )
 
@@ -3054,6 +3070,46 @@ class ModelUpdateHandler:
             {"success": True, "record": self._serialize_record(record)}
         )
 
+    async def get_price_alerts(self, request: web.Request) -> web.Response:
+        """List gated versions whose stored price crosses the alert threshold.
+
+        Backed by the persisted alert state, so it matches the badges; the
+        threshold (and whether price tracking runs at all) comes from settings.
+        """
+
+        try:
+            limit = int(request.query.get("limit") or 200)
+        except (TypeError, ValueError):
+            limit = 200
+
+        alerts = await self._update_service.get_price_alerts(
+            self._service.model_type, limit=limit
+        )
+        threshold = 0
+        enabled = False
+        if self._settings is not None:
+            try:
+                threshold = int(
+                    self._settings.get("price_alert_threshold_buzz", 0) or 0
+                )
+            except (TypeError, ValueError):
+                threshold = 0
+            try:
+                enabled = bool(
+                    self._settings.get("price_tracking_enabled", False)
+                )
+            except Exception:
+                enabled = False
+
+        return web.json_response(
+            {
+                "success": True,
+                "enabled": enabled,
+                "thresholdBuzz": threshold,
+                "alerts": alerts,
+            }
+        )
+
     async def get_model_versions(self, request: web.Request) -> web.Response:
         model_id = self._normalize_model_id(request.match_info.get("model_id"))
         if model_id is None:
@@ -3391,6 +3447,7 @@ class ModelUpdateHandler:
                 hide_early_access=hide_early_access,
                 hide_paid=hide_paid,
             ),
+            "events": list(getattr(record, "events", None) or []),
             "versions": [
                 self._serialize_version(version, context.get(version.version_id))
                 for version in record.versions
@@ -3414,16 +3471,11 @@ class ModelUpdateHandler:
         if getattr(version, "is_paid", False) and not version.early_access_ends_at:
             is_early_access = False
         elif version.early_access_ends_at:
-            try:
-                from datetime import datetime, timezone
-
-                ea_date = datetime.fromisoformat(
-                    version.early_access_ends_at.replace("Z", "+00:00")
-                )
-                is_early_access = ea_date > datetime.now(timezone.utc)
-            except (ValueError, AttributeError):
-                # If date parsing fails, treat as active EA (conservative)
-                is_early_access = True
+            # Shared with the update service and the download gate so the badge,
+            # the update filter and the download warning cannot disagree.
+            is_early_access = is_early_access_deadline_active(
+                version.early_access_ends_at
+            )
         elif getattr(version, "is_early_access", False):
             # Fallback to basic EA flag from bulk API
             is_early_access = True
@@ -3450,6 +3502,16 @@ class ModelUpdateHandler:
             "usageControl": version.usage_control,
             "isPaid": bool(getattr(version, "is_paid", False)),
             "paidAccess": paid_access_payload,
+            # Set when a version that used to be gated became free, so the UI can
+            # keep showing "Free" long after the transition.
+            "gateLapsedAt": getattr(version, "gate_lapsed_at", None),
+            "priceBuzz": getattr(version, "price_buzz", None),
+            "listPriceBuzz": getattr(version, "list_price_buzz", None),
+            "generationPriceBuzz": getattr(version, "generation_price_buzz", None),
+            "acceptsBlueBuzz": bool(getattr(version, "accepts_blue_buzz", False)),
+            "priceSaleEndsAt": getattr(version, "price_sale_ends_at", None),
+            "priceCheckedAt": getattr(version, "price_checked_at", None),
+            "priceAlert": bool(getattr(version, "price_alert_state", False)),
             "filePath": context.get("file_path"),
             "fileName": context.get("file_name"),
             # Weight-file variant count (None when unknown); lets the UI hide
@@ -3612,5 +3674,6 @@ class ModelHandlerSet:
             "set_version_update_ignore": self.updates.set_version_update_ignore,
             "get_model_update_status": self.updates.get_model_update_status,
             "get_model_versions": self.updates.get_model_versions,
+            "get_price_alerts": self.updates.get_price_alerts,
             "cancel_task": self.query.cancel_task,
         }

py/routes/model_route_registrar.py

@@ -110,6 +110,9 @@ COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
     RouteDefinition(
         "GET", "/api/lm/{prefix}/updates/versions/{model_id}", "get_model_versions"
     ),
+    RouteDefinition(
+        "GET", "/api/lm/{prefix}/updates/price-alerts", "get_price_alerts"
+    ),
     RouteDefinition("POST", "/api/lm/download-model", "download_model"),
     RouteDefinition("GET", "/api/lm/download-model-get", "download_model_get"),
     RouteDefinition("GET", "/api/lm/cancel-download-get", "cancel_download_get"),