cli-meta-ads 0.1.0

package/dist/domain/meta-ads-service.d.ts

@@ -0,0 +1,620 @@
+import { z } from "zod";
+import type { ResolvedConfig } from "../config/types.js";
+import type { ManagedAccount } from "../client/meta-discovery.js";
+import type { MetaApiClient } from "../client/meta-api-client.js";
+import type { DateWindow } from "../utils/date-range.js";
+import type { AdCreateSpec, AdSetCreateSpec, CampaignCreateSpec, CreativeCreateSpec } from "../validators/create-spec.js";
+declare const campaignSchema: z.ZodObject<{
+    account_id: z.ZodOptional<z.ZodString>;
+    buying_type: z.ZodOptional<z.ZodString>;
+    created_time: z.ZodOptional<z.ZodString>;
+    daily_budget: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    effective_status: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    objective: z.ZodOptional<z.ZodString>;
+    spend_cap: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    start_time: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    stop_time: z.ZodOptional<z.ZodString>;
+    updated_time: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+declare function normalizeCampaign(row: z.infer<typeof campaignSchema>): {
+    accountId: string | undefined;
+    buyingType: string | undefined;
+    createdTime: string | undefined;
+    dailyBudgetMinorUnits: number | undefined;
+    effectiveStatus: string | undefined;
+    id: string;
+    name: string | undefined;
+    objective: string | undefined;
+    spendCapMinorUnits: number | undefined;
+    startTime: string | undefined;
+    status: string | undefined;
+    stopTime: string | undefined;
+    updatedTime: string | undefined;
+    raw: {
+        [x: string]: unknown;
+        id: string;
+        account_id?: string | undefined;
+        buying_type?: string | undefined;
+        created_time?: string | undefined;
+        daily_budget?: string | number | undefined;
+        effective_status?: string | undefined;
+        name?: string | undefined;
+        objective?: string | undefined;
+        spend_cap?: string | number | undefined;
+        start_time?: string | undefined;
+        status?: string | undefined;
+        stop_time?: string | undefined;
+        updated_time?: string | undefined;
+    };
+};
+export interface CampaignRecord extends ReturnType<typeof normalizeCampaign> {
+}
+export interface InsightsQuery {
+    breakdowns?: string[] | undefined;
+    fields: string[];
+    level?: "account" | "campaign" | "adset" | "ad" | undefined;
+    sort?: string | undefined;
+    targetId: string;
+    timeIncrement?: 1 | "all_days" | undefined;
+    window: DateWindow;
+}
+export interface AssetFeedCreativeCreateSpec {
+    assetFeedSpec: Record<string, unknown>;
+    kind: "link-image" | "video-link";
+    name?: string | undefined;
+    pageId: string;
+}
+export declare class MetaAdsService {
+    private readonly client;
+    constructor(client: MetaApiClient);
+    whoAmI(): Promise<{
+        [x: string]: unknown;
+        id: string;
+        name?: string | undefined;
+    }>;
+    listManagedAccounts(config: ResolvedConfig): Promise<ManagedAccount[]>;
+    getAccount(accountId: string): Promise<{
+        [x: string]: unknown;
+        account_id?: string | undefined;
+        account_status?: string | number | undefined;
+        business?: {
+            [x: string]: unknown;
+            id?: string | undefined;
+            name?: string | undefined;
+        } | undefined;
+        currency?: string | undefined;
+        id?: string | undefined;
+        name?: string | undefined;
+        timezone_name?: string | undefined;
+    }>;
+    createCampaign(accountId: string, spec: CampaignCreateSpec): Promise<{
+        id: string;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+        };
+    }>;
+    createAdSet(accountId: string, spec: AdSetCreateSpec): Promise<{
+        id: string;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+        };
+    }>;
+    uploadAdImage(accountId: string, filePath: string, name?: string | undefined): Promise<{
+        fileName: string;
+        hash: string | undefined;
+        name: string;
+        url: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            hash?: string | undefined;
+            url?: string | undefined;
+        };
+    }>;
+    uploadAdVideo(accountId: string, filePath: string, name?: string | undefined): Promise<{
+        id: string;
+        name: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            success?: boolean | undefined;
+        };
+    }>;
+    getAdVideoStatus(videoId: string): Promise<{
+        id: string;
+        processingProgress: number | undefined;
+        status: string | undefined;
+        title: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            processing_progress?: string | number | undefined;
+            status?: string | {
+                [x: string]: unknown;
+                processing_phase?: {
+                    [x: string]: unknown;
+                    progress?: string | number | undefined;
+                    status?: string | undefined;
+                } | undefined;
+                video_status?: string | undefined;
+            } | undefined;
+            title?: string | undefined;
+        };
+    }>;
+    waitForVideoReady(videoId: string, options?: {
+        pollMs?: number | undefined;
+        timeoutMs?: number | undefined;
+    }): Promise<{
+        id: string;
+        processingProgress: number | undefined;
+        status: string | undefined;
+        title: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            processing_progress?: string | number | undefined;
+            status?: string | {
+                [x: string]: unknown;
+                processing_phase?: {
+                    [x: string]: unknown;
+                    progress?: string | number | undefined;
+                    status?: string | undefined;
+                } | undefined;
+                video_status?: string | undefined;
+            } | undefined;
+            title?: string | undefined;
+        };
+    }>;
+    createCreative(accountId: string, spec: CreativeCreateSpec): Promise<{
+        id: string;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+        };
+    }>;
+    createAssetFeedCreative(accountId: string, spec: AssetFeedCreativeCreateSpec): Promise<{
+        id: string;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+        };
+    }>;
+    createAd(accountId: string, spec: AdCreateSpec): Promise<{
+        id: string;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+        };
+    }>;
+    listCampaigns(accountId: string): Promise<{
+        accountId: string | undefined;
+        buyingType: string | undefined;
+        createdTime: string | undefined;
+        dailyBudgetMinorUnits: number | undefined;
+        effectiveStatus: string | undefined;
+        id: string;
+        name: string | undefined;
+        objective: string | undefined;
+        spendCapMinorUnits: number | undefined;
+        startTime: string | undefined;
+        status: string | undefined;
+        stopTime: string | undefined;
+        updatedTime: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            account_id?: string | undefined;
+            buying_type?: string | undefined;
+            created_time?: string | undefined;
+            daily_budget?: string | number | undefined;
+            effective_status?: string | undefined;
+            name?: string | undefined;
+            objective?: string | undefined;
+            spend_cap?: string | number | undefined;
+            start_time?: string | undefined;
+            status?: string | undefined;
+            stop_time?: string | undefined;
+            updated_time?: string | undefined;
+        };
+    }[]>;
+    getCampaign(campaignId: string): Promise<{
+        accountId: string | undefined;
+        buyingType: string | undefined;
+        createdTime: string | undefined;
+        dailyBudgetMinorUnits: number | undefined;
+        effectiveStatus: string | undefined;
+        id: string;
+        name: string | undefined;
+        objective: string | undefined;
+        spendCapMinorUnits: number | undefined;
+        startTime: string | undefined;
+        status: string | undefined;
+        stopTime: string | undefined;
+        updatedTime: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            account_id?: string | undefined;
+            buying_type?: string | undefined;
+            created_time?: string | undefined;
+            daily_budget?: string | number | undefined;
+            effective_status?: string | undefined;
+            name?: string | undefined;
+            objective?: string | undefined;
+            spend_cap?: string | number | undefined;
+            start_time?: string | undefined;
+            status?: string | undefined;
+            stop_time?: string | undefined;
+            updated_time?: string | undefined;
+        };
+    }>;
+    updateCampaignStatus(campaignId: string, status: "ACTIVE" | "PAUSED"): Promise<import("../client/meta-api-client.js").MetaRequestResult<unknown>>;
+    updateCampaignDailyBudget(campaignId: string, dailyBudgetMinorUnits: number): Promise<import("../client/meta-api-client.js").MetaRequestResult<unknown>>;
+    listAdsByCampaign(campaignId: string): Promise<{
+        adsetId: string | undefined;
+        creativeId: string | undefined;
+        creativeName: string | undefined;
+        effectiveStatus: string | undefined;
+        id: string;
+        name: string | undefined;
+        status: string | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            adset_id?: string | undefined;
+            creative?: {
+                [x: string]: unknown;
+                id?: string | undefined;
+                name?: string | undefined;
+            } | undefined;
+            effective_status?: string | undefined;
+            name?: string | undefined;
+            status?: string | undefined;
+        };
+    }[]>;
+    getAdPreview(adId: string, adFormat?: string | undefined): Promise<{
+        [x: string]: unknown;
+        body?: string | undefined;
+        html?: string | undefined;
+        preview_shareable_link?: string | undefined;
+        render_type?: string | undefined;
+    }[]>;
+    listPixels(accountId: string): Promise<{
+        createdAt: string | undefined;
+        enableAutomaticMatching: boolean;
+        eventStats: string | Record<string, unknown> | unknown[] | undefined;
+        eventTimeMax: string | undefined;
+        firstPartyCookieStatus: string | undefined;
+        id: string;
+        isUnavailable: boolean;
+        lastFiredTime: string | undefined;
+        name: string | undefined;
+        serverEventsBusinessIds: string[];
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            creation_time?: string | undefined;
+            enable_automatic_matching?: boolean | undefined;
+            event_stats?: string | Record<string, unknown> | unknown[] | undefined;
+            event_time_max?: string | number | undefined;
+            first_party_cookie_status?: string | undefined;
+            is_unavailable?: boolean | undefined;
+            last_fired_time?: string | undefined;
+            name?: string | undefined;
+            server_events_business_ids?: string[] | undefined;
+        };
+    }[]>;
+    listAudiences(accountId: string): Promise<{
+        approximateCount: number | undefined;
+        approximateCountLowerBound: number | undefined;
+        approximateCountUpperBound: number | undefined;
+        deliveryStatusCode: number | undefined;
+        deliveryStatusDescription: string | undefined;
+        id: string;
+        name: string | undefined;
+        operationStatusCode: number | undefined;
+        operationStatusDescription: string | undefined;
+        retentionDays: number | undefined;
+        subtype: string | undefined;
+        timeUpdated: string | number | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            approximate_count?: number | undefined;
+            approximate_count_lower_bound?: number | undefined;
+            approximate_count_upper_bound?: number | undefined;
+            delivery_status?: {
+                [x: string]: unknown;
+                code?: number | undefined;
+                description?: string | undefined;
+            } | undefined;
+            name?: string | undefined;
+            operation_status?: {
+                [x: string]: unknown;
+                code?: number | undefined;
+                description?: string | undefined;
+            } | undefined;
+            retention_days?: number | undefined;
+            subtype?: string | undefined;
+            time_updated?: string | number | undefined;
+        };
+    }[]>;
+    getAudience(audienceId: string): Promise<{
+        approximateCount: number | undefined;
+        approximateCountLowerBound: number | undefined;
+        approximateCountUpperBound: number | undefined;
+        deliveryStatusCode: number | undefined;
+        deliveryStatusDescription: string | undefined;
+        id: string;
+        name: string | undefined;
+        operationStatusCode: number | undefined;
+        operationStatusDescription: string | undefined;
+        retentionDays: number | undefined;
+        subtype: string | undefined;
+        timeUpdated: string | number | undefined;
+        raw: {
+            [x: string]: unknown;
+            id: string;
+            approximate_count?: number | undefined;
+            approximate_count_lower_bound?: number | undefined;
+            approximate_count_upper_bound?: number | undefined;
+            delivery_status?: {
+                [x: string]: unknown;
+                code?: number | undefined;
+                description?: string | undefined;
+            } | undefined;
+            name?: string | undefined;
+            operation_status?: {
+                [x: string]: unknown;
+                code?: number | undefined;
+                description?: string | undefined;
+            } | undefined;
+            retention_days?: number | undefined;
+            subtype?: string | undefined;
+            time_updated?: string | number | undefined;
+        };
+    }>;
+    getInsights(query: InsightsQuery): Promise<{
+        accountCurrency: string | undefined;
+        accountId: string | undefined;
+        accountName: string | undefined;
+        actions: {
+            actionType: string | undefined;
+            value: number;
+        }[];
+        adId: string | undefined;
+        adName: string | undefined;
+        campaignId: string | undefined;
+        campaignName: string | undefined;
+        clicks: number;
+        cpc: number;
+        cpm: number;
+        ctr: number;
+        dateStart: string | undefined;
+        dateStop: string | undefined;
+        frequency: number;
+        impressions: number;
+        reach: number;
+        spend: number;
+        raw: {
+            [x: string]: unknown;
+            account_currency?: string | undefined;
+            account_id?: string | undefined;
+            account_name?: string | undefined;
+            actions?: {
+                action_type?: string | undefined;
+                value?: string | undefined;
+            }[] | undefined;
+            ad_id?: string | undefined;
+            ad_name?: string | undefined;
+            campaign_id?: string | undefined;
+            campaign_name?: string | undefined;
+            clicks?: string | undefined;
+            cpc?: string | undefined;
+            cpm?: string | undefined;
+            ctr?: string | undefined;
+            date_start?: string | undefined;
+            date_stop?: string | undefined;
+            frequency?: string | undefined;
+            impressions?: string | undefined;
+            reach?: string | undefined;
+            spend?: string | undefined;
+        };
+    }[]>;
+    getPerformanceByAccount(accountId: string, window: DateWindow, breakdowns: string[], campaignName?: string | undefined, sort?: string | undefined): Promise<{
+        accountCurrency: string | undefined;
+        accountId: string | undefined;
+        accountName: string | undefined;
+        actions: {
+            actionType: string | undefined;
+            value: number;
+        }[];
+        adId: string | undefined;
+        adName: string | undefined;
+        campaignId: string | undefined;
+        campaignName: string | undefined;
+        clicks: number;
+        cpc: number;
+        cpm: number;
+        ctr: number;
+        dateStart: string | undefined;
+        dateStop: string | undefined;
+        frequency: number;
+        impressions: number;
+        reach: number;
+        spend: number;
+        raw: {
+            [x: string]: unknown;
+            account_currency?: string | undefined;
+            account_id?: string | undefined;
+            account_name?: string | undefined;
+            actions?: {
+                action_type?: string | undefined;
+                value?: string | undefined;
+            }[] | undefined;
+            ad_id?: string | undefined;
+            ad_name?: string | undefined;
+            campaign_id?: string | undefined;
+            campaign_name?: string | undefined;
+            clicks?: string | undefined;
+            cpc?: string | undefined;
+            cpm?: string | undefined;
+            ctr?: string | undefined;
+            date_start?: string | undefined;
+            date_stop?: string | undefined;
+            frequency?: string | undefined;
+            impressions?: string | undefined;
+            reach?: string | undefined;
+            spend?: string | undefined;
+        };
+    }[]>;
+    getAdPerformanceByCampaign(campaignId: string, window: DateWindow, sort?: string | undefined): Promise<{
+        accountCurrency: string | undefined;
+        accountId: string | undefined;
+        accountName: string | undefined;
+        actions: {
+            actionType: string | undefined;
+            value: number;
+        }[];
+        adId: string | undefined;
+        adName: string | undefined;
+        campaignId: string | undefined;
+        campaignName: string | undefined;
+        clicks: number;
+        cpc: number;
+        cpm: number;
+        ctr: number;
+        dateStart: string | undefined;
+        dateStop: string | undefined;
+        frequency: number;
+        impressions: number;
+        reach: number;
+        spend: number;
+        raw: {
+            [x: string]: unknown;
+            account_currency?: string | undefined;
+            account_id?: string | undefined;
+            account_name?: string | undefined;
+            actions?: {
+                action_type?: string | undefined;
+                value?: string | undefined;
+            }[] | undefined;
+            ad_id?: string | undefined;
+            ad_name?: string | undefined;
+            campaign_id?: string | undefined;
+            campaign_name?: string | undefined;
+            clicks?: string | undefined;
+            cpc?: string | undefined;
+            cpm?: string | undefined;
+            ctr?: string | undefined;
+            date_start?: string | undefined;
+            date_stop?: string | undefined;
+            frequency?: string | undefined;
+            impressions?: string | undefined;
+            reach?: string | undefined;
+            spend?: string | undefined;
+        };
+    }[]>;
+    getDailyCampaignInsights(accountId: string, window: DateWindow): Promise<{
+        accountCurrency: string | undefined;
+        accountId: string | undefined;
+        accountName: string | undefined;
+        actions: {
+            actionType: string | undefined;
+            value: number;
+        }[];
+        adId: string | undefined;
+        adName: string | undefined;
+        campaignId: string | undefined;
+        campaignName: string | undefined;
+        clicks: number;
+        cpc: number;
+        cpm: number;
+        ctr: number;
+        dateStart: string | undefined;
+        dateStop: string | undefined;
+        frequency: number;
+        impressions: number;
+        reach: number;
+        spend: number;
+        raw: {
+            [x: string]: unknown;
+            account_currency?: string | undefined;
+            account_id?: string | undefined;
+            account_name?: string | undefined;
+            actions?: {
+                action_type?: string | undefined;
+                value?: string | undefined;
+            }[] | undefined;
+            ad_id?: string | undefined;
+            ad_name?: string | undefined;
+            campaign_id?: string | undefined;
+            campaign_name?: string | undefined;
+            clicks?: string | undefined;
+            cpc?: string | undefined;
+            cpm?: string | undefined;
+            ctr?: string | undefined;
+            date_start?: string | undefined;
+            date_stop?: string | undefined;
+            frequency?: string | undefined;
+            impressions?: string | undefined;
+            reach?: string | undefined;
+            spend?: string | undefined;
+        };
+    }[]>;
+    getDailyAdInsights(campaignId: string, window: DateWindow): Promise<{
+        accountCurrency: string | undefined;
+        accountId: string | undefined;
+        accountName: string | undefined;
+        actions: {
+            actionType: string | undefined;
+            value: number;
+        }[];
+        adId: string | undefined;
+        adName: string | undefined;
+        campaignId: string | undefined;
+        campaignName: string | undefined;
+        clicks: number;
+        cpc: number;
+        cpm: number;
+        ctr: number;
+        dateStart: string | undefined;
+        dateStop: string | undefined;
+        frequency: number;
+        impressions: number;
+        reach: number;
+        spend: number;
+        raw: {
+            [x: string]: unknown;
+            account_currency?: string | undefined;
+            account_id?: string | undefined;
+            account_name?: string | undefined;
+            actions?: {
+                action_type?: string | undefined;
+                value?: string | undefined;
+            }[] | undefined;
+            ad_id?: string | undefined;
+            ad_name?: string | undefined;
+            campaign_id?: string | undefined;
+            campaign_name?: string | undefined;
+            clicks?: string | undefined;
+            cpc?: string | undefined;
+            cpm?: string | undefined;
+            ctr?: string | undefined;
+            date_start?: string | undefined;
+            date_stop?: string | undefined;
+            frequency?: string | undefined;
+            impressions?: string | undefined;
+            reach?: string | undefined;
+            spend?: string | undefined;
+        };
+    }[]>;
+    verifyApi(accountId?: string | undefined): Promise<Record<string, unknown>>;
+    requireCampaignBudgetMinorUnits(campaign: CampaignRecord): number;
+    expandCampaignBudget(campaign: CampaignRecord, currency: string): number | undefined;
+}
+export {};