@koda-sl/baker-cli 0.515.0-dev.957976bb7 → 0.516.0

package/dist/study-writes-IR7RSSTK.js

@@ -0,0 +1,470 @@
+import {
+  bareAccountId,
+  failWriteValidation,
+  loadJsonFileArg,
+  requireTarget,
+  stageOp
+} from "./chunk-ILPHIYAL.js";
+import "./chunk-Q3GSVLE5.js";
+import "./chunk-GDFJOCDO.js";
+import "./chunk-M7QZSEHF.js";
+import {
+  repeatedValues
+} from "./chunk-ERSX3MKH.js";
+import "./chunk-SCAGMX2I.js";
+import "./chunk-4NZ47VXO.js";
+import "./chunk-D5FY4FAK.js";
+import "./chunk-QPESDKZC.js";
+import "./chunk-Y2JZX6JB.js";
+import "./chunk-6DPSWLGY.js";
+import "./chunk-E44NXCTL.js";
+import "./chunk-EJGAJHLB.js";
+import "./chunk-LNNTHEL7.js";
+import "./chunk-FOMFU2RX.js";
+import "./chunk-PSGIHSNC.js";
+import "./chunk-PONLPYD7.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-NSBNIPIW.js";
+import "./chunk-X7VQFLHI.js";
+import "./chunk-LU4HI4KI.js";
+import "./chunk-LGK7UWBN.js";
+import {
+  registerSchema
+} from "./chunk-Q7US4OOA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/study-writes.ts
+import { defineCommand } from "citty";
+
+// src/commands/ads/meta/study-flags.ts
+var DAY_SECONDS = 86400;
+function studyTimeFlag(value, flag) {
+  if (/^\d{10}$/.test(value)) return Number(value);
+  if (/^\d{13}$/.test(value)) return Math.floor(Number(value) / 1e3);
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new Error(`${flag} must be an ISO date/time (2026-10-20T08:00Z) or epoch seconds`);
+  }
+  return Math.floor(ms / 1e3);
+}
+function numberFlag(value, flag) {
+  const n = Number(value.replace(/%$/, ""));
+  if (!Number.isFinite(n)) throw new Error(`${flag} must be a number, got "${value}"`);
+  return n;
+}
+function evenSplit(count) {
+  const base = Math.floor(100 / count * 100) / 100;
+  const first = Math.round((100 - base * (count - 1)) * 100) / 100;
+  return Array.from({ length: count }, (_, index) => index === 0 ? first : base);
+}
+function endTime(flags, start) {
+  if (flags.end) return studyTimeFlag(flags.end, "--end");
+  if (flags.days !== void 0) {
+    if (start === void 0) throw new Error("--days counts from --start \u2014 pass --start too, or --end");
+    return start + Math.round(numberFlag(flags.days, "--days") * DAY_SECONDS);
+  }
+  return void 0;
+}
+function confidence(value) {
+  if (value === void 0) return void 0;
+  const n = numberFlag(value, "--confidence");
+  return n > 1 ? n / 100 : n;
+}
+function measure(flags) {
+  const events = [flags["measure-event"] ?? []].flat().filter(Boolean);
+  if (flags["measure-pixel"]) {
+    if (events.length === 0) {
+      throw new Error("--measure-pixel needs --measure-event (the pixel event that counts, e.g. Lead or Purchase)");
+    }
+    const name = flags["measure-name"] ?? events.join(" or ");
+    return [
+      { name, type: "CONVERSIONS", is_primary: true, adspixels: [{ id: flags["measure-pixel"], event_names: events }] }
+    ];
+  }
+  if (flags["measure-conversion"]) {
+    const name = flags["measure-name"] ?? "Custom conversion";
+    return [{ name, type: "CONVERSIONS", is_primary: true, customconversions: [{ id: flags["measure-conversion"] }] }];
+  }
+  if (events.length > 0) throw new Error("--measure-event counts on a pixel \u2014 pass --measure-pixel too");
+  return void 0;
+}
+function versionLetter(index) {
+  return `Version ${String.fromCharCode(65 + index)}`;
+}
+function observationEnd(flags) {
+  const until = flags["observe-until"];
+  return until ? { observation_end_time: studyTimeFlag(until, "--observe-until") } : {};
+}
+function liftFromFlags(flags, start, end) {
+  const level = flags.adsets?.length ? "adsets" : flags.campaigns?.length ? "campaigns" : void 0;
+  if (!level) throw new Error("a lift study measures --campaigns or --adsets (comma-separated, all in one group)");
+  if (flags.split) {
+    throw new Error(
+      "a lift study shows the ads to everyone but a held-out share \u2014 set that share with --holdout (e.g. --holdout 10), not --split"
+    );
+  }
+  const names = flags["version-names"] ?? [];
+  if (names.length > 1) {
+    throw new Error("a lift study runs as one group \u2014 pass one --version-names for it, or none (default Lift)");
+  }
+  const holdout = flags.holdout === void 0 ? 10 : numberFlag(flags.holdout, "--holdout");
+  const objectives = measure(flags);
+  const conf = confidence(flags.confidence);
+  if (!objectives)
+    throw new Error(
+      "a lift study needs a measure: --measure-pixel <id> --measure-event Lead, or --measure-conversion <id>"
+    );
+  return {
+    name: flags.name ?? "",
+    ...flags.description ? { description: flags.description } : {},
+    type: "LIFT",
+    start_time: start,
+    end_time: end,
+    ...observationEnd(flags),
+    cells: [
+      {
+        name: names[0] ?? "Lift",
+        treatment_percentage: 100 - holdout,
+        control_percentage: holdout,
+        [level]: (level === "adsets" ? flags.adsets : flags.campaigns) ?? []
+      }
+    ],
+    objectives,
+    ...conf !== void 0 ? { confidence_level: conf } : {}
+  };
+}
+function creativeTestFromFlags(flags, start, end) {
+  const ads = flags.ads ?? [];
+  if (ads.length < 2) throw new Error("a creative test compares 2 to 5 ads of one ad set: --ads <ad>,<ad>");
+  if (!flags["test-daily-budget"])
+    throw new Error("pass --test-daily-budget: the part of the ad set's daily budget the test spends");
+  const shares = flags.split?.map((share) => numberFlag(share, "--split")) ?? evenSplit(ads.length);
+  const names = flags["version-names"] ?? [];
+  const objectives = measure(flags);
+  const conf = confidence(flags.confidence);
+  return {
+    name: flags.name ?? "",
+    ...flags.description ? { description: flags.description } : {},
+    type: "SPLIT_TEST_V2",
+    start_time: start,
+    end_time: end,
+    ...observationEnd(flags),
+    testDailyBudget: { amount: flags["test-daily-budget"] },
+    cells: ads.map((id, index) => ({
+      name: names[index] ?? versionLetter(index),
+      treatment_percentage: shares[index] ?? 0,
+      ads: [id]
+    })),
+    ...conf !== void 0 ? { confidence_level: conf } : {},
+    ...objectives ? { objectives } : {}
+  };
+}
+function otherStudyFromFlags(flags, type) {
+  if (!flags.start) throw new Error("pass --start: when the test begins (ISO, in the future)");
+  const start = studyTimeFlag(flags.start, "--start");
+  const end = endTime(flags, start);
+  if (end === void 0) throw new Error("pass --days or --end");
+  return type === "lift" ? liftFromFlags(flags, start, end) : creativeTestFromFlags(flags, start, end);
+}
+var TYPE_FLAGS = {
+  adsets: ["split", "lift"],
+  campaigns: ["split", "lift"],
+  ads: ["creative"],
+  holdout: ["lift"],
+  "test-daily-budget": ["creative"],
+  "observe-until": ["lift", "creative"]
+};
+function refuseForeignFlags(flags, kind) {
+  for (const [flag, kinds] of Object.entries(TYPE_FLAGS)) {
+    const value = flags[flag];
+    const given = Array.isArray(value) ? value.length > 0 : value !== void 0 && value !== "";
+    if (given && !kinds.includes(kind)) {
+      throw new Error(
+        `--${flag} is for ${kinds.map((other) => `--type ${other}`).join(" or ")}, not a ${kind} test \u2014 drop it, or pass the --type it belongs to`
+      );
+    }
+  }
+}
+function studyCreateFromFlags(flags) {
+  const kind = flags.type ?? "split";
+  if (kind !== "split" && kind !== "lift" && kind !== "creative") throw new Error("--type is split, lift or creative");
+  refuseForeignFlags(flags, kind);
+  return kind === "split" ? splitTestFromFlags(flags) : otherStudyFromFlags(flags, kind);
+}
+function splitTestFromFlags(flags) {
+  const level = flags.adsets?.length ? "adsets" : flags.campaigns?.length ? "campaigns" : void 0;
+  if (!level) {
+    throw new Error("pass --adsets or --campaigns: one id per version, e.g. --adsets 6123,6124");
+  }
+  const ids = (level === "adsets" ? flags.adsets : flags.campaigns) ?? [];
+  if (!flags.start) {
+    throw new Error("pass --start: when the test begins (ISO, in the future \u2014 after this chat publishes)");
+  }
+  const start = studyTimeFlag(flags.start, "--start");
+  const end = endTime(flags, start);
+  if (end === void 0) throw new Error("pass --days (how long it runs, 7\u201330 recommended) or --end");
+  const shares = flags.split?.map((share) => numberFlag(share, "--split")) ?? evenSplit(ids.length);
+  if (shares.length !== ids.length) {
+    throw new Error(`--split gives one share per version, in order: ${ids.length} versions, ${shares.length} shares`);
+  }
+  const names = flags["version-names"] ?? [];
+  const objectives = measure(flags);
+  const conf = confidence(flags.confidence);
+  return {
+    name: flags.name ?? "",
+    ...flags.description ? { description: flags.description } : {},
+    type: "SPLIT_TEST",
+    start_time: start,
+    end_time: end,
+    cells: ids.map((id, index) => ({
+      name: names[index] ?? versionLetter(index),
+      treatment_percentage: shares[index] ?? 0,
+      [level]: [id]
+    })),
+    ...conf !== void 0 ? { confidence_level: conf } : {},
+    ...objectives ? { objectives } : {}
+  };
+}
+function studyUpdateFromFlags(flags) {
+  const start = flags.start ? studyTimeFlag(flags.start, "--start") : void 0;
+  const end = endTime(flags, start);
+  const cells = flags.split?.map((pair) => {
+    const match = /^(\d+)=(.+)$/.exec(pair);
+    if (!match?.[1] || !match[2]) {
+      throw new Error(
+        `--split on a live test names each version by its cell id: --split 2231801141074157=60 (\`studies --study-id\` lists them), got "${pair}"`
+      );
+    }
+    return { id: match[1], treatment_percentage: numberFlag(match[2], "--split") };
+  });
+  const conf = confidence(flags.confidence);
+  const update = {};
+  if (flags.name) update.name = flags.name;
+  if (flags.description) update.description = flags.description;
+  if (start !== void 0) update.start_time = start;
+  if (end !== void 0) update.end_time = end;
+  if (conf !== void 0) update.confidence_level = conf;
+  if (cells) update.cells = cells;
+  return update;
+}
+var FILE_COMPANION_FLAGS = /* @__PURE__ */ new Set(["file", "name", "account-id"]);
+function studyFileIgnoredFlags(args) {
+  const given = Object.entries(args).filter(([key, value]) => key !== "_" && value !== void 0 && value !== false && value !== "").map(([key]) => key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)).filter((key) => !FILE_COMPANION_FLAGS.has(key));
+  return [...new Set(given)].map((key) => `--${key}`);
+}
+
+// src/commands/ads/meta/study-writes.ts
+var STAGED_NOTE = "Staged until publish \u2014 review with `baker ads meta draft`.";
+var timeArgs = {
+  start: {
+    type: "string",
+    description: "When the test begins: ISO date/time (2026-10-20T08:00Z) or epoch seconds \u2014 in the future, after this chat publishes"
+  },
+  end: { type: "string", description: "When it ends (ISO or epoch seconds). Or --days" },
+  days: { type: "string", description: "How long it runs, from --start: 1\u201330 days (Meta recommends at least 7)" }
+};
+var createArgs = {
+  "account-id": { type: "string", description: "Numeric account ID or act_N" },
+  name: { type: "string", description: "Test name, shown in Ads Manager \u2192 Experiments" },
+  description: { type: "string", description: "What the test answers, e.g. which audience brings cheaper leads" },
+  adsets: {
+    type: "string",
+    description: "One ad set per version (repeatable or comma-separated; meta_temp_* refs from this chat work) \u2014 ad sets that differ in ONE thing"
+  },
+  campaigns: { type: "string", description: "One campaign per version instead (repeatable or comma-separated)" },
+  "version-names": {
+    type: "string",
+    description: 'A name for each version, in order \u2014 repeat once per version: --version-names Broad --version-names "Lookalike, 1%" (default Version A, Version B, \u2026; --type lift takes one, for its group)'
+  },
+  split: {
+    type: "string",
+    description: "Each version's share of the audience in %, in order, adding up to 100 (default even). Not for --type lift, which splits by --holdout"
+  },
+  ...timeArgs,
+  confidence: { type: "string", description: "How sure Meta must be to call a winner: 80, 90 or 95 (%)" },
+  "measure-pixel": {
+    type: "string",
+    description: "Decide on cost per pixel event: the pixel id (with --measure-event)"
+  },
+  "measure-event": {
+    type: "string",
+    description: "The pixel event that counts: Lead, Purchase, CompleteRegistration, \u2026"
+  },
+  "measure-conversion": { type: "string", description: "Decide on cost per custom conversion instead: its id" },
+  "measure-name": { type: "string", description: "What to call the measure in the review (default: the event)" },
+  type: {
+    type: "string",
+    description: "split (default: A/B test of ad sets or campaigns) | lift (a held-out group shows what the ads add \u2014 needs a measure) | creative (2\u20135 ads of one ad set, --ads)"
+  },
+  ads: { type: "string", description: "--type creative: one ad per version (comma-separated or repeatable)" },
+  holdout: { type: "string", description: "--type lift: % of the audience that never sees the ads (default 10)" },
+  "test-daily-budget": {
+    type: "string",
+    description: "--type creative: the part of the ad set's daily budget the test spends, e.g. 2"
+  },
+  "observe-until": {
+    type: "string",
+    description: "--type lift or creative: count results until this time (ISO) \u2014 after the end, for late conversions (default the end)"
+  },
+  file: {
+    type: "string",
+    description: "JSON with the full test in Meta's shape \u2014 {name, start_time, end_time, cells:[{name, treatment_percentage, adsets|campaigns}], objectives, confidence_level}, times in unix seconds. Needed for several ad sets per version. --name overrides its name; any other flag beside --file is refused."
+  }
+};
+function schemaArgs(args) {
+  return Object.fromEntries(Object.entries(args).map(([key, arg]) => [key, { ...arg, required: false }]));
+}
+function listValues(rawArgs, flag, parsed) {
+  const values = repeatedValues(rawArgs, flag, parsed).flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean);
+  return values.length > 0 ? values : void 0;
+}
+function wholeValues(rawArgs, flag, parsed) {
+  const values = repeatedValues(rawArgs, flag, parsed).map((value) => value.trim()).filter(Boolean);
+  return values.length > 0 ? values : void 0;
+}
+function studyFlagsFromArgs(args, rawArgs) {
+  const text = (key) => typeof args[key] === "string" && args[key] !== "" ? String(args[key]) : void 0;
+  return {
+    name: text("name"),
+    description: text("description"),
+    adsets: listValues(rawArgs, "adsets", args.adsets),
+    campaigns: listValues(rawArgs, "campaigns", args.campaigns),
+    "version-names": wholeValues(rawArgs, "version-names", args["version-names"]),
+    split: listValues(rawArgs, "split", args.split),
+    start: text("start"),
+    end: text("end"),
+    days: text("days"),
+    confidence: text("confidence"),
+    "measure-name": text("measure-name"),
+    "measure-pixel": text("measure-pixel"),
+    "measure-event": listValues(rawArgs, "measure-event", args["measure-event"]),
+    "measure-conversion": text("measure-conversion"),
+    type: text("type"),
+    ads: listValues(rawArgs, "ads", args.ads),
+    holdout: text("holdout"),
+    "test-daily-budget": text("test-daily-budget"),
+    "observe-until": text("observe-until")
+  };
+}
+function orFail(build) {
+  try {
+    return build();
+  } catch (err) {
+    failWriteValidation(err instanceof Error ? err.message : String(err));
+  }
+}
+registerSchema({
+  command: "ads.meta.studies.create",
+  description: "Stage a Meta A/B test (split test) \u2014 created at publish. Meta splits the audience so each person sees one version and calls the winner. Shorthand: --adsets <a>,<b> (or --campaigns) --start <ISO> --days 14 [--split 50,50] [--version-names \u2026] [--confidence 90] [--measure-pixel <id> --measure-event Lead | --measure-conversion <id>]. Without a measure Meta decides on cost per result of the campaigns' objective. Or --file with Meta's shape. --type lift: a held-out group (--holdout, default 10%) shows what the --campaigns/--adsets add, needs a measure. --type creative: 2\u20135 --ads of one ad set compared on --test-daily-budget.",
+  args: schemaArgs(createArgs)
+});
+var studiesCreateCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: `Stage a Meta A/B test. ${STAGED_NOTE}
+Set it up properly: versions that differ in ONE thing (duplicate the ad set with \`adsets duplicate\`, change the audience, placement or creative on the copy), each with its own budget, none in another running test.
+Examples:
+  baker ads meta studies create --name "Broad vs lookalike" --adsets 6123,6124 --start 2026-10-20T08:00Z --days 14
+  baker ads meta studies create --name "Lead cost" --adsets 6123,meta_temp_ab12 --start 2026-10-20T08:00Z --days 14 --confidence 90 --measure-pixel 1275507706837548 --measure-event Lead
+  baker ads meta studies create --file test.json`
+  },
+  args: createArgs,
+  run: async ({ args, rawArgs }) => {
+    const accountId = bareAccountId(args);
+    const file = loadJsonFileArg(args.file);
+    const ignored = Object.keys(file).length > 0 ? studyFileIgnoredFlags(args) : [];
+    if (ignored.length > 0) {
+      failWriteValidation(
+        `--file holds the whole test, so ${ignored.join(", ")} would be ignored \u2014 put them in the file, or drop --file`
+      );
+    }
+    const flags = studyFlagsFromArgs(args, rawArgs);
+    const payload = Object.keys(file).length > 0 ? { ...file, ...flags.name ? { name: flags.name } : {} } : orFail(() => studyCreateFromFlags(flags));
+    await stageOp({ kind: "adStudy.create", accountId, payload });
+  }
+});
+var updateArgs = {
+  id: { type: "positional", description: "Test id (or a meta_temp_* ref staged in this chat)", required: true },
+  "account-id": createArgs["account-id"],
+  name: createArgs.name,
+  description: createArgs.description,
+  ...timeArgs,
+  split: {
+    type: "string",
+    description: "New shares by cell id, adding up to 100: --split 2231801141074157=60,1425644426371372=40 (`studies --study-id` lists the cell ids). Only before it starts."
+  },
+  confidence: createArgs.confidence
+};
+registerSchema({
+  command: "ads.meta.studies.update",
+  description: "Stage a change to a Meta A/B test: rename, describe, move the end (--end; --days counts from a new --start), re-time or re-split it (--start, --split <cell_id>=60,\u2026) before it starts, change the confidence. A running test keeps its start and split \u2014 end it and start a new one to change those.",
+  args: {
+    id: updateArgs.id,
+    ...schemaArgs(Object.fromEntries(Object.entries(updateArgs).filter(([key]) => key !== "id")))
+  }
+});
+var studiesUpdateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: `Stage a change to an A/B test. ${STAGED_NOTE}
+Example: baker ads meta studies update 6123 --end 2026-11-10T08:00Z`
+  },
+  args: updateArgs,
+  run: async ({ args, rawArgs }) => {
+    const accountId = bareAccountId(args);
+    const target = requireTarget(args, "test");
+    const payload = orFail(() => studyUpdateFromFlags(studyFlagsFromArgs(args, rawArgs)));
+    if (Object.keys(payload).length === 0) {
+      failWriteValidation("nothing to change \u2014 pass --name, --description, --start, --end, --split or --confidence");
+    }
+    await stageOp({ kind: "adStudy.update", accountId, target, payload });
+  }
+});
+var ACTIONS = {
+  end: {
+    payload: { end_now: true },
+    note: "The test stops a few minutes after publish and keeps its results \u2014 use this to stop a running test early."
+  },
+  delete: {
+    payload: { status: "DELETED" },
+    note: "Deleting removes the test from Meta, results and all. For a running or finished test prefer `studies end` unless the user asked to delete it; for one that has not started, deleting is how to cancel it."
+  }
+};
+function actionCommand(name) {
+  const { payload, note } = ACTIONS[name];
+  registerSchema({
+    command: `ads.meta.studies.${name}`,
+    description: `Stage ${name === "end" ? "ending" : "deleting"} a Meta A/B test. ${note}`,
+    args: {
+      id: { type: "positional", description: "Test id", required: true },
+      "account-id": { type: "string", description: "Meta ad account ID (act_123)", required: false }
+    }
+  });
+  return defineCommand({
+    meta: { name, description: `Stage ${name === "end" ? "ending" : "deleting"} an A/B test. ${note} ${STAGED_NOTE}` },
+    args: {
+      id: { type: "positional", description: "Test id", required: true },
+      "account-id": createArgs["account-id"]
+    },
+    run: async ({ args }) => {
+      const accountId = bareAccountId(args);
+      await stageOp({
+        kind: "adStudy.update",
+        accountId,
+        target: requireTarget(args, "test"),
+        payload
+      });
+    }
+  });
+}
+var studiesEndCommand = actionCommand("end");
+var studiesDeleteCommand = actionCommand("delete");
+export {
+  studiesCreateCommand,
+  studiesDeleteCommand,
+  studiesEndCommand,
+  studiesUpdateCommand,
+  studyFlagsFromArgs
+};
+//# sourceMappingURL=study-writes-IR7RSSTK.js.map

package/dist/sync-4YTVVEVC.js

@@ -0,0 +1,57 @@
+import {
+  reportError,
+  reportInvalid
+} from "./chunk-EDWRTYEO.js";
+import {
+  testimonialSourcesSyncRequestSchema
+} from "./chunk-PC3FJEZH.js";
+import "./chunk-CAZGM2NX.js";
+import "./chunk-NZS3KEQ2.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-NSBNIPIW.js";
+import "./chunk-46YLDIQG.js";
+import {
+  apiPost
+} from "./chunk-X7VQFLHI.js";
+import "./chunk-LU4HI4KI.js";
+import "./chunk-LGK7UWBN.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-Q7US4OOA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/testimonials/sources/sync.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "testimonials.sources.sync",
+  description: "Import a review source's new reviews now. Only reviews newer than the last import are read where the site allows it.",
+  args: { id: { type: "string", description: "Source id from `testimonials sources list`", required: true } }
+});
+var syncCommand = defineCommand({
+  meta: {
+    name: "sync",
+    description: "Import a review source's new reviews now.\n\nExample: baker testimonials sources sync <source-id>"
+  },
+  args: { id: { type: "positional", description: "Source id from `testimonials sources list`", required: true } },
+  run: async ({ args }) => {
+    const parsed = testimonialSourcesSyncRequestSchema.safeParse({ id: String(args.id ?? "") });
+    if (!parsed.success) reportInvalid(parsed.error.issues[0]);
+    try {
+      const data = await apiPost("/api/testimonials/sources/sync", parsed.data);
+      writeJson({
+        ok: true,
+        data,
+        hints: data.started ? void 0 : ["An import was already running for this source; nothing new was started."]
+      });
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  syncCommand
+};
+//# sourceMappingURL=sync-4YTVVEVC.js.map