@adcp/client 4.22.0 → 4.23.0

package/storyboards/creative_lifecycle.yaml

@@ -0,0 +1,284 @@
+id: creative_lifecycle
+version: "1.0.0"
+title: "Creative lifecycle"
+category: creative_lifecycle
+summary: "Full creative lifecycle on a stateful platform: sync multiple creatives, list with filtering, build and preview across formats, observe status transitions."
+track: creative
+required_tools:
+  - list_creative_formats
+
+narrative: |
+  You run a creative platform with a persistent library — an ad server, creative management
+  platform, or publisher that accepts and stores creative assets. A buyer agent pushes
+  multiple creatives in different formats, queries the library, builds serving tags, previews
+  renderings, and monitors creative status as assets move through your review pipeline.
+
+  This storyboard covers the complete creative lifecycle from the buyer's perspective:
+  uploading assets, browsing the library, building deliverables across formats, and
+  observing status transitions as creatives move from pending_review through to accepted.
+
+  The individual creative storyboards (template, ad server, sales agent) cover specific
+  interaction models. This storyboard tests the full lifecycle across multiple creatives
+  and formats on a single platform.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - has_creative_library
+    - supports_transformation
+  examples:
+    - "Innovid"
+    - "Flashtalking"
+    - "CM360"
+    - "Creative management platforms"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs creative assets in multiple formats (display, video, native) and
+    a brand identity. The test kit provides sample assets at standard ad dimensions.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover_formats
+    title: "Discover accepted formats"
+    narrative: |
+      Before pushing any creatives, the buyer discovers what formats your platform accepts.
+      This determines which assets to prepare and what dimensions and specs to target.
+
+    steps:
+      - id: list_formats
+        title: "List creative formats"
+        narrative: |
+          The buyer calls list_creative_formats to discover what your platform accepts.
+          The response defines format specs: dimensions, asset requirements, mime types,
+          and any platform-specific constraints.
+        task: list_creative_formats
+        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 all creative formats your platform accepts:
+          - format_id with your agent_url and unique id
+          - Asset requirements (dimensions, file sizes, mime types)
+          - Render dimensions
+          - At least two formats (e.g., display and video)
+
+        sample_request: {}
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains formats array"
+
+  - id: sync_multiple
+    title: "Sync multiple creatives"
+    narrative: |
+      The buyer pushes three creatives in different formats to your platform: a display
+      banner, a video spot, and a native card. Your platform validates each creative
+      against its format specs and returns per-creative status.
+
+    steps:
+      - id: sync_creatives
+        title: "Push three creatives in different formats"
+        narrative: |
+          The buyer syncs three creatives simultaneously: a 300x250 display banner, a 30s
+          video spot, and a native content card. Your platform validates each against its
+          format specs and returns per-creative action and status.
+        task: sync_creatives
+        schema_ref: "creative/sync-creatives-request.json"
+        response_schema_ref: "creative/sync-creatives-response.json"
+        doc_ref: "/creative/task-reference/sync_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Accept and validate all three creatives:
+          - Per-creative action: created
+          - Per-creative status: accepted or pending_review
+          - Validation results for each creative
+          - Platform-assigned IDs if applicable
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          creatives:
+            - creative_id: "display_trail_pro_300x250"
+              name: "Trail Pro 3000 - Display 300x250"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                - asset_id: "image"
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-300x250.png"
+                  mime_type: "image/png"
+            - creative_id: "video_30s_trail_pro"
+              name: "Trail Pro 3000 - 30s Video"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "video_30s"
+              assets:
+                - asset_id: "video"
+                  asset_type: "video"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-30s.mp4"
+                  mime_type: "video/mp4"
+            - creative_id: "native_trail_pro"
+              name: "Trail Pro 3000 - Native Card"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "native_content"
+              assets:
+                - asset_id: "image"
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-native.png"
+                  mime_type: "image/png"
+                - asset_id: "headline"
+                  asset_type: "text"
+                  content: "Trail Pro 3000 — Built for the Summit"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "results"
+            description: "Response contains per-creative results"
+
+  - id: list_and_filter
+    title: "List creatives with filtering"
+    narrative: |
+      The buyer queries the creative library to see their synced creatives. First a broad
+      list, then filtered by format. This verifies the library correctly stores and indexes
+      the pushed creatives.
+
+    steps:
+      - id: list_all
+        title: "List all creatives in library"
+        narrative: |
+          The buyer calls list_creatives with no filters to see all creatives in the
+          library for their account. The response includes the three creatives synced
+          in the previous phase.
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Return creatives in the library:
+          - creatives array containing the synced items
+          - Each creative includes: creative_id, name, format_id, status
+          - At least three creatives from the sync phase
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json schema"
+          - check: field_present
+            path: "creatives"
+            description: "Response contains creatives array"
+
+      - id: list_filtered
+        title: "List creatives filtered by format"
+        narrative: |
+          The buyer lists creatives filtered to a specific format (display only). The
+          response should only include creatives matching that format.
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        comply_scenario: creative_lifecycle
+        stateful: true
+        expected: |
+          Return only creatives matching the format filter:
+          - creatives array filtered to display format
+          - Should include display_trail_pro_300x250 but not video or native
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          filters:
+            format_ids:
+              - agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json schema"
+          - check: field_present
+            path: "creatives"
+            description: "Response contains filtered creatives"
+
+  - id: build_and_preview
+    title: "Build and preview across formats"
+    narrative: |
+      The buyer builds serving tags and previews renderings for the synced creatives.
+      This tests multi-format output: a display tag, a VAST tag for video, and a
+      native rendering preview.
+
+    steps:
+      - id: preview_display
+        title: "Preview the display creative"
+        narrative: |
+          The buyer calls preview_creative for the display banner to see how it renders
+          in the platform's environment before going live.
+        task: preview_creative
+        schema_ref: "creative/preview-creative-request.json"
+        response_schema_ref: "creative/preview-creative-response.json"
+        doc_ref: "/creative/task-reference/preview_creative"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Return a preview of the display creative:
+          - preview_url: rendered preview the buyer can inspect
+          - render_dimensions: matches the 300x250 format
+          - status: preview available
+
+        sample_request:
+          creative_id: "display_trail_pro_300x250"
+
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+
+      - id: build_video_tag
+        title: "Build a VAST tag for the video creative"
+        narrative: |
+          The buyer builds a serving tag for the video creative. The platform produces
+          a VAST-compatible tag that the buyer can traffic to ad servers.
+        task: build_creative
+        schema_ref: "creative/build-creative-request.json"
+        response_schema_ref: "creative/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Return a built serving tag for the video creative:
+          - tag: VAST-compatible serving tag or URL
+          - format: matches the video format
+          - creative_id: matches the requested creative
+
+        sample_request:
+          creative_id: "video_30s_trail_pro"
+          output_format:
+            agent_url: "https://your-platform.example.com"
+            id: "vast_30s"
+
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"

package/storyboards/creative_sales_agent.yaml

@@ -3,14 +3,10 @@ version: "1.0.0"
 title: "Sales agent with creative capabilities"
 category: creative_sales_agent
 summary: "Stateful sales agent that accepts pushed creative assets and renders them in its environment."
-platform_types:
-  - retail_media
-  - social_platform
-
 track: creative
 required_tools:
   - sync_creatives
-  - list_creative_formats
+
 narrative: |
   You run a publisher platform, retail media network, or other sell-side system that
   accepts creative assets from buyers. The buyer pushes assets or catalog items to your
@@ -122,7 +118,7 @@ phases:
           - check: response_schema
             description: "Response matches sync-creatives-response.json schema"
           - check: field_present
-            path: "creatives[0].action"
+            path: "results[0].action"
             description: "Each creative has an action (created/updated)"
 
   - id: preview

package/storyboards/creative_template.yaml

@@ -3,14 +3,10 @@ version: "1.0.0"
 title: "Creative template and transformation agent"
 category: creative_template
 summary: "Stateless creative agent that takes assets in, applies templates, and produces tags or rendered output."
-platform_types:
-  - creative_transformer
-  - creative_library
-
 track: creative
 required_tools:
   - build_creative
-  - list_creative_formats
+
 narrative: |
   You build a creative management or rich media platform — think Celtra, a format
   conversion service, or any tool that defines ad templates and transforms input assets

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"