@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/domains/creative/scenarios/canonical_supported_formats.yaml

@@ -0,0 +1,212 @@
+id: creative/canonical_supported_formats
+version: "1.0.0"
+title: "Creative canonical supported formats"
+category: creative
+summary: "Verifies the 3.1 creative-agent canonical path: targetable supported_formats capability IDs, build_creative routing, and unsupported target rejection."
+track: creative
+introduced_in: "3.1"
+required_tools:
+  - get_adcp_capabilities
+  - build_creative
+
+narrative: |
+  Creative agents in 3.1 declare what they can produce via
+  `creative.supported_formats` on `get_adcp_capabilities`. Targetable
+  supported-format entries carry an agent-local stable `capability_id` that
+  selects the build path on that creative agent. This is separate from media-buy
+  `format_option_id`, which selects a product or publisher-catalog format
+  option.
+
+  The buyer reads the canonical capability catalog, invokes one advertised
+  capability through `build_creative`, and verifies that an unsupported target
+  fails with `FORMAT_NOT_SUPPORTED` instead of silently producing an arbitrary
+  manifest.
+
+agent:
+  interaction_model: creative_agent
+  capabilities:
+    - supports_generation
+    - supports_transformation
+  examples:
+    - "Creative generation platforms"
+    - "Creative transformation services"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and a creative brief. The test kit
+    provides fictional brand context for Acme Outdoor.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Discover canonical build capabilities"
+    narrative: |
+      The buyer calls `get_adcp_capabilities` and reads
+      `creative.supported_formats` as the creative agent's 3.1 canonical build
+      catalog. The first advertised image capability is used in the next phase.
+
+    steps:
+      - id: get_capabilities
+        title: "Read supported canonical formats"
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return a creative capability block with implemented `supported_formats[]`.
+          The targetable entry used for build routing has:
+          - `capability_id` at the supported-format entry level
+          - `format.format_kind` and `format.params.slots[]`
+          - no product-level `format_option_id` on the creative-agent
+            capability entry used for build routing
+        sample_request:
+          context:
+            correlation_id: "creative_canonical_supported_formats--get_capabilities"
+        context_outputs:
+          - key: "image_build_capability_id"
+            path: "creative.supported_formats[0].capability_id"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "creative.supported_formats"
+            description: "Creative canonical supported formats are advertised"
+          - check: field_value
+            path: "creative.supported_formats[0].capability_id"
+            value: "training_image_generation"
+            description: "The image build path has a stable local capability_id"
+          - check: field_value
+            path: "creative.supported_formats[0].format.format_kind"
+            value: "image"
+            description: "The first supported capability declares the image canonical"
+          - check: field_present
+            path: "creative.supported_formats[0].format.params.slots[0].asset_group_id"
+            description: "Canonical format declaration includes slot metadata"
+          - check: field_absent
+            path: "creative.supported_formats[0].format.format_option_id"
+            description: "Creative-agent build routing uses capability_id, not product format_option_id"
+          - check: field_absent
+            path: "creative.supported_formats[1].capability_id"
+            description: "Storyboard fixture only advertises implemented canonical build paths"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_canonical_supported_formats--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+
+  - id: build_from_capability
+    title: "Build using the advertised capability"
+    narrative: |
+      The buyer invokes `build_creative` using the advertised image build
+      capability. The produced manifest uses the 3.1 canonical manifest path
+      (`format_kind`) and does not fall back to a legacy named format.
+
+    steps:
+      - id: build_image_capability
+        title: "Build with the advertised image capability"
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a completed build with a canonical image manifest:
+          - `creative_manifest.format_kind: image`
+          - generated assets keyed by canonical slot names
+        sample_request:
+          message: "Create a clean image creative for Acme Outdoor's summer trail sale. Use a direct headline and a clear landing page."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "$context.image_build_capability_id"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          quality: "draft"
+          idempotency_key: "$generate:uuid_v4#creative_canonical_supported_formats_build_image"
+          context:
+            correlation_id: "creative_canonical_supported_formats--build_image"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_value
+            path: "creative_manifest.format_kind"
+            value: "image"
+            description: "Generated manifest uses the 3.1 canonical manifest path"
+          - check: field_absent
+            path: "creative_manifest.format_id"
+            description: "Canonical build does not invent a legacy named-format id"
+          - check: field_present
+            path: "creative_manifest.assets.image_main"
+            description: "Output manifest includes an image asset under the canonical slot"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_canonical_supported_formats--build_image"
+            description: "Context correlation_id returned unchanged"
+
+  - id: reject_unsupported_capability
+    title: "Reject unsupported target capability"
+    narrative: |
+      A buyer may cache or mistype a build target. The creative agent must fail
+      closed with `FORMAT_NOT_SUPPORTED` instead of producing a manifest under a
+      target it does not recognize. Legacy named-format IDs may still be
+      accepted during the 3.x migration window; this phase probes an unknown
+      selector that is neither a legacy format nor an advertised capability.
+
+    steps:
+      - id: reject_unknown_capability
+        title: "Reject an unknown build target"
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expect_error: true
+        negative_path: payload_well_formed
+        expected: |
+          Return a build_creative error response with:
+          - errors[0].code: FORMAT_NOT_SUPPORTED
+          - errors[0].field: target_format_id
+          - errors[0].recovery: correctable
+        sample_request:
+          message: "Create an unsupported canonical creative."
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "unknown_takeover_generation"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          quality: "draft"
+          idempotency_key: "$generate:uuid_v4#creative_canonical_supported_formats_reject_unknown"
+          context:
+            correlation_id: "creative_canonical_supported_formats--reject_unknown"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: error_code
+            value: "FORMAT_NOT_SUPPORTED"
+            description: "Unsupported build target is rejected with the canonical error code"
+          - check: field_value
+            path: "errors[0].field"
+            value: "target_format_id"
+            description: "Error points at the unsupported target selector"
+          - check: field_value
+            path: "errors[0].recovery"
+            value: "correctable"
+            description: "Buyer can correct the target by choosing an advertised capability_id"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_canonical_supported_formats--reject_unknown"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/domains/creative/scenarios/creative_lifecycle_webhooks.yaml

@@ -0,0 +1,389 @@
+id: creative/creative_lifecycle_webhooks
+version: "1.0.0"
+introduced_in: "3.1"
+title: "Creative lifecycle webhooks"
+category: creative
+summary: "Registers account-level creative lifecycle notifications, forces a seller-side status transition, observes creative.status_changed, and verifies list_creatives snapshot repair plus optional creative.purged coverage."
+track: creative
+required_tools:
+  - sync_accounts
+  - sync_creatives
+  - list_creatives
+  - comply_test_controller
+
+narrative: |
+  A buyer registers an account-level webhook subscriber through
+  sync_accounts.accounts[].notification_configs[] for creative lifecycle
+  events. The runner then pushes a creative, forces a seller-side lifecycle
+  transition with comply_test_controller, observes the account-anchored
+  creative.status_changed event, and re-reads list_creatives as the repair
+  path after a missed or distrusted webhook.
+
+  This storyboard is deliberately separate from media-buy impairment coverage:
+  creative.status_changed and creative.purged are account-anchored lifecycle
+  events, while impairment webhooks are media-buy anchored state-event logs.
+
+agent:
+  interaction_model: stateful_push
+  capabilities:
+    - has_creative_library
+    - emits_account_lifecycle_webhooks
+  examples:
+    - "Creative management platforms"
+    - "Ad servers with account-scoped creative libraries"
+    - "Media sellers that host buyer-supplied creative assets"
+
+caller:
+  role: compliance_runner
+  example: "AdCP Verified runner with webhook receiver capability"
+
+prerequisites:
+  description: |
+    The runner MUST host the webhook receiver contract so the account-level
+    notification_configs[] URL can point at a per-step receiver. This
+    storyboard is intended for sellers that expose account-level creative
+    lifecycle notifications; sellers that do not support notification_configs[]
+    should omit this scenario from their claimed coverage.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: register_account_lifecycle_subscriber
+    title: "Register account-level creative lifecycle notifications"
+    narrative: |
+      The buyer provisions a sandbox account and declares a webhook subscriber
+      interested in account-anchored creative.status_changed and
+      creative.purged events. The subscriber URL is owned by the runner.
+
+    steps:
+      - id: sync_accounts_with_lifecycle_notifications
+        title: "Register notification_configs[] for creative lifecycle events"
+        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: |
+          Seller accepts the sandbox account relationship and persists the
+          account-level subscriber:
+          - action: created or updated
+          - status: active
+          - notification_configs[0].subscriber_id: buyer-primary
+          - notification_configs[0].event_types includes creative.status_changed
+            and creative.purged
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.example"
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+              sandbox: true
+              notification_configs:
+                - subscriber_id: "buyer-primary"
+                  url: "{{runner.webhook_url:creative_lifecycle_events}}"
+                  event_types:
+                    - "creative.status_changed"
+                    - "creative.purged"
+                  active: true
+          idempotency_key: "$generate:uuid_v4#creative_lifecycle_webhooks_sync_accounts"
+          context:
+            correlation_id: "creative_lifecycle_webhooks--sync_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json"
+          - check: field_value
+            path: "accounts[0].action"
+            allowed_values: ["created", "updated", "unchanged"]
+            description: "Account sync succeeded"
+          - check: field_value
+            path: "accounts[0].status"
+            allowed_values: ["active"]
+            description: "Sandbox account is active"
+          - check: field_value
+            path: "accounts[0].notification_configs[0].subscriber_id"
+            value: "buyer-primary"
+            description: "Seller echoes the account-level subscriber id"
+          - check: field_present
+            path: "accounts[0].notification_configs[0].event_types"
+            description: "Seller echoes the account-level creative lifecycle event filter array"
+
+  - id: seed_creative
+    title: "Create a sandbox creative"
+    narrative: |
+      The buyer syncs a creative into the account-scoped library. The creative
+      starts from a known approved baseline before the runner forces a
+      seller-side status transition.
+
+    steps:
+      - id: sync_creative
+        title: "Sync a display creative into the account library"
+        task: sync_creatives
+        schema_ref: "creative/sync-creatives-request.json"
+        response_schema_ref: "creative/sync-creatives-response.json"
+        doc_ref: "/creative/task-reference/sync_creatives"
+        stateful: true
+        expected: |
+          Creative is created or updated and can be addressed by creative_id
+          in later list_creatives and comply_test_controller calls.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          creatives:
+            - creative_id: "acme_lifecycle_banner_001"
+              name: "Trail Pro lifecycle webhook banner"
+              format_id:
+                agent_url: "https://your-platform.example.com"
+                id: "display_300x250"
+              assets:
+                image:
+                  asset_type: "image"
+                  url: "https://test-assets.adcontextprotocol.org/acme-outdoor/trail-pro-300x250.png"
+                  width: 300
+                  height: 250
+                  mime_type: "image/png"
+          idempotency_key: "$generate:uuid_v4#creative_lifecycle_webhooks_sync_creative"
+          context:
+            correlation_id: "creative_lifecycle_webhooks--sync_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json"
+          - check: field_value
+            path: "creatives[0].creative_id"
+            value: "acme_lifecycle_banner_001"
+            description: "Creative id is echoed"
+          - check: field_value
+            path: "creatives[0].action"
+            allowed_values: ["created", "updated"]
+            description: "Creative was stored"
+
+      - id: force_creative_approved
+        title: "Force approved baseline"
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        stateful: true
+        expected: |
+          success: true. The creative is approved before the status-changed
+          event phase begins.
+        sample_request:
+          account:
+            sandbox: true
+          brand:
+            domain: "acmeoutdoor.example"
+          scenario: "force_creative_status"
+          params:
+            creative_id: "acme_lifecycle_banner_001"
+            status: "approved"
+          context:
+            correlation_id: "creative_lifecycle_webhooks--force_approved"
+        validations:
+          - check: response_schema
+            description: "Response matches comply-test-controller-response.json"
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Controller accepted the approved baseline"
+
+  - id: status_changed_event
+    title: "Observe creative.status_changed"
+    narrative: |
+      The controller forces an approved → rejected seller-side transition. The
+      seller emits creative.status_changed to the registered account-level
+      subscriber, and the buyer re-reads the creative snapshot to repair state
+      after any missed webhook.
+
+    steps:
+      - id: force_creative_rejected
+        title: "Force approved → rejected"
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        stateful: true
+        expected: |
+          success: true. Seller observed a seller-initiated creative lifecycle
+          transition and must notify account-level lifecycle subscribers.
+        sample_request:
+          account:
+            sandbox: true
+          brand:
+            domain: "acmeoutdoor.example"
+          scenario: "force_creative_status"
+          params:
+            creative_id: "acme_lifecycle_banner_001"
+            status: "rejected"
+            rejection_reason: "Lifecycle webhook storyboard: forced revocation for account-level notification coverage."
+          context:
+            correlation_id: "creative_lifecycle_webhooks--force_rejected"
+        validations:
+          - check: response_schema
+            description: "Response matches comply-test-controller-response.json"
+          - check: field_value
+            path: "success"
+            allowed_values: [true]
+            description: "Controller accepted the rejected transition"
+
+      - id: expect_status_changed_webhook
+        title: "Assert creative.status_changed webhook payload"
+        task: expect_webhook
+        triggered_by: force_creative_rejected
+        filter:
+          notification_type: "creative.status_changed"
+          creative_id: "acme_lifecycle_banner_001"
+          subscriber_id: "buyer-primary"
+        timeout_seconds: 30
+        expect_idempotency_key: true
+        webhook_payload_schema_ref: "creative/creative-status-changed-webhook.json"
+        requires_contract: webhook_receiver_runner
+        stateful: true
+        expected: |
+          A webhook arrives at the account-level subscriber URL. Payload
+          validates against creative-status-changed-webhook.json and carries:
+          notification_type: creative.status_changed, subscriber_id:
+          buyer-primary, creative_id: acme_lifecycle_banner_001,
+          transition.from: approved, transition.to: rejected, notification_id,
+          and idempotency_key.
+
+      - id: list_creatives_after_status_change
+        title: "Repair from list_creatives after the status webhook"
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        stateful: true
+        expected: |
+          Snapshot repair shows the creative's current rejected status and the
+          recent creative.status_changed activity record, keyed by the same
+          creative_id as the webhook payload.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          creative_ids:
+            - "acme_lifecycle_banner_001"
+          include_webhook_activity: true
+          context:
+            correlation_id: "creative_lifecycle_webhooks--list_after_status_change"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json"
+          - check: field_value
+            path: "creatives[0].creative_id"
+            value: "acme_lifecycle_banner_001"
+            description: "Snapshot returns the transitioned creative"
+          - check: field_value
+            path: "creatives[0].status"
+            value: "rejected"
+            description: "Snapshot repair reflects the current rejected status"
+          - check: field_value
+            path: "creatives[0].webhook_activity[0].notification_type"
+            value: "creative.status_changed"
+            description: "Snapshot exposes recent status-changed webhook activity"
+          - check: field_present
+            path: "creatives[0].webhook_activity[0].idempotency_key"
+            description: "Activity record carries the delivery idempotency key"
+
+  - id: purged_event_optional
+    title: "Optional creative.purged coverage"
+    optional: true
+    narrative: |
+      Sellers that advertise force_creative_purge can deterministically destroy
+      the sandbox creative and emit creative.purged. This phase is optional;
+      the required status_changed and snapshot-repair coverage above still
+      stands when a seller does not implement the purge primitive.
+
+    steps:
+      - id: force_creative_purged
+        title: "Force a soft purge"
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        stateful: true
+        expected: |
+          success: true when the seller supports force_creative_purge. The
+          creative is soft-purged so list_creatives can expose a tombstone.
+        sample_request:
+          account:
+            sandbox: true
+          brand:
+            domain: "acmeoutdoor.example"
+          scenario: "force_creative_purge"
+          params:
+            creative_id: "acme_lifecycle_banner_001"
+            purge_kind: "soft"
+            reason_code: "retention_expired"
+            reason_detail: "Lifecycle webhook storyboard: soft purge for account-level notification coverage."
+          context:
+            correlation_id: "creative_lifecycle_webhooks--force_purged"
+        validations:
+          - check: response_schema
+            description: "Response matches comply-test-controller-response.json"
+
+      - id: expect_purged_webhook
+        title: "Assert creative.purged webhook payload"
+        task: expect_webhook
+        triggered_by: force_creative_purged
+        filter:
+          notification_type: "creative.purged"
+          creative_id: "acme_lifecycle_banner_001"
+          subscriber_id: "buyer-primary"
+        timeout_seconds: 30
+        expect_idempotency_key: true
+        webhook_payload_schema_ref: "creative/creative-purged-webhook.json"
+        requires_contract: webhook_receiver_runner
+        stateful: true
+        expected: |
+          A creative.purged webhook arrives for the same account-level
+          subscriber. Payload validates against creative-purged-webhook.json
+          and carries creative_id, notification_id, idempotency_key,
+          purge_kind: soft, and reason_code.
+
+      - id: list_creatives_after_purge
+        title: "Repair from list_creatives tombstone"
+        task: list_creatives
+        schema_ref: "creative/list-creatives-request.json"
+        response_schema_ref: "creative/list-creatives-response.json"
+        doc_ref: "/creative/task-reference/list_creatives"
+        stateful: true
+        expected: |
+          With include_purged and include_webhook_activity, snapshot repair
+          surfaces the soft-purged tombstone and the recent creative.purged
+          activity record.
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          creative_ids:
+            - "acme_lifecycle_banner_001"
+          include_purged: true
+          include_webhook_activity: true
+          context:
+            correlation_id: "creative_lifecycle_webhooks--list_after_purge"
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json"
+          - check: field_value
+            path: "creatives[0].creative_id"
+            value: "acme_lifecycle_banner_001"
+            description: "Tombstone retains the creative id"
+          - check: field_value
+            path: "creatives[0].purge.kind"
+            value: "soft"
+            description: "Soft-purged creative remains visible as a tombstone"
+          - check: field_value
+            path: "creatives[0].webhook_activity[0].notification_type"
+            value: "creative.purged"
+            description: "Snapshot exposes recent purged webhook activity"