@adcp/sdk 7.11.0 → 7.11.1

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

@@ -0,0 +1,203 @@
+id: media_buy_seller/measurement_terms_rejected
+version: "1.0.0"
+title: "Seller rejects unworkable measurement_terms"
+category: media_buy_seller
+summary: "Buyer proposes measurement_terms the seller will not accept; seller returns TERMS_REJECTED; buyer retries with seller-compatible terms."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+
+narrative: |
+  measurement_terms negotiation is a round-trip. The buyer proposes a measurement vendor,
+  window, and variance tolerance on each package; the seller either accepts (returning
+  measurement_terms echoed in the response) or rejects with TERMS_REJECTED and a message
+  explaining what is unacceptable. The buyer mints a fresh idempotency_key and retries
+  create_media_buy with the adjusted payload — reusing the prior key against a different
+  body MUST be rejected with IDEMPOTENCY_CONFLICT per spec.
+
+  This scenario sends an intentionally aggressive first proposal (max_variance_percent: 0
+  with a window the seller does not guarantee), verifies the seller rejects with
+  TERMS_REJECTED, then retries with a relaxed proposal that falls inside the seller's
+  stated tolerance and expects a successful create_media_buy.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - measurement_terms
+  examples:
+    - "Broadcast sellers"
+    - "CTV sellers with C3/C7 guarantees"
+    - "Any seller that negotiates measurement terms"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    Seller supports measurement_terms on create_media_buy packages. Buyer knows the
+    seller's declared measurement capabilities from get_adcp_capabilities.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover_products
+    title: "Discover products"
+    steps:
+      - id: get_products_brief
+        title: "Find a product that supports measurement_terms"
+        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 with pricing_options. At least one product should advertise
+          measurement support in the response.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory with measurement guarantees. Q3 flight, $50K."
+          filters:
+            is_fixed_price: true
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        context_outputs:
+          - path: "products[0].product_id"
+            key: "product_id"
+          - path: "products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "At least one product returned"
+          - check: field_present
+            path: "products[0].pricing_options[0].fixed_price"
+            description: "The captured pricing option is fixed-price; fixed-price storyboards do not send bid_price"
+
+  - id: reject_terms
+    title: "Seller rejects unworkable terms"
+    narrative: |
+      The buyer proposes max_variance_percent: 0 — a tolerance almost no seller can
+      honor against third-party measurement. The seller must reject with TERMS_REJECTED
+      and indicate what would be acceptable.
+
+    steps:
+      - id: create_media_buy_aggressive_terms
+        title: "Propose aggressive measurement_terms"
+        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
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with:
+          - code: TERMS_REJECTED
+          - recovery: correctable
+          - message indicating which terms are unworkable (vendor, window, or variance)
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_measurement_terms_rejected_reject_terms_create_media_buy_aggressive_terms"
+          start_time: "2026-07-01T00:00:00Z"
+          end_time: "2026-09-30T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 25000
+              pricing_option_id: "$context.pricing_option_id"
+              measurement_terms:
+                billing_measurement:
+                  vendor:
+                    domain: "videoamp.example"
+                  measurement_window: "c28"
+                  max_variance_percent: 0
+                makegood_policy:
+                  available_remedies: ["credit"]
+
+          context:
+            correlation_id: "measurement_terms_rejected--aggressive"
+        validations:
+          - check: error_code
+            value: "TERMS_REJECTED"
+            description: "Error code is TERMS_REJECTED"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "measurement_terms_rejected--aggressive"
+            description: "Context correlation_id returned unchanged"
+
+  - id: accept_terms
+    title: "Buyer retries with acceptable terms"
+    narrative: |
+      The buyer relaxes measurement_terms to match the seller's stated capability
+      (c7 window, 10% variance, makegood remedies) and retries. The seller accepts and
+      returns the confirmed terms echoed in the response.
+
+    steps:
+      - id: create_media_buy_relaxed_terms
+        title: "Propose seller-compatible measurement_terms"
+        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: |
+          The buy succeeds. The response echoes the accepted measurement_terms (possibly
+          normalized by the seller).
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_measurement_terms_rejected_reject_terms_create_media_buy_aggressive_terms"
+          start_time: "2026-07-01T00:00:00Z"
+          end_time: "2026-09-30T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 25000
+              pricing_option_id: "$context.pricing_option_id"
+              measurement_terms:
+                billing_measurement:
+                  vendor:
+                    domain: "videoamp.example"
+                  measurement_window: "c7"
+                  max_variance_percent: 10
+                makegood_policy:
+                  available_remedies: ["additional_delivery", "credit"]
+
+          context:
+            correlation_id: "measurement_terms_rejected--relaxed"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Seller returns a media_buy_id after accepting terms"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "measurement_terms_rejected--relaxed"
+            description: "Context correlation_id returned unchanged"
+        reviewer_checks:
+          - "Reviewer MUST confirm the seller releases the idempotency claim after a TERMS_REJECTED response. Probe: send the aggressive-terms request (same key, step 1), then retry with the same key and corrected terms (this step) — the seller MUST return a fresh media_buy_id, not IDEMPOTENCY_CONFLICT. A seller that caches rejected requests would make this two-step retry pattern impossible. See security.mdx#idempotency rule 3 ('Only successful responses are cached')."

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

@@ -0,0 +1,113 @@
+id: media_buy_seller/package_correlation_legacy_fallback
+version: "1.0.0"
+title: "Legacy package correlation fallback without product_id"
+category: media_buy_seller
+summary: "Models the mixed-seller compatibility path where a legacy package response omits product_id and buyers correlate by package context.buyer_ref."
+track: media_buy
+required_tools:
+  - get_media_buys
+
+narrative: |
+  Current sellers MUST echo package product_id for explicit create_media_buy
+  package requests. Legacy sellers may still return package objects without
+  product_id. Buyers and SDKs targeting mixed seller populations need an
+  executable compatibility vector for that legacy response shape: correlate the
+  seller-assigned package_id back to the requested line item through package
+  context, commonly context.buyer_ref.
+
+  This storyboard is a compatibility fixture, not the current seller
+  conformance path. The runner seeds a legacy-shaped media buy whose package
+  intentionally omits product_id, then verifies get_media_buys still surfaces
+  package-level context so a buyer can recover the mapping.
+
+agent:
+  interaction_model: stateful_preloaded
+  capabilities:
+    - sells_media
+  examples:
+    - "Compatibility test harnesses validating buyer-side package correlation"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The runner seeds a legacy-shaped media buy via seed_media_buy. Sellers or
+    SDK test harnesses that do not implement seed_media_buy grade this scenario
+    not_applicable rather than failing current seller conformance.
+  test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  media_buys:
+    - media_buy_id: "legacy_package_correlation_buy"
+      status: "active"
+      currency: "USD"
+      total_budget: 5000
+      confirmed_at: "2026-04-01T00:00:00Z"
+      revision: 1
+      context:
+        correlation_id: "legacy-package-correlation-media-buy"
+      packages:
+        - package_id: "pkg_legacy_context_only"
+          budget: 5000
+          currency: "USD"
+          context:
+            buyer_ref: "legacy-line-001"
+
+phases:
+  - id: read_legacy_package
+    title: "Read a legacy package shape"
+    narrative: |
+      The buyer reads a seeded media buy whose package intentionally has no
+      product_id. The response must still include package context.buyer_ref,
+      giving the buyer a stable fallback mapping from package_id to the line
+      item it submitted.
+    steps:
+      - id: get_seeded_legacy_buy
+        title: "Get seeded legacy media buy"
+        task: get_media_buys
+        schema_ref: "media-buy/get-media-buys-request.json"
+        response_schema_ref: "media-buy/get-media-buys-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buys"
+        comply_scenario: package_correlation_legacy_fallback
+        stateful: true
+        expected: |
+          Return the seeded media buy with:
+          - media_buys[0].packages[0].package_id present
+          - media_buys[0].packages[0].product_id absent, modeling the legacy response
+          - media_buys[0].packages[0].context.buyer_ref preserved for fallback correlation
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "legacy_package_correlation_buy"
+          context:
+            correlation_id: "package_correlation_legacy_fallback--get_seeded_legacy_buy"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_value
+            path: "media_buys[0].media_buy_id"
+            value: "legacy_package_correlation_buy"
+            description: "The seeded legacy media buy is returned"
+          - check: field_value
+            path: "media_buys[0].packages[0].package_id"
+            value: "pkg_legacy_context_only"
+            description: "Package has the seller-assigned package_id buyers must persist"
+          - check: field_absent
+            path: "media_buys[0].packages[0].product_id"
+            description: "Legacy-shaped package omits product_id; this scenario verifies fallback behavior, not current seller conformance"
+          - check: field_value
+            path: "media_buys[0].packages[0].context.buyer_ref"
+            value: "legacy-line-001"
+            description: "Package context preserves buyer_ref for buyer-side fallback correlation"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "package_correlation_legacy_fallback--get_seeded_legacy_buy"
+            description: "Response context correlation_id returned unchanged"

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

@@ -0,0 +1,292 @@
+id: media_buy_seller/pending_creatives_to_start
+version: "1.0.0"
+title: "Creative sync unblocks pending_creatives → pending_start"
+category: media_buy_seller
+summary: "Verifies that a media buy created without creatives sits in pending_creatives until sync_creatives completes, then transitions to pending_start."
+track: media_buy
+
+# This scenario requires an explicit auto-approval declaration. Sellers that
+# declare `require_human`, or omit the field because approval behavior is
+# legacy-unspecified, grade not_applicable rather than false-failing on a
+# manual-review workflow.
+requires_capability:
+  path: media_buy.creative_approval_mode
+  equals: auto_approve
+
+required_tools:
+  - get_products
+  - create_media_buy
+  - sync_creatives
+  - get_media_buys
+
+narrative: |
+  When a buyer creates a media buy without creative_assignments, the seller cannot start
+  delivery until creatives are supplied. The seller must report status: pending_creatives
+  and, after sync_creatives attaches the required assets, transition the buy to
+  pending_start (awaiting flight start) or active (if already in flight).
+
+  This scenario walks the transition end-to-end: create the buy, confirm pending_creatives,
+  sync a creative, and confirm the status advances to pending_start. The transition
+  proves that the creative pipeline and the buy state machine are wired together — a
+  common integration gap when creative and media buy systems live on different backends.
+  Sellers with manual creative review declare media_buy.creative_approval_mode:
+  require_human and skip this auto-approval-dependent scenario as not_applicable.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_creatives
+  examples:
+    - "Any seller that requires creatives before starting delivery"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    Seller supports create_media_buy without creative_assignments and honors the
+    pending_creatives → pending_start transition when creatives are synced.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: setup
+    title: "Discover products and formats"
+    steps:
+      - id: get_products_brief
+        title: "Discover a product"
+        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 at least one product with format_ids and pricing options.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Display inventory on outdoor lifestyle content. Q3 flight."
+          filters:
+            is_fixed_price: true
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+        context_outputs:
+          - path: "products[0].product_id"
+            key: "product_id"
+          - path: "products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+          - path: "products[0].format_ids[0]"
+            key: "format_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].format_ids[0].id"
+            description: "Product declares a format_id for creative sync"
+          - check: field_present
+            path: "products[0].pricing_options[0].fixed_price"
+            description: "The captured pricing option is fixed-price; fixed-price storyboards do not send bid_price"
+
+  - id: create_without_creatives
+    title: "Create media buy without creative_assignments"
+    narrative: |
+      The buyer intentionally omits creative_assignments. The seller must accept the
+      buy, persist it, and return status: pending_creatives with valid_actions
+      including sync_creatives.
+
+    steps:
+      - id: create_buy_no_creatives
+        title: "Create buy in pending_creatives"
+        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: |
+          Media buy created with:
+          - media_buy_id assigned
+          - status: pending_creatives
+          - valid_actions including sync_creatives
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "$generate:uuid_v4#pending_creatives_to_start_create_buy_no_creatives"
+          start_time: "2026-08-01T00:00:00Z"
+          end_time: "2026-08-31T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 10000
+              pricing_option_id: "$context.pricing_option_id"
+              context:
+                buyer_ref: "pending-creatives-line-001"
+
+          context:
+            correlation_id: "pending_creatives_to_start--create_buy_no_creatives"
+        context_outputs:
+          - path: "media_buy_id"
+            key: "media_buy_id"
+          - path: "packages[0].package_id"
+            key: "package_id"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Seller assigns a media_buy_id"
+          - check: field_value
+            path: "media_buy_status"
+            value: "pending_creatives"
+            description: "media_buy_status is pending_creatives because no creatives supplied"
+          - check: field_value_or_absent
+            path: "status"
+            value: "pending_creatives"
+            description: "Legacy status, when present alongside media_buy_status, MUST carry the same value (3.1 deprecation window — see #4908)"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "pending_creatives_to_start--create_buy_no_creatives"
+            description: "Context correlation_id returned unchanged"
+          - check: field_equals_context
+            path: "packages[0].product_id"
+            context_key: "product_id"
+            description: "Created package echoes the requested product_id for package-to-product correlation"
+          - check: field_value
+            path: "packages[0].context.buyer_ref"
+            value: "pending-creatives-line-001"
+            description: "Created package echoes package-level context for legacy package correlation"
+
+  - id: supply_creatives
+    title: "Supply creatives and assign to the package"
+    narrative: |
+      The buyer syncs a creative with the format the product requires, then updates the
+      media buy with creative_assignments so the seller can attach the asset to the
+      package and advance state.
+
+    steps:
+      - id: sync_creative
+        title: "Sync the creative asset"
+        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: |
+          The seller ingests the creative and returns status active (or approved).
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "acme-outdoor-display-q3"
+              name: "Acme Outdoor Q3 display"
+              format_id: "$context.format_id"
+              assets:
+                image:
+                  asset_type: "image"
+                  url: "https://creative.acmeoutdoor.example/q3/display-300x250.jpg"
+                  width: 300
+                  height: 250
+                  mime_type: "image/jpeg"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_pending_creatives_to_start_supply_creatives_sync_creative"
+          context:
+            correlation_id: "pending_creatives_to_start--sync_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+
+      - id: assign_creative_to_package
+        title: "Assign the creative to the package"
+        task: update_media_buy
+        schema_ref: "media-buy/update-media-buy-request.json"
+        response_schema_ref: "media-buy/update-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/update_media_buy"
+        comply_scenario: media_buy_lifecycle
+        stateful: true
+        expected: |
+          The seller acknowledges the assignment and advances the buy state. The response
+          status should be pending_start (or active if the flight has started).
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "$context.media_buy_id"
+          packages:
+            - package_id: "$context.package_id"
+              creative_assignments:
+                - creative_id: "acme-outdoor-display-q3"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_pending_creatives_to_start_supply_creatives_assign_creative_to_package"
+          context:
+            correlation_id: "pending_creatives_to_start--assign_creative_to_package"
+        validations:
+          - check: response_schema
+            description: "Response matches update-media-buy-response.json schema"
+          - check: field_value
+            path: "media_buy_status"
+            allowed_values: ["pending_start", "active"]
+            description: "media_buy_status advances out of pending_creatives once creatives attached"
+          - check: field_value_or_absent
+            path: "status"
+            allowed_values: ["pending_start", "active"]
+            description: "Legacy status, when present alongside media_buy_status, MUST carry the same value (3.1 deprecation window — see #4908)"
+
+  - id: verify_transition
+    title: "Verify the status transition"
+    narrative: |
+      Independently of the update_media_buy response, call get_media_buys to confirm the
+      seller's stored state has advanced. This protects against sellers that return the
+      updated status in response but do not persist it.
+
+    steps:
+      - id: get_media_buy_after_sync
+        title: "Confirm pending_start after creative sync"
+        task: get_media_buys
+        schema_ref: "media-buy/get-media-buys-request.json"
+        response_schema_ref: "media-buy/get-media-buys-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buys"
+        comply_scenario: media_buy_lifecycle
+        stateful: true
+        expected: |
+          The media buy's persisted status is pending_start (or active). valid_actions
+          no longer includes sync_creatives as a required next step.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_ids:
+            - "$context.media_buy_id"
+
+          context:
+            correlation_id: "pending_creatives_to_start--get_media_buy_after_sync"
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buys-response.json schema"
+          - check: field_value
+            path: "media_buys[0].status"
+            allowed_values: ["pending_start", "active"]
+            description: "Persisted status is past pending_creatives"
+          - check: field_equals_context
+            path: "media_buys[0].packages[0].product_id"
+            context_key: "product_id"
+            description: "Read package retains the product_id from the explicit create request"
+          - check: field_value
+            path: "media_buys[0].packages[0].context.buyer_ref"
+            value: "pending-creatives-line-001"
+            description: "Read package includes persisted package context for legacy package correlation"