@adcp/sdk 7.10.2 → 7.11.1

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

@@ -0,0 +1,565 @@
+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"