@adcp/sdk 6.8.0 → 6.10.0

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

@@ -0,0 +1,284 @@
+id: media_buy_seller/invalid_transitions
+version: "1.0.0"
+title: "Seller rejects illegal state transitions and unknown references"
+category: media_buy_seller
+summary: "Validates that the seller returns structured AdCP errors (MEDIA_BUY_NOT_FOUND, PACKAGE_NOT_FOUND, NOT_CANCELLABLE) rather than 500s or undefined behavior when the buyer references missing entities or attempts forbidden state transitions."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+  - update_media_buy
+
+narrative: |
+  Error-code coverage is the most common compliance gap: sellers accept malformed input
+  silently or return generic 500s rather than the specific AdCP codes the spec defines.
+  This scenario forces three of the most-referenced media_buy error codes with
+  deterministic input:
+
+  - MEDIA_BUY_NOT_FOUND — buyer references a media_buy_id that does not exist.
+  - PACKAGE_NOT_FOUND — media_buy_id is valid but package_id inside it is not.
+  - NOT_CANCELLABLE — buyer cancels the same media buy twice; the second cancel must
+    be rejected because canceled is terminal.
+
+  All three probes use hard `check: error_code` assertions so a seller that returns
+  a 500 or swallows the error fails the scenario outright. Recovery hints, correlation
+  echo, and context preservation are also checked on every error response.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any media buy seller"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    Seller supports create_media_buy and update_media_buy with cancellation via
+    the canceled field.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: unknown_media_buy
+    title: "Reference an unknown media_buy_id"
+    narrative: |
+      Before any state is set up, call update_media_buy with a fabricated media_buy_id.
+      The seller must return MEDIA_BUY_NOT_FOUND with a correctable recovery hint — not
+      a 500 and not a silent success.
+
+    steps:
+      - id: update_unknown_media_buy
+        title: "update_media_buy with bogus media_buy_id"
+        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
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: false
+        expected: |
+          Reject with:
+          - code: MEDIA_BUY_NOT_FOUND
+          - recovery: correctable
+          - context echoed unchanged
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "does-not-exist-invalid-transitions-v1"
+          paused: true
+          idempotency_key: "$generate:uuid_v4#update_unknown_media_buy"
+          context:
+            correlation_id: "invalid_transitions--update_unknown_media_buy"
+        validations:
+          - check: error_code
+            value: "MEDIA_BUY_NOT_FOUND"
+            description: "Error code is MEDIA_BUY_NOT_FOUND"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "invalid_transitions--update_unknown_media_buy"
+            description: "Context correlation_id returned unchanged"
+
+  - id: setup
+    title: "Create a real media buy for follow-up probes"
+    narrative: |
+      The remaining probes need a real media_buy_id and package_id. Discover a product
+      and create a plain buy — no targeting tricks, no governance — so we have known-good
+      IDs for the error cases.
+
+    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 pricing.
+        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"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+
+      - id: create_buy
+        title: "Create a buy for the error probes"
+        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 and at least one package.
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "invalid-transitions-setup-v1"
+          start_time: "2026-08-01T00:00:00Z"
+          end_time: "2026-08-31T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 5000
+              pricing_option_id: "$context.pricing_option_id"
+          context:
+            correlation_id: "invalid_transitions--create_buy"
+        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 returns media_buy_id"
+
+  - id: unknown_package
+    title: "Reference an unknown package_id on a real buy"
+    narrative: |
+      The media_buy_id is real, but the package_id is fabricated. The seller must
+      return PACKAGE_NOT_FOUND — distinct from MEDIA_BUY_NOT_FOUND — because the
+      lookup succeeds at the buy level and only fails at the package lookup.
+
+    steps:
+      - id: update_unknown_package
+        title: "update_media_buy with bogus package_id"
+        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
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Reject with:
+          - code: PACKAGE_NOT_FOUND
+          - recovery: correctable
+          - context echoed unchanged
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "$context.media_buy_id"
+          idempotency_key: "$generate:uuid_v4#update_unknown_package"
+          packages:
+            - package_id: "does-not-exist-package-invalid-transitions-v1"
+              paused: true
+          context:
+            correlation_id: "invalid_transitions--update_unknown_package"
+        validations:
+          - check: error_code
+            value: "PACKAGE_NOT_FOUND"
+            description: "Error code is PACKAGE_NOT_FOUND"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "invalid_transitions--update_unknown_package"
+            description: "Context correlation_id returned unchanged"
+
+  - id: double_cancel
+    title: "Cancel twice — second cancel is not valid"
+    narrative: |
+      Cancel the buy (success), then try to cancel the same buy again. canceled is
+      terminal per the AdCP spec, so the second cancel cannot succeed. The seller
+      must return NOT_CANCELLABLE — the schema specifically reserves this code for
+      "media buy cannot be canceled in its current state."
+
+    steps:
+      - id: first_cancel
+        title: "Cancel the media buy"
+        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: |
+          Seller acknowledges the cancellation and transitions the buy to canceled.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "$context.media_buy_id"
+          canceled: true
+          cancellation_reason: "Testing NOT_CANCELLABLE on re-cancel"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_invalid_transitions_double_cancel_first_cancel"
+          context:
+            correlation_id: "invalid_transitions--first_cancel"
+        validations:
+          - check: response_schema
+            description: "Response matches update-media-buy-response.json schema"
+
+      - id: second_cancel
+        title: "Re-cancel the canceled buy"
+        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
+        expect_error: true
+        negative_path: payload_well_formed
+        stateful: true
+        expected: |
+          Reject with:
+          - code: NOT_CANCELLABLE
+          - recovery: correctable
+          - context echoed unchanged
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          media_buy_id: "$context.media_buy_id"
+          canceled: true
+          cancellation_reason: "Deliberate re-cancel to force NOT_CANCELLABLE"
+          idempotency_key: "$generate:uuid_v4#media_buy_seller_invalid_transitions_double_cancel_second_cancel"
+          context:
+            correlation_id: "invalid_transitions--second_cancel"
+        validations:
+          - check: error_code
+            value: "NOT_CANCELLABLE"
+            description: "Error code is NOT_CANCELLABLE on re-cancel of canceled buy"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object even on errors"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "invalid_transitions--second_cancel"
+            description: "Context correlation_id returned unchanged"

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

@@ -0,0 +1,143 @@
+id: media_buy_seller/inventory_list_no_match
+version: "1.0.0"
+title: "Seller handles property_list / collection_list references that match zero inventory"
+category: media_buy_seller
+summary: "Verifies a seller returns a zero-forecast product or a clear error — not a crash — when a buyer references inventory lists that resolve to nothing in the seller's catalog."
+track: media_buy
+required_tools:
+  - get_products
+  - create_media_buy
+
+narrative: |
+  Not every buyer list matches every seller's inventory. A buyer may point at a
+  property_list of domains this seller does not carry, or a collection_list of
+  programs this seller does not syndicate. The seller must handle that gracefully:
+
+  - Return a product with a zero forecast and explain the mismatch, OR
+  - Return an informative error on create_media_buy (INSUFFICIENT_INVENTORY or
+    similar) with findings the buyer can act on.
+
+  What the seller must NOT do: crash, return a misleading non-zero forecast, or
+  silently drop the targeting and deliver against unintended inventory. Each of
+  those is a real failure mode we've seen in adapter integrations.
+
+  This scenario exercises the no-match path using the test kit's pre-populated
+  no_match_properties and no_match_collections lists.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - supports_property_list_targeting
+    - supports_collection_list_targeting
+  examples:
+    - "Sellers that validate inventory against buyer-supplied lists"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The seller must resolve PropertyListReference / CollectionListReference against
+    its own inventory and report a truthful outcome when nothing matches.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: discover
+    title: "Discover products"
+    steps:
+      - id: get_products_brief
+        title: "Discover 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: full_sales_flow
+        stateful: false
+        expected: |
+          Return products the seller carries.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Video inventory on outdoor lifestyle programming. Q3 flight."
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "inventory_list_no_match--get_products_brief"
+        context_outputs:
+          - path: "products[0].product_id"
+            key: "product_id"
+          - path: "products[0].pricing_options[0].pricing_option_id"
+            key: "pricing_option_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+
+  - id: no_match_attempt
+    title: "Create buy with lists that match no inventory"
+    narrative: |
+      The buyer references the no-match property list and the no-match collection
+      list. Neither list resolves to anything in the seller's catalog. The seller
+      must either (a) accept the buy and surface a zero-delivery expectation, or
+      (b) reject it with an informative error. Silent success with undefined
+      delivery behaviour is not acceptable.
+
+    steps:
+      - id: create_buy_no_match
+        title: "create_media_buy against empty intersections"
+        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: |
+          One of two acceptable outcomes:
+
+          1. Buy accepted with zero-forecast reporting — status may be
+             pending_creatives/pending_start/active, but the seller returns
+             packages with forecast indicating zero deliverable inventory and
+             a message explaining the list mismatch.
+
+          2. Buy rejected with an informative error — typically
+             INSUFFICIENT_INVENTORY or INVALID_TARGETING — including findings
+             that identify which list(s) matched nothing.
+
+          What is NOT acceptable: a silently-successful buy with normal forecast
+          numbers, or a crash / non-AdCP error shape.
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          idempotency_key: "inventory-list-no-match-v1"
+          start_time: "2026-07-01T00:00:00Z"
+          end_time: "2026-09-30T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 10000
+              pricing_option_id: "$context.pricing_option_id"
+              targeting_overlay:
+                property_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_no_match_v1"
+                collection_list:
+                  agent_url: "https://governance.pinnacle-agency.example"
+                  list_id: "acme_outdoor_no_match_collections_v1"
+
+          context:
+            correlation_id: "inventory_list_no_match--create_buy_no_match"
+        validations:
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object (success or error)"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "inventory_list_no_match--create_buy_no_match"
+            description: "Context correlation_id returned unchanged"