@adcp/sdk 6.8.0 → 6.10.0

package/compliance/cache/3.0.6/protocols/media-buy/scenarios/pending_creatives_to_start.yaml

@@ -0,0 +1,250 @@
+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
+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.
+
+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."
+          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"
+
+  - 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: "pending-creatives-transition-v1"
+          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:
+            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: "status"
+            value: "pending_creatives"
+            description: "Status is pending_creatives because no creatives supplied"
+          - 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"
+
+  - 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: "status"
+            allowed_values: ["pending_start", "active"]
+            description: "Status advances out of pending_creatives once creatives attached"
+
+  - 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"

package/compliance/cache/3.0.6/protocols/media-buy/scenarios/proposal_finalize.yaml

@@ -0,0 +1,243 @@
+id: media_buy_seller/proposal_finalize
+version: "1.0.0"
+title: "Seller handles proposal refinement and finalize"
+category: media_buy_seller
+summary: "Verifies the full proposal lifecycle: brief with proposals, refine a proposal, finalize to committed, and accept via create_media_buy."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+
+narrative: |
+  Proposals are curated media plans that the seller generates alongside products. The buyer
+  reviews proposals, refines them (adjust budget splits, swap products, add constraints),
+  and then finalizes a proposal to get firm pricing and an inventory hold. Once committed,
+  the buyer accepts the proposal via create_media_buy.
+
+  The proposal lifecycle is: draft (indicative pricing) -> refine -> finalize (firm pricing,
+  inventory hold) -> create_media_buy (accept and go live).
+
+  This scenario exercises the complete proposal flow including the finalize action, which
+  transitions a proposal from draft to committed status with an expires_at hold window.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+    - generates_proposals
+  examples:
+    - "Full-service publisher with proposal engine"
+    - "Retail media network with curated packages"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and operator credentials. The seller must support
+    proposal generation (return proposals alongside products in get_products responses).
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: setup
+    title: "Account setup"
+    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_proposal_finalize_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: brief_with_proposals
+    title: "Brief with proposals"
+    narrative: |
+      Send a brief and receive proposals alongside products. Proposals are curated
+      media plans with budget allocations the buyer can review and refine.
+
+    steps:
+      - id: get_products_brief
+        title: "Send a brief and receive proposals"
+        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 and proposals matching the brief:
+          - products: individual products with pricing and forecasts
+          - proposals: curated media plans with proposal_id, budget_allocations, rationale
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video and display across outdoor lifestyle and sports. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          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"
+          - check: field_present
+            path: "proposals"
+            description: "Response contains proposals"
+          - check: field_present
+            path: "proposals[0].proposal_id"
+            description: "Proposals have IDs"
+
+  - id: refine_proposal
+    title: "Refine the proposal"
+    narrative: |
+      The buyer reviews the proposals and wants to adjust one. They call get_products in
+      refine mode targeting a specific proposal_id with changes. The seller applies the
+      refinements and returns the updated proposal.
+
+    steps:
+      - id: get_products_refine
+        title: "Refine a specific proposal"
+        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: true
+        expected: |
+          Return the refined proposal:
+          - proposals: updated proposal reflecting the requested changes
+          - refinement_applied: how each refinement was handled
+          - Updated budget allocations, product selections, and forecasts
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "balanced_reach_q2"
+              ask: "Shift 60% of budget to CTV. Drop the display product and redistribute that budget to video."
+            - scope: "request"
+              ask: "All products must support frequency capping at 3 per day."
+          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: "proposals"
+            description: "Response contains updated proposals"
+
+  - id: finalize_proposal
+    title: "Finalize the proposal"
+    narrative: |
+      The buyer is satisfied with the refined proposal and requests finalization. This
+      triggers the transition from draft (indicative pricing) to committed (firm pricing
+      with inventory hold). The seller may need time to process this — the buyer should
+      not set a time_budget to signal willingness to wait.
+
+      After finalization, the proposal has firm pricing and an expires_at timestamp.
+      The buyer must create the media buy before the hold expires.
+
+    steps:
+      - id: get_products_finalize
+        title: "Finalize the proposal"
+        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: true
+        expected: |
+          Return the finalized proposal with committed status:
+          - proposals[0].proposal_status: committed
+          - proposals[0].expires_at: timestamp for the inventory hold window
+          - Firm pricing (not indicative)
+          - The proposal is ready to accept via create_media_buy
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "balanced_reach_q2"
+              action: "finalize"
+          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: "proposals"
+            description: "Response contains the finalized proposal"
+
+  - id: accept_proposal
+    title: "Accept the committed proposal"
+    narrative: |
+      The buyer accepts the committed proposal by creating a media buy with the
+      proposal_id. The seller converts the proposal's product selections and budget
+      allocations into active packages.
+
+    steps:
+      - id: create_media_buy
+        title: "Create media buy from proposal"
+        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: |
+          Convert the committed proposal into an active media buy:
+          - media_buy_id: the seller's identifier
+          - status: active
+          - confirmed_at: timestamp
+          - packages: line items derived from the proposal's budget allocations
+          - proposal_id: echoed back to confirm which proposal was accepted
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          proposal_id: "balanced_reach_q2"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_proposal_finalize_accept_proposal_create_media_buy"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"

package/compliance/cache/3.0.6/protocols/media-buy/scenarios/refine_products.yaml

@@ -0,0 +1,148 @@
+id: media_buy_seller/refine_products
+version: "1.0.0"
+title: "Seller handles product refinement"
+category: media_buy_seller
+summary: "Verifies that a media buy seller supports buying_mode: refine with product-level and request-level changes."
+track: media_buy
+required_tools:
+  - get_products
+
+narrative: |
+  After a buyer receives products from a brief, they refine the results without starting
+  over. The buyer calls get_products with buying_mode: refine and a refine array describing
+  changes at the request level ("only guaranteed") or product level ("increase this product's
+  budget").
+
+  The seller must apply each refinement, return updated products, and include
+  refinement_applied showing how each request was handled. This is the standard negotiation
+  loop — brief, review, refine, repeat until satisfied.
+
+  Every media buy seller that supports negotiation (not just wholesale) must handle
+  product-level refinement.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+  examples:
+    - "Any media buy seller that accepts briefs"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and operator credentials.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: setup
+    title: "Account setup"
+    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_refine_products_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: brief
+    title: "Initial brief"
+    narrative: |
+      Send a brief to get the initial product set that the buyer will refine.
+
+    steps:
+      - id: get_products_brief
+        title: "Send a brief"
+        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. Each product should include product_id,
+          delivery_type, pricing_models, and forecast.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video and display on sports and outdoor lifestyle. Q2 flight, $50K budget. Adults 25-54, US and Canada."
+          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"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "Products have IDs"
+
+  - id: refine
+    title: "Refine products"
+    narrative: |
+      The buyer has reviewed the initial products and wants to narrow down. They call
+      get_products with buying_mode: refine and a refine array with request-level and
+      product-level changes. The seller applies each refinement and returns the updated
+      product set.
+
+    steps:
+      - id: get_products_refine
+        title: "Refine with request-level and product-level changes"
+        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: true
+        expected: |
+          Return updated products reflecting the refinements:
+          - Apply each refinement to the relevant scope (request or product)
+          - Include refinement_applied showing how each request was handled
+          - Preserve products that weren't targeted by refinements
+          - Update pricing and forecasts to reflect the changes
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "request"
+              ask: "Only guaranteed packages. Must include completion rate SLA above 80%."
+            - scope: "product"
+              product_id: "sports_preroll_q2"
+              ask: "Increase budget allocation to $30K"
+          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 updated products"