Media Buy

// Discover available publisher products
const products = await discover_publisher_products({
  query: "premium video inventory for sports fans",
  maxCpm: 30,
  formats: ["video", "display"]
});

// Returns publisher media products with pricing:
// • ESPN Video Package - $25 CPM (guaranteed delivery)
// • Fox Sports Display - $18 CPM (non-guaranteed)  
// • NBC Sports CTV - $45 CPM (premium guaranteed)

// Single product media buy
const mediaBuy = await media_buy_create({
  tacticId: "strat_123",
  name: "Q4 ESPN Video Buy",
  products: [{
    salesAgentId: "agent_espn_456",
    mediaProductId: "prod_video_789",
    budgetAmount: 25000,
    pricingCpm: 25.00,        // Base CPM from publisher
    pricingSignalCost: 2.50   // Additional cost for data targeting
  }],
  budget: {
    amount: 25000,
    currency: "USD",
    dailyCap: 1000,
    pacing: "even"
  }
});

// Total effective CPM: $27.50
// Projected impressions: ~909,090

// Multi-product media buy (single execution, multiple publishers)
const multiProductBuy = await media_buy_create({
  tacticId: "strat_123",
  name: "Q4 Sports Multi-Publisher Buy",
  products: [
    {
      salesAgentId: "agent_espn_456",
      mediaProductId: "prod_video_789",
      budgetAmount: 15000,
      pricingCpm: 25.00,
      pricingSignalCost: 2.50
    },
    {
      salesAgentId: "agent_fox_123",
      mediaProductId: "prod_display_456",
      budgetAmount: 10000,
      pricingCpm: 18.00,
      pricingSignalCost: 2.00
    }
  ],
  budget: {
    amount: 25000,  // Must match sum of product budgets
    currency: "USD",
    pacing: "even"
  }
});

// Each sales agent receives separate ADCP submission
// Budget validation ensures sum ≤ total

const execution = await media_buy_execute({
  mediaBuyId: "mb_123"
});

// Status progression:
// draft → pending_approval → active → completed
// ⚪     → 🟡              → 🟢    → ✅

const performance = await media_buy_get({
  mediaBuyId: "mb_123"
});

// Returns live metrics:
// 📊 Impressions: 450,230 delivered
// 💰 Spend: $12,381 (49.5% of budget)
// 📈 CPM: $27.51 (on target)
// ⏱️ Pacing: On track (51% remaining, 10 days left)

// Example pricing breakdown
{
  pricing: {
    cpm: 25.00,         // What publisher charges
    signalCost: 2.50,   // Data/targeting premium
    totalCpm: 27.50     // What you actually pay
  }
}

// List all media buys for a strategy
const mediaBuys = await media_buy_list({
  tacticId: "strat_123"
});

// Returns aggregated view:
// Total Media Buys: 5
// Active: 3 ($45,000 allocated)
// Pending: 1 ($10,000 allocated)  
// Draft: 1 ($5,000 allocated)
// 
// Top Performer: ESPN Buy (120% delivery)
// Needs Attention: Fox Buy (65% delivery)

// Pause underperforming buy
await media_buy_update({
  mediaBuyId: "mb_underperformer",
  status: "paused"
});

// Increase budget for high performer
await media_buy_update({
  mediaBuyId: "mb_top_performer",
  budget: {
    amount: 15000  // Increased from 10000
  }
});

// Adjust pacing for time-sensitive campaign
await media_buy_update({
  mediaBuyId: "mb_urgent",
  budget: {
    pacing: "asap"  // Changed from "even"
  }
});

// Webhook payload when publisher approves
{
  event: "media_buy.approved",
  mediaBuyId: "mb_123",
  adcpMediaBuyId: "adcp_456",
  status: "active",
  timestamp: "2024-01-15T10:30:00Z"
}

// Automatic status update in your system
// No polling required

// Good: Diversified across publishers
Strategy: $50,000
├── ESPN: $15,000 (30%)
├── Fox: $12,000 (24%)
├── NBC: $10,000 (20%)
├── CNN: $8,000 (16%)
└── CBS: $5,000 (10%)

// Risky: Single publisher concentration
Strategy: $50,000
└── ESPN: $50,000 (100%) ❌

// Analyze CPM efficiency
const analysis = await analyze_media_buys({
  tacticId: "strat_123"
});

// Premium Video CPMs:
// ESPN: $28 (baseline)
// Fox: $26 (-7% vs ESPN) ✅
// NBC: $32 (+14% vs ESPN) ⚠️
// CBS: $25 (-11% vs ESPN) ✅

// Daily monitoring routine
const dailyCheck = async () => {
  const mediaBuys = await media_buy_list({
    tacticId: "strat_123",
    status: "active"
  });

  for (const mb of mediaBuys) {
    if (mb.performance.cpm > mb.pricing.totalCpm * 1.1) {
      // CPM drifting 10% above target
      console.warn(`Review ${mb.name}: CPM drift detected`);
    }

    if (mb.performance.impressions < mb.projectedDaily * 0.8) {
      // Under-delivering by 20%
      console.warn(`Review ${mb.name}: Under-delivery detected`);
    }
  }
};

// Start small with new publishers
const testBuy = await media_buy_create({
  tacticId: "strat_123",
  salesAgentId: "new_publisher",
  name: "Test Buy - New Publisher",
  budget: {
    amount: 1000,  // Small test budget
    pacing: "even"
  },
  cpm: 20.00
});

// If performance is good, scale up
if (testBuy.performance.qualityScore > 80) {
  await media_buy_update({
    mediaBuyId: testBuy.id,
    budget: { amount: 10000 }  // 10x increase
  });
}

// Book premium inventory in advance
const holidayBuy = await media_buy_create({
  tacticId: "strat_holiday",
  name: "Black Friday Premium Video",
  budget: {
    amount: 50000,
    pacing: "front_loaded"  // Heavy early delivery
  },
  startDate: "2024-11-25",
  endDate: "2024-11-30"
});

// Strategy organizes all media buys
const strategy = await strategy_get({
  tacticId: "strat_123"
});

// Shows aggregated metrics:
{
  metrics: {
    totalSpend: 45230,        // Sum of all media buys
    totalImpressions: 1650000, // Combined delivery
    averageCpm: 27.41,        // Weighted average
    activeMediaBuys: 3,       // Currently delivering
    totalMediaBuys: 5         // All statuses
  }
}