cli-meta-ads 0.1.0

package/dist/client/meta-api-client.d.ts

@@ -0,0 +1,50 @@
+import type { ResolvedConfig } from "../config/types.js";
+export interface MetaRateLimitUsage {
+    app?: Record<string, unknown> | undefined;
+    adAccount?: Record<string, unknown> | undefined;
+    businessUseCase?: Record<string, unknown> | undefined;
+}
+export interface MetaPagedResponse<T> {
+    data: T[];
+    paging?: {
+        cursors?: {
+            after?: string | undefined;
+            before?: string | undefined;
+        } | undefined;
+        next?: string | undefined;
+    } | undefined;
+    summary?: Record<string, unknown> | undefined;
+}
+export interface MetaRequestOptions {
+    body?: Record<string, string | number | boolean | undefined> | undefined;
+    multipart?: Record<string, MetaMultipartValue | undefined> | undefined;
+    method?: "GET" | "POST";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined> | undefined;
+    retryable?: boolean | undefined;
+}
+export interface MetaRequestResult<T> {
+    data: T;
+    usage: MetaRateLimitUsage;
+    headers: Headers;
+}
+export interface FetchLike {
+    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export type MetaMultipartValue = string | number | boolean | Blob | {
+    blob: Blob;
+    filename: string;
+};
+export declare class MetaApiClient {
+    private readonly fetchImpl;
+    private readonly config;
+    constructor(config: ResolvedConfig, fetchImpl?: FetchLike);
+    get apiVersion(): string;
+    request<T>(options: MetaRequestOptions): Promise<MetaRequestResult<T>>;
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<MetaRequestResult<T>>;
+    post<T>(path: string, body?: Record<string, string | number | boolean | undefined>): Promise<MetaRequestResult<T>>;
+    postMultipart<T>(path: string, multipart: Record<string, MetaMultipartValue | undefined>): Promise<MetaRequestResult<T>>;
+    paginate<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<MetaRequestResult<MetaPagedResponse<T>>>;
+    private executeRequest;
+    private extractError;
+}

package/dist/client/meta-api-client.js

@@ -0,0 +1,258 @@
+import { createHmac } from "node:crypto";
+import { createRequire } from "node:module";
+import { setTimeout as sleep } from "node:timers/promises";
+import { requireAccessToken } from "../auth/guards.js";
+import { AppError, ExitCode, MetaApiError } from "../utils/errors.js";
+import { sanitizeText, sanitizeUrl } from "../utils/security.js";
+const require = createRequire(import.meta.url);
+const packageJson = require("../../package.json");
+const USER_AGENT = `cli-meta-ads/${packageJson.version ?? "0.0.0"}`;
+const RETRIABLE_META_CODES = new Set([4, 17, 32, 341, 613, 80001, 80002, 80004]);
+const MAX_PAGINATION_PAGES = 100;
+function buildFormData(params, accessToken, appSecret) {
+    const formData = new FormData();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (value instanceof Blob) {
+            formData.append(key, value);
+            continue;
+        }
+        if (typeof value === "object" && "blob" in value && "filename" in value) {
+            formData.append(key, value.blob, value.filename);
+            continue;
+        }
+        formData.append(key, String(value));
+    }
+    formData.append("access_token", accessToken);
+    if (appSecret) {
+        const proof = createHmac("sha256", appSecret).update(accessToken).digest("hex");
+        formData.append("appsecret_proof", proof);
+    }
+    return formData;
+}
+function parseUsageHeader(value) {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRetriableError(status, metaCode) {
+    return status === 429 || status >= 500 || (metaCode !== undefined && RETRIABLE_META_CODES.has(metaCode));
+}
+function classifyExitCode(status, metaCode) {
+    if (metaCode === 190) {
+        return ExitCode.Auth;
+    }
+    if (metaCode === 200 || metaCode === 10 || metaCode === 270) {
+        return ExitCode.Permission;
+    }
+    if (isRetriableError(status, metaCode)) {
+        return ExitCode.RateLimit;
+    }
+    if (metaCode === 2635) {
+        return ExitCode.VerificationFailed;
+    }
+    return ExitCode.Provider;
+}
+function buildSearchParams(params, accessToken, appSecret) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            searchParams.set(key, String(value));
+        }
+    }
+    searchParams.set("access_token", accessToken);
+    if (appSecret) {
+        const proof = createHmac("sha256", appSecret).update(accessToken).digest("hex");
+        searchParams.set("appsecret_proof", proof);
+    }
+    return searchParams;
+}
+export class MetaApiClient {
+    fetchImpl;
+    config;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    get apiVersion() {
+        return this.config.apiVersion;
+    }
+    async request(options) {
+        const maxAttempts = options.retryable === false ? 1 : 4;
+        const accessToken = requireAccessToken(this.config);
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            try {
+                return await this.executeRequest(options, accessToken);
+            }
+            catch (error) {
+                if (!(error instanceof MetaApiError)) {
+                    throw error;
+                }
+                lastError = error;
+                const retriable = options.retryable !== false && isRetriableError(error.status, error.metaCode);
+                if (!retriable || attempt === maxAttempts) {
+                    throw error;
+                }
+                const backoffMs = 400 * (2 ** (attempt - 1)) + Math.floor(Math.random() * 250);
+                await sleep(backoffMs);
+            }
+        }
+        throw lastError ?? new MetaApiError("Meta request failed.", ExitCode.Provider, { status: 500 });
+    }
+    async get(path, query) {
+        return this.request({
+            method: "GET",
+            path,
+            query,
+            retryable: true
+        });
+    }
+    async post(path, body) {
+        return this.request({
+            method: "POST",
+            path,
+            body,
+            retryable: false
+        });
+    }
+    async postMultipart(path, multipart) {
+        return this.request({
+            method: "POST",
+            multipart,
+            path,
+            retryable: false
+        });
+    }
+    async paginate(path, query) {
+        const collected = [];
+        let after;
+        let lastUsage = {};
+        let summary;
+        let pageCount = 0;
+        do {
+            const pageQuery = {
+                ...(query ?? {}),
+                ...(after ? { after } : {})
+            };
+            const page = await this.get(path, pageQuery);
+            pageCount += 1;
+            collected.push(...page.data.data);
+            lastUsage = page.usage;
+            summary = page.data.summary ?? summary;
+            after = page.data.paging?.cursors?.after;
+            if (!page.data.paging?.next) {
+                after = undefined;
+            }
+            if (after && pageCount >= MAX_PAGINATION_PAGES) {
+                throw new AppError(`Pagination exceeded the safety limit of ${MAX_PAGINATION_PAGES} pages. Refine the query before retrying.`, ExitCode.Provider, {
+                    pageLimit: MAX_PAGINATION_PAGES,
+                    path
+                });
+            }
+        } while (after);
+        return {
+            data: {
+                data: collected,
+                summary
+            },
+            usage: lastUsage,
+            headers: new Headers()
+        };
+    }
+    async executeRequest(options, accessToken) {
+        const baseUrl = `https://graph.facebook.com/${this.config.apiVersion}${options.path}`;
+        const method = options.method ?? "GET";
+        const init = {
+            method,
+            headers: {
+                Accept: "application/json",
+                "User-Agent": USER_AGENT
+            }
+        };
+        let url = baseUrl;
+        if (method === "GET") {
+            const searchParams = buildSearchParams(options.query ?? {}, accessToken, this.config.appSecret);
+            url = `${baseUrl}?${searchParams.toString()}`;
+        }
+        else if (options.multipart) {
+            init.body = buildFormData(options.multipart, accessToken, this.config.appSecret);
+        }
+        else {
+            const bodyParams = buildSearchParams(options.body ?? {}, accessToken, this.config.appSecret);
+            init.headers = {
+                ...init.headers,
+                "Content-Type": "application/x-www-form-urlencoded"
+            };
+            init.body = bodyParams.toString();
+        }
+        const sanitizedRequestUrl = sanitizeUrl(url);
+        const response = await this.fetchImpl(url, init);
+        const usage = {
+            app: parseUsageHeader(response.headers.get("x-app-usage")),
+            adAccount: parseUsageHeader(response.headers.get("x-ad-account-usage")),
+            businessUseCase: parseUsageHeader(response.headers.get("x-business-use-case-usage"))
+        };
+        const text = await response.text();
+        let payload = {};
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                throw new MetaApiError(`Meta returned a non-JSON response with status ${response.status}.`, classifyExitCode(response.status), {
+                    status: response.status,
+                    details: {
+                        contentType: response.headers.get("content-type") ?? undefined,
+                        path: options.path,
+                        requestUrl: sanitizedRequestUrl,
+                        responsePreview: sanitizeText(text.slice(0, 200))
+                    }
+                });
+            }
+        }
+        const errorPayload = this.extractError(payload);
+        if (!response.ok || errorPayload) {
+            const status = response.status;
+            const message = errorPayload?.message ?? `Meta request failed with status ${status}.`;
+            const metaCode = errorPayload?.code;
+            const metaSubcode = errorPayload?.error_subcode;
+            const fbtraceId = errorPayload?.fbtrace_id;
+            throw new MetaApiError(message, classifyExitCode(status, metaCode), {
+                status,
+                metaCode,
+                metaSubcode,
+                fbtraceId,
+                details: {
+                    path: options.path,
+                    requestUrl: sanitizedRequestUrl,
+                    usage,
+                    response: payload
+                }
+            });
+        }
+        return {
+            data: payload,
+            headers: response.headers,
+            usage
+        };
+    }
+    extractError(payload) {
+        if (typeof payload !== "object" || payload === null || !("error" in payload)) {
+            return null;
+        }
+        const errorValue = payload.error;
+        if (typeof errorValue !== "object" || errorValue === null) {
+            return null;
+        }
+        return errorValue;
+    }
+}

package/dist/client/meta-discovery.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedConfig } from "../config/types.js";
+import { MetaApiClient } from "./meta-api-client.js";
+export interface ManagedAccount {
+    id: string;
+    name?: string | undefined;
+    accountStatus?: number | string | undefined;
+    currency?: string | undefined;
+    timezoneName?: string | undefined;
+    source: string;
+    businessId?: string | undefined;
+    businessName?: string | undefined;
+}
+export declare function discoverManagedAccounts(config: ResolvedConfig, client?: MetaApiClient): Promise<ManagedAccount[]>;

package/dist/client/meta-discovery.js

@@ -0,0 +1,88 @@
+import { AppError, ExitCode, MetaApiError } from "../utils/errors.js";
+import { normalizeAdAccountId } from "../utils/ids.js";
+import { MetaApiClient } from "./meta-api-client.js";
+function normalizeAccountNode(node, source, business) {
+    const rawId = node.account_id ?? node.id;
+    if (!rawId) {
+        throw new AppError("Meta account discovery returned an account without an id.", ExitCode.Provider);
+    }
+    return {
+        id: normalizeAdAccountId(rawId),
+        name: node.name,
+        accountStatus: node.account_status,
+        businessId: business?.id,
+        businessName: business?.name,
+        currency: node.currency,
+        source,
+        timezoneName: node.timezone_name
+    };
+}
+function dedupeAccounts(accounts) {
+    const byId = new Map();
+    for (const account of accounts) {
+        if (!byId.has(account.id)) {
+            byId.set(account.id, account);
+        }
+    }
+    return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+async function swallowDiscoveryError(promise) {
+    try {
+        return await promise;
+    }
+    catch (error) {
+        if (error instanceof MetaApiError) {
+            if (error.exitCode === ExitCode.Auth || error.exitCode === ExitCode.RateLimit) {
+                throw error;
+            }
+            return null;
+        }
+        throw error;
+    }
+}
+export async function discoverManagedAccounts(config, client = new MetaApiClient(config)) {
+    const discovered = [];
+    const [meAccounts, meAssigned, businesses] = await Promise.all([
+        swallowDiscoveryError(client.paginate("/me/adaccounts", {
+            fields: "id,account_id,name,account_status,currency,timezone_name",
+            limit: 500
+        })),
+        swallowDiscoveryError(client.get("/me", {
+            fields: "assigned_ad_accounts{id,account_id,name,account_status,currency,timezone_name}"
+        })),
+        swallowDiscoveryError(client.paginate("/me/businesses", {
+            fields: "id,name",
+            limit: 200
+        }))
+    ]);
+    if (meAccounts) {
+        discovered.push(...meAccounts.data.data.map((account) => normalizeAccountNode(account, "/me/adaccounts")));
+    }
+    if (meAssigned?.data.assigned_ad_accounts?.data) {
+        discovered.push(...meAssigned.data.assigned_ad_accounts.data.map((account) => normalizeAccountNode(account, "/me?fields=assigned_ad_accounts")));
+    }
+    if (businesses) {
+        const expandedBusinesses = [];
+        for (const business of businesses.data.data) {
+            const expanded = await swallowDiscoveryError(client.get(`/${business.id}`, {
+                fields: [
+                    "id",
+                    "name",
+                    "owned_ad_accounts.limit(500){id,account_id,name,account_status,currency,timezone_name}",
+                    "client_ad_accounts.limit(500){id,account_id,name,account_status,currency,timezone_name}"
+                ].join(",")
+            }));
+            expandedBusinesses.push(expanded);
+        }
+        for (const expanded of expandedBusinesses) {
+            if (!expanded) {
+                continue;
+            }
+            const businessNode = expanded.data;
+            const owned = businessNode.owned_ad_accounts?.data ?? [];
+            const clientAccounts = businessNode.client_ad_accounts?.data ?? [];
+            discovered.push(...owned.map((account) => normalizeAccountNode(account, "business.owned_ad_accounts", businessNode)), ...clientAccounts.map((account) => normalizeAccountNode(account, "business.client_ad_accounts", businessNode)));
+        }
+    }
+    return dedupeAccounts(discovered);
+}

package/dist/commands/accounts.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliRuntimeState } from "../cli/action.js";
+import type { CliDeps } from "../cli/context.js";
+export declare function registerAccountsCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/accounts.js

@@ -0,0 +1,42 @@
+import { createAction } from "../cli/action.js";
+import { writeFileConfig } from "../config/file-config.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { normalizeAdAccountId } from "../utils/ids.js";
+export function registerAccountsCommands(program, deps, state) {
+    const accounts = program.command("accounts").description("Managed account discovery and local defaults.");
+    accounts
+        .command("list")
+        .description("List all managed ad accounts accessible to the current token.")
+        .action(createAction("accounts list", deps, state, async (context) => {
+        const service = new MetaAdsService(context.client);
+        const accountsList = await service.listManagedAccounts(context.config);
+        return {
+            ok: true,
+            command: "accounts list",
+            data: {
+                accounts: accountsList
+            },
+            meta: {
+                count: accountsList.length
+            }
+        };
+    }));
+    accounts
+        .command("set-default")
+        .argument("<ad-account-id>", "Default ad account id.")
+        .description("Persist the default ad account id in the local CLI config.")
+        .action(createAction("accounts set-default", deps, state, async (context, accountId) => {
+        const normalized = normalizeAdAccountId(accountId);
+        await writeFileConfig(context.config.configPath, {
+            defaultAccountId: normalized
+        });
+        return {
+            ok: true,
+            command: "accounts set-default",
+            data: {
+                defaultAccountId: normalized,
+                configPath: context.config.configPath
+            }
+        };
+    }));
+}

package/dist/commands/ads.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliRuntimeState } from "../cli/action.js";
+import type { CliDeps } from "../cli/context.js";
+export declare function registerAdsCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/ads.js

@@ -0,0 +1,148 @@
+import { requirePermission } from "../auth/guards.js";
+import { createAction } from "../cli/action.js";
+import { analyzeCreativeFatigue } from "../domain/analytics.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parseDateWindow } from "../utils/date-range.js";
+import { adCreateSpecSchema, readSpecFile } from "../validators/create-spec.js";
+import { parseAdId, parseCampaignId } from "../validators/common.js";
+import { resolveSingleAccount, toMetaSort } from "./helpers.js";
+export function registerAdsCommands(program, deps, state) {
+    const ads = program.command("ads").description("Ad reads, creation, performance and fatigue analysis.");
+    ads
+        .command("create")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON ad create spec.")
+        .description("Draft or create an ad from a JSON spec.")
+        .action(createAction("ads create", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "ads create");
+        const { spec, specPath } = await readSpecFile(options.spec, adCreateSpecSchema, "Ad create");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "create-ad",
+            spec,
+            specPath
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "ads create",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Ad create");
+        const ad = await service.createAd(account.id, spec);
+        return {
+            ok: true,
+            command: "ads create",
+            data: {
+                accountId: account.id,
+                ad,
+                applied: true,
+                specPath
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+    ads
+        .command("list")
+        .requiredOption("--campaign <id>", "Campaign id.")
+        .description("List ads under a campaign.")
+        .action(createAction("ads list", deps, state, async (context, options) => {
+        const service = new MetaAdsService(context.client);
+        const campaignId = parseCampaignId(options.campaign);
+        const rows = await service.listAdsByCampaign(campaignId);
+        return {
+            ok: true,
+            command: "ads list",
+            data: {
+                ads: rows,
+                campaignId
+            },
+            meta: {
+                count: rows.length
+            }
+        };
+    }));
+    ads
+        .command("performance")
+        .requiredOption("--campaign <id>", "Campaign id.")
+        .option("--last <window>", "Relative time window like 7d or 30d, unless --from/--to is used.")
+        .option("--from <date>", "Start date in YYYY-MM-DD.")
+        .option("--to <date>", "End date in YYYY-MM-DD.")
+        .option("--sort <metric>", "Sort metric such as ctr or spend.")
+        .description("Ad-level performance for a campaign.")
+        .action(createAction("ads performance", deps, state, async (context, options) => {
+        const service = new MetaAdsService(context.client);
+        const campaignId = parseCampaignId(options.campaign);
+        const window = parseDateWindow({
+            from: options.from,
+            last: options.last,
+            to: options.to
+        });
+        const rows = await service.getAdPerformanceByCampaign(campaignId, window, toMetaSort(options.sort));
+        return {
+            ok: true,
+            command: "ads performance",
+            data: {
+                campaignId,
+                rows,
+                window
+            },
+            meta: {
+                count: rows.length
+            }
+        };
+    }));
+    ads
+        .command("fatigue")
+        .requiredOption("--campaign <id>", "Campaign id.")
+        .option("--last <window>", "Relative time window like 30d.", "30d")
+        .description("Local creative fatigue analysis on ad-level trends.")
+        .action(createAction("ads fatigue", deps, state, async (context, options) => {
+        const service = new MetaAdsService(context.client);
+        const campaignId = parseCampaignId(options.campaign);
+        const window = parseDateWindow({
+            last: options.last
+        });
+        const rows = await service.getDailyAdInsights(campaignId, window);
+        const fatigue = analyzeCreativeFatigue(rows);
+        return {
+            ok: true,
+            command: "ads fatigue",
+            data: {
+                campaignId,
+                fatigue,
+                window
+            },
+            meta: {
+                count: fatigue.length
+            }
+        };
+    }));
+    ads
+        .command("preview")
+        .argument("<ad-id>", "Ad id.")
+        .option("--ad-format <format>", "Optional ad_format override for previews.")
+        .description("Fetch preview payloads for an ad.")
+        .action(createAction("ads preview", deps, state, async (context, adId, options) => {
+        const service = new MetaAdsService(context.client);
+        const previews = await service.getAdPreview(parseAdId(adId), options.adFormat);
+        return {
+            ok: true,
+            command: "ads preview",
+            data: {
+                adId,
+                previews
+            },
+            meta: {
+                count: previews.length
+            }
+        };
+    }));
+}

package/dist/commands/adsets.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliRuntimeState } from "../cli/action.js";
+import type { CliDeps } from "../cli/context.js";
+export declare function registerAdSetCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/adsets.js

@@ -0,0 +1,49 @@
+import { createAction } from "../cli/action.js";
+import { requirePermission } from "../auth/guards.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { adSetCreateSpecSchema, readSpecFile } from "../validators/create-spec.js";
+import { resolveSingleAccount } from "./helpers.js";
+export function registerAdSetCommands(program, deps, state) {
+    const adSets = program.command("adsets").description("Ad set creation workflows.");
+    adSets
+        .command("create")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON ad set create spec.")
+        .description("Draft or create an ad set from a JSON spec.")
+        .action(createAction("adsets create", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "adsets create");
+        const { spec, specPath } = await readSpecFile(options.spec, adSetCreateSpecSchema, "Ad set create");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "create-adset",
+            spec,
+            specPath
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "adsets create",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Ad set create");
+        const adSet = await service.createAdSet(account.id, spec);
+        return {
+            ok: true,
+            command: "adsets create",
+            data: {
+                accountId: account.id,
+                adSet,
+                applied: true,
+                specPath
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+}

package/dist/commands/anomalies.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliRuntimeState } from "../cli/action.js";
+import type { CliDeps } from "../cli/context.js";
+export declare function registerAnomaliesCommand(program: Command, deps: CliDeps, state: CliRuntimeState): void;