@adcp/sdk 7.11.0 → 7.11.1

package/compliance/cache/3.1.0-rc.2/protocols/media-buy/scenarios/creative_reception.yaml

@@ -0,0 +1,247 @@
+id: media_buy_seller/creative_reception
+version: "1.0.0"
+title: "Sales agent with creative capabilities"
+category: media_buy_seller
+summary: "Stateful sales agent that accepts pushed creative assets and renders them in its environment."
+track: creative
+required_tools:
+  - sync_creatives
+
+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
+  platform, and you render them in your environment.
+
+  Your agent is stateful: buyers push creatives to you via sync_creatives, and you
+  persist them for rendering. This is where catalogs get interesting — the buyer might
+  push product feeds (flights, hotels, retail products) that your platform renders as
+  native ads.
+
+  This storyboard walks through the push-and-preview flow from the buyer's perspective.
+
+agent:
+  interaction_model: stateful_push
+  capabilities:
+    - has_creative_library
+  examples:
+    - "Publisher platforms"
+    - "Retail media networks"
+    - "Native ad platforms"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The buyer has creative assets (images, catalog feeds, or ad tags) ready to push.
+    The test kit provides sample assets compatible with common publisher formats.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports creative operations before browsing or building creatives.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring creative in supported_protocols, confirming the agent handles creative operations.
+        sample_request:
+          context:
+            correlation_id: "media_buy_seller_creative_reception--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller_creative_reception--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: discover_accepted_formats
+    title: "Discover accepted formats"
+    narrative: |
+      The buyer first needs to know what creative formats your platform accepts.
+      For a publisher, this includes your native ad formats, display placements,
+      and any custom units. For retail media, this might include product listing
+      formats or sponsored product cards.
+
+    steps:
+      - id: list_formats
+        title: "Discover accepted creative formats"
+        narrative: |
+          The buyer asks: "What creative formats does your platform accept?" Your
+          platform returns the formats you support — native post formats, display
+          units, video slots, or product listing formats.
+        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_sync
+        stateful: false
+        expected: |
+          Return the creative formats your platform accepts. Each format should define:
+          - Asset requirements (what the buyer needs to provide)
+          - Render dimensions
+          - Any catalog requirements (for product-feed formats)
+
+  - id: push_creatives
+    title: "Push creative assets"
+    narrative: |
+      The buyer pushes their creative assets to your platform. This could be:
+      - Standard display assets (images, HTML tags)
+      - Catalog items (product feeds, flight listings, hotel inventory)
+      - Native ad content (headlines, descriptions, images)
+
+      Your platform validates the assets against your format specs and stores them.
+
+    steps:
+      - id: sync_creatives
+        title: "Push creatives to the platform"
+        narrative: |
+          The buyer uploads creative assets to your platform. For standard ads, this
+          is images and copy. For catalog-driven formats, this is a product feed or
+          set of catalog items. Your platform validates each creative against the
+          format's asset requirements and returns a per-creative 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_sync
+        stateful: true
+        expected: |
+          Accept the creatives, validate against format specifications, and return:
+          - Per-creative action (created or updated)
+          - Per-creative status (accepted, pending_review, rejected)
+          - Platform-assigned IDs if applicable
+          - Validation errors for rejected creatives
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "acme_summer_native_001"
+              name: "Acme Summer Sale — native 2026"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "native_post"
+              assets:
+                headline:
+                  asset_type: "text"
+                  content: "Summer Sale — 40% Off All Gear"
+                image:
+                  asset_type: "image"
+                  url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-master.jpg"
+                  width: 1200
+                  height: 628
+                click_url:
+                  asset_type: "url"
+                  url: "https://acmeoutdoor.example/summer-sale"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_creative_reception_push_creatives_sync_creatives"
+          context:
+            correlation_id: "media_buy_seller_creative_reception--sync_creatives"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "creatives[0].action"
+            description: "Each creative has an action (created/updated)"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller_creative_reception--sync_creatives"
+            description: "Context correlation_id returned unchanged"
+  - id: preview
+    title: "Preview pushed creatives"
+    narrative: |
+      After pushing assets, the buyer wants to see how their creatives will render
+      in your platform's environment. For a publisher, this shows the ad in the
+      publication's native chrome — with engagement buttons, community badges, and
+      platform-specific styling that the buyer can't preview elsewhere.
+
+    steps:
+      - id: preview_synced
+        title: "Preview a pushed creative"
+        narrative: |
+          The buyer asks to see how a synced creative will look in your environment.
+          Your platform renders the creative with its native chrome — the surrounding
+          UI, engagement buttons, and platform-specific styling.
+        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 showing the creative in your platform's environment.
+          The preview should include your platform's native chrome — not just the
+          raw assets, but how they'll actually appear to users.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          request_type: "single"
+          creative_manifest:
+            creative_id: "acme_summer_native_001"
+            format_id:
+              agent_url: "https://your-platform.example.com"
+              id: "native_post"
+            assets:
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off"
+              body:
+                asset_type: "text"
+                content: "Top-rated outdoor gear. This weekend only."
+              image:
+                asset_type: "image"
+                url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero.jpg"
+                width: 1200
+                height: 628
+              click_url:
+                asset_type: "url"
+                url: "https://acmeoutdoor.example/summer-sale"
+          output_format: "url"
+          quality: "draft"
+
+          context:
+            correlation_id: "media_buy_seller_creative_reception--preview_synced"
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+          - check: field_present
+            path: "previews[0].renders[0].preview_url"
+            description: "Preview includes a renderable URL"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "media_buy_seller_creative_reception--preview_synced"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/protocols/media-buy/scenarios/delivery_reporting.yaml

@@ -0,0 +1,357 @@
+id: media_buy_seller/delivery_reporting
+version: "1.0.0"
+title: "Seller returns valid delivery reporting"
+category: media_buy_seller
+summary: "Verifies that get_media_buy_delivery returns schema-compliant delivery data after simulated delivery via the test controller."
+track: reporting
+required_tools:
+  - get_products
+  - create_media_buy
+  - get_media_buy_delivery
+  - comply_test_controller
+
+narrative: |
+  Delivery reporting is how buyers know if their campaign is working. The seller must
+  return schema-compliant delivery data from get_media_buy_delivery with per-package
+  metrics (impressions, spend, pacing).
+
+  This scenario creates a media buy, injects delivery data via the test controller's
+  simulate_delivery scenario, then calls get_media_buy_delivery and validates the
+  response against the schema. Without this test, sellers can return arbitrary formats
+  and still pass certification.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any media buy seller"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must implement comply_test_controller with the simulate_delivery
+    scenario. This allows the test harness to inject delivery metrics into a
+    media buy so get_media_buy_delivery has data to return.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "outdoor_display_q2"
+      delivery_type: "guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+    - product_id: "outdoor_video_q2"
+      delivery_type: "guaranteed"
+      channels: ["video"]
+      format_ids:
+        - id: "video_15s"
+    - product_id: "video_viewability_q2"
+      delivery_type: "guaranteed"
+      channels: ["video"]
+      format_ids:
+        - id: "video_15s"
+      metric_optimization:
+        supported_metrics: ["viewed_seconds"]
+  pricing_options:
+    - product_id: "outdoor_display_q2"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 8.0
+    - product_id: "outdoor_video_q2"
+      pricing_option_id: "cpm_standard"
+      pricing_model: "cpm"
+      currency: "USD"
+      fixed_price: 12.0
+    - product_id: "video_viewability_q2"
+      pricing_option_id: "vcpm_standard"
+      pricing_model: "vcpm"
+      currency: "USD"
+      fixed_price: 14.0
+
+phases:
+  - id: setup
+    title: "Create a media buy for delivery testing"
+    steps:
+      - id: sync_accounts
+        title: "Establish account"
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        stateful: true
+        expected: |
+          Return the account with account_id and status active.
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              payment_terms: "net_30"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_delivery_reporting_setup_sync_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "Account has a platform-assigned ID"
+
+      - id: get_products_brief
+        title: "Discover products"
+        task: 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: full_sales_flow
+        stateful: false
+        expected: |
+          Return products matching the brief.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Display and video inventory on outdoor lifestyle content. Q2 flight, $25K budget. Adults 25-54, US."
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains products"
+
+      - id: create_media_buy
+        title: "Create media buy"
+        task: create_media_buy
+        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. We need a media_buy_id to simulate delivery against.
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "outdoor_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+            - product_id: "outdoor_video_q2"
+              budget: 10000
+              pricing_option_id: "cpm_standard"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_delivery_reporting_setup_create_media_buy"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+
+  - id: simulate_and_verify
+    title: "Simulate delivery and validate reporting"
+    narrative: |
+      Inject delivery metrics via the test controller, then call get_media_buy_delivery
+      and validate the response format. This is the core test — does the seller return
+      schema-compliant delivery data with per-package metrics?
+
+    steps:
+      - id: simulate_delivery
+        title: "Inject simulated delivery metrics"
+        task: comply_test_controller
+        requires_tool: comply_test_controller
+        stateful: true
+        expected: |
+          The test controller acknowledges the simulated delivery data.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "simulate_delivery"
+          params:
+            media_buy_id: "$context.media_buy_id"
+            impressions: 5000
+            clicks: 150
+            reported_spend:
+              amount: 250.00
+              currency: "USD"
+        validations:
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Delivery simulation succeeds"
+
+      - id: get_delivery
+        title: "Get delivery report and validate schema"
+        task: get_media_buy_delivery
+        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 reflecting the simulated data:
+          - media_buy_deliveries array with at least one entry
+          - Per-package breakdown with impressions, spend
+          - Response matches the get-media-buy-delivery-response.json schema
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+          include_package_daily_breakdown: true
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"
+          - check: field_present
+            path: "media_buy_deliveries"
+            description: "Response contains delivery data"
+
+  - id: viewability_delivery
+    title: "Delivery reporting surfaces viewability.viewed_seconds for viewability-capable products"
+    narrative: |
+      3.1 adds `viewability.viewed_seconds` to delivery-metrics — the
+      average in-view duration per measurable impression in seconds. It
+      shares the same denominator (`measurable_impressions`) as
+      `viewable_rate` and is governed by the same measurement `standard`
+      (e.g., MRC 50%/1s for display, 50%/2s for video). Sellers reporting
+      against a `viewed_seconds` optimization goal MUST populate this field.
+
+      This phase creates a separate media buy for a viewability-capable
+      vCPM video product, injects simulated delivery with a full viewability
+      block (measurable_impressions, viewable_impressions, viewable_rate,
+      viewed_seconds, standard), and verifies that get_media_buy_delivery
+      returns the viewed_seconds field inside the viewability block.
+      Response schema validation anchors the viewability block shape and
+      scalar bounds; the named fields make the shared denominator explicit
+      for buyers and controller implementers.
+
+    steps:
+      - id: create_media_buy_viewability
+        title: "Create media buy for viewability-capable video product"
+        task: create_media_buy
+        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"
+        stateful: true
+        expected: |
+          Create the media buy. Returns a media_buy_id used for the
+          viewability delivery simulation.
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          start_time: "2026-06-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "video_viewability_q2"
+              budget: 20000
+              pricing_option_id: "vcpm_standard"
+              optimization_goals:
+                - kind: "metric"
+                  metric: "viewed_seconds"
+                  target:
+                    kind: "threshold_rate"
+                    value: 3.0
+                  priority: 1
+          idempotency_key: "$generate:uuid_v4#delivery_reporting_viewability_delivery_create_media_buy"
+        context_outputs:
+          - name: viewability_media_buy_id
+            path: "media_buy_id"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Media buy has a platform-assigned ID"
+
+      - id: simulate_viewability_delivery
+        title: "Inject simulated delivery with full viewability block including viewed_seconds"
+        task: comply_test_controller
+        requires_tool: comply_test_controller
+        stateful: true
+        expected: |
+          The test controller acknowledges the simulated delivery with a
+          full viewability block: measurable_impressions as the shared
+          denominator, viewable_impressions, viewable_rate, viewed_seconds,
+          and the MRC standard.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "simulate_delivery"
+          params:
+            media_buy_id: "$context.viewability_media_buy_id"
+            impressions: 80000
+            viewability:
+              measurable_impressions: 74000
+              viewable_impressions: 59200
+              viewable_rate: 0.80
+              viewed_seconds: 4.3
+              standard: "mrc"
+            reported_spend:
+              amount: 1030.00
+              currency: "USD"
+        validations:
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Delivery simulation with viewability block succeeds"
+
+      - id: get_viewability_delivery
+        title: "Verify viewability.viewed_seconds appears in delivery report"
+        task: get_media_buy_delivery
+        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"
+        stateful: true
+        expected: |
+          Delivery response carries a viewability block with viewed_seconds,
+          measurable_impressions (shared denominator), viewable_rate, and
+          standard. The viewed_seconds value represents the average in-view
+          duration per measurable impression — the reporting counterpart to
+          the viewed_seconds optimization metric. The denominator for both
+          viewable_rate and viewed_seconds is measurable_impressions (not
+          total impressions) since some environments cannot measure viewability.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.viewability_media_buy_id"
+          include_package_daily_breakdown: true
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability"
+            description: "Viewability block present on delivery row"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability.viewed_seconds"
+            description: "viewed_seconds — average in-view duration per measurable impression — present in viewability block"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability.measurable_impressions"
+            description: "measurable_impressions denominator present (shared basis for viewable_rate and viewed_seconds)"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability.viewable_impressions"
+            description: "viewable_impressions numerator present for viewable_rate"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability.viewable_rate"
+            description: "viewable_rate present alongside viewed_seconds in the viewability block"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.viewability.standard"
+            description: "viewability standard present — governs threshold for both viewable_rate and viewed_seconds"