@adcp/sdk 6.8.0 → 6.10.0

package/compliance/cache/3.0.6/specialisms/sales-social/index.yaml

@@ -0,0 +1,584 @@
+id: sales_social
+version: "1.0.0"
+title: "Social platform"
+protocol: media-buy
+category: sales_social
+summary: "Social media platform that accepts audience segments, native creatives, and conversion events from buyer agents."
+track: audiences
+required_tools:
+  - sync_audiences
+  - sync_catalogs
+  - sync_creatives
+  - sync_event_sources
+
+# Cross-step assertion (adcp#2664). status.monotonic rejects resource
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph — e.g. approved → processing on a creative asset or
+# active → pending_creatives on a media_buy.
+invariants:
+  - status.monotonic
+
+narrative: |
+  You run a social media platform — Snap, Meta, TikTok, Pinterest, or any walled garden that
+  sells advertising through audience-based targeting and native creative formats. A buyer agent
+  connects to set up an account, push audience segments, sync native creatives, track conversion
+  events, and monitor spend.
+
+  Unlike open-web media buys, social platforms require the buyer to push assets into the
+  platform's environment. Audiences are activated via sync_audiences, creatives are pushed via
+  sync_creatives in platform-native formats, and conversion events flow back via log_event.
+
+  This storyboard covers the social platform integration from the buyer's perspective:
+  account setup, audience activation, native creative push, event tracking, and financial
+  monitoring.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+    - supports_non_guaranteed
+  examples:
+    - "Snap"
+    - "Meta"
+    - "TikTok"
+    - "Pinterest"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, audience segment definitions,
+    and native creative assets. The test kit provides a sample brand with creative assets
+    suitable for social formats.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports media buying before syncing audiences and native creatives.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        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 capabilities declaring media_buy in supported_protocols, confirming the agent sells media.
+        sample_request:
+          context:
+            correlation_id: "sales_social--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      The buyer establishes an account with the social platform and verifies its status.
+      Social platforms often require advertiser verification before accepting ad spend.
+
+    steps:
+      - id: sync_accounts
+        title: "Register advertiser account"
+        narrative: |
+          The buyer registers their brand and operator with the social platform. The platform
+          provisions an advertiser account and returns its status. Social platforms may require
+          identity verification before the account goes active.
+        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: |
+          Return the advertiser account with:
+          - account_id: platform's identifier
+          - status: active or pending_approval (if verification required)
+          - account_scope: how the platform scopes this relationship
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "acmeoutdoor.example"
+              operator: "pinnacle-agency.example"
+              billing: "operator"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_account_setup_sync_accounts"
+          context:
+            correlation_id: "sales_social--sync_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "Account has a platform-assigned ID"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_accounts"
+            description: "Context correlation_id returned unchanged"
+      - id: list_accounts
+        title: "Verify account status"
+        narrative: |
+          The buyer checks which accounts exist on the platform and their current status.
+          This confirms the account is active and shows any pending setup requirements.
+        task: list_accounts
+        schema_ref: "account/list-accounts-request.json"
+        response_schema_ref: "account/list-accounts-response.json"
+        doc_ref: "/accounts/tasks/list_accounts"
+        stateful: true
+        # Explicit-mode social platforms (Snap, Meta, TikTok) pre-provision
+        # advertiser accounts out-of-band — `sync_accounts` is intentionally
+        # missing_tool, with `list_accounts` as the canonical alternative.
+        # Declaring the substitution here lets the runner waive the
+        # downstream missing_tool cascade when list_accounts passes.
+        # See adcontextprotocol/adcp#3734.
+        provides_state_for: sync_accounts
+        expected: |
+          Return accounts matching the query:
+          - accounts array with status, account_id, brand, operator
+          - Active accounts ready for ad operations
+          - Pending accounts with accounts[].setup.url populated if verification is needed
+
+        sample_request:
+          context:
+            correlation_id: "sales_social--list_accounts"
+        validations:
+          - check: response_schema
+            description: "Response matches list-accounts-response.json schema"
+          - check: field_present
+            path: "accounts"
+            description: "Response contains accounts array"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--list_accounts"
+            description: "Context correlation_id returned unchanged"
+  - id: audience_sync
+    title: "Audience activation"
+    narrative: |
+      The buyer pushes audience segments to the platform. Social platforms use these segments
+      for targeting — the buyer defines who to reach, and the platform matches against its
+      user base.
+
+    steps:
+      - id: sync_audiences
+        title: "Push audience segments"
+        narrative: |
+          The buyer syncs audience segment definitions to the platform. Each segment includes
+          targeting criteria that the platform evaluates against its user graph. The platform
+          returns match rates and segment status.
+        task: sync_audiences
+        schema_ref: "media-buy/sync-audiences-request.json"
+        response_schema_ref: "media-buy/sync-audiences-response.json"
+        doc_ref: "/media-buy/task-reference/sync_audiences"
+        comply_scenario: sync_audiences
+        stateful: true
+        expected: |
+          Accept and process audience segments:
+          - Per-segment status: active, processing, or rejected
+          - Match rate estimates where available
+          - Platform-assigned segment IDs
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          audiences:
+            - audience_id: "outdoor_enthusiasts_25_54"
+              name: "Outdoor enthusiasts 25-54"
+              description: "Adults 25-54 interested in hiking, camping, and outdoor gear"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_audience_sync_sync_audiences"
+          context:
+            correlation_id: "sales_social--sync_audiences"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-audiences-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_audiences"
+            description: "Context correlation_id returned unchanged"
+  - id: creative_push
+    title: "Native creative sync"
+    narrative: |
+      The buyer pushes native creative assets to the platform. Social platforms render ads
+      in their native format — the buyer provides assets (images, headlines, descriptions)
+      and the platform assembles them into the native ad unit.
+
+    steps:
+      - id: sync_creatives
+        title: "Push native creative assets"
+        narrative: |
+          The buyer syncs creative assets for native ad formats. The platform validates
+          each creative against its format requirements and returns per-creative status.
+        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"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          Accept and validate native creatives:
+          - Per-creative action: created or updated
+          - Per-creative status: accepted, pending_review, or rejected
+          - Validation errors for rejected creatives
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "native_trail_pro"
+              name: "Trail Pro 3000 - Native"
+              format_id:
+                agent_url: "https://social-platform.example.com"
+                id: "native_feed"
+              assets:
+                image:
+                  asset_type: "image"
+                  url: "https://cdn.pinnacle-agency.example/trail-pro-native.png"
+                  width: 1200
+                  height: 628
+                  mime_type: "image/png"
+                headline:
+                  asset_type: "text"
+                  content: "Trail Pro 3000 — Built for the Summit"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_creative_push_sync_creatives"
+          context:
+            correlation_id: "sales_social--sync_creatives"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_creatives"
+            description: "Context correlation_id returned unchanged"
+  - id: catalog_driven_dynamic_ads
+    title: "Catalog-driven dynamic product ads"
+    narrative: |
+      Social platforms routinely ship dynamic product ads (Snap Dynamic Ads, Meta DPA,
+      TikTok Dynamic Showcase): the buyer pushes a product catalog and the platform
+      renders per-impression creative pulling product images, titles, and tracker URLs
+      from catalog items. The creative template references catalog-item macros
+      (`{SKU}`, `{GTIN}`) whose values resolve to the specific item shown at
+      impression time.
+
+      This phase exercises the catalog-acceptance leg of that flow: push a small inline
+      product catalog (with `content_id_type: "sku"` declared so macro resolution binds
+      to the right field), then push a DPA creative template using the AdCP-native
+      `product_carousel_3_to_10` format on `creative.adcontextprotocol.org`. Real
+      social-platform formats (Meta `native_carousel`, Snap dynamic ad set, TikTok
+      dynamic showcase) are platform-specific refinements tracked as follow-ups on
+      #2640; the AdCP-native format is the interop baseline.
+
+      Runtime substitution-safety checks (that the emitted tracker URLs percent-encode
+      the macro values per `docs/creative/universal-macros#substitution-safety-catalog-item-macros`)
+      require the substitution-observer contract tracked in #2638; phases gated on
+      that contract activate when runners advertise it.
+
+    steps:
+      - id: sync_product_catalog
+        title: "Push a product catalog"
+        narrative: |
+          The buyer pushes a small inline product catalog — the shape social platforms
+          accept for dynamic product ads. Your platform validates each item and
+          returns per-item approval status.
+        task: sync_catalogs
+        schema_ref: "media-buy/sync-catalogs-request.json"
+        response_schema_ref: "media-buy/sync-catalogs-response.json"
+        doc_ref: "/media-buy/task-reference/sync_catalogs"
+        stateful: true
+        expected: |
+          Return per-catalog results with catalog_id, action, item_count, and
+          items_approved counts.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          catalogs:
+            - catalog_id: "acme_gear_spring_2026"
+              type: "product"
+              content_id_type: "sku"
+              name: "Acme Outdoor — Spring 2026 Gear"
+              items:
+                - item_id: "trail_pro_3000"
+                  title: "Trail Pro 3000 Backpack"
+                  description: "65L expedition pack with torso-length adjustment."
+                  url: "https://acmeoutdoor.example/gear/trail-pro-3000"
+                  image_url: "https://cdn.acmeoutdoor.example/gear/trail-pro-3000.jpg"
+                  price:
+                    amount: 289.00
+                    currency: "USD"
+                - item_id: "summit_tent_2p"
+                  title: "Summit 2P Ultralight Tent"
+                  description: "2-person four-season tent, 1.8kg packed."
+                  url: "https://acmeoutdoor.example/gear/summit-tent-2p"
+                  image_url: "https://cdn.acmeoutdoor.example/gear/summit-tent-2p.jpg"
+                  price:
+                    amount: 549.00
+                    currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_driven_dynamic_ads_sync_product_catalog"
+          context:
+            correlation_id: "sales_social--sync_product_catalog"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-catalogs-response.json schema"
+          - check: field_present
+            path: "catalogs[0].catalog_id"
+            description: "Catalog has an ID"
+          - check: field_present
+            path: "catalogs[0].item_count"
+            description: "Catalog reports item count"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_product_catalog"
+            description: "Context correlation_id returned unchanged"
+
+      - id: sync_dpa_creative
+        title: "Push a dynamic product ad creative with catalog-item macros"
+        narrative: |
+          The buyer pushes a creative template whose tracker URLs reference
+          catalog-item macros (`{SKU}`, `{GTIN}`). At impression time, your platform
+          substitutes each catalog item's values into the template to render the
+          per-impression ad.
+
+          The template uses the AdCP-native `product_carousel_3_to_10` format
+          (see `docs/creative/channels/carousels.mdx`). Per #2620, values substituted
+          into URL contexts MUST be percent-encoded such that only RFC 3986 unreserved
+          characters remain unescaped; nested macro expansion is prohibited. This step
+          validates that the template is accepted into the library; runtime
+          substitution validation is tracked under #2638.
+        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"
+        comply_scenario: creative_sync
+        stateful: true
+        expected: |
+          Accept the DPA creative template. Per-creative action: created or updated.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          creatives:
+            - creative_id: "acme_dpa_spring_2026"
+              name: "Acme Outdoor — Spring DPA template"
+              format_id:
+                agent_url: "https://creative.adcontextprotocol.org"
+                id: "product_carousel_3_to_10"
+              assets:
+                impression_pixel:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/imp?sku={SKU}&gtin={GTIN}&mb={MEDIA_BUY_ID}"
+                click_url:
+                  asset_type: "url"
+                  url: "https://track.acmeoutdoor.example/click?sku={SKU}"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_catalog_driven_dynamic_ads_sync_dpa_creative"
+          context:
+            correlation_id: "sales_social--sync_dpa_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-creatives-response.json schema"
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_dpa_creative"
+            description: "Context correlation_id returned unchanged"
+  - id: event_setup
+    title: "Event source setup"
+    narrative: |
+      Before sending conversion events, the buyer registers the event sources the platform
+      should expect events from — a website pixel, a mobile SDK, or a server-to-server feed.
+      The platform returns setup instructions and binds the event_source_id that later
+      log_event calls will reference.
+
+    steps:
+      - id: sync_event_sources
+        title: "Register conversion event sources"
+        narrative: |
+          The buyer tells the platform where conversion events will come from. The
+          platform records each event_source_id, returns integration code, and will
+          accept log_event calls that reference it.
+        task: sync_event_sources
+        schema_ref: "media-buy/sync-event-sources-request.json"
+        response_schema_ref: "media-buy/sync-event-sources-response.json"
+        doc_ref: "/media-buy/task-reference/sync_event_sources"
+        stateful: true
+        expected: |
+          Return event sources with:
+          - event_source_id and seller_id
+          - setup.snippet: integration code (JavaScript pixel, HTML tag, or pixel URL)
+          - setup.instructions: human-readable integration guide
+          - action: created or updated
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          event_sources:
+            - event_source_id: "acmeoutdoor_website"
+              name: "Acme Outdoor Website"
+              event_types: ["purchase", "add_to_cart", "page_view", "lead"]
+              allowed_domains: ["acmeoutdoor.example"]
+
+          idempotency_key: "$generate:uuid_v4#sales_social_event_setup_sync_event_sources"
+          context:
+            correlation_id: "sales_social--sync_event_sources"
+        validations:
+          - check: response_schema
+            description: "Response matches sync-event-sources-response.json schema"
+          - check: field_present
+            path: "event_sources[0].setup.snippet"
+            description: "Event source includes setup snippet"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--sync_event_sources"
+            description: "Context correlation_id returned unchanged"
+  - id: event_logging
+    title: "Conversion event tracking"
+    narrative: |
+      The buyer sends conversion events back to the platform for measurement and optimization.
+      Events include purchases, signups, and other post-click actions that the platform uses
+      to optimize delivery and report on campaign performance.
+
+    steps:
+      - id: log_event
+        title: "Send conversion events"
+        narrative: |
+          The buyer logs conversion events that occurred after ad exposure. The platform
+          records these events for attribution, reporting, and delivery optimization.
+        task: log_event
+        schema_ref: "media-buy/log-event-request.json"
+        response_schema_ref: "media-buy/log-event-response.json"
+        doc_ref: "/media-buy/task-reference/log_event"
+        stateful: true
+        expected: |
+          Acknowledge the events:
+          - Per-event status: accepted or rejected
+          - Event IDs for deduplication
+          - Attribution window validation
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          event_source_id: "acmeoutdoor_website"
+          events:
+            - event_type: "purchase"
+              event_id: "evt_trail_pro_001"
+              event_time: "2026-04-05T14:30:00Z"
+              value: 149.99
+              currency: "USD"
+
+          idempotency_key: "$generate:uuid_v4#sales_social_event_logging_log_event"
+          context:
+            correlation_id: "sales_social--log_event"
+        validations:
+          - check: response_schema
+            description: "Response matches log-event-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--log_event"
+            description: "Context correlation_id returned unchanged"
+  - id: financials
+    title: "Account financials"
+    narrative: |
+      The buyer checks account financials — spending, balance, and payment status. This is
+      essential for budget monitoring across multiple social platforms.
+
+    steps:
+      - id: get_account_financials
+        title: "Check account spending and balance"
+        narrative: |
+          The buyer retrieves financial information for the advertiser account. The platform
+          returns current spend, remaining balance, and payment status.
+        task: get_account_financials
+        schema_ref: "account/get-account-financials-request.json"
+        response_schema_ref: "account/get-account-financials-response.json"
+        doc_ref: "/accounts/tasks/get_account_financials"
+        stateful: true
+        expected: |
+          Return account financial data:
+          - Current spend to date
+          - Remaining balance or credit
+          - Payment status and terms
+          - Budget utilization metrics
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "sales_social--get_account_financials"
+        validations:
+          - check: response_schema
+            description: "Response matches get-account-financials-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "sales_social--get_account_financials"
+            description: "Context correlation_id returned unchanged"