@koda-sl/baker-cli 0.559.0 → 0.561.0

package/dist/adsets-FEVYHKAQ.js

@@ -0,0 +1,182 @@
+import {
+  VIEWER_TABLE_COLUMNS,
+  adSetViewerRows,
+  audienceNamesOf,
+  flattenViewerRows,
+  readAudienceNames
+} from "./chunk-G6XKD7QE.js";
+import {
+  META_LIST_SHAPE_ARGS,
+  budgetUnitHints,
+  registerMetaListSchema,
+  shapeMetaListRows,
+  writeMetaListRows
+} from "./chunk-3E74OM2E.js";
+import {
+  NAME_CONTAINS_ARG,
+  csvOrJson,
+  handleMetaError,
+  resolveAccountIdArg,
+  resolveEffectiveStatus,
+  statusFilterHints
+} from "./chunk-5H6N36LS.js";
+import {
+  rememberedJev
+} from "./chunk-4H6XLX7E.js";
+import "./chunk-QALAJNBG.js";
+import {
+  writeAdsOutput
+} from "./chunk-RBCO3C3Q.js";
+import {
+  holdUnbilledSpend
+} from "./chunk-Y5PNLB24.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-N3PASNUA.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-GO6ISZUZ.js";
+import "./chunk-2WZI36D3.js";
+import "./chunk-65Y3RCWP.js";
+import "./chunk-E56V3RFO.js";
+import "./chunk-EL3TDR5S.js";
+import "./chunk-G6U45QD3.js";
+import "./chunk-X6U3B6YK.js";
+import {
+  apiGet
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/adsets.ts
+import path from "path";
+import { defineCommand } from "citty";
+var listArgs = {
+  "account-id": { type: "string", description: "Meta ad account ID" },
+  "campaign-id": { type: "string", description: "Filter to one campaign" },
+  "effective-status": { type: "string", description: "Comma-separated effective_status filter (overrides default)" },
+  "all-statuses": { type: "boolean", description: "Drop the default ACTIVE filter" },
+  "name-contains": NAME_CONTAINS_ARG,
+  limit: { type: "string", description: "Max rows (default 1000)" },
+  "no-cache": NO_CACHE_ARG,
+  audience: {
+    type: "boolean",
+    description: "Who each ad set reaches, instead of the compact row: a viewer per ad set \u2014 temperature (cold|warm|hot), what they already know (brand/offer/product), placements, and the reasons, read from its targeting, the account's audiences and the campaign objective. Start here before writing an ad for an ad set: baker ads meta adsets --campaign-id 6123 --audience --output json"
+  },
+  ...META_LIST_SHAPE_ARGS
+};
+async function readOrEmpty(path2, params, label, hints) {
+  try {
+    return await apiGet(path2, params);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    hints.push(`Could not read the account's ${label} (${message}); the viewer was read without them.`);
+    return [];
+  }
+}
+async function writeAdSetViewers(adSets, accountParams, format, hints) {
+  const [audiences, campaigns] = await Promise.all([
+    readOrEmpty("/api/ads/meta/audiences", accountParams, "audiences", hints),
+    readOrEmpty("/api/ads/meta/campaigns", accountParams, "campaigns", hints)
+  ]);
+  const root = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+  const cacheDir = path.join(root, "canvas", ".cache");
+  const spent = [];
+  const readName = await readAudienceNames(
+    audienceNamesOf(adSets, audiences),
+    rememberedJev(path.join(cacheDir, "audience-names.json"), (u) => spent.push(u))
+  );
+  await holdUnbilledSpend(cacheDir, spent).catch(() => void 0);
+  const rows = adSetViewerRows(adSets, audiences, campaigns, readName);
+  if (rows.length > 0) {
+    hints.push(
+      `Write each ad for the viewer of the ad set it will run in, then record it in the creative's _definition.md: targetAdSet: "<ad set id>" and viewer: { temperature, knows, placements, source }.`
+    );
+  }
+  if (format === "md" || format === "csv") {
+    writeAdsOutput(flattenViewerRows(rows), format, [...VIEWER_TABLE_COLUMNS], hints);
+    return;
+  }
+  writeAdsOutput(rows, format, void 0, hints);
+}
+registerMetaListSchema(
+  "adsets",
+  "List ad sets in a Meta ad account, as a table by default: id, name, campaign_id, effective_status, optimization_goal, billing_event, bid_strategy, budgets, destination_type, is_dynamic_creative, learning_stage, end_time, created_time. Targeting is not in the compact row \u2014 ask for it with --fields id,name,targeting (or --full). --audience replaces the row with who each ad set reaches (a viewer: temperature, what they already know, placements, reasons) \u2014 read it before writing an ad for an ad set. Start here: baker ads meta adsets --campaign-id 6123 --all-statuses. --output json returns the rows in the envelope.",
+  listArgs
+);
+var listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List ad sets in a Meta ad account. Runs by default when no subcommand is given. Example: baker ads meta adsets --account-id act_123"
+  },
+  args: listArgs,
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    const effectiveStatus = resolveEffectiveStatus(args);
+    try {
+      const params = { "account-id": accountId };
+      if (args["campaign-id"]) params["campaign-id"] = args["campaign-id"];
+      if (effectiveStatus) params["effective-status"] = effectiveStatus;
+      if (args["name-contains"]) params["name-contains"] = args["name-contains"];
+      if (args.limit) params.limit = args.limit;
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/meta/adsets", params);
+      if (args.audience) {
+        const hints = statusFilterHints(data, effectiveStatus, "ad sets");
+        const accountParams = { "account-id": accountId };
+        if (args["no-cache"]) accountParams["skip-cache"] = "true";
+        await writeAdSetViewers(data, accountParams, csvOrJson(args), hints);
+        return;
+      }
+      const shaped = shapeMetaListRows("adsets", data, args);
+      writeMetaListRows("adsets", shaped, csvOrJson(args), [
+        ...statusFilterHints(data, effectiveStatus, "ad sets"),
+        ...budgetUnitHints(data)
+      ]);
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+var adsetsCommand = defineCommand({
+  meta: {
+    name: "adsets",
+    description: `List ad sets in a Meta ad account, or stage writes (create/update/pause/resume/archive/delete/duplicate/copy).
+Defaults to ACTIVE only. Write subcommands stage ops on this chat's draft.
+
+Listings print a table by default: id, name, campaign_id, effective_status, optimization_goal, billing_event,
+bid_strategy, budgets, destination_type, is_dynamic_creative, learning_stage, end_time, created_time. Targeting
+is not in the compact row \u2014 ask for it with --fields (dotted paths) or --full. --output json returns the rows as JSON.
+
+Examples:
+  baker ads meta adsets --account-id act_123
+  baker ads meta adsets --campaign-id 6123456789
+  baker ads meta adsets --account-id act_123 --all-statuses --name-contains retargeting   \u2014 find one ad set by name
+  baker ads meta adsets --campaign-id 6123456789 --fields id,name,targeting.geo_locations
+  baker ads meta adsets --campaign-id 6123456789 --audience --output json   \u2014 who each ad set reaches (viewer per ad set)
+  baker ads meta adsets create --campaign meta_temp_ab12 --name "US 25-54" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --daily-budget 50 --targeting-file t.json`
+  },
+  subCommands: {
+    list: listCommand,
+    create: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsCreateCommand),
+    update: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsUpdateCommand),
+    pause: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsPauseCommand),
+    resume: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsResumeCommand),
+    archive: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsArchiveCommand),
+    delete: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsDeleteCommand),
+    duplicate: () => import("./write-commands-SIOVTRHH.js").then((m) => m.adSetsDuplicateCommand),
+    copy: () => import("./copy-writes-X2LM5I4Z.js").then((m) => m.adSetsCopyCommand)
+  },
+  // `args` stays even though the parent has no `run`: citty scans rawArgs for the
+  // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
+  // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
+  // invocation — citty falls through to `run` after a subcommand, double-executing it.
+  args: listArgs,
+  default: "list"
+});
+export {
+  adsetsCommand
+};
+//# sourceMappingURL=adsets-FEVYHKAQ.js.map

package/dist/advertisers-2GKICB23.js

@@ -0,0 +1,125 @@
+import {
+  reportError,
+  splitList
+} from "./chunk-KDVYI4LC.js";
+import {
+  apiGet
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  applyFieldMask,
+  registerSchema,
+  writeJson,
+  writeOutput
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/advertisers.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.advertisers",
+  description: "List brands in the shared ad-dna corpus by name or domain. Use it to find your OWN advertiser (to --exclude-advertiser on search) or a competitor (to --advertiser-id on search / winners).",
+  args: {
+    query: { type: "string", description: "Brand name or domain to match (case-insensitive)", required: false },
+    platform: {
+      type: "string",
+      description: "Filter to a single platform: meta|linkedin|tiktok|google",
+      required: false
+    },
+    limit: { type: "number", description: "Max results 1-100 (default 20)", required: false, default: 20 },
+    offset: { type: "number", description: "Skip N results (pagination)", required: false, default: 0 }
+  }
+});
+function compactAdvertiser(record) {
+  return {
+    advertiser_id: String(record.advertiser_id ?? ""),
+    label: record.label ?? null,
+    platform_count: record.platform_count ?? null,
+    family_count: record.family_count ?? null,
+    active_ad_count: record.active_ad_count ?? null,
+    total_ad_count: record.total_ad_count ?? null
+  };
+}
+function advertiserNormalizer(record, full) {
+  const compact = compactAdvertiser(record);
+  if (!full) {
+    return compact;
+  }
+  return {
+    ...compact,
+    scraped_name: record.scraped_name ?? null,
+    image_url: record.image_url ?? null,
+    platforms: Array.isArray(record.platforms) ? record.platforms : [],
+    total_reach: record.total_reach ?? null,
+    last_synced_at: record.last_synced_at ?? null
+  };
+}
+var advertisersCommand = defineCommand({
+  meta: {
+    name: "advertisers",
+    description: 'List corpus advertisers by name or domain. Find your own advertiser for --exclude-advertiser, or a competitor for --advertiser-id / winners. Example: baker winning-ads advertisers "Deel" --output md'
+  },
+  args: {
+    query: { type: "positional", description: "Brand name or domain", required: false },
+    platform: {
+      type: "string",
+      description: "Filter to a single platform: meta|linkedin|tiktok|google",
+      required: false
+    },
+    limit: { type: "string", description: "Max results (default 20)", required: false },
+    offset: { type: "string", description: "Skip N results (pagination)", required: false },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: { type: "string", description: "Comma-separated field names to include", required: false },
+    full: {
+      type: "boolean",
+      description: "Include image, platforms, reach, last-synced",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = {};
+      const query = args.query;
+      if (query) {
+        params.q = query;
+      }
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      if (args.limit) {
+        params.limit = String(args.limit);
+      }
+      if (args.offset) {
+        params.offset = String(args.offset);
+      }
+      const data = await apiGet("/api/ad-library/advertisers", params);
+      const output = args.output || "json";
+      const full = args.full;
+      const rawList = Array.isArray(data?.advertisers) ? data.advertisers : [];
+      if (output === "json") {
+        const fields = splitList(args.fields);
+        const advertisers = rawList.map((a) => {
+          const row = advertiserNormalizer(a, full);
+          return fields.length > 0 ? applyFieldMask(row, fields) : row;
+        });
+        writeJson({ ok: true, data: { advertisers, total: data?.total ?? null } });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: rawList },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        advertiserNormalizer
+      );
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  advertisersCommand
+};
+//# sourceMappingURL=advertisers-2GKICB23.js.map

package/dist/advertisers-3D36UJTQ.js

@@ -0,0 +1,123 @@
+import {
+  advertisersHints
+} from "./chunk-X2OVFCRC.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-D3YAFC6K.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-FVDC6AKZ.js";
+import "./chunk-Q2JDS6WL.js";
+import "./chunk-TK7VRZKM.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/advertisers.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.advertisers",
+  description: 'Returns a ranked list of domains competing for one keyword in Google, with avg SERP position, relevance rating, estimated traffic value and visibility \u2014 domain economics, not ad copy. Despite the name it returns no headlines, descriptions or creative of any kind; for a competitor\'s actual ad copy use `baker research google-ads <competitor.com> --copy` (Google) or `baker winning-ads content <adId>` (Meta/LinkedIn). Start here: `baker research advertisers "<keyword>" --location <cc> --language <code>` to size up who owns a term. If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.',
+  args: {
+    keyword: {
+      type: "string",
+      description: "Keyword to search (positional). One search term, not a brand or a domain \u2014 this is a SERP query, not an advertiser lookup",
+      required: true
+    },
+    location: {
+      type: "string",
+      description: "Country code (us, uk, es, de...) or DataForSEO location code. Defaults to us (United States) if omitted \u2014 always set this for non-US markets",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name (en, es, spanish...). Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    limit: { type: "string", description: "Max results (default: 20, max: 100)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  domain: "Competing domain (no ad copy is returned \u2014 see hints)",
+  avg_position: "Average SERP position (1 = top)",
+  rating: "Domain relevance rating (0-100)",
+  etv: "Estimated traffic value (USD)",
+  visibility: "SERP visibility score (0-1)"
+};
+var advertisersCommand = defineCommand({
+  meta: {
+    name: "advertisers",
+    description: `Domains competing for a keyword in Google SERPs, with position, relevance, traffic value and visibility. Returns NO ad copy \u2014 for a competitor's headlines and body copy use \`baker research google-ads <competitor.com> --copy\` (Google) or \`baker winning-ads content <adId>\` (Meta/LinkedIn).
+
+Examples:
+  baker research advertisers "running shoes"
+  baker research advertisers "crm software" --location uk --limit 10
+  baker research advertisers "zapatos" --location es --language spanish`
+  },
+  args: {
+    keyword: { type: "positional", description: "Keyword to search", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    limit: { type: "string", description: "Max results (default: 20, max: 100)", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const keyword = args.keyword;
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const limit = args.limit ? Number(args.limit) : void 0;
+    const skipCache = args["no-cache"] ? true : void 0;
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const data = await apiPost("/api/research/advertisers", {
+        keyword,
+        location,
+        language,
+        limit,
+        skipCache
+      });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      const hints = advertisersHints(data.length, queryContext);
+      if (format !== "json") {
+        writeResearchOutput(data, format);
+        writeResearchHints(hints, format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data,
+        fields: FIELDS,
+        note: RESEARCH_DATA_NOTE,
+        query_context: queryContext,
+        hints
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  advertisersCommand
+};
+//# sourceMappingURL=advertisers-3D36UJTQ.js.map