cli-meta-ads 0.1.0

package/dist/commands/anomalies.js

@@ -0,0 +1,44 @@
+import { createAction } from "../cli/action.js";
+import { collectAcrossAccounts } from "./helpers.js";
+import { detectAnomalies } from "../domain/analytics.js";
+import { resolveAccountScope } from "../domain/account-scope.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parseDateWindow } from "../utils/date-range.js";
+import { parseThreshold } from "../validators/common.js";
+export function registerAnomaliesCommand(program, deps, state) {
+    program
+        .command("anomalies")
+        .description("Detect campaign-level anomalies from recent daily insights.")
+        .requiredOption("--account <id|all>", "Ad account id or all.")
+        .option("--threshold <percent>", "Percent change threshold.", "20")
+        .action(createAction("anomalies", deps, state, async (context, options) => {
+        const threshold = parseThreshold(options.threshold);
+        const scope = await resolveAccountScope(context, options.account);
+        const service = new MetaAdsService(context.client);
+        const window = parseDateWindow({
+            last: "14d"
+        });
+        const collected = await collectAcrossAccounts(scope.accounts, async (account) => {
+            const rows = await service.getDailyCampaignInsights(account.id, window);
+            const anomalies = detectAnomalies(rows, threshold);
+            return {
+                accountId: account.id,
+                accountName: account.name,
+                anomalies
+            };
+        });
+        return {
+            ok: true,
+            command: "anomalies",
+            data: {
+                accounts: collected.results,
+                threshold,
+                window
+            },
+            partialFailures: collected.failures.map((failure) => ({
+                message: failure.message,
+                scope: failure.accountId
+            }))
+        };
+    }));
+}

package/dist/commands/assets.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 registerAssetCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/assets.js

@@ -0,0 +1,116 @@
+import { createAction } from "../cli/action.js";
+import { requirePermission } from "../auth/guards.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parsePositiveNumber, parseVideoId } from "../validators/common.js";
+import { resolveExistingFilePath } from "../validators/create-spec.js";
+import { resolveSingleAccount } from "./helpers.js";
+export function registerAssetCommands(program, deps, state) {
+    const assets = program.command("assets").description("Asset uploads and video processing visibility.");
+    const images = assets.command("images").description("Image asset uploads.");
+    const videos = assets.command("videos").description("Video asset uploads and processing status.");
+    images
+        .command("upload")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--file <path>", "Local image file path.")
+        .option("--name <name>", "Optional asset name.")
+        .description("Draft or upload an image asset to the ad account.")
+        .action(createAction("assets images upload", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "assets images upload");
+        const absolutePath = await resolveExistingFilePath(options.file, "Image file");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "upload-image",
+            file: absolutePath,
+            name: options.name
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "assets images upload",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Image upload");
+        const asset = await service.uploadAdImage(account.id, absolutePath, options.name);
+        return {
+            ok: true,
+            command: "assets images upload",
+            data: {
+                accountId: account.id,
+                applied: true,
+                asset
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+    videos
+        .command("upload")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--file <path>", "Local video file path.")
+        .option("--name <name>", "Optional asset name.")
+        .option("--wait", "Wait until Meta reports the video as ready.")
+        .option("--poll-ms <ms>", "Polling interval in milliseconds while waiting.", "3000")
+        .option("--timeout-ms <ms>", "Wait timeout in milliseconds.", "90000")
+        .description("Draft or upload a video asset to the ad account.")
+        .action(createAction("assets videos upload", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "assets videos upload");
+        const absolutePath = await resolveExistingFilePath(options.file, "Video file");
+        const pollMs = parsePositiveNumber(options.pollMs ?? "3000", "Poll interval");
+        const timeoutMs = parsePositiveNumber(options.timeoutMs ?? "90000", "Timeout");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "upload-video",
+            file: absolutePath,
+            name: options.name,
+            wait: Boolean(options.wait)
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "assets videos upload",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Video upload");
+        const asset = await service.uploadAdVideo(account.id, absolutePath, options.name);
+        const status = options.wait
+            ? await service.waitForVideoReady(asset.id, { pollMs, timeoutMs })
+            : undefined;
+        return {
+            ok: true,
+            command: "assets videos upload",
+            data: {
+                accountId: account.id,
+                applied: true,
+                asset,
+                status
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+    videos
+        .command("status")
+        .argument("<video-id>", "Video id.")
+        .description("Show the current processing status of an uploaded video.")
+        .action(createAction("assets videos status", deps, state, async (context, videoId) => {
+        const service = new MetaAdsService(context.client);
+        const status = await service.getAdVideoStatus(parseVideoId(videoId));
+        return {
+            ok: true,
+            command: "assets videos status",
+            data: status
+        };
+    }));
+}

package/dist/commands/audiences.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 registerAudienceCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/audiences.js

@@ -0,0 +1,40 @@
+import { createAction } from "../cli/action.js";
+import { resolveSingleAccount } from "./helpers.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parseAudienceId } from "../validators/common.js";
+export function registerAudienceCommands(program, deps, state) {
+    const audiences = program.command("audiences").description("Audience discovery and size estimates.");
+    audiences
+        .command("list")
+        .requiredOption("--account <id>", "Ad account id.")
+        .description("List audiences for an account.")
+        .action(createAction("audiences list", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "audiences list");
+        const service = new MetaAdsService(context.client);
+        const rows = await service.listAudiences(account.id);
+        return {
+            ok: true,
+            command: "audiences list",
+            data: {
+                accountId: account.id,
+                audiences: rows
+            },
+            meta: {
+                count: rows.length
+            }
+        };
+    }));
+    audiences
+        .command("size")
+        .requiredOption("--audience <id>", "Audience id.")
+        .description("Get audience size estimate details.")
+        .action(createAction("audiences size", deps, state, async (context, options) => {
+        const service = new MetaAdsService(context.client);
+        const audience = await service.getAudience(parseAudienceId(options.audience));
+        return {
+            ok: true,
+            command: "audiences size",
+            data: audience
+        };
+    }));
+}

package/dist/commands/auth.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 registerAuthCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/auth.js

@@ -0,0 +1,139 @@
+import { DEFAULT_AUTH_REDIRECT_URI } from "../auth/constants.js";
+import { createAction } from "../cli/action.js";
+import { runInteractiveAuthLogin } from "../auth/login.js";
+import { writeFileConfig } from "../config/file-config.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+function resolveSettingSource(envName, resolvedValue, fallback = "none") {
+    if (process.env[envName]?.trim()) {
+        return "env";
+    }
+    if (resolvedValue) {
+        return fallback;
+    }
+    return "none";
+}
+function isExpired(value) {
+    if (!value) {
+        return undefined;
+    }
+    const expiresAt = new Date(value);
+    if (Number.isNaN(expiresAt.getTime())) {
+        return undefined;
+    }
+    return expiresAt.getTime() <= Date.now();
+}
+export function registerAuthCommands(program, deps, state) {
+    const auth = program.command("auth").description("Authentication and token visibility.");
+    auth
+        .command("status")
+        .description("Show resolved auth state, token source, and a lightweight token probe if possible.")
+        .action(createAction("auth status", deps, state, async (context) => {
+        const service = new MetaAdsService(context.client);
+        let tokenProbe = null;
+        let tokenProbeError;
+        if (context.config.accessToken) {
+            try {
+                tokenProbe = await service.whoAmI();
+            }
+            catch (error) {
+                tokenProbeError = error instanceof Error ? error.message : "Unknown auth probe failure.";
+            }
+        }
+        return {
+            ok: true,
+            command: "auth status",
+            data: {
+                accessTokenExpiresAt: context.config.accessTokenExpiresAt,
+                accessTokenExpired: isExpired(context.config.accessTokenExpiresAt),
+                accessTokenPresent: Boolean(context.config.accessToken),
+                accessTokenSource: resolveSettingSource("META_ACCESS_TOKEN", context.config.accessToken, "config"),
+                apiVersion: context.config.apiVersion,
+                appIdPresent: Boolean(context.config.appId),
+                appIdSource: resolveSettingSource("META_APP_ID", context.config.appId, "config"),
+                appSecretPresent: Boolean(context.config.appSecret),
+                approvalWebhookPresent: Boolean(context.config.approvalWebhook),
+                authConfigIdPresent: Boolean(context.config.authConfigId),
+                authConfigIdSource: resolveSettingSource("META_AUTH_CONFIG_ID", context.config.authConfigId, "config"),
+                authRedirectUri: context.config.authRedirectUri,
+                authRedirectUriSource: process.env.META_AUTH_REDIRECT_URI?.trim()
+                    ? "env"
+                    : context.config.authRedirectUri && context.config.authRedirectUri !== DEFAULT_AUTH_REDIRECT_URI
+                        ? "config"
+                        : "default",
+                configPath: context.config.configPath,
+                defaultAccountId: context.config.defaultAccountId,
+                permissionMode: context.config.permissionMode,
+                tokenProbe,
+                tokenProbeError
+            }
+        };
+    }));
+    auth
+        .command("login")
+        .description("Run Facebook Login for Business and persist the resulting user token locally.")
+        .option("--app-id <id>", "Override the Meta app ID used for the login flow.")
+        .option("--config-id <id>", "Override the Facebook Login for Business configuration ID.")
+        .option("--redirect-uri <url>", "Override the redirect URI used for the login flow.")
+        .option("--no-open-browser", "Do not open a browser automatically; print the login URL and wait for the pasted callback URL.")
+        .action(createAction("auth login", deps, state, async (context, options) => {
+        const login = await runInteractiveAuthLogin(context.config, {
+            appId: options.appId,
+            configId: options.configId,
+            openBrowser: options.openBrowser,
+            redirectUri: options.redirectUri
+        }, {
+            fetchImpl: context.fetchImpl
+        });
+        await writeFileConfig(context.config.configPath, {
+            accessToken: login.accessToken,
+            accessTokenExpiresAt: login.accessTokenExpiresAt,
+            appId: login.appId,
+            authConfigId: login.authConfigId,
+            authRedirectUri: login.authRedirectUri
+        });
+        const warnings = [];
+        if (process.env.META_ACCESS_TOKEN?.trim()) {
+            warnings.push("META_ACCESS_TOKEN is currently set in the environment and will continue to override the stored login token until it is unset.");
+        }
+        if ((options.openBrowser ?? true) && !login.browserOpened) {
+            warnings.push("The browser could not be opened automatically. Complete the login flow manually with the printed login URL.");
+        }
+        return {
+            ok: true,
+            command: "auth login",
+            data: {
+                accessTokenExpiresAt: login.accessTokenExpiresAt,
+                authConfigId: login.authConfigId,
+                authRedirectUri: login.authRedirectUri,
+                browserOpened: login.browserOpened,
+                codeExchangeUsed: login.codeExchangeUsed,
+                configPath: context.config.configPath,
+                tokenSource: "config"
+            },
+            warnings
+        };
+    }));
+    auth
+        .command("logout")
+        .description("Remove any locally stored access token from the CLI config.")
+        .action(createAction("auth logout", deps, state, async (context) => {
+        await writeFileConfig(context.config.configPath, {
+            accessToken: undefined,
+            accessTokenExpiresAt: undefined
+        });
+        const warnings = process.env.META_ACCESS_TOKEN?.trim()
+            ? [
+                "META_ACCESS_TOKEN is still set in the environment and will remain active for this shell until it is unset."
+            ]
+            : undefined;
+        return {
+            ok: true,
+            command: "auth logout",
+            data: {
+                configPath: context.config.configPath,
+                localAccessTokenCleared: true
+            },
+            warnings
+        };
+    }));
+}

package/dist/commands/campaigns.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 registerCampaignCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;

package/dist/commands/campaigns.js

@@ -0,0 +1,273 @@
+import { createAction } from "../cli/action.js";
+import { requirePermission } from "../auth/guards.js";
+import { resolveSingleAccount } from "./helpers.js";
+import { decideBudgetApproval, decideCampaignStatusApproval, submitApprovalRequest } from "../domain/approval-service.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { fromMinorUnits, toMinorUnits } from "../utils/currency.js";
+import { percentChange } from "../utils/date-range.js";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { campaignCreateSpecSchema, readSpecFile } from "../validators/create-spec.js";
+import { parseCampaignId, parsePositiveNumber } from "../validators/common.js";
+function buildApprovalPayload(context, action, resourceId, accountId, changeSummary, reason) {
+    const approvalArgv = action === "budget"
+        ? ["campaigns", "budget", resourceId, "--daily", String(changeSummary.requestedBudget ?? "unknown")]
+        : ["campaigns", action, resourceId];
+    return {
+        action,
+        accountId,
+        approvalReason: reason,
+        argv: approvalArgv,
+        changeSummary,
+        command: approvalArgv.join(" "),
+        requestedAt: new Date().toISOString(),
+        requestedMode: context.config.permissionMode,
+        resourceId,
+        resourceType: "campaign"
+    };
+}
+export function registerCampaignCommands(program, deps, state) {
+    const campaigns = program.command("campaigns").description("Campaign reads, creation, and controlled writes.");
+    campaigns
+        .command("create")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON campaign create spec.")
+        .description("Draft or create a campaign from a JSON spec.")
+        .action(createAction("campaigns create", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "campaigns create");
+        const { spec, specPath } = await readSpecFile(options.spec, campaignCreateSpecSchema, "Campaign create");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "create-campaign",
+            spec,
+            specPath
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "campaigns create",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Campaign create");
+        const campaign = await service.createCampaign(account.id, spec);
+        return {
+            ok: true,
+            command: "campaigns create",
+            data: {
+                accountId: account.id,
+                applied: true,
+                campaign,
+                specPath
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+    campaigns
+        .command("list")
+        .requiredOption("--account <id>", "Ad account id.")
+        .description("List campaigns for an ad account.")
+        .action(createAction("campaigns list", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "campaigns list");
+        const service = new MetaAdsService(context.client);
+        const campaignsList = await service.listCampaigns(account.id);
+        return {
+            ok: true,
+            command: "campaigns list",
+            data: {
+                accountId: account.id,
+                campaigns: campaignsList
+            },
+            meta: {
+                count: campaignsList.length
+            }
+        };
+    }));
+    campaigns
+        .command("get")
+        .argument("<campaign-id>", "Campaign id.")
+        .description("Get campaign details.")
+        .action(createAction("campaigns get", deps, state, async (context, campaignId) => {
+        const service = new MetaAdsService(context.client);
+        const campaign = await service.getCampaign(parseCampaignId(campaignId));
+        return {
+            ok: true,
+            command: "campaigns get",
+            data: campaign
+        };
+    }));
+    campaigns
+        .command("pause")
+        .argument("<campaign-id>", "Campaign id.")
+        .description("Draft or submit approval request to pause a campaign.")
+        .action(createAction("campaigns pause", deps, state, async (context, campaignId) => {
+        const service = new MetaAdsService(context.client);
+        const normalizedId = parseCampaignId(campaignId);
+        const campaign = await service.getCampaign(normalizedId);
+        const decision = decideCampaignStatusApproval("pause");
+        const plan = {
+            action: "pause",
+            approvalRequired: decision.required,
+            campaign,
+            mutation: {
+                status: "PAUSED"
+            },
+            reason: decision.reason
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "campaigns pause",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Campaign pause");
+        const approvalPayload = buildApprovalPayload(context, "pause", normalizedId, campaign.accountId, plan.mutation, decision.reason);
+        await submitApprovalRequest(context, approvalPayload);
+        return {
+            ok: true,
+            command: "campaigns pause",
+            data: {
+                approvalSubmitted: true,
+                payload: approvalPayload
+            },
+            meta: {
+                exitCode: ExitCode.ApprovalRequired,
+                mode: "approval"
+            }
+        };
+    }));
+    campaigns
+        .command("enable")
+        .argument("<campaign-id>", "Campaign id.")
+        .description("Draft or submit approval request to enable a campaign.")
+        .action(createAction("campaigns enable", deps, state, async (context, campaignId) => {
+        const service = new MetaAdsService(context.client);
+        const normalizedId = parseCampaignId(campaignId);
+        const campaign = await service.getCampaign(normalizedId);
+        const decision = decideCampaignStatusApproval("enable");
+        const plan = {
+            action: "enable",
+            approvalRequired: decision.required,
+            campaign,
+            mutation: {
+                status: "ACTIVE"
+            },
+            reason: decision.reason
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "campaigns enable",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Campaign enable");
+        const approvalPayload = buildApprovalPayload(context, "enable", normalizedId, campaign.accountId, plan.mutation, decision.reason);
+        await submitApprovalRequest(context, approvalPayload);
+        return {
+            ok: true,
+            command: "campaigns enable",
+            data: {
+                approvalSubmitted: true,
+                payload: approvalPayload
+            },
+            meta: {
+                exitCode: ExitCode.ApprovalRequired,
+                mode: "approval"
+            }
+        };
+    }));
+    campaigns
+        .command("budget")
+        .argument("<campaign-id>", "Campaign id.")
+        .requiredOption("--daily <amount>", "Daily budget amount in account currency.")
+        .description("Draft or update a campaign-level daily budget.")
+        .action(createAction("campaigns budget", deps, state, async (context, campaignId, options) => {
+        const service = new MetaAdsService(context.client);
+        const normalizedId = parseCampaignId(campaignId);
+        const campaign = await service.getCampaign(normalizedId);
+        if (!campaign.accountId) {
+            throw new AppError("Campaign account id is missing from the provider response.", ExitCode.Provider);
+        }
+        const account = await service.getAccount(campaign.accountId);
+        const currency = account.currency ?? "USD";
+        const currentBudgetMinorUnits = service.requireCampaignBudgetMinorUnits(campaign);
+        const currentBudget = fromMinorUnits(currentBudgetMinorUnits, currency);
+        const requestedBudget = parsePositiveNumber(options.daily, "Daily budget");
+        const change = percentChange(currentBudget, requestedBudget);
+        const decision = decideBudgetApproval(change);
+        const minorUnits = toMinorUnits(requestedBudget, currency);
+        const plan = {
+            action: "budget",
+            approvalRequired: decision.required,
+            campaign,
+            changePercent: change,
+            currency,
+            currentBudget,
+            mutation: {
+                daily_budget: minorUnits
+            },
+            requestedBudget,
+            reason: decision.reason
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "campaigns budget",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Campaign budget");
+        if (decision.required) {
+            const approvalPayload = buildApprovalPayload(context, "budget", normalizedId, campaign.accountId, {
+                currentBudget,
+                currency,
+                requestedBudget
+            }, decision.reason);
+            await submitApprovalRequest(context, approvalPayload);
+            return {
+                ok: true,
+                command: "campaigns budget",
+                data: {
+                    approvalSubmitted: true,
+                    payload: approvalPayload
+                },
+                meta: {
+                    exitCode: ExitCode.ApprovalRequired,
+                    mode: "approval"
+                }
+            };
+        }
+        await service.updateCampaignDailyBudget(normalizedId, minorUnits);
+        return {
+            ok: true,
+            command: "campaigns budget",
+            data: {
+                accountId: campaign.accountId,
+                applied: true,
+                campaignId: normalizedId,
+                currency,
+                currentBudget,
+                requestedBudget
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+}

package/dist/commands/capi.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 registerCapiCommands(program: Command, deps: CliDeps, state: CliRuntimeState): void;