/*
=== Utility: Target CPC Calculator ===
Purpose: Calculate target bids from performance efficiency metrics (ACOS, AOV, CVR) for manual bid optimization.
Dataset: Keywords & Targets
Recommended: Change Bid → Set ($) using $target_bid | Manual Execution
Note: Run on-demand after reviewing performance - not intended for automated daily execution
*/

// === Core Settings ===
let $orders_min = 2;                            // CORE: Minimum orders required for reliable calculation
let $clicks_min = 20;                           // CORE: Minimum clicks required for reliable calculation
let $period_eval = 30d;                         // CORE: Performance evaluation period [30 days including today]

// === Safeguards ===
let $bid_limit_cpc_multiplier = 2.0;            // SAFEGUARD: Max bid = Avg CPC × 2.0 [e.g., $0.50 CPC = $1.00 max]
let $bid_limit_cpc_period = 90d;                // SAFEGUARD: Period for calculating CPC-based limits

// === Segment Filters ===
let $include_campaigns = [""];                  // FILTER: Apply to all campaigns, or specify terms
let $exclude_campaigns = ["NEVER_MATCH"];       // FILTER: Exclude campaigns containing these terms

// ============================================================================
// === Segment Logic ===
// ============================================================================
// Advanced logic below - modify carefully

// === Target CPC Calculation Method ===
// Formula: Target CPC = Target ACOS × Average Order Value × Conversion Rate
//
// Example: If targeting 30% ACOS with $50 AOV and 5% CVR:
// Target CPC = 0.30 × $50 × 0.05 = $0.75
//
// This ensures each click costs the right amount to hit your profit target
// given your actual conversion performance and order values.

// === Performance Metrics ===
let $recent_cpc = cpc($period_eval);
let $recent_acos = acos($period_eval);
let $recent_aov = aov($period_eval);
let $recent_orders = orders($period_eval);
let $recent_clicks = clicks($period_eval);

// Calculate conversion rate
let $recent_cvr = case(
   $recent_clicks > 0 => $recent_orders / $recent_clicks,
   else 0
);

// === Calculate Target CPC ===
let $calculated_target_cpc = case(
   target acos <= 0 => $recent_cpc,  // No target set - keep current bid
   $recent_cvr > 0 and $recent_aov > 0 => target acos * $recent_aov * $recent_cvr,
   else $recent_cpc  // Insufficient data - keep current bid
);

// === Apply Dynamic Bid Cap ===
let $avg_cpc_for_cap = cpc($bid_limit_cpc_period);
let $dynamic_max_bid = case(
   $avg_cpc_for_cap > 0 => $avg_cpc_for_cap * $bid_limit_cpc_multiplier,
   else 999  // No cap if no CPC data
);

let $target_bid = case(
   $calculated_target_cpc > $dynamic_max_bid => $dynamic_max_bid,
   else $calculated_target_cpc
);

// === Data Sufficiency Check ===
let $sufficient_data = case(
   $recent_orders >= $orders_min and $recent_clicks >= $clicks_min => 1,
   else 0
);

// === Diagnostic Properties ===
// Show calculation inputs for transparency
let $aov_used = $recent_aov;
let $cvr_used = $recent_cvr;
let $target_acos_used = target acos;
let $uncapped_target_cpc = $calculated_target_cpc;

let $reason = case(
   target acos <= 0 => "No target ACOS set - cannot calculate",
   $recent_orders < $orders_min => "Insufficient orders for reliable calculation",
   $recent_clicks < $clicks_min => "Insufficient clicks for reliable calculation",
   $calculated_target_cpc > $dynamic_max_bid => "Target CPC exceeds dynamic cap",
   $recent_cvr <= 0 or $recent_aov <= 0 => "Missing conversion or AOV data",
   else "Target CPC calculated from performance metrics"
);

let $result = case(
   target acos <= 0 => "No Target ACOS - Cannot Calculate",
   $sufficient_data = 0 => "Insufficient Data - Review Manually",
   $target_bid = bid => "No Change - Already at Target CPC",
   $calculated_target_cpc > $dynamic_max_bid => "Bid Set - Capped at Dynamic Maximum",
   $recent_cvr <= 0 or $recent_aov <= 0 => "Cannot Calculate - Missing Data",
   else "Target CPC Calculated Successfully"
);

// === Final Filter ===
state = "effectively enabled"
and (campaign name contains any $include_campaigns)
and (campaign name does not contain any $exclude_campaigns)
and target acos > 0
and $target_bid != bid
and $sufficient_data = 1