Fix reference seller 3.1 storyboard compatibility

Author: bokelley

examples/seller_agent.py

@@ -17,6 +17,7 @@
 
 import os
 import uuid
+from datetime import datetime, timezone
 from typing import Any
 
 from adcp.server import (
@@ -79,6 +80,7 @@
 accounts: dict[str, dict[str, Any]] = {}
 media_buys: dict[str, dict[str, Any]] = {}
 creatives: dict[str, dict[str, Any]] = {}
+open_impairments: dict[tuple[str, str], dict[str, Any]] = {}
 proposals: dict[str, dict[str, Any]] = {}
 # Used when no account_id is present; single-tenant demo shortcut.
 # Real sellers must scope directives and tasks by account_id.
@@ -89,6 +91,78 @@
 # Seeded creative formats keyed by the string format ID the storyboard supplies.
 # list_creative_formats merges these in so storyboard references resolve.
 seeded_creative_formats: dict[str, dict[str, Any]] = {}
+
+
+def _now_z() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _package_creative_ids(pkg: dict[str, Any]) -> list[str]:
+    ids: list[str] = []
+    for assignment in pkg.get("creative_assignments") or []:
+        if isinstance(assignment, dict) and assignment.get("creative_id"):
+            ids.append(str(assignment["creative_id"]))
+    for creative in pkg.get("creatives") or []:
+        if isinstance(creative, dict) and creative.get("creative_id"):
+            ids.append(str(creative["creative_id"]))
+    return list(dict.fromkeys(ids))
+
+
+def _health_fields_for_media_buy(media_buy_id: str | None, mb: dict[str, Any]) -> dict[str, Any]:
+    impaired_packages: dict[str, list[str]] = {}
+    for pkg in mb.get("packages", []):
+        package_id = pkg.get("package_id")
+        if not package_id:
+            continue
+        creative_ids = _package_creative_ids(pkg)
+        if not creative_ids:
+            continue
+        if any(
+            creatives.get(creative_id, {}).get("status") in {"approved", "active"}
+            for creative_id in creative_ids
+        ):
+            continue
+        for creative_id in creative_ids:
+            creative_status = creatives.get(creative_id, {}).get("status")
+            if creative_status in {"rejected"}:
+                package_ids = impaired_packages.setdefault(creative_id, [])
+                if package_id not in package_ids:
+                    package_ids.append(package_id)
+    media_buy_key = media_buy_id or "__anonymous__"
+    active_keys = {(media_buy_key, creative_id) for creative_id in impaired_packages}
+    for key in [
+        key for key in open_impairments if key[0] == media_buy_key and key not in active_keys
+    ]:
+        del open_impairments[key]
+
+    impairments: list[dict[str, Any]] = []
+    for creative_id, package_ids in impaired_packages.items():
+        creative = creatives.get(creative_id, {})
+        key = (media_buy_key, creative_id)
+        if key not in open_impairments:
+            open_impairments[key] = {
+                "impairment_id": f"imp-{uuid.uuid4().hex[:8]}",
+                "observed_at": creative.get("status_changed_at") or _now_z(),
+            }
+        impairment = open_impairments[key]
+        impairments.append(
+            {
+                "impairment_id": impairment["impairment_id"],
+                "resource_type": "creative",
+                "resource_id": creative_id,
+                "package_ids": package_ids,
+                "transition": {"from": "approved", "to": "rejected"},
+                "reason_code": "content_rejected",
+                "reason": "Creative is no longer approved for delivery.",
+                "observed_at": impairment["observed_at"],
+                "remediation": "Assign an approved replacement creative.",
+            }
+        )
+    if impairments:
+        return {"health": "impaired", "impairments": impairments}
+    return {"health": "ok", "impairments": []}
+
+
 # Single-shot directives registered by force_create_media_buy_arm; keyed by account_id.
 pending_directives: dict[str, dict[str, Any]] = {}
 # Tasks registered when create_media_buy consumes a 'submitted' directive; keyed by task_id.
@@ -310,9 +384,7 @@ async def sync_governance(self, params: dict[str, Any], context: Any = None) ->
                 {
                     "account": acct_ref,
                     "status": "synced",
-                    "governance_agents": [
-                        {"url": a.get("url"), "categories": a.get("categories", [])} for a in agents
-                    ],
+                    "governance_agents": [{"url": a.get("url")} for a in agents],
                 }
             )
         return sync_governance_response(results)
@@ -345,7 +417,7 @@ async def get_products(self, params: dict[str, Any], context: Any = None) -> dic
                     }
                 ]
             return {
-                **products_response(PRODUCTS),
+                **products_response(PRODUCTS, cache_scope="public"),
                 "proposals": [
                     {
                         "proposal_id": proposal_id,
@@ -355,7 +427,7 @@ async def get_products(self, params: dict[str, Any], context: Any = None) -> dic
                     }
                 ],
             }
-        return products_response(PRODUCTS)
+        return products_response(PRODUCTS, cache_scope="public")
 
     async def create_media_buy(self, params: dict[str, Any], context: Any = None) -> dict[str, Any]:
         account_id = (params.get("account") or {}).get("account_id") or _DEFAULT_ACCOUNT_ID
@@ -478,6 +550,7 @@ async def get_media_buys(self, params: dict[str, Any], context: Any = None) -> d
                     "currency": mb.get("currency", "USD"),
                     "packages": mb.get("packages", []),
                     "total_budget": total_budget,
+                    **_health_fields_for_media_buy(mb_id, mb),
                 }
             )
         return media_buys_response(results)
@@ -605,12 +678,11 @@ async def sync_creatives(self, params: dict[str, Any], context: Any = None) -> d
         results = []
         for c in params.get("creatives", []):
             creative_id = c.get("creative_id") or f"c-{uuid.uuid4().hex[:8]}"
-            creatives[creative_id] = {**c, "status": "approved"}
+            creatives[creative_id] = {**c, "status": "approved", "status_changed_at": _now_z()}
             results.append(
                 {
                     "creative_id": creative_id,
                     "action": "created",
-                    "status": "approved",
                 }
             )
         # Transition any media buys waiting on creatives to pending_start
@@ -696,6 +768,7 @@ async def force_creative_status(
                 current_state=prev,
             )
         c["status"] = status
+        c["status_changed_at"] = _now_z()
         return {"previous_state": prev, "current_state": status}
 
     async def simulate_delivery(
@@ -900,6 +973,7 @@ async def seed_creative(
         data = dict(fixture or {})
         cid = creative_id or data.get("creative_id") or f"c-seeded-{uuid.uuid4().hex[:8]}"
         data["creative_id"] = cid
+        data.setdefault("status_changed_at", _now_z())
         creatives[cid] = data
         return {"creative_id": cid}
 

src/adcp/server/mcp_tools.py

@@ -33,6 +33,28 @@
 logger = logging.getLogger(__name__)
 
 
+_MEDIA_BUY_STATUS_VALUES = {
+    "draft",
+    "pending_creatives",
+    "pending_start",
+    "active",
+    "paused",
+    "completed",
+    "canceled",
+    "cancelled",
+    "rejected",
+}
+
+
+def _looks_like_sync_media_buy_success(method_name: str, result: dict[str, Any]) -> bool:
+    return (
+        method_name in {"create_media_buy", "update_media_buy"}
+        and "media_buy_id" in result
+        and "errors" not in result
+        and "task_id" not in result
+    )
+
+
 def _normalize_response_envelope(
     method_name: str, result: dict[str, Any], raw_params: dict[str, Any]
 ) -> None:
@@ -44,6 +66,16 @@ def _normalize_response_envelope(
     wholesale reads must be explicit so a seller doesn't accidentally label
     account-specific inventory as globally cacheable.
     """
+    if _looks_like_sync_media_buy_success(method_name, result):
+        raw_status = result.get("status")
+        media_buy_status = result.get("media_buy_status")
+        if media_buy_status is None and raw_status in _MEDIA_BUY_STATUS_VALUES:
+            if raw_status != "completed":
+                result["media_buy_status"] = raw_status
+                result["status"] = "completed"
+        elif media_buy_status is not None and raw_status in {None, media_buy_status}:
+            result["status"] = "completed"
+
     result.setdefault("status", "completed")
     if (
         method_name in {"get_products", "get_signals"}

src/adcp/server/responses.py

@@ -364,7 +364,6 @@ def media_buy_response(
         resp["buyer_ref"] = buyer_ref
     if status is not None:
         resp["media_buy_status"] = status
-        resp["status"] = status
         if valid_actions is None:
             resp["valid_actions"] = valid_actions_for_status(status)
         else:
@@ -405,7 +404,6 @@ def update_media_buy_response(
         resp["affected_packages"] = _serialize(affected_packages)
     if status is not None:
         resp["media_buy_status"] = status
-        resp["status"] = status
         if valid_actions is None:
             resp["valid_actions"] = valid_actions_for_status(status)
         else:

src/adcp/types/__init__.py

@@ -583,6 +583,8 @@
     UpdateMediaBuyPackagesRequest,
     UpdateMediaBuyPropertiesRequest,
     UpdateMediaBuyResponse1,
+    UpdateMediaBuyResponse3,
+    UpdateMediaBuySubmittedResponse,
     UpdateMediaBuySuccessResponse,
     UrlDaastAsset,
     UrlFormatAsset,
@@ -1255,8 +1257,10 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "UpdateContentStandardsSuccessResponse",
     "UpdateMediaBuyErrorResponse",
     "UpdateMediaBuyResponse1",
+    "UpdateMediaBuyResponse3",
     "UpdateMediaBuyPackagesRequest",
     "UpdateMediaBuyPropertiesRequest",
+    "UpdateMediaBuySubmittedResponse",
     "UpdateMediaBuySuccessResponse",
     "UrlDaastAsset",
     "UrlPreviewRender",

src/adcp/types/_generated.py

@@ -1459,6 +1459,7 @@
     UpdateMediaBuyResponse,
     UpdateMediaBuyResponse1,
     UpdateMediaBuyResponse2,
+    UpdateMediaBuyResponse3,
 )
 from adcp.types.generated_poc.pricing_options.cpa_option import CpaPricingOption
 from adcp.types.generated_poc.pricing_options.cpc_option import CpcPricingOption
@@ -2983,6 +2984,7 @@
     "UpdateMediaBuyResponse",
     "UpdateMediaBuyResponse1",
     "UpdateMediaBuyResponse2",
+    "UpdateMediaBuyResponse3",
     "UpdateMediaBuySubmitted",
     "UpdateMediaBuyWorking",
     "UpdatePropertyListRequest",

src/adcp/types/aliases.py

@@ -189,6 +189,7 @@
 )
 UpdateMediaBuyResponse1 = getattr(_g, "UpdateMediaBuyResponse1", _g.UpdateMediaBuyResponse)
 UpdateMediaBuyResponse2 = getattr(_g, "UpdateMediaBuyResponse2", _g.UpdateMediaBuyResponse)
+UpdateMediaBuyResponse3 = getattr(_g, "UpdateMediaBuyResponse3", _g.UpdateMediaBuyResponse)
 ValidateContentDeliveryResponse1 = getattr(
     _g, "ValidateContentDeliveryResponse1", _g.ValidateContentDeliveryResponse
 )
@@ -475,6 +476,9 @@ def process_result(result: SyncCatalogResult) -> None:
 UpdateMediaBuyErrorResponse: TypeAlias = UpdateMediaBuyResponse2
 """Error response - media buy update failed, no changes applied."""
 
+UpdateMediaBuySubmittedResponse: TypeAlias = UpdateMediaBuyResponse3
+"""Submitted (async) envelope - media buy update accepted for async processing."""
+
 # Get Account Financials Response Variants
 GetAccountFinancialsSuccessResponse: TypeAlias = GetAccountFinancialsResponse1
 """Success response - account financials retrieved."""
@@ -1725,6 +1729,7 @@ class UnknownGroupAsset(_BaseGroupAsset):
     # Update media buy responses
     "UpdateMediaBuySuccessResponse",
     "UpdateMediaBuyErrorResponse",
+    "UpdateMediaBuySubmittedResponse",
     # Validate content delivery responses
     "ValidateContentDeliverySuccessResponse",
     "ValidateContentDeliveryErrorResponse",

src/adcp/types/generated_poc/media_buy/create_media_buy_response.py

@@ -4,7 +4,6 @@
 
 from __future__ import annotations
 
-from ..core.protocol_envelope import ProtocolEnvelope
 from ..core.version_envelope import AdcpVersionEnvelope
 
 
@@ -14,30 +13,63 @@
 # historical numbered variants as ergonomic construction/parsing aliases.
 from typing import Any, Literal, TypeAlias
 
-from pydantic import ConfigDict
+from pydantic import ConfigDict, model_validator
 
 from ..core import error as error_1
 from ..core import package as package_1
 from ..enums import media_buy_status as media_buy_status_1
 
 
+_MEDIA_BUY_STATUS_VALUES = {
+    "pending_creatives",
+    "pending_start",
+    "active",
+    "paused",
+    "rejected",
+    "canceled",
+}
+
+
+def _value(value: Any) -> Any:
+    return getattr(value, "value", value)
+
+
 class CreateMediaBuyResponse1(AdcpVersionEnvelope):
     model_config = ConfigDict(extra='allow')
     media_buy_id: str
     packages: list[package_1.Package]
     buyer_ref: str | None = None
     media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
-    status: media_buy_status_1.MediaBuyStatus | None = None
+    status: Literal["completed"]
+
+    @model_validator(mode='before')
+    @classmethod
+    def _normalize_legacy_status(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        raw_status = _value(data.get("status"))
+        media_buy_status = _value(data.get("media_buy_status"))
+        if raw_status is None:
+            data = dict(data)
+            data["status"] = "completed"
+        elif media_buy_status is None and raw_status in _MEDIA_BUY_STATUS_VALUES:
+            data = dict(data)
+            data["media_buy_status"] = raw_status
+            data["status"] = "completed"
+        elif media_buy_status is not None and raw_status == media_buy_status:
+            data = dict(data)
+            data["status"] = "completed"
+        return data
 
 
 class CreateMediaBuyResponse2(AdcpVersionEnvelope):
     model_config = ConfigDict(extra='allow')
     errors: list[error_1.Error]
 
 
-class CreateMediaBuyResponse3(AdcpVersionEnvelope, ProtocolEnvelope):
+class CreateMediaBuyResponse3(AdcpVersionEnvelope):
     model_config = ConfigDict(extra='allow')
-    status: Any = 'submitted'
+    status: Literal["submitted"] = "submitted"
     task_id: str