@adcp/sdk 7.11.0 → 7.11.1

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

@@ -0,0 +1,399 @@
+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
+
+requires_capability:
+  path: media_buy.supports_proposals
+  equals: true
+
+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"
+
+        context_outputs:
+          - path: "proposals[0].proposal_id"
+            key: "proposal_id"
+
+        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: "$context.proposal_id"
+              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: unknown_proposal_finalize
+    title: "Reject unknown proposals during finalization"
+    narrative: |
+      The buyer asks to finalize a proposal reference that was never issued by
+      the seller. The request is schema-valid; the rejection is semantic and
+      must use the canonical proposal-not-found code.
+
+    steps:
+      - id: get_products_finalize_unknown_proposal
+        title: "Reject finalize against an unknown 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"
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Reject with:
+          - code: PROPOSAL_NOT_FOUND
+          - recovery: correctable
+          - field: refine[0].proposal_id
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "prop_unknown_proposal_not_found"
+              action: "finalize"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+        validations:
+          - check: error_code
+            value: "PROPOSAL_NOT_FOUND"
+            description: "Unknown proposal finalize returns the canonical proposal-not-found code"
+          - check: field_value
+            path: "adcp_error.recovery"
+            value: "correctable"
+            description: "Recovery is correctable"
+          - check: field_value
+            path: "adcp_error.field"
+            value: "refine[0].proposal_id"
+            description: "Error field identifies the missing proposal reference"
+
+  - 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: "$context.proposal_id"
+              action: "finalize"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+        context_outputs:
+          - path: "proposals[0].insertion_order.io_id"
+            key: "io_id"
+
+        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: "$context.proposal_id"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          io_acceptance:
+            io_id: "$context.io_id"
+            accepted_at: "2026-03-15T14:30:00Z"
+            signatory: "ops@acmeoutdoor.example"
+
+          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"
+
+  - id: unknown_proposal_references
+    title: "Reject unknown proposal references"
+    narrative: |
+      The buyer references proposal IDs that were never issued by the seller.
+      These requests are schema-valid; the rejection is semantic. The seller
+      must return the canonical PROPOSAL_NOT_FOUND code rather than generic
+      NOT_FOUND, INVALID_REQUEST, or platform-specific proposal errors.
+
+    steps:
+      - id: get_products_refine_unknown_proposal
+        title: "Reject refine against an unknown 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"
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Reject with:
+          - code: PROPOSAL_NOT_FOUND
+          - recovery: correctable
+          - field: refine[0].proposal_id
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "prop_unknown_proposal_not_found"
+              ask: "Shift budget toward premium video."
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+        validations:
+          - check: error_code
+            value: "PROPOSAL_NOT_FOUND"
+            description: "Unknown proposal refine returns the canonical proposal-not-found code"
+          - check: field_value
+            path: "adcp_error.recovery"
+            value: "correctable"
+            description: "Recovery is correctable"
+          - check: field_value
+            path: "adcp_error.field"
+            value: "refine[0].proposal_id"
+            description: "Error field identifies the missing proposal reference"
+
+      - id: create_media_buy_unknown_proposal
+        title: "Reject create_media_buy from an unknown 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
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Reject with:
+          - code: PROPOSAL_NOT_FOUND
+          - recovery: correctable
+          - field: proposal_id
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          proposal_id: "prop_unknown_proposal_not_found"
+          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_unknown_proposal_create_media_buy"
+        validations:
+          - check: error_code
+            value: "PROPOSAL_NOT_FOUND"
+            description: "Unknown proposal create returns the canonical proposal-not-found code"
+          - check: field_value
+            path: "adcp_error.recovery"
+            value: "correctable"
+            description: "Recovery is correctable"
+          - check: field_value
+            path: "adcp_error.field"
+            value: "proposal_id"
+            description: "Error field identifies the missing proposal reference"

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

@@ -0,0 +1,264 @@
+id: media_buy_seller/proposal_finalize_asap_timing
+version: "1.0.0"
+title: "Seller handles proposal finalize — asap start_time form"
+category: media_buy_seller
+summary: "Variant of proposal_finalize that exercises start_time: 'asap' on create_media_buy, catching wrapper-layer rejections of the spec-defined string literal form."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+
+requires_capability:
+  path: media_buy.supports_proposals
+  equals: true
+
+narrative: |
+  Mirrors the proposal_finalize scenario but passes start_time: "asap" (the spec-defined
+  string literal from start-timing.json) when accepting the committed proposal. This arm
+  catches implementations that accept ISO 8601 dates but reject the "asap" string form
+  at the wrapper/validation layer before the handler's date-carry-forward logic runs.
+
+  The AdCP spec defines start_time as a oneOf over two string variants: the literal "asap"
+  and an ISO 8601 date-time string. Both must be accepted by conformant sellers.
+
+  Background: an adopter identified that their Pydantic wrapper was rejecting
+  "asap" at the input-validation layer. The current proposal_finalize scenario only tests
+  the ISO date form; this variant provides coverage for the "asap" form.
+
+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_asap_timing_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.
+
+    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"
+
+        context_outputs:
+          - path: "proposals[0].proposal_id"
+            key: "proposal_id"
+
+        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 and refines the proposal before finalization.
+
+    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 reflecting the requested changes.
+
+        sample_request:
+          buying_mode: "refine"
+          refine:
+            - scope: "proposal"
+              proposal_id: "$context.proposal_id"
+              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 requests finalization to transition the proposal from draft to committed
+      with firm pricing and an inventory hold.
+
+    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: "$context.proposal_id"
+              action: "finalize"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+        context_outputs:
+          - path: "proposals[0].insertion_order.io_id"
+            key: "io_id"
+
+        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 with start_time: asap"
+    narrative: |
+      The buyer accepts the committed proposal via create_media_buy, supplying
+      start_time as the string literal "asap" (the spec-defined form from
+      start-timing.json). This verifies the seller's input-validation layer
+      accepts this form without rejecting it before the handler runs.
+
+      io_acceptance is included so this scenario works against sellers that
+      finalize proposals with requires_signature: true (the common production
+      shape). The asap-vs-iso check is on start_time only — passing io_acceptance
+      keeps the IO gate satisfied so the start_time form is the discriminator.
+
+      Response field checks (media_buy_id, status, etc.) are intentionally limited
+      to response_schema here. Behavioral verification of the create_media_buy
+      response is the parent proposal_finalize scenario's job. This variant's sole
+      purpose is to confirm the seller's input layer does not reject start_time:
+      "asap" before the handler runs — a non-error response satisfies that.
+
+    steps:
+      - id: create_media_buy
+        title: "Create media buy from proposal — start_time: asap"
+        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
+
+          The seller MUST accept start_time: "asap" (string literal) without
+          rejecting it at the wrapper/input-validation layer.
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+            sandbox: true
+          proposal_id: "$context.proposal_id"
+          total_budget:
+            amount: 50000
+            currency: "USD"
+          start_time: "asap"
+          end_time: "2026-06-30T23:59:59Z"
+          io_acceptance:
+            io_id: "$context.io_id"
+            accepted_at: "2026-03-15T14:30:00Z"
+            signatory: "ops@acmeoutdoor.example"
+
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_proposal_finalize_asap_timing_accept_proposal_create_media_buy"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"