@koda-sl/baker-cli 0.194.0-dev.5dba041c4 → 0.194.0

package/dist/cli.js

@@ -47,7 +47,7 @@ import {
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-5YX3QOT3.js";
+} from "./chunk-O5GXFPWC.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -15740,6 +15740,7 @@ var PLACEMENT_TARGETING_DOC = "https://developers.facebook.com/docs/marketing-ap
 var CONSTRAINED_PLACEMENTS = [
   {
     position: "facebook_reels_overlay",
+    reportedAs: "facebook_reels_overlay",
     platform: "facebook",
     kind: "constraint",
     note: "Ads on Facebook Reels take two shapes and a stock 9:16 video fits neither: overlay ads are 'a single, static image ad' (JPG/PNG, 1:1, 0% ratio tolerance, headline capped at 10 characters), and post-loop ads are 1:1 video of 4-15 seconds. Expect a long-headline 9:16 creative to look wrong here.",
@@ -15748,6 +15749,7 @@ var CONSTRAINED_PLACEMENTS = [
   },
   {
     position: "explore_home",
+    reportedAs: "instagram_explore_grid_home",
     platform: "instagram",
     kind: "constraint",
     note: "Marketing API placement asset customization states 'The explore_home placement only supports the SINGLE_IMAGE format', but Meta's own Ads Guide lists Instagram Explore home under video specs. Check the account's play rate for this position before treating it as image-only.",
@@ -15756,6 +15758,7 @@ var CONSTRAINED_PLACEMENTS = [
   },
   {
     position: "right_hand_column",
+    reportedAs: "right_hand_column",
     platform: "facebook",
     kind: "correction",
     note: "Facebook right column publishes full video specs (MP4/MOV/GIF, 1:1 at 1440x1440 or mobile-only 4:5 at 1440x1800, 1 second to 241 minutes) \u2014 it is NOT image-only. Its real constraint is that it cannot be the only placement for a video, collection, or canvas ad.",
@@ -15767,30 +15770,30 @@ var FACEBOOK_PREVIEW_FORMATS = {
   feed: "MOBILE_FEED_STANDARD",
   right_hand_column: "RIGHT_COLUMN_STANDARD",
   marketplace: "MARKETPLACE_MOBILE",
-  story: "FACEBOOK_STORY_MOBILE",
+  facebook_stories: "FACEBOOK_STORY_MOBILE",
   facebook_reels: "FACEBOOK_REELS_MOBILE",
   facebook_reels_overlay: "FACEBOOK_REELS_BANNER",
   instream_video: "INSTREAM_VIDEO_MOBILE",
   video_feeds: "INSTREAM_VIDEO_MOBILE"
 };
 var INSTAGRAM_PREVIEW_FORMATS = {
-  stream: "INSTAGRAM_STANDARD",
-  story: "INSTAGRAM_STORY",
-  reels: "INSTAGRAM_REELS",
-  explore: "INSTAGRAM_EXPLORE_CONTEXTUAL",
-  explore_home: "INSTAGRAM_EXPLORE_GRID_HOME",
-  ig_search: "INSTAGRAM_SEARCH_CHAIN",
-  profile_feed: "INSTAGRAM_PROFILE_FEED"
+  feed: "INSTAGRAM_STANDARD",
+  instagram_stories: "INSTAGRAM_STORY",
+  instagram_reels: "INSTAGRAM_REELS",
+  instagram_explore: "INSTAGRAM_EXPLORE_CONTEXTUAL",
+  instagram_explore_grid_home: "INSTAGRAM_EXPLORE_GRID_HOME",
+  instagram_search: "INSTAGRAM_SEARCH_CHAIN",
+  instagram_profile_feed: "INSTAGRAM_PROFILE_FEED"
 };
-var PLATFORM_SCOPED_POSITIONS = /* @__PURE__ */ new Set(["story", "profile_feed"]);
+var PLATFORM_SCOPED_POSITIONS = /* @__PURE__ */ new Set(["feed"]);
 function previewFormatForPosition(position, platform) {
   if (platform === "facebook") return FACEBOOK_PREVIEW_FORMATS[position];
   if (platform === "instagram") return INSTAGRAM_PREVIEW_FORMATS[position];
   if (PLATFORM_SCOPED_POSITIONS.has(position)) return void 0;
   return FACEBOOK_PREVIEW_FORMATS[position] ?? INSTAGRAM_PREVIEW_FORMATS[position];
 }
-function placementFormatNote(position) {
-  return CONSTRAINED_PLACEMENTS.find((p) => p.position === position);
+function placementFormatNote(reportedPosition) {
+  return CONSTRAINED_PLACEMENTS.find((p) => p.reportedAs === reportedPosition);
 }
 function positionsMissingRequiredFeed(targeting) {
   const positions = targeting?.facebook_positions;
@@ -17525,8 +17528,8 @@ var metaDraftCommand = defineCommand62({
 import { defineCommand as defineCommand63 } from "citty";
 
 // src/commands/ads/meta/placement-delivery.ts
-var MIN_IMPRESSIONS = 100;
-var SILENT_PLAY_RATE = 0.02;
+var MIN_IMPRESSIONS = 20;
+var SILENT_FRACTION_OF_REFERENCE = 0.1;
 var PLAYING_REFERENCE_RATE = 0.5;
 function toNumber(value) {
   const n = Number(value);
@@ -17576,10 +17579,17 @@ function placementDeliveryHints(rows) {
   const carriesVideoMetrics = rows.some((row) => Array.isArray(row.video_play_actions));
   if (!carriesVideoMetrics || !isSingleAdQuery(rows)) return [];
   const placements = aggregate(rows);
-  const plays = placements.some((p) => p.impressions >= MIN_IMPRESSIONS && p.playRate >= PLAYING_REFERENCE_RATE);
-  if (!plays) return [];
-  const silent = placements.filter((p) => p.impressions >= MIN_IMPRESSIONS && p.playRate < SILENT_PLAY_RATE).sort((a, b) => b.impressions - a.impressions);
-  if (silent.length === 0) return [];
+  const judgeable = placements.filter((p) => p.impressions >= MIN_IMPRESSIONS);
+  const impressions = judgeable.reduce((total, p) => total + p.impressions, 0);
+  const reference = impressions > 0 ? judgeable.reduce((total, p) => total + p.plays, 0) / impressions : 0;
+  if (reference < PLAYING_REFERENCE_RATE) return [];
+  const silent = judgeable.filter((p) => p.playRate < reference * SILENT_FRACTION_OF_REFERENCE).sort((a, b) => b.impressions - a.impressions);
+  if (silent.length === 0) {
+    const worst = [...judgeable].sort((a, b) => a.playRate - b.playRate)[0];
+    return [
+      `Checked every placement above ${MIN_IMPRESSIONS} impressions against this ad's own play rate (${(reference * 100).toFixed(0)}%): no placement is failing to play the video${worst ? `, the lowest being ${worst.platform}/${worst.position} at ${(worst.playRate * 100).toFixed(0)}%` : ""}. So placements do not explain a "it shows as a still image" report \u2014 rule out autoplay off or data saver in the viewer's own app, which renders every video as its cover frame account-wide.`
+    ];
+  }
   const hints = silent.map((placement) => {
     const note = placementFormatNote(placement.position);
     const documented = note ? ` Meta documents this placement: ${note.note}` : "";
@@ -17712,6 +17722,11 @@ function shouldAutoAsync(body) {
   }
   return false;
 }
+function wantsAsync(asyncFlag, body) {
+  if (asyncFlag === true) return true;
+  if (asyncFlag === false) return false;
+  return shouldAutoAsync(body);
+}
 function applyDateRange(body, args) {
   const range = getDateRange(args);
   if (range.datePreset) body.datePreset = range.datePreset;
@@ -17760,9 +17775,9 @@ function buildBody(args) {
 async function pollAsync(reportRunId) {
   const start = Date.now();
   while (Date.now() - start < POLL_MAX_MS) {
-    const status = await apiPost(
-      `/api/ads/meta/insights/async/status?report-run-id=${encodeURIComponent(reportRunId)}`,
-      {}
+    const status = await apiGet(
+      "/api/ads/meta/insights/async/status",
+      { "report-run-id": reportRunId }
     );
     if (status.async_status === "Job Completed") return;
     if (status.async_status === "Job Failed" || status.async_status === "Job Skipped") {
@@ -17860,8 +17875,10 @@ Async is automatic for heavy queries; pass --async to force it, or --no-async to
     "use-account-attribution": { type: "boolean", description: "Use account-saved attribution setting" },
     "use-unified-attribution": { type: "boolean", description: "Use ad-set unified attribution setting" },
     limit: { type: "string", description: "Max rows (default 1000)" },
-    async: { type: "boolean", description: "Force async submit-and-poll path" },
-    "no-async": { type: "boolean", description: "Refuse the auto-async fallback for heavy queries" },
+    // Declaring `no-async` too would be a trap: citty resolves it to `async: false`
+    // and never fills an arg of that name, so the declaration reads as supported
+    // while nothing consumes it.
+    async: { type: "boolean", description: "Force the async submit-and-poll path (--no-async refuses it)" },
     "no-sort": { type: "boolean", description: "Skip default spend-desc sort" },
     "skip-cache": { type: "boolean", description: "Bypass server-side cache" },
     output: { type: "string", description: "Output format", default: "json" }
@@ -17880,7 +17897,7 @@ Async is automatic for heavy queries; pass --async to force it, or --no-async to
     }
     const body = buildBody(args);
     const fmt = csvOrJson(args);
-    const wantAsync = Boolean(args.async) || !args["no-async"] && shouldAutoAsync(body);
+    const wantAsync = wantsAsync(args.async, body);
     try {
       const rows = wantAsync ? await runAsync(body) : await apiPost("/api/ads/meta/insights", body);
       const sorted = args["no-sort"] ? rows : sortRowsBySpendDesc(rows);
@@ -18093,11 +18110,11 @@ function resolvePlacement(position, platform) {
   }
   if (PLATFORM_SCOPED_POSITIONS.has(position) && !platformArg) {
     failPreviewValidation(
-      `--placement ${position} names a different surface on Facebook and on Instagram \u2014 add --platform facebook or --platform instagram`
+      `--placement ${position} names a different surface on Facebook and on Instagram \u2014 add --platform facebook or --platform instagram (the breakdown row's publisher_platform)`
     );
   }
   failPreviewValidation(
-    `No Meta preview format is published for placement "${position}". Meta does not document one for every placement (Facebook notifications and profile feed, Instagram search among them), so this placement cannot be previewed \u2014 report it as unverified rather than inferring what it renders. Previewable placements: ${listPlacements()}`
+    `No Meta preview format is published for placement "${position}". Meta does not document one for every placement (facebook_notification and facebook_profile_feed among them), so this placement cannot be previewed \u2014 report it as unverified rather than inferring what it renders. Pass the platform_position exactly as the insights breakdown spelled it: targeting names a few surfaces differently (story, reels, explore_home) and those names never appear in a breakdown. Previewable placements: ${listPlacements()}`
   );
 }
 function listPlacements() {
@@ -18132,7 +18149,7 @@ Examples:
       type: "string",
       description: "platform_position from an insights breakdown (e.g. facebook_reels_overlay) \u2014 resolved to an ad_format"
     },
-    platform: { type: "string", description: "facebook|instagram \u2014 disambiguates --placement story / profile_feed" },
+    platform: { type: "string", description: "facebook|instagram \u2014 required for --placement feed, which both report" },
     "list-formats": { type: "boolean", description: "Print the ad_format values and placement mappings, then exit" },
     "out-file": { type: "string", description: "Save iframe HTML to this path" },
     "skip-cache": { type: "boolean", description: "Bypass server-side cache" }