@adcp/client 4.22.1 → 4.24.0

package/storyboards/error_compliance.yaml

@@ -1,10 +1,9 @@
 id: error_compliance
 version: "1.0.0"
 title: "Error handling and compliance"
-category: media_buy_seller
-track: error_handling
+category: error_compliance
 summary: "Validates that agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings."
-
+track: error_handling
 required_tools:
   - get_products
 
@@ -33,6 +32,12 @@ caller:
   role: buyer_agent
   example: "Compliance test harness"
 
+prerequisites:
+  description: |
+    No special prerequisites. The storyboard sends intentionally invalid requests
+    to test error handling.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
 phases:
   - id: error_responses
     title: "Error responses for invalid input"
@@ -46,16 +51,19 @@ phases:
         title: "Reject negative budget"
         narrative: |
           A negative budget is never valid. The agent must reject this with INVALID_REQUEST
-          or BUDGET_TOO_LOW and a correctable recovery hint so the buyer knows to fix the value.
+          or BUDGET_TOO_LOW and a correctable recovery hint.
         task: create_media_buy
-        requires_tool: create_media_buy
-        expect_error: true
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: error_handling
         stateful: false
         expected: |
           Reject the request with an error containing:
           - code: INVALID_REQUEST or BUDGET_TOO_LOW
           - recovery: correctable
           - field: packages[0].budget (optional but recommended)
+
         sample_request:
           idempotency_key: "error-test-negative-budget"
           start_time: "2026-05-01T00:00:00Z"
@@ -64,10 +72,11 @@ phases:
             - product_id: "test-product"
               budget: -500
               pricing_option_id: "test-pricing"
+
         validations:
-          - check: error_code
-            value: "INVALID_REQUEST"
-            description: "Error code is INVALID_REQUEST or BUDGET_TOO_LOW"
+          - check: field_present
+            path: "errors"
+            description: "Response contains an error for negative budget"
 
       - id: nonexistent_product
         title: "Reject nonexistent product ID"
@@ -75,157 +84,145 @@ phases:
           The buyer references a product ID that does not exist on this platform.
           The agent should return PRODUCT_NOT_FOUND or INVALID_REQUEST.
         task: create_media_buy
-        requires_tool: create_media_buy
-        expect_error: true
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: error_handling
         stateful: false
         expected: |
-          Reject the request with an error containing:
+          Reject the request with:
           - code: PRODUCT_NOT_FOUND or INVALID_REQUEST
           - recovery: correctable
+
         sample_request:
           idempotency_key: "error-test-nonexistent-product"
           start_time: "2026-05-01T00:00:00Z"
           end_time: "2026-05-31T23:59:59Z"
           packages:
-            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
-              budget: 1000
-              pricing_option_id: "nonexistent-pricing"
+            - product_id: "nonexistent-product-id-xyz"
+              budget: 10000
+              pricing_option_id: "test-pricing"
+
         validations:
-          - check: error_code
-            value: "PRODUCT_NOT_FOUND"
-            description: "Error code is PRODUCT_NOT_FOUND or INVALID_REQUEST"
+          - check: field_present
+            path: "errors"
+            description: "Response contains an error for nonexistent product"
 
       - id: missing_fields
-        title: "Handle empty get_products request"
+        title: "Reject empty get_products request"
         narrative: |
-          The buyer sends an empty get_products request with no brief or brand.
-          The agent may accept it (permissive) or reject it (strict validation).
-          Both behaviors are acceptable — what matters is that the response is structured.
+          Send a get_products request with no brief and no buying_mode. The agent should
+          either return products (treating it as a catalog browse) or return an error
+          requesting the missing brief.
         task: get_products
-        requires_tool: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: error_handling
         stateful: false
         expected: |
-          Either:
-          - Return products (permissive mode)
-          - Return a structured error with INVALID_REQUEST (strict mode)
-          Both are acceptable. An unstructured error or crash is not.
-        sample_request: {}
+          Either return products (treating empty request as browse) or return a
+          structured error requesting the missing brief. Both are valid.
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+
         validations:
           - check: response_schema
-            description: "Response is a valid get-products-response or structured error"
+            description: "Response is either valid products or a structured error"
 
-      - id: reversed_dates
-        title: "Reject end time before start time"
+      - id: reversed_dates_error
+        title: "Reject reversed dates with error code"
         narrative: |
-          The buyer sends a create_media_buy with end_time before start_time.
-          The agent must reject this temporal inconsistency.
+          Send a create_media_buy with end_time before start_time and verify the error
+          response includes the correct code and recovery classification.
         task: create_media_buy
-        requires_tool: create_media_buy
-        expect_error: true
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: error_handling
         stateful: false
         expected: |
-          Reject the request with an error containing:
-          - code: INVALID_REQUEST
-          - recovery: correctable
-          - field: end_time (optional but recommended)
+          Reject with INVALID_REQUEST and correctable recovery.
+
         sample_request:
           idempotency_key: "error-test-reversed-dates"
-          start_time: "2026-05-31T23:59:59Z"
-          end_time: "2026-05-01T00:00:00Z"
+          start_time: "2026-12-31T00:00:00Z"
+          end_time: "2026-01-01T00:00:00Z"
           packages:
             - product_id: "test-product"
-              budget: 1000
+              budget: 10000
               pricing_option_id: "test-pricing"
+
         validations:
-          - check: error_code
-            value: "INVALID_REQUEST"
-            description: "Error code is INVALID_REQUEST for reversed date range"
+          - check: field_present
+            path: "errors"
+            description: "Response contains an error for reversed dates"
 
   - id: error_structure
-    title: "Error JSON structure validation"
+    title: "Error structure compliance"
     narrative: |
-      Beyond returning the right error code, the error object itself must conform to the
-      AdCP error schema. Required fields: code (non-empty string), message (string).
-      Optional fields: recovery (transient|correctable|terminal), retry_after (non-negative
-      number), field (string), suggestion (string). Non-standard codes must use the X_ prefix.
+      Validates that error responses follow the AdCP error structure with required
+      and optional fields.
 
     steps:
       - id: validate_error_shape
-        title: "Validate error JSON structure"
+        title: "Validate error response structure"
         narrative: |
-          Provoke an error and inspect the JSON structure. The error object must have a
-          code and message at minimum. If recovery, retry_after, field, or suggestion are
-          present, they must have the correct types. Non-standard codes must use X_ prefix.
+          Trigger an error and inspect the response structure. The adcp_error object
+          must have code and message. Optional fields include recovery, retry_after,
+          field, and suggestion.
         task: create_media_buy
-        requires_tool: create_media_buy
-        expect_error: true
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: error_codes
         stateful: false
         expected: |
-          Error object with valid structure:
-          - code: non-empty string (standard AdCP code or X_-prefixed vendor code)
-          - message: string
-          - recovery: transient, correctable, or terminal (if present)
-          - retry_after: non-negative number (if present)
-          - field: string path to the offending field (if present)
-          - suggestion: string with remediation hint (if present)
+          Error response with:
+          - code: a recognized AdCP error code
+          - message: human-readable description
+          - recovery: correctable, transient, or fatal (optional)
+
         sample_request:
-          idempotency_key: "error-test-structure"
-          start_time: "2026-05-01T00:00:00Z"
-          end_time: "2026-05-31T23:59:59Z"
+          idempotency_key: "error-structure-test"
+          start_time: "2026-12-31T00:00:00Z"
+          end_time: "2026-01-01T00:00:00Z"
           packages:
-            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
-              budget: 1000
-              pricing_option_id: "nonexistent-pricing"
-        validations:
-          - check: field_present
-            path: "adcp_error.code"
-            description: "Error has a code field"
-          - check: field_present
-            path: "adcp_error.message"
-            description: "Error has a message field"
+            - product_id: "test-product"
+              budget: -1
+              pricing_option_id: "test-pricing"
 
   - id: error_transport
-    title: "Error transport binding validation"
+    title: "Error transport bindings"
     narrative: |
-      AdCP errors must be delivered through the correct MCP transport layers. The isError
-      flag signals the error to the MCP client, the JSON text content provides a fallback
-      for clients that do not support structuredContent, and structuredContent.adcp_error
-      provides the full typed error object.
-
-      Agents using the adcpError() helper from @adcp/client get all three layers automatically.
+      Validates that errors are transported correctly via MCP. The isError flag must
+      be set, and the error should be available in both JSON text content (L2) and
+      structuredContent (L3) bindings.
 
     steps:
       - id: validate_transport_binding
-        title: "Validate structuredContent.adcp_error binding"
+        title: "Validate error transport binding"
         narrative: |
-          Provoke an error and check that it appears in the correct transport layers:
-          - isError: true on the MCP response
-          - JSON text content with adcp_error (L2 fallback)
-          - structuredContent.adcp_error (L3 full compliance)
-
-          L2 is the minimum passing level. L3 is expected for agents using adcpError().
+          Trigger an error and verify the MCP transport binding: isError flag must be
+          set to true, and the error content should include the adcp_error object.
         task: create_media_buy
-        requires_tool: create_media_buy
-        expect_error: true
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: error_transport
         stateful: false
         expected: |
           MCP response with:
           - isError: true
-          - content[].text contains JSON with adcp_error (L2)
-          - structuredContent.adcp_error present (L3)
-          - Error code in structuredContent matches error code in text content (consistency)
+          - content containing adcp_error (L2: JSON text, L3: structuredContent)
+
         sample_request:
-          idempotency_key: "error-test-transport"
-          start_time: "2026-05-01T00:00:00Z"
-          end_time: "2026-05-31T23:59:59Z"
+          idempotency_key: "error-transport-test"
+          start_time: "2026-12-31T00:00:00Z"
+          end_time: "2026-01-01T00:00:00Z"
           packages:
-            - product_id: "NONEXISTENT_PRODUCT_ID_12345"
-              budget: 1000
-              pricing_option_id: "nonexistent-pricing"
-        validations:
-          - check: field_present
-            path: "adcp_error"
-            description: "structuredContent contains adcp_error object"
-          - check: error_code
-            value: "PRODUCT_NOT_FOUND"
-            description: "Error code is a valid AdCP standard code or X_-prefixed vendor code"
+            - product_id: "nonexistent"
+              budget: -1
+              pricing_option_id: "bad-pricing"

package/storyboards/media_buy_catalog_creative.yaml

@@ -3,13 +3,11 @@ version: "1.0.0"
 title: "Catalog-driven creative and conversion tracking"
 category: media_buy_catalog_creative
 summary: "Seller that renders dynamic ads from product catalogs, tracks conversions, and optimizes delivery based on performance feedback."
-platform_types:
-  - retail_media
-
 track: media_buy
 required_tools:
+  - get_products
   - create_media_buy
-  - sync_creatives
+
 narrative: |
   You run a platform that supports catalog-driven advertising — think Snap Dynamic Ads,
   Meta Product Catalogs, or retail media product listing ads. The buyer pushes a product
@@ -112,6 +110,7 @@ phases:
         schema_ref: "creative/list-creative-formats-request.json"
         response_schema_ref: "creative/list-creative-formats-response.json"
         doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_lifecycle
         stateful: false
         expected: |
           Return creative formats that accept catalog assets. Look for formats with
@@ -219,6 +218,7 @@ phases:
         schema_ref: "media-buy/get-products-request.json"
         response_schema_ref: "media-buy/get-products-response.json"
         doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: full_sales_flow
         stateful: false
         expected: |
           Return products that support catalog-driven creative. Products should indicate
@@ -255,11 +255,12 @@ phases:
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/media-buy/task-reference/create_media_buy"
+        comply_scenario: create_media_buy
         stateful: true
         expected: |
           Create the media buy with catalog-driven packages. Return:
           - media_buy_id
-          - status: active or confirmed
+          - status: active
           - packages with catalog references preserved
 
         sample_request:
@@ -427,6 +428,7 @@ phases:
             description: "Response matches provide-performance-feedback-response.json schema"
           - check: field_value
             path: "success"
+            value: true
             description: "Feedback accepted"
 
       - id: check_delivery
@@ -438,6 +440,7 @@ phases:
         schema_ref: "media-buy/get-media-buy-delivery-request.json"
         response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
         doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
+        comply_scenario: reporting_flow
         stateful: true
         expected: |
           Return delivery metrics including impressions, clicks, spend, and