feat: Add UX improvements to naming templates - live preview, presets, validation

[bokelley]

Summary

Adds publisher-configurable GAM order/line item naming templates with comprehensive UX improvements based on agent feedback.

Problem

Publishers were getting GAM orders named "None - X packages" because we were using optional campaign_name instead of required promoted_offering. More broadly, different publishers have different naming conventions - some want dates, some want advertiser names, some want brief summaries. Hardcoding the format doesn't work for a platform.

Solution

Built a configurable naming template system with:

• Variable substitution with fallback syntax
• Live preview showing exact output
• Preset templates for common use cases
• Real-time validation
• Comprehensive inline help

Changes

Commit 1: Core Feature (57cc4ab)

• Database schema: Added gam_order_name_template and gam_line_item_name_template to adapter_config
• Template engine: Variable substitution with fallback syntax ({var1|var2})
• Smart date formatting (handles same month, different months, different years)
• Admin UI: Basic configuration fields
• GAM adapter: Loads templates from config and applies them

Commit 2: Better Defaults (71b3cf1)

• Quick fix: Used promoted_offering with fallback to campaign_name
• Prevented "None" from appearing in order names

Commit 3: UX Improvements (eeb93aa)

Based on detailed feedback from ad-tech-protocol-expert and adtech-product-expert:

1. Better Line Item Default

• Changed from {product_name} to {order_name} - {product_name}
• Industry standard (DV360, TTD, Amazon DSP all do this)
• Provides campaign context in line-item reports
• Result: "Nike Q1 Launch - Oct 7-14, 2025 - Display 300x250"

2. Preset Template Buttons
Three one-click presets:

• 📊 Simple: {promoted_offering} - {date_range}
• 🎯 Campaign-First: {campaign_name|promoted_offering} - {month_year}
• 📅 Detailed: {campaign_name|promoted_offering} - {date_range} - {package_count}pkg

3. Live Preview with Sample Data

• Real-time rendering as you type
• Shows order name + 3 line item examples
• Uses realistic sample: campaign_name=null, promoted_offering="Nike Shoes Q1", 3 products
• Updates immediately on input change

4. Inline Variable Help

• Collapsible <details> sections for each template
• Explains every variable with examples:
  • {campaign_name} - Campaign name (optional - may be empty)
  • {promoted_offering} - What's being advertised (always present)
  • {buyer_ref} - Buyer's internal reference (optional)
  • {date_range} - Flight dates (e.g., "Oct 7-14, 2025")
  • {month_year} - Month and year (e.g., "Oct 2025")
  • {package_count} - Number of packages in order
• Documents fallback syntax: {var1|var2} uses var1 if present, else var2
• Non-intrusive until clicked

5. Client-Side Validation
Validates templates in real-time:

• ✅ Empty results: "⚠️ Template produces empty name - add fallback variables"
• ✅ Character limits: "❌ Order name too long (320 chars, max 255)"
• ✅ Risky patterns: "💡 Tip: {campaign_name} is optional - add fallback"
• Color-coded feedback: Red (errors), Amber (warnings), Green (success)
• Shows character counts: "✅ Templates look good (35 chars for order, 67 chars max for line items)"

Default Templates

Order Name:

{campaign_name|promoted_offering} - {date_range}

Examples:

• With campaign_name: "Q1 Launch - Oct 7-14, 2025"
• Without (fallback): "Nike Shoes - Oct 7-14, 2025"

Line Item Name:

{order_name} - {product_name}

Examples:

• "Nike Q1 Launch - Oct 7-14, 2025 - Display 300x250"
• "Spring Promo - Mar 2025 - Video Pre-roll"

Available Variables

For Orders:

• {campaign_name} - Optional buyer field
• {promoted_offering} - Required (what's being advertised)
• {buyer_ref} - Optional buyer reference
• {date_range} - Formatted flight dates
• {month_year} - Month-focused format
• {package_count} - Number of packages

For Line Items:

• {product_name} - Product/inventory name
• {order_name} - Parent order name (for context)
• {package_index} - Package position (1, 2, 3...)

Benefits

For Publishers

• ✅ Control: Define your own naming conventions
• ✅ Consistency: Templates ensure uniform naming
• ✅ Flexibility: Supports any pattern (dates, advertisers, briefs, etc.)
• ✅ Spec Compliant: Works with all AdCP fields (required and optional)

For Users

• ✅ Power users: Full flexibility with custom templates and live feedback
• ✅ Average users: Click preset button → See preview → Save (5 seconds)
• ✅ All users: Know exactly what names will look like before committing

Testing

• ✅ All unit tests pass
• ✅ Pre-commit hooks pass (schema validation, linting, formatting)
• ✅ MCP tool contract validation passes
• ✅ AdCP spec compliance validated
• ⚠️ One integration test fails in quick mode (database not running - unrelated to changes)

Migration

Migration ede76bc258af adds two fields:

• gam_order_name_template (String, 500 chars, nullable)
• gam_line_item_name_template (String, 500 chars, nullable)

Existing GAM tenants get defaults automatically.

Screenshots

Live preview with validation:

┌─────────────────────────────────────────────────┐
│ Order Name:                                     │
│ Nike Shoes Q1 - Oct 7-14, 2025                 │
├─────────────────────────────────────────────────┤
│ Line Item Names:                                │
│ 1. Nike Shoes Q1 - Oct 7-14, 2025 - Display... │
│ 2. Nike Shoes Q1 - Oct 7-14, 2025 - Video...  │
│ 3. Nike Shoes Q1 - Oct 7-14, 2025 - Native... │
├─────────────────────────────────────────────────┤
│ ✅ Templates look good (35 chars for order,    │
│    67 chars max for line items)                 │
└─────────────────────────────────────────────────┘

Follow-up Work

Phase 2 (Future):

• Add {advertiser_name} variable (useful for multi-advertiser publishers)
• Template presets based on publisher tier/business model
• Import/export templates between tenants

References

• AdCP Spec: https://adcontextprotocol.org/docs/
• Agent feedback: See commits for detailed analysis from ad-tech-protocol-expert and adtech-product-expert

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com