whale-code 6.4.0

package/dist/server/handlers/meta-ads.js

@@ -0,0 +1,2279 @@
+/**
+ * Meta Ads Handler — campaign/ad set/ad CRUD + publish to Meta Graph API.
+ *
+ * V2 features added:
+ * - Reporting breakdowns (age, gender, placement, device, region)
+ * - Ad preview URLs
+ * - Custom audiences (website, customer list, lookalike)
+ * - Lead forms (instant form creation + lead retrieval)
+ * - Conversion tracking (pixels, custom conversions)
+ * - Ad rules / automation (auto-pause, auto-budget)
+ * - Ad scheduling / dayparting
+ * - Placement control (Feed, Stories, Reels, etc.)
+ * - Frequency capping
+ * - Campaign Budget Optimization (CBO)
+ * - Carousel ads (multi-card)
+ * - Dynamic creative (multi-asset optimization)
+ * - Reach estimation / audience insights
+ *
+ * Lessons baked in from live testing against Meta Marketing API v21:
+ * - Budget lives on ad sets, NOT campaigns (unless CBO is enabled)
+ * - is_adset_budget_sharing_enabled: false required on campaign publish (non-CBO)
+ * - bid_strategy always required on ad set publish (even LOWEST_COST)
+ * - targeting_automation.advantage_audience: 0 required (Advantage+ flag)
+ * - DRAFT status invalid for Meta — always mapped to PAUSED
+ * - special_ad_categories only used at publish time (not a DB column)
+ * - Video URLs uploaded to Meta during publish → video_id
+ * - Image URLs uploaded to Meta during publish → image_hash
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const META_API_VERSION = "v21.0";
+const META_BASE = `https://graph.facebook.com/${META_API_VERSION}`;
+/** Valid optimization goals per campaign objective (Meta Marketing API v21). */
+const VALID_GOALS = {
+    OUTCOME_AWARENESS: ["REACH", "IMPRESSIONS", "AD_RECALL_LIFT", "THRUPLAY"],
+    OUTCOME_TRAFFIC: ["LINK_CLICKS", "LANDING_PAGE_VIEWS", "REACH", "IMPRESSIONS"],
+    OUTCOME_ENGAGEMENT: ["THRUPLAY", "POST_ENGAGEMENT", "VIDEO_VIEWS", "REACH"],
+    OUTCOME_LEADS: ["LEAD_GENERATION", "LINK_CLICKS", "QUALITY_LEAD", "REACH"],
+    OUTCOME_APP_PROMOTION: ["APP_INSTALLS", "LINK_CLICKS", "APP_EVENTS", "VALUE"],
+    OUTCOME_SALES: ["OFFSITE_CONVERSIONS", "LINK_CLICKS", "VALUE", "REACH"],
+};
+/** Default optimization goal per objective. */
+function defaultGoal(objective) {
+    return VALID_GOALS[objective]?.[0] ?? "LINK_CLICKS";
+}
+/** Validate goal against objective, falling back to the best default. */
+function validateGoal(goal, objective) {
+    const valid = VALID_GOALS[objective];
+    if (!valid)
+        return goal;
+    return valid.includes(goal) ? goal : valid[0];
+}
+/** Billing event depends on optimization goal. */
+function billingEvent(goal) {
+    return goal === "THRUPLAY" ? "THRUPLAY" : "IMPRESSIONS";
+}
+/** Map any status to Meta-valid status. Meta only accepts ACTIVE/PAUSED/DELETED/ARCHIVED. */
+function metaStatus(status) {
+    if (!status || status === "DRAFT")
+        return "PAUSED";
+    return status;
+}
+// ============================================================================
+// GRAPH API — low-level Meta helpers
+// ============================================================================
+/** Real Meta IDs are purely numeric. Local/Supabase IDs contain non-digit chars. */
+function isLocalId(id) {
+    if (!id)
+        return true;
+    return /[^0-9]/.test(id);
+}
+/** RFC 3986 percent-encode. */
+function enc(v) {
+    return encodeURIComponent(v);
+}
+/** Build form-encoded body from params object + access_token. */
+function formBody(params, token) {
+    const parts = [`access_token=${enc(token)}`];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === null || v === undefined)
+            continue;
+        parts.push(`${k}=${enc(typeof v === "object" ? JSON.stringify(v) : String(v))}`);
+    }
+    return parts.join("&");
+}
+/**
+ * Parse Meta API error responses into human-readable messages.
+ * Extracts error_user_msg when available (much better than raw JSON).
+ */
+function parseMetaError(body, path, status) {
+    try {
+        const json = JSON.parse(body);
+        const err = json.error || {};
+        const userMsg = err.error_user_msg || err.message || "Unknown error";
+        const code = err.code ? ` (code ${err.code})` : "";
+        return `Meta API ${path}: ${userMsg}${code}`;
+    }
+    catch {
+        return `Meta API ${path}: ${status} — ${body.slice(0, 300)}`;
+    }
+}
+/** GET from Meta Graph API with auto-pagination. */
+async function graphGet(path, fields, token, extra) {
+    let url = `${META_BASE}/${path}?fields=${fields}&access_token=${enc(token)}&limit=200`;
+    if (extra)
+        url += `&${extra}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(parseMetaError(body, path, res.status));
+    }
+    const page1 = (await res.json());
+    // Single-object response — return as-is
+    if (!Array.isArray(page1.data))
+        return page1;
+    // List response — paginate up to 20 pages
+    const all = [...page1.data];
+    let next = page1.paging?.next;
+    let pages = 1;
+    while (next && pages < 20) {
+        const r = await fetch(next);
+        if (!r.ok)
+            break;
+        const j = (await r.json());
+        if (Array.isArray(j.data))
+            all.push(...j.data);
+        next = j.paging?.next;
+        pages++;
+    }
+    return { data: all };
+}
+/** POST to Meta Graph API with form encoding. */
+async function graphPost(path, params, token) {
+    const res = await fetch(`${META_BASE}/${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: formBody(params, token),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(parseMetaError(body, path, res.status));
+    }
+    return (await res.json());
+}
+/** DELETE from Meta Graph API. */
+async function graphDelete(path, token) {
+    const res = await fetch(`${META_BASE}/${path}?access_token=${enc(token)}`, {
+        method: "DELETE",
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(parseMetaError(body, path, res.status));
+    }
+    return (await res.json());
+}
+// ============================================================================
+// CREDENTIALS
+// ============================================================================
+async function getIntegration(sb, storeId) {
+    const { data, error } = await sb
+        .from("meta_integrations")
+        .select("access_token_encrypted, ad_account_id, page_id, pixel_id, instagram_business_id, token_expires_at, status")
+        .eq("store_id", storeId)
+        .limit(1)
+        .single();
+    if (error || !data?.access_token_encrypted || !data?.ad_account_id) {
+        throw new Error("Meta not connected. Go to Settings → Meta Connection to link your account.");
+    }
+    // Warn if token is expired (but still return it — some operations may work with refresh)
+    if (data.token_expires_at) {
+        const expiresAt = new Date(data.token_expires_at);
+        if (expiresAt < new Date()) {
+            throw new Error(`Meta access token expired at ${expiresAt.toISOString()}. Reconnect in the CRM app (Settings → Meta Connection).`);
+        }
+    }
+    return {
+        accessToken: data.access_token_encrypted,
+        adAccountId: data.ad_account_id,
+        pageId: data.page_id || null,
+        pixelId: data.pixel_id || null,
+        instagramAccountId: data.instagram_business_id || null,
+        tokenExpiresAt: data.token_expires_at || null,
+    };
+}
+/** Page Access Token cache (user token → page token). Avoids re-fetching every call. */
+const pageTokenCache = new Map();
+/**
+ * Exchange user access token for a Page Access Token.
+ * Required for lead forms, page-level APIs, and some creative operations.
+ * Cached for 5 minutes.
+ */
+async function getPageToken(int) {
+    if (!int.pageId)
+        throw new Error("No Facebook Page linked. Add page_id in Meta Connection settings.");
+    const cacheKey = `${int.pageId}:${int.accessToken.slice(-10)}`;
+    const cached = pageTokenCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < 300_000)
+        return cached.token;
+    const result = await graphGet(int.pageId, "access_token", int.accessToken);
+    const pageToken = result.access_token;
+    if (!pageToken)
+        throw new Error("Could not get Page Access Token. Ensure your token has pages_manage_ads permission.");
+    pageTokenCache.set(cacheKey, { token: pageToken, fetchedAt: Date.now() });
+    // Evict old entries
+    if (pageTokenCache.size > 20)
+        pageTokenCache.delete([...pageTokenCache.keys()][0]);
+    return pageToken;
+}
+// ============================================================================
+// TARGETING BUILDER — smart resolution from natural language
+// ============================================================================
+async function resolveAudienceIds(sb, ids) {
+    if (!ids.length)
+        return [];
+    const { data } = await sb
+        .from("meta_audiences")
+        .select("id, meta_audience_id")
+        .in("id", ids);
+    return (data || [])
+        .filter((r) => r.meta_audience_id)
+        .map((r) => ({ id: r.meta_audience_id }));
+}
+/**
+ * Resolve natural-language location strings to Meta geo_locations.
+ * Accepts: ["Charlotte, NC", "US", "New York", "90210"]
+ * Returns: { countries: [...], cities: [...], regions: [...], zips: [...] }
+ */
+async function resolveLocations(int, locations) {
+    const geo = {};
+    const countries = [];
+    const regions = [];
+    const cities = [];
+    const zips = [];
+    for (const loc of locations) {
+        const trimmed = loc.trim();
+        if (!trimmed)
+            continue;
+        // 2-letter country code
+        if (/^[A-Z]{2}$/i.test(trimmed)) {
+            countries.push(trimmed.toUpperCase());
+            continue;
+        }
+        // ZIP code (5-digit US)
+        if (/^\d{5}$/.test(trimmed)) {
+            try {
+                const url = `${META_BASE}/search?type=adgeolocation&q=${enc(trimmed)}&location_types=["zip"]&access_token=${enc(int.accessToken)}&limit=1`;
+                const res = await fetch(url);
+                if (res.ok) {
+                    const json = (await res.json());
+                    const results = json.data;
+                    if (results?.[0]?.key) {
+                        zips.push({ key: results[0].key });
+                        continue;
+                    }
+                }
+            }
+            catch { /* fall through to general search */ }
+            zips.push({ key: trimmed });
+            continue;
+        }
+        // General search — let Meta figure out if it's a city, region, etc.
+        try {
+            const url = `${META_BASE}/search?type=adgeolocation&q=${enc(trimmed)}&access_token=${enc(int.accessToken)}&limit=3`;
+            const res = await fetch(url);
+            if (!res.ok)
+                continue;
+            const json = (await res.json());
+            const results = json.data;
+            if (!results?.length)
+                continue;
+            const best = results[0];
+            const key = best.key;
+            const type = best.type;
+            switch (type) {
+                case "country":
+                    countries.push(key);
+                    break;
+                case "region":
+                    regions.push({ key });
+                    break;
+                case "city":
+                    cities.push({ key, radius: 25, distance_unit: "mile" });
+                    break;
+                case "zip":
+                    zips.push({ key });
+                    break;
+                case "geo_market":
+                    (geo.geo_markets || (geo.geo_markets = []));
+                    geo.geo_markets.push({ key });
+                    break;
+                default:
+                    if (key)
+                        cities.push({ key, radius: 25, distance_unit: "mile" });
+            }
+        }
+        catch { /* skip unresolvable locations */ }
+    }
+    if (countries.length)
+        geo.countries = countries;
+    if (regions.length)
+        geo.regions = regions;
+    if (cities.length)
+        geo.cities = cities;
+    if (zips.length)
+        geo.zips = zips;
+    // Fallback: if nothing resolved, default to US
+    if (!Object.keys(geo).length)
+        geo.countries = ["US"];
+    return geo;
+}
+/**
+ * Resolve natural-language interest strings to Meta interest IDs.
+ * Accepts: ["streetwear", "hip hop music", "cannabis"]
+ */
+async function resolveInterests(int, interests) {
+    const resolved = [];
+    for (const term of interests) {
+        const trimmed = term.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const url = `${META_BASE}/search?type=adinterest&q=${enc(trimmed)}&access_token=${enc(int.accessToken)}&limit=3`;
+            const res = await fetch(url);
+            if (!res.ok)
+                continue;
+            const json = (await res.json());
+            const results = json.data;
+            if (results?.length) {
+                const best = results[0];
+                if (best.id && best.name) {
+                    resolved.push({ id: String(best.id), name: best.name });
+                }
+            }
+        }
+        catch { /* skip unresolvable interests */ }
+    }
+    return resolved;
+}
+/**
+ * Convert targeting args → Meta API targeting spec.
+ * Accepts THREE formats (auto-detected).
+ */
+async function buildTargeting(sb, raw, int) {
+    const fallback = {
+        geo_locations: { countries: ["US"] },
+        targeting_automation: { advantage_audience: 0 },
+    };
+    let t;
+    if (!raw)
+        return fallback;
+    if (typeof raw === "string") {
+        try {
+            t = JSON.parse(raw);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    else {
+        t = raw;
+    }
+    // Already in Meta format (synced from Meta) — ensure advantage_audience is set
+    if (t.geo_locations) {
+        if (!t.targeting_automation)
+            t.targeting_automation = { advantage_audience: 0 };
+        return t;
+    }
+    const result = {};
+    // === LOCATIONS ===
+    const simpleLocs = t.locations;
+    if (Array.isArray(simpleLocs) && simpleLocs.length > 0 && typeof simpleLocs[0] === "string" && int) {
+        result.geo_locations = await resolveLocations(int, simpleLocs);
+    }
+    else {
+        const locs = t.locations_v2;
+        if (Array.isArray(locs) && locs.length > 0) {
+            const geo = {};
+            const countries = [];
+            const regions = [];
+            const cities = [];
+            const zips = [];
+            const markets = [];
+            for (const loc of locs) {
+                if (!loc.key || !loc.type)
+                    continue;
+                switch (loc.type) {
+                    case "country":
+                        countries.push(loc.key);
+                        break;
+                    case "region":
+                        regions.push({ key: loc.key });
+                        break;
+                    case "city":
+                        cities.push({ key: loc.key });
+                        break;
+                    case "zip":
+                        zips.push({ key: loc.key });
+                        break;
+                    case "geo_market":
+                        markets.push({ key: loc.key });
+                        break;
+                    default: countries.push(loc.key);
+                }
+            }
+            if (countries.length)
+                geo.countries = countries;
+            if (regions.length)
+                geo.regions = regions;
+            if (cities.length)
+                geo.cities = cities;
+            if (zips.length)
+                geo.zips = zips;
+            if (markets.length)
+                geo.geo_markets = markets;
+            result.geo_locations = geo;
+        }
+        else if (typeof t.locations === "string" && t.locations) {
+            result.geo_locations = { countries: t.locations.split(",").map(s => s.trim().toUpperCase()) };
+        }
+        else {
+            result.geo_locations = { countries: ["US"] };
+        }
+    }
+    // === DEMOGRAPHICS ===
+    if (t.age_min != null)
+        result.age_min = Math.max(Number(t.age_min) || 18, 13);
+    if (t.age_max != null)
+        result.age_max = Math.min(Number(t.age_max) || 65, 65);
+    if (t.genders === "male")
+        result.genders = [1];
+    else if (t.genders === "female")
+        result.genders = [2];
+    // === INTERESTS ===
+    const simpleInts = t.interests;
+    if (Array.isArray(simpleInts) && simpleInts.length > 0 && typeof simpleInts[0] === "string" && int) {
+        const resolved = await resolveInterests(int, simpleInts);
+        if (resolved.length)
+            result.flexible_spec = [{ interests: resolved }];
+    }
+    else {
+        const ints = t.interests_v2;
+        if (Array.isArray(ints) && ints.length > 0) {
+            const valid = ints.filter(i => i.id && i.name).map(i => ({ id: i.id, name: i.name }));
+            if (valid.length)
+                result.flexible_spec = [{ interests: valid }];
+        }
+    }
+    // === CUSTOM AUDIENCES ===
+    if (typeof t.custom_audiences === "string" && t.custom_audiences) {
+        const resolved = await resolveAudienceIds(sb, t.custom_audiences.split(",").map(s => s.trim()));
+        if (resolved.length)
+            result.custom_audiences = resolved;
+    }
+    else if (Array.isArray(t.custom_audiences)) {
+        result.custom_audiences = t.custom_audiences;
+    }
+    // === EXCLUDED AUDIENCES ===
+    if (typeof t.excluded_custom_audiences === "string" && t.excluded_custom_audiences) {
+        const resolved = await resolveAudienceIds(sb, t.excluded_custom_audiences.split(",").map(s => s.trim()));
+        if (resolved.length)
+            result.excluded_custom_audiences = resolved;
+    }
+    // === Required: Advantage audience flag ===
+    result.targeting_automation = { advantage_audience: 0 };
+    // === PUBLISHER PLATFORMS (placement control) ===
+    if (Array.isArray(t.publisher_platforms)) {
+        result.publisher_platforms = t.publisher_platforms;
+    }
+    if (Array.isArray(t.facebook_positions)) {
+        result.facebook_positions = t.facebook_positions;
+    }
+    if (Array.isArray(t.instagram_positions)) {
+        result.instagram_positions = t.instagram_positions;
+    }
+    if (Array.isArray(t.audience_network_positions)) {
+        result.audience_network_positions = t.audience_network_positions;
+    }
+    if (Array.isArray(t.messenger_positions)) {
+        result.messenger_positions = t.messenger_positions;
+    }
+    return result;
+}
+// ============================================================================
+// MEDIA UPLOAD
+// ============================================================================
+/** Upload image URL to Meta → returns image_hash. */
+async function uploadImage(int, url) {
+    try {
+        const r = await graphPost(`${int.adAccountId}/adimages`, { url }, int.accessToken);
+        const images = r.images;
+        if (images) {
+            const first = Object.values(images)[0];
+            if (first?.hash)
+                return first.hash;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Upload video URL to Meta → returns video_id.
+ * Meta's async video upload: POST the URL, poll until ready.
+ */
+async function uploadVideo(int, videoUrl) {
+    let videoId = null;
+    const errors = [];
+    // --- Strategy 1: file_url via query params ---
+    try {
+        const url = `${META_BASE}/${int.adAccountId}/advideos?access_token=${enc(int.accessToken)}&file_url=${enc(videoUrl)}`;
+        const res = await fetch(url, { method: "POST" });
+        if (res.ok) {
+            const json = (await res.json());
+            videoId = json.id;
+        }
+        else {
+            errors.push(`advideos/file_url: ${(await res.text()).slice(0, 200)}`);
+        }
+    }
+    catch (e) {
+        errors.push(`advideos/file_url: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // --- Strategy 2: binary upload via FormData ---
+    if (!videoId) {
+        try {
+            const downloadRes = await fetch(videoUrl);
+            if (!downloadRes.ok)
+                throw new Error(`download failed: ${downloadRes.status}`);
+            const blob = await downloadRes.blob();
+            const form = new FormData();
+            form.append("access_token", int.accessToken);
+            form.append("source", blob, "video.mp4");
+            const res = await fetch(`${META_BASE}/${int.adAccountId}/advideos`, { method: "POST", body: form });
+            if (res.ok) {
+                const json = (await res.json());
+                videoId = json.id;
+            }
+            else {
+                errors.push(`advideos/binary: ${(await res.text()).slice(0, 200)}`);
+            }
+        }
+        catch (e) {
+            errors.push(`advideos/binary: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // --- Strategy 3: Page video upload ---
+    if (!videoId && int.pageId) {
+        try {
+            const downloadRes = await fetch(videoUrl);
+            if (!downloadRes.ok)
+                throw new Error(`download failed: ${downloadRes.status}`);
+            const blob = await downloadRes.blob();
+            const form = new FormData();
+            form.append("access_token", int.accessToken);
+            form.append("source", blob, "video.mp4");
+            form.append("published", "false");
+            form.append("no_story", "true");
+            const res = await fetch(`${META_BASE}/${int.pageId}/videos`, { method: "POST", body: form });
+            if (res.ok) {
+                const json = (await res.json());
+                videoId = json.id;
+            }
+            else {
+                errors.push(`page/videos: ${(await res.text()).slice(0, 200)}`);
+            }
+        }
+        catch (e) {
+            errors.push(`page/videos: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (!videoId) {
+        throw new Error(`Video upload failed. Tried 3 strategies:\n${errors.join("\n")}`);
+    }
+    // Poll for processing (up to 90s)
+    for (let i = 0; i < 18; i++) {
+        await new Promise(resolve => setTimeout(resolve, 5000));
+        try {
+            const s = await graphGet(videoId, "status", int.accessToken);
+            const phase = s.status?.processing_phase;
+            if (phase === "ready" || phase === "complete")
+                return videoId;
+            if (phase === "error")
+                throw new Error(`Meta video processing failed for ${videoId}`);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.includes("processing failed"))
+                throw e;
+        }
+    }
+    return videoId;
+}
+// ============================================================================
+// OBJECT STORY SPEC
+// ============================================================================
+function buildStorySpec(creative, pageId, imageHash, metaVideoId, carouselHashes) {
+    // --- CAROUSEL ---
+    if (carouselHashes && carouselHashes.length > 0) {
+        const childAttachments = carouselHashes.map(({ hash, videoId, card }) => {
+            const child = {};
+            if (card.link_url)
+                child.link = card.link_url;
+            if (card.headline)
+                child.name = card.headline;
+            if (card.description)
+                child.description = card.description;
+            if (videoId) {
+                child.video_id = videoId;
+                if (hash)
+                    child.image_hash = hash;
+            }
+            else if (hash) {
+                child.image_hash = hash;
+            }
+            else if (card.image_url) {
+                child.picture = card.image_url;
+            }
+            if (card.call_to_action && card.link_url) {
+                child.call_to_action = { type: card.call_to_action, value: { link: card.link_url } };
+            }
+            return child;
+        });
+        const linkData = {
+            child_attachments: childAttachments,
+            multi_share_optimized: true,
+        };
+        if (creative?.link_url)
+            linkData.link = creative.link_url;
+        if (creative?.body)
+            linkData.message = creative.body;
+        return { page_id: pageId, link_data: linkData };
+    }
+    const isVideo = metaVideoId || creative?.object_type?.toUpperCase() === "VIDEO";
+    if (isVideo && (metaVideoId || creative?.video_id)) {
+        const vid = { video_id: metaVideoId || creative.video_id };
+        if (creative?.body)
+            vid.message = creative.body;
+        if (creative?.title)
+            vid.title = creative.title;
+        if (imageHash)
+            vid.image_hash = imageHash;
+        else if (creative?.image_url)
+            vid.image_url = creative.image_url;
+        if (creative?.call_to_action && creative?.link_url) {
+            vid.call_to_action = { type: creative.call_to_action, value: { link: creative.link_url } };
+        }
+        return { page_id: pageId, video_data: vid };
+    }
+    const link = {};
+    if (creative?.link_url)
+        link.link = creative.link_url;
+    if (creative?.body)
+        link.message = creative.body;
+    if (creative?.title)
+        link.name = creative.title;
+    if (imageHash)
+        link.image_hash = imageHash;
+    else if (creative?.image_url)
+        link.picture = creative.image_url;
+    if (creative?.call_to_action && creative?.link_url) {
+        link.call_to_action = { type: creative.call_to_action, value: { link: creative.link_url } };
+    }
+    return { page_id: pageId, link_data: link };
+}
+// ============================================================================
+// PUBLISH PIPELINE
+// ============================================================================
+async function publishCampaign(sb, storeId, campaignId) {
+    const { data: c, error } = await sb
+        .from("meta_campaigns").select("*").eq("id", campaignId).single();
+    if (error || !c)
+        throw new Error(`Campaign not found: ${campaignId}`);
+    // Already published — skip
+    if (!isLocalId(c.meta_campaign_id))
+        return { metaCampaignId: c.meta_campaign_id };
+    const int = await getIntegration(sb, storeId);
+    const params = {
+        name: c.name || "Campaign",
+        objective: c.objective || "OUTCOME_AWARENESS",
+        status: "PAUSED",
+        special_ad_categories: ["NONE"],
+    };
+    // CBO: budget at campaign level
+    if (c.is_cbo) {
+        params.is_adset_budget_sharing_enabled = true;
+        if (c.daily_budget > 0)
+            params.daily_budget = Math.round(c.daily_budget * 100);
+        if (c.lifetime_budget > 0)
+            params.lifetime_budget = Math.round(c.lifetime_budget * 100);
+        if (c.campaign_bid_strategy)
+            params.bid_strategy = c.campaign_bid_strategy;
+    }
+    else {
+        params.is_adset_budget_sharing_enabled = false;
+    }
+    if (c.start_time)
+        params.start_time = c.start_time;
+    if (c.stop_time)
+        params.stop_time = c.stop_time;
+    const result = await graphPost(`${int.adAccountId}/campaigns`, params, int.accessToken);
+    const metaId = result.id;
+    if (!metaId)
+        throw new Error("Meta returned no campaign ID");
+    await sb.from("meta_campaigns").update({
+        meta_campaign_id: metaId,
+        meta_account_id: int.adAccountId,
+        last_synced_at: new Date().toISOString(),
+    }).eq("id", campaignId);
+    return { metaCampaignId: metaId };
+}
+async function publishAdSet(sb, storeId, adSetId) {
+    const { data: as_, error } = await sb
+        .from("meta_ad_sets").select("*").eq("id", adSetId).single();
+    if (error || !as_)
+        throw new Error(`Ad set not found: ${adSetId}`);
+    if (!isLocalId(as_.meta_ad_set_id)) {
+        return { metaAdSetId: as_.meta_ad_set_id, metaCampaignId: "" };
+    }
+    const int = await getIntegration(sb, storeId);
+    // Cascade: publish parent campaign if needed
+    const campaignUUID = as_.meta_campaign_id;
+    if (!campaignUUID)
+        throw new Error("Ad set has no campaign reference");
+    const { data: camp } = await sb
+        .from("meta_campaigns").select("*").eq("id", campaignUUID).single();
+    if (!camp)
+        throw new Error(`Parent campaign not found: ${campaignUUID}`);
+    let metaCampaignId = camp.meta_campaign_id || "";
+    if (isLocalId(metaCampaignId)) {
+        const pub = await publishCampaign(sb, storeId, campaignUUID);
+        metaCampaignId = pub.metaCampaignId;
+    }
+    // CBO detection: check if campaign has budget on Meta
+    const isCBO = !!camp.is_cbo;
+    let campaignHasCBO = isCBO;
+    if (!isCBO) {
+        try {
+            const mc = await graphGet(metaCampaignId, "daily_budget,lifetime_budget,bid_strategy", int.accessToken);
+            if (mc.daily_budget || mc.lifetime_budget) {
+                campaignHasCBO = true;
+                if (mc.bid_strategy && mc.bid_strategy !== "LOWEST_COST_WITHOUT_CAP") {
+                    await graphPost(metaCampaignId, { bid_strategy: "LOWEST_COST_WITHOUT_CAP" }, int.accessToken);
+                }
+            }
+        }
+        catch { /* proceed without CBO check */ }
+    }
+    const optGoal = validateGoal(as_.optimization_goal || "LINK_CLICKS", camp.objective || "OUTCOME_AWARENESS");
+    // Build targeting with placement control
+    const targetingSpec = await buildTargeting(sb, as_.targeting, int);
+    // Merge placement config from ad set columns into targeting
+    if (as_.publisher_platforms) {
+        const pp = typeof as_.publisher_platforms === "string"
+            ? JSON.parse(as_.publisher_platforms) : as_.publisher_platforms;
+        if (Array.isArray(pp) && pp.length)
+            targetingSpec.publisher_platforms = pp;
+    }
+    if (as_.facebook_positions) {
+        const fp = typeof as_.facebook_positions === "string"
+            ? JSON.parse(as_.facebook_positions) : as_.facebook_positions;
+        if (Array.isArray(fp) && fp.length)
+            targetingSpec.facebook_positions = fp;
+    }
+    if (as_.instagram_positions) {
+        const ip = typeof as_.instagram_positions === "string"
+            ? JSON.parse(as_.instagram_positions) : as_.instagram_positions;
+        if (Array.isArray(ip) && ip.length)
+            targetingSpec.instagram_positions = ip;
+    }
+    if (as_.audience_network_positions) {
+        const anp = typeof as_.audience_network_positions === "string"
+            ? JSON.parse(as_.audience_network_positions) : as_.audience_network_positions;
+        if (Array.isArray(anp) && anp.length)
+            targetingSpec.audience_network_positions = anp;
+    }
+    if (as_.messenger_positions) {
+        const mp = typeof as_.messenger_positions === "string"
+            ? JSON.parse(as_.messenger_positions) : as_.messenger_positions;
+        if (Array.isArray(mp) && mp.length)
+            targetingSpec.messenger_positions = mp;
+    }
+    const params = {
+        campaign_id: metaCampaignId,
+        name: as_.name || "Ad Set",
+        billing_event: billingEvent(optGoal),
+        optimization_goal: optGoal,
+        status: "PAUSED",
+        targeting: targetingSpec,
+    };
+    if (!campaignHasCBO) {
+        // Ad set level budget + bid strategy (always required for non-CBO)
+        if (as_.daily_budget > 0)
+            params.daily_budget = Math.round(as_.daily_budget * 100);
+        if (as_.lifetime_budget > 0)
+            params.lifetime_budget = Math.round(as_.lifetime_budget * 100);
+        const bs = as_.bid_strategy || "LOWEST_COST_WITHOUT_CAP";
+        params.bid_strategy = bs;
+        if (bs !== "LOWEST_COST_WITHOUT_CAP" && as_.bid_amount > 0) {
+            params.bid_amount = Math.round(as_.bid_amount * 100);
+        }
+    }
+    if (as_.start_time)
+        params.start_time = as_.start_time;
+    if (as_.end_time) {
+        params.end_time = as_.end_time;
+    }
+    else if (!campaignHasCBO && as_.lifetime_budget > 0) {
+        params.end_time = new Date(Date.now() + 30 * 86400000).toISOString();
+    }
+    // --- Ad scheduling / dayparting ---
+    if (as_.adset_schedule) {
+        const schedule = typeof as_.adset_schedule === "string"
+            ? JSON.parse(as_.adset_schedule) : as_.adset_schedule;
+        if (Array.isArray(schedule) && schedule.length) {
+            params.adset_schedule = schedule;
+            // Dayparting requires lifetime budget or pacing_type USER_DEFINED
+            params.pacing_type = ["day_parting"];
+        }
+    }
+    // --- Frequency capping ---
+    if (as_.frequency_control_specs) {
+        const fcs = typeof as_.frequency_control_specs === "string"
+            ? JSON.parse(as_.frequency_control_specs) : as_.frequency_control_specs;
+        if (Array.isArray(fcs) && fcs.length) {
+            params.frequency_control_specs = fcs;
+        }
+    }
+    // --- Promoted object (conversion tracking) ---
+    if (as_.promoted_object) {
+        const po = typeof as_.promoted_object === "string"
+            ? JSON.parse(as_.promoted_object) : as_.promoted_object;
+        if (po && typeof po === "object" && Object.keys(po).length) {
+            params.promoted_object = po;
+        }
+    }
+    // --- Dynamic creative flag ---
+    if (as_.is_dynamic_creative) {
+        params.is_dynamic_creative = true;
+    }
+    const result = await graphPost(`${int.adAccountId}/adsets`, params, int.accessToken);
+    const metaId = result.id;
+    if (!metaId)
+        throw new Error("Meta returned no ad set ID");
+    await sb.from("meta_ad_sets").update({
+        meta_ad_set_id: metaId,
+        last_synced_at: new Date().toISOString(),
+    }).eq("id", adSetId);
+    return { metaAdSetId: metaId, metaCampaignId };
+}
+async function publishAd(sb, storeId, adId) {
+    const { data: ad, error } = await sb
+        .from("meta_ads").select("*").eq("id", adId).single();
+    if (error || !ad)
+        throw new Error(`Ad not found: ${adId}`);
+    if (!isLocalId(ad.meta_ad_id)) {
+        return { metaAdId: ad.meta_ad_id, creativeId: ad.creative_id || "", metaAdSetId: "", metaCampaignId: "" };
+    }
+    const int = await getIntegration(sb, storeId);
+    // Cascade: publish parent ad set (which cascades to campaign)
+    const adSetUUID = ad.meta_ad_set_id;
+    if (!adSetUUID)
+        throw new Error("Ad has no ad set reference");
+    const { data: adSet } = await sb
+        .from("meta_ad_sets").select("*").eq("id", adSetUUID).single();
+    if (!adSet)
+        throw new Error(`Parent ad set not found: ${adSetUUID}`);
+    let metaAdSetId = adSet.meta_ad_set_id || "";
+    let metaCampaignId = "";
+    if (isLocalId(metaAdSetId)) {
+        const pub = await publishAdSet(sb, storeId, adSetUUID);
+        metaAdSetId = pub.metaAdSetId;
+        metaCampaignId = pub.metaCampaignId;
+    }
+    if (!int.pageId)
+        throw new Error("No Facebook Page linked. Add page_id in Meta Connection settings.");
+    const creative = (ad.creative || {});
+    const isCarousel = Array.isArray(creative.carousel_cards) && creative.carousel_cards.length > 0;
+    const isDynamic = !!creative.asset_feed_spec;
+    const wantsVideo = !!(creative.video_url || creative.video_id || creative.object_type?.toUpperCase() === "VIDEO");
+    let imageHash = null;
+    let metaVideoId = null;
+    let videoWarning = null;
+    // --- CAROUSEL: upload each card's media ---
+    if (isCarousel) {
+        const carouselHashes = [];
+        for (const card of creative.carousel_cards) {
+            let cardHash = null;
+            let cardVideoId = null;
+            if (card.video_url) {
+                try {
+                    cardVideoId = await uploadVideo(int, card.video_url);
+                }
+                catch { /* skip video, fall to image */ }
+                if (card.image_url)
+                    cardHash = await uploadImage(int, card.image_url);
+            }
+            else if (card.image_url) {
+                cardHash = await uploadImage(int, card.image_url);
+            }
+            carouselHashes.push({ hash: cardHash, videoId: cardVideoId, card });
+        }
+        const oss = buildStorySpec(creative, int.pageId, null, null, carouselHashes);
+        const crResult = await graphPost(`${int.adAccountId}/adcreatives`, { name: `${ad.name || "Ad"} Creative`, object_story_spec: oss }, int.accessToken);
+        const creativeId = crResult.id;
+        if (!creativeId)
+            throw new Error("Meta returned no creative ID");
+        const adResult = await graphPost(`${int.adAccountId}/ads`, {
+            name: ad.name || "Ad",
+            adset_id: metaAdSetId,
+            creative: { creative_id: creativeId },
+            status: metaStatus(ad.status),
+        }, int.accessToken);
+        const metaAdId = adResult.id;
+        if (!metaAdId)
+            throw new Error("Meta returned no ad ID");
+        await sb.from("meta_ads").update({
+            meta_ad_id: metaAdId,
+            creative_id: creativeId,
+            last_synced_at: new Date().toISOString(),
+        }).eq("id", adId);
+        return { metaAdId, creativeId, metaAdSetId, metaCampaignId };
+    }
+    // --- DYNAMIC CREATIVE: asset_feed_spec ---
+    if (isDynamic && creative.asset_feed_spec) {
+        const spec = creative.asset_feed_spec;
+        // Upload images in the asset feed
+        if (Array.isArray(spec.images)) {
+            for (const img of spec.images) {
+                if (img.url && !img.hash) {
+                    const hash = await uploadImage(int, img.url);
+                    if (hash) {
+                        img.hash = hash;
+                        delete img.url;
+                    }
+                }
+            }
+        }
+        const crParams = {
+            name: `${ad.name || "Ad"} Dynamic Creative`,
+            asset_feed_spec: spec,
+            object_story_spec: { page_id: int.pageId, link_data: { link: creative.link_url || "" } },
+        };
+        const crResult = await graphPost(`${int.adAccountId}/adcreatives`, crParams, int.accessToken);
+        const creativeId = crResult.id;
+        if (!creativeId)
+            throw new Error("Meta returned no creative ID");
+        const adResult = await graphPost(`${int.adAccountId}/ads`, {
+            name: ad.name || "Ad",
+            adset_id: metaAdSetId,
+            creative: { creative_id: creativeId },
+            status: metaStatus(ad.status),
+        }, int.accessToken);
+        const metaAdId = adResult.id;
+        if (!metaAdId)
+            throw new Error("Meta returned no ad ID");
+        await sb.from("meta_ads").update({
+            meta_ad_id: metaAdId,
+            creative_id: creativeId,
+            last_synced_at: new Date().toISOString(),
+        }).eq("id", adId);
+        return { metaAdId, creativeId, metaAdSetId, metaCampaignId };
+    }
+    // --- STANDARD (single image/video) ---
+    if (wantsVideo && creative.video_url) {
+        try {
+            metaVideoId = await uploadVideo(int, creative.video_url);
+        }
+        catch (e) {
+            videoWarning = `Video upload failed (${e instanceof Error ? e.message.slice(0, 150) : "unknown"}). Published as image ad instead. To fix: add ads_management and pages_manage_posts permissions to your Meta App.`;
+        }
+        if (creative.image_url) {
+            imageHash = await uploadImage(int, creative.image_url);
+        }
+    }
+    else if (wantsVideo && creative.video_id) {
+        metaVideoId = creative.video_id;
+        if (creative.image_url)
+            imageHash = await uploadImage(int, creative.image_url);
+    }
+    else if (creative.image_url) {
+        imageHash = await uploadImage(int, creative.image_url);
+    }
+    // Create creative on Meta
+    const oss = buildStorySpec(creative, int.pageId, imageHash, metaVideoId);
+    const crParams = {
+        name: `${ad.name || "Ad"} Creative`,
+        object_story_spec: oss,
+    };
+    // Attach lead form if specified
+    if (creative.lead_form_id) {
+        const ossObj = oss;
+        if (ossObj.link_data) {
+            ossObj.link_data = { ...ossObj.link_data, lead_gen_form_id: creative.lead_form_id };
+        }
+        crParams.object_story_spec = ossObj;
+    }
+    const crResult = await graphPost(`${int.adAccountId}/adcreatives`, crParams, int.accessToken);
+    const creativeId = crResult.id;
+    if (!creativeId)
+        throw new Error("Meta returned no creative ID");
+    // Create ad
+    const adResult = await graphPost(`${int.adAccountId}/ads`, {
+        name: ad.name || "Ad",
+        adset_id: metaAdSetId,
+        creative: { creative_id: creativeId },
+        status: metaStatus(ad.status),
+    }, int.accessToken);
+    const metaAdId = adResult.id;
+    if (!metaAdId)
+        throw new Error("Meta returned no ad ID");
+    await sb.from("meta_ads").update({
+        meta_ad_id: metaAdId,
+        creative_id: creativeId,
+        last_synced_at: new Date().toISOString(),
+    }).eq("id", adId);
+    return {
+        metaAdId, creativeId, metaAdSetId, metaCampaignId,
+        ...(videoWarning && { warning: videoWarning }),
+    };
+}
+// ============================================================================
+// MAIN HANDLER
+// ============================================================================
+export async function handleMetaAds(sb, args, storeId) {
+    if (!storeId)
+        return { success: false, error: "store_id required" };
+    const action = args.action;
+    try {
+        switch (action) {
+            // ==================================================================
+            // CREATE
+            // ==================================================================
+            case "create_campaign": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const row = {
+                    store_id: storeId,
+                    meta_campaign_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_account_id: "draft",
+                    name,
+                    objective: args.objective || "OUTCOME_AWARENESS",
+                    status: "DRAFT",
+                };
+                if (args.daily_budget)
+                    row.daily_budget = Number(args.daily_budget);
+                if (args.lifetime_budget)
+                    row.lifetime_budget = Number(args.lifetime_budget);
+                if (args.start_time)
+                    row.start_time = args.start_time;
+                if (args.stop_time)
+                    row.stop_time = args.stop_time;
+                // CBO support
+                if (args.is_cbo === true)
+                    row.is_cbo = true;
+                if (args.campaign_bid_strategy)
+                    row.campaign_bid_strategy = args.campaign_bid_strategy;
+                const { data, error } = await sb.from("meta_campaigns").insert(row).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            case "create_ad_set": {
+                const campaignId = args.campaign_id;
+                const name = args.name;
+                if (!campaignId)
+                    return { success: false, error: "campaign_id required" };
+                if (!name)
+                    return { success: false, error: "name required" };
+                const { data: camp } = await sb
+                    .from("meta_campaigns").select("id, objective")
+                    .eq("id", campaignId).eq("store_id", storeId).single();
+                if (!camp)
+                    return { success: false, error: `Campaign not found: ${campaignId}` };
+                const optGoal = args.optimization_goal
+                    ? validateGoal(args.optimization_goal, camp.objective || "OUTCOME_AWARENESS")
+                    : defaultGoal(camp.objective || "OUTCOME_AWARENESS");
+                const row = {
+                    store_id: storeId,
+                    meta_ad_set_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_campaign_id: campaignId,
+                    name,
+                    optimization_goal: optGoal,
+                    billing_event: billingEvent(optGoal),
+                    status: "DRAFT",
+                };
+                if (args.daily_budget)
+                    row.daily_budget = Number(args.daily_budget);
+                if (args.lifetime_budget)
+                    row.lifetime_budget = Number(args.lifetime_budget);
+                if (args.bid_strategy)
+                    row.bid_strategy = args.bid_strategy;
+                if (args.bid_amount)
+                    row.bid_amount = Number(args.bid_amount);
+                if (args.start_time)
+                    row.start_time = args.start_time;
+                if (args.end_time)
+                    row.end_time = args.end_time;
+                if (args.targeting) {
+                    row.targeting = typeof args.targeting === "string" ? args.targeting : JSON.stringify(args.targeting);
+                }
+                // V2: scheduling, placements, frequency, conversions, dynamic creative
+                if (args.adset_schedule) {
+                    row.adset_schedule = typeof args.adset_schedule === "string"
+                        ? args.adset_schedule : JSON.stringify(args.adset_schedule);
+                }
+                if (args.publisher_platforms) {
+                    row.publisher_platforms = typeof args.publisher_platforms === "string"
+                        ? args.publisher_platforms : JSON.stringify(args.publisher_platforms);
+                }
+                if (args.facebook_positions) {
+                    row.facebook_positions = typeof args.facebook_positions === "string"
+                        ? args.facebook_positions : JSON.stringify(args.facebook_positions);
+                }
+                if (args.instagram_positions) {
+                    row.instagram_positions = typeof args.instagram_positions === "string"
+                        ? args.instagram_positions : JSON.stringify(args.instagram_positions);
+                }
+                if (args.audience_network_positions) {
+                    row.audience_network_positions = typeof args.audience_network_positions === "string"
+                        ? args.audience_network_positions : JSON.stringify(args.audience_network_positions);
+                }
+                if (args.messenger_positions) {
+                    row.messenger_positions = typeof args.messenger_positions === "string"
+                        ? args.messenger_positions : JSON.stringify(args.messenger_positions);
+                }
+                if (args.frequency_control_specs) {
+                    row.frequency_control_specs = typeof args.frequency_control_specs === "string"
+                        ? args.frequency_control_specs : JSON.stringify(args.frequency_control_specs);
+                }
+                if (args.promoted_object) {
+                    row.promoted_object = typeof args.promoted_object === "string"
+                        ? args.promoted_object : JSON.stringify(args.promoted_object);
+                }
+                if (args.is_dynamic_creative === true)
+                    row.is_dynamic_creative = true;
+                const { data, error } = await sb.from("meta_ad_sets").insert(row).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            case "create_ad": {
+                const adSetId = args.ad_set_id;
+                const name = args.name;
+                if (!adSetId)
+                    return { success: false, error: "ad_set_id required" };
+                if (!name)
+                    return { success: false, error: "name required" };
+                const { data: adSet } = await sb
+                    .from("meta_ad_sets").select("id")
+                    .eq("id", adSetId).eq("store_id", storeId).single();
+                if (!adSet)
+                    return { success: false, error: `Ad set not found: ${adSetId}` };
+                const hasVideo = !!args.video_url;
+                const creative = {
+                    title: args.headline || undefined,
+                    body: args.body || undefined,
+                    image_url: args.image_url || undefined,
+                    video_url: args.video_url || undefined,
+                    link_url: args.link_url || undefined,
+                    call_to_action: args.call_to_action || "LEARN_MORE",
+                    object_type: hasVideo ? "VIDEO" : "SHARE",
+                    video_id: args.video_id || undefined,
+                };
+                // V2: carousel cards
+                if (args.carousel_cards && Array.isArray(args.carousel_cards)) {
+                    creative.carousel_cards = args.carousel_cards;
+                    creative.object_type = "SHARE";
+                }
+                // V2: dynamic creative asset feed
+                if (args.asset_feed_spec && typeof args.asset_feed_spec === "object") {
+                    creative.asset_feed_spec = args.asset_feed_spec;
+                }
+                // V2: lead form
+                if (args.lead_form_id) {
+                    creative.lead_form_id = args.lead_form_id;
+                }
+                const { data, error } = await sb.from("meta_ads").insert({
+                    store_id: storeId,
+                    meta_ad_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_ad_set_id: adSetId,
+                    name,
+                    creative,
+                    status: "DRAFT",
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            // ==================================================================
+            // CREATE FULL — campaign + ad set + ad in one call
+            // ==================================================================
+            case "create_full": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required (used as campaign name)" };
+                const objective = args.objective || "OUTCOME_AWARENESS";
+                const optGoal = args.optimization_goal
+                    ? validateGoal(args.optimization_goal, objective)
+                    : defaultGoal(objective);
+                const wantPublish = args.auto_publish === true;
+                // 1. Campaign
+                const campRow = {
+                    store_id: storeId,
+                    meta_campaign_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_account_id: "draft",
+                    name,
+                    objective,
+                    status: "DRAFT",
+                };
+                if (args.daily_budget)
+                    campRow.daily_budget = Number(args.daily_budget);
+                if (args.lifetime_budget)
+                    campRow.lifetime_budget = Number(args.lifetime_budget);
+                if (args.start_time)
+                    campRow.start_time = args.start_time;
+                if (args.stop_time)
+                    campRow.stop_time = args.stop_time;
+                if (args.is_cbo === true)
+                    campRow.is_cbo = true;
+                if (args.campaign_bid_strategy)
+                    campRow.campaign_bid_strategy = args.campaign_bid_strategy;
+                const { data: camp, error: e1 } = await sb.from("meta_campaigns")
+                    .insert(campRow).select().single();
+                if (e1)
+                    return { success: false, error: `Campaign: ${e1.message}` };
+                // 2. Ad Set
+                const adSetName = args.ad_set_name || `${name} — Ad Set`;
+                const adSetRow = {
+                    store_id: storeId,
+                    meta_ad_set_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_campaign_id: camp.id,
+                    name: adSetName,
+                    optimization_goal: optGoal,
+                    billing_event: billingEvent(optGoal),
+                    status: "DRAFT",
+                };
+                // Budget goes on ad set (unless CBO)
+                if (!campRow.is_cbo && args.daily_budget)
+                    adSetRow.daily_budget = Number(args.daily_budget);
+                if (!campRow.is_cbo && args.lifetime_budget)
+                    adSetRow.lifetime_budget = Number(args.lifetime_budget);
+                if (args.bid_strategy)
+                    adSetRow.bid_strategy = args.bid_strategy;
+                if (args.start_time)
+                    adSetRow.start_time = args.start_time;
+                if (args.end_time)
+                    adSetRow.end_time = args.end_time;
+                if (args.targeting) {
+                    adSetRow.targeting = typeof args.targeting === "string"
+                        ? args.targeting : JSON.stringify(args.targeting);
+                }
+                // V2 ad set fields
+                if (args.adset_schedule) {
+                    adSetRow.adset_schedule = typeof args.adset_schedule === "string"
+                        ? args.adset_schedule : JSON.stringify(args.adset_schedule);
+                }
+                if (args.publisher_platforms) {
+                    adSetRow.publisher_platforms = typeof args.publisher_platforms === "string"
+                        ? args.publisher_platforms : JSON.stringify(args.publisher_platforms);
+                }
+                if (args.facebook_positions) {
+                    adSetRow.facebook_positions = typeof args.facebook_positions === "string"
+                        ? args.facebook_positions : JSON.stringify(args.facebook_positions);
+                }
+                if (args.instagram_positions) {
+                    adSetRow.instagram_positions = typeof args.instagram_positions === "string"
+                        ? args.instagram_positions : JSON.stringify(args.instagram_positions);
+                }
+                if (args.frequency_control_specs) {
+                    adSetRow.frequency_control_specs = typeof args.frequency_control_specs === "string"
+                        ? args.frequency_control_specs : JSON.stringify(args.frequency_control_specs);
+                }
+                if (args.promoted_object) {
+                    adSetRow.promoted_object = typeof args.promoted_object === "string"
+                        ? args.promoted_object : JSON.stringify(args.promoted_object);
+                }
+                if (args.is_dynamic_creative === true)
+                    adSetRow.is_dynamic_creative = true;
+                const { data: adSet, error: e2 } = await sb.from("meta_ad_sets")
+                    .insert(adSetRow).select().single();
+                if (e2)
+                    return { success: false, error: `Ad set: ${e2.message}` };
+                // 3. Ad
+                const hasVideo = !!args.video_url;
+                const adName = args.ad_name || `${name} — Ad`;
+                const creative = {
+                    title: args.headline || undefined,
+                    body: args.body || undefined,
+                    image_url: args.image_url || undefined,
+                    video_url: args.video_url || undefined,
+                    link_url: args.link_url || undefined,
+                    call_to_action: args.call_to_action || "LEARN_MORE",
+                    object_type: hasVideo ? "VIDEO" : "SHARE",
+                    video_id: args.video_id || undefined,
+                };
+                if (args.carousel_cards && Array.isArray(args.carousel_cards)) {
+                    creative.carousel_cards = args.carousel_cards;
+                    creative.object_type = "SHARE";
+                }
+                if (args.asset_feed_spec && typeof args.asset_feed_spec === "object") {
+                    creative.asset_feed_spec = args.asset_feed_spec;
+                }
+                if (args.lead_form_id) {
+                    creative.lead_form_id = args.lead_form_id;
+                }
+                const { data: ad, error: e3 } = await sb.from("meta_ads").insert({
+                    store_id: storeId,
+                    meta_ad_id: `local_${crypto.randomUUID().slice(0, 8)}`,
+                    meta_ad_set_id: adSet.id,
+                    name: adName,
+                    creative,
+                    status: "DRAFT",
+                }).select().single();
+                if (e3)
+                    return { success: false, error: `Ad: ${e3.message}` };
+                // 4. Auto-publish if requested
+                if (wantPublish) {
+                    try {
+                        const pubResult = await publishAd(sb, storeId, ad.id);
+                        const { data: finalCamp } = await sb.from("meta_campaigns").select("*").eq("id", camp.id).single();
+                        const { data: finalAdSet } = await sb.from("meta_ad_sets").select("*").eq("id", adSet.id).single();
+                        const { data: finalAd } = await sb.from("meta_ads").select("*").eq("id", ad.id).single();
+                        return {
+                            success: true,
+                            published: true,
+                            data: {
+                                campaign: finalCamp,
+                                ad_set: finalAdSet,
+                                ad: finalAd,
+                                meta_ids: {
+                                    campaign_id: pubResult.metaCampaignId,
+                                    ad_set_id: pubResult.metaAdSetId,
+                                    creative_id: pubResult.creativeId,
+                                    ad_id: pubResult.metaAdId,
+                                },
+                                ...(("warning" in pubResult) && { warning: pubResult.warning }),
+                            },
+                        };
+                    }
+                    catch (pubErr) {
+                        return {
+                            success: true,
+                            published: false,
+                            data: {
+                                campaign: camp,
+                                ad_set: adSet,
+                                ad: ad,
+                                publish_error: pubErr instanceof Error ? pubErr.message : String(pubErr),
+                                hint: "Drafts created. Fix the error and retry: publish(type=ad, id=" + ad.id + ")",
+                            },
+                        };
+                    }
+                }
+                return {
+                    success: true,
+                    published: false,
+                    data: {
+                        campaign: camp,
+                        ad_set: adSet,
+                        ad: ad,
+                        hint: "Created as drafts. Set auto_publish=true to publish immediately, or call publish(type=ad, id=" + ad.id + ").",
+                    },
+                };
+            }
+            // ==================================================================
+            // READ
+            // ==================================================================
+            case "list_campaigns": {
+                let q = sb.from("meta_campaigns").select("*")
+                    .eq("store_id", storeId).order("created_at", { ascending: false });
+                if (args.status)
+                    q = q.eq("status", args.status);
+                q = q.limit(args.limit || 25);
+                const { data, error } = await q;
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, count: data?.length ?? 0, data };
+            }
+            case "list_ad_sets": {
+                let q = sb.from("meta_ad_sets").select("*")
+                    .eq("store_id", storeId).order("created_at", { ascending: false });
+                if (args.campaign_id)
+                    q = q.eq("meta_campaign_id", args.campaign_id);
+                if (args.status)
+                    q = q.eq("status", args.status);
+                q = q.limit(args.limit || 25);
+                const { data, error } = await q;
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, count: data?.length ?? 0, data };
+            }
+            case "list_ads": {
+                let q = sb.from("meta_ads").select("*")
+                    .eq("store_id", storeId).order("created_at", { ascending: false });
+                if (args.ad_set_id)
+                    q = q.eq("meta_ad_set_id", args.ad_set_id);
+                if (args.status)
+                    q = q.eq("status", args.status);
+                q = q.limit(args.limit || 25);
+                const { data, error } = await q;
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, count: data?.length ?? 0, data };
+            }
+            case "get_campaign": {
+                const id = (args.campaign_id || args.id);
+                if (!id)
+                    return { success: false, error: "campaign_id required" };
+                const { data: c, error } = await sb.from("meta_campaigns").select("*")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (error)
+                    return { success: false, error: error.message };
+                const { data: sets } = await sb.from("meta_ad_sets").select("*")
+                    .eq("meta_campaign_id", id).order("created_at", { ascending: false });
+                return { success: true, data: { ...c, ad_sets: sets || [] } };
+            }
+            case "get_ad_set": {
+                const id = (args.ad_set_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_set_id required" };
+                const { data: s, error } = await sb.from("meta_ad_sets").select("*")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (error)
+                    return { success: false, error: error.message };
+                const { data: ads } = await sb.from("meta_ads").select("*")
+                    .eq("meta_ad_set_id", id).order("created_at", { ascending: false });
+                return { success: true, data: { ...s, ads: ads || [] } };
+            }
+            case "get_ad": {
+                const id = (args.ad_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_id required" };
+                const { data, error } = await sb.from("meta_ads").select("*")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            // ==================================================================
+            // UPDATE
+            // ==================================================================
+            case "update_campaign": {
+                const id = (args.campaign_id || args.id);
+                if (!id)
+                    return { success: false, error: "campaign_id required" };
+                const u = {};
+                if (args.name !== undefined)
+                    u.name = args.name;
+                if (args.objective !== undefined)
+                    u.objective = args.objective;
+                if (args.daily_budget !== undefined)
+                    u.daily_budget = Number(args.daily_budget);
+                if (args.lifetime_budget !== undefined)
+                    u.lifetime_budget = Number(args.lifetime_budget);
+                if (args.status !== undefined)
+                    u.status = args.status;
+                if (args.start_time !== undefined)
+                    u.start_time = args.start_time;
+                if (args.stop_time !== undefined)
+                    u.stop_time = args.stop_time;
+                if (args.is_cbo !== undefined)
+                    u.is_cbo = args.is_cbo;
+                if (args.campaign_bid_strategy !== undefined)
+                    u.campaign_bid_strategy = args.campaign_bid_strategy;
+                if (!Object.keys(u).length)
+                    return { success: false, error: "No fields to update" };
+                const { data, error } = await sb.from("meta_campaigns").update(u)
+                    .eq("id", id).eq("store_id", storeId).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            case "update_ad_set": {
+                const id = (args.ad_set_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_set_id required" };
+                const u = {};
+                if (args.name !== undefined)
+                    u.name = args.name;
+                if (args.daily_budget !== undefined)
+                    u.daily_budget = Number(args.daily_budget);
+                if (args.lifetime_budget !== undefined)
+                    u.lifetime_budget = Number(args.lifetime_budget);
+                if (args.optimization_goal !== undefined)
+                    u.optimization_goal = args.optimization_goal;
+                if (args.bid_strategy !== undefined)
+                    u.bid_strategy = args.bid_strategy;
+                if (args.bid_amount !== undefined)
+                    u.bid_amount = Number(args.bid_amount);
+                if (args.status !== undefined)
+                    u.status = args.status;
+                if (args.start_time !== undefined)
+                    u.start_time = args.start_time;
+                if (args.end_time !== undefined)
+                    u.end_time = args.end_time;
+                if (args.targeting !== undefined) {
+                    u.targeting = typeof args.targeting === "string" ? args.targeting : JSON.stringify(args.targeting);
+                }
+                // V2 fields
+                if (args.adset_schedule !== undefined) {
+                    u.adset_schedule = typeof args.adset_schedule === "string"
+                        ? args.adset_schedule : JSON.stringify(args.adset_schedule);
+                }
+                if (args.publisher_platforms !== undefined) {
+                    u.publisher_platforms = typeof args.publisher_platforms === "string"
+                        ? args.publisher_platforms : JSON.stringify(args.publisher_platforms);
+                }
+                if (args.facebook_positions !== undefined) {
+                    u.facebook_positions = typeof args.facebook_positions === "string"
+                        ? args.facebook_positions : JSON.stringify(args.facebook_positions);
+                }
+                if (args.instagram_positions !== undefined) {
+                    u.instagram_positions = typeof args.instagram_positions === "string"
+                        ? args.instagram_positions : JSON.stringify(args.instagram_positions);
+                }
+                if (args.audience_network_positions !== undefined) {
+                    u.audience_network_positions = typeof args.audience_network_positions === "string"
+                        ? args.audience_network_positions : JSON.stringify(args.audience_network_positions);
+                }
+                if (args.messenger_positions !== undefined) {
+                    u.messenger_positions = typeof args.messenger_positions === "string"
+                        ? args.messenger_positions : JSON.stringify(args.messenger_positions);
+                }
+                if (args.frequency_control_specs !== undefined) {
+                    u.frequency_control_specs = typeof args.frequency_control_specs === "string"
+                        ? args.frequency_control_specs : JSON.stringify(args.frequency_control_specs);
+                }
+                if (args.promoted_object !== undefined) {
+                    u.promoted_object = typeof args.promoted_object === "string"
+                        ? args.promoted_object : JSON.stringify(args.promoted_object);
+                }
+                if (args.is_dynamic_creative !== undefined)
+                    u.is_dynamic_creative = args.is_dynamic_creative;
+                if (!Object.keys(u).length)
+                    return { success: false, error: "No fields to update" };
+                const { data, error } = await sb.from("meta_ad_sets").update(u)
+                    .eq("id", id).eq("store_id", storeId).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            case "update_ad": {
+                const id = (args.ad_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_id required" };
+                const u = {};
+                if (args.name !== undefined)
+                    u.name = args.name;
+                if (args.status !== undefined)
+                    u.status = args.status;
+                // Merge creative fields
+                if (args.headline !== undefined || args.body !== undefined || args.image_url !== undefined ||
+                    args.video_url !== undefined || args.link_url !== undefined ||
+                    args.call_to_action !== undefined || args.video_id !== undefined ||
+                    args.carousel_cards !== undefined || args.asset_feed_spec !== undefined ||
+                    args.lead_form_id !== undefined) {
+                    const { data: existing } = await sb.from("meta_ads").select("creative").eq("id", id).single();
+                    const prev = (existing?.creative || {});
+                    u.creative = {
+                        ...prev,
+                        ...(args.headline !== undefined && { title: args.headline }),
+                        ...(args.body !== undefined && { body: args.body }),
+                        ...(args.image_url !== undefined && { image_url: args.image_url }),
+                        ...(args.video_url !== undefined && { video_url: args.video_url, object_type: "VIDEO" }),
+                        ...(args.link_url !== undefined && { link_url: args.link_url }),
+                        ...(args.call_to_action !== undefined && { call_to_action: args.call_to_action }),
+                        ...(args.video_id !== undefined && { video_id: args.video_id, object_type: "VIDEO" }),
+                        ...(args.carousel_cards !== undefined && { carousel_cards: args.carousel_cards }),
+                        ...(args.asset_feed_spec !== undefined && { asset_feed_spec: args.asset_feed_spec }),
+                        ...(args.lead_form_id !== undefined && { lead_form_id: args.lead_form_id }),
+                    };
+                }
+                if (!Object.keys(u).length)
+                    return { success: false, error: "No fields to update" };
+                const { data, error } = await sb.from("meta_ads").update(u)
+                    .eq("id", id).eq("store_id", storeId).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data };
+            }
+            // ==================================================================
+            // DELETE
+            // ==================================================================
+            case "delete": {
+                const id = args.id;
+                const type = args.type;
+                if (!id)
+                    return { success: false, error: "id required" };
+                if (!type)
+                    return { success: false, error: "type required (campaign, ad_set, ad)" };
+                const table = type === "campaign" ? "meta_campaigns"
+                    : type === "ad_set" ? "meta_ad_sets"
+                        : type === "ad" ? "meta_ads" : null;
+                const metaIdCol = type === "campaign" ? "meta_campaign_id"
+                    : type === "ad_set" ? "meta_ad_set_id"
+                        : type === "ad" ? "meta_ad_id" : null;
+                if (!table || !metaIdCol)
+                    return { success: false, error: `Invalid type: ${type}` };
+                const { data: record } = await sb.from(table).select(metaIdCol).eq("id", id).single();
+                const metaId = record?.[metaIdCol];
+                let metaDeleted = false;
+                if (metaId && !isLocalId(metaId)) {
+                    const int = await getIntegration(sb, storeId);
+                    if (int) {
+                        try {
+                            await graphPost(metaId, { status: "DELETED" }, int.accessToken);
+                            metaDeleted = true;
+                        }
+                        catch (e) {
+                            console.warn(`[meta_ads] Meta delete failed for ${metaId}:`, e);
+                        }
+                    }
+                }
+                const { error } = await sb.from(table).delete().eq("id", id).eq("store_id", storeId);
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { deleted: id, type, meta_deleted: metaDeleted } };
+            }
+            // ==================================================================
+            // PUBLISH
+            // ==================================================================
+            case "publish": {
+                const type = args.type;
+                const id = args.id;
+                if (!type)
+                    return { success: false, error: "type required (campaign, ad_set, ad)" };
+                if (!id)
+                    return { success: false, error: "id required" };
+                let result;
+                switch (type) {
+                    case "campaign":
+                        result = await publishCampaign(sb, storeId, id);
+                        break;
+                    case "ad_set":
+                        result = await publishAdSet(sb, storeId, id);
+                        break;
+                    case "ad":
+                        result = await publishAd(sb, storeId, id);
+                        break;
+                    default: return { success: false, error: `Invalid type: ${type}` };
+                }
+                // Audit trail (fire-and-forget)
+                sb.from("audit_logs").insert({
+                    store_id: storeId,
+                    action: `meta_publish_${type}`,
+                    resource_type: `meta_${type === "ad_set" ? "ad_set" : type}`,
+                    resource_id: id,
+                    details: result,
+                    source: "agent_chat",
+                    severity: "info",
+                }).then(() => { });
+                return { success: true, data: result };
+            }
+            // ==================================================================
+            // SYNC — pull latest stats from Meta (with optional breakdowns)
+            // ==================================================================
+            case "sync": {
+                const id = (args.campaign_id || args.id);
+                if (!id)
+                    return { success: false, error: "campaign_id required" };
+                const { data: c } = await sb.from("meta_campaigns").select("meta_campaign_id")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (!c)
+                    return { success: false, error: `Campaign not found: ${id}` };
+                if (isLocalId(c.meta_campaign_id))
+                    return { success: false, error: "Campaign not published yet. Publish first." };
+                const int = await getIntegration(sb, storeId);
+                const stats = await graphGet(c.meta_campaign_id, "name,status,effective_status,daily_budget,lifetime_budget,budget_remaining,start_time,stop_time", int.accessToken);
+                const u = { last_synced_at: new Date().toISOString() };
+                if (stats.status)
+                    u.status = stats.status;
+                if (stats.effective_status)
+                    u.effective_status = stats.effective_status;
+                if (stats.daily_budget)
+                    u.daily_budget = Number(stats.daily_budget) / 100;
+                if (stats.lifetime_budget)
+                    u.lifetime_budget = Number(stats.lifetime_budget) / 100;
+                if (stats.budget_remaining)
+                    u.budget_remaining = Number(stats.budget_remaining) / 100;
+                // Insights (with optional breakdowns)
+                try {
+                    const breakdowns = args.breakdowns;
+                    let extra = "date_preset=maximum";
+                    if (breakdowns)
+                        extra += `&breakdowns=${enc(breakdowns)}`;
+                    const ins = await graphGet(`${c.meta_campaign_id}/insights`, "spend,impressions,clicks,reach,cpc,cpm,ctr,actions", int.accessToken, extra);
+                    const results = ins.data;
+                    if (breakdowns && results?.length) {
+                        // Return breakdown data without saving to DB (too granular)
+                        u.raw_insights = results;
+                    }
+                    else {
+                        const d = results?.[0];
+                        if (d) {
+                            if (d.spend)
+                                u.spend = Number(d.spend);
+                            if (d.impressions)
+                                u.impressions = Number(d.impressions);
+                            if (d.clicks)
+                                u.clicks = Number(d.clicks);
+                            if (d.reach)
+                                u.reach = Number(d.reach);
+                            if (d.cpc)
+                                u.cpc = Number(d.cpc);
+                            if (d.cpm)
+                                u.cpm = Number(d.cpm);
+                            if (d.ctr)
+                                u.ctr = Number(d.ctr);
+                            u.raw_insights = d;
+                        }
+                    }
+                }
+                catch { /* insights may not exist yet */ }
+                await sb.from("meta_campaigns").update(u).eq("id", id);
+                const { data: refreshed } = await sb.from("meta_campaigns").select("*").eq("id", id).single();
+                return { success: true, data: refreshed };
+            }
+            // ==================================================================
+            // INSIGHTS BREAKDOWN — detailed performance by dimension
+            // ==================================================================
+            case "insights_breakdown": {
+                const id = (args.campaign_id || args.ad_set_id || args.ad_id || args.id);
+                if (!id)
+                    return { success: false, error: "campaign_id, ad_set_id, or ad_id required" };
+                const breakdowns = args.breakdowns || "age,gender";
+                // Determine which table to look up the Meta ID
+                let metaId = null;
+                if (args.campaign_id || (!args.ad_set_id && !args.ad_id)) {
+                    const { data } = await sb.from("meta_campaigns").select("meta_campaign_id")
+                        .eq("id", id).eq("store_id", storeId).single();
+                    metaId = data?.meta_campaign_id;
+                }
+                else if (args.ad_set_id) {
+                    const { data } = await sb.from("meta_ad_sets").select("meta_ad_set_id")
+                        .eq("id", id).eq("store_id", storeId).single();
+                    metaId = data?.meta_ad_set_id;
+                }
+                else if (args.ad_id) {
+                    const { data } = await sb.from("meta_ads").select("meta_ad_id")
+                        .eq("id", id).eq("store_id", storeId).single();
+                    metaId = data?.meta_ad_id;
+                }
+                if (!metaId || isLocalId(metaId)) {
+                    return { success: false, error: "Entity not published yet. Publish first." };
+                }
+                const int = await getIntegration(sb, storeId);
+                const datePreset = args.date_preset || "last_30d";
+                const fields = args.fields || "spend,impressions,clicks,reach,cpc,cpm,ctr,actions,cost_per_action_type";
+                const extra = `breakdowns=${enc(breakdowns)}&date_preset=${enc(datePreset)}`;
+                const ins = await graphGet(`${metaId}/insights`, fields, int.accessToken, extra);
+                return { success: true, data: ins.data || [] };
+            }
+            // ==================================================================
+            // AD PREVIEW — get preview URLs
+            // ==================================================================
+            case "ad_preview": {
+                const id = (args.ad_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_id required" };
+                const { data: ad } = await sb.from("meta_ads").select("meta_ad_id")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (!ad)
+                    return { success: false, error: `Ad not found: ${id}` };
+                if (isLocalId(ad.meta_ad_id)) {
+                    return { success: false, error: "Ad not published yet. Publish first to get preview." };
+                }
+                const int = await getIntegration(sb, storeId);
+                const format = args.ad_format || "DESKTOP_FEED_STANDARD";
+                const url = `${META_BASE}/${ad.meta_ad_id}/previews?ad_format=${enc(format)}&access_token=${enc(int.accessToken)}`;
+                const res = await fetch(url);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return { success: false, error: parseMetaError(body, "previews", res.status) };
+                }
+                const json = (await res.json());
+                return { success: true, data: json.data || [] };
+            }
+            // ==================================================================
+            // CUSTOM AUDIENCES
+            // ==================================================================
+            case "create_audience": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const int = await getIntegration(sb, storeId);
+                const subtype = args.subtype || "CUSTOM";
+                const metaParams = {
+                    name,
+                    subtype,
+                    description: args.description || "",
+                    customer_file_source: args.customer_file_source || "USER_PROVIDED_ONLY",
+                };
+                // Website audience (requires pixel)
+                if (subtype === "WEBSITE") {
+                    const pixelForAudience = args.pixel_id || int.pixelId;
+                    if (!pixelForAudience)
+                        return { success: false, error: "pixel_id required for website audiences (none configured — set one in Settings → Meta Connection)" };
+                    metaParams.rule = args.rule || { inclusions: { operator: "or", rules: [{ event_sources: [{ id: pixelForAudience, type: "pixel" }], retention_seconds: (Number(args.retention_days) || 30) * 86400 }] } };
+                    if (args.retention_days)
+                        metaParams.retention_days = Number(args.retention_days);
+                    if (args.prefill)
+                        metaParams.prefill = true;
+                }
+                // Engagement audience
+                if (subtype === "ENGAGEMENT") {
+                    metaParams.rule = args.rule;
+                }
+                const result = await graphPost(`${int.adAccountId}/customaudiences`, metaParams, int.accessToken);
+                const metaAudienceId = result.id;
+                // Save to local DB
+                const { data, error } = await sb.from("meta_audiences").insert({
+                    store_id: storeId,
+                    meta_audience_id: metaAudienceId || null,
+                    name,
+                    description: args.description || null,
+                    audience_type: "custom",
+                    subtype,
+                    rule: args.rule || null,
+                    customer_file_source: args.customer_file_source || null,
+                    retention_days: args.retention_days ? Number(args.retention_days) : null,
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { ...data, meta_audience_id: metaAudienceId } };
+            }
+            case "list_audiences": {
+                // Fetch from Meta for live data
+                const int = await getIntegration(sb, storeId);
+                const fields = "id,name,description,subtype,approximate_count,delivery_status,operation_status,time_created,time_updated";
+                const result = await graphGet(`${int.adAccountId}/customaudiences`, fields, int.accessToken);
+                // Also sync to local DB
+                const audiences = (result.data || []);
+                for (const aud of audiences) {
+                    await sb.from("meta_audiences").upsert({
+                        store_id: storeId,
+                        meta_audience_id: aud.id,
+                        name: aud.name,
+                        description: aud.description || null,
+                        subtype: aud.subtype || null,
+                        approximate_count: aud.approximate_count ? Number(aud.approximate_count) : null,
+                        updated_at: new Date().toISOString(),
+                    }, { onConflict: "meta_audience_id", ignoreDuplicates: false }).then(() => { });
+                }
+                return { success: true, count: audiences.length, data: audiences };
+            }
+            case "get_audience": {
+                const id = (args.audience_id || args.id);
+                if (!id)
+                    return { success: false, error: "audience_id required" };
+                // Check if it's a local UUID or Meta ID
+                let metaId = id;
+                if (isLocalId(id)) {
+                    const { data } = await sb.from("meta_audiences").select("meta_audience_id")
+                        .eq("id", id).single();
+                    if (!data?.meta_audience_id)
+                        return { success: false, error: `Audience not found: ${id}` };
+                    metaId = data.meta_audience_id;
+                }
+                const int = await getIntegration(sb, storeId);
+                const fields = "id,name,description,subtype,approximate_count,delivery_status,operation_status,rule,lookalike_spec,time_created,time_updated";
+                const result = await graphGet(metaId, fields, int.accessToken);
+                return { success: true, data: result };
+            }
+            case "delete_audience": {
+                const id = (args.audience_id || args.id);
+                if (!id)
+                    return { success: false, error: "audience_id required" };
+                let metaId = id;
+                if (isLocalId(id)) {
+                    const { data } = await sb.from("meta_audiences").select("meta_audience_id")
+                        .eq("id", id).single();
+                    if (data?.meta_audience_id)
+                        metaId = data.meta_audience_id;
+                }
+                const int = await getIntegration(sb, storeId);
+                let metaDeleted = false;
+                if (!isLocalId(metaId)) {
+                    try {
+                        await graphDelete(metaId, int.accessToken);
+                        metaDeleted = true;
+                    }
+                    catch { /* continue */ }
+                }
+                // Delete from local DB
+                if (isLocalId(id)) {
+                    await sb.from("meta_audiences").delete().eq("id", id);
+                }
+                else {
+                    await sb.from("meta_audiences").delete().eq("meta_audience_id", id).eq("store_id", storeId);
+                }
+                return { success: true, data: { deleted: id, meta_deleted: metaDeleted } };
+            }
+            case "create_lookalike": {
+                const sourceId = (args.source_audience_id || args.source_id);
+                if (!sourceId)
+                    return { success: false, error: "source_audience_id required (Meta audience ID)" };
+                const int = await getIntegration(sb, storeId);
+                const name = args.name || `Lookalike — ${sourceId}`;
+                const country = args.country || "US";
+                const ratio = Number(args.ratio) || 0.01; // 1% default
+                // Resolve source Meta ID if local UUID given
+                let sourceMetaId = sourceId;
+                if (isLocalId(sourceId)) {
+                    const { data } = await sb.from("meta_audiences").select("meta_audience_id")
+                        .eq("id", sourceId).single();
+                    if (!data?.meta_audience_id)
+                        return { success: false, error: `Source audience not found: ${sourceId}` };
+                    sourceMetaId = data.meta_audience_id;
+                }
+                const result = await graphPost(`${int.adAccountId}/customaudiences`, {
+                    name,
+                    subtype: "LOOKALIKE",
+                    origin_audience_id: sourceMetaId,
+                    lookalike_spec: JSON.stringify({
+                        type: "custom_ratio",
+                        ratio,
+                        country,
+                    }),
+                }, int.accessToken);
+                const metaAudienceId = result.id;
+                // Save to local DB
+                const { data, error } = await sb.from("meta_audiences").insert({
+                    store_id: storeId,
+                    meta_audience_id: metaAudienceId || null,
+                    name,
+                    audience_type: "lookalike",
+                    subtype: "LOOKALIKE",
+                    lookalike_spec: { source_id: sourceMetaId, country, ratio },
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { ...data, meta_audience_id: metaAudienceId } };
+            }
+            // ==================================================================
+            // LEAD FORMS
+            // ==================================================================
+            case "create_lead_form": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const int = await getIntegration(sb, storeId);
+                if (!int.pageId)
+                    return { success: false, error: "No Facebook Page linked. Required for lead forms." };
+                const questions = args.questions || [
+                    { type: "FULL_NAME" },
+                    { type: "EMAIL" },
+                    { type: "PHONE" },
+                ];
+                const privacyUrl = args.privacy_policy_url || "https://example.com/privacy";
+                const metaParams = {
+                    name,
+                    questions: JSON.stringify(questions),
+                    privacy_policy_url: privacyUrl,
+                    privacy_policy: JSON.stringify({ url: privacyUrl, link_text: "Privacy Policy" }),
+                    follow_up_action_url: privacyUrl,
+                    follow_up_action_text: "Visit Website",
+                };
+                if (args.context_card) {
+                    metaParams.context_card = JSON.stringify(args.context_card);
+                }
+                if (args.thank_you_page) {
+                    metaParams.thank_you_page = JSON.stringify(args.thank_you_page);
+                }
+                const pageToken = await getPageToken(int);
+                const result = await graphPost(`${int.pageId}/leadgen_forms`, metaParams, pageToken);
+                const metaFormId = result.id;
+                const { data, error } = await sb.from("meta_lead_forms").insert({
+                    store_id: storeId,
+                    meta_form_id: metaFormId || null,
+                    page_id: int.pageId,
+                    name,
+                    questions,
+                    privacy_policy: args.privacy_policy_url ? { url: args.privacy_policy_url } : null,
+                    context_card: args.context_card || null,
+                    thank_you_page: args.thank_you_page || null,
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { ...data, meta_form_id: metaFormId } };
+            }
+            case "list_lead_forms": {
+                const int = await getIntegration(sb, storeId);
+                if (!int.pageId)
+                    return { success: false, error: "No Facebook Page linked." };
+                const pageToken = await getPageToken(int);
+                const fields = "id,name,status,questions,privacy_policy_url,created_time,leads_count";
+                const result = await graphGet(`${int.pageId}/leadgen_forms`, fields, pageToken);
+                return { success: true, data: result.data || [] };
+            }
+            case "get_leads": {
+                const formId = (args.form_id || args.lead_form_id);
+                if (!formId)
+                    return { success: false, error: "form_id required (Meta lead form ID)" };
+                // Resolve local UUID to Meta ID
+                let metaFormId = formId;
+                if (isLocalId(formId)) {
+                    const { data } = await sb.from("meta_lead_forms").select("meta_form_id")
+                        .eq("id", formId).single();
+                    if (!data?.meta_form_id)
+                        return { success: false, error: `Lead form not found: ${formId}` };
+                    metaFormId = data.meta_form_id;
+                }
+                const int = await getIntegration(sb, storeId);
+                const pageToken = await getPageToken(int);
+                const fields = "id,created_time,field_data,ad_id,ad_name,campaign_id,campaign_name";
+                const result = await graphGet(`${metaFormId}/leads`, fields, pageToken);
+                return { success: true, data: result.data || [] };
+            }
+            // ==================================================================
+            // CONVERSION TRACKING — Pixels & Custom Conversions
+            // ==================================================================
+            case "list_pixels": {
+                const int = await getIntegration(sb, storeId);
+                const fields = "id,name,code,last_fired_time,is_unavailable,creation_time";
+                const result = await graphGet(`${int.adAccountId}/adspixels`, fields, int.accessToken);
+                const pixels = (result.data || []);
+                // Sync to local DB
+                for (const px of pixels) {
+                    await sb.from("meta_pixels").upsert({
+                        store_id: storeId,
+                        meta_pixel_id: px.id,
+                        name: px.name,
+                        code: px.code || null,
+                        last_fired_time: px.last_fired_time || null,
+                        is_active: !px.is_unavailable,
+                    }, { onConflict: "meta_pixel_id", ignoreDuplicates: false }).then(() => { });
+                }
+                return { success: true, count: pixels.length, data: pixels };
+            }
+            case "create_pixel": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const int = await getIntegration(sb, storeId);
+                // 1. Create pixel on Meta
+                const result = await graphPost(`${int.adAccountId}/adspixels`, { name }, int.accessToken);
+                const metaPixelId = result.id;
+                if (!metaPixelId)
+                    return { success: false, error: "Meta did not return a pixel ID" };
+                // 2. Fetch full pixel info (including code snippet)
+                const pixelInfo = await graphGet(metaPixelId, "id,name,code,last_fired_time", int.accessToken);
+                // 3. Save to local DB
+                const { data, error } = await sb.from("meta_pixels").insert({
+                    store_id: storeId,
+                    meta_pixel_id: metaPixelId,
+                    name,
+                    code: pixelInfo.code || null,
+                    is_active: true,
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return {
+                    success: true,
+                    data: { ...data, meta_pixel_id: metaPixelId, code: pixelInfo.code || null },
+                    message: `Pixel "${name}" created on Meta (ID: ${metaPixelId}). Install the pixel code on your website to start tracking.`,
+                };
+            }
+            case "delete_pixel": {
+                const pixelId = (args.pixel_id || args.id);
+                if (!pixelId)
+                    return { success: false, error: "pixel_id required (local UUID or meta_pixel_id)" };
+                // Try to find by local UUID first, then by meta_pixel_id
+                let row = null;
+                const { data: byId } = await sb.from("meta_pixels").select("*").eq("id", pixelId).maybeSingle();
+                if (byId) {
+                    row = byId;
+                }
+                else {
+                    const { data: byMetaId } = await sb.from("meta_pixels").select("*").eq("meta_pixel_id", pixelId).eq("store_id", storeId).maybeSingle();
+                    row = byMetaId;
+                }
+                if (!row)
+                    return { success: false, error: `Pixel not found: ${pixelId}` };
+                // Delete from local DB (Meta pixels can't be deleted via API, only archived)
+                const { error } = await sb.from("meta_pixels").delete().eq("id", row.id);
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, message: `Pixel "${row.name}" removed from store.` };
+            }
+            case "create_custom_conversion": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const int = await getIntegration(sb, storeId);
+                const pixelId = args.pixel_id || int.pixelId;
+                if (!pixelId)
+                    return { success: false, error: "pixel_id required (none configured — set one in Settings → Meta Connection)" };
+                const metaParams = {
+                    name,
+                    event_source_id: pixelId,
+                    custom_event_type: args.custom_event_type || "OTHER",
+                    rule: JSON.stringify(args.rule || { url: { i_contains: "" } }),
+                };
+                if (args.default_conversion_value) {
+                    metaParams.default_conversion_value = Number(args.default_conversion_value);
+                }
+                const result = await graphPost(`${int.adAccountId}/customconversions`, metaParams, int.accessToken);
+                const metaConversionId = result.id;
+                const { data, error } = await sb.from("meta_custom_conversions").insert({
+                    store_id: storeId,
+                    meta_conversion_id: metaConversionId || null,
+                    name,
+                    pixel_id: pixelId,
+                    rule: args.rule || null,
+                    default_conversion_value: args.default_conversion_value ? Number(args.default_conversion_value) : null,
+                    custom_event_type: args.custom_event_type || "OTHER",
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { ...data, meta_conversion_id: metaConversionId } };
+            }
+            case "list_custom_conversions": {
+                const int = await getIntegration(sb, storeId);
+                const fields = "id,name,pixel,custom_event_type,rule,default_conversion_value,creation_time,last_fired_time";
+                const result = await graphGet(`${int.adAccountId}/customconversions`, fields, int.accessToken);
+                return { success: true, data: result.data || [] };
+            }
+            // ==================================================================
+            // AD RULES / AUTOMATION
+            // ==================================================================
+            case "create_rule": {
+                const name = args.name;
+                if (!name)
+                    return { success: false, error: "name required" };
+                const int = await getIntegration(sb, storeId);
+                const evaluationSpec = args.evaluation_spec;
+                const executionSpec = args.execution_spec;
+                if (!evaluationSpec)
+                    return { success: false, error: "evaluation_spec required" };
+                if (!executionSpec)
+                    return { success: false, error: "execution_spec required" };
+                const entityType = args.entity_type || "CAMPAIGN";
+                const scheduleSpec = args.schedule_spec || { schedule_type: "SEMI_HOURLY" };
+                // Meta requires entity_type as a filter inside evaluation_spec.filters
+                const evalSpecFinal = { ...evaluationSpec };
+                delete evalSpecFinal.entity_type; // not valid as root key
+                if (!evalSpecFinal.filters)
+                    evalSpecFinal.filters = [];
+                const filters = evalSpecFinal.filters;
+                const hasEntityFilter = filters.some((f) => f.field === "entity_type");
+                if (!hasEntityFilter) {
+                    filters.push({ field: "entity_type", value: entityType, operator: "EQUAL" });
+                }
+                const hasTimePreset = filters.some((f) => f.field === "time_preset");
+                if (!hasTimePreset) {
+                    filters.push({ field: "time_preset", value: "LAST_7_DAYS", operator: "EQUAL" });
+                }
+                const metaParams = {
+                    name,
+                    evaluation_spec: JSON.stringify(evalSpecFinal),
+                    execution_spec: JSON.stringify(executionSpec),
+                    schedule_spec: JSON.stringify(scheduleSpec),
+                };
+                const result = await graphPost(`${int.adAccountId}/adrules_library`, metaParams, int.accessToken);
+                const metaRuleId = result.id;
+                const { data, error } = await sb.from("meta_ad_rules").insert({
+                    store_id: storeId,
+                    meta_rule_id: metaRuleId || null,
+                    name,
+                    evaluation_spec: evalSpecFinal,
+                    execution_spec: executionSpec,
+                    schedule_spec: scheduleSpec,
+                    entity_type: entityType,
+                }).select().single();
+                if (error)
+                    return { success: false, error: error.message };
+                return { success: true, data: { ...data, meta_rule_id: metaRuleId } };
+            }
+            case "list_rules": {
+                const int = await getIntegration(sb, storeId);
+                const fields = "id,name,status,evaluation_spec,execution_spec,schedule_spec,created_time,updated_time";
+                const result = await graphGet(`${int.adAccountId}/adrules_library`, fields, int.accessToken);
+                return { success: true, data: result.data || [] };
+            }
+            case "delete_rule": {
+                const id = (args.rule_id || args.id);
+                if (!id)
+                    return { success: false, error: "rule_id required" };
+                let metaId = id;
+                if (isLocalId(id)) {
+                    const { data } = await sb.from("meta_ad_rules").select("meta_rule_id")
+                        .eq("id", id).single();
+                    if (data?.meta_rule_id)
+                        metaId = data.meta_rule_id;
+                }
+                const int = await getIntegration(sb, storeId);
+                let metaDeleted = false;
+                if (!isLocalId(metaId)) {
+                    try {
+                        await graphDelete(metaId, int.accessToken);
+                        metaDeleted = true;
+                    }
+                    catch { /* continue */ }
+                }
+                // Delete from local DB
+                if (isLocalId(id)) {
+                    await sb.from("meta_ad_rules").delete().eq("id", id);
+                }
+                else {
+                    await sb.from("meta_ad_rules").delete().eq("meta_rule_id", id).eq("store_id", storeId);
+                }
+                return { success: true, data: { deleted: id, meta_deleted: metaDeleted } };
+            }
+            // ==================================================================
+            // REACH ESTIMATE / AUDIENCE INSIGHTS
+            // ==================================================================
+            case "reach_estimate": {
+                const int = await getIntegration(sb, storeId);
+                const targetingSpec = args.targeting;
+                if (!targetingSpec)
+                    return { success: false, error: "targeting required (targeting spec object)" };
+                const resolvedTargeting = await buildTargeting(sb, targetingSpec, int);
+                // Meta v21 uses delivery_estimate with GET, targeting_spec as query param
+                const extra = `targeting_spec=${encodeURIComponent(JSON.stringify(resolvedTargeting))}&optimization_goal=${encodeURIComponent(args.optimize_for || "REACH")}`;
+                const result = await graphGet(`${int.adAccountId}/delivery_estimate`, "daily_outcomes_curve,estimate_dau,estimate_ready", int.accessToken, extra);
+                return { success: true, data: result.data || result };
+            }
+            case "audience_insights": {
+                const id = (args.ad_set_id || args.id);
+                if (!id)
+                    return { success: false, error: "ad_set_id required" };
+                const { data: adSet } = await sb.from("meta_ad_sets").select("meta_ad_set_id, targeting")
+                    .eq("id", id).eq("store_id", storeId).single();
+                if (!adSet)
+                    return { success: false, error: `Ad set not found: ${id}` };
+                const int = await getIntegration(sb, storeId);
+                // If published, get delivery insights
+                if (!isLocalId(adSet.meta_ad_set_id)) {
+                    const fields = "reach,impressions,frequency,actions,age_targeting,gender_targeting";
+                    const result = await graphGet(`${adSet.meta_ad_set_id}/insights`, fields, int.accessToken, "breakdowns=age,gender&date_preset=last_30d");
+                    return { success: true, data: result.data || [] };
+                }
+                // If draft, estimate reach
+                const targeting = adSet.targeting
+                    ? (typeof adSet.targeting === "string" ? JSON.parse(adSet.targeting) : adSet.targeting)
+                    : null;
+                if (!targeting)
+                    return { success: false, error: "No targeting configured on this ad set" };
+                const resolvedTargeting = await buildTargeting(sb, targeting, int);
+                const extra = `targeting_spec=${encodeURIComponent(JSON.stringify(resolvedTargeting))}&optimization_goal=REACH`;
+                const estimate = await graphGet(`${int.adAccountId}/delivery_estimate`, "daily_outcomes_curve,estimate_dau,estimate_ready", int.accessToken, extra);
+                return { success: true, data: { type: "estimate", ...(Array.isArray(estimate.data) ? estimate.data[0] : estimate) } };
+            }
+            // ==================================================================
+            // SEARCH TARGETING — find valid Meta interest/location IDs
+            // ==================================================================
+            case "search_targeting": {
+                const query = args.query;
+                const type = args.targeting_type || "adinterest";
+                if (!query)
+                    return { success: false, error: "query required (search term for interests/locations)" };
+                const int = await getIntegration(sb, storeId);
+                const validTypes = ["adinterest", "adgeolocation", "adlocale", "adTargetingCategory"];
+                const searchType = validTypes.includes(type) ? type : "adinterest";
+                const url = `${META_BASE}/search?type=${searchType}&q=${enc(query)}&access_token=${enc(int.accessToken)}&limit=25`;
+                const res = await fetch(url);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return { success: false, error: parseMetaError(body, "search", res.status) };
+                }
+                const json = await res.json();
+                return { success: true, data: json.data || [] };
+            }
+            // ==================================================================
+            // DEFAULT
+            // ==================================================================
+            default:
+                return {
+                    success: false,
+                    error: `Unknown action: ${action}. Valid: create_campaign, create_ad_set, create_ad, create_full, list_campaigns, list_ad_sets, list_ads, get_campaign, get_ad_set, get_ad, update_campaign, update_ad_set, update_ad, delete, publish, sync, search_targeting, insights_breakdown, ad_preview, create_audience, list_audiences, get_audience, delete_audience, create_lookalike, create_lead_form, list_lead_forms, get_leads, list_pixels, create_custom_conversion, list_custom_conversions, create_rule, list_rules, delete_rule, reach_estimate, audience_insights.`,
+                };
+        }
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}