fix(types): widen guards.CreateMediaBuyResponse to 3-branch union + re-export Submitted

The local CreateMediaBuyResponse alias in guards.py was a stale 2-branch
union (Success | Error). PlatformHandler.create_media_buy now returns the
full 3-branch union including the async Submitted envelope, so callers
running is_create_media_buy_success on a handler result would silently
mis-classify the submitted branch.

Changes:
- guards.py: widen CreateMediaBuyResponse to include
  CreateMediaBuySubmittedResponse; add is_create_media_buy_submitted
  TypeGuard; update success/error guards to short-circuit on the
  submitted branch (it's neither sync success nor terminal error).
- adcp/__init__.py: re-export CreateMediaBuySubmittedResponse alongside
  the existing Success/Error aliases.
- tests: cover the new submitted guard (positive + success/error
  negatives); update public_api snapshot for the top-level re-export.

Author: bokelley

src/adcp/__init__.py

@@ -294,6 +294,7 @@
     CreateContentStandardsErrorResponse,
     CreateContentStandardsSuccessResponse,
     CreateMediaBuyErrorResponse,
+    CreateMediaBuySubmittedResponse,
     CreateMediaBuySuccessResponse,
     Deployment,
     Destination,
@@ -890,6 +891,7 @@ def get_adcp_version() -> str:
     "CreateContentStandardsErrorResponse",
     "CreateMediaBuySuccessResponse",
     "CreateMediaBuyErrorResponse",
+    "CreateMediaBuySubmittedResponse",
     "Deployment",
     "Destination",
     "GetContentStandardsSuccessResponse",

src/adcp/types/guards.py

@@ -79,6 +79,7 @@ def is_adcp_success(response: Any) -> bool:
     CalibrateContentErrorResponse,
     CalibrateContentSuccessResponse,
     CreateMediaBuyErrorResponse,
+    CreateMediaBuySubmittedResponse,
     CreateMediaBuySuccessResponse,
     GetAccountFinancialsErrorResponse,
     GetAccountFinancialsSuccessResponse,
@@ -103,7 +104,9 @@ def is_adcp_success(response: Any) -> bool:
 )
 
 # Type aliases for response unions
-CreateMediaBuyResponse = CreateMediaBuySuccessResponse | CreateMediaBuyErrorResponse
+CreateMediaBuyResponse = (
+    CreateMediaBuySuccessResponse | CreateMediaBuyErrorResponse | CreateMediaBuySubmittedResponse
+)
 UpdateMediaBuyResponse = UpdateMediaBuySuccessResponse | UpdateMediaBuyErrorResponse
 ActivateSignalResponse = ActivateSignalSuccessResponse | ActivateSignalErrorResponse
 BuildCreativeResponse = BuildCreativeSuccessResponse | BuildCreativeErrorResponse
@@ -116,22 +119,49 @@ def is_adcp_success(response: Any) -> bool:
 
 # --- Create Media Buy ---
 
+
+def is_create_media_buy_submitted(
+    response: CreateMediaBuyResponse,
+) -> TypeGuard[CreateMediaBuySubmittedResponse]:
+    """Check if a CreateMediaBuyResponse is the async submitted envelope.
+
+    The submitted branch carries ``status == 'submitted'`` and a ``task_id``
+    the buyer uses to poll ``tasks/get`` (or correlate with push-notification
+    callbacks). It is neither a synchronous success nor a terminal error.
+    """
+    return getattr(response, "status", None) == "submitted" and hasattr(response, "task_id")
+
+
 def is_create_media_buy_success(
     response: CreateMediaBuyResponse,
 ) -> TypeGuard[CreateMediaBuySuccessResponse]:
-    """Check if a CreateMediaBuyResponse is a success."""
+    """Check if a CreateMediaBuyResponse is a synchronous success.
+
+    Returns False for the submitted (async) envelope — use
+    ``is_create_media_buy_submitted`` for that branch.
+    """
+    if is_create_media_buy_submitted(response):
+        return False
     return not is_adcp_error(response)
 
 
 def is_create_media_buy_error(
     response: CreateMediaBuyResponse,
 ) -> TypeGuard[CreateMediaBuyErrorResponse]:
-    """Check if a CreateMediaBuyResponse is an error."""
+    """Check if a CreateMediaBuyResponse is an error.
+
+    Returns False for the submitted (async) envelope, even if it carries
+    advisory (non-blocking) errors. Use ``is_create_media_buy_submitted``
+    for that branch.
+    """
+    if is_create_media_buy_submitted(response):
+        return False
     return is_adcp_error(response)
 
 
 # --- Update Media Buy ---
 
+
 def is_update_media_buy_success(
     response: UpdateMediaBuyResponse,
 ) -> TypeGuard[UpdateMediaBuySuccessResponse]:
@@ -148,6 +178,7 @@ def is_update_media_buy_error(
 
 # --- Activate Signal ---
 
+
 def is_activate_signal_success(
     response: ActivateSignalResponse,
 ) -> TypeGuard[ActivateSignalSuccessResponse]:
@@ -164,6 +195,7 @@ def is_activate_signal_error(
 
 # --- Build Creative ---
 
+
 def is_build_creative_success(
     response: BuildCreativeResponse,
 ) -> TypeGuard[BuildCreativeSuccessResponse]:
@@ -180,6 +212,7 @@ def is_build_creative_error(
 
 # --- Sync Creatives ---
 
+
 def is_sync_creatives_success(
     response: SyncCreativesResponse,
 ) -> TypeGuard[SyncCreativesSuccessResponse]:
@@ -196,6 +229,7 @@ def is_sync_creatives_error(
 
 # --- Performance Feedback ---
 
+
 def is_performance_feedback_success(
     response: ProvidePerformanceFeedbackSuccessResponse | ProvidePerformanceFeedbackErrorResponse,
 ) -> TypeGuard[ProvidePerformanceFeedbackSuccessResponse]:
@@ -212,6 +246,7 @@ def is_performance_feedback_error(
 
 # --- Sync Accounts ---
 
+
 def is_sync_accounts_success(
     response: SyncAccountsResponse,
 ) -> TypeGuard[SyncAccountsSuccessResponse]:
@@ -228,6 +263,7 @@ def is_sync_accounts_error(
 
 # --- Log Event ---
 
+
 def is_log_event_success(
     response: LogEventResponse,
 ) -> TypeGuard[LogEventSuccessResponse]:
@@ -244,6 +280,7 @@ def is_log_event_error(
 
 # --- Sync Catalogs ---
 
+
 def is_sync_catalogs_success(
     response: SyncCatalogsResponse,
 ) -> TypeGuard[SyncCatalogsSuccessResponse]:
@@ -260,6 +297,7 @@ def is_sync_catalogs_error(
 
 # --- Get Account Financials ---
 
+
 def is_get_account_financials_success(
     response: GetAccountFinancialsSuccessResponse | GetAccountFinancialsErrorResponse,
 ) -> TypeGuard[GetAccountFinancialsSuccessResponse]:
@@ -276,6 +314,7 @@ def is_get_account_financials_error(
 
 # --- Content Standards ---
 
+
 def is_calibrate_content_success(
     response: CalibrateContentSuccessResponse | CalibrateContentErrorResponse,
 ) -> TypeGuard[CalibrateContentSuccessResponse]:
@@ -292,6 +331,7 @@ def is_validate_content_delivery_success(
 
 # --- Creative Features ---
 
+
 def is_get_creative_features_success(
     response: GetCreativeFeaturesSuccessResponse | GetCreativeFeaturesErrorResponse,
 ) -> TypeGuard[GetCreativeFeaturesSuccessResponse]:
@@ -310,6 +350,7 @@ def is_get_creative_features_success(
     # Media buy guards
     "is_create_media_buy_success",
     "is_create_media_buy_error",
+    "is_create_media_buy_submitted",
     "is_update_media_buy_success",
     "is_update_media_buy_error",
     # Signal guards

tests/fixtures/public_api_snapshot.json

@@ -94,6 +94,7 @@
     "CreateMediaBuyErrorResponse",
     "CreateMediaBuyRequest",
     "CreateMediaBuyResponse",
+    "CreateMediaBuySubmittedResponse",
     "CreateMediaBuySuccessResponse",
     "Creative",
     "CreativeApproval",

tests/test_type_guards.py

@@ -6,6 +6,7 @@
     is_adcp_error,
     is_adcp_success,
     is_create_media_buy_error,
+    is_create_media_buy_submitted,
     is_create_media_buy_success,
     is_update_media_buy_error,
     is_update_media_buy_success,
@@ -93,6 +94,34 @@ def test_create_media_buy_error_guard(self) -> None:
         )
         assert is_create_media_buy_success(resp) is False
         assert is_create_media_buy_error(resp) is True
+        assert is_create_media_buy_submitted(resp) is False
+
+    def test_create_media_buy_submitted_guard(self) -> None:
+        """Submitted (async) envelope is neither success nor error."""
+        from adcp.types.aliases import (
+            CreateMediaBuyErrorResponse,
+            CreateMediaBuySubmittedResponse,
+            CreateMediaBuySuccessResponse,
+        )
+
+        submitted = CreateMediaBuySubmittedResponse.model_validate(
+            {"status": "submitted", "task_id": "task_abc"}
+        )
+        assert is_create_media_buy_submitted(submitted) is True
+        assert is_create_media_buy_success(submitted) is False
+        assert is_create_media_buy_error(submitted) is False
+
+        # Negative cases: success and error payloads must not be classified
+        # as submitted.
+        success = CreateMediaBuySuccessResponse.model_validate(
+            {"media_buy_id": "mb_123", "packages": []}
+        )
+        assert is_create_media_buy_submitted(success) is False
+
+        error = CreateMediaBuyErrorResponse.model_validate(
+            {"errors": [{"message": "fail", "code": "INVALID_REQUEST"}]}
+        )
+        assert is_create_media_buy_submitted(error) is False
 
     def test_update_media_buy_guards(self) -> None:
         from adcp.types.aliases import (