cli-meta-ads 0.1.0

package/dist/validators/launch-spec.js

@@ -0,0 +1,371 @@
+import path from "node:path";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { normalizeObjectId } from "../utils/ids.js";
+import { expandPlacementTargeting, hasPlacementFormats, launchCreativeFormatKeys, pickFeedPlacementIds, pickUnsupportedPlacementIds, pickVerticalPlacementIds } from "../utils/meta-placement-assets.js";
+import { z } from "zod";
+import { bidStrategySchema, callToActionSchema, campaignObjectiveSchema, optimizationGoalSchema, promotedObjectSchema, resolveExistingFilePath, readSpecFile, targetingSpecSchema } from "./create-spec.js";
+const nonEmptyStringSchema = z.string().trim().min(1);
+const refSchema = nonEmptyStringSchema;
+const pausedStatusSchema = z.literal("PAUSED");
+const metaIdSchema = (label) => z.string().trim().min(1).transform((value) => normalizeObjectId(value, label));
+const launchCampaignSpecSchema = z.object({
+    bidStrategy: bidStrategySchema.optional(),
+    dailyBudget: z.number().int().positive().optional(),
+    lifetimeBudget: z.number().int().positive().optional(),
+    ref: refSchema,
+    name: nonEmptyStringSchema,
+    objective: campaignObjectiveSchema,
+    specialAdCategories: z.array(nonEmptyStringSchema).default([]),
+    status: pausedStatusSchema.optional()
+}).strict().superRefine((value, ctx) => {
+    if (value.dailyBudget !== undefined && value.lifetimeBudget !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide either dailyBudget or lifetimeBudget for campaign budget optimization, not both."
+        });
+    }
+    if (value.bidStrategy !== undefined
+        && value.dailyBudget === undefined
+        && value.lifetimeBudget === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Campaign bidStrategy requires dailyBudget or lifetimeBudget."
+        });
+    }
+});
+const launchAdSetSpecSchema = z.object({
+    ref: refSchema,
+    campaignRef: refSchema,
+    bidAmount: z.number().int().positive().optional(),
+    bidStrategy: bidStrategySchema.optional(),
+    billingEvent: z.enum(["IMPRESSIONS", "CLICKS"]),
+    dailyBudget: z.number().int().positive().optional(),
+    endTime: nonEmptyStringSchema.optional(),
+    lifetimeBudget: z.number().int().positive().optional(),
+    name: nonEmptyStringSchema,
+    optimizationGoal: optimizationGoalSchema,
+    promotedObject: promotedObjectSchema,
+    startTime: nonEmptyStringSchema.optional(),
+    status: pausedStatusSchema.optional(),
+    targeting: targetingSpecSchema
+}).strict().superRefine((value, ctx) => {
+    if (value.dailyBudget === undefined && value.lifetimeBudget === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Either dailyBudget or lifetimeBudget is required."
+        });
+    }
+    if (value.dailyBudget !== undefined && value.lifetimeBudget !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide either dailyBudget or lifetimeBudget, not both."
+        });
+    }
+    if (value.bidStrategy === "LOWEST_COST_WITHOUT_CAP" && value.bidAmount !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "bidAmount cannot be combined with LOWEST_COST_WITHOUT_CAP."
+        });
+    }
+    if ((value.bidStrategy === "LOWEST_COST_WITH_BID_CAP" || value.bidStrategy === "COST_CAP")
+        && value.bidAmount === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${value.bidStrategy} requires bidAmount.`
+        });
+    }
+    if ((value.optimizationGoal === "OFFSITE_CONVERSIONS" || value.optimizationGoal === "VALUE")
+        && (!value.promotedObject.pixelId || !value.promotedObject.customEventType)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${value.optimizationGoal} requires promotedObject.pixelId and promotedObject.customEventType.`
+        });
+    }
+    if ((value.optimizationGoal === "CONVERSATIONS"
+        || value.optimizationGoal === "LEAD_GENERATION"
+        || value.optimizationGoal === "QUALITY_CALL"
+        || value.optimizationGoal === "QUALITY_LEAD")
+        && !value.promotedObject.pageId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${value.optimizationGoal} requires promotedObject.pageId.`
+        });
+    }
+});
+const imageAssetSpecSchema = z.object({
+    ref: refSchema,
+    kind: z.literal("image"),
+    file: nonEmptyStringSchema,
+    name: nonEmptyStringSchema.optional()
+}).strict();
+const videoAssetSpecSchema = z.object({
+    ref: refSchema,
+    kind: z.literal("video"),
+    file: nonEmptyStringSchema,
+    name: nonEmptyStringSchema.optional()
+}).strict();
+const imageCropValuesSchema = z.array(z.number());
+const imageCropsSchema = z.record(z.string(), imageCropValuesSchema);
+const launchPlatformCustomizationOverrideSchema = z.object({
+    assetRef: refSchema,
+    captionIds: z.array(nonEmptyStringSchema).optional(),
+    imageCrops: imageCropsSchema.optional()
+}).strict();
+const launchCreativeFormatOverrideSchema = z.object({
+    assetRef: refSchema,
+    captionIds: z.array(nonEmptyStringSchema).optional(),
+    imageCrops: imageCropsSchema.optional()
+}).strict();
+const launchCreativeFormatsSchema = z.object({
+    feed4x5: launchCreativeFormatOverrideSchema.optional(),
+    square1x1: launchCreativeFormatOverrideSchema.optional(),
+    story9x16: launchCreativeFormatOverrideSchema.optional()
+}).strict().superRefine((value, ctx) => {
+    if (!launchCreativeFormatKeys.some((key) => value[key])) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "formats must include at least one supported format override."
+        });
+    }
+});
+const launchPlatformCustomizationsSchema = z.object({
+    instagram: launchPlatformCustomizationOverrideSchema.optional()
+}).strict().superRefine((value, ctx) => {
+    if (!value.instagram) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "platformCustomizations must include at least one supported platform override."
+        });
+    }
+});
+const imageCreativeSpecSchema = z.object({
+    ref: refSchema,
+    kind: z.literal("link-image"),
+    assetRef: refSchema.optional(),
+    formats: launchCreativeFormatsSchema.optional(),
+    linkData: z.object({
+        callToAction: callToActionSchema.optional(),
+        description: nonEmptyStringSchema.optional(),
+        headline: nonEmptyStringSchema.optional(),
+        link: z.string().trim().url(),
+        message: nonEmptyStringSchema
+    }).strict(),
+    name: nonEmptyStringSchema.optional(),
+    pageId: metaIdSchema("page id"),
+    platformCustomizations: launchPlatformCustomizationsSchema.optional(),
+    status: pausedStatusSchema.optional()
+}).strict().superRefine((value, ctx) => {
+    if (!value.assetRef && !hasPlacementFormats(value.formats)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Creative must include assetRef or formats."
+        });
+    }
+    if (value.platformCustomizations && value.formats) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "formats cannot be combined with legacy platformCustomizations."
+        });
+    }
+});
+const videoCreativeSpecSchema = z.object({
+    ref: refSchema,
+    kind: z.literal("video-link"),
+    assetRef: refSchema.optional(),
+    formats: launchCreativeFormatsSchema.optional(),
+    name: nonEmptyStringSchema.optional(),
+    pageId: metaIdSchema("page id"),
+    platformCustomizations: launchPlatformCustomizationsSchema.optional(),
+    status: pausedStatusSchema.optional(),
+    videoData: z.object({
+        callToAction: callToActionSchema.optional(),
+        description: nonEmptyStringSchema.optional(),
+        link: z.string().trim().url(),
+        message: nonEmptyStringSchema,
+        title: nonEmptyStringSchema.optional()
+    }).strict()
+}).strict().superRefine((value, ctx) => {
+    if (!value.assetRef && !hasPlacementFormats(value.formats)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Creative must include assetRef or formats."
+        });
+    }
+    if (value.platformCustomizations && value.formats) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "formats cannot be combined with legacy platformCustomizations."
+        });
+    }
+});
+const launchAdSpecSchema = z.object({
+    ref: refSchema,
+    name: nonEmptyStringSchema,
+    adSetRef: refSchema,
+    creativeRef: refSchema,
+    status: pausedStatusSchema.optional()
+}).strict();
+export const launchSpecSchema = z.object({
+    version: z.literal(1),
+    campaign: launchCampaignSpecSchema,
+    adSets: z.array(launchAdSetSpecSchema).default([]),
+    assets: z.array(z.discriminatedUnion("kind", [imageAssetSpecSchema, videoAssetSpecSchema])).default([]),
+    creatives: z.array(z.discriminatedUnion("kind", [imageCreativeSpecSchema, videoCreativeSpecSchema])).default([]),
+    ads: z.array(launchAdSpecSchema).default([])
+}).strict().superRefine((value, ctx) => {
+    const allRefs = new Map();
+    const registerRef = (ref, owner) => {
+        const previous = allRefs.get(ref);
+        if (previous) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Duplicate ref '${ref}' used by ${previous} and ${owner}.`
+            });
+            return;
+        }
+        allRefs.set(ref, owner);
+    };
+    registerRef(value.campaign.ref, "campaign");
+    value.adSets.forEach((entry) => registerRef(entry.ref, `adSet:${entry.name}`));
+    value.assets.forEach((entry) => registerRef(entry.ref, `asset:${entry.file}`));
+    value.creatives.forEach((entry) => registerRef(entry.ref, `creative:${entry.kind}`));
+    value.ads.forEach((entry) => registerRef(entry.ref, `ad:${entry.name}`));
+    const assetKinds = new Map(value.assets.map((entry) => [entry.ref, entry.kind]));
+    const creativeRefs = new Set(value.creatives.map((entry) => entry.ref));
+    const adSetRefs = new Set(value.adSets.map((entry) => entry.ref));
+    const adSetPlacements = new Map(value.adSets.map((entry) => [entry.ref, expandPlacementTargeting(entry.targeting)]));
+    value.adSets.forEach((entry) => {
+        if (entry.campaignRef !== value.campaign.ref) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Ad set '${entry.ref}' references unknown campaignRef '${entry.campaignRef}'.`
+            });
+        }
+    });
+    value.creatives.forEach((entry) => {
+        const requireAssetRef = (assetRef, source) => {
+            const assetKind = assetKinds.get(assetRef);
+            if (!assetKind) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Creative '${entry.ref}' references unknown ${source} '${assetRef}'.`
+                });
+                return;
+            }
+            if (entry.kind === "link-image" && assetKind !== "image") {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Creative '${entry.ref}' requires an image ${source}.`
+                });
+            }
+            if (entry.kind === "video-link" && assetKind !== "video") {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Creative '${entry.ref}' requires a video ${source}.`
+                });
+            }
+        };
+        if (entry.assetRef) {
+            requireAssetRef(entry.assetRef, "assetRef");
+        }
+        launchCreativeFormatKeys.forEach((formatKey) => {
+            const formatOverride = entry.formats?.[formatKey];
+            if (formatOverride) {
+                requireAssetRef(formatOverride.assetRef, `formats.${formatKey}.assetRef`);
+            }
+        });
+        const instagramOverride = entry.platformCustomizations?.instagram;
+        if (!instagramOverride) {
+            // Continue into placement validation below.
+        }
+        else {
+            requireAssetRef(instagramOverride.assetRef, "platform customization assetRef");
+        }
+        const adsForCreative = value.ads.filter((item) => item.creativeRef === entry.ref);
+        const expandedPlacementIds = [...new Set(adsForCreative.flatMap((item) => adSetPlacements.get(item.adSetRef)?.placementIds ?? []))];
+        const explicitPlacementIds = [...new Set(adsForCreative.flatMap((item) => adSetPlacements.get(item.adSetRef)?.explicitPlacementIds ?? []))];
+        const automaticPlacements = adsForCreative.some((item) => adSetPlacements.get(item.adSetRef)?.automatic);
+        const requiredVerticalPlacements = [
+            ...new Set([
+                ...pickVerticalPlacementIds(explicitPlacementIds),
+                ...(automaticPlacements && hasPlacementFormats(entry.formats)
+                    ? pickVerticalPlacementIds(expandedPlacementIds)
+                    : [])
+            ])
+        ];
+        const requiredFeedPlacements = [
+            ...new Set([
+                ...pickFeedPlacementIds(explicitPlacementIds),
+                ...(automaticPlacements && hasPlacementFormats(entry.formats)
+                    ? pickFeedPlacementIds(expandedPlacementIds)
+                    : [])
+            ])
+        ];
+        const requiredUnsupportedPlacements = [
+            ...new Set([
+                ...pickUnsupportedPlacementIds(explicitPlacementIds),
+                ...(automaticPlacements && hasPlacementFormats(entry.formats)
+                    ? pickUnsupportedPlacementIds(expandedPlacementIds)
+                    : [])
+            ])
+        ];
+        const hasFeedAsset = Boolean(entry.assetRef || entry.formats?.feed4x5 || entry.formats?.square1x1);
+        const hasStoryAsset = Boolean(entry.formats?.story9x16);
+        const hasLegacyInstagramVerticalCoverage = Boolean(entry.platformCustomizations?.instagram)
+            && requiredVerticalPlacements.length > 0
+            && requiredVerticalPlacements.every((placementId) => placementId.startsWith("instagram."));
+        if (requiredVerticalPlacements.length > 0 && !hasStoryAsset && !hasLegacyInstagramVerticalCoverage) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Creative '${entry.ref}' targets story/reels placements (${requiredVerticalPlacements.join(", ")}) but does not provide formats.story9x16.`
+            });
+        }
+        if (requiredFeedPlacements.length > 0 && !hasFeedAsset) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Creative '${entry.ref}' targets feed-like placements (${requiredFeedPlacements.join(", ")}) but does not provide assetRef, formats.feed4x5, or formats.square1x1.`
+            });
+        }
+        if (requiredUnsupportedPlacements.length > 0 && hasPlacementFormats(entry.formats) && !entry.assetRef) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Creative '${entry.ref}' targets placements outside the current formats abstraction (${requiredUnsupportedPlacements.join(", ")}) and must provide assetRef as the explicit fallback asset.`
+            });
+        }
+    });
+    value.ads.forEach((entry) => {
+        if (!adSetRefs.has(entry.adSetRef)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Ad '${entry.ref}' references unknown adSetRef '${entry.adSetRef}'.`
+            });
+        }
+        if (!creativeRefs.has(entry.creativeRef)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Ad '${entry.ref}' references unknown creativeRef '${entry.creativeRef}'.`
+            });
+        }
+    });
+});
+export async function readLaunchSpecFile(specPath) {
+    const { spec, specPath: absoluteSpecPath } = await readSpecFile(specPath, launchSpecSchema, "Launch");
+    const specDir = path.dirname(absoluteSpecPath);
+    const assets = await Promise.all(spec.assets.map(async (asset) => ({
+        ...asset,
+        file: await resolveExistingFilePath(asset.file, `Asset file for ref '${asset.ref}'`, specDir)
+    })));
+    return {
+        spec: {
+            ...spec,
+            assets
+        },
+        specPath: absoluteSpecPath
+    };
+}
+export function requireReceiptPath(value) {
+    if (!value?.trim()) {
+        throw new AppError("A receipt path is required.", ExitCode.Usage);
+    }
+    return value;
+}