@adcp/sdk 7.11.1 → 7.11.3

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

@@ -1,565 +0,0 @@
-id: media_buy_seller/available_actions
-version: "1.0.0"
-title: "Seller carries product allowed actions into per-buy available actions"
-category: media_buy_seller
-summary: "Validates the AdCP 3.1 media-buy action-discovery flow: product allowed_actions[], buy available_actions[], SLAWindow duration fields, self-serve mutation, and ACTION_NOT_ALLOWED enforcement."
-track: media_buy
-required_tools:
-  - get_products
-  - create_media_buy
-  - get_media_buys
-  - update_media_buy
-
-narrative: |
-  Buyers should not hard-code a seller's media-buy state machine. Sellers
-  declare the product-level action template in get_products.allowed_actions[],
-  resolve it into the authoritative buy-level available_actions[] when the
-  buy is created, return that surface from get_media_buys, and enforce the
-  same surface when update_media_buy is called.
-
-  This scenario creates a media buy from a product whose allowed_actions[]
-  advertise one self-serve budget action, one proposal-routed flight action,
-  and one approval-routed cancellation action. The runner then verifies that
-  the created buy and subsequent get/update responses carry the resolved
-  available_actions[] surface, that the self-serve update succeeds, and that
-  direct updates for non-self-serve or unadvertised product actions reject
-  with ACTION_NOT_ALLOWED.
-
-agent:
-  interaction_model: stateful_preloaded
-  capabilities:
-    - sells_media
-  examples:
-    - "Any AdCP media buy seller exposing the 3.1 action-discovery surface"
-
-caller:
-  role: buyer_agent
-  example: "Pinnacle Agency (buyer)"
-
-prerequisites:
-  description: |
-    The runner seeds a product with allowed_actions[]. The seller must carry
-    that product template into buy-level available_actions[] on create_media_buy,
-    persist it for get_media_buys, and enforce the advertised modes when
-    update_media_buy is called.
-  test_kit: "test-kits/acme-outdoor.yaml"
-  controller_seeding: true
-
-fixtures:
-  products:
-    - product_id: "available_actions_display"
-      name: "Available Actions Display Package"
-      description: "Display inventory fixture used to verify product allowed actions become buy available actions."
-      delivery_type: "guaranteed"
-      channels: ["display"]
-      format_ids:
-        - id: "display_300x250"
-      allowed_actions:
-        - action: "increase_budget"
-          modes: ["self_serve"]
-          sla:
-            response_max: "PT5M"
-            completion_max: "PT1H"
-        - action: "extend_flight"
-          modes: ["requires_proposal"]
-          sla:
-            response_max: "PT4H"
-            completion_max: "P2D"
-          terms_ref: "terms://available-actions/extension"
-        - action: "cancel"
-          modes: ["requires_approval"]
-          sla:
-            response_max: "PT1H"
-            completion_max: "P1D"
-        - action: "decrease_budget"
-          modes: ["self_serve"]
-          allowed_statuses: ["active"]
-  pricing_options:
-    - product_id: "available_actions_display"
-      pricing_option_id: "available_actions_cpm"
-      pricing_model: "cpm"
-      currency: "USD"
-      fixed_price: 8.0
-
-phases:
-  - id: discover_product_action_template
-    title: "Discover product allowed actions"
-    narrative: |
-      The buyer discovers the product-level allowed_actions[] template before
-      creating a media buy. This is the product promise the later buy-level
-      surface must resolve and enforce.
-    steps:
-      - id: get_product_allowed_actions
-        title: "Read allowed_actions from get_products"
-        task: get_products
-        schema_ref: "media-buy/get-products-request.json"
-        response_schema_ref: "media-buy/get-products-response.json"
-        doc_ref: "/media-buy/task-reference/get_products"
-        comply_scenario: media_buy_action_discovery
-        stateful: true
-        expected: |
-          Return the seeded product with allowed_actions[] entries for
-          increase_budget, extend_flight, and cancel.
-        sample_request:
-          buying_mode: brief
-          brief: "available actions display package"
-          filters:
-            channels: ["display"]
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          context:
-            correlation_id: "available_actions--get_products"
-        validations:
-          - check: response_schema
-            description: "Response matches get-products-response.json schema"
-          - check: field_value
-            path: "products[0].product_id"
-            value: "available_actions_display"
-            description: "The seeded product is discoverable through get_products"
-          - check: field_value
-            path: "products[0].allowed_actions[0].action"
-            value: "increase_budget"
-            description: "Product advertises the self-serve budget action"
-          - check: field_value
-            path: "products[0].allowed_actions[0].modes[0]"
-            value: "self_serve"
-            description: "Product declares increase_budget as self-serve"
-          - check: field_value
-            path: "products[0].allowed_actions[0].sla.response_max"
-            value: "PT5M"
-            description: "Product action SLA uses the generated ISO 8601 duration shape"
-          - check: field_value
-            path: "products[0].allowed_actions[1].action"
-            value: "extend_flight"
-            description: "Product advertises the proposal-routed flight extension action"
-          - check: field_value
-            path: "products[0].allowed_actions[1].modes[0]"
-            value: "requires_proposal"
-            description: "Product declares extend_flight as proposal-routed"
-          - check: field_value
-            path: "products[0].allowed_actions[2].action"
-            value: "cancel"
-            description: "Product advertises the approval-routed cancellation action"
-          - check: field_value
-            path: "products[0].allowed_actions[2].modes[0]"
-            value: "requires_approval"
-            description: "Product declares cancel as approval-routed"
-          - check: field_value
-            path: "products[0].allowed_actions[3].action"
-            value: "decrease_budget"
-            description: "Product advertises a status-scoped budget decrease action"
-          - check: field_value
-            path: "products[0].allowed_actions[3].allowed_statuses[0]"
-            value: "active"
-            description: "Product can scope allowed actions to specific buy statuses"
-
-  - id: create_buy_from_product
-    title: "Resolve product actions onto the buy"
-    narrative: |
-      The buyer creates a media buy from the discovered product. The seller
-      must materialize the product-level template into buy-level
-      available_actions[] on the create response.
-    steps:
-      - id: create_media_buy_with_available_actions
-        title: "Create a buy from the action-enabled product"
-        task: create_media_buy
-        schema_ref: "media-buy/create-media-buy-request.json"
-        response_schema_ref: "media-buy/create-media-buy-response.json"
-        doc_ref: "/media-buy/task-reference/create_media_buy"
-        comply_scenario: media_buy_action_discovery
-        stateful: true
-        expected: |
-          Create the buy and return available_actions[] resolved from the
-          product's allowed_actions[] template.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "available_actions_product_mb"
-          start_time: "2026-05-01T00:00:00Z"
-          end_time: "2027-07-31T23:59:59Z"
-          packages:
-            - product_id: "available_actions_display"
-              pricing_option_id: "available_actions_cpm"
-              budget: 10000
-          idempotency_key: "$generate:uuid_v4#available_actions_create_buy"
-          context:
-            correlation_id: "available_actions--create_buy"
-        context_outputs:
-          - path: "media_buy_id"
-            key: "available_actions_media_buy_id"
-          - path: "packages[0].package_id"
-            key: "available_actions_package_id"
-        validations:
-          - check: response_schema
-            description: "Response matches create-media-buy-response.json schema"
-          - check: field_present
-            path: "media_buy_id"
-            description: "Seller returns the created media buy ID"
-          - check: field_present
-            path: "packages[0].package_id"
-            description: "Seller returns the created package ID for later updates"
-          - check: field_value
-            path: "available_actions[0].action"
-            value: "increase_budget"
-            description: "Created buy carries increase_budget from product allowed_actions"
-          - check: field_value
-            path: "available_actions[0].mode"
-            value: "self_serve"
-            description: "Created buy resolves increase_budget to self_serve"
-          - check: field_value
-            path: "available_actions[0].sla.response_max"
-            value: "PT5M"
-            description: "Created buy preserves response_max SLA duration"
-          - check: field_value
-            path: "available_actions[0].sla.completion_max"
-            value: "PT1H"
-            description: "Created buy preserves completion_max SLA duration"
-          - check: field_value
-            path: "available_actions[1].action"
-            value: "extend_flight"
-            description: "Created buy carries extend_flight from product allowed_actions"
-          - check: field_value
-            path: "available_actions[1].mode"
-            value: "requires_proposal"
-            description: "Created buy resolves extend_flight to requires_proposal"
-          - check: field_value
-            path: "available_actions[1].terms_ref"
-            value: "terms://available-actions/extension"
-            description: "Created buy preserves the action terms reference"
-          - check: field_value
-            path: "available_actions[2].action"
-            value: "cancel"
-            description: "Created buy carries cancel from product allowed_actions"
-          - check: field_value
-            path: "available_actions[2].mode"
-            value: "requires_approval"
-            description: "Created buy resolves cancel to requires_approval"
-          - check: field_present
-            path: "valid_actions"
-            description: "Legacy valid_actions may still be present during the 3.x deprecation window"
-
-  - id: read_persisted_buy_actions
-    title: "Read persisted buy actions"
-    narrative: |
-      The buyer reads the created buy. The same available_actions[] surface
-      must persist through get_media_buys; it is the authoritative contract
-      for update_media_buy.
-    steps:
-      - id: get_created_buy_available_actions
-        title: "Read available_actions from get_media_buys"
-        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_action_discovery
-        stateful: true
-        expected: |
-          Return the created buy with the same available_actions[] resolved
-          during create_media_buy.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_ids: ["$context.available_actions_media_buy_id"]
-          context:
-            correlation_id: "available_actions--get_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: "$context.available_actions_media_buy_id"
-            description: "Seller returns the created media buy"
-          - check: field_value
-            path: "media_buys[0].available_actions[0].action"
-            value: "increase_budget"
-            description: "Persisted buy carries the self-serve budget action"
-          - check: field_value
-            path: "media_buys[0].available_actions[0].mode"
-            value: "self_serve"
-            description: "Persisted buy keeps the self-serve mode"
-          - check: field_value
-            path: "media_buys[0].available_actions[1].action"
-            value: "extend_flight"
-            description: "Persisted buy carries the proposal-routed action"
-          - check: field_value
-            path: "media_buys[0].available_actions[1].mode"
-            value: "requires_proposal"
-            description: "Persisted buy keeps the proposal mode"
-          - check: field_value
-            path: "media_buys[0].available_actions[2].action"
-            value: "cancel"
-            description: "Persisted buy carries the approval-routed action"
-          - check: field_value
-            path: "media_buys[0].available_actions[2].mode"
-            value: "requires_approval"
-            description: "Persisted buy keeps the approval mode"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--get_buy"
-            description: "Context correlation_id returned unchanged"
-
-  - id: enforce_available_actions
-    title: "Enforce advertised actions"
-    narrative: |
-      The buyer attempts updates against the created buy. The self-serve action
-      succeeds, proposal/approval modes reject direct mutation with
-      mode_mismatch, and an action never advertised by the product rejects as
-      not_supported_on_product.
-    steps:
-      - id: increase_budget
-        title: "Apply the advertised self-serve budget action"
-        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_action_discovery
-        stateful: true
-        expected: |
-          Accept the budget increase and return the post-update
-          available_actions[] surface.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "$context.available_actions_media_buy_id"
-          packages:
-            - package_id: "$context.available_actions_package_id"
-              budget: 12000
-          idempotency_key: "$generate:uuid_v4#available_actions_increase_budget"
-          context:
-            correlation_id: "available_actions--increase_budget"
-        validations:
-          - check: response_schema
-            description: "Response matches update-media-buy-response.json schema"
-          - check: field_value
-            path: "media_buy_id"
-            value: "$context.available_actions_media_buy_id"
-            description: "Seller updates the requested media buy"
-          - check: field_value
-            path: "available_actions[0].action"
-            value: "increase_budget"
-            description: "Update response carries the post-update action surface"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--increase_budget"
-            description: "Context correlation_id returned unchanged"
-
-      - id: direct_extend_requires_proposal
-        title: "Reject direct update for proposal-routed extension"
-        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_action_discovery
-        expect_error: true
-        negative_path: mode_mismatch
-        stateful: true
-        expected: |
-          Reject with ACTION_NOT_ALLOWED because extend_flight is advertised,
-          but its resolved mode is requires_proposal rather than self_serve.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "$context.available_actions_media_buy_id"
-          end_time: "2027-08-31T23:59:59Z"
-          idempotency_key: "$generate:uuid_v4#available_actions_extend_direct"
-          context:
-            correlation_id: "available_actions--extend_direct"
-        validations:
-          - check: error_code
-            code: ACTION_NOT_ALLOWED
-            description: "Seller rejects direct mutation for proposal-routed action"
-          - check: field_value
-            path: "errors[0].details.attempted_action"
-            value: "extend_flight"
-            description: "Error identifies the attempted fine-grained action"
-          - check: field_value
-            path: "errors[0].details.reason"
-            value: "mode_mismatch"
-            description: "Error distinguishes mode mismatch from unsupported action"
-          - check: field_value
-            path: "errors[0].recovery"
-            value: "correctable"
-            description: "Mode mismatch is a correctable flow-switch recovery"
-          - check: field_value
-            path: "errors[0].details.currently_available_actions[1].mode"
-            value: "requires_proposal"
-            description: "Recovery details echo the current proposal-routed action surface"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--extend_direct"
-            description: "Context correlation_id returned unchanged"
-
-      - id: direct_cancel_requires_approval
-        title: "Reject direct update for approval-routed cancellation"
-        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_action_discovery
-        expect_error: true
-        negative_path: mode_mismatch
-        stateful: true
-        expected: |
-          Reject with ACTION_NOT_ALLOWED because cancel is advertised, but its
-          resolved mode is requires_approval rather than self_serve.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "$context.available_actions_media_buy_id"
-          canceled: true
-          cancellation_reason: "Buyer wants a direct cancellation despite approval routing"
-          idempotency_key: "$generate:uuid_v4#available_actions_cancel_direct"
-          context:
-            correlation_id: "available_actions--cancel_direct"
-        validations:
-          - check: error_code
-            code: ACTION_NOT_ALLOWED
-            description: "Seller rejects direct mutation for approval-routed action"
-          - check: field_value
-            path: "errors[0].details.attempted_action"
-            value: "cancel"
-            description: "Error identifies the attempted fine-grained action"
-          - check: field_value
-            path: "errors[0].details.reason"
-            value: "mode_mismatch"
-            description: "Error distinguishes approval routing from unsupported action"
-          - check: field_value
-            path: "errors[0].recovery"
-            value: "correctable"
-            description: "Approval mode mismatch is a correctable flow-switch recovery"
-          - check: field_value
-            path: "errors[0].details.currently_available_actions[2].mode"
-            value: "requires_approval"
-            description: "Recovery details echo the current approval-routed action surface"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--cancel_direct"
-            description: "Context correlation_id returned unchanged"
-
-      - id: direct_decrease_wrong_status
-        title: "Reject an action whose product status scope does not match"
-        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_action_discovery
-        expect_error: true
-        negative_path: wrong_status
-        stateful: true
-        expected: |
-          Reject with ACTION_NOT_ALLOWED because decrease_budget is supported
-          by the product, but only for active buys. The created buy is still
-          pending_creatives, so the action is not currently available.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "$context.available_actions_media_buy_id"
-          packages:
-            - package_id: "$context.available_actions_package_id"
-              budget: 11000
-          idempotency_key: "$generate:uuid_v4#available_actions_decrease_wrong_status"
-          context:
-            correlation_id: "available_actions--decrease_wrong_status"
-        validations:
-          - check: error_code
-            code: ACTION_NOT_ALLOWED
-            description: "Seller rejects a product-supported action in the wrong buy status"
-          - check: field_value
-            path: "errors[0].details.attempted_action"
-            value: "decrease_budget"
-            description: "Error identifies the attempted fine-grained action"
-          - check: field_value
-            path: "errors[0].details.reason"
-            value: "wrong_status"
-            description: "Error distinguishes status scoping from unsupported action"
-          - check: field_value
-            path: "errors[0].recovery"
-            value: "correctable"
-            description: "Wrong-status action rejection is correctable by waiting for or transitioning status"
-          - check: field_value
-            path: "errors[0].details.currently_available_actions[0].action"
-            value: "increase_budget"
-            description: "Recovery details echo the currently available buy actions"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--decrease_wrong_status"
-            description: "Context correlation_id returned unchanged"
-
-      - id: direct_pause_not_supported_on_product
-        title: "Reject an action the product never advertised"
-        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_action_discovery
-        expect_error: true
-        negative_path: unsupported_action
-        stateful: true
-        expected: |
-          Reject with ACTION_NOT_ALLOWED because pause is not present in the
-          product's allowed_actions[] template and therefore is not available
-          on the buy.
-        sample_request:
-          account:
-            brand:
-              domain: "acmeoutdoor.example"
-            operator: "pinnacle-agency.example"
-          brand:
-            domain: "acmeoutdoor.example"
-          media_buy_id: "$context.available_actions_media_buy_id"
-          paused: true
-          idempotency_key: "$generate:uuid_v4#available_actions_pause_direct"
-          context:
-            correlation_id: "available_actions--pause_direct"
-        validations:
-          - check: error_code
-            code: ACTION_NOT_ALLOWED
-            description: "Seller rejects direct mutation for an action not supported by the product"
-          - check: field_value
-            path: "errors[0].details.attempted_action"
-            value: "pause"
-            description: "Error identifies the attempted fine-grained action"
-          - check: field_value
-            path: "errors[0].details.reason"
-            value: "not_supported_on_product"
-            description: "Error distinguishes product capability from transient buy state"
-          - check: field_value
-            path: "errors[0].recovery"
-            value: "terminal"
-            description: "Unsupported product action is terminal for this buy"
-          - check: field_value
-            path: "errors[0].details.currently_available_actions[0].action"
-            value: "increase_budget"
-            description: "Recovery details echo the currently available buy actions"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "available_actions--pause_direct"
-            description: "Context correlation_id returned unchanged"