@adcp/client 4.21.0 → 4.22.1

package/storyboards/media_buy_state_machine.yaml

@@ -0,0 +1,254 @@
+id: media_buy_state_machine
+version: "1.0.0"
+title: "Media buy state machine lifecycle"
+category: media_buy_seller
+track: media_buy
+summary: "Validates media buy state transitions: create, pause, resume, cancel, and terminal state enforcement."
+
+required_tools:
+  - create_media_buy
+  - update_media_buy
+
+narrative: |
+  A media buy has a well-defined state machine: draft, pending_approval, confirmed, active,
+  paused, completed, canceled. Transitions between states must follow the spec — you cannot
+  resume a canceled buy or pause a completed one.
+
+  This storyboard creates a media buy, walks it through pause/resume/cancel transitions, then
+  verifies that the agent rejects updates to a buy in a terminal state (canceled or completed).
+  It also tests package-level pause/resume independent of the media buy status.
+
+  The state machine is the backbone of media buy reliability. If an agent allows invalid
+  transitions, buyers cannot trust the status field and automation breaks down.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+  examples:
+    - "Any AdCP seller with media buy support"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity for account setup. The test creates a media buy
+    using discovered products, then exercises state transitions.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: setup
+    title: "Create a media buy"
+    narrative: |
+      Discover products and create a media buy to use for state transition testing.
+      The media buy ID is captured and passed to subsequent phases via context.
+
+    steps:
+      - id: discover_products
+        title: "Discover products for media buy"
+        narrative: |
+          Send a brief to get available products with pricing options. The first product
+          with a pricing option will be used to create the test media buy.
+        task: get_products
+        requires_tool: get_products
+        stateful: false
+        expected: |
+          Return products with:
+          - product_id
+          - pricing_options with pricing_option_id
+        sample_request:
+          buying_mode: "brief"
+          brief: "Display advertising products for state machine testing"
+          brand:
+            domain: "acmeoutdoor.com"
+        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"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "At least one product with a product_id"
+
+      - id: create_buy
+        title: "Create the test media buy"
+        narrative: |
+          Create a media buy using the discovered product. The media_buy_id is captured
+          for use in all subsequent state transition steps.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        stateful: true
+        expected: |
+          Return a media buy with:
+          - media_buy_id: platform-assigned identifier
+          - status: confirmed, active, or pending_approval
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          brand:
+            domain: "acmeoutdoor.com"
+          start_time: "2026-05-01T00:00:00Z"
+          end_time: "2026-05-31T23:59:59Z"
+          packages:
+            - product_id: "$context.product_id"
+              budget: 5000
+              pricing_option_id: "$context.pricing_option_id"
+        context_outputs:
+          - path: "media_buy_id"
+            key: "media_buy_id"
+          - path: "media_buy.media_buy_id"
+            key: "media_buy_id"
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+          - check: field_present
+            path: "media_buy_id"
+            description: "Response contains a media_buy_id"
+
+  - id: state_transitions
+    title: "State transitions: pause, resume, cancel"
+    narrative: |
+      Exercise the core state transitions on the media buy. Pause puts the buy on hold
+      (status becomes paused), resume reactivates it (status becomes active), and cancel
+      terminates it permanently (status becomes canceled).
+
+      Each transition is validated by checking the returned status field.
+
+    steps:
+      - id: pause_buy
+        title: "Pause the media buy"
+        narrative: |
+          Pause the active media buy. The status should transition to paused.
+          This is a reversible operation — the buy can be resumed later.
+        task: update_media_buy
+        requires_tool: update_media_buy
+        stateful: true
+        expected: |
+          Return the media buy with status: paused.
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          paused: true
+        validations:
+          - check: field_value
+            path: "status"
+            value: "paused"
+            description: "Media buy status is paused"
+
+      - id: resume_buy
+        title: "Resume the media buy"
+        narrative: |
+          Resume the paused media buy. The status should transition back to active
+          (or pending_activation on some platforms).
+        task: update_media_buy
+        requires_tool: update_media_buy
+        stateful: true
+        expected: |
+          Return the media buy with status: active or pending_activation.
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          paused: false
+        validations:
+          - check: field_present
+            path: "status"
+            description: "Response contains a status field after resume"
+
+      - id: cancel_buy
+        title: "Cancel the media buy"
+        narrative: |
+          Cancel the media buy permanently. The status should transition to canceled.
+          This is a terminal state — no further transitions are allowed.
+        task: update_media_buy
+        requires_tool: update_media_buy
+        stateful: true
+        expected: |
+          Return the media buy with status: canceled.
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          canceled: true
+          cancellation_reason: "AdCP compliance test — state machine scenario"
+        validations:
+          - check: field_value
+            path: "status"
+            value: "canceled"
+            description: "Media buy status is canceled"
+
+  - id: terminal_enforcement
+    title: "Terminal state enforcement"
+    narrative: |
+      Once a media buy is canceled or completed, the agent must reject any further
+      state changes. Attempting to pause, resume, or re-cancel a terminated buy should
+      return an error — typically INVALID_STATE_TRANSITION or INVALID_STATE.
+
+      This validates that the state machine is properly enforced and buyers can trust
+      that terminal states are final.
+
+    steps:
+      - id: pause_canceled_buy
+        title: "Pause a canceled media buy (expect rejection)"
+        narrative: |
+          Attempt to pause the canceled media buy. The agent should reject this with
+          an error indicating the state transition is invalid.
+        task: update_media_buy
+        requires_tool: update_media_buy
+        expect_error: true
+        stateful: true
+        expected: |
+          Reject with an error containing:
+          - code: INVALID_STATE_TRANSITION, INVALID_STATE, or similar
+          - The buy must remain in canceled status
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          paused: true
+        validations:
+          - check: error_code
+            value: "INVALID_STATE_TRANSITION"
+            description: "Error code indicates invalid state transition"
+
+      - id: resume_canceled_buy
+        title: "Resume a canceled media buy (expect rejection)"
+        narrative: |
+          Attempt to resume the canceled media buy. The agent should reject this —
+          canceled is a terminal state and cannot be reversed.
+        task: update_media_buy
+        requires_tool: update_media_buy
+        expect_error: true
+        stateful: true
+        expected: |
+          Reject with an error. Canceled media buys cannot be resumed.
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          paused: false
+        validations:
+          - check: error_code
+            value: "INVALID_STATE_TRANSITION"
+            description: "Error code indicates invalid state transition"
+
+      - id: recancel_buy
+        title: "Re-cancel an already canceled media buy"
+        narrative: |
+          Attempt to cancel a buy that is already canceled. The agent may either
+          reject with INVALID_STATE_TRANSITION or accept idempotently. Both are
+          acceptable — what matters is no crash or unstructured error.
+        task: update_media_buy
+        requires_tool: update_media_buy
+        stateful: true
+        expected: |
+          Either:
+          - Reject with INVALID_STATE_TRANSITION (strict)
+          - Accept idempotently and return status: canceled (permissive)
+          Both are acceptable behaviors.
+        sample_request:
+          media_buy_id: "$context.media_buy_id"
+          canceled: true
+        validations:
+          - check: field_present
+            path: "status"
+            description: "Response contains a status field (canceled) or a structured error"

package/storyboards/schema.yaml

@@ -0,0 +1,65 @@
+# Storyboard Definition Schema
+#
+# Storyboards are narrative test workflows that walk agent builders through
+# the sequence of calls their agent will receive, with context at each step.
+#
+# Each storyboard targets a specific agent interaction model and
+# describes the flow from a caller's perspective.
+
+# --- Schema definition ---
+
+# A storyboard file must conform to this structure:
+#
+# id: string (unique identifier, e.g., "creative_template")
+# version: string (semver, e.g., "1.0.0")
+# title: string (human-readable title)
+# category: enum (creative_template | creative_ad_server | creative_sales_agent | creative_generative | media_buy_seller | media_buy_guaranteed_approval | media_buy_non_guaranteed | media_buy_proposal_mode | media_buy_governance_escalation | media_buy_catalog_creative | signal_marketplace | signal_owned)
+# summary: string (one-line description for listings)
+# narrative: string (paragraph explaining the overall flow)
+#
+# agent:
+#   interaction_model: enum (stateless_transform | stateful_preloaded | stateful_push | stateless_generate | media_buy_seller | marketplace_catalog | owned_signals)
+#   capabilities: string[] (AdCP capability flags: supports_transformation, has_creative_library, supports_generation, sells_media, accepts_briefs, supports_guaranteed, supports_non_guaranteed, catalog_signals)
+#   examples: string[] (real-world examples: "Celtra", "Innovid")
+#
+# caller:
+#   role: string (who initiates the calls: "buyer_agent", "orchestrator", "dsp")
+#   example: string (e.g., "Scope3", "Pinnacle Agency")
+#
+# prerequisites:
+#   description: string (what must be true before running this storyboard)
+#   test_kit: string (reference to a test kit file, e.g., "test-kits/acme-outdoor.yaml")
+#
+# phases: array of Phase objects
+#
+# --- Phase ---
+#
+# id: string (unique within storyboard)
+# title: string (human-readable phase title)
+# narrative: string (paragraph explaining this phase from the caller's perspective)
+#
+# steps: array of Step objects
+#
+# --- Step ---
+#
+# id: string (unique within phase)
+# title: string (human-readable step title)
+# narrative: string (what's happening and why)
+# task: string (AdCP task name: list_creative_formats, preview_creative, build_creative, get_products, create_media_buy, sync_accounts, etc.)
+# schema_ref: string (path to request schema, e.g., "creative/list-creative-formats-request.json" or "media-buy/get-products-request.json")
+# response_schema_ref: string (path to response schema)
+# doc_ref: string (path to documentation page)
+# comply_scenario: string (maps to @adcp/client testing scenario, e.g., "creative_sync")
+# expected: string (human-readable description of expected behavior)
+# stateful: boolean (does this step depend on state from a previous step?)
+#
+# sample_request: object (optional — example request payload for this step)
+# sample_response: object (optional — example expected response)
+#
+# validations: array of Validation objects (optional)
+#
+# --- Validation ---
+#
+# check: string (what to validate: "response_schema", "field_present", "field_value", "status_code")
+# path: string (JSON path to the field, e.g., "formats[0].format_id")
+# description: string (human-readable description of validation)

package/storyboards/schema_validation.yaml

@@ -0,0 +1,166 @@
+id: schema_validation
+version: "1.0.0"
+title: "Schema compliance and temporal validation"
+category: media_buy_seller
+track: core
+summary: "Validates that agent responses conform to AdCP schemas and that temporal constraints are enforced."
+
+required_tools:
+  - get_products
+
+narrative: |
+  Every AdCP agent must return responses that match the published JSON schemas. Fields defined
+  in the spec — product_id, delivery_type, pricing_options — must be present and correctly typed.
+  Agents must also enforce temporal constraints: flight dates must be logically consistent
+  (end after start) and start dates should not be in the past.
+
+  This storyboard checks schema compliance on get_products responses and validates that
+  create_media_buy rejects temporally invalid requests. These are foundational requirements
+  that every agent must satisfy regardless of platform type.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+  examples:
+    - "Any AdCP seller agent"
+
+caller:
+  role: buyer_agent
+  example: "Compliance test harness"
+
+phases:
+  - id: schema_compliance
+    title: "Response schema compliance"
+    narrative: |
+      The buyer sends a standard get_products request and validates that the response
+      matches the published schema. Each product must have the required fields defined
+      in the AdCP spec: product_id, delivery_type, and pricing information.
+
+    steps:
+      - id: get_products_schema
+        title: "Validate get_products response schema"
+        narrative: |
+          Send a brief and validate the response structure. Every product in the response
+          must conform to the get-products-response.json schema, with required v3 fields
+          present.
+        task: get_products
+        requires_tool: get_products
+        stateful: false
+        expected: |
+          Return products matching the brief. Each product must have:
+          - product_id: unique identifier
+          - name: human-readable name
+          - delivery_type: guaranteed or non_guaranteed
+          - pricing_options: at least one pricing option
+        sample_request:
+          buying_mode: "brief"
+          brief: "Show all available advertising products"
+          brand:
+            domain: "acmeoutdoor.com"
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+          - check: field_present
+            path: "products[0].product_id"
+            description: "Each product has a product_id"
+          - check: field_present
+            path: "products[0].delivery_type"
+            description: "Each product declares guaranteed or non_guaranteed delivery"
+          - check: field_present
+            path: "products[0].name"
+            description: "Each product has a name"
+
+      - id: pricing_options_present
+        title: "Validate pricing options structure"
+        narrative: |
+          Check that products include pricing_options with the required fields:
+          pricing_option_id and pricing_model. These are essential for buyers to
+          construct valid create_media_buy requests.
+        task: get_products
+        requires_tool: get_products
+        stateful: false
+        expected: |
+          Products include pricing_options with:
+          - pricing_option_id: unique identifier for the pricing option
+          - pricing_model: CPM, CPC, flat_fee, etc.
+        sample_request:
+          buying_mode: "brief"
+          brief: "Products with detailed pricing information"
+          brand:
+            domain: "acmeoutdoor.com"
+        validations:
+          - check: field_present
+            path: "products[0].pricing_options"
+            description: "Products include pricing_options array"
+          - check: field_present
+            path: "products[0].pricing_options[0].pricing_option_id"
+            description: "Pricing options have a pricing_option_id"
+          - check: field_present
+            path: "products[0].pricing_options[0].pricing_model"
+            description: "Pricing options declare a pricing_model"
+
+  - id: temporal_validation
+    title: "Temporal constraint enforcement"
+    narrative: |
+      Flight dates are a fundamental constraint in media buying. The start date must come
+      before the end date, and agents should validate this before accepting a media buy.
+      Some agents also reject start dates in the past, though this is platform-dependent.
+
+    steps:
+      - id: reversed_dates
+        title: "Reject reversed date range"
+        narrative: |
+          Send a create_media_buy with end_time before start_time. The agent must reject
+          this — a campaign cannot end before it starts.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        expect_error: true
+        stateful: false
+        expected: |
+          Reject with an error containing:
+          - code: INVALID_REQUEST
+          - recovery: correctable
+          The agent must not accept a media buy where end_time precedes start_time.
+        sample_request:
+          idempotency_key: "temporal-test-reversed"
+          start_time: "2026-05-31T23:59:59Z"
+          end_time: "2026-05-01T00:00:00Z"
+          packages:
+            - product_id: "test-product"
+              budget: 1000
+              pricing_option_id: "test-pricing"
+        validations:
+          - check: error_code
+            value: "INVALID_REQUEST"
+            description: "Error code is INVALID_REQUEST for reversed date range"
+
+      - id: past_start_date
+        title: "Handle start date in the past"
+        narrative: |
+          Send a create_media_buy with a start_time in the past. Some agents reject this
+          outright, others accept it and auto-adjust the start date. Both behaviors are
+          acceptable — what matters is that the response is structured and intentional.
+        task: create_media_buy
+        requires_tool: create_media_buy
+        stateful: false
+        expected: |
+          Either:
+          - Reject with INVALID_REQUEST (strict validation)
+          - Accept and auto-adjust the start date (permissive)
+          Both are acceptable. The agent should not silently accept a past date without
+          adjusting it or warning the buyer.
+        sample_request:
+          idempotency_key: "temporal-test-past-start"
+          start_time: "2025-01-01T00:00:00Z"
+          end_time: "2026-12-31T23:59:59Z"
+          packages:
+            - product_id: "test-product"
+              budget: 1000
+              pricing_option_id: "test-pricing"
+        validations:
+          - check: response_schema
+            description: "Response is a valid create-media-buy-response or structured error"