@koda-sl/baker-cli 0.470.0-dev.fb31086c9 → 0.471.0

package/dist/pixels-26G2WGVF.js

@@ -0,0 +1,108 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleMetaError,
+  resolveAccountIdArg,
+  todayIso
+} from "./chunk-XNEWH3NK.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-JM7C6OHU.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-Z3GHDRUA.js";
+import {
+  apiGet
+} from "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import "./chunk-NVBBZPJP.js";
+import "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/pixels.ts
+import { defineCommand } from "citty";
+var pixelsCommand = defineCommand({
+  meta: {
+    name: "pixels",
+    description: `List Meta Pixels for an ad account, or fetch firing stats for one pixel.
+
+Examples:
+  baker ads meta pixels --account-id act_123
+  baker ads meta pixels --account-id act_123 --pixel-id 9876 --stats --days 7`
+  },
+  args: {
+    "account-id": { type: "string", description: "Meta ad account ID" },
+    "pixel-id": { type: "string", description: "Pixel ID for --stats" },
+    stats: { type: "boolean", description: "Fetch firing stats for the pixel" },
+    aggregation: {
+      type: "string",
+      description: "stats aggregation: event|browser_type|host|pixel_fire",
+      default: "event"
+    },
+    days: { type: "string", description: "Lookback days for --stats (default 7)" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "Output format", default: "json" }
+  },
+  run: async ({ args }) => {
+    try {
+      if (args.stats) {
+        await runStats(args);
+        return;
+      }
+      await runList(args);
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+async function runStats(args) {
+  const pixelId = args["pixel-id"];
+  if (!pixelId) {
+    handleMetaError(new Error("--pixel-id is required when --stats is set"));
+  }
+  const days = args.days ? Number(args.days) : 7;
+  if (!Number.isInteger(days) || days <= 0 || days > 90) {
+    handleMetaError(new Error("--days must be a positive integer \u2264 90"));
+  }
+  const params = {
+    "pixel-id": pixelId,
+    aggregation: args.aggregation ?? "event",
+    "start-time": daysAgoIso(days),
+    "end-time": todayIso()
+  };
+  if (args["no-cache"]) params["skip-cache"] = "true";
+  const data = await apiGet("/api/ads/meta/pixel-stats", params);
+  emit(data, args);
+}
+async function runList(args) {
+  const accountId = resolveAccountIdArg(args);
+  const params = { "account-id": accountId };
+  if (args["no-cache"]) params["skip-cache"] = "true";
+  const { pixels, restrictedFields } = await apiGet("/api/ads/meta/pixels", params);
+  emit(pixels, args, pixelWarnings(restrictedFields));
+}
+function pixelWarnings(restrictedFields) {
+  if (restrictedFields.length === 0) {
+    return [];
+  }
+  return [
+    {
+      code: "PIXEL_FIELDS_RESTRICTED",
+      message: `Meta withheld ${restrictedFields.join(", ")} for these pixels \u2014 the connected user holds no role in the Business that owns them. IDs, names, creation and last-fired times are complete; install code and setup details are not. To get them, the client assigns the pixel to the connected user in Meta Business settings \u2192 Data sources \u2192 Datasets.`
+    }
+  ];
+}
+function emit(data, args, warnings = []) {
+  const fmt = csvOrJson(args);
+  if (fmt !== "json") {
+    writeAdsOutput(data, fmt);
+    return;
+  }
+  writeAdsJson({ ok: true, data, ...warnings.length > 0 ? { warnings } : {} });
+}
+export {
+  pixelWarnings,
+  pixelsCommand
+};
+//# sourceMappingURL=pixels-26G2WGVF.js.map

package/dist/pixels-FJXN7Y72.js

@@ -0,0 +1,60 @@
+import {
+  schemaArgs,
+  stageChatgptOp
+} from "./chunk-7KDYPEGZ.js";
+import {
+  CHATGPT_ADS_REFERENCE
+} from "./chunk-4E2NL5OH.js";
+import "./chunk-JM7C6OHU.js";
+import "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import "./chunk-NVBBZPJP.js";
+import {
+  registerSchema
+} from "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/pixels.ts
+import { defineCommand } from "citty";
+var CREATE_ARGS = {
+  name: { type: "string", description: "What the pixel is called in Ads Manager, e.g. withbaker.com", required: true }
+};
+function pixelCreateOp(args) {
+  return { kind: "pixel.create", payload: { name: typeof args.name === "string" ? args.name.trim() : args.name } };
+}
+registerSchema({
+  command: "ads.chatgpt.pixels.create",
+  description: "Stage a new website pixel for the account, applied when the chat is published. Read `conversions` first: an account usually needs one pixel, installed on every page, and a second splits the site's events.",
+  args: schemaArgs(CREATE_ARGS)
+});
+var pixelsCreateCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: `Stage a new website pixel (applies when the chat is published).
+
+Example:
+  baker ads chatgpt pixels create --name "withbaker.com"`
+  },
+  args: CREATE_ARGS,
+  run: async ({ args }) => {
+    await stageChatgptOp(pixelCreateOp(args), CHATGPT_ADS_REFERENCE.conversions, (staged) => [
+      `Define what it counts with \`baker ads chatgpt conversions create --pixel ${staged.ref} --name \u2026 --event \u2026\`.`,
+      "After the publish, read its Pixel ID with `baker ads chatgpt conversions` and install it on the site's pages as a tracking tag."
+    ]);
+  }
+});
+var pixelsCommand = defineCommand({
+  meta: {
+    name: "pixels",
+    description: `Website pixels \u2014 what a site installs so ChatGPT Ads can count its conversions. Read them with \`baker ads chatgpt conversions\`.
+
+Example:
+  baker ads chatgpt pixels create --name "withbaker.com"`
+  },
+  subCommands: { create: pixelsCreateCommand }
+});
+export {
+  pixelCreateOp,
+  pixelsCommand
+};
+//# sourceMappingURL=pixels-FJXN7Y72.js.map

package/dist/plan-PZVXAECA.js

@@ -0,0 +1,207 @@
+import {
+  TAG_MANAGER_TIMEOUT_MS
+} from "./chunk-ZLF477SL.js";
+import {
+  funnelStepSchema
+} from "./chunk-237WE5LX.js";
+import {
+  trackingPlanErrorEnvelope
+} from "./chunk-OCFYRZQW.js";
+import {
+  ANALYTICS_EVENT_DOORS,
+  parseEventKey
+} from "./chunk-BC2BXRXY.js";
+import "./chunk-EDLZGTGN.js";
+import "./chunk-D5FY4FAK.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-JM7C6OHU.js";
+import {
+  apiPost
+} from "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import {
+  getEnv
+} from "./chunk-NVBBZPJP.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-PZVXAECA.js.map

package/dist/preview-LMX4O4SJ.js

@@ -0,0 +1,169 @@
+import {
+  FACEBOOK_PREVIEW_FORMATS,
+  INSTAGRAM_PREVIEW_FORMATS,
+  PLATFORM_SCOPED_POSITIONS,
+  previewFormatForPosition
+} from "./chunk-GOJXKIFQ.js";
+import {
+  handleMetaError
+} from "./chunk-XNEWH3NK.js";
+import {
+  writeAdsJson,
+  writeJsonEnvelope
+} from "./chunk-JM7C6OHU.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-Z3GHDRUA.js";
+import {
+  apiPost
+} from "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import "./chunk-NVBBZPJP.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-LMX4O4SJ.js.map