@adcp/sdk 5.23.0 → 5.24.0

package/compliance/cache/3.0.1.previous/specialisms/sales-social/index.yaml

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