@adcp/client 4.22.1 → 4.24.0

package/storyboards/content_standards.yaml

@@ -0,0 +1,251 @@
+id: content_standards
+version: "1.0.0"
+title: "Content standards"
+category: content_standards
+summary: "Define creative quality rules, calibrate content against them, and validate that delivered ads met the standards."
+track: governance
+required_tools:
+  - list_content_standards
+
+narrative: |
+  You run a governance agent that manages content standards — rules that define what
+  creative content is acceptable for a brand or campaign. Buyers create standards that
+  specify quality requirements, safety constraints, and brand compliance rules. Your
+  agent stores these standards, calibrates sample content against them, and validates
+  that delivered creatives met the requirements.
+
+  Content standards complement property governance. Property lists control where ads appear;
+  content standards control what the ads look like. Together they form a complete brand
+  safety framework.
+
+  This storyboard covers the full content standards lifecycle: defining standards, querying
+  them, calibrating content before launch, and validating delivery after the fact.
+
+agent:
+  interaction_model: governance_agent
+  capabilities:
+    - content_standards
+    - creative_quality
+  examples:
+    - "Creative quality platforms"
+    - "Brand safety services"
+    - "Ad verification platforms"
+    - "GARM-aligned quality tools"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and creative quality requirements. The test kit
+    provides a sample brand with visual assets for calibration.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: create_standards
+    title: "Define content standards"
+    narrative: |
+      The buyer creates content standards that define what creative content is acceptable.
+      Standards include quality requirements, safety constraints, and brand-specific rules.
+
+    steps:
+      - id: create_content_standards
+        title: "Create content standards"
+        narrative: |
+          The buyer defines a set of content standards. These rules will be used to
+          evaluate creatives before and after delivery.
+        task: create_content_standards
+        schema_ref: "content-standards/create-content-standards-request.json"
+        response_schema_ref: "content-standards/create-content-standards-response.json"
+        doc_ref: "/governance/content-standards/tasks/create_content_standards"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return the created content standards:
+          - standards_id: platform-assigned identifier
+          - Rules registered with severity levels
+          - Status: active
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+          name: "Acme Outdoor creative standards"
+          rules:
+            - category: "brand_safety"
+              description: "No violent or controversial imagery"
+              severity: "must"
+            - category: "quality"
+              description: "Minimum 72 DPI for display assets"
+              severity: "should"
+            - category: "brand_compliance"
+              description: "Brand colors must match palette within 5% tolerance"
+              severity: "must"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-content-standards-response.json schema"
+
+  - id: list_and_get
+    title: "Query content standards"
+    narrative: |
+      The buyer lists all content standards for the account and retrieves a specific
+      standard to inspect its rules.
+
+    steps:
+      - id: list_content_standards
+        title: "List all content standards"
+        narrative: |
+          The buyer lists all content standards for the brand. The response includes
+          standard metadata without full rule details.
+        task: list_content_standards
+        schema_ref: "content-standards/list-content-standards-request.json"
+        response_schema_ref: "content-standards/list-content-standards-response.json"
+        doc_ref: "/governance/content-standards/tasks/list_content_standards"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return content standard summaries:
+          - Array of standards with standards_id, name, rule_count
+          - Status of each standard set
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-content-standards-response.json schema"
+
+      - id: get_content_standards
+        title: "Get a specific content standard"
+        narrative: |
+          The buyer retrieves the full details of a specific content standard, including
+          all rules and their severity levels.
+        task: get_content_standards
+        schema_ref: "content-standards/get-content-standards-request.json"
+        response_schema_ref: "content-standards/get-content-standards-response.json"
+        doc_ref: "/governance/content-standards/tasks/get_content_standards"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return the full content standard:
+          - standards_id, name
+          - All rules with categories, descriptions, and severity
+
+        sample_request:
+          standards_id: "cs_acme_creative_001"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-content-standards-response.json schema"
+
+  - id: update_standards
+    title: "Update content standards"
+    narrative: |
+      The buyer modifies existing content standards — adding rules, adjusting severity,
+      or removing obsolete constraints.
+
+    steps:
+      - id: update_content_standards
+        title: "Update content standards"
+        narrative: |
+          The buyer updates an existing content standard with new or modified rules.
+        task: update_content_standards
+        schema_ref: "content-standards/update-content-standards-request.json"
+        response_schema_ref: "content-standards/update-content-standards-response.json"
+        doc_ref: "/governance/content-standards/tasks/update_content_standards"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return the updated content standard:
+          - Updated rule set
+          - Confirmation of changes applied
+
+        sample_request:
+          standards_id: "cs_acme_creative_001"
+          add_rules:
+            - category: "accessibility"
+              description: "All images must have alt text"
+              severity: "should"
+
+        validations:
+          - check: response_schema
+            description: "Response matches update-content-standards-response.json schema"
+
+  - id: calibration
+    title: "Calibrate content"
+    narrative: |
+      Before launching a campaign, the buyer calibrates sample creatives against the
+      content standards. This is a pre-flight check — does the creative meet the rules
+      before it goes live?
+
+    steps:
+      - id: calibrate_content
+        title: "Calibrate content against standards"
+        narrative: |
+          The buyer submits sample creative content for evaluation against the content
+          standards. The governance agent checks each rule and returns a calibration
+          report indicating pass/fail per rule.
+        task: calibrate_content
+        schema_ref: "content-standards/calibrate-content-request.json"
+        response_schema_ref: "content-standards/calibrate-content-response.json"
+        doc_ref: "/governance/content-standards/tasks/calibrate_content"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return a calibration report:
+          - overall_pass: boolean
+          - Per-rule results with pass/fail and evidence
+          - Remediation guidance for failed rules
+
+        sample_request:
+          standards_id: "cs_acme_creative_001"
+          content:
+            creative_id: "display_trail_pro_300x250"
+            format: "display_300x250"
+            assets:
+              - asset_type: "image"
+                url: "https://cdn.pinnacle-agency.example/trail-pro-300x250.png"
+
+        validations:
+          - check: response_schema
+            description: "Response matches calibrate-content-response.json schema"
+
+  - id: delivery_validation
+    title: "Validate delivered content"
+    narrative: |
+      After the campaign runs, the buyer validates that the delivered creatives met the
+      content standards. The governance agent checks actual delivered content against
+      the rules and flags any violations.
+
+    steps:
+      - id: validate_content_delivery
+        title: "Validate content delivery compliance"
+        narrative: |
+          The buyer submits delivery data with creative references. The governance agent
+          evaluates the delivered content against the content standards and returns
+          a compliance report.
+        task: validate_content_delivery
+        schema_ref: "content-standards/validate-content-delivery-request.json"
+        response_schema_ref: "content-standards/validate-content-delivery-response.json"
+        doc_ref: "/governance/content-standards/tasks/validate_content_delivery"
+        comply_scenario: governance_content_standards
+        stateful: true
+        expected: |
+          Return validation results:
+          - compliant: boolean overall status
+          - Per-creative compliance status
+          - Violations with rule references and evidence
+
+        sample_request:
+          standards_id: "cs_acme_creative_001"
+          delivery:
+            - creative_id: "display_trail_pro_300x250"
+              impressions: 150000
+            - creative_id: "video_30s_trail_pro"
+              impressions: 75000
+
+        validations:
+          - check: response_schema
+            description: "Response matches validate-content-delivery-response.json schema"

package/storyboards/creative_ad_server.yaml

@@ -1,15 +1,12 @@
 id: creative_ad_server
-version: "1.0.0"
+version: "1.1.0"
 title: "Creative ad server"
 category: creative_ad_server
-summary: "Stateful ad server with pre-loaded creatives. Generates serving tags per media buy."
-platform_types:
-  - creative_ad_server
-
+summary: "Stateful ad server with pre-loaded creatives. Generates serving tags per media buy with pricing and billing."
 track: creative
 required_tools:
   - build_creative
-  - sync_creatives
+
 narrative: |
   You run a creative ad server — think Innovid, Flashtalking, or CM360. Your clients
   have already uploaded their creatives through your UI. Buyers connect to browse your
@@ -19,6 +16,10 @@ narrative: |
   assets to you. Instead, they browse your library, pick creatives, and ask you to generate
   tags for specific placements. For a campaign with 25 media buys, you'll generate 25 tags.
 
+  If you charge for your services, pricing is part of the flow. The buyer's account
+  determines the rate card. list_creatives shows the applicable pricing, build_creative
+  returns the cost, and report_usage closes the billing loop after delivery.
+
   This storyboard walks through that flow from the buyer's perspective.
 
 agent:
@@ -40,6 +41,9 @@ prerequisites:
     platform's own UI or API. The buyer does not push assets — they browse and
     request tags for what's already there.
 
+    For pricing steps, the buyer must have an established account with the ad server.
+    The account's rate card determines creative pricing.
+
 phases:
   - id: browse_library
     title: "Browse the creative library"
@@ -48,16 +52,19 @@ phases:
       available for a campaign. They call list_creatives to browse concepts and
       individual creatives in your library.
 
-      For an Innovid-like platform, this returns the advertiser's uploaded video
-      creatives, display ads, and any other assets managed in the platform.
+      When the buyer provides an account and requests pricing, each creative
+      includes the applicable rate from the account's rate card.
 
     steps:
       - id: list_creatives
-        title: "Browse available creatives"
+        title: "Browse available creatives with pricing"
         narrative: |
-          The buyer asks: "What creatives do you have for this advertiser?" This is
-          the primary entry point for ad server interactions — the buyer browses your
-          library to find creatives to use in their media buys.
+          The buyer asks: "What creatives do you have for this advertiser, and what
+          do they cost?" This is the primary entry point for ad server interactions.
+
+          With include_pricing=true and an account reference, the response includes
+          pricing_options on each creative. Vendors may offer multiple options —
+          volume tiers, context-specific rates, or different models per product line.
         task: list_creatives
         schema_ref: "creative/list-creatives-request.json"
         response_schema_ref: "creative/list-creatives-response.json"
@@ -70,6 +77,26 @@ phases:
           - format_id referencing the creative's format
           - name and status (approved, pending_review, rejected)
           - concept_id grouping related creatives across sizes
+          - pricing_options array with pricing_option_id, model, rate, currency
+            (when include_pricing=true and account provided)
+
+        sample_request:
+          account:
+            account_id: "acct_acme_creative"
+          include_pricing: true
+          filters:
+            statuses:
+              - "approved"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creatives-response.json schema"
+          - check: field_present
+            path: "creatives[0].pricing_options"
+            description: "First creative includes pricing_options from account rate card"
+          - check: field_present
+            path: "creatives[0].pricing_options[0].pricing_option_id"
+            description: "Pricing option includes pricing_option_id for billing reference"
 
       - id: list_output_formats
         title: "Check available output formats"
@@ -93,11 +120,13 @@ phases:
     narrative: |
       The buyer has selected creatives from your library and now needs serving tags
       for their media buys. They call build_creative for each media buy/package
-      combination, passing the creative_id and the context needed to generate the
-      right tag.
+      combination, passing the creative_id, account, and the context needed to
+      generate the right tag.
 
-      This is the core of the ad server interaction: turning library creatives into
-      traffickable tags.
+      When an account is provided, the response includes pricing fields — the
+      pricing_option_id that was applied and the vendor_cost for this build.
+      For CPM-priced creatives, vendor_cost is zero at build time because cost
+      accrues when impressions are served.
 
     steps:
       - id: build_tag
@@ -109,6 +138,9 @@ phases:
           For Innovid, this produces a VAST tag for a CTV placement. For Flashtalking,
           this might produce an HTML tag for a display placement. The media_buy_id and
           package_id provide the trafficking context.
+
+          The response includes pricing_option_id and vendor_cost so the buyer knows
+          which rate applies and what the build cost (zero for CPM).
         task: build_creative
         schema_ref: "media-buy/build-creative-request.json"
         response_schema_ref: "media-buy/build-creative-response.json"
@@ -120,9 +152,14 @@ phases:
           - An HTML, JavaScript, or VAST asset containing the tag
           - The format_id matching the target format
           - Macro placeholders (CLICK_URL, CACHEBUSTER) if applicable
+          - pricing_option_id from the account's rate card
+          - vendor_cost (0 for CPM — cost accrues at serve time)
+          - currency (ISO 4217)
 
         sample_request:
           creative_id: "campaign_hero_video"
+          account:
+            account_id: "acct_acme_creative"
           target_format_id:
             agent_url: "https://your-ad-server.example.com"
             id: "vast_30s"
@@ -135,6 +172,9 @@ phases:
           - check: field_present
             path: "creative_manifest.assets"
             description: "Output includes a serving tag asset"
+          - check: field_present
+            path: "pricing_option_id"
+            description: "Response includes pricing_option_id"
 
   - id: track_delivery
     title: "Track creative delivery"
@@ -169,3 +209,55 @@ phases:
         validations:
           - check: response_schema
             description: "Response matches get-creative-delivery-response.json schema"
+
+  - id: report_billing
+    title: "Report usage for billing"
+    narrative: |
+      After delivery, the buyer reports creative usage to the ad server for billing
+      reconciliation. Each usage record includes the creative_id and pricing_option_id
+      from the build_creative response, along with impressions served and the computed
+      vendor_cost.
+
+      The ad server validates that the pricing_option_id matches its records. If the
+      IDs don't match, the record is rejected with a descriptive error.
+
+    steps:
+      - id: report_usage
+        title: "Report impressions and cost"
+        narrative: |
+          The buyer sends a usage report covering a billing period. Each record
+          includes the creative_id, pricing_option_id (from the build_creative
+          response), impressions served, and the computed vendor_cost. The ad server
+          verifies the rate matches its rate card and accepts the record.
+        task: report_usage
+        schema_ref: "account/report-usage-request.json"
+        response_schema_ref: "account/report-usage-response.json"
+        doc_ref: "/accounts/tasks/report_usage"
+        comply_scenario: creative_flow
+        stateful: true
+        expected: |
+          Response includes:
+          - accepted count (number of records successfully stored)
+          - errors array (empty if all records pass validation)
+
+        sample_request:
+          idempotency_key: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+          reporting_period:
+            start: "2026-03-01T00:00:00Z"
+            end: "2026-03-31T23:59:59Z"
+          usage:
+            - account:
+                account_id: "acct_acme_creative"
+              creative_id: "campaign_hero_video"
+              pricing_option_id: "po_vast_30s_cpm"
+              impressions: 2400000
+              vendor_cost: 1200.00
+              currency: "USD"
+
+        validations:
+          - check: response_schema
+            description: "Response matches report-usage-response.json schema"
+          - check: field_value
+            path: "accepted"
+            value: 1
+            description: "One usage record accepted"