cli-meta-ads 0.1.0

package/dist/commands/capi.js

@@ -0,0 +1,64 @@
+import { createAction } from "../cli/action.js";
+import { resolveSingleAccount } from "./helpers.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parseTimeWindow } from "../utils/date-range.js";
+export function registerCapiCommands(program, deps, state) {
+    const capi = program.command("capi").description("Best-effort Conversions API visibility.");
+    capi
+        .command("status")
+        .requiredOption("--account <id>", "Ad account id.")
+        .description("Infer CAPI connectivity from pixel/server event fields.")
+        .action(createAction("capi status", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "capi status");
+        const service = new MetaAdsService(context.client);
+        const pixels = await service.listPixels(account.id);
+        return {
+            ok: true,
+            command: "capi status",
+            data: {
+                accountId: account.id,
+                bestEffort: true,
+                pixels: pixels.map((entry) => ({
+                    capiConnected: entry.serverEventsBusinessIds.length > 0,
+                    id: entry.id,
+                    lastFiredTime: entry.lastFiredTime,
+                    name: entry.name,
+                    serverEventsBusinessIds: entry.serverEventsBusinessIds
+                }))
+            },
+            warnings: [
+                "Meta does not expose a single dedicated CAPI health endpoint here; this command infers status from officially documented Ads Pixel fields."
+            ]
+        };
+    }));
+    capi
+        .command("events")
+        .requiredOption("--account <id>", "Ad account id.")
+        .option("--last <window>", "Relative time window like 24h.", "24h")
+        .description("Show recent server-side event hints from pixel fields.")
+        .action(createAction("capi events", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "capi events");
+        const window = parseTimeWindow(options.last ?? "24h");
+        const service = new MetaAdsService(context.client);
+        const pixels = await service.listPixels(account.id);
+        const rows = pixels
+            .filter((entry) => entry.serverEventsBusinessIds.length > 0)
+            .filter((entry) => {
+            const marker = entry.lastFiredTime ?? entry.eventTimeMax;
+            return marker ? new Date(marker) >= window.since : false;
+        });
+        return {
+            ok: true,
+            command: "capi events",
+            data: {
+                accountId: account.id,
+                bestEffort: true,
+                pixels: rows,
+                window
+            },
+            warnings: [
+                "This view is based on Ads Pixel/server-event fields and is not a dedicated Conversions API event log."
+            ]
+        };
+    }));
+}

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

package/dist/commands/creatives.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 { creativeCreateSpecSchema, readSpecFile } from "../validators/create-spec.js";
+import { resolveSingleAccount } from "./helpers.js";
+export function registerCreativeCommands(program, deps, state) {
+    const creatives = program.command("creatives").description("Creative creation workflows.");
+    creatives
+        .command("create")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON creative create spec.")
+        .description("Draft or create a supported creative from a JSON spec.")
+        .action(createAction("creatives create", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "creatives create");
+        const { spec, specPath } = await readSpecFile(options.spec, creativeCreateSpecSchema, "Creative create");
+        const service = new MetaAdsService(context.client);
+        const plan = {
+            accountId: account.id,
+            action: "create-creative",
+            spec,
+            specPath
+        };
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "creatives create",
+                data: plan,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Creative create");
+        const creative = await service.createCreative(account.id, spec);
+        return {
+            ok: true,
+            command: "creatives create",
+            data: {
+                accountId: account.id,
+                applied: true,
+                creative,
+                specPath
+            },
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+}

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

package/dist/commands/diagnostics.js

@@ -0,0 +1,88 @@
+import { createAction } from "../cli/action.js";
+import { requireAccessToken } from "../auth/guards.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { ExitCode } from "../utils/errors.js";
+import { resolveSingleAccount } from "./helpers.js";
+export function registerDiagnosticCommands(program, deps, state) {
+    program
+        .command("whoami")
+        .description("Resolve /me against the current token.")
+        .action(createAction("whoami", deps, state, async (context) => {
+        requireAccessToken(context.config);
+        const service = new MetaAdsService(context.client);
+        const identity = await service.whoAmI();
+        return {
+            ok: true,
+            command: "whoami",
+            data: identity
+        };
+    }));
+    program
+        .command("doctor")
+        .option("--account <id>", "Optional account id to verify account-level reachability.")
+        .description("Run local and remote health checks for config, auth and API reachability.")
+        .action(createAction("doctor", deps, state, async (context, options) => {
+        const checks = [];
+        checks.push({
+            check: "config",
+            detail: context.config.configPath,
+            status: "ok"
+        });
+        checks.push({
+            check: "meta_access_token",
+            status: context.config.accessToken ? "ok" : "fail"
+        });
+        checks.push({
+            check: "approval_webhook",
+            status: context.config.approvalWebhook ? "ok" : "warn"
+        });
+        if (context.config.accessToken) {
+            const service = new MetaAdsService(context.client);
+            const whoAmI = await service.whoAmI();
+            checks.push({
+                check: "whoami",
+                detail: whoAmI.name ?? whoAmI.id,
+                status: "ok"
+            });
+            const selectedAccount = options.account ?? context.config.defaultAccountId;
+            if (selectedAccount) {
+                const accountScope = await resolveSingleAccount(context, selectedAccount, "doctor");
+                const account = await service.getAccount(accountScope.id);
+                checks.push({
+                    check: "account",
+                    detail: account.name ?? accountScope.id,
+                    status: "ok"
+                });
+            }
+        }
+        const hasFailure = checks.some((entry) => entry.status === "fail");
+        return {
+            ok: true,
+            command: "doctor",
+            data: {
+                checks
+            },
+            meta: {
+                exitCode: hasFailure ? ExitCode.VerificationFailed : ExitCode.Ok
+            }
+        };
+    }));
+    program
+        .command("verify-api")
+        .option("--account <id>", "Optional account id to verify campaigns and insights.")
+        .description("Verify auth, account reachability, campaign reads and insights compatibility.")
+        .action(createAction("verify-api", deps, state, async (context, options) => {
+        requireAccessToken(context.config);
+        const service = new MetaAdsService(context.client);
+        const selectedAccount = options.account ?? context.config.defaultAccountId;
+        const account = selectedAccount
+            ? (await resolveSingleAccount(context, selectedAccount, "verify-api")).id
+            : undefined;
+        const verification = await service.verifyApi(account);
+        return {
+            ok: true,
+            command: "verify-api",
+            data: verification
+        };
+    }));
+}

package/dist/commands/helpers.d.ts

@@ -0,0 +1,13 @@
+import type { CommandContext } from "../cli/context.js";
+import type { ManagedAccount } from "../client/meta-discovery.js";
+import type { DateWindow } from "../utils/date-range.js";
+export declare function toMetaSort(metric?: string | undefined): string | undefined;
+export declare function collectAcrossAccounts<T>(accounts: ManagedAccount[], run: (account: ManagedAccount) => Promise<T>): Promise<{
+    failures: Array<{
+        accountId: string;
+        message: string;
+    }>;
+    results: T[];
+}>;
+export declare function buildFixedWindow(period: "daily" | "weekly" | "monthly"): DateWindow;
+export declare function resolveSingleAccount(context: CommandContext, selection: string | undefined, operation: string): Promise<ManagedAccount>;

package/dist/commands/helpers.js

@@ -0,0 +1,50 @@
+import { resolveAccountScope } from "../domain/account-scope.js";
+import { buildRecentDateWindow } from "../utils/date-range.js";
+import { AppError, ExitCode } from "../utils/errors.js";
+export function toMetaSort(metric) {
+    if (!metric) {
+        return undefined;
+    }
+    if (metric.endsWith("_ascending") || metric.endsWith("_descending")) {
+        return metric;
+    }
+    return `${metric}_descending`;
+}
+export async function collectAcrossAccounts(accounts, run) {
+    const settled = await Promise.allSettled(accounts.map((account) => run(account)));
+    const results = [];
+    const failures = [];
+    settled.forEach((entry, index) => {
+        const account = accounts[index];
+        if (!account) {
+            return;
+        }
+        if (entry.status === "fulfilled") {
+            results.push(entry.value);
+            return;
+        }
+        failures.push({
+            accountId: account.id,
+            message: entry.reason instanceof Error ? entry.reason.message : "Unknown error"
+        });
+    });
+    return { failures, results };
+}
+export function buildFixedWindow(period) {
+    const days = period === "daily" ? 1 : period === "weekly" ? 7 : 30;
+    return buildRecentDateWindow(days);
+}
+export async function resolveSingleAccount(context, selection, operation) {
+    if (selection?.trim().toLowerCase() === "all") {
+        throw new AppError(`${operation} requires a single ad account. --account all is not supported for this command.`, ExitCode.Usage);
+    }
+    const scope = await resolveAccountScope(context, selection);
+    const account = scope.accounts[0];
+    if (!account) {
+        throw new AppError(`${operation} could not resolve a single ad account.`, ExitCode.VerificationFailed);
+    }
+    if (scope.accounts.length > 1) {
+        throw new AppError(`${operation} resolved multiple accounts unexpectedly.`, ExitCode.VerificationFailed);
+    }
+    return account;
+}

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

package/dist/commands/launch.js

@@ -0,0 +1,109 @@
+import { requirePermission } from "../auth/guards.js";
+import { createAction } from "../cli/action.js";
+import { LaunchService } from "../domain/launch-service.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { readLaunchSpecFile, requireReceiptPath } from "../validators/launch-spec.js";
+import { resolveSingleAccount } from "./helpers.js";
+export function registerLaunchCommands(program, deps, state) {
+    const launch = program.command("launch").description("Validated, resumable launch execution from a single spec.");
+    launch
+        .command("validate")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON launch spec.")
+        .description("Validate a launch spec, refs, and referenced asset files.")
+        .action(createAction("launch validate", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "launch validate");
+        const { spec, specPath } = await readLaunchSpecFile(options.spec);
+        const service = new LaunchService(new MetaAdsService(context.client));
+        const result = service.validate(account.id, specPath, spec);
+        return {
+            ok: true,
+            command: "launch validate",
+            data: result.data,
+            warnings: result.warnings
+        };
+    }));
+    launch
+        .command("plan")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON launch spec.")
+        .description("Render the ordered launch plan without creating anything.")
+        .action(createAction("launch plan", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "launch plan");
+        const { spec, specPath } = await readLaunchSpecFile(options.spec);
+        const service = new LaunchService(new MetaAdsService(context.client));
+        const result = service.buildPlan(account.id, specPath, spec);
+        return {
+            ok: true,
+            command: "launch plan",
+            data: result.data,
+            warnings: result.warnings
+        };
+    }));
+    launch
+        .command("apply")
+        .requiredOption("--account <id>", "Ad account id.")
+        .requiredOption("--spec <path>", "Path to a JSON launch spec.")
+        .option("--receipt <path>", "Optional receipt output path.")
+        .description("Draft or execute the full launch spec and persist a resumable receipt.")
+        .action(createAction("launch apply", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "launch apply");
+        const { spec, specPath } = await readLaunchSpecFile(options.spec);
+        const service = new LaunchService(new MetaAdsService(context.client));
+        if (!context.apply) {
+            const result = service.buildPlan(account.id, specPath, spec);
+            return {
+                ok: true,
+                command: "launch apply",
+                data: result.data,
+                warnings: result.warnings,
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Launch apply");
+        const result = await service.apply({
+            accountId: account.id,
+            receiptPath: options.receipt,
+            spec,
+            specPath
+        });
+        return {
+            ok: true,
+            command: "launch apply",
+            data: result.data,
+            warnings: result.warnings,
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+    launch
+        .command("resume")
+        .requiredOption("--receipt <path>", "Path to an existing launch receipt.")
+        .description("Resume a previously interrupted launch receipt.")
+        .action(createAction("launch resume", deps, state, async (context, options) => {
+        const service = new LaunchService(new MetaAdsService(context.client));
+        if (!context.apply) {
+            return {
+                ok: true,
+                command: "launch resume",
+                data: await service.previewResume(requireReceiptPath(options.receipt)),
+                meta: {
+                    mode: "draft"
+                }
+            };
+        }
+        requirePermission(context.config, "write", "Launch resume");
+        const result = await service.resume(requireReceiptPath(options.receipt));
+        return {
+            ok: true,
+            command: "launch resume",
+            data: result,
+            meta: {
+                mode: "write"
+            }
+        };
+    }));
+}

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

package/dist/commands/performance.js

@@ -0,0 +1,55 @@
+import { createAction } from "../cli/action.js";
+import { collectAcrossAccounts, toMetaSort } from "./helpers.js";
+import { summarizePerformance } 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 { parseBreakdowns } from "../validators/common.js";
+export function registerPerformanceCommand(program, deps, state) {
+    program
+        .command("performance")
+        .description("Campaign performance from the Meta Insights API.")
+        .option("--last <window>", "Relative time window like 7d or 30d, unless --from/--to is used.")
+        .option("--account <id|all>", "Ad account id or all.")
+        .option("--campaign <name>", "Case-insensitive campaign name filter.")
+        .option("--from <date>", "Start date in YYYY-MM-DD.")
+        .option("--to <date>", "End date in YYYY-MM-DD.")
+        .option("--breakdown <values>", "Comma-separated breakdowns, e.g. age,gender.")
+        .option("--sort <metric>", "Sort metric, e.g. ctr or spend.")
+        .action(createAction("performance", deps, state, async (context, options) => {
+        const window = parseDateWindow({
+            from: options.from,
+            last: options.last,
+            to: options.to
+        });
+        const scope = await resolveAccountScope(context, options.account);
+        const breakdowns = parseBreakdowns(options.breakdown);
+        const sort = toMetaSort(options.sort);
+        const service = new MetaAdsService(context.client);
+        const collected = await collectAcrossAccounts(scope.accounts, async (account) => {
+            const rows = await service.getPerformanceByAccount(account.id, window, breakdowns, options.campaign, sort);
+            return {
+                accountId: account.id,
+                accountName: account.name,
+                rows,
+                summary: summarizePerformance(rows)
+            };
+        });
+        return {
+            ok: true,
+            command: "performance",
+            data: {
+                accounts: collected.results,
+                window
+            },
+            meta: {
+                accountSelection: scope.selection,
+                count: collected.results.length
+            },
+            partialFailures: collected.failures.map((failure) => ({
+                message: failure.message,
+                scope: failure.accountId
+            }))
+        };
+    }));
+}

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

package/dist/commands/pixel.js

@@ -0,0 +1,68 @@
+import { createAction } from "../cli/action.js";
+import { resolveSingleAccount } from "./helpers.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+import { parseTimeWindow } from "../utils/date-range.js";
+function derivePixelHealth(pixel) {
+    if (pixel.isUnavailable) {
+        return "unavailable";
+    }
+    if (!pixel.lastFiredTime) {
+        return "unknown";
+    }
+    const ageMs = Date.now() - new Date(pixel.lastFiredTime).getTime();
+    return ageMs <= 48 * 60 * 60 * 1000 ? "healthy" : "stale";
+}
+export function registerPixelCommands(program, deps, state) {
+    const pixel = program.command("pixel").description("Pixel health and event visibility.");
+    pixel
+        .command("status")
+        .requiredOption("--account <id>", "Ad account id.")
+        .description("List pixel health for an account.")
+        .action(createAction("pixel status", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "pixel status");
+        const service = new MetaAdsService(context.client);
+        const pixels = await service.listPixels(account.id);
+        return {
+            ok: true,
+            command: "pixel status",
+            data: {
+                accountId: account.id,
+                pixels: pixels.map((entry) => ({
+                    ...entry,
+                    health: derivePixelHealth(entry)
+                }))
+            },
+            meta: {
+                count: pixels.length
+            }
+        };
+    }));
+    pixel
+        .command("events")
+        .requiredOption("--account <id>", "Ad account id.")
+        .option("--last <window>", "Relative time window like 24h.", "24h")
+        .description("Show recent pixel event activity using provider-exposed pixel stats.")
+        .action(createAction("pixel events", deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, "pixel events");
+        const window = parseTimeWindow(options.last ?? "24h");
+        const service = new MetaAdsService(context.client);
+        const pixels = await service.listPixels(account.id);
+        const recent = pixels.filter((entry) => {
+            const marker = entry.lastFiredTime ?? entry.eventTimeMax;
+            return marker ? new Date(marker) >= window.since : false;
+        });
+        return {
+            ok: true,
+            command: "pixel events",
+            data: {
+                accountId: account.id,
+                note: "Event visibility is derived from Ads Pixel reference fields such as event_stats and last_fired_time.",
+                pixels: recent,
+                window
+            },
+            meta: {
+                count: recent.length
+            }
+        };
+    }));
+}

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

package/dist/commands/report.js

@@ -0,0 +1,30 @@
+import { createAction } from "../cli/action.js";
+import { buildFixedWindow, resolveSingleAccount } from "./helpers.js";
+import { buildReport } from "../domain/analytics.js";
+import { MetaAdsService } from "../domain/meta-ads-service.js";
+function registerReportVariant(parent, name, deps, state) {
+    parent
+        .command(name)
+        .requiredOption("--account <id>", "Ad account id.")
+        .description(`Generate a ${name} performance report.`)
+        .action(createAction(`report ${name}`, deps, state, async (context, options) => {
+        const account = await resolveSingleAccount(context, options.account, `report ${name}`);
+        const service = new MetaAdsService(context.client);
+        const window = buildFixedWindow(name);
+        const rows = await service.getPerformanceByAccount(account.id, window, [], undefined, undefined);
+        return {
+            ok: true,
+            command: `report ${name}`,
+            data: {
+                accountId: account.id,
+                report: buildReport(name, window, rows)
+            }
+        };
+    }));
+}
+export function registerReportCommands(program, deps, state) {
+    const report = program.command("report").description("Predefined reporting views.");
+    registerReportVariant(report, "daily", deps, state);
+    registerReportVariant(report, "weekly", deps, state);
+    registerReportVariant(report, "monthly", deps, state);
+}

package/dist/config/file-config.d.ts

@@ -0,0 +1,6 @@
+import type { OutputFormat } from "../types.js";
+import type { ConfigOverrides, FileConfig, ResolvedConfig } from "./types.js";
+export declare function resolveDefaultConfigPath(): string;
+export declare function detectConfiguredOutputFormat(configPath?: string): Promise<OutputFormat | undefined>;
+export declare function loadResolvedConfig(overrides?: ConfigOverrides): Promise<ResolvedConfig>;
+export declare function writeFileConfig(configPath: string, partial: Partial<FileConfig>): Promise<void>;