cli-meta-ads 0.1.0

package/dist/domain/launch-service.js

@@ -0,0 +1,558 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AppError, ExitCode } from "../utils/errors.js";
+import { expandPlacementTargeting, formatPlacementIds, hasPlacementFormats } from "../utils/meta-placement-assets.js";
+import { buildAssetFeedCreativeSpec as compileAssetFeedCreativeSpec } from "./asset-feed-compiler.js";
+function createExecutionId() {
+    return `launch_${new Date().toISOString().replace(/[-:.TZ]/g, "")}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function defaultReceiptPath(executionId) {
+    return path.resolve(".meta-launch", `${executionId}.json`);
+}
+function createStep(kind, ref, detail) {
+    return {
+        detail,
+        id: `${kind}:${ref}`,
+        kind,
+        ref,
+        status: "pending"
+    };
+}
+export function buildLaunchSteps(spec) {
+    return [
+        createStep("campaign.create", spec.campaign.ref, `Create campaign '${spec.campaign.name}'`),
+        ...spec.adSets.map((entry) => createStep("adset.create", entry.ref, `Create ad set '${entry.name}'`)),
+        ...spec.assets.flatMap((entry) => entry.kind === "image"
+            ? [createStep("asset.image.upload", entry.ref, `Upload image asset '${entry.ref}'`)]
+            : [
+                createStep("asset.video.upload", entry.ref, `Upload video asset '${entry.ref}'`),
+                createStep("asset.video.wait", entry.ref, `Wait for video asset '${entry.ref}' to be ready`)
+            ]),
+        ...spec.creatives.map((entry) => createStep("creative.create", entry.ref, `Create creative '${entry.ref}'`)),
+        ...spec.ads.map((entry) => createStep("ad.create", entry.ref, `Create ad '${entry.name}'`))
+    ];
+}
+function summarizeCreated(receipt) {
+    return {
+        ads: Object.entries(receipt.created.ads).map(([ref, value]) => ({ ref, ...value })),
+        adSets: Object.entries(receipt.created.adSets).map(([ref, value]) => ({ ref, ...value })),
+        assets: Object.entries(receipt.created.assets).map(([ref, value]) => ({ ref, ...value })),
+        campaign: receipt.created.campaign,
+        creatives: Object.entries(receipt.created.creatives).map(([ref, value]) => ({ ref, ...value }))
+    };
+}
+function pendingSteps(receipt) {
+    return receipt.steps.filter((entry) => entry.status === "pending");
+}
+async function ensureWritableReceiptPath(receiptPath) {
+    const absolutePath = path.resolve(receiptPath);
+    try {
+        await access(absolutePath);
+        throw new AppError(`Receipt path already exists: ${absolutePath}`, ExitCode.Usage, {
+            receiptPath: absolutePath
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return absolutePath;
+        }
+        throw error;
+    }
+}
+async function persistReceipt(receipt) {
+    await mkdir(path.dirname(receipt.receiptPath), { recursive: true });
+    receipt.updatedAt = new Date().toISOString();
+    await writeFile(receipt.receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+}
+async function readReceipt(receiptPath) {
+    const absolutePath = path.resolve(receiptPath);
+    try {
+        const parsed = JSON.parse(await readFile(absolutePath, "utf8"));
+        if (!parsed || parsed.version !== 1 || !parsed.executionId || !Array.isArray(parsed.steps)) {
+            throw new AppError("Launch receipt is invalid.", ExitCode.Usage, {
+                receiptPath: absolutePath
+            });
+        }
+        parsed.receiptPath = absolutePath;
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            throw error;
+        }
+        if (error.code === "ENOENT") {
+            throw new AppError("Launch receipt does not exist.", ExitCode.Usage, {
+                receiptPath: absolutePath
+            });
+        }
+        if (error instanceof SyntaxError) {
+            throw new AppError("Launch receipt is not valid JSON.", ExitCode.Usage, {
+                receiptPath: absolutePath
+            });
+        }
+        throw error;
+    }
+}
+function requireCreatedId(value, label, ref) {
+    if (!value) {
+        throw new AppError(`Launch receipt is missing ${label} for ref '${ref}'.`, ExitCode.VerificationFailed, {
+            ref
+        });
+    }
+    return value.id;
+}
+function requireCreatedAsset(receipt, ref, assetRef) {
+    const asset = receipt.created.assets[assetRef];
+    if (!asset) {
+        throw new AppError(`Launch receipt is missing asset for creative ref '${ref}'.`, ExitCode.VerificationFailed, {
+            assetRef
+        });
+    }
+    return asset;
+}
+function findCreativeEntry(receipt, ref) {
+    const entry = receipt.spec.creatives.find((item) => item.ref === ref);
+    if (!entry) {
+        throw new AppError(`Launch spec is missing creative ref '${ref}'.`, ExitCode.VerificationFailed);
+    }
+    return entry;
+}
+function resolveCreativeAssetBinding(receipt, creativeRef, override) {
+    const asset = requireCreatedAsset(receipt, creativeRef, override.assetRef);
+    return asset.kind === "image"
+        ? {
+            id: override.assetRef,
+            assetRef: override.assetRef,
+            imageCrops: override.imageCrops,
+            imageHash: asset.imageHash,
+            kind: "image"
+        }
+        : {
+            assetRef: override.assetRef,
+            captionIds: override.captionIds,
+            id: override.assetRef,
+            kind: "video",
+            videoId: asset.videoId
+        };
+}
+function resolveCreativeFallbackBinding(receipt, entry) {
+    if (entry.assetRef) {
+        return resolveCreativeAssetBinding(receipt, entry.ref, {
+            assetRef: entry.assetRef
+        });
+    }
+    const fallbackFormat = entry.formats?.feed4x5
+        ?? entry.formats?.square1x1
+        ?? entry.formats?.story9x16;
+    if (!fallbackFormat) {
+        return undefined;
+    }
+    return resolveCreativeAssetBinding(receipt, entry.ref, fallbackFormat);
+}
+function resolveCreativePlatformCustomizations(receipt, ref, platformCustomizations) {
+    const instagramOverride = platformCustomizations?.instagram;
+    if (!instagramOverride) {
+        return undefined;
+    }
+    const asset = requireCreatedAsset(receipt, ref, instagramOverride.assetRef);
+    return {
+        instagram: {
+            ...(asset.kind === "image" ? { imageHash: asset.imageHash } : { videoId: asset.videoId }),
+            captionIds: instagramOverride.captionIds,
+            imageCrops: instagramOverride.imageCrops
+        }
+    };
+}
+function buildLaunchWarnings(spec) {
+    const warnings = new Set();
+    const adSetsByRef = new Map(spec.adSets.map((entry) => [entry.ref, entry]));
+    spec.creatives.forEach((creative) => {
+        const adsForCreative = spec.ads.filter((entry) => entry.creativeRef === creative.ref);
+        const placements = adsForCreative
+            .map((entry) => adSetsByRef.get(entry.adSetRef))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => expandPlacementTargeting(entry.targeting));
+        const automaticPlacements = placements.some((entry) => entry.automatic);
+        const unsupportedPlacements = [...new Set(placements.flatMap((entry) => entry.unsupportedPlacementIds))];
+        if (automaticPlacements && !hasPlacementFormats(creative.formats)) {
+            warnings.add(`Creative '${creative.ref}' uses automatic placements without formats.feed4x5, formats.square1x1, or formats.story9x16. Meta may crop or expand the fallback asset across Feed, Stories, and Reels.`);
+        }
+        if (unsupportedPlacements.length > 0 && hasPlacementFormats(creative.formats)) {
+            warnings.add(`Creative '${creative.ref}' targets placements outside the current formats abstraction (${formatPlacementIds(unsupportedPlacements)}). These placements will fall back to the base/default asset instead of a dedicated format slot.`);
+        }
+    });
+    return [...warnings];
+}
+function resolveSimpleCreativeSpec(receipt, entry) {
+    const fallbackAsset = resolveCreativeFallbackBinding(receipt, entry);
+    if (!fallbackAsset) {
+        throw new AppError(`Creative '${entry.ref}' is missing a fallback asset.`, ExitCode.VerificationFailed);
+    }
+    const platformCustomizations = resolveCreativePlatformCustomizations(receipt, entry.ref, entry.platformCustomizations);
+    if (entry.kind === "link-image") {
+        if (fallbackAsset.kind !== "image" || !fallbackAsset.imageHash) {
+            throw new AppError(`Creative '${entry.ref}' requires an image asset.`, ExitCode.VerificationFailed, {
+                assetRef: fallbackAsset.assetRef
+            });
+        }
+        return {
+            imageHash: fallbackAsset.imageHash,
+            kind: entry.kind,
+            linkData: entry.linkData,
+            name: entry.name,
+            pageId: entry.pageId,
+            platformCustomizations,
+            status: entry.status
+        };
+    }
+    if (fallbackAsset.kind !== "video" || !fallbackAsset.videoId) {
+        throw new AppError(`Creative '${entry.ref}' requires a video asset.`, ExitCode.VerificationFailed, {
+            assetRef: fallbackAsset.assetRef
+        });
+    }
+    return {
+        kind: entry.kind,
+        name: entry.name,
+        pageId: entry.pageId,
+        platformCustomizations,
+        status: entry.status,
+        videoData: entry.videoData,
+        videoId: fallbackAsset.videoId
+    };
+}
+function buildAssetFeedCreativeSpec(receipt, entry) {
+    if (!hasPlacementFormats(entry.formats)) {
+        return undefined;
+    }
+    const adSetsByRef = new Map(receipt.spec.adSets.map((item) => [item.ref, item]));
+    const placements = receipt.spec.ads
+        .filter((item) => item.creativeRef === entry.ref)
+        .map((item) => adSetsByRef.get(item.adSetRef))
+        .filter((item) => Boolean(item))
+        .map((item) => expandPlacementTargeting(item.targeting));
+    const unsupportedPlacements = [...new Set(placements.flatMap((item) => item.unsupportedPlacementIds))];
+    const squarePlacements = [...new Set(placements.flatMap((item) => item.squarePlacementIds))];
+    const verticalPlacements = [...new Set(placements.flatMap((item) => item.verticalPlacementIds))];
+    const feedPlacements = [...new Set(placements.flatMap((item) => item.feedPlacementIds))]
+        .filter((placementId) => !squarePlacements.includes(placementId));
+    if (unsupportedPlacements.length > 0 && !entry.assetRef) {
+        throw new AppError(`Creative '${entry.ref}' targets placements outside the current formats abstraction (${formatPlacementIds(unsupportedPlacements)}) and must provide assetRef as the explicit fallback asset.`, ExitCode.VerificationFailed);
+    }
+    const fallbackBinding = resolveCreativeFallbackBinding(receipt, entry);
+    if (!fallbackBinding) {
+        return undefined;
+    }
+    const feedBinding = entry.formats?.feed4x5
+        ? resolveCreativeAssetBinding(receipt, entry.ref, entry.formats.feed4x5)
+        : fallbackBinding;
+    const squareBinding = entry.formats?.square1x1
+        ? resolveCreativeAssetBinding(receipt, entry.ref, entry.formats.square1x1)
+        : feedBinding;
+    const storyBinding = entry.formats?.story9x16
+        ? resolveCreativeAssetBinding(receipt, entry.ref, entry.formats.story9x16)
+        : fallbackBinding;
+    return entry.kind === "link-image"
+        ? compileAssetFeedCreativeSpec({
+            fallback: fallbackBinding,
+            formatBindings: {
+                feed4x5: feedBinding,
+                square1x1: squareBinding,
+                story9x16: storyBinding
+            },
+            kind: entry.kind,
+            linkData: entry.linkData,
+            name: entry.name ?? entry.ref,
+            pageId: entry.pageId,
+            placementTargets: {
+                feed4x5: feedPlacements,
+                square1x1: squarePlacements,
+                story9x16: verticalPlacements
+            }
+        })
+        : compileAssetFeedCreativeSpec({
+            fallback: fallbackBinding,
+            formatBindings: {
+                feed4x5: feedBinding,
+                square1x1: squareBinding,
+                story9x16: storyBinding
+            },
+            kind: entry.kind,
+            name: entry.name ?? entry.ref,
+            pageId: entry.pageId,
+            placementTargets: {
+                feed4x5: feedPlacements,
+                square1x1: squarePlacements,
+                story9x16: verticalPlacements
+            },
+            videoData: entry.videoData
+        });
+}
+function resolveCampaignSpec(spec) {
+    return {
+        bidStrategy: spec.campaign.bidStrategy,
+        dailyBudget: spec.campaign.dailyBudget,
+        lifetimeBudget: spec.campaign.lifetimeBudget,
+        name: spec.campaign.name,
+        objective: spec.campaign.objective,
+        specialAdCategories: spec.campaign.specialAdCategories,
+        status: spec.campaign.status
+    };
+}
+function resolveAdSetSpec(spec, ref, campaignId) {
+    const entry = spec.adSets.find((item) => item.ref === ref);
+    if (!entry) {
+        throw new AppError(`Launch spec is missing ad set ref '${ref}'.`, ExitCode.VerificationFailed);
+    }
+    return {
+        bidAmount: entry.bidAmount,
+        bidStrategy: entry.bidStrategy,
+        billingEvent: entry.billingEvent,
+        campaignId,
+        dailyBudget: entry.dailyBudget,
+        endTime: entry.endTime,
+        lifetimeBudget: entry.lifetimeBudget,
+        name: entry.name,
+        optimizationGoal: entry.optimizationGoal,
+        promotedObject: entry.promotedObject,
+        startTime: entry.startTime,
+        status: entry.status,
+        targeting: entry.targeting
+    };
+}
+function resolveCreativeSpec(receipt, ref) {
+    const entry = findCreativeEntry(receipt, ref);
+    const assetFeedSpec = buildAssetFeedCreativeSpec(receipt, entry);
+    if (assetFeedSpec) {
+        return {
+            mode: "asset-feed",
+            spec: assetFeedSpec
+        };
+    }
+    return {
+        mode: "simple",
+        spec: resolveSimpleCreativeSpec(receipt, entry)
+    };
+}
+function resolveAdSpec(receipt, ref) {
+    const entry = receipt.spec.ads.find((item) => item.ref === ref);
+    if (!entry) {
+        throw new AppError(`Launch spec is missing ad ref '${ref}'.`, ExitCode.VerificationFailed);
+    }
+    return {
+        adSetId: requireCreatedId(receipt.created.adSets[entry.adSetRef], "ad set", entry.adSetRef),
+        creativeId: requireCreatedId(receipt.created.creatives[entry.creativeRef], "creative", entry.creativeRef),
+        name: entry.name,
+        status: entry.status
+    };
+}
+async function executeStep(service, receipt, step) {
+    switch (step.kind) {
+        case "campaign.create": {
+            const campaign = await service.createCampaign(receipt.accountId, resolveCampaignSpec(receipt.spec));
+            receipt.created.campaign = {
+                id: campaign.id,
+                ref: receipt.spec.campaign.ref
+            };
+            return;
+        }
+        case "adset.create": {
+            const campaignId = requireCreatedId(receipt.created.campaign, "campaign", receipt.spec.campaign.ref);
+            const adSet = await service.createAdSet(receipt.accountId, resolveAdSetSpec(receipt.spec, step.ref, campaignId));
+            receipt.created.adSets[step.ref] = {
+                id: adSet.id
+            };
+            return;
+        }
+        case "asset.image.upload": {
+            const assetSpec = receipt.spec.assets.find((entry) => entry.ref === step.ref && entry.kind === "image");
+            if (!assetSpec) {
+                throw new AppError(`Launch spec is missing image asset ref '${step.ref}'.`, ExitCode.VerificationFailed);
+            }
+            const uploaded = await service.uploadAdImage(receipt.accountId, assetSpec.file, assetSpec.name);
+            if (!uploaded.hash) {
+                throw new AppError(`Meta image upload for ref '${step.ref}' did not return an image hash.`, ExitCode.Provider);
+            }
+            receipt.created.assets[step.ref] = {
+                imageHash: uploaded.hash,
+                kind: "image",
+                name: uploaded.name
+            };
+            return;
+        }
+        case "asset.video.upload": {
+            const assetSpec = receipt.spec.assets.find((entry) => entry.ref === step.ref && entry.kind === "video");
+            if (!assetSpec) {
+                throw new AppError(`Launch spec is missing video asset ref '${step.ref}'.`, ExitCode.VerificationFailed);
+            }
+            const uploaded = await service.uploadAdVideo(receipt.accountId, assetSpec.file, assetSpec.name);
+            receipt.created.assets[step.ref] = {
+                kind: "video",
+                name: uploaded.name,
+                status: "uploaded",
+                videoId: uploaded.id
+            };
+            return;
+        }
+        case "asset.video.wait": {
+            const asset = receipt.created.assets[step.ref];
+            if (!asset || asset.kind !== "video") {
+                throw new AppError(`Launch receipt is missing uploaded video for ref '${step.ref}'.`, ExitCode.VerificationFailed);
+            }
+            const status = await service.waitForVideoReady(asset.videoId);
+            receipt.created.assets[step.ref] = {
+                ...asset,
+                status: status.status ?? "ready"
+            };
+            return;
+        }
+        case "creative.create": {
+            const creativeSpec = resolveCreativeSpec(receipt, step.ref);
+            const creative = creativeSpec.mode === "asset-feed"
+                ? await service.createAssetFeedCreative(receipt.accountId, creativeSpec.spec)
+                : await service.createCreative(receipt.accountId, creativeSpec.spec);
+            receipt.created.creatives[step.ref] = {
+                id: creative.id
+            };
+            return;
+        }
+        case "ad.create": {
+            const ad = await service.createAd(receipt.accountId, resolveAdSpec(receipt, step.ref));
+            receipt.created.ads[step.ref] = {
+                id: ad.id
+            };
+        }
+    }
+}
+async function runReceipt(service, receipt) {
+    receipt.status = "running";
+    receipt.lastError = undefined;
+    await persistReceipt(receipt);
+    for (const step of pendingSteps(receipt)) {
+        try {
+            await executeStep(service, receipt, step);
+            step.status = "completed";
+            receipt.lastError = undefined;
+            await persistReceipt(receipt);
+        }
+        catch (error) {
+            receipt.lastError = {
+                message: error instanceof Error ? error.message : "Unknown error",
+                stepId: step.id
+            };
+            receipt.status = error instanceof AppError && error.exitCode === ExitCode.VerificationFailed && step.kind === "asset.video.wait"
+                ? "waiting_for_video"
+                : "failed";
+            await persistReceipt(receipt);
+            if (error instanceof AppError) {
+                throw new AppError(error.message, error.exitCode, {
+                    ...(error.details ?? {}),
+                    executionId: receipt.executionId,
+                    receiptPath: receipt.receiptPath,
+                    stepId: step.id
+                });
+            }
+            throw new AppError("Launch execution failed.", ExitCode.Provider, {
+                executionId: receipt.executionId,
+                receiptPath: receipt.receiptPath,
+                stepId: step.id
+            });
+        }
+    }
+    receipt.status = "completed";
+    receipt.lastError = undefined;
+    await persistReceipt(receipt);
+    return receipt;
+}
+export class LaunchService {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    buildPlan(accountId, specPath, spec) {
+        const steps = buildLaunchSteps(spec);
+        const warnings = buildLaunchWarnings(spec);
+        return {
+            data: {
+                accountId,
+                specPath,
+                steps,
+                summary: {
+                    ads: spec.ads.length,
+                    adSets: spec.adSets.length,
+                    assets: spec.assets.length,
+                    creatives: spec.creatives.length
+                }
+            },
+            warnings
+        };
+    }
+    validate(accountId, specPath, spec) {
+        return {
+            data: {
+                accountId,
+                specPath,
+                summary: {
+                    ads: spec.ads.length,
+                    adSets: spec.adSets.length,
+                    assets: spec.assets.length,
+                    campaignRef: spec.campaign.ref,
+                    creatives: spec.creatives.length
+                },
+                valid: true
+            },
+            warnings: buildLaunchWarnings(spec)
+        };
+    }
+    async apply(options) {
+        const executionId = createExecutionId();
+        const receiptPath = await ensureWritableReceiptPath(options.receiptPath ?? defaultReceiptPath(executionId));
+        const receipt = {
+            version: 1,
+            accountId: options.accountId,
+            created: {
+                ads: {},
+                adSets: {},
+                assets: {},
+                creatives: {}
+            },
+            executionId,
+            receiptPath,
+            spec: options.spec,
+            specPath: options.specPath,
+            status: "running",
+            steps: buildLaunchSteps(options.spec),
+            updatedAt: new Date().toISOString()
+        };
+        const result = await runReceipt(this.service, receipt);
+        return {
+            data: {
+                created: summarizeCreated(result),
+                executionId: result.executionId,
+                receiptPath: result.receiptPath,
+                status: result.status
+            },
+            warnings: buildLaunchWarnings(options.spec)
+        };
+    }
+    async previewResume(receiptPath) {
+        const receipt = await readReceipt(receiptPath);
+        return {
+            created: summarizeCreated(receipt),
+            executionId: receipt.executionId,
+            pendingSteps: pendingSteps(receipt),
+            receiptPath: receipt.receiptPath,
+            status: receipt.status
+        };
+    }
+    async resume(receiptPath) {
+        const receipt = await readReceipt(receiptPath);
+        const result = await runReceipt(this.service, receipt);
+        return {
+            created: summarizeCreated(result),
+            executionId: result.executionId,
+            pendingSteps: pendingSteps(result),
+            receiptPath: result.receiptPath,
+            status: result.status
+        };
+    }
+}