Metaads

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "python-dotenv",
# ]
# ///
"""
Meta Ads Performance Analytics (Marketing API)

Fetches campaign, ad set, ad, and creative performance metrics from Meta Ads.
Saves data to Analytics/meta-ads/ for cross-channel analysis.

Usage:
    uv run scripts/meta-ads-analytics.py --setup                 # Credential setup guide
    uv run scripts/meta-ads-analytics.py --summary               # Account overview (last 7 days)
    uv run scripts/meta-ads-analytics.py --campaigns             # All campaigns with metrics
    uv run scripts/meta-ads-analytics.py --campaign CAMPAIGN_ID  # Deep dive (daily + ad sets + ads)
    uv run scripts/meta-ads-analytics.py --adsets                # Ad set performance
    uv run scripts/meta-ads-analytics.py --ads                   # Ad-level performance
    uv run scripts/meta-ads-analytics.py --creative              # Asset-level breakdowns
    uv run scripts/meta-ads-analytics.py --audience              # Age/gender/placement/device
    uv run scripts/meta-ads-analytics.py --period 30             # Custom lookback (default 7)
    uv run scripts/meta-ads-analytics.py --sync                  # Save all data to Analytics/
    uv run scripts/meta-ads-analytics.py --export results.csv    # Export to CSV

Environment variables (or .env file):
    META_ADS_ACCESS_TOKEN - System User token with ads_read permission
    META_ADS_ACCOUNT_ID   - Ad account ID (format: act_XXXXXXXXX)
"""

import argparse
import csv
import json
import os
import sys
import time
from datetime import datetime, timedelta, timezone
from pathlib import Path

import requests
from dotenv import load_dotenv

# Load environment variables from current working directory
PROJECT_ROOT = Path.cwd()
load_dotenv(PROJECT_ROOT / ".env")

ACCESS_TOKEN = os.getenv("META_ADS_ACCESS_TOKEN", "")
ACCOUNT_ID = os.getenv("META_ADS_ACCOUNT_ID", "")

DATA_DIR = PROJECT_ROOT / "Analytics" / "meta-ads"
API_BASE = "https://graph.facebook.com/v21.0"

# Standard insight fields
INSIGHT_FIELDS = (
    "impressions,reach,clicks,ctr,cpc,cpm,cpp,spend,"
    "actions,cost_per_action_type,purchase_roas,"
    "frequency,unique_clicks,cost_per_unique_click"
)


# ---------------------------------------------------------------------------
# API helpers
# ---------------------------------------------------------------------------

def api_request(
    endpoint: str,
    params: dict | None = None,
    max_retries: int = 5,
) -> dict | None:
    """Make authenticated GET request with rate limiting and exponential backoff."""
    params = params or {}
    params["access_token"] = ACCESS_TOKEN

    url = f"{API_BASE}/{endpoint}"

    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params, timeout=60)

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
                print(f"  Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue

            if response.status_code != 200:
                error = response.json().get("error", {})
                error_msg = error.get("message", response.text[:300])
                error_code = error.get("code", "")

                # Transient errors — retry
                if error_code in (1, 2, 4, 17):
                    wait = 2 ** attempt
                    print(f"  Transient API error (code {error_code}). Retrying in {wait}s...")
                    time.sleep(wait)
                    continue

                print(f"  API Error [{error_code}]: {error_msg}")
                return None

            return response.json()

        except requests.RequestException as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"  Request error: {e}. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                print(f"  Request failed after {max_retries} attempts: {e}")
                return None

    return None


# ---------------------------------------------------------------------------
# Data helpers
# ---------------------------------------------------------------------------

def save_data(filename: str, data: dict) -> None:
    """Save data to JSON file in Analytics/meta-ads/."""
    DATA_DIR.mkdir(parents=True, exist_ok=True)
    filepath = DATA_DIR / filename
    with open(filepath, "w") as f:
        json.dump(data, f, indent=2, default=str)
    print(f"  Saved to {filepath.relative_to(PROJECT_ROOT)}")


def load_data(filename: str) -> dict | None:
    """Load data from JSON file."""
    filepath = DATA_DIR / filename
    if filepath.exists():
        with open(filepath) as f:
            return json.load(f)
    return None


def save_sync_state(key: str) -> None:
    """Update sync state timestamp."""
    state_file = DATA_DIR / "sync-meta.json"
    state = {}
    if state_file.exists():
        with open(state_file) as f:
            state = json.load(f)
    state[key] = datetime.now(timezone.utc).isoformat()
    DATA_DIR.mkdir(parents=True, exist_ok=True)
    with open(state_file, "w") as f:
        json.dump(state, f, indent=2)


def date_range(days: int) -> tuple[str, str]:
    """Return (since, until) date strings for the given lookback period."""
    until = datetime.now(timezone.utc).date()
    since = until - timedelta(days=days)
    return str(since), str(until)


def extract_action_value(actions: list | None, action_type: str) -> float:
    """Extract a specific action value from the actions list."""
    if not actions:
        return 0
    for a in actions:
        if a.get("action_type") == action_type:
            return float(a.get("value", 0))
    return 0


def extract_roas(roas_list: list | None) -> float:
    """Extract purchase ROAS value."""
    if not roas_list:
        return 0
    for r in roas_list:
        if r.get("action_type") == "omni_purchase":
            return float(r.get("value", 0))
    return 0


def extract_cost_per_action(cost_list: list | None, action_type: str) -> float:
    """Extract cost per specific action."""
    if not cost_list:
        return 0
    for c in cost_list:
        if c.get("action_type") == action_type:
            return float(c.get("value", 0))
    return 0


# ---------------------------------------------------------------------------
# Insight fetching
# ---------------------------------------------------------------------------

def get_account_insights(days: int = 7) -> dict | None:
    """Account-level insights for the given period."""
    since, until = date_range(days)
    print(f"Fetching account insights ({since} to {until})...")

    result = api_request(
        f"{ACCOUNT_ID}/insights",
        params={
            "fields": INSIGHT_FIELDS,
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "account",
        },
    )

    if result and result.get("data"):
        return result["data"][0]
    return None


def get_campaigns_insights(days: int = 7) -> list:
    """Campaign-level insights."""
    since, until = date_range(days)
    print(f"Fetching campaign insights ({since} to {until})...")

    result = api_request(
        f"{ACCOUNT_ID}/insights",
        params={
            "fields": f"campaign_id,campaign_name,{INSIGHT_FIELDS}",
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "campaign",
            "limit": 100,
        },
    )

    return result.get("data", []) if result else []


def get_adset_insights(days: int = 7) -> list:
    """Ad set-level insights."""
    since, until = date_range(days)
    print(f"Fetching ad set insights ({since} to {until})...")

    result = api_request(
        f"{ACCOUNT_ID}/insights",
        params={
            "fields": f"adset_id,adset_name,campaign_name,{INSIGHT_FIELDS}",
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "adset",
            "limit": 200,
        },
    )

    return result.get("data", []) if result else []


def get_ad_insights(days: int = 7) -> list:
    """Ad-level insights."""
    since, until = date_range(days)
    print(f"Fetching ad-level insights ({since} to {until})...")

    result = api_request(
        f"{ACCOUNT_ID}/insights",
        params={
            "fields": f"ad_id,ad_name,adset_name,campaign_name,{INSIGHT_FIELDS}",
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "ad",
            "limit": 500,
        },
    )

    return result.get("data", []) if result else []


def get_campaign_deep_dive(campaign_id: str, days: int = 7) -> dict:
    """Single campaign with daily time series + breakdowns."""
    since, until = date_range(days)
    print(f"Fetching deep dive for campaign {campaign_id}...")

    # Daily trend
    daily = api_request(
        f"{campaign_id}/insights",
        params={
            "fields": INSIGHT_FIELDS,
            "time_range": json.dumps({"since": since, "until": until}),
            "time_increment": 1,
        },
    )

    # Campaign info
    info = api_request(
        campaign_id,
        params={"fields": "id,name,status,effective_status,objective,daily_budget"},
    )

    # Ad set breakdown
    adsets = api_request(
        f"{campaign_id}/insights",
        params={
            "fields": f"adset_id,adset_name,{INSIGHT_FIELDS}",
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "adset",
            "limit": 50,
        },
    )

    # Ad breakdown
    ads = api_request(
        f"{campaign_id}/insights",
        params={
            "fields": f"ad_id,ad_name,{INSIGHT_FIELDS}",
            "time_range": json.dumps({"since": since, "until": until}),
            "level": "ad",
            "limit": 100,
        },
    )

    return {
        "campaign": info or {},
        "daily": daily.get("data", []) if daily else [],
        "adsets": adsets.get("data", []) if adsets else [],
        "ads": ads.get("data", []) if ads else [],
    }


def get_audience_breakdowns(days: int = 7) -> dict:
    """Age, gender, placement, device breakdowns."""
    since, until = date_range(days)
    print(f"Fetching audience breakdowns ({since} to {until})...")

    breakdowns = {}

    for breakdown_name in ["age", "gender", "publisher_platform", "device_platform"]:
        result = api_request(
            f"{ACCOUNT_ID}/insights",
            params={
                "fields": INSIGHT_FIELDS,
                "time_range": json.dumps({"since": since, "until": until}),
                "breakdowns": breakdown_name,
                "level": "account",
                "limit": 100,
            },
        )
        breakdowns[breakdown_name] = result.get("data", []) if result else []

    return breakdowns


# ---------------------------------------------------------------------------
# Display functions
# ---------------------------------------------------------------------------

def print_summary(insights: dict, days: int) -> None:
    """Print account summary."""
    print(f"\n{'='*70}")
    print(f"META ADS ACCOUNT SUMMARY (last {days} days)")
    print(f"{'='*70}")

    spend = float(insights.get("spend", 0))
    impressions = int(insights.get("impressions", 0))
    reach = int(insights.get("reach", 0))
    clicks = int(insights.get("clicks", 0))
    ctr = float(insights.get("ctr", 0))
    cpc = float(insights.get("cpc", 0))
    cpm = float(insights.get("cpm", 0))
    frequency = float(insights.get("frequency", 0))

    purchases = extract_action_value(insights.get("actions"), "omni_purchase")
    add_to_cart = extract_action_value(insights.get("actions"), "omni_add_to_cart")
    roas = extract_roas(insights.get("purchase_roas"))
    cpa = extract_cost_per_action(insights.get("cost_per_action_type"), "omni_purchase")

    print(f"\n  Spend:        ${spend:,.2f}")
    print(f"  Impressions:  {impressions:,}")
    print(f"  Reach:        {reach:,}")
    print(f"  Frequency:    {frequency:.2f}")
    print(f"  Clicks:       {clicks:,}")
    print(f"  CTR:          {ctr:.2f}%")
    print(f"  CPC:          ${cpc:.2f}")
    print(f"  CPM:          ${cpm:.2f}")

    print(f"\n  Conversions:")
    print(f"    Purchases:    {purchases:.0f}")
    print(f"    Add to Cart:  {add_to_cart:.0f}")
    print(f"    CPA:          ${cpa:.2f}" if cpa else "    CPA:          N/A")
    print(f"    ROAS:         {roas:.2f}x" if roas else "    ROAS:         N/A")

    # DTC benchmark comparison
    print(f"\n  DTC Benchmarks:")
    ctr_status = "GOOD" if ctr >= 1.0 else "LOW" if ctr < 0.5 else "OK"
    cpm_status = "GOOD" if cpm <= 20 else "HIGH" if cpm > 30 else "OK"
    cpa_status = "GOOD" if 0 < cpa <= 30 else "HIGH" if cpa > 60 else "OK" if cpa > 0 else "N/A"
    roas_status = "GOOD" if roas >= 3.0 else "LOW" if 0 < roas < 2.0 else "OK" if roas > 0 else "N/A"

    print(f"    CTR {ctr:.2f}% [{ctr_status}] (target: 1-2.5%)")
    print(f"    CPM ${cpm:.2f} [{cpm_status}] (target: $10-30)")
    print(f"    CPA ${cpa:.2f} [{cpa_status}] (target: $20-60)" if cpa else f"    CPA N/A (target: $20-60)")
    print(f"    ROAS {roas:.2f}x [{roas_status}] (target: 2-4x)" if roas else f"    ROAS N/A (target: 2-4x)")

    print(f"\n{'='*70}")


def print_campaign_table(campaigns: list) -> None:
    """Print campaign metrics table."""
    print(f"\n{'='*100}")
    print("CAMPAIGN PERFORMANCE")
    print(f"{'='*100}")

    print(f"\n{'Campaign':<30} {'Spend':>10} {'Impr':>10} {'Clicks':>8} {'CTR':>7} {'CPC':>7} {'Purch':>7} {'ROAS':>7}")
    print(f"{'-'*30} {'-'*10} {'-'*10} {'-'*8} {'-'*7} {'-'*7} {'-'*7} {'-'*7}")

    for c in campaigns:
        name = c.get("campaign_name", "")[:29]
        spend = float(c.get("spend", 0))
        impressions = int(c.get("impressions", 0))
        clicks = int(c.get("clicks", 0))
        ctr = float(c.get("ctr", 0))
        cpc = float(c.get("cpc", 0))
        purchases = extract_action_value(c.get("actions"), "omni_purchase")
        roas = extract_roas(c.get("purchase_roas"))

        roas_str = f"{roas:.1f}x" if roas else "—"
        purch_str = f"{purchases:.0f}" if purchases else "—"

        print(f"{name:<30} ${spend:>9,.2f} {impressions:>10,} {clicks:>8,} {ctr:>6.2f}% ${cpc:>5.2f} {purch_str:>7} {roas_str:>7}")

    print(f"\n{'='*100}")


def print_adset_table(adsets: list) -> None:
    """Print ad set metrics table."""
    print(f"\n{'='*100}")
    print("AD SET PERFORMANCE")
    print(f"{'='*100}")

    print(f"\n{'Ad Set':<30} {'Campaign':<20} {'Spend':>10} {'Impr':>9} {'CTR':>7} {'CPC':>7} {'ROAS':>7}")
    print(f"{'-'*30} {'-'*20} {'-'*10} {'-'*9} {'-'*7} {'-'*7} {'-'*7}")

    for a in adsets:
        name = a.get("adset_name", "")[:29]
        campaign = a.get("campaign_name", "")[:19]
        spend = float(a.get("spend", 0))
        impressions = int(a.get("impressions", 0))
        ctr = float(a.get("ctr", 0))
        cpc = float(a.get("cpc", 0))
        roas = extract_roas(a.get("purchase_roas"))
        roas_str = f"{roas:.1f}x" if roas else "—"

        print(f"{name:<30} {campaign:<20} ${spend:>9,.2f} {impressions:>9,} {ctr:>6.2f}% ${cpc:>5.2f} {roas_str:>7}")

    print(f"\n{'='*100}")


def print_ad_table(ads: list) -> None:
    """Print ad-level metrics table."""
    print(f"\n{'='*100}")
    print("AD PERFORMANCE")
    print(f"{'='*100}")

    print(f"\n{'Ad Name':<35} {'Spend':>10} {'Impr':>9} {'CTR':>7} {'CPC':>7} {'Purch':>7} {'ROAS':>7}")
    print(f"{'-'*35} {'-'*10} {'-'*9} {'-'*7} {'-'*7} {'-'*7} {'-'*7}")

    for a in ads:
        name = a.get("ad_name", "")[:34]
        spend = float(a.get("spend", 0))
        impressions = int(a.get("impressions", 0))
        ctr = float(a.get("ctr", 0))
        cpc = float(a.get("cpc", 0))
        purchases = extract_action_value(a.get("actions"), "omni_purchase")
        roas = extract_roas(a.get("purchase_roas"))

        roas_str = f"{roas:.1f}x" if roas else "—"
        purch_str = f"{purchases:.0f}" if purchases else "—"

        print(f"{name:<35} ${spend:>9,.2f} {impressions:>9,} {ctr:>6.2f}% ${cpc:>5.2f} {purch_str:>7} {roas_str:>7}")

    print(f"\n{'='*100}")


def print_campaign_deep_dive(data: dict, days: int) -> None:
    """Print campaign deep dive with daily trend."""
    campaign = data.get("campaign", {})
    daily = data.get("daily", [])
    adsets = data.get("adsets", [])
    ads = data.get("ads", [])

    print(f"\n{'='*70}")
    print(f"CAMPAIGN DEEP DIVE (last {days} days)")
    print(f"{'='*70}")
    print(f"  Name:      {campaign.get('name', 'N/A')}")
    print(f"  Status:    {campaign.get('effective_status', campaign.get('status', 'N/A'))}")
    print(f"  Objective: {campaign.get('objective', 'N/A')}")

    if daily:
        print(f"\n  Daily Trend:")
        print(f"  {'Date':<12} {'Spend':>10} {'Impr':>9} {'Clicks':>8} {'CTR':>7} {'Purch':>7}")
        print(f"  {'-'*12} {'-'*10} {'-'*9} {'-'*8} {'-'*7} {'-'*7}")

        for day in daily:
            date = day.get("date_start", "")
            spend = float(day.get("spend", 0))
            impressions = int(day.get("impressions", 0))
            clicks = int(day.get("clicks", 0))
            ctr = float(day.get("ctr", 0))
            purchases = extract_action_value(day.get("actions"), "omni_purchase")
            purch_str = f"{purchases:.0f}" if purchases else "—"

            print(f"  {date:<12} ${spend:>9,.2f} {impressions:>9,} {clicks:>8,} {ctr:>6.2f}% {purch_str:>7}")

    if adsets:
        print(f"\n  Ad Set Breakdown:")
        for a in adsets:
            name = a.get("adset_name", "")
            spend = float(a.get("spend", 0))
            ctr = float(a.get("ctr", 0))
            roas = extract_roas(a.get("purchase_roas"))
            roas_str = f"{roas:.1f}x" if roas else "—"
            print(f"    {name}: ${spend:,.2f} spend, {ctr:.2f}% CTR, {roas_str} ROAS")

    if ads:
        print(f"\n  Top Ads:")
        sorted_ads = sorted(ads, key=lambda x: float(x.get("spend", 0)), reverse=True)
        for a in sorted_ads[:10]:
            name = a.get("ad_name", "")[:40]
            spend = float(a.get("spend", 0))
            ctr = float(a.get("ctr", 0))
            roas = extract_roas(a.get("purchase_roas"))
            roas_str = f"{roas:.1f}x" if roas else "—"
            print(f"    {name}: ${spend:,.2f} spend, {ctr:.2f}% CTR, {roas_str} ROAS")

    print(f"\n{'='*70}")


def print_audience_breakdowns(breakdowns: dict) -> None:
    """Print audience breakdown tables."""
    print(f"\n{'='*70}")
    print("AUDIENCE BREAKDOWNS")
    print(f"{'='*70}")

    for breakdown_name, data in breakdowns.items():
        if not data:
            continue

        label = breakdown_name.replace("_", " ").title()
        print(f"\n  {label}:")
        print(f"  {'Segment':<25} {'Spend':>10} {'Impr':>10} {'CTR':>7} {'CPC':>7}")
        print(f"  {'-'*25} {'-'*10} {'-'*10} {'-'*7} {'-'*7}")

        for row in data:
            segment = row.get(breakdown_name, "unknown")
            spend = float(row.get("spend", 0))
            impressions = int(row.get("impressions", 0))
            ctr = float(row.get("ctr", 0))
            cpc = float(row.get("cpc", 0))
            print(f"  {segment:<25} ${spend:>9,.2f} {impressions:>10,} {ctr:>6.2f}% ${cpc:>5.2f}")

    print(f"\n{'='*70}")


# ---------------------------------------------------------------------------
# Export & sync
# ---------------------------------------------------------------------------

def export_to_csv(data: list, filepath: Path) -> None:
    """Export insight rows to CSV."""
    if not data:
        print("  No data to export")
        return

    # Flatten actions into columns
    rows = []
    for row in data:
        flat = {}
        for k, v in row.items():
            if k in ("actions", "cost_per_action_type", "purchase_roas"):
                continue
            flat[k] = v

        flat["purchases"] = extract_action_value(row.get("actions"), "omni_purchase")
        flat["add_to_cart"] = extract_action_value(row.get("actions"), "omni_add_to_cart")
        flat["roas"] = extract_roas(row.get("purchase_roas"))
        flat["cost_per_purchase"] = extract_cost_per_action(
            row.get("cost_per_action_type"), "omni_purchase"
        )
        rows.append(flat)

    if not rows:
        return

    fieldnames = list(rows[0].keys())
    with open(filepath, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(rows)

    print(f"  Exported {len(rows)} rows to {filepath}")


def sync_all_data(days: int) -> None:
    """Full sync of all insight data to Analytics/meta-ads/."""
    print(f"\nSyncing all Meta Ads data (last {days} days)...\n")

    # Account insights
    account = get_account_insights(days)
    if account:
        account["_fetched_at"] = datetime.now(timezone.utc).isoformat()
        account["_days"] = days
        save_data("insights-account.json", account)
        save_sync_state("insights-account")

    # Campaign insights
    campaigns = get_campaigns_insights(days)
    if campaigns:
        save_data("insights-campaigns.json", {
            "data": campaigns,
            "_fetched_at": datetime.now(timezone.utc).isoformat(),
            "_days": days,
        })
        save_sync_state("insights-campaigns")

    # Ad set insights
    adsets = get_adset_insights(days)
    if adsets:
        save_data("adsets.json", {
            "data": adsets,
            "_fetched_at": datetime.now(timezone.utc).isoformat(),
            "_days": days,
        })
        save_sync_state("adsets")

    # Campaign list
    campaigns_list = api_request(
        f"{ACCOUNT_ID}/campaigns",
        params={
            "fields": "id,name,status,effective_status,objective,daily_budget,created_time",
            "limit": 100,
        },
    )
    if campaigns_list and campaigns_list.get("data"):
        save_data("campaigns.json", {
            "data": campaigns_list["data"],
            "_fetched_at": datetime.now(timezone.utc).isoformat(),
        })
        save_sync_state("campaigns")

    # Audience breakdowns
    audience = get_audience_breakdowns(days)
    if audience:
        audience["_fetched_at"] = datetime.now(timezone.utc).isoformat()
        audience["_days"] = days
        save_data("insights-audience.json", audience)
        save_sync_state("insights-audience")

    print(f"\nSync complete. Data saved to {DATA_DIR.relative_to(PROJECT_ROOT)}/")


# ---------------------------------------------------------------------------
# Setup
# ---------------------------------------------------------------------------

def print_setup_guide() -> None:
    """Print credential setup instructions."""
    print("""
META ADS ANALYTICS SETUP GUIDE
===============================

To use this script, you need:
1. META_ADS_ACCESS_TOKEN - System User token with ads_read permission
2. META_ADS_ACCOUNT_ID   - Ad account ID (format: act_XXXXXXXXX)

If you already set up meta-ads-publish.py, the same credentials work here.

STEP 1: Create a System User in Business Manager
-------------------------------------------------
1. Go to business.facebook.com/settings
2. Navigate to Users > System Users
3. Click "Add" to create a new System User
4. Set role to "Admin"

STEP 2: Generate an Access Token
---------------------------------
1. Click on the System User you created
2. Click "Generate New Token"
3. Select your app
4. Select permissions:
   - ads_read (required - read campaign metrics)
   - ads_management (optional - if also using publish script)
5. Click "Generate Token"

STEP 3: Get Your Ad Account ID
-------------------------------
1. Go to business.facebook.com/settings
2. Navigate to Accounts > Ad Accounts
3. Copy the account ID (format: act_XXXXXXXXX)

STEP 4: Add to .env
--------------------
META_ADS_ACCESS_TOKEN=your_system_user_token
META_ADS_ACCOUNT_ID=act_XXXXXXXXX

STEP 5: Verify
--------------
uv run scripts/meta-ads-analytics.py --summary

AVAILABLE METRICS
=================
  --summary    Account overview with DTC benchmarks
  --campaigns  Campaign-level metrics table
  --campaign   Single campaign deep dive (daily trend + ad sets)
  --adsets     Ad set performance
  --ads        Ad-level performance
  --audience   Age, gender, platform, device breakdowns
  --sync       Save all data to Analytics/meta-ads/
  --export     Export to CSV for spreadsheet analysis
  --period N   Change lookback period (default: 7 days)
""")


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(
        description="Meta Ads Performance Analytics",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  uv run scripts/meta-ads-analytics.py --summary
  uv run scripts/meta-ads-analytics.py --campaigns --period 30
  uv run scripts/meta-ads-analytics.py --campaign 12345678
  uv run scripts/meta-ads-analytics.py --audience
  uv run scripts/meta-ads-analytics.py --sync
  uv run scripts/meta-ads-analytics.py --export results.csv
        """,
    )

    parser.add_argument("--setup", action="store_true", help="Show setup guide")
    parser.add_argument("--summary", action="store_true", help="Account overview")
    parser.add_argument("--campaigns", action="store_true", help="All campaigns with metrics")
    parser.add_argument("--campaign", metavar="ID", help="Deep dive into specific campaign")
    parser.add_argument("--adsets", action="store_true", help="Ad set performance")
    parser.add_argument("--ads", action="store_true", help="Ad-level performance")
    parser.add_argument("--creative", action="store_true", help="Creative/asset breakdowns")
    parser.add_argument("--audience", action="store_true", help="Audience breakdowns")
    parser.add_argument("--period", type=int, default=7, help="Lookback period in days (default: 7)")
    parser.add_argument("--sync", action="store_true", help="Save all data to Analytics/meta-ads/")
    parser.add_argument("--export", metavar="FILE", help="Export campaign data to CSV")

    args = parser.parse_args()

    if args.setup:
        print_setup_guide()
        return

    # All other commands need credentials
    if not ACCESS_TOKEN or not ACCOUNT_ID:
        print("Error: Missing Meta Ads credentials")
        print("\nRequired environment variables:")
        print("  META_ADS_ACCESS_TOKEN - System User token")
        print("  META_ADS_ACCOUNT_ID   - Ad account ID (act_XXXXXXXXX)")
        print("\nRun with --setup for configuration instructions:")
        print("  uv run scripts/meta-ads-analytics.py --setup")
        sys.exit(1)

    days = args.period

    # Default to summary if no action specified
    has_action = any([
        args.summary, args.campaigns, args.campaign, args.adsets,
        args.ads, args.creative, args.audience, args.sync, args.export,
    ])
    if not has_action:
        args.summary = True

    if args.summary:
        insights = get_account_insights(days)
        if insights:
            print_summary(insights, days)
        else:
            print("  No data available for this period")

    if args.campaigns:
        campaigns = get_campaigns_insights(days)
        if campaigns:
            print_campaign_table(campaigns)
        else:
            print("  No campaign data available")

    if args.campaign:
        data = get_campaign_deep_dive(args.campaign, days)
        print_campaign_deep_dive(data, days)

    if args.adsets:
        adsets = get_adset_insights(days)
        if adsets:
            print_adset_table(adsets)
        else:
            print("  No ad set data available")

    if args.ads or args.creative:
        ads = get_ad_insights(days)
        if ads:
            print_ad_table(ads)
        else:
            print("  No ad data available")

    if args.audience:
        breakdowns = get_audience_breakdowns(days)
        print_audience_breakdowns(breakdowns)

    if args.sync:
        sync_all_data(days)

    if args.export:
        campaigns = get_campaigns_insights(days)
        export_path = Path(args.export)
        export_to_csv(campaigns, export_path)


if __name__ == "__main__":
    main()

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "python-dotenv",
# ]
# ///
"""
Meta Ads Campaign Publisher (Marketing API)

Publishes ad campaigns to Meta Ads Manager. Creates campaigns, ad sets,
creatives, and ads — all in PAUSED state for manual review before activation.

Usage:
    uv run scripts/meta-ads-publish.py --setup                  # Credential setup guide
    uv run scripts/meta-ads-publish.py --check                  # Verify API access
    uv run scripts/meta-ads-publish.py --upload-images DIR      # Upload images, get hashes
    uv run scripts/meta-ads-publish.py --publish CONFIG.json    # Publish full campaign (PAUSED)
    uv run scripts/meta-ads-publish.py --list                   # List campaigns
    uv run scripts/meta-ads-publish.py --status CAMPAIGN_ID     # Campaign hierarchy status
    uv run scripts/meta-ads-publish.py --pause CAMPAIGN_ID      # Pause campaign
    uv run scripts/meta-ads-publish.py --resume CAMPAIGN_ID     # Resume (activate) campaign

Environment variables (or .env file):
    META_ADS_ACCESS_TOKEN - System User token with ads_management permission
    META_ADS_ACCOUNT_ID   - Ad account ID (format: act_XXXXXXXXX)
"""

import argparse
import json
import os
import sys
import time
from datetime import datetime, timezone
from pathlib import Path

import requests
from dotenv import load_dotenv

# Load environment variables from current working directory
PROJECT_ROOT = Path.cwd()
load_dotenv(PROJECT_ROOT / ".env")

ACCESS_TOKEN = os.getenv("META_ADS_ACCESS_TOKEN", "")
ACCOUNT_ID = os.getenv("META_ADS_ACCOUNT_ID", "")

API_BASE = "https://graph.facebook.com/v21.0"


# ---------------------------------------------------------------------------
# API helpers
# ---------------------------------------------------------------------------

def api_request(
    method: str,
    endpoint: str,
    params: dict | None = None,
    data: dict | None = None,
    files: dict | None = None,
    max_retries: int = 5,
) -> dict | None:
    """Unified API handler with rate limiting, Meta error parsing, exponential backoff."""
    params = params or {}
    params["access_token"] = ACCESS_TOKEN

    url = f"{API_BASE}/{endpoint}"

    for attempt in range(max_retries):
        try:
            response = requests.request(
                method, url, params=params, data=data, files=files, timeout=60
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
                print(f"  Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue

            if response.status_code not in (200, 201):
                error = response.json().get("error", {})
                error_msg = error.get("message", response.text[:300])
                error_code = error.get("code", "")
                error_subcode = error.get("error_subcode", "")

                # Transient errors — retry
                if error_code in (1, 2, 4, 17):
                    wait = 2 ** attempt
                    print(f"  Transient API error (code {error_code}). Retrying in {wait}s...")
                    time.sleep(wait)
                    continue

                print(f"  API Error [{error_code}]: {error_msg}")
                if error_subcode:
                    print(f"  Subcode: {error_subcode}")
                return None

            return response.json()

        except requests.RequestException as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"  Request error: {e}. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                print(f"  Request failed after {max_retries} attempts: {e}")
                return None

    return None


# ---------------------------------------------------------------------------
# Image upload
# ---------------------------------------------------------------------------

def upload_image(image_path: Path) -> str | None:
    """Upload a single image and return its hash."""
    print(f"  Uploading {image_path.name}...")

    with open(image_path, "rb") as f:
        result = api_request(
            "POST",
            f"{ACCOUNT_ID}/adimages",
            files={"filename": (image_path.name, f)},
        )

    if result and "images" in result:
        # Response: {"images": {"filename": {"hash": "...", "url": "..."}}}
        for _name, img_data in result["images"].items():
            image_hash = img_data.get("hash")
            print(f"    Hash: {image_hash}")
            return image_hash

    print(f"    Failed to upload {image_path.name}")
    return None


def upload_images_from_directory(directory: Path) -> dict:
    """Upload all images from a directory. Returns {filename: image_hash}."""
    image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
    image_files = sorted(
        p for p in directory.iterdir()
        if p.suffix.lower() in image_extensions and p.is_file()
    )

    if not image_files:
        print(f"  No images found in {directory}")
        return {}

    print(f"Uploading {len(image_files)} images from {directory}...")

    hashes = {}
    for img_path in image_files:
        h = upload_image(img_path)
        if h:
            hashes[img_path.name] = h

    print(f"  Uploaded {len(hashes)}/{len(image_files)} images")
    return hashes


# ---------------------------------------------------------------------------
# Campaign creation
# ---------------------------------------------------------------------------

def create_campaign(name: str, objective: str = "OUTCOME_SALES") -> str | None:
    """Create a campaign in PAUSED state. Returns campaign ID."""
    print(f"Creating campaign: {name}")

    result = api_request(
        "POST",
        f"{ACCOUNT_ID}/campaigns",
        data={
            "name": name,
            "objective": objective,
            "status": "PAUSED",
            "special_ad_categories": "[]",
        },
    )

    if result and "id" in result:
        campaign_id = result["id"]
        print(f"  Campaign ID: {campaign_id}")
        return campaign_id

    return None


def create_adset(
    campaign_id: str,
    name: str,
    daily_budget: int,
    targeting: dict,
    optimization_goal: str = "OFFSITE_CONVERSIONS",
    billing_event: str = "IMPRESSIONS",
    bid_strategy: str = "LOWEST_COST_WITHOUT_CAP",
    pixel_id: str | None = None,
) -> str | None:
    """Create an ad set in PAUSED state. daily_budget is in cents."""
    print(f"Creating ad set: {name} (${daily_budget / 100:.2f}/day)")

    data = {
        "campaign_id": campaign_id,
        "name": name,
        "daily_budget": str(daily_budget),
        "optimization_goal": optimization_goal,
        "billing_event": billing_event,
        "bid_strategy": bid_strategy,
        "targeting": json.dumps(targeting),
        "status": "PAUSED",
    }

    if pixel_id:
        data["promoted_object"] = json.dumps({"pixel_id": pixel_id})

    result = api_request("POST", f"{ACCOUNT_ID}/adsets", data=data)

    if result and "id" in result:
        adset_id = result["id"]
        print(f"  Ad Set ID: {adset_id}")
        return adset_id

    return None


def create_creative(
    name: str,
    image_hashes: list[str],
    primary_texts: list[str],
    headlines: list[str],
    descriptions: list[str],
    link_url: str,
    call_to_action_type: str = "SHOP_NOW",
    url_parameters: str = "",
    page_id: str | None = None,
) -> str | None:
    """Create an Advantage+ creative with asset_feed_spec for flexible format."""
    print(f"Creating creative: {name}")

    # Build asset_feed_spec for Advantage+ Creative
    images = [{"hash": h} for h in image_hashes]
    bodies = [{"text": t} for t in primary_texts]
    titles = [{"text": h} for h in headlines]
    descs = [{"text": d} for d in descriptions]
    link_urls = [{"website_url": link_url}]

    cta = [{"type": call_to_action_type}]

    asset_feed_spec = {
        "images": images,
        "bodies": bodies,
        "titles": titles,
        "descriptions": descs,
        "link_urls": link_urls,
        "call_to_action_types": cta,
        "ad_formats": ["SINGLE_IMAGE"],
    }

    if url_parameters:
        asset_feed_spec["link_urls"] = [
            {"website_url": link_url, "display_url": link_url}
        ]

    data = {
        "name": name,
        "asset_feed_spec": json.dumps(asset_feed_spec),
        "degrees_of_freedom_spec": json.dumps({
            "creative_features_spec": {
                "standard_enhancements": {"enroll_status": "OPT_IN"}
            }
        }),
    }

    if url_parameters:
        data["url_tags"] = url_parameters

    if page_id:
        data["object_story_spec"] = json.dumps({
            "page_id": page_id,
        })

    result = api_request("POST", f"{ACCOUNT_ID}/adcreatives", data=data)

    if result and "id" in result:
        creative_id = result["id"]
        print(f"  Creative ID: {creative_id}")
        return creative_id

    return None


def create_ad(name: str, adset_id: str, creative_id: str) -> str | None:
    """Create an ad linking creative to ad set. PAUSED state."""
    print(f"Creating ad: {name}")

    result = api_request(
        "POST",
        f"{ACCOUNT_ID}/ads",
        data={
            "name": name,
            "adset_id": adset_id,
            "creative": json.dumps({"creative_id": creative_id}),
            "status": "PAUSED",
        },
    )

    if result and "id" in result:
        ad_id = result["id"]
        print(f"  Ad ID: {ad_id}")
        return ad_id

    return None


# ---------------------------------------------------------------------------
# Config validation & orchestration
# ---------------------------------------------------------------------------

def validate_config(config: dict) -> list[str]:
    """Pre-publish validation. Returns list of error messages (empty = valid)."""
    errors = []

    # Campaign
    campaign = config.get("campaign", {})
    if not campaign.get("name"):
        errors.append("campaign.name is required")

    # Ad sets
    adsets = config.get("adsets", [])
    if not adsets:
        errors.append("At least one ad set is required")

    for i, adset in enumerate(adsets):
        if not adset.get("name"):
            errors.append(f"adsets[{i}].name is required")
        budget = adset.get("daily_budget", 0)
        if budget < 100:
            errors.append(f"adsets[{i}].daily_budget must be >= 100 cents ($1.00)")
        if not adset.get("targeting"):
            errors.append(f"adsets[{i}].targeting is required")

    # Creative
    creative = config.get("creative", {})
    if not creative.get("primary_texts"):
        errors.append("creative.primary_texts is required (at least 1)")
    if not creative.get("headlines"):
        errors.append("creative.headlines is required (at least 1)")
    if not creative.get("link_url"):
        errors.append("creative.link_url is required")
    if not creative.get("images_directory") and not creative.get("image_hashes"):
        errors.append("creative.images_directory or creative.image_hashes is required")

    return errors


def publish_from_config(config_path: Path) -> bool:
    """Orchestrate full campaign publish from JSON config."""
    print(f"Loading config: {config_path}")

    with open(config_path) as f:
        config = json.load(f)

    # Validate
    errors = validate_config(config)
    if errors:
        print("\nConfig validation failed:")
        for err in errors:
            print(f"  - {err}")
        return False

    campaign_cfg = config["campaign"]
    adsets_cfg = config["adsets"]
    creative_cfg = config["creative"]

    print(f"\n{'='*60}")
    print("PUBLISHING CAMPAIGN")
    print(f"{'='*60}")
    print(f"  Campaign: {campaign_cfg['name']}")
    print(f"  Ad Sets:  {len(adsets_cfg)}")
    print(f"  Status:   All created PAUSED")
    print(f"{'='*60}\n")

    # Step 1: Upload images
    image_hashes = creative_cfg.get("image_hashes", [])
    if not image_hashes and creative_cfg.get("images_directory"):
        img_dir = Path(creative_cfg["images_directory"])
        if not img_dir.is_absolute():
            img_dir = config_path.parent / img_dir
        hash_map = upload_images_from_directory(img_dir)
        image_hashes = list(hash_map.values())

    if not image_hashes:
        print("Error: No images available for creative")
        return False

    # Step 2: Create campaign
    campaign_id = create_campaign(
        name=campaign_cfg["name"],
        objective=campaign_cfg.get("objective", "OUTCOME_SALES"),
    )
    if not campaign_id:
        return False

    # Step 3: Create creative
    creative_id = create_creative(
        name=f"{campaign_cfg['name']}-creative",
        image_hashes=image_hashes,
        primary_texts=creative_cfg["primary_texts"],
        headlines=creative_cfg["headlines"],
        descriptions=creative_cfg.get("descriptions", []),
        link_url=creative_cfg["link_url"],
        call_to_action_type=creative_cfg.get("call_to_action_type", "SHOP_NOW"),
        url_parameters=creative_cfg.get("url_parameters", ""),
        page_id=creative_cfg.get("page_id"),
    )
    if not creative_id:
        return False

    # Step 4: Create ad sets + ads
    for adset_cfg in adsets_cfg:
        adset_id = create_adset(
            campaign_id=campaign_id,
            name=adset_cfg["name"],
            daily_budget=adset_cfg["daily_budget"],
            targeting=adset_cfg["targeting"],
            optimization_goal=adset_cfg.get("optimization_goal", "OFFSITE_CONVERSIONS"),
            billing_event=adset_cfg.get("billing_event", "IMPRESSIONS"),
            bid_strategy=adset_cfg.get("bid_strategy", "LOWEST_COST_WITHOUT_CAP"),
            pixel_id=adset_cfg.get("pixel_id"),
        )
        if not adset_id:
            print(f"  Warning: Failed to create ad set '{adset_cfg['name']}'")
            continue

        ad_id = create_ad(
            name=f"{adset_cfg['name']}-ad",
            adset_id=adset_id,
            creative_id=creative_id,
        )
        if not ad_id:
            print(f"  Warning: Failed to create ad for '{adset_cfg['name']}'")

    # Summary
    print(f"\n{'='*60}")
    print("PUBLISH COMPLETE")
    print(f"{'='*60}")
    print(f"  Campaign ID: {campaign_id}")
    print(f"  Status: PAUSED (review in Ads Manager before activating)")
    print(f"\n  To activate:")
    print(f"    uv run scripts/meta-ads-publish.py --resume {campaign_id}")
    print(f"{'='*60}")

    return True


# ---------------------------------------------------------------------------
# Campaign management
# ---------------------------------------------------------------------------

def list_campaigns() -> None:
    """List all campaigns with status, spend, dates."""
    print("Fetching campaigns...")

    result = api_request(
        "GET",
        f"{ACCOUNT_ID}/campaigns",
        params={
            "fields": "id,name,status,effective_status,objective,daily_budget,lifetime_budget,start_time,created_time",
            "limit": 50,
        },
    )

    if not result or not result.get("data"):
        print("  No campaigns found")
        return

    campaigns = result["data"]

    print(f"\n{'='*90}")
    print("META ADS CAMPAIGNS")
    print(f"{'='*90}")
    print(f"\n{'Name':<35} {'Status':<12} {'Objective':<20} {'ID':<20}")
    print(f"{'-'*35} {'-'*12} {'-'*20} {'-'*20}")

    for c in campaigns:
        name = c.get("name", "")[:34]
        status = c.get("effective_status", c.get("status", ""))
        objective = c.get("objective", "")
        cid = c.get("id", "")
        print(f"{name:<35} {status:<12} {objective:<20} {cid:<20}")

    print(f"\n  Total: {len(campaigns)} campaigns")
    print(f"{'='*90}")


def campaign_status(campaign_id: str) -> None:
    """Show campaign hierarchy: campaign → ad sets → ads."""
    print(f"Fetching status for campaign {campaign_id}...")

    # Campaign
    campaign = api_request(
        "GET",
        campaign_id,
        params={"fields": "id,name,status,effective_status,objective,daily_budget,created_time"},
    )
    if not campaign:
        print("  Campaign not found")
        return

    print(f"\n{'='*70}")
    print(f"CAMPAIGN: {campaign.get('name')}")
    print(f"{'='*70}")
    print(f"  ID:        {campaign.get('id')}")
    print(f"  Status:    {campaign.get('effective_status', campaign.get('status'))}")
    print(f"  Objective: {campaign.get('objective')}")
    print(f"  Created:   {campaign.get('created_time', 'N/A')}")

    # Ad sets
    adsets = api_request(
        "GET",
        f"{campaign_id}/adsets",
        params={
            "fields": "id,name,status,effective_status,daily_budget,optimization_goal,targeting",
            "limit": 50,
        },
    )

    if adsets and adsets.get("data"):
        print(f"\n  Ad Sets ({len(adsets['data'])}):")
        for adset in adsets["data"]:
            budget = int(adset.get("daily_budget", 0)) / 100
            print(f"    - {adset['name']} [{adset.get('effective_status', adset.get('status'))}] ${budget:.2f}/day")
            print(f"      ID: {adset['id']}")

            # Ads under this ad set
            ads = api_request(
                "GET",
                f"{adset['id']}/ads",
                params={
                    "fields": "id,name,status,effective_status,creative",
                    "limit": 50,
                },
            )
            if ads and ads.get("data"):
                for ad in ads["data"]:
                    print(f"      Ad: {ad['name']} [{ad.get('effective_status', ad.get('status'))}] ID: {ad['id']}")

    print(f"\n{'='*70}")


def toggle_campaign_status(campaign_id: str, status: str) -> None:
    """Pause or resume a campaign."""
    action = "Pausing" if status == "PAUSED" else "Activating"
    print(f"{action} campaign {campaign_id}...")

    result = api_request(
        "POST",
        campaign_id,
        data={"status": status},
    )

    if result and result.get("success"):
        print(f"  Campaign {campaign_id} is now {status}")
    else:
        print(f"  Failed to update campaign status")


# ---------------------------------------------------------------------------
# Check & setup
# ---------------------------------------------------------------------------

def check_credentials() -> None:
    """Verify API access and show account info."""
    print("Checking Meta Ads API access...\n")

    result = api_request(
        "GET",
        ACCOUNT_ID,
        params={"fields": "id,name,account_status,currency,timezone_name,amount_spent,balance"},
    )

    if not result:
        print("Failed to access ad account. Check your credentials.")
        print("\nRun with --setup for configuration instructions:")
        print("  uv run scripts/meta-ads-publish.py --setup")
        sys.exit(1)

    status_map = {
        1: "ACTIVE",
        2: "DISABLED",
        3: "UNSETTLED",
        7: "PENDING_RISK_REVIEW",
        8: "PENDING_SETTLEMENT",
        9: "IN_GRACE_PERIOD",
        100: "PENDING_CLOSURE",
        101: "CLOSED",
    }

    account_status = status_map.get(result.get("account_status", 0), "UNKNOWN")
    spent = int(result.get("amount_spent", 0)) / 100

    print(f"  Account:  {result.get('name', 'N/A')}")
    print(f"  ID:       {result.get('id')}")
    print(f"  Status:   {account_status}")
    print(f"  Currency: {result.get('currency', 'N/A')}")
    print(f"  Timezone: {result.get('timezone_name', 'N/A')}")
    print(f"  Spent:    ${spent:,.2f}")
    print(f"\n  API access verified successfully.")


def print_setup_guide() -> None:
    """Print credential setup instructions."""
    print("""
META ADS PUBLISH SETUP GUIDE
=============================

To use this script, you need:
1. META_ADS_ACCESS_TOKEN - System User token with ads_management permission
2. META_ADS_ACCOUNT_ID   - Ad account ID (format: act_XXXXXXXXX)

STEP 1: Create a System User in Business Manager
-------------------------------------------------
1. Go to business.facebook.com/settings
2. Navigate to Users > System Users
3. Click "Add" to create a new System User
4. Set role to "Admin" (needed for ad management)

STEP 2: Generate an Access Token
---------------------------------
1. Click on the System User you created
2. Click "Generate New Token"
3. Select your app
4. Select these permissions:
   - ads_management (required - create/edit campaigns)
   - ads_read (required - read campaign data)
   - pages_read_engagement (for page-linked ads)
5. Click "Generate Token"
6. Copy and save the token securely

   Note: System User tokens don't expire (unlike user tokens).

STEP 3: Get Your Ad Account ID
-------------------------------
1. Go to business.facebook.com/settings
2. Navigate to Accounts > Ad Accounts
3. Your account ID is shown (format: act_XXXXXXXXX)
4. Make sure the System User is assigned to this ad account

STEP 4: Add to .env
--------------------
META_ADS_ACCESS_TOKEN=your_system_user_token
META_ADS_ACCOUNT_ID=act_XXXXXXXXX

STEP 5: Verify
--------------
uv run scripts/meta-ads-publish.py --check

CONFIG FILE FORMAT
==================
Create a JSON config to publish a full campaign:

{
  "campaign": {
    "name": "my-campaign-name",
    "objective": "OUTCOME_SALES"
  },
  "adsets": [
    {
      "name": "Broad-25-54",
      "daily_budget": 7500,
      "targeting": {
        "age_min": 25,
        "age_max": 54,
        "genders": [0],
        "geo_locations": {"countries": ["US"]},
        "publisher_platforms": ["facebook", "instagram"]
      },
      "optimization_goal": "OFFSITE_CONVERSIONS"
    }
  ],
  "creative": {
    "images_directory": "./path/to/images/",
    "primary_texts": ["Your primary text 1", "Your primary text 2"],
    "headlines": ["Headline 1", "Headline 2"],
    "descriptions": ["Description 1"],
    "link_url": "https://yoursite.com/landing-page",
    "url_parameters": "utm_source=meta&utm_medium=paid-social&utm_campaign=my-campaign",
    "call_to_action_type": "SHOP_NOW"
  }
}

Budget is in CENTS (7500 = $75.00/day).
All objects are created PAUSED. Review in Ads Manager before activating.
""")


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(
        description="Meta Ads Campaign Publisher",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  uv run scripts/meta-ads-publish.py --setup
  uv run scripts/meta-ads-publish.py --check
  uv run scripts/meta-ads-publish.py --upload-images ./ads/images/
  uv run scripts/meta-ads-publish.py --publish campaign-config.json
  uv run scripts/meta-ads-publish.py --list
  uv run scripts/meta-ads-publish.py --status 12345678
  uv run scripts/meta-ads-publish.py --pause 12345678
  uv run scripts/meta-ads-publish.py --resume 12345678
        """,
    )

    parser.add_argument("--setup", action="store_true", help="Show setup guide")
    parser.add_argument("--check", action="store_true", help="Verify API access")
    parser.add_argument("--upload-images", metavar="DIR", help="Upload images from directory")
    parser.add_argument("--publish", metavar="CONFIG", help="Publish campaign from JSON config")
    parser.add_argument("--list", action="store_true", help="List campaigns")
    parser.add_argument("--status", metavar="CAMPAIGN_ID", help="Show campaign hierarchy status")
    parser.add_argument("--pause", metavar="CAMPAIGN_ID", help="Pause a campaign")
    parser.add_argument("--resume", metavar="CAMPAIGN_ID", help="Resume (activate) a campaign")

    args = parser.parse_args()

    if args.setup:
        print_setup_guide()
        return

    # All other commands need credentials
    if not ACCESS_TOKEN or not ACCOUNT_ID:
        print("Error: Missing Meta Ads credentials")
        print("\nRequired environment variables:")
        print("  META_ADS_ACCESS_TOKEN - System User token")
        print("  META_ADS_ACCOUNT_ID   - Ad account ID (act_XXXXXXXXX)")
        print("\nRun with --setup for configuration instructions:")
        print("  uv run scripts/meta-ads-publish.py --setup")
        sys.exit(1)

    if args.check:
        check_credentials()
    elif args.upload_images:
        img_dir = Path(args.upload_images)
        if not img_dir.is_dir():
            print(f"Error: {img_dir} is not a directory")
            sys.exit(1)
        hashes = upload_images_from_directory(img_dir)
        if hashes:
            print(f"\nImage hashes (for use in config):")
            print(json.dumps(hashes, indent=2))
    elif args.publish:
        config_path = Path(args.publish)
        if not config_path.exists():
            print(f"Error: Config file not found: {config_path}")
            sys.exit(1)
        success = publish_from_config(config_path)
        if not success:
            sys.exit(1)
    elif args.list:
        list_campaigns()
    elif args.status:
        campaign_status(args.status)
    elif args.pause:
        toggle_campaign_status(args.pause, "PAUSED")
    elif args.resume:
        toggle_campaign_status(args.resume, "ACTIVE")
    else:
        # Default: list campaigns
        if ACCESS_TOKEN and ACCOUNT_ID:
            list_campaigns()
        else:
            parser.print_help()


if __name__ == "__main__":
    main()