cli-meta-ads 0.1.0

package/dist/domain/meta-ads-service.js

@@ -0,0 +1,841 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { discoverManagedAccounts } from "../client/meta-discovery.js";
+import { buildAssetFeedCreativeSpec as compileAssetFeedCreativeSpec } from "./asset-feed-compiler.js";
+import { buildRecentDateWindow, toInsightsTimeRange } from "../utils/date-range.js";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { defaultCreativeFormatPlacementTargets, hasPlacementFormats, launchCreativeFormatKeys } from "../utils/meta-placement-assets.js";
+import { fromMinorUnits } from "../utils/currency.js";
+import { toAdAccountNodeId } from "../utils/ids.js";
+const actionStatSchema = z.object({
+    action_type: z.string().optional(),
+    value: z.string().optional()
+});
+const insightsRowSchema = z
+    .object({
+    account_currency: z.string().optional(),
+    account_id: z.string().optional(),
+    account_name: z.string().optional(),
+    actions: z.array(actionStatSchema).optional(),
+    ad_id: z.string().optional(),
+    ad_name: z.string().optional(),
+    campaign_id: z.string().optional(),
+    campaign_name: z.string().optional(),
+    clicks: z.string().optional(),
+    cpc: z.string().optional(),
+    cpm: z.string().optional(),
+    ctr: z.string().optional(),
+    date_start: z.string().optional(),
+    date_stop: z.string().optional(),
+    frequency: z.string().optional(),
+    impressions: z.string().optional(),
+    reach: z.string().optional(),
+    spend: z.string().optional()
+})
+    .passthrough();
+const campaignSchema = z
+    .object({
+    account_id: z.string().optional(),
+    buying_type: z.string().optional(),
+    created_time: z.string().optional(),
+    daily_budget: z.union([z.string(), z.number()]).optional(),
+    effective_status: z.string().optional(),
+    id: z.string(),
+    name: z.string().optional(),
+    objective: z.string().optional(),
+    spend_cap: z.union([z.string(), z.number()]).optional(),
+    start_time: z.string().optional(),
+    status: z.string().optional(),
+    stop_time: z.string().optional(),
+    updated_time: z.string().optional()
+})
+    .passthrough();
+const adSchema = z
+    .object({
+    adset_id: z.string().optional(),
+    creative: z
+        .object({
+        id: z.string().optional(),
+        name: z.string().optional()
+    })
+        .passthrough()
+        .optional(),
+    effective_status: z.string().optional(),
+    id: z.string(),
+    name: z.string().optional(),
+    status: z.string().optional()
+})
+    .passthrough();
+const pixelSchema = z
+    .object({
+    creation_time: z.string().optional(),
+    enable_automatic_matching: z.boolean().optional(),
+    event_stats: z.union([z.string(), z.array(z.unknown()), z.record(z.string(), z.unknown())]).optional(),
+    event_time_max: z.union([z.number(), z.string()]).optional(),
+    first_party_cookie_status: z.string().optional(),
+    id: z.string(),
+    is_unavailable: z.boolean().optional(),
+    last_fired_time: z.string().optional(),
+    name: z.string().optional(),
+    server_events_business_ids: z.array(z.string()).optional()
+})
+    .passthrough();
+const audienceSchema = z
+    .object({
+    approximate_count: z.number().optional(),
+    approximate_count_lower_bound: z.number().optional(),
+    approximate_count_upper_bound: z.number().optional(),
+    delivery_status: z
+        .object({
+        code: z.number().optional(),
+        description: z.string().optional()
+    })
+        .passthrough()
+        .optional(),
+    id: z.string(),
+    name: z.string().optional(),
+    operation_status: z
+        .object({
+        code: z.number().optional(),
+        description: z.string().optional()
+    })
+        .passthrough()
+        .optional(),
+    retention_days: z.number().optional(),
+    subtype: z.string().optional(),
+    time_updated: z.union([z.number(), z.string()]).optional()
+})
+    .passthrough();
+const whoAmISchema = z
+    .object({
+    id: z.string(),
+    name: z.string().optional()
+})
+    .passthrough();
+const accountSchema = z
+    .object({
+    account_id: z.string().optional(),
+    account_status: z.union([z.number(), z.string()]).optional(),
+    business: z
+        .object({
+        id: z.string().optional(),
+        name: z.string().optional()
+    })
+        .passthrough()
+        .optional(),
+    currency: z.string().optional(),
+    id: z.string().optional(),
+    name: z.string().optional(),
+    timezone_name: z.string().optional()
+})
+    .passthrough();
+const previewSchema = z
+    .object({
+    body: z.string().optional(),
+    html: z.string().optional(),
+    preview_shareable_link: z.string().optional(),
+    render_type: z.string().optional()
+})
+    .passthrough();
+const createdEntitySchema = z.object({
+    id: z.string()
+}).passthrough();
+const adImageUploadSchema = z.object({
+    images: z.record(z.string(), z.object({
+        hash: z.string().optional(),
+        url: z.string().optional()
+    }).passthrough())
+}).passthrough();
+const adVideoUploadSchema = z.object({
+    id: z.string(),
+    success: z.boolean().optional()
+}).passthrough();
+const adVideoStatusSchema = z.object({
+    id: z.string(),
+    processing_progress: z.union([z.number(), z.string()]).optional(),
+    status: z.union([
+        z.string(),
+        z.object({
+            processing_phase: z.object({
+                progress: z.union([z.number(), z.string()]).optional(),
+                status: z.string().optional()
+            }).passthrough().optional(),
+            video_status: z.string().optional()
+        }).passthrough()
+    ]).optional(),
+    title: z.string().optional()
+}).passthrough();
+function toNumber(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    return typeof value === "number" ? value : Number(value);
+}
+function normalizeInsightsRow(row) {
+    return {
+        accountCurrency: row.account_currency,
+        accountId: row.account_id,
+        accountName: row.account_name,
+        actions: row.actions?.map((entry) => ({
+            actionType: entry.action_type,
+            value: toNumber(entry.value)
+        })) ?? [],
+        adId: row.ad_id,
+        adName: row.ad_name,
+        campaignId: row.campaign_id,
+        campaignName: row.campaign_name,
+        clicks: toNumber(row.clicks),
+        cpc: toNumber(row.cpc),
+        cpm: toNumber(row.cpm),
+        ctr: toNumber(row.ctr),
+        dateStart: row.date_start,
+        dateStop: row.date_stop,
+        frequency: toNumber(row.frequency),
+        impressions: toNumber(row.impressions),
+        reach: toNumber(row.reach),
+        spend: toNumber(row.spend),
+        raw: row
+    };
+}
+function normalizeCampaign(row) {
+    return {
+        accountId: row.account_id,
+        buyingType: row.buying_type,
+        createdTime: row.created_time,
+        dailyBudgetMinorUnits: row.daily_budget !== undefined ? toNumber(row.daily_budget) : undefined,
+        effectiveStatus: row.effective_status,
+        id: row.id,
+        name: row.name,
+        objective: row.objective,
+        spendCapMinorUnits: row.spend_cap !== undefined ? toNumber(row.spend_cap) : undefined,
+        startTime: row.start_time,
+        status: row.status,
+        stopTime: row.stop_time,
+        updatedTime: row.updated_time,
+        raw: row
+    };
+}
+function normalizeAd(row) {
+    return {
+        adsetId: row.adset_id,
+        creativeId: row.creative?.id,
+        creativeName: row.creative?.name,
+        effectiveStatus: row.effective_status,
+        id: row.id,
+        name: row.name,
+        status: row.status,
+        raw: row
+    };
+}
+function normalizePixel(row) {
+    return {
+        createdAt: row.creation_time,
+        enableAutomaticMatching: row.enable_automatic_matching ?? false,
+        eventStats: row.event_stats,
+        eventTimeMax: row.event_time_max ? new Date(Number(row.event_time_max) * 1000).toISOString() : undefined,
+        firstPartyCookieStatus: row.first_party_cookie_status,
+        id: row.id,
+        isUnavailable: row.is_unavailable ?? false,
+        lastFiredTime: row.last_fired_time,
+        name: row.name,
+        serverEventsBusinessIds: row.server_events_business_ids ?? [],
+        raw: row
+    };
+}
+function normalizeAudience(row) {
+    return {
+        approximateCount: row.approximate_count,
+        approximateCountLowerBound: row.approximate_count_lower_bound,
+        approximateCountUpperBound: row.approximate_count_upper_bound,
+        deliveryStatusCode: row.delivery_status?.code,
+        deliveryStatusDescription: row.delivery_status?.description,
+        id: row.id,
+        name: row.name,
+        operationStatusCode: row.operation_status?.code,
+        operationStatusDescription: row.operation_status?.description,
+        retentionDays: row.retention_days,
+        subtype: row.subtype,
+        timeUpdated: row.time_updated,
+        raw: row
+    };
+}
+function toCreateResult(row) {
+    return {
+        id: row.id,
+        raw: row
+    };
+}
+function buildPromotedObject(spec) {
+    return {
+        application_id: spec.applicationId,
+        custom_conversion_id: spec.customConversionId,
+        custom_event_type: spec.customEventType,
+        event_id: spec.eventId,
+        instagram_actor_id: spec.instagramActorId,
+        object_store_url: spec.objectStoreUrl,
+        offline_conversion_data_set_id: spec.offlineConversionDataSetId,
+        page_id: spec.pageId,
+        pixel_id: spec.pixelId,
+        product_set_id: spec.productSetId,
+        whatsapp_phone_number: spec.whatsappPhoneNumber
+    };
+}
+function buildCreativePlatformCustomizations(spec) {
+    const instagram = spec?.instagram;
+    if (!instagram) {
+        return undefined;
+    }
+    return {
+        instagram: {
+            caption_ids: instagram.captionIds,
+            image_crops: instagram.imageCrops,
+            image_hash: instagram.imageHash,
+            image_url: instagram.imageUrl,
+            video_id: instagram.videoId
+        }
+    };
+}
+function resolveCreativeMediaBinding(source, fallbackId) {
+    if (source.videoId) {
+        return {
+            captionIds: source.captionIds,
+            id: `video:${source.videoId}`,
+            kind: "video",
+            videoId: source.videoId
+        };
+    }
+    return {
+        id: source.imageHash ? `image_hash:${source.imageHash}` : `image_url:${source.imageUrl ?? fallbackId}`,
+        imageCrops: source.imageCrops,
+        imageHash: source.imageHash,
+        imageUrl: source.imageUrl,
+        kind: "image"
+    };
+}
+function hasImageUrlFormatOverride(formats) {
+    return Boolean(formats && launchCreativeFormatKeys.some((key) => formats[key]?.imageUrl));
+}
+function normalizeVideoStatus(row) {
+    const status = typeof row.status === "string"
+        ? row.status
+        : row.status?.video_status ?? row.status?.processing_phase?.status;
+    const rawProgress = row.processing_progress
+        ?? (typeof row.status === "object" ? row.status?.processing_phase?.progress : undefined);
+    return {
+        id: row.id,
+        processingProgress: rawProgress !== undefined ? Number(rawProgress) : undefined,
+        status,
+        title: row.title,
+        raw: row
+    };
+}
+function isReadyVideoStatus(status) {
+    const normalizedStatus = status.status?.toLowerCase();
+    return normalizedStatus === "ready"
+        || normalizedStatus === "active"
+        || normalizedStatus === "available"
+        || status.processingProgress === 100;
+}
+function isFailedVideoStatus(status) {
+    const normalizedStatus = status.status?.toLowerCase();
+    return normalizedStatus === "error"
+        || normalizedStatus === "failed"
+        || normalizedStatus === "failure";
+}
+export class MetaAdsService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async whoAmI() {
+        const response = await this.client.get("/me", {
+            fields: "id,name"
+        });
+        return whoAmISchema.parse(response.data);
+    }
+    async listManagedAccounts(config) {
+        return discoverManagedAccounts(config, this.client);
+    }
+    async getAccount(accountId) {
+        const response = await this.client.get(`/${toAdAccountNodeId(accountId)}`, {
+            fields: "id,account_id,name,account_status,currency,timezone_name,business{id,name}"
+        });
+        return accountSchema.parse(response.data);
+    }
+    async createCampaign(accountId, spec) {
+        const response = await this.client.post(`/${toAdAccountNodeId(accountId)}/campaigns`, {
+            bid_strategy: spec.bidStrategy,
+            daily_budget: spec.dailyBudget,
+            is_adset_budget_sharing_enabled: false,
+            lifetime_budget: spec.lifetimeBudget,
+            name: spec.name,
+            objective: spec.objective,
+            special_ad_categories: JSON.stringify(spec.specialAdCategories ?? []),
+            status: spec.status ?? "PAUSED"
+        });
+        return toCreateResult(createdEntitySchema.parse(response.data));
+    }
+    async createAdSet(accountId, spec) {
+        const response = await this.client.post(`/${toAdAccountNodeId(accountId)}/adsets`, {
+            bid_amount: spec.bidAmount,
+            bid_strategy: spec.bidStrategy
+                ?? (spec.bidAmount !== undefined ? "LOWEST_COST_WITH_BID_CAP" : "LOWEST_COST_WITHOUT_CAP"),
+            billing_event: spec.billingEvent,
+            campaign_id: spec.campaignId,
+            daily_budget: spec.dailyBudget,
+            end_time: spec.endTime,
+            lifetime_budget: spec.lifetimeBudget,
+            name: spec.name,
+            optimization_goal: spec.optimizationGoal,
+            promoted_object: JSON.stringify(buildPromotedObject(spec.promotedObject)),
+            start_time: spec.startTime,
+            status: spec.status ?? "PAUSED",
+            targeting: JSON.stringify(spec.targeting)
+        });
+        return toCreateResult(createdEntitySchema.parse(response.data));
+    }
+    async uploadAdImage(accountId, filePath, name) {
+        const fileBuffer = await readFile(filePath);
+        const response = await this.client.postMultipart(`/${toAdAccountNodeId(accountId)}/adimages`, {
+            filename: {
+                blob: new Blob([fileBuffer]),
+                filename: path.basename(filePath)
+            },
+            name
+        });
+        const payload = adImageUploadSchema.parse(response.data);
+        const [uploadedName, uploadedImage] = Object.entries(payload.images)[0] ?? [];
+        if (!uploadedName || !uploadedImage) {
+            throw new AppError("Meta image upload did not return an uploaded image record.", ExitCode.Provider);
+        }
+        return {
+            fileName: uploadedName,
+            hash: uploadedImage.hash,
+            name: name ?? uploadedName,
+            url: uploadedImage.url,
+            raw: uploadedImage
+        };
+    }
+    async uploadAdVideo(accountId, filePath, name) {
+        const fileBuffer = await readFile(filePath);
+        const response = await this.client.postMultipart(`/${toAdAccountNodeId(accountId)}/advideos`, {
+            name,
+            source: {
+                blob: new Blob([fileBuffer]),
+                filename: path.basename(filePath)
+            }
+        });
+        const payload = adVideoUploadSchema.parse(response.data);
+        return {
+            id: payload.id,
+            name,
+            raw: payload
+        };
+    }
+    async getAdVideoStatus(videoId) {
+        const response = await this.client.get(`/${videoId}`, {
+            fields: "id,title,status,processing_progress"
+        });
+        return normalizeVideoStatus(adVideoStatusSchema.parse(response.data));
+    }
+    async waitForVideoReady(videoId, options = {}) {
+        const pollMs = options.pollMs ?? 3000;
+        const timeoutMs = options.timeoutMs ?? 90000;
+        const deadline = Date.now() + timeoutMs;
+        let lastStatus = await this.getAdVideoStatus(videoId);
+        while (!isReadyVideoStatus(lastStatus)) {
+            if (isFailedVideoStatus(lastStatus)) {
+                throw new AppError(`Meta video ${videoId} failed during processing.`, ExitCode.Provider, {
+                    status: lastStatus.status,
+                    videoId
+                });
+            }
+            if (Date.now() >= deadline) {
+                throw new AppError(`Timed out waiting for Meta video ${videoId} to finish processing.`, ExitCode.VerificationFailed, {
+                    status: lastStatus.status,
+                    timeoutMs,
+                    videoId
+                });
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            lastStatus = await this.getAdVideoStatus(videoId);
+        }
+        return lastStatus;
+    }
+    async createCreative(accountId, spec) {
+        const includeMatchingFormatRules = spec.kind === "link-image" && hasImageUrlFormatOverride(spec.formats);
+        const fallbackBinding = hasPlacementFormats(spec.formats)
+            ? spec.kind === "link-image"
+                ? resolveCreativeMediaBinding({
+                    imageHash: spec.imageHash ?? spec.formats?.feed4x5?.imageHash ?? spec.formats?.square1x1?.imageHash ?? spec.formats?.story9x16?.imageHash,
+                    imageUrl: spec.formats?.feed4x5?.imageUrl ?? spec.formats?.square1x1?.imageUrl ?? spec.formats?.story9x16?.imageUrl
+                }, spec.name ?? spec.kind)
+                : resolveCreativeMediaBinding({
+                    videoId: spec.videoId ?? spec.formats?.feed4x5?.videoId ?? spec.formats?.square1x1?.videoId ?? spec.formats?.story9x16?.videoId
+                }, spec.name ?? spec.kind)
+            : undefined;
+        if (fallbackBinding && hasPlacementFormats(spec.formats)) {
+            const assetFeedSpec = spec.kind === "link-image"
+                ? compileAssetFeedCreativeSpec({
+                    fallback: fallbackBinding,
+                    formatBindings: {
+                        feed4x5: spec.formats?.feed4x5
+                            ? resolveCreativeMediaBinding(spec.formats.feed4x5, `${spec.name ?? spec.kind}:feed4x5`)
+                            : undefined,
+                        square1x1: spec.formats?.square1x1
+                            ? resolveCreativeMediaBinding(spec.formats.square1x1, `${spec.name ?? spec.kind}:square1x1`)
+                            : undefined,
+                        story9x16: spec.formats?.story9x16
+                            ? resolveCreativeMediaBinding(spec.formats.story9x16, `${spec.name ?? spec.kind}:story9x16`)
+                            : undefined
+                    },
+                    kind: spec.kind,
+                    linkData: spec.linkData,
+                    includeMatchingFormatRules,
+                    name: spec.name,
+                    pageId: spec.pageId,
+                    placementTargets: defaultCreativeFormatPlacementTargets
+                })
+                : compileAssetFeedCreativeSpec({
+                    fallback: fallbackBinding,
+                    formatBindings: {
+                        feed4x5: spec.formats?.feed4x5
+                            ? resolveCreativeMediaBinding(spec.formats.feed4x5, `${spec.name ?? spec.kind}:feed4x5`)
+                            : undefined,
+                        square1x1: spec.formats?.square1x1
+                            ? resolveCreativeMediaBinding(spec.formats.square1x1, `${spec.name ?? spec.kind}:square1x1`)
+                            : undefined,
+                        story9x16: spec.formats?.story9x16
+                            ? resolveCreativeMediaBinding(spec.formats.story9x16, `${spec.name ?? spec.kind}:story9x16`)
+                            : undefined
+                    },
+                    kind: spec.kind,
+                    includeMatchingFormatRules,
+                    name: spec.name,
+                    pageId: spec.pageId,
+                    placementTargets: defaultCreativeFormatPlacementTargets,
+                    videoData: spec.videoData
+                });
+            if (assetFeedSpec) {
+                return this.createAssetFeedCreative(accountId, assetFeedSpec);
+            }
+        }
+        const platformCustomizations = buildCreativePlatformCustomizations(spec.platformCustomizations);
+        const objectStorySpec = spec.kind === "link-image"
+            ? {
+                link_data: {
+                    call_to_action: spec.linkData.callToAction
+                        ? {
+                            type: spec.linkData.callToAction,
+                            value: {
+                                link: spec.linkData.link
+                            }
+                        }
+                        : undefined,
+                    description: spec.linkData.description,
+                    image_hash: spec.imageHash ?? fallbackBinding?.imageHash,
+                    link: spec.linkData.link,
+                    message: spec.linkData.message,
+                    name: spec.linkData.headline
+                },
+                page_id: spec.pageId
+            }
+            : {
+                page_id: spec.pageId,
+                video_data: {
+                    call_to_action: spec.videoData.callToAction
+                        ? {
+                            type: spec.videoData.callToAction,
+                            value: {
+                                link: spec.videoData.link
+                            }
+                        }
+                        : undefined,
+                    description: spec.videoData.description,
+                    link: spec.videoData.link,
+                    message: spec.videoData.message,
+                    title: spec.videoData.title,
+                    video_id: spec.videoId ?? fallbackBinding?.videoId
+                }
+            };
+        const response = await this.client.post(`/${toAdAccountNodeId(accountId)}/adcreatives`, {
+            name: spec.name ?? `${spec.kind}-${Date.now()}`,
+            object_story_spec: JSON.stringify(objectStorySpec),
+            platform_customizations: platformCustomizations
+                ? JSON.stringify(platformCustomizations)
+                : undefined
+        });
+        return toCreateResult(createdEntitySchema.parse(response.data));
+    }
+    async createAssetFeedCreative(accountId, spec) {
+        const response = await this.client.post(`/${toAdAccountNodeId(accountId)}/adcreatives`, {
+            asset_feed_spec: JSON.stringify(spec.assetFeedSpec),
+            name: spec.name ?? `${spec.kind}-placement-${Date.now()}`,
+            object_story_spec: JSON.stringify({
+                page_id: spec.pageId
+            })
+        });
+        return toCreateResult(createdEntitySchema.parse(response.data));
+    }
+    async createAd(accountId, spec) {
+        const response = await this.client.post(`/${toAdAccountNodeId(accountId)}/ads`, {
+            adset_id: spec.adSetId,
+            creative: JSON.stringify({
+                creative_id: spec.creativeId
+            }),
+            name: spec.name,
+            status: spec.status ?? "PAUSED"
+        });
+        return toCreateResult(createdEntitySchema.parse(response.data));
+    }
+    async listCampaigns(accountId) {
+        const response = await this.client.paginate(`/${toAdAccountNodeId(accountId)}/campaigns`, {
+            fields: "id,account_id,name,objective,status,effective_status,daily_budget,spend_cap,start_time,stop_time,created_time,updated_time",
+            limit: 500
+        });
+        return response.data.data.map((entry) => normalizeCampaign(campaignSchema.parse(entry)));
+    }
+    async getCampaign(campaignId) {
+        const response = await this.client.get(`/${campaignId}`, {
+            fields: "id,account_id,name,objective,status,effective_status,daily_budget,spend_cap,start_time,stop_time,created_time,updated_time,buying_type"
+        });
+        return normalizeCampaign(campaignSchema.parse(response.data));
+    }
+    async updateCampaignStatus(campaignId, status) {
+        return this.client.post(`/${campaignId}`, {
+            status
+        });
+    }
+    async updateCampaignDailyBudget(campaignId, dailyBudgetMinorUnits) {
+        return this.client.post(`/${campaignId}`, {
+            daily_budget: dailyBudgetMinorUnits
+        });
+    }
+    async listAdsByCampaign(campaignId) {
+        const response = await this.client.paginate(`/${campaignId}/ads`, {
+            fields: "id,name,status,effective_status,adset_id,creative{id,name}",
+            limit: 500
+        });
+        return response.data.data.map((entry) => normalizeAd(adSchema.parse(entry)));
+    }
+    async getAdPreview(adId, adFormat) {
+        const response = await this.client.paginate(`/${adId}/previews`, {
+            ...(adFormat ? { ad_format: adFormat } : {}),
+            limit: 50
+        });
+        return response.data.data.map((entry) => previewSchema.parse(entry));
+    }
+    async listPixels(accountId) {
+        const response = await this.client.paginate(`/${toAdAccountNodeId(accountId)}/adspixels`, {
+            fields: [
+                "id",
+                "name",
+                "creation_time",
+                "last_fired_time",
+                "event_time_max",
+                "event_stats",
+                "is_unavailable",
+                "enable_automatic_matching",
+                "first_party_cookie_status",
+                "server_events_business_ids"
+            ].join(","),
+            limit: 200
+        });
+        return response.data.data.map((entry) => normalizePixel(pixelSchema.parse(entry)));
+    }
+    async listAudiences(accountId) {
+        const response = await this.client.paginate(`/${toAdAccountNodeId(accountId)}/customaudiences`, {
+            fields: [
+                "id",
+                "name",
+                "subtype",
+                "delivery_status",
+                "approximate_count",
+                "approximate_count_lower_bound",
+                "approximate_count_upper_bound",
+                "operation_status",
+                "retention_days",
+                "time_updated"
+            ].join(","),
+            limit: 500
+        });
+        return response.data.data.map((entry) => normalizeAudience(audienceSchema.parse(entry)));
+    }
+    async getAudience(audienceId) {
+        const response = await this.client.get(`/${audienceId}`, {
+            fields: [
+                "id",
+                "name",
+                "subtype",
+                "delivery_status",
+                "approximate_count",
+                "approximate_count_lower_bound",
+                "approximate_count_upper_bound",
+                "operation_status",
+                "retention_days",
+                "time_updated"
+            ].join(",")
+        });
+        return normalizeAudience(audienceSchema.parse(response.data));
+    }
+    async getInsights(query) {
+        const response = await this.client.paginate(`/${query.targetId}/insights`, {
+            breakdowns: query.breakdowns && query.breakdowns.length > 0 ? query.breakdowns.join(",") : undefined,
+            fields: query.fields.join(","),
+            level: query.level,
+            limit: 500,
+            sort: query.sort ? JSON.stringify([query.sort]) : undefined,
+            time_increment: query.timeIncrement,
+            time_range: toInsightsTimeRange(query.window)
+        });
+        return response.data.data.map((entry) => normalizeInsightsRow(insightsRowSchema.parse(entry)));
+    }
+    async getPerformanceByAccount(accountId, window, breakdowns, campaignName, sort) {
+        const fields = [
+            "account_id",
+            "account_name",
+            "account_currency",
+            "campaign_id",
+            "campaign_name",
+            "impressions",
+            "reach",
+            "clicks",
+            "ctr",
+            "cpc",
+            "cpm",
+            "spend",
+            "frequency",
+            "actions",
+            "date_start",
+            "date_stop"
+        ];
+        if (!campaignName) {
+            return this.getInsights({
+                breakdowns,
+                fields,
+                level: "campaign",
+                sort,
+                targetId: toAdAccountNodeId(accountId),
+                window
+            });
+        }
+        const campaigns = await this.listCampaigns(accountId);
+        const matches = campaigns.filter((campaign) => (campaign.name ?? "").toLowerCase().includes(campaignName.toLowerCase()));
+        if (matches.length === 0) {
+            return [];
+        }
+        const rows = await Promise.all(matches.map((campaign) => this.getInsights({
+            breakdowns,
+            fields,
+            sort,
+            targetId: campaign.id,
+            window
+        })));
+        return rows.flat();
+    }
+    async getAdPerformanceByCampaign(campaignId, window, sort) {
+        return this.getInsights({
+            fields: [
+                "account_id",
+                "account_name",
+                "campaign_id",
+                "campaign_name",
+                "ad_id",
+                "ad_name",
+                "impressions",
+                "reach",
+                "clicks",
+                "ctr",
+                "cpc",
+                "cpm",
+                "spend",
+                "frequency",
+                "actions",
+                "date_start",
+                "date_stop"
+            ],
+            level: "ad",
+            sort,
+            targetId: campaignId,
+            window
+        });
+    }
+    async getDailyCampaignInsights(accountId, window) {
+        return this.getInsights({
+            fields: [
+                "account_id",
+                "account_name",
+                "campaign_id",
+                "campaign_name",
+                "impressions",
+                "clicks",
+                "ctr",
+                "cpc",
+                "spend",
+                "date_start",
+                "date_stop"
+            ],
+            level: "campaign",
+            targetId: toAdAccountNodeId(accountId),
+            timeIncrement: 1,
+            window
+        });
+    }
+    async getDailyAdInsights(campaignId, window) {
+        return this.getInsights({
+            fields: [
+                "ad_id",
+                "ad_name",
+                "campaign_id",
+                "campaign_name",
+                "impressions",
+                "clicks",
+                "ctr",
+                "cpc",
+                "cpm",
+                "spend",
+                "frequency",
+                "date_start",
+                "date_stop"
+            ],
+            level: "ad",
+            targetId: campaignId,
+            timeIncrement: 1,
+            window
+        });
+    }
+    async verifyApi(accountId) {
+        const whoAmI = await this.whoAmI();
+        const verification = {
+            apiVersion: this.client.apiVersion,
+            whoAmI
+        };
+        if (accountId) {
+            const account = await this.getAccount(accountId);
+            const campaigns = await this.listCampaigns(accountId);
+            const insights = await this.getInsights({
+                fields: ["account_id", "campaign_id", "campaign_name", "impressions", "clicks", "spend"],
+                level: "campaign",
+                targetId: toAdAccountNodeId(accountId),
+                window: buildRecentDateWindow(7)
+            });
+            verification.account = account;
+            verification.campaignCount = campaigns.length;
+            verification.insightSampleCount = insights.length;
+        }
+        return verification;
+    }
+    requireCampaignBudgetMinorUnits(campaign) {
+        if (campaign.dailyBudgetMinorUnits === undefined) {
+            throw new AppError("This campaign does not expose a campaign-level daily budget. Meta allows budget at campaign or ad set level; this CLI only updates campaign-level budgets via this command.", ExitCode.UnsafeBlocked);
+        }
+        return campaign.dailyBudgetMinorUnits;
+    }
+    expandCampaignBudget(campaign, currency) {
+        if (campaign.dailyBudgetMinorUnits === undefined) {
+            return undefined;
+        }
+        return fromMinorUnits(campaign.dailyBudgetMinorUnits, currency);
+    }
+}