@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/domains/media-buy/scenarios/clicks_buy_flow.yaml

@@ -0,0 +1,264 @@
+id: media_buy_seller/clicks_buy_flow
+version: "1.0.0"
+title: "Seller fulfills a media buy with a clicks optimization goal (target CPC)"
+category: media_buy_seller
+summary: "Verifies that a seller advertising clicks in supported_optimization_metrics can accept a media buy whose metric-kind optimization_goal targets cost-per-click and reports clicks + cost_per_click on delivery. Lightweight sibling to the performance scenarios on the click-optimization side: sellers that don't advertise clicks as an optimization metric (rare — most do; pure brand sellers like broadcast TV upper-funnel video are the not_applicable population) grade not_applicable."
+track: media_buy
+
+# Gate: scenario runs only when the seller declares clicks in
+# media_buy.supported_optimization_metrics (proposed in #4669). Most
+# adopters declare clicks (it is the most universal metric in advertising),
+# but broadcast TV upper-funnel video and signal-only sellers honestly
+# don't optimize for clicks and grade `not_applicable`. The gate is what
+# keeps them from being marked failing. Requires runner support for the
+# `contains:` matcher (adcp-client >= 7.70).
+requires_capability:
+  path: media_buy.supported_optimization_metrics
+  contains: "clicks"
+
+required_tools:
+  - get_products
+  - create_media_buy
+  - get_media_buy_delivery
+  - comply_test_controller
+
+invariants:
+  - status.monotonic
+
+narrative: |
+  A "clicks buy" is a media buy whose optimization_goal is metric-kind with
+  metric: clicks and a target_cpc (target.kind: cost_per, value:
+  target-cost-per-click in the buy currency). This is the most common
+  performance-shaped buy in advertising — link clicks, swipe-throughs, CTA
+  taps that navigate away — and the optimization shape is well-understood
+  across the industry. The scenario certifies that the click-optimization
+  path connects end-to-end when the seller advertises clicks as an
+  optimization metric.
+
+  This scenario is intentionally lightweight (no rejection arm) because
+  clicks is universal in semantics — there isn't an obvious unbound-id or
+  unsupported-value to reject. The seller either supports clicks as an
+  optimization metric or it doesn't (handled by the capability gate). The
+  three-phase shape — setup, create, delivery — is sufficient to certify
+  the click-optimization path without manufacturing artificial rejection
+  surfaces.
+
+  Discriminating behaviors this scenario verifies:
+  1. create_media_buy with metric-kind goal (metric: clicks, target.kind:
+     cost_per, target.value: target CPC) is accepted.
+  2. get_media_buy_delivery surfaces totals.clicks and totals.cost_per_click
+     — the discriminating output fields of click optimization. cost_per_click
+     is defined in delivery-metrics.json as spend / clicks; sellers
+     optimizing for clicks MUST populate both fields on delivery.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - supports_non_guaranteed
+  examples:
+    - "DSPs running click-optimized campaigns"
+    - "Social platforms (Meta link clicks, TikTok swipe-throughs)"
+    - "Search-adjacent / native sellers optimizing for CTA taps"
+    - "Retail-media performance products optimizing for product page visits"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must implement comply_test_controller with simulate_delivery
+    (already required for delivery_reporting). simulate_delivery injects
+    impressions, clicks, and spend so get_media_buy_delivery has something
+    to surface for the click-optimized buy.
+
+    The buyer fixture supplies a brand, an operator, and click optimization
+    parameters sufficient to exercise the cost_per target binding.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "clicks_display_q2"
+      delivery_type: "non_guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+  pricing_options:
+    - product_id: "clicks_display_q2"
+      pricing_option_id: "auction_cpm"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_price: 1.50
+
+phases:
+
+  - id: setup
+    title: "Establish account and discover products"
+    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"
+          idempotency_key: "$generate:uuid_v4#clicks_buy_flow_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_for_clicks
+        title: "Discover products that support click optimization"
+        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"
+        stateful: false
+        expected: |
+          Return at least one product whose metric_optimization capabilities
+          include clicks as an optimization metric.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Display performance, US adults 25-54. Q2 flight ~$15K, optimizing for clicks with a target CPC."
+          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_clicks_buy
+    title: "Create a click-optimized buy with a target CPC"
+    narrative: |
+      The buyer creates a media buy whose package carries a metric-kind
+      optimization_goal with metric: clicks and target.kind: cost_per at
+      $2.50 per click. The seller should accept and return a media_buy_id
+      used for subsequent delivery checks.
+
+    steps:
+      - id: create_media_buy_clicks
+        title: "Create media buy with metric-kind clicks goal"
+        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. Response carries a media_buy_id used for
+          subsequent get_media_buy_delivery calls.
+        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: "clicks_display_q2"
+              budget: 15000
+              pricing_option_id: "auction_cpm"
+              optimization_goals:
+                - kind: "metric"
+                  metric: "clicks"
+                  target:
+                    kind: "cost_per"
+                    value: 2.50
+                  priority: 1
+          idempotency_key: "$generate:uuid_v4#clicks_buy_flow_create_clicks_buy_create_media_buy"
+        context_outputs:
+          - name: 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: clicks_delivery
+    title: "Delivery reporting carries clicks and cost_per_click"
+    narrative: |
+      The discriminating assertion of the click-optimization mode: delivery
+      reporting MUST surface clicks and cost_per_click — not just
+      impressions and spend. The runner injects simulated impressions,
+      clicks, and spend via the test controller, then verifies
+      get_media_buy_delivery returns clicks + cost_per_click on totals.
+
+      cost_per_click is defined in delivery-metrics.json as spend / clicks;
+      sellers optimizing for clicks at a cost_per target are committing to
+      populate both fields on delivery responses so the buyer can reconcile
+      effective CPC against the target.
+
+    steps:
+      - id: simulate_clicks_delivery
+        title: "Inject impressions + clicks + spend"
+        task: comply_test_controller
+        requires_tool: comply_test_controller
+        stateful: true
+        expected: |
+          The test controller acknowledges the simulated delivery.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "simulate_delivery"
+          params:
+            media_buy_id: "$context.media_buy_id"
+            impressions: 300000
+            clicks: 4800
+            reported_spend:
+              amount: 11000.00
+              currency: "USD"
+        validations:
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Delivery simulation succeeds"
+
+      - id: get_clicks_delivery
+        title: "Get delivery and verify clicks + cost_per_click metrics"
+        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 includes totals.clicks (the click count) and
+          totals.cost_per_click (effective CPC, spend / clicks). These are
+          the discriminating output fields of click optimization and are
+          required on click-optimized buys.
+        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[0].totals.clicks"
+            description: "Click count surfaced at the buy level"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.cost_per_click"
+            description: "Effective CPC surfaced at the buy level (spend / clicks — the discriminating field of click-optimization with a cost_per target)"

package/compliance/cache/3.1.0-rc.2/domains/media-buy/scenarios/completed_views_buy_flow.yaml

@@ -0,0 +1,344 @@
+id: media_buy_seller/completed_views_buy_flow
+version: "1.0.0"
+title: "Seller fulfills a video media buy with a completed_views optimization goal (target CPCV)"
+category: media_buy_seller
+summary: "Verifies that a seller advertising completed_views in supported_optimization_metrics can accept a media buy whose metric-kind optimization_goal targets completed views at a buyer-supplied view_duration_seconds, reject view_duration_seconds values not in the product's metric_optimization.supported_view_durations, and report completed_views + completion_rate on delivery. Sibling to reach_buy_flow on the video-completion side: sellers without video inventory (display-only DSPs, retail-media networks, audio-only sellers without video products) grade not_applicable."
+track: media_buy
+
+# Gate: scenario runs only when the seller declares completed_views in
+# media_buy.supported_optimization_metrics (proposed in #4669). Sellers
+# without video inventory or whose video products don't optimize for
+# completion (display-only DSPs, retail-media networks, audio-only
+# sellers without video) grade `not_applicable`, not failing. Gating
+# on the explicit metric in supported_optimization_metrics avoids
+# over-claiming against the broad delivery-tracking community.
+# Requires runner support for the `contains:` matcher (adcp-client >= 7.70).
+requires_capability:
+  path: media_buy.supported_optimization_metrics
+  contains: "completed_views"
+
+required_tools:
+  - get_products
+  - create_media_buy
+  - get_media_buy_delivery
+  - comply_test_controller
+
+invariants:
+  - status.monotonic
+
+narrative: |
+  A "completed-views buy" (CPCV — cost per completed view) is a video or
+  audio media buy whose optimization_goal is metric-kind with metric:
+  completed_views, a buyer-supplied view_duration_seconds (e.g., 2 for
+  Snap/LinkedIn defaults, 6 for TikTok, 15 for Meta ThruPlay), and a
+  target.kind: cost_per target. The view_duration_seconds value MUST be
+  in the product's metric_optimization.supported_view_durations — silent
+  rounding to the seller's nearest supported duration would create
+  measurement discrepancies (a buyer targeting 6-second completion would
+  unknowingly be billed against 2-second or 15-second completion).
+
+  Discriminating behaviors this scenario verifies:
+  1. create_media_buy with metric: completed_views, a view_duration_seconds
+     value declared in the product's supported_view_durations, and a
+     target.kind: cost_per target is accepted.
+  2. create_media_buy with a view_duration_seconds value NOT in the
+     product's supported_view_durations is rejected with INVALID_REQUEST.
+     error.field points at the offending view_duration_seconds path.
+     optimization-goal.json:50-53 makes this requirement explicit:
+     "Sellers must reject goals with unsupported values — silent rounding
+     would create measurement discrepancies."
+  3. get_media_buy_delivery surfaces totals.completed_views and
+     totals.completion_rate on delivery. completion_rate is defined in
+     delivery-metrics.json as completed_views / impressions; sellers
+     optimizing for completed_views MUST populate both fields.
+
+  The 999-second view_duration is chosen for the rejection arm because
+  no honest video product will declare a 999-second duration in
+  supported_view_durations — common values are 2, 6, 15, and 30. A
+  seller that round-trips 999 as accepted is demonstrating they don't
+  validate against their product capability declarations.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - supports_non_guaranteed
+  examples:
+    - "CTV sellers optimizing for video completion"
+    - "Social platforms with video completion goals (Meta ThruPlay, TikTok 6-second views)"
+    - "Audio sellers optimizing for podcast/stream completion"
+    - "Online video DSPs with CPCV pricing"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must implement comply_test_controller with simulate_delivery
+    (already required for delivery_reporting). simulate_delivery injects
+    impressions and completed_views so get_media_buy_delivery has something
+    to surface for the completion-optimized buy.
+
+    The buyer fixture supplies a brand, an operator, and video-channel
+    targeting parameters sufficient to exercise the view_duration_seconds
+    binding contract and the unsupported-value rejection.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "cpcv_video_q2"
+      delivery_type: "non_guaranteed"
+      channels: ["video"]
+      format_ids:
+        - id: "video_30s"
+  pricing_options:
+    - product_id: "cpcv_video_q2"
+      pricing_option_id: "auction_cpm"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_price: 12.00
+
+phases:
+
+  - id: setup
+    title: "Establish account and discover products"
+    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"
+          idempotency_key: "$generate:uuid_v4#completed_views_buy_flow_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_for_cpcv
+        title: "Discover video products that support completed_views optimization"
+        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"
+        stateful: false
+        expected: |
+          Return at least one video product whose metric_optimization
+          capabilities include completed_views as an optimization metric and
+          declare supported_view_durations. The buyer selects a duration
+          from that list for the create_media_buy call below.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Online video / CTV, US adults 25-54. Q2 flight ~$30K, optimizing for completed views at a 6-second threshold with target CPCV."
+          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_cpcv_buy
+    title: "Create a completed-views buy at a supported view_duration"
+    narrative: |
+      The buyer creates a media buy whose package carries a metric-kind
+      optimization_goal with metric: completed_views, view_duration_seconds:
+      6 (a common supported value for online video — TikTok native, Meta
+      6-second qualifier), and target.kind: cost_per at $0.05 per completed
+      view. The seller should accept and return a media_buy_id used for
+      subsequent delivery checks.
+
+    steps:
+      - id: create_media_buy_cpcv
+        title: "Create media buy with metric-kind completed_views goal"
+        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. Response carries a media_buy_id used for
+          subsequent get_media_buy_delivery calls.
+        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: "cpcv_video_q2"
+              budget: 30000
+              pricing_option_id: "auction_cpm"
+              optimization_goals:
+                - kind: "metric"
+                  metric: "completed_views"
+                  view_duration_seconds: 6
+                  target:
+                    kind: "cost_per"
+                    value: 0.05
+                  priority: 1
+          idempotency_key: "$generate:uuid_v4#completed_views_buy_flow_create_cpcv_buy_create_media_buy"
+        context_outputs:
+          - name: 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: rejection_unsupported_view_duration
+    title: "Reject a completed_views goal whose view_duration_seconds is not in supported_view_durations"
+    narrative: |
+      Silent acceptance of a view_duration_seconds value not declared in
+      the product's metric_optimization.supported_view_durations is a
+      façade — the seller either rounds to the nearest supported duration
+      (creating measurement discrepancies where the buyer thinks they're
+      paying for 999-second completion but is billed against the rounded
+      duration) or runs without a duration (delivery becomes uncomparable).
+      The seller MUST reject with INVALID_REQUEST and set error.field to
+      the offending view_duration_seconds path. Same shape as the
+      unsupported reach_unit rejection in reach_buy_flow.
+
+      optimization-goal.json:50-53 makes this requirement explicit:
+      "Sellers declare which durations they support in
+      metric_optimization.supported_view_durations. Sellers must reject
+      goals with unsupported values — silent rounding would create
+      measurement discrepancies."
+
+      The literal 999 is chosen because no honest video product will
+      declare a 999-second duration — common values are 2, 6, 15, and 30.
+
+    steps:
+      - id: create_media_buy_with_phantom_view_duration
+        title: "Submit a completed_views goal whose view_duration_seconds is not in supported_view_durations"
+        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"
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with INVALID_REQUEST. error.field points at the offending
+          view_duration_seconds path. media_buy_id is not allocated.
+        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: "cpcv_video_q2"
+              budget: 5000
+              pricing_option_id: "auction_cpm"
+              optimization_goals:
+                - kind: "metric"
+                  metric: "completed_views"
+                  view_duration_seconds: 999
+                  target:
+                    kind: "cost_per"
+                    value: 0.05
+          idempotency_key: "$generate:uuid_v4#completed_views_buy_flow_rejection_unsupported_view_duration"
+        validations:
+          - check: error_code
+            allowed_values: ["INVALID_REQUEST"]
+            description: "Seller rejects the unsupported view_duration_seconds with INVALID_REQUEST"
+          - check: field_value
+            path: "errors[0].field"
+            value: "packages[0].optimization_goals[0].view_duration_seconds"
+            description: "Error.field points at the offending view_duration_seconds path (core/error.json defines field as deterministic JSONPath-lite — literal equality)"
+
+  - id: cpcv_delivery
+    title: "Delivery reporting carries completed_views and completion_rate"
+    narrative: |
+      The discriminating assertion of the completed-views buy mode:
+      delivery reporting MUST surface completed_views and completion_rate
+      — not just impressions and spend. The runner injects simulated
+      impressions and completed_views via the test controller, then
+      verifies get_media_buy_delivery returns completed_views +
+      completion_rate on totals.
+
+      completion_rate is defined in delivery-metrics.json as
+      completed_views / impressions; sellers optimizing for completed_views
+      at a target view_duration_seconds are committing to populate both
+      fields on delivery responses.
+
+    steps:
+      - id: simulate_cpcv_delivery
+        title: "Inject impressions + completed_views + spend"
+        task: comply_test_controller
+        requires_tool: comply_test_controller
+        stateful: true
+        expected: |
+          The test controller acknowledges the simulated delivery.
+        sample_request:
+          account:
+            sandbox: true
+          scenario: "simulate_delivery"
+          params:
+            media_buy_id: "$context.media_buy_id"
+            impressions: 500000
+            completed_views: 350000
+            reported_spend:
+              amount: 18000.00
+              currency: "USD"
+        validations:
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Delivery simulation succeeds"
+
+      - id: get_cpcv_delivery
+        title: "Get delivery and verify completed_views + completion_rate metrics"
+        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 includes totals.completed_views (the completion
+          count at the declared view_duration_seconds threshold) and
+          totals.completion_rate (completed_views / impressions). These two
+          fields are the discriminating output of completed-views
+          optimization and are required on completion-optimized buys.
+        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[0].totals.completed_views"
+            description: "Completed-views count surfaced at the buy level (at the declared view_duration_seconds threshold)"
+          - check: field_present
+            path: "media_buy_deliveries[0].totals.completion_rate"
+            description: "Completion rate surfaced at the buy level (completed_views / impressions)"