cli-meta-ads 0.1.0

package/dist/utils/meta-placement-assets.js

@@ -0,0 +1,315 @@
+export const launchCreativeFormatKeys = ["feed4x5", "square1x1", "story9x16"];
+const publisherPlatforms = [
+    "facebook",
+    "instagram",
+    "messenger",
+    "audience_network",
+    "threads"
+];
+const facebookPositions = [
+    "feed",
+    "right_hand_column",
+    "marketplace",
+    "video_feeds",
+    "search",
+    "story",
+    "notification",
+    "facebook_reels"
+];
+const instagramPositions = [
+    "stream",
+    "story",
+    "explore",
+    "explore_home",
+    "profile_feed",
+    "ig_search",
+    "reels",
+    "profile_reels"
+];
+const messengerPositions = [
+    "sponsored_messages",
+    "story"
+];
+const audienceNetworkPositions = [
+    "classic",
+    "instream_video",
+    "rewarded_video"
+];
+const threadsPositions = ["threads_stream"];
+const defaultAutomaticPublisherPlatforms = [
+    "facebook",
+    "instagram",
+    "messenger",
+    "audience_network"
+];
+const defaultAutomaticFacebookPositions = [...facebookPositions];
+const defaultAutomaticInstagramPositions = [...instagramPositions];
+const defaultAutomaticMessengerPositions = [...messengerPositions];
+const defaultAutomaticAudienceNetworkPositions = [...audienceNetworkPositions];
+const supportedFeedPlacementIds = new Set([
+    "facebook.feed",
+    "facebook.marketplace",
+    "facebook.video_feeds",
+    "instagram.stream",
+    "instagram.profile_feed",
+    "threads.threads_stream"
+]);
+const supportedSquarePlacementIds = new Set([
+    "facebook.right_hand_column",
+    "facebook.search",
+    "facebook.notification",
+    "instagram.explore",
+    "instagram.explore_home",
+    "instagram.ig_search"
+]);
+const supportedVerticalPlacementIds = new Set([
+    "facebook.story",
+    "facebook.facebook_reels",
+    "instagram.story",
+    "instagram.reels",
+    "instagram.profile_reels",
+    "messenger.story"
+]);
+const supportedFallbackPlacementIds = new Set([
+    ...supportedFeedPlacementIds,
+    ...supportedSquarePlacementIds
+]);
+const explicitlyUnsupportedPlacementIds = new Set([
+    "messenger.sponsored_messages",
+    "audience_network.classic",
+    "audience_network.instream_video",
+    "audience_network.rewarded_video"
+]);
+export const defaultCreativeFormatPlacementTargets = {
+    feed4x5: [...supportedFeedPlacementIds].filter((placementId) => placementId !== "threads.threads_stream"),
+    square1x1: [...supportedSquarePlacementIds],
+    story9x16: [...supportedVerticalPlacementIds]
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function sortByReference(values, reference) {
+    const index = new Map(reference.map((entry, idx) => [entry, idx]));
+    return [...values].sort((left, right) => {
+        const leftIndex = index.get(left) ?? Number.MAX_SAFE_INTEGER;
+        const rightIndex = index.get(right) ?? Number.MAX_SAFE_INTEGER;
+        if (leftIndex !== rightIndex) {
+            return leftIndex - rightIndex;
+        }
+        return left.localeCompare(right);
+    });
+}
+function normalizePublisherPlatforms(values) {
+    return unique(values.filter((entry) => publisherPlatforms.includes(entry)));
+}
+function toPlacementIds(platform, positions) {
+    return positions.map((position) => `${platform}.${position}`);
+}
+function selectPublisherPlatforms(targeting) {
+    const explicitPublisherPlatforms = normalizePublisherPlatforms(asStringArray(targeting.publisher_platforms));
+    if (explicitPublisherPlatforms.length > 0) {
+        return {
+            publisherPlatforms: explicitPublisherPlatforms,
+            publisherPlatformsWereExplicit: true
+        };
+    }
+    const inferredPublisherPlatforms = normalizePublisherPlatforms([
+        ...(asStringArray(targeting.facebook_positions).length > 0 ? ["facebook"] : []),
+        ...(asStringArray(targeting.instagram_positions).length > 0 ? ["instagram"] : []),
+        ...(asStringArray(targeting.messenger_positions).length > 0 ? ["messenger"] : []),
+        ...(asStringArray(targeting.audience_network_positions).length > 0 ? ["audience_network"] : []),
+        ...(asStringArray(targeting.threads_positions).length > 0 ? ["threads"] : [])
+    ]);
+    if (inferredPublisherPlatforms.length > 0) {
+        return {
+            publisherPlatforms: inferredPublisherPlatforms,
+            publisherPlatformsWereExplicit: false
+        };
+    }
+    return {
+        publisherPlatforms: [...defaultAutomaticPublisherPlatforms],
+        publisherPlatformsWereExplicit: false
+    };
+}
+function expandPositions(publisherPlatformsValue, targeting, platform, fieldName, automaticDefaults) {
+    if (!publisherPlatformsValue.includes(platform)) {
+        return {
+            automatic: false,
+            positions: []
+        };
+    }
+    const positions = asStringArray(targeting[fieldName]);
+    if (positions.length > 0) {
+        return {
+            automatic: false,
+            positions: unique(positions)
+        };
+    }
+    return {
+        automatic: automaticDefaults.length > 0,
+        positions: [...automaticDefaults]
+    };
+}
+function pickPlacementIds(placementIds, matcher) {
+    return placementIds.filter((placementId) => matcher.has(placementId));
+}
+function toPlacementId(value) {
+    return value;
+}
+export function expandPlacementTargeting(targeting) {
+    const rawTargeting = isRecord(targeting) ? targeting : {};
+    const { publisherPlatforms: selectedPublisherPlatforms, publisherPlatformsWereExplicit } = selectPublisherPlatforms(rawTargeting);
+    const facebook = expandPositions(selectedPublisherPlatforms, rawTargeting, "facebook", "facebook_positions", defaultAutomaticFacebookPositions);
+    const instagram = expandPositions(selectedPublisherPlatforms, rawTargeting, "instagram", "instagram_positions", defaultAutomaticInstagramPositions);
+    const messenger = expandPositions(selectedPublisherPlatforms, rawTargeting, "messenger", "messenger_positions", defaultAutomaticMessengerPositions);
+    const audienceNetwork = expandPositions(selectedPublisherPlatforms, rawTargeting, "audience_network", "audience_network_positions", defaultAutomaticAudienceNetworkPositions);
+    const threads = expandPositions(selectedPublisherPlatforms, rawTargeting, "threads", "threads_positions", []);
+    const automaticPublisherPlatforms = [
+        ...(facebook.automatic ? ["facebook"] : []),
+        ...(instagram.automatic ? ["instagram"] : []),
+        ...(messenger.automatic ? ["messenger"] : []),
+        ...(audienceNetwork.automatic ? ["audience_network"] : []),
+        ...(threads.automatic ? ["threads"] : [])
+    ];
+    const placementIds = [
+        ...toPlacementIds("facebook", facebook.positions),
+        ...toPlacementIds("instagram", instagram.positions),
+        ...toPlacementIds("messenger", messenger.positions),
+        ...toPlacementIds("audience_network", audienceNetwork.positions),
+        ...toPlacementIds("threads", threads.positions)
+    ];
+    const explicitPlacementIds = [
+        ...toPlacementIds("facebook", asStringArray(rawTargeting.facebook_positions)),
+        ...toPlacementIds("instagram", asStringArray(rawTargeting.instagram_positions)),
+        ...toPlacementIds("messenger", asStringArray(rawTargeting.messenger_positions)),
+        ...toPlacementIds("audience_network", asStringArray(rawTargeting.audience_network_positions)),
+        ...toPlacementIds("threads", asStringArray(rawTargeting.threads_positions))
+    ];
+    const knownPlacementIds = pickPlacementIds(placementIds, new Set([
+        ...supportedFeedPlacementIds,
+        ...supportedSquarePlacementIds,
+        ...supportedVerticalPlacementIds,
+        ...explicitlyUnsupportedPlacementIds
+    ]));
+    const unknownPlacementIds = placementIds.filter((placementId) => !knownPlacementIds.includes(placementId));
+    const unsupportedPlacementIds = unique([
+        ...pickPlacementIds(placementIds, explicitlyUnsupportedPlacementIds),
+        ...unknownPlacementIds
+    ]);
+    return {
+        automatic: automaticPublisherPlatforms.length > 0,
+        automaticPublisherPlatforms,
+        audienceNetworkPositions: sortByReference(audienceNetwork.positions, audienceNetworkPositions),
+        explicitPlacementIds: unique(explicitPlacementIds),
+        facebookPositions: sortByReference(facebook.positions, facebookPositions),
+        feedPlacementIds: unique([
+            ...pickPlacementIds(placementIds, supportedFeedPlacementIds),
+            ...pickPlacementIds(placementIds, supportedSquarePlacementIds)
+        ]),
+        instagramPositions: sortByReference(instagram.positions, instagramPositions),
+        knownPlacementIds: unique(knownPlacementIds),
+        messengerPositions: sortByReference(messenger.positions, messengerPositions),
+        placementIds: unique(placementIds),
+        publisherPlatforms: selectedPublisherPlatforms,
+        publisherPlatformsWereExplicit,
+        squarePlacementIds: pickPlacementIds(placementIds, supportedSquarePlacementIds),
+        threadsPositions: sortByReference(threads.positions, threadsPositions),
+        unknownPlacementIds,
+        unsupportedPlacementIds,
+        verticalPlacementIds: pickPlacementIds(placementIds, supportedVerticalPlacementIds)
+    };
+}
+export function hasPlacementFormats(formats) {
+    return Boolean(formats && launchCreativeFormatKeys.some((key) => formats[key]));
+}
+export function hasOnlyInstagramVerticalPlacements(targeting) {
+    return targeting.verticalPlacementIds.length > 0
+        && targeting.verticalPlacementIds.every((placementId) => placementId.startsWith("instagram."));
+}
+export function formatPlacementIds(placementIds) {
+    return [...placementIds].sort().join(", ");
+}
+export function pickVerticalPlacementIds(placementIds) {
+    return unique(placementIds.map(toPlacementId).filter((placementId) => supportedVerticalPlacementIds.has(placementId)));
+}
+export function pickFeedPlacementIds(placementIds) {
+    return unique(placementIds.map(toPlacementId).filter((placementId) => supportedFeedPlacementIds.has(placementId) || supportedSquarePlacementIds.has(placementId)));
+}
+export function pickUnsupportedPlacementIds(placementIds) {
+    return unique(placementIds.map(toPlacementId).filter((placementId) => explicitlyUnsupportedPlacementIds.has(placementId)
+        || (!supportedFeedPlacementIds.has(placementId)
+            && !supportedSquarePlacementIds.has(placementId)
+            && !supportedVerticalPlacementIds.has(placementId))));
+}
+export function buildPlacementCustomizationSpec(placementIds) {
+    const facebook = new Set();
+    const instagram = new Set();
+    const messenger = new Set();
+    const audienceNetwork = new Set();
+    const threads = new Set();
+    placementIds.forEach((placementId) => {
+        const [platform, position] = placementId.split(".", 2);
+        if (!position) {
+            return;
+        }
+        switch (platform) {
+            case "facebook":
+                facebook.add(position);
+                break;
+            case "instagram":
+                instagram.add(position);
+                break;
+            case "messenger":
+                messenger.add(position);
+                break;
+            case "audience_network":
+                audienceNetwork.add(position);
+                break;
+            case "threads":
+                threads.add(position);
+                break;
+            default:
+                break;
+        }
+    });
+    const publisherPlatformsValue = unique([
+        ...(facebook.size > 0 ? ["facebook"] : []),
+        ...(instagram.size > 0 ? ["instagram"] : []),
+        ...(messenger.size > 0 ? ["messenger"] : []),
+        ...(audienceNetwork.size > 0 ? ["audience_network"] : []),
+        ...(threads.size > 0 ? ["threads"] : [])
+    ]);
+    return {
+        ...(publisherPlatformsValue.length > 0 ? { publisher_platforms: publisherPlatformsValue } : {}),
+        ...(facebook.size > 0
+            ? { facebook_positions: sortByReference([...facebook], facebookPositions) }
+            : {}),
+        ...(instagram.size > 0
+            ? { instagram_positions: sortByReference([...instagram], instagramPositions) }
+            : {}),
+        ...(messenger.size > 0
+            ? { messenger_positions: sortByReference([...messenger], messengerPositions) }
+            : {}),
+        ...(audienceNetwork.size > 0
+            ? { audience_network_positions: sortByReference([...audienceNetwork], audienceNetworkPositions) }
+            : {}),
+        ...(threads.size > 0
+            ? { threads_positions: sortByReference([...threads], threadsPositions) }
+            : {})
+    };
+}
+export function coversFallbackPlacements(placementId) {
+    return supportedFallbackPlacementIds.has(placementId);
+}

package/dist/utils/security.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeHttpsUrl(value: string, label: string): string;
+export declare function normalizeAuthRedirectUri(value: string, label: string): string;
+export declare function sanitizeUrl(value: string): string;
+export declare function sanitizeText(value: string): string;
+export declare function sanitizeArgvForLogs(argv: string[]): string[];

package/dist/utils/security.js

@@ -0,0 +1,104 @@
+import { AppError, ExitCode } from "./errors.js";
+const REDACTED = "<redacted>";
+const REDACTED_QUERY_PARAMS = new Set(["access_token", "appsecret_proof", "code"]);
+const REDACTED_ARG_VALUE_OPTIONS = new Set(["--config"]);
+export function normalizeHttpsUrl(value, label) {
+    const trimmed = value.trim();
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new AppError(`${label} must be a valid https URL.`, ExitCode.Config);
+    }
+    if (url.protocol !== "https:") {
+        throw new AppError(`${label} must use https.`, ExitCode.Config);
+    }
+    return url.toString();
+}
+function isLoopbackHost(hostname) {
+    if (hostname === "localhost" || hostname === "::1" || hostname === "[::1]") {
+        return true;
+    }
+    if (/^127(?:\.\d{1,3}){3}$/.test(hostname)) {
+        return true;
+    }
+    return false;
+}
+export function normalizeAuthRedirectUri(value, label) {
+    const trimmed = value.trim();
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new AppError(`${label} must be a valid http or https URL.`, ExitCode.Config);
+    }
+    if (url.protocol === "https:") {
+        return url.toString();
+    }
+    if (url.protocol === "http:" && isLoopbackHost(url.hostname)) {
+        return url.toString();
+    }
+    throw new AppError(`${label} must use https unless it targets localhost or a loopback address.`, ExitCode.Config);
+}
+export function sanitizeUrl(value) {
+    try {
+        const url = new URL(value);
+        for (const parameter of REDACTED_QUERY_PARAMS) {
+            if (url.searchParams.has(parameter)) {
+                url.searchParams.set(parameter, REDACTED);
+            }
+        }
+        if (url.hash.startsWith("#")) {
+            const fragmentParams = new URLSearchParams(url.hash.slice(1));
+            let mutated = false;
+            for (const parameter of REDACTED_QUERY_PARAMS) {
+                if (fragmentParams.has(parameter)) {
+                    fragmentParams.set(parameter, REDACTED);
+                    mutated = true;
+                }
+            }
+            if (mutated) {
+                const nextHash = fragmentParams.toString();
+                url.hash = nextHash ? `#${nextHash}` : "";
+            }
+        }
+        return url.toString();
+    }
+    catch {
+        return value.replace(/([?&](?:access_token|appsecret_proof|code)=)[^&]*/gi, `$1${REDACTED}`);
+    }
+}
+export function sanitizeText(value) {
+    const sanitizedUrls = value.replace(/https?:\/\/[^\s"'<>]+/gi, (candidate) => sanitizeUrl(candidate));
+    return sanitizedUrls
+        .replace(/((?:access_token|appsecret_proof|code)=)[^&\s"'<>]+/gi, `$1${REDACTED}`)
+        .replace(/((?:access_token|appsecret_proof|code)%3[Dd])[^&\s"'<>]+/g, `$1${REDACTED}`)
+        .replace(/("(?:access_token|appsecret_proof|code)"\s*:\s*")[^"]*"/gi, `$1${REDACTED}"`)
+        .replace(/('(?:access_token|appsecret_proof|code)'\s*:\s*')[^']*'/gi, `$1${REDACTED}'`);
+}
+export function sanitizeArgvForLogs(argv) {
+    const sanitized = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const entry = argv[index];
+        if (!entry) {
+            continue;
+        }
+        if (REDACTED_ARG_VALUE_OPTIONS.has(entry)) {
+            sanitized.push(entry);
+            if (argv[index + 1]) {
+                sanitized.push(REDACTED);
+                index += 1;
+            }
+            continue;
+        }
+        const [flag, value] = entry.split("=", 2);
+        if (flag && value !== undefined && REDACTED_ARG_VALUE_OPTIONS.has(flag)) {
+            sanitized.push(`${flag}=${REDACTED}`);
+            continue;
+        }
+        sanitized.push(sanitizeText(entry));
+    }
+    return sanitized;
+}

package/dist/validators/common.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const accountSelectionSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export declare function parseAccountSelection(value: string | undefined): string;
+export declare function parseCampaignId(value: string): string;
+export declare function parseAdId(value: string): string;
+export declare function parseVideoId(value: string): string;
+export declare function parseAudienceId(value: string): string;
+export declare function parsePositiveNumber(value: string, label: string): number;
+export declare function parseThreshold(value: string | number | undefined): number;
+export declare function parseBreakdowns(value: string | undefined): string[];

package/dist/validators/common.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { isAllAccountsSelection, normalizeAdAccountId, normalizeObjectId } from "../utils/ids.js";
+export const accountSelectionSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .transform((value) => (isAllAccountsSelection(value) ? "all" : normalizeAdAccountId(value)));
+export function parseAccountSelection(value) {
+    if (!value) {
+        throw new AppError("An account is required.", ExitCode.Usage);
+    }
+    return accountSelectionSchema.parse(value);
+}
+export function parseCampaignId(value) {
+    return normalizeObjectId(value, "campaign id");
+}
+export function parseAdId(value) {
+    return normalizeObjectId(value, "ad id");
+}
+export function parseVideoId(value) {
+    return normalizeObjectId(value, "video id");
+}
+export function parseAudienceId(value) {
+    return normalizeObjectId(value, "audience id");
+}
+export function parsePositiveNumber(value, label) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+        throw new AppError(`${label} must be a positive number.`, ExitCode.Usage);
+    }
+    return numeric;
+}
+export function parseThreshold(value) {
+    const numeric = Number(value ?? 20);
+    if (!Number.isFinite(numeric) || numeric < 1 || numeric > 1000) {
+        throw new AppError("Threshold must be a number between 1 and 1000.", ExitCode.Usage);
+    }
+    return numeric;
+}
+export function parseBreakdowns(value) {
+    if (!value) {
+        return [];
+    }
+    const allowed = new Set(["age", "gender", "publisher_platform", "platform_position", "device_platform"]);
+    const breakdowns = value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const breakdown of breakdowns) {
+        if (!allowed.has(breakdown)) {
+            throw new AppError(`Unsupported breakdown: ${breakdown}`, ExitCode.Usage);
+        }
+    }
+    return breakdowns;
+}