cli-meta-ads 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "./cli/build-cli.js";
+const exitCode = await runCli(process.argv.slice(2), {
+    io: {
+        stderr: process.stderr,
+        stdout: process.stdout
+    }
+});
+process.exitCode = exitCode;

package/dist/output/render.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFailureShape, CommandSuccess } from "../types.js";
+export declare function renderSuccess(result: CommandSuccess<unknown>, asJson: boolean): string;
+export declare function renderFailure(result: CommandFailureShape, asJson: boolean): string;

package/dist/output/render.js

@@ -0,0 +1,103 @@
+function isScalar(value) {
+    return value === null || value === undefined || typeof value !== "object";
+}
+function stringifyScalar(value) {
+    if (value === null || value === undefined) {
+        return "-";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function stringWidth(value) {
+    return Array.from(value).length;
+}
+function padCell(value, width) {
+    const padding = Math.max(0, width - stringWidth(value));
+    return `${value}${" ".repeat(padding)}`;
+}
+function renderTable(rows) {
+    if (rows.length === 0) {
+        return "(empty)";
+    }
+    const headers = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+    const widths = headers.map((header) => Math.max(stringWidth(header), ...rows.map((row) => stringWidth(stringifyScalar(row[header])))));
+    const headerLine = headers
+        .map((header, index) => padCell(header, widths[index] ?? stringWidth(header)))
+        .join("  ");
+    const divider = widths.map((width) => "-".repeat(width)).join("  ");
+    const body = rows
+        .map((row) => headers
+        .map((header, index) => padCell(stringifyScalar(row[header]), widths[index] ?? stringWidth(header)))
+        .join("  "))
+        .join("\n");
+    return [headerLine, divider, body].join("\n");
+}
+function renderValue(value, indent = 0) {
+    const prefix = " ".repeat(indent);
+    if (isScalar(value)) {
+        return `${prefix}${stringifyScalar(value)}`;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return `${prefix}(empty)`;
+        }
+        if (value.every((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))) {
+            return renderTable(value)
+                .split("\n")
+                .map((line) => `${prefix}${line}`)
+                .join("\n");
+        }
+        return value
+            .map((entry) => `${prefix}- ${renderValue(entry, indent + 2).trimStart()}`)
+            .join("\n");
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return `${prefix}(empty)`;
+    }
+    return entries
+        .map(([key, entryValue]) => {
+        if (isScalar(entryValue)) {
+            return `${prefix}${key}: ${stringifyScalar(entryValue)}`;
+        }
+        return `${prefix}${key}:\n${renderValue(entryValue, indent + 2)}`;
+    })
+        .join("\n");
+}
+export function renderSuccess(result, asJson) {
+    if (asJson) {
+        return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const sections = [
+        `command: ${result.command}`,
+        renderValue(result.data)
+    ];
+    if (result.warnings && result.warnings.length > 0) {
+        sections.push(`warnings:\n${renderValue(result.warnings, 2)}`);
+    }
+    if (result.partialFailures && result.partialFailures.length > 0) {
+        sections.push(`partialFailures:\n${renderValue(result.partialFailures, 2)}`);
+    }
+    if (result.meta && Object.keys(result.meta).length > 0) {
+        sections.push(`meta:\n${renderValue(result.meta, 2)}`);
+    }
+    return `${sections.join("\n\n")}\n`;
+}
+export function renderFailure(result, asJson) {
+    if (asJson) {
+        return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const sections = [
+        `command: ${result.command}`,
+        `error: ${result.error}`
+    ];
+    if (result.meta && Object.keys(result.meta).length > 0) {
+        sections.push(`meta:\n${renderValue(result.meta, 2)}`);
+    }
+    return `${sections.join("\n\n")}\n`;
+}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+export type PermissionMode = "read" | "write" | "admin";
+export type OutputFormat = "text" | "json";
+export interface PartialFailure {
+    scope: string;
+    message: string;
+    code?: number | string | undefined;
+}
+export interface CommandMeta {
+    command: string;
+    warnings?: string[] | undefined;
+    meta?: Record<string, unknown> | undefined;
+    partialFailures?: PartialFailure[] | undefined;
+}
+export interface CommandSuccess<T> extends CommandMeta {
+    ok: true;
+    data: T;
+}
+export interface CommandFailureShape extends CommandMeta {
+    ok: false;
+    error: string;
+}
+export type CommandResult<T> = CommandSuccess<T>;
+export interface GlobalOptions {
+    apiVersion?: string | undefined;
+    apply?: boolean | undefined;
+    config?: string | undefined;
+    debug?: boolean | undefined;
+    json?: boolean | undefined;
+    mode?: PermissionMode | undefined;
+}
+export interface ApprovalRequestPayload {
+    requestedAt: string;
+    action: string;
+    command: string;
+    resourceType: string;
+    resourceId: string;
+    accountId?: string | undefined;
+    approvalReason: string;
+    requestedMode: PermissionMode;
+    argv: string[];
+    changeSummary: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/currency.d.ts

@@ -0,0 +1,4 @@
+export declare function currencyMinorUnitFactor(currency: string): number;
+export declare function toMinorUnits(amount: number, currency: string): number;
+export declare function fromMinorUnits(amount: number | string, currency: string): number;
+export declare function formatCurrency(amount: number, currency: string): string;

package/dist/utils/currency.js

@@ -0,0 +1,40 @@
+const ZERO_DECIMAL_CURRENCIES = new Set([
+    "BIF",
+    "CLP",
+    "DJF",
+    "GNF",
+    "JPY",
+    "KMF",
+    "KRW",
+    "MGA",
+    "PYG",
+    "RWF",
+    "UGX",
+    "VND",
+    "VUV",
+    "XAF",
+    "XOF",
+    "XPF"
+]);
+export function currencyMinorUnitFactor(currency) {
+    return ZERO_DECIMAL_CURRENCIES.has(currency.toUpperCase()) ? 1 : 100;
+}
+export function toMinorUnits(amount, currency) {
+    return Math.round(amount * currencyMinorUnitFactor(currency));
+}
+export function fromMinorUnits(amount, currency) {
+    const numericAmount = typeof amount === "string" ? Number(amount) : amount;
+    return numericAmount / currencyMinorUnitFactor(currency);
+}
+export function formatCurrency(amount, currency) {
+    try {
+        return new Intl.NumberFormat("en-US", {
+            style: "currency",
+            currency,
+            maximumFractionDigits: currencyMinorUnitFactor(currency) === 1 ? 0 : 2
+        }).format(amount);
+    }
+    catch {
+        return `${amount.toFixed(2)} ${currency}`;
+    }
+}

package/dist/utils/date-range.d.ts

@@ -0,0 +1,20 @@
+export interface DateWindowInput {
+    last?: string | undefined;
+    from?: string | undefined;
+    to?: string | undefined;
+}
+export interface DateWindow {
+    from: string;
+    to: string;
+    days: number;
+}
+export interface TimeWindow {
+    since: Date;
+    until: Date;
+    label: string;
+}
+export declare function buildRecentDateWindow(days: number, now?: Date): DateWindow;
+export declare function parseDateWindow(input: DateWindowInput): DateWindow;
+export declare function toInsightsTimeRange(window: DateWindow): string;
+export declare function parseTimeWindow(last: string): TimeWindow;
+export declare function percentChange(previous: number, current: number): number | null;

package/dist/utils/date-range.js

@@ -0,0 +1,115 @@
+import { AppError, ExitCode } from "./errors.js";
+const DAY_IN_MS = 24 * 60 * 60 * 1000;
+const HOUR_IN_MS = 60 * 60 * 1000;
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+function toLocalIsoDate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+function parseStrictIsoDate(value, label) {
+    const match = ISO_DATE_PATTERN.exec(value);
+    if (!match) {
+        throw new AppError(`${label} must use YYYY-MM-DD.`, ExitCode.Usage);
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (Number.isNaN(date.getTime())
+        || date.getUTCFullYear() !== year
+        || date.getUTCMonth() !== month - 1
+        || date.getUTCDate() !== day) {
+        throw new AppError(`${label} must be a valid calendar date.`, ExitCode.Usage);
+    }
+    return date;
+}
+export function buildRecentDateWindow(days, now = new Date()) {
+    if (!Number.isInteger(days) || days < 1) {
+        throw new AppError("Relative date windows must be at least 1 day.", ExitCode.Usage);
+    }
+    const until = new Date(now);
+    until.setHours(0, 0, 0, 0);
+    const fromDate = new Date(until);
+    fromDate.setDate(fromDate.getDate() - (days - 1));
+    return {
+        from: toLocalIsoDate(fromDate),
+        to: toLocalIsoDate(until),
+        days
+    };
+}
+export function parseDateWindow(input) {
+    const { last, from, to } = input;
+    if (last && (from || to)) {
+        throw new AppError("Use either --last or --from/--to, not both.", ExitCode.Usage);
+    }
+    if (!last && !from && !to) {
+        throw new AppError("A time window is required. Provide --last or --from/--to.", ExitCode.Usage);
+    }
+    if (last) {
+        const match = /^(\d+)(d|w)$/i.exec(last.trim());
+        if (!match) {
+            throw new AppError("Invalid --last value. Use values like 7d or 4w.", ExitCode.Usage);
+        }
+        const amountValue = match[1];
+        const unitValue = match[2];
+        if (!amountValue || !unitValue) {
+            throw new AppError("Invalid --last value. Use values like 7d or 4w.", ExitCode.Usage);
+        }
+        const amount = Number(amountValue);
+        const unit = unitValue.toLowerCase();
+        const days = unit === "w" ? amount * 7 : amount;
+        return buildRecentDateWindow(days);
+    }
+    if (!from || !to) {
+        throw new AppError("Both --from and --to are required.", ExitCode.Usage);
+    }
+    const fromDate = parseStrictIsoDate(from, "--from");
+    const toDate = parseStrictIsoDate(to, "--to");
+    if (fromDate > toDate) {
+        throw new AppError("--from must be before or equal to --to.", ExitCode.Usage);
+    }
+    const days = Math.floor((toDate.getTime() - fromDate.getTime()) / DAY_IN_MS) + 1;
+    return {
+        from,
+        to,
+        days
+    };
+}
+export function toInsightsTimeRange(window) {
+    return JSON.stringify({
+        since: window.from,
+        until: window.to
+    });
+}
+export function parseTimeWindow(last) {
+    const match = /^(\d+)(h|d)$/i.exec(last.trim());
+    if (!match) {
+        throw new AppError("Invalid --last value. Use values like 24h or 7d.", ExitCode.Usage);
+    }
+    const amountValue = match[1];
+    const unitValue = match[2];
+    if (!amountValue || !unitValue) {
+        throw new AppError("Invalid --last value. Use values like 24h or 7d.", ExitCode.Usage);
+    }
+    const amount = Number(amountValue);
+    const unit = unitValue.toLowerCase();
+    if (amount < 1) {
+        throw new AppError("Invalid --last value. Use values like 24h or 7d.", ExitCode.Usage);
+    }
+    const durationMs = unit === "h" ? amount * HOUR_IN_MS : amount * DAY_IN_MS;
+    const until = new Date();
+    const since = new Date(until.getTime() - durationMs);
+    return {
+        since,
+        until,
+        label: last
+    };
+}
+export function percentChange(previous, current) {
+    if (previous === 0) {
+        return current === 0 ? 0 : null;
+    }
+    return ((current - previous) / previous) * 100;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,35 @@
+import type { CommandFailureShape } from "../types.js";
+export declare enum ExitCode {
+    Ok = 0,
+    Usage = 2,
+    Config = 3,
+    Auth = 4,
+    Permission = 5,
+    RateLimit = 6,
+    Provider = 7,
+    PartialFailure = 8,
+    ApprovalRequired = 9,
+    UnsafeBlocked = 10,
+    VerificationFailed = 11
+}
+export declare class AppError extends Error {
+    readonly exitCode: ExitCode;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, exitCode: ExitCode, details?: Record<string, unknown>);
+}
+export interface MetaApiErrorOptions {
+    status: number;
+    metaCode?: number | undefined;
+    metaSubcode?: number | undefined;
+    fbtraceId?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+}
+export declare class MetaApiError extends AppError {
+    readonly status: number;
+    readonly metaCode: number | undefined;
+    readonly metaSubcode: number | undefined;
+    readonly fbtraceId: string | undefined;
+    constructor(message: string, exitCode: ExitCode, options: MetaApiErrorOptions);
+}
+export declare function isAppError(value: unknown): value is AppError;
+export declare function toFailureShape(error: unknown, command: string, meta?: Record<string, unknown>): CommandFailureShape;

package/dist/utils/errors.js

@@ -0,0 +1,68 @@
+export var ExitCode;
+(function (ExitCode) {
+    ExitCode[ExitCode["Ok"] = 0] = "Ok";
+    ExitCode[ExitCode["Usage"] = 2] = "Usage";
+    ExitCode[ExitCode["Config"] = 3] = "Config";
+    ExitCode[ExitCode["Auth"] = 4] = "Auth";
+    ExitCode[ExitCode["Permission"] = 5] = "Permission";
+    ExitCode[ExitCode["RateLimit"] = 6] = "RateLimit";
+    ExitCode[ExitCode["Provider"] = 7] = "Provider";
+    ExitCode[ExitCode["PartialFailure"] = 8] = "PartialFailure";
+    ExitCode[ExitCode["ApprovalRequired"] = 9] = "ApprovalRequired";
+    ExitCode[ExitCode["UnsafeBlocked"] = 10] = "UnsafeBlocked";
+    ExitCode[ExitCode["VerificationFailed"] = 11] = "VerificationFailed";
+})(ExitCode || (ExitCode = {}));
+export class AppError extends Error {
+    exitCode;
+    details;
+    constructor(message, exitCode, details) {
+        super(message);
+        this.name = new.target.name;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export class MetaApiError extends AppError {
+    status;
+    metaCode;
+    metaSubcode;
+    fbtraceId;
+    constructor(message, exitCode, options) {
+        super(message, exitCode, options.details);
+        this.status = options.status;
+        this.metaCode = options.metaCode;
+        this.metaSubcode = options.metaSubcode;
+        this.fbtraceId = options.fbtraceId;
+    }
+}
+export function isAppError(value) {
+    return value instanceof AppError;
+}
+export function toFailureShape(error, command, meta) {
+    if (isAppError(error)) {
+        return {
+            ok: false,
+            command,
+            error: error.message,
+            meta: {
+                ...(meta ?? {}),
+                exitCode: error.exitCode,
+                ...(error.details ?? {})
+            }
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            ok: false,
+            command,
+            error: error.message,
+            meta
+        };
+    }
+    return {
+        ok: false,
+        command,
+        error: "Unknown error",
+        meta
+    };
+}

package/dist/utils/ids.d.ts

@@ -0,0 +1,4 @@
+export declare function isAllAccountsSelection(value: string): boolean;
+export declare function normalizeAdAccountId(value: string): string;
+export declare function toAdAccountNodeId(value: string): string;
+export declare function normalizeObjectId(value: string, label: string): string;

package/dist/utils/ids.js

@@ -0,0 +1,23 @@
+import { AppError, ExitCode } from "./errors.js";
+const ACCOUNT_ALL = "all";
+export function isAllAccountsSelection(value) {
+    return value.toLowerCase() === ACCOUNT_ALL;
+}
+export function normalizeAdAccountId(value) {
+    const trimmed = value.trim();
+    const numeric = trimmed.startsWith("act_") ? trimmed.slice(4) : trimmed;
+    if (!/^\d+$/.test(numeric)) {
+        throw new AppError(`Invalid ad account id: ${value}`, ExitCode.Usage);
+    }
+    return numeric;
+}
+export function toAdAccountNodeId(value) {
+    return `act_${normalizeAdAccountId(value)}`;
+}
+export function normalizeObjectId(value, label) {
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new AppError(`Invalid ${label}: ${value}`, ExitCode.Usage);
+    }
+    return trimmed;
+}

package/dist/utils/meta-placement-assets.d.ts

@@ -0,0 +1,44 @@
+export declare const launchCreativeFormatKeys: readonly ["feed4x5", "square1x1", "story9x16"];
+export type LaunchCreativeFormatKey = typeof launchCreativeFormatKeys[number];
+export interface PlacementAssetOverride {
+    assetRef: string;
+    captionIds?: string[] | undefined;
+    imageCrops?: Record<string, number[]> | undefined;
+}
+export interface PlacementAssetFormats {
+    feed4x5?: PlacementAssetOverride | undefined;
+    square1x1?: PlacementAssetOverride | undefined;
+    story9x16?: PlacementAssetOverride | undefined;
+}
+type PublisherPlatform = "facebook" | "instagram" | "messenger" | "audience_network" | "threads";
+type PlacementId = `${PublisherPlatform}.${string}`;
+export declare const defaultCreativeFormatPlacementTargets: Record<LaunchCreativeFormatKey, string[]>;
+export interface ExpandedPlacementTargeting {
+    automatic: boolean;
+    automaticPublisherPlatforms: PublisherPlatform[];
+    audienceNetworkPositions: string[];
+    explicitPlacementIds: PlacementId[];
+    facebookPositions: string[];
+    feedPlacementIds: PlacementId[];
+    instagramPositions: string[];
+    knownPlacementIds: PlacementId[];
+    messengerPositions: string[];
+    placementIds: PlacementId[];
+    publisherPlatforms: PublisherPlatform[];
+    publisherPlatformsWereExplicit: boolean;
+    squarePlacementIds: PlacementId[];
+    threadsPositions: string[];
+    unknownPlacementIds: PlacementId[];
+    unsupportedPlacementIds: PlacementId[];
+    verticalPlacementIds: PlacementId[];
+}
+export declare function expandPlacementTargeting(targeting: unknown): ExpandedPlacementTargeting;
+export declare function hasPlacementFormats(formats: Partial<Record<LaunchCreativeFormatKey, unknown>> | undefined): boolean;
+export declare function hasOnlyInstagramVerticalPlacements(targeting: ExpandedPlacementTargeting): boolean;
+export declare function formatPlacementIds(placementIds: readonly string[]): string;
+export declare function pickVerticalPlacementIds(placementIds: readonly string[]): string[];
+export declare function pickFeedPlacementIds(placementIds: readonly string[]): string[];
+export declare function pickUnsupportedPlacementIds(placementIds: readonly string[]): string[];
+export declare function buildPlacementCustomizationSpec(placementIds: readonly string[]): Record<string, unknown>;
+export declare function coversFallbackPlacements(placementId: string): boolean;
+export {};