@koda-sl/baker-cli 0.470.0 → 0.472.0

package/dist/plan-NUGTA2QS.js

@@ -0,0 +1,207 @@
+import {
+  TAG_MANAGER_TIMEOUT_MS
+} from "./chunk-PLBUJ2L6.js";
+import {
+  funnelStepSchema
+} from "./chunk-237WE5LX.js";
+import {
+  trackingPlanErrorEnvelope
+} from "./chunk-35WVBJDG.js";
+import {
+  ANALYTICS_EVENT_DOORS,
+  parseEventKey
+} from "./chunk-BC2BXRXY.js";
+import "./chunk-EDLZGTGN.js";
+import "./chunk-D5FY4FAK.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-CXT6Q7KP.js";
+import {
+  apiPost
+} from "./chunk-QG2WPVKE.js";
+import "./chunk-TSOJM4EO.js";
+import {
+  getEnv
+} from "./chunk-5TTHWWON.js";
+import {
+  registerSchema
+} from "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/analytics/plan.ts
+import { readFileSync } from "fs";
+
+// ../api/src/analytics/trackingPlanWire.ts
+import { z as z2 } from "zod";
+
+// ../api/src/analytics/trackingPlan.ts
+import { z } from "zod";
+var text = z.string().trim().min(1).max(2e3);
+var key = z.string().trim().min(1).max(100);
+var webUrl = z.url().refine(
+  (value) => URL.canParse(value) && ["https:", "http:"].includes(new URL(value).protocol),
+  "Use a website address"
+);
+var trackingEventSchema = z.object({
+  eventKey: key.refine((value) => parseEventKey(value) !== null, "Use an existing Baker event key"),
+  name: text,
+  purpose: z.enum(["conversion", "progress", "diagnostic", "uncounted"]),
+  door: z.enum(ANALYTICS_EVENT_DOORS),
+  sourceEvent: key.optional(),
+  emitterEvidence: text.optional(),
+  status: z.enum(["prepared", "waiting", "published", "verified"]),
+  requirement: text.optional(),
+  owner: text.optional(),
+  verificationEvidence: text.optional()
+}).superRefine((event, ctx) => {
+  if (event.status === "waiting") {
+    if (!event.requirement || !event.owner)
+      ctx.addIssue({ code: "custom", message: "A waiting event needs its requirement and owner" });
+  } else if (!event.emitterEvidence) {
+    ctx.addIssue({ code: "custom", message: "A prepared event needs evidence that the source emits it" });
+  }
+  if (["published", "verified"].includes(event.status) && !event.verificationEvidence) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Published or verified tracking needs evidence; a staged tag is only prepared"
+    });
+  }
+});
+var trackingJourneySchema = z.object({
+  key,
+  name: text,
+  entryUrls: z.array(webUrl).max(50),
+  destinationUrl: webUrl,
+  strategy: z.enum(["native", "embed", "api", "link"]),
+  status: z.enum(["supported", "waiting"]),
+  requiredFields: z.array(key).max(100),
+  attribution: text,
+  acceptanceEvidence: text.optional(),
+  continuationEvidence: text.optional(),
+  requirement: text.optional(),
+  owner: text.optional()
+}).superRefine((journey, ctx) => {
+  if (journey.strategy === "link" && journey.requiredFields.length > 0)
+    ctx.addIssue({
+      code: "custom",
+      message: "A link handoff must not capture details that the destination asks for again"
+    });
+  if (journey.status === "waiting" && (!journey.requirement || !journey.owner))
+    ctx.addIssue({ code: "custom", message: "A waiting journey needs its requirement and owner" });
+  if (journey.status === "supported" && journey.strategy === "api" && (!journey.acceptanceEvidence || !journey.continuationEvidence))
+    ctx.addIssue({
+      code: "custom",
+      message: "An API replacement needs accepted-submission and continuation evidence"
+    });
+});
+var trackingPlanSchema = z.object({
+  journeys: z.array(trackingJourneySchema).max(30),
+  events: z.array(trackingEventSchema).max(100)
+}).superRefine((plan, ctx) => {
+  for (const entries of [plan.journeys.map((journey) => journey.key), plan.events.map((event) => event.eventKey)]) {
+    if (new Set(entries).size !== entries.length)
+      ctx.addIssue({ code: "custom", message: "Each journey and event must appear once" });
+  }
+});
+
+// ../api/src/analytics/trackingPlanWire.ts
+var key2 = z2.string().trim().min(1).max(100);
+var variableName = z2.string().trim().min(1).max(200).refine((value) => !/[{}<>"'\\\r\n]/.test(value), "Use a plain container variable name");
+var trackingInstallationSchema = z2.object({
+  containerId: key2,
+  baseTagName: key2,
+  folderId: key2.optional(),
+  consent: z2.enum(["auto", "strict"]).default("auto"),
+  measure: z2.enum(["campaigns", "outcomes", "all"]).default("campaigns"),
+  events: z2.array(
+    z2.object({
+      eventKey: key2.refine((value) => parseEventKey(value) !== null, "Use an existing Baker event key"),
+      tagName: key2,
+      triggerId: key2,
+      properties: z2.record(key2, variableName).default({}),
+      eventIdVariable: variableName.optional()
+    })
+  ).max(50)
+});
+var trackingPlanRequestSchema = z2.object({
+  chatId: z2.string().optional(),
+  plan: trackingPlanSchema.optional(),
+  wireConversions: z2.boolean().default(false),
+  steps: z2.array(funnelStepSchema).max(30).optional(),
+  installation: trackingInstallationSchema.optional()
+}).superRefine((request, ctx) => {
+  if (!request.plan && (request.installation || request.wireConversions || request.steps))
+    ctx.addIssue({ code: "custom", message: "Preparation needs the agreed tracking plan" });
+});
+var trackingPlanResponseSchema = z2.object({
+  ok: z2.literal(true),
+  data: z2.object({ plan: trackingPlanSchema.nullable(), staged: z2.boolean() }),
+  hints: z2.array(z2.string()).optional()
+});
+
+// src/commands/analytics/plan.ts
+import { defineCommand } from "citty";
+var description = "Start here before building a replacement Form: read the agreed journeys, event names, purposes and readiness. --json @plan.json stages the complete plan, with optional wireConversions, funnel steps and a managed Tag Manager installation. Each event records its actual emitter or the missing change and owner. Prepared is not verified. See analytics.md for the contract. Repeating installation preparation replaces its own staged tags; applies only at Publish. --full includes evidence; the default keeps the decision inventory compact.";
+var args = {
+  json: {
+    type: "string",
+    description: "Preparation request as JSON or @path; omit to read the effective plan",
+    required: false
+  },
+  full: { type: "boolean", description: "Include all journey and verification evidence", required: false }
+};
+registerSchema({ command: "analytics.plan", description, args });
+var planCommand = defineCommand({
+  meta: { name: "plan", description },
+  args,
+  run: async ({ args: args2 }) => {
+    try {
+      const input = args2.json ? JSON.parse(args2.json.startsWith("@") ? readFileSync(args2.json.slice(1), "utf8") : args2.json) : {};
+      const parsed = trackingPlanRequestSchema.parse(input);
+      const body = { ...parsed, chatId: getEnv().BAKER_CHAT_ID };
+      const response = trackingPlanResponseSchema.parse(
+        // Preparing stages the Tag Manager install, which queues behind other companies' requests.
+        await apiPost("/api/analytics/plan", body, { timeoutMs: TAG_MANAGER_TIMEOUT_MS })
+      );
+      const plan = response.data.plan;
+      writeJsonEnvelope({
+        ...response,
+        data: {
+          ...response.data,
+          plan: args2.full || !plan ? plan : {
+            journeys: plan.journeys.map(
+              ({ key: key3, name, strategy, status, destinationUrl, requirement, owner }) => ({
+                key: key3,
+                name,
+                strategy,
+                status,
+                destinationUrl,
+                requirement,
+                owner
+              })
+            ),
+            events: plan.events.map(
+              ({ eventKey, name, purpose, door, sourceEvent, status, requirement, owner }) => ({
+                eventKey,
+                name,
+                purpose,
+                door,
+                sourceEvent,
+                status,
+                requirement,
+                owner
+              })
+            )
+          }
+        }
+      });
+    } catch (error) {
+      writeJsonEnvelope({ ok: false, error: trackingPlanErrorEnvelope(error) });
+      process.exitCode = 1;
+    }
+  }
+});
+export {
+  planCommand
+};
+//# sourceMappingURL=plan-NUGTA2QS.js.map

package/dist/preview-FQIQRVT3.js

@@ -0,0 +1,169 @@
+import {
+  FACEBOOK_PREVIEW_FORMATS,
+  INSTAGRAM_PREVIEW_FORMATS,
+  PLATFORM_SCOPED_POSITIONS,
+  previewFormatForPosition
+} from "./chunk-GOJXKIFQ.js";
+import {
+  handleMetaError
+} from "./chunk-HR3HS56F.js";
+import {
+  writeAdsJson,
+  writeJsonEnvelope
+} from "./chunk-CXT6Q7KP.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-Z3GHDRUA.js";
+import {
+  apiPost
+} from "./chunk-QG2WPVKE.js";
+import "./chunk-TSOJM4EO.js";
+import "./chunk-5TTHWWON.js";
+import "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/preview.ts
+import { writeFileSync } from "fs";
+import { defineCommand } from "citty";
+var VALID_AD_FORMATS = [
+  "DESKTOP_FEED_STANDARD",
+  "MOBILE_FEED_STANDARD",
+  "MOBILE_FEED_BASIC",
+  "RIGHT_COLUMN_STANDARD",
+  "MOBILE_FULLWIDTH",
+  "MOBILE_INTERSTITIAL",
+  "MOBILE_BANNER",
+  "MOBILE_MEDIUM_RECTANGLE",
+  "MOBILE_NATIVE",
+  "FACEBOOK_STORY_MOBILE",
+  "FACEBOOK_REELS_MOBILE",
+  "INSTAGRAM_STORY",
+  "INSTAGRAM_REELS",
+  "INSTAGRAM_REELS_OVERLAY",
+  "INSTAGRAM_STANDARD",
+  "INSTAGRAM_EXPLORE_CONTEXTUAL",
+  "INSTAGRAM_EXPLORE_GRID_HOME",
+  "INSTAGRAM_SEARCH_CHAIN",
+  "INSTAGRAM_SHOP",
+  "INSTAGRAM_PROFILE_FEED",
+  "INSTREAM_VIDEO_DESKTOP",
+  "INSTREAM_VIDEO_MOBILE",
+  "FACEBOOK_REELS_BANNER",
+  "FACEBOOK_REELS_STICKER",
+  "MESSENGER_MOBILE_INBOX_MEDIA",
+  "MESSENGER_MOBILE_STORY_MEDIA",
+  "AUDIENCE_NETWORK_OUTSTREAM_VIDEO",
+  "AUDIENCE_NETWORK_INSTREAM_VIDEO_MOBILE",
+  "AUDIENCE_NETWORK_REWARDED_VIDEO",
+  "INSTANT_ARTICLE_STANDARD",
+  "MARKETPLACE_MOBILE",
+  "BIZ_DISCO_FEED_MOBILE"
+];
+function failPreviewValidation(message) {
+  writeAdsJson({ ok: false, error: { code: "VALIDATION_ERROR", message } });
+  process.exit(1);
+}
+function resolvePlacement(position, platform) {
+  const platformArg = typeof platform === "string" ? platform.toLowerCase() : void 0;
+  if (platformArg && platformArg !== "facebook" && platformArg !== "instagram") {
+    failPreviewValidation("--platform must be facebook or instagram");
+  }
+  const format = previewFormatForPosition(position, platformArg);
+  if (format) {
+    return format;
+  }
+  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 (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_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() {
+  const facebook = Object.keys(FACEBOOK_PREVIEW_FORMATS).join(", ");
+  const instagram = Object.keys(INSTAGRAM_PREVIEW_FORMATS).join(", ");
+  return `facebook \u2014 ${facebook}; instagram \u2014 ${instagram}`;
+}
+var previewCommand = defineCommand({
+  meta: {
+    name: "preview",
+    description: `Generate a Meta-hosted preview iframe for a creative or ad. Returns iframe HTML which you
+can embed or save to a file. The iframe URL contains a short-lived access token \u2014 treat as secret.
+
+Start here when you need to know what a creative looks like in one specific placement \u2014 this is
+Meta's own renderer, so it settles "does my video show as a still image there?" without guessing.
+Pass the placement straight from an insights breakdown with --placement (a platform_position value),
+or a Meta ad_format with --ad-format. Run --list-formats to see both sets.
+
+Examples:
+  baker ads meta preview --creative-id 6123 --ad-format MOBILE_FEED_STANDARD
+  baker ads meta preview --creative-id 6123 --placement facebook_reels_overlay --platform facebook
+  baker ads meta preview --ad-id 9988 --ad-format INSTAGRAM_REELS --out-file /tmp/preview.html
+  baker ads meta preview --account-id act_123 --creative '{"object_story_spec":{...}}' --ad-format MOBILE_FEED_STANDARD`
+  },
+  args: {
+    "creative-id": { type: "string", description: "Existing creative ID" },
+    "ad-id": { type: "string", description: "Existing ad ID" },
+    "account-id": { type: "string", description: "Required when previewing an unpublished --creative spec" },
+    creative: { type: "string", description: "JSON spec of an unpublished creative (e.g. object_story_spec)" },
+    "ad-format": { type: "string", description: "Meta ad_format enum value (--list-formats to see them)" },
+    placement: {
+      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 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" },
+    "no-cache": NO_CACHE_ARG
+  },
+  run: async ({ args }) => {
+    if (args["list-formats"]) {
+      writeAdsJson({
+        ok: true,
+        data: {
+          adFormats: VALID_AD_FORMATS,
+          placements: { facebook: FACEBOOK_PREVIEW_FORMATS, instagram: INSTAGRAM_PREVIEW_FORMATS }
+        }
+      });
+      return;
+    }
+    const placement = args.placement;
+    const adFormat = placement ? resolvePlacement(placement, args.platform) : args["ad-format"];
+    if (!adFormat) {
+      failPreviewValidation("pass --ad-format or --placement (see --list-formats)");
+    }
+    if (!VALID_AD_FORMATS.includes(adFormat)) {
+      failPreviewValidation(
+        `Invalid --ad-format "${adFormat}". Meta publishes no complete ad_format enum, so this is the set we know: ${VALID_AD_FORMATS.join(", ")}. To preview a placement you saw in an insights breakdown, pass --placement <platform_position> instead of guessing a format name.`
+      );
+    }
+    const body = { adFormat };
+    if (args["creative-id"]) body.creativeId = args["creative-id"];
+    if (args["ad-id"]) body.adId = args["ad-id"];
+    if (args["account-id"]) body.accountId = args["account-id"];
+    if (args.creative) body.creative = args.creative;
+    if (args["no-cache"]) body.skipCache = true;
+    try {
+      const data = await apiPost("/api/ads/meta/preview", body);
+      const html = data.map((d) => d.body).join("\n");
+      const hints = placement ? [
+        `Rendered ${placement} as ad_format ${adFormat}. Open the iframe to SEE it \u2014 Meta does not document what it renders for a creative a placement cannot take, so a preview you looked at is the evidence, and anything you did not look at stays unverified.`
+      ] : [];
+      if (args["out-file"]) {
+        const summary = { ok: true, data: { file: args["out-file"], rows: data.length, adFormat } };
+        writeFileSync(args["out-file"], html, "utf-8");
+        writeJsonEnvelope(hints.length > 0 ? { ...summary, hints } : summary);
+        return;
+      }
+      writeJsonEnvelope(hints.length > 0 ? { ok: true, data, hints } : { ok: true, data });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+export {
+  previewCommand
+};
+//# sourceMappingURL=preview-FQIQRVT3.js.map

package/dist/profile-KHOHP4NN.js

@@ -0,0 +1,159 @@
+import {
+  IDEA_HINT
+} from "./chunk-IMQY53XT.js";
+import {
+  reportError
+} from "./chunk-4AQJJHOM.js";
+import {
+  apiGet
+} from "./chunk-QG2WPVKE.js";
+import "./chunk-TSOJM4EO.js";
+import "./chunk-5TTHWWON.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/profile.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.profile",
+  description: "What one brand is doing, read off its ads: estimated spend (a range over every ad from `since` to today, the last 30 days, and a min.), what it launched lately and what still runs, the tests it ran and the version it kept, format and platform mix, top landing pages, audiences (Google Ads: declared targeting and the countries its ads were shown in, EU-shown ads only), similar brands, and when it was last checked. Compact by default; --full returns every launch, calendar day and landing page.",
+  args: {
+    advertiser: { type: "string", description: "Advertiser id (from `advertisers` or `following`)", required: true },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "Return the whole profile", required: false, default: false }
+  }
+});
+var COMPACT_LAUNCHES = 15;
+var COMPACT_TOP = 5;
+var STALE_DAYS = 35;
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function compactProfile(p) {
+  return {
+    last_checked_at: p.freshness.last_checked_at,
+    next_scan_at: p.freshness.next_scan_at,
+    spend: p.spend ? {
+      currency: p.spend.currency,
+      min: p.spend.min,
+      range: [p.spend.low, p.spend.high],
+      since: p.spend.since ? p.spend.since.slice(0, 10) : null,
+      last_30_days: { min: p.spend.last_30_days.min, range: [p.spend.last_30_days.low, p.spend.last_30_days.high] },
+      by_platform: p.spend.by_platform.map(
+        (b) => b.high === 0 && (b.unpriced_ads ?? 0) > 0 ? {
+          platform: b.platform,
+          unpriced: `no delivery published for its ${b.unpriced_ads} ads: spend unknown, never $0`
+        } : {
+          platform: b.platform,
+          range: [b.low, b.high],
+          ...b.last_30_days ? { last_30_days: [b.last_30_days.low, b.last_30_days.high] } : {}
+        }
+      ),
+      ads_counted: {
+        measured: p.spend.measured_ads,
+        estimated: p.spend.extrapolated_ads,
+        not_counted: p.spend.unpriced_ads
+      }
+    } : null,
+    counts: p.counts,
+    media_mix: p.media_mix,
+    platform_split: p.platform_split,
+    launch_weeks: p.launch_weeks,
+    recent_launches: p.recent_launches.slice(0, COMPACT_LAUNCHES).map((l) => ({
+      ad_id: l.ad_id,
+      platform: l.platform,
+      format: l.format,
+      headline: l.headline,
+      first_seen_at: l.first_seen_at,
+      stage: l.stage,
+      idea: l.idea ?? null
+    })),
+    tests: p.tests.slice(0, COMPACT_TOP).map((t) => ({
+      concept: t.concept,
+      launched_at: t.launched_at,
+      versions: t.versions,
+      still_running: t.still_running,
+      status: t.status,
+      winner_ad_id: t.winner_ad_id,
+      what_differed: t.what_differed
+    })),
+    landing_pages: p.landing_pages.slice(0, COMPACT_TOP).map((l) => ({ page: l.page, ads: l.ads, active_ads: l.active_ads })),
+    audiences: {
+      inferred: p.audiences.inferred.slice(0, COMPACT_TOP),
+      measured_countries: p.audiences.measured?.countries.slice(0, COMPACT_TOP) ?? null,
+      targeting: p.audiences.targeting ? {
+        ages: p.audiences.targeting.ages.slice(0, COMPACT_TOP),
+        genders: p.audiences.targeting.genders.slice(0, COMPACT_TOP),
+        locations: p.audiences.targeting.locations.slice(0, COMPACT_TOP),
+        countries: p.audiences.targeting.countries.slice(0, COMPACT_TOP)
+      } : null
+    },
+    similar: p.similar.slice(0, COMPACT_TOP)
+  };
+}
+function profileHints(p, now) {
+  const hints = [];
+  if (p.spend) {
+    hints.push(
+      'Spend is an estimate from the reach platforms publish \xD7 benchmark prices, in USD: quote it as a range ("at least $min, likely $low\u2013$high since <since>"; `range` covers every ad from `since` to today, `last_30_days` the last month), never as one exact figure.'
+    );
+    if (p.spend.unpriced_ads > 0) {
+      hints.push(
+        `${p.spend.unpriced_ads} ads publish no reach and are not counted (\`ads_counted.not_counted\`; \`by_platform\` names the channel), so real spend is higher than the range: say so whenever you quote it. \`estimated\` ads are priced from the brand's similar ads.`
+      );
+    }
+  } else {
+    hints.push(
+      "No platform publishes delivery for this brand's ads, so its spend is unknown: say so, never report $0."
+    );
+  }
+  const checked = p.freshness.last_checked_at ? Date.parse(p.freshness.last_checked_at) : null;
+  if (checked === null || now.getTime() - checked > STALE_DAYS * DAY_MS) {
+    hints.push(
+      "This brand was not checked in the last 5 weeks, so what still runs may be out of date: `baker winning-ads refresh <advertiser>` re-scans it."
+    );
+  }
+  if (p.recent_launches.some((l) => l.idea)) {
+    hints.push(
+      `${IDEA_HINT} \`launch_weeks\` counts \`new_ideas\` and \`idea_ads\` per week; \`counts.unique_ideas\` is every concept the brand ran.`
+    );
+  }
+  if (p.tests.some((t) => t.status === "decided" && t.winner_ad_id)) {
+    hints.push("Open a test's winner with `baker winning-ads content <ad-id>` to see what the brand kept.");
+  }
+  return hints;
+}
+var profileCommand = defineCommand({
+  meta: {
+    name: "profile",
+    description: "What one brand is doing: spend estimate, launches and what still runs, tests and the version kept, mixes, landing pages, audiences, similar brands. Start here: baker winning-ads profile adv_123 (add --platform meta to narrow, --full for everything)"
+  },
+  args: {
+    advertiser: { type: "positional", description: "Advertiser id", required: true },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "Return the whole profile", required: false, default: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = { id: String(args.advertiser) };
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const profile = await apiGet("/api/ad-library/advertiser-profile", params);
+      writeJson({
+        ok: true,
+        data: { advertiser_id: String(args.advertiser), ...args.full ? profile : compactProfile(profile) },
+        hints: profileHints(profile, /* @__PURE__ */ new Date())
+      });
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  compactProfile,
+  profileCommand,
+  profileHints
+};
+//# sourceMappingURL=profile-KHOHP4NN.js.map