@koda-sl/baker-cli 0.462.0 → 0.464.0

package/dist/chunk-NQ47WGLK.js

@@ -0,0 +1,533 @@
+import {
+  adFieldPlan,
+  adRows
+} from "./chunk-MC6DQQBV.js";
+import {
+  reportError,
+  splitList
+} from "./chunk-FDNECEXO.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-64RONDRZ.js";
+import {
+  registerSchema,
+  scopedWinnersSearchRequestSchema,
+  staticFormatPatternSchema,
+  winnerSearchScopeSchema,
+  winnersSortSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-RHA6K4WJ.js";
+
+// src/commands/winning-ads/search.ts
+import { defineCommand } from "citty";
+var FORMAT_PATTERN_DESCRIPTION = `Comma list of static containers, the best proven ads in them from any category (\`winning-ads formats\` ranks them for a segment): ${staticFormatPatternSchema.options.join(", ")}`;
+var STAGE_DESCRIPTION = "Comma list of where the ad is in its life: new (\u22647 days running), testing (\u226421), proven (\u226460), evergreen (longer), killed_early (stopped within 2 weeks: a lost test), retired, unverified (brand not checked recently). What competitors kept: --stage proven,evergreen";
+var SURVIVED_TEST_DESCRIPTION = "Only the version a brand kept after testing it against other versions of the same concept: the strongest public sign it works";
+var LANGUAGE_DESCRIPTION = "Comma list of ISO 639-1 codes (es,en) for the language the ad's copy and voiceover are in; where it ran is --country";
+registerSchema({
+  command: "winning-ads.search",
+  description: "Search the ad-dna corpus of scored winning ads, the company's followed brands first. Returns a lean shortlist (advertiser, summary, scores, days_active/active/winner_category as proof, media_url, visual/container/mechanism, and who the ad was made for: audience_temperature/funnel_stage/advertiser_size/presumes_brand_knowledge, when known) to pick a reference to reproduce. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry. Each row carries its stage (new, testing, proven, evergreen, killed_early, retired, unverified) and survived_test when it is the version its brand kept after testing; --survived-test or --stage proven,evergreen keep only what competitors kept. Only designed pictures and videos come back by default (no Google search, Shopping or app ads); --format text asks for Google search ads (their words), --all-kinds for everything. A value outside a closed list (--platform, --format, --winner-category, --awareness, --audience-temperature, --funnel-stage, --advertiser-size, --format-pattern, --stage, --sort) is refused with error.fix.validValues.",
+  args: {
+    query: { type: "string", description: "Free-text natural-language query", required: false },
+    scope: {
+      type: "string",
+      description: "Which brands to draw from: followed-first (default: followed brands first, topped up from the library when too few clear the relevance floor; the whole library when the company follows nobody), followed (only brands the company follows), all (the whole shared library). Every result carries source: followed|library.",
+      required: false,
+      default: "followed-first"
+    },
+    "ref-ad-id": {
+      type: "string",
+      description: "Find ads similar to this ad id (instead of free text)",
+      required: false
+    },
+    limit: { type: "number", description: "Max results 1-100 (default 10)", required: false, default: 10 },
+    "max-per-advertiser": {
+      type: "number",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "number", description: "Relevance floor 0-1; trims weak matches", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a browse with no query: winner (default, by winner score), longest_running (by days active), newest (by first seen). Ignored when a query is given: a query ranks by relevance blended with winner score.",
+      required: false,
+      default: "winner"
+    },
+    platform: {
+      type: "string",
+      description: "Comma list: meta,linkedin,tiktok,google",
+      required: false
+    },
+    format: { type: "string", description: "Comma list: video,static,carousel,text", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list: winner,scaled_winner,evergreen,rising,untested,dud,\u2026",
+      required: false
+    },
+    awareness: {
+      type: "string",
+      description: "Comma list: unaware,problem_aware,solution_aware,product_aware,most_aware",
+      required: false
+    },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold (strangers), 1_warm_engaged (engaged, not yet visited), 2_hot_visited (visited the site), 3_customer. A cold brief takes 0_cold references.",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads whose copy only works if the viewer already knows the brand (an unexplained logo, mascot, nickname or promise). Ads not judged yet are kept and show no presumes_brand_knowledge. Use it whenever the ad you are making is for viewers who don't know the brand.",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": {
+      type: "string",
+      description: "Restrict to these advertiser ids (browse one brand's winners)",
+      required: false
+    },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand (a reused ad is marked already_adapted instead)",
+      required: false
+    },
+    "first-seen-after": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen after this",
+      required: false
+    },
+    "first-seen-before": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen before this",
+      required: false
+    },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of hook SEEDS (from `winning-ads hooks`) \u2014 narrow to ads on a proven hook pattern",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return ads nobody can build a creative on: Google search text, Shopping and app ads. By default a search returns only designed pictures and videos; --format text asks for search ads alone (their words: headlines, claims, offers).",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "Return one varied set (different brands, containers, hooks) instead of rank order: one reference per concept in a single call",
+      required: false,
+      default: false
+    }
+  }
+});
+function setNumber(body, key, value) {
+  if (value !== void 0 && value !== "") {
+    body[key] = Number(value);
+  }
+}
+function setList(target, key, value) {
+  const list = splitList(value);
+  if (list.length) {
+    target[key] = list;
+  }
+}
+function setString(target, key, value) {
+  if (value) {
+    target[key] = value;
+  }
+}
+function buildSearchBody(args) {
+  const body = {};
+  if (args.query) {
+    body.free_text_query = args.query;
+  }
+  if (args.refAdId) {
+    body.ref_ad_id = args.refAdId;
+  }
+  setString(body, "scope", args.scope);
+  setNumber(body, "limit", args.limit);
+  setNumber(body, "max_per_advertiser", args.maxPerAdvertiser);
+  setNumber(body, "min_relevance", args.minRelevance);
+  setString(body, "sort", args.sort);
+  if (args.diverse) {
+    body.diverse = true;
+  }
+  const hardFilters = {};
+  setList(hardFilters, "platform", args.platform);
+  setList(hardFilters, "format", args.format);
+  setList(hardFilters, "winner_category", args.winnerCategory);
+  setList(hardFilters, "awareness_stage", args.awareness);
+  setList(hardFilters, "audience_temperature", args.audienceTemperature);
+  setList(hardFilters, "funnel_stage", args.funnelStage);
+  setList(hardFilters, "advertiser_size", args.advertiserSize);
+  if (args.excludeBrandReliant) {
+    hardFilters.presumes_brand_knowledge = false;
+  }
+  setList(hardFilters, "country", args.country);
+  setList(hardFilters, "language", args.language?.toLowerCase());
+  setList(hardFilters, "advertiser_ids", args.advertiserId);
+  setList(hardFilters, "exclude_advertiser_ids", args.excludeAdvertiser);
+  setList(hardFilters, "hook_archetype_seeds", args.hookArchetype);
+  setList(hardFilters, "static_format_patterns", args.formatPattern);
+  setString(hardFilters, "first_seen_after", args.firstSeenAfter);
+  setString(hardFilters, "first_seen_before", args.firstSeenBefore);
+  setList(hardFilters, "lifecycle_stage", args.stage);
+  if (args.survivedTest) {
+    hardFilters.survived_test = true;
+  }
+  if (Object.keys(hardFilters).length) {
+    body.hard_filters = hardFilters;
+  }
+  return body;
+}
+function designedByDefault(body, opts) {
+  const filters = body.hard_filters ?? {};
+  const wantsText = Array.isArray(filters.format) && filters.format.includes("text");
+  if (opts.allKinds || wantsText) return body;
+  return { ...body, hard_filters: { ...filters, design_reference: true } };
+}
+function searchHints(data) {
+  const hints = [];
+  if ((data.following_count ?? 0) === 0) {
+    hints.push(
+      'The company follows no brands, so these references come from brands tracked by others and may be off-market. Follow competitors with `baker winning-ads follow-competitors "<domain,domain>"` to get on-market references, then search with --scope followed-first.'
+    );
+  } else if (data.scope === "followed" && (data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No followed brand has an ad on this brief. Re-run with --scope followed-first to top up from the whole library."
+    );
+  } else if ((data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No reference matched the brief and every filter. Search once more with ONE change: drop the narrowest filter (--country, --audience-temperature or one --awareness stage) or shorten the brief to the product and who it is for. For a container your concept needs, --format-pattern <container> with no query returns the best proven ads in it from any category."
+    );
+  }
+  const kept = keptHint(data.results ?? []);
+  if (kept) hints.push(kept);
+  const adapted = (data.results ?? []).filter(
+    (r) => r?.baker_uses?.ours === true
+  ).length;
+  if (adapted > 0) {
+    hints.push(
+      `${adapted} of these references you already adapted into a creative (already_adapted), so they are listed last. A second creative from the same ad is a variant, not a new concept: pick another unless the user asked for one.`
+    );
+  }
+  return hints;
+}
+var KEPT_STAGES = /* @__PURE__ */ new Set(["proven", "evergreen"]);
+var UNTESTED_STAGES = /* @__PURE__ */ new Set(["new", "testing"]);
+function keptHint(results) {
+  const rows = results.map((r) => r ?? {});
+  const kept = rows.filter((r) => r.survived_test === true || KEPT_STAGES.has(String(r.stage))).length;
+  if (kept > 0 && kept < rows.length) {
+    return `${kept} of these are what competitors kept after testing (survived_test, or stage proven/evergreen): prefer them as references; a new or testing ad may still be cut.`;
+  }
+  if (kept === 0 && rows.some((r) => UNTESTED_STAGES.has(String(r.stage)))) {
+    return "None of these has outlived a test yet (stage new/testing): to reference what competitors kept, search once more with --survived-test or --stage proven,evergreen.";
+  }
+  return null;
+}
+var UNKNOWN_COUNTRY_RE = /Unknown country code\(s\): ([^.]+)\. Countries with ads: ([^.]+)\./;
+function unknownCountryFix(message) {
+  const match = UNKNOWN_COUNTRY_RE.exec(message);
+  if (!match) {
+    return null;
+  }
+  const unknownCountries = splitList(match[1]);
+  const validCountries = splitList(match[2]);
+  if (unknownCountries.length === 0 || validCountries.length === 0) {
+    return null;
+  }
+  return {
+    action: "retry_with_a_valid_country",
+    explanation: `${unknownCountries.join(", ")} is not a country the winning-ads library holds ads for. Re-run with codes from \`validCountries\`, or drop --country to search every market.`,
+    unknownCountries,
+    validCountries
+  };
+}
+function searchErrorFix(code, message) {
+  if (code === "UNAVAILABLE") {
+    return {
+      action: "retry_narrower_once",
+      explanation: "The library did not answer this search in time. Retry once with a shorter brief, a lower --limit or fewer filters. If it fails again, continue without a reference and say so; do not stop the creative work."
+    };
+  }
+  return unknownCountryFix(message);
+}
+function reportSearchError(err) {
+  const fix = err instanceof ApiError ? searchErrorFix(err.code, err.message) : null;
+  if (err instanceof ApiError && fix) {
+    writeJson({ ok: false, error: { code: err.code, message: err.message, fix } });
+    process.exit(1);
+  }
+  reportError(err);
+}
+var FLAG_FOR_FIELD = {
+  limit: "--limit",
+  max_per_advertiser: "--max-per-advertiser",
+  min_relevance: "--min-relevance",
+  platform: "--platform",
+  format: "--format",
+  winner_category: "--winner-category",
+  awareness_stage: "--awareness",
+  audience_temperature: "--audience-temperature",
+  funnel_stage: "--funnel-stage",
+  advertiser_size: "--advertiser-size",
+  static_format_patterns: "--format-pattern",
+  first_seen_after: "--first-seen-after",
+  first_seen_before: "--first-seen-before",
+  lifecycle_stage: "--stage"
+};
+function flagFor(path) {
+  const field = String(path[0] === "hard_filters" ? path[1] : path[0]);
+  return FLAG_FOR_FIELD[field] ?? field;
+}
+function schemaRejection(body) {
+  const parsed = scopedWinnersSearchRequestSchema.safeParse(body, { reportInput: true });
+  if (parsed.success) {
+    return null;
+  }
+  const [first] = parsed.error.issues;
+  if (!first) {
+    return { message: "Invalid search" };
+  }
+  const flag = flagFor(first.path);
+  if (first.code === "invalid_value") {
+    const sameFlag = parsed.error.issues.filter((i) => i.code === "invalid_value" && flagFor(i.path) === flag);
+    const invalidValues = sameFlag.map((i) => String(i.input));
+    const validValues = first.values.map(String);
+    return {
+      message: `Unknown ${flag} value${invalidValues.length > 1 ? "s" : ""} ${invalidValues.map((v) => `"${v}"`).join(", ")}.`,
+      fix: {
+        action: "retry_with_valid_values",
+        explanation: `Re-run with values from \`validValues\` for ${flag}, or drop the flag.`,
+        flag,
+        invalidValues,
+        validValues
+      }
+    };
+  }
+  return { message: first.path.length > 0 ? `${flag}: ${first.message}` : first.message };
+}
+var NUMERIC_FLAGS = [
+  ["--limit", "limit"],
+  ["--max-per-advertiser", "maxPerAdvertiser"],
+  ["--min-relevance", "minRelevance"]
+];
+function searchRejection(args, body) {
+  if (args.scope !== void 0 && !winnerSearchScopeSchema.safeParse(args.scope).success) {
+    return { message: `Unknown --scope "${args.scope}". Use one of: ${winnerSearchScopeSchema.options.join(", ")}.` };
+  }
+  if (args.sort !== void 0 && !winnersSortSchema.safeParse(args.sort).success) {
+    return { message: `Unknown --sort "${args.sort}". Use one of: ${winnersSortSchema.options.join(", ")}.` };
+  }
+  for (const [flag, key] of NUMERIC_FLAGS) {
+    const value = args[key];
+    if (value !== void 0 && value !== "" && Number.isNaN(Number(value))) {
+      return { message: `${flag} must be a number, got "${value}".` };
+    }
+  }
+  if (!("free_text_query" in body || "ref_ad_id" in body || "hard_filters" in body)) {
+    return { message: "Provide a query, --ref-ad-id, or a filter flag" };
+  }
+  return schemaRejection(body);
+}
+function writeSearchResult(data, opts) {
+  const rawResults = Array.isArray(data?.results) ? data.results : [];
+  const hints = searchHints(data ?? {});
+  const withHints = hints.length > 0 ? { hints } : {};
+  if (opts.output === "json") {
+    const results = adRows(rawResults, opts);
+    writeJson({
+      ok: true,
+      data: {
+        results,
+        scope: data?.scope ?? null,
+        following_count: data?.following_count ?? null,
+        pool_size: data?.pool_size ?? null,
+        match_confidence: data?.match_confidence ?? null,
+        below_floor_count: data?.below_floor_count ?? null,
+        country_coverage: data?.country_coverage ?? null
+      },
+      ...withHints
+    });
+    return;
+  }
+  writeOutput({ ok: true, data: rawResults, ...withHints }, opts.output, opts.fields, opts.full, winningAdNormalizer);
+}
+var SEARCH_TIMEOUT_MS = 12e4;
+var searchCommand = defineCommand({
+  meta: {
+    name: "search",
+    description: "Search winning reference ads, the company's followed brands first. Start here: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --exclude-advertiser adv_123 --output md. A set of references for N concepts in one call: add --diverse --limit N. The best proven ad in one container from any category: --format-pattern comparison_table (no query needed; add --sort longest_running to order by staying power). References for viewers who don't know the brand: --audience-temperature 0_cold --exclude-brand-reliant. What competitors kept after testing: --survived-test. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry."
+  },
+  args: {
+    query: { type: "positional", description: "Free-text search query", required: false },
+    scope: {
+      type: "string",
+      description: "followed-first (default) | followed | all. followed-first = the company's followed brands first, topped up from the whole library (the whole library when it follows nobody)",
+      required: false
+    },
+    "ref-ad-id": { type: "string", description: "Find ads similar to this ad id", required: false },
+    limit: {
+      type: "string",
+      description: "Max results 1-100 (default 10 \u2014 a shortlist)",
+      required: false,
+      default: "10"
+    },
+    "max-per-advertiser": {
+      type: "string",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "string", description: "Relevance floor 0-1", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a no-query browse: winner (default) | longest_running | newest. Ignored when a query is given",
+      required: false
+    },
+    platform: {
+      type: "string",
+      description: "Comma list of platforms (meta,linkedin,tiktok,google) \u2014 search one or several",
+      required: false
+    },
+    format: { type: "string", description: "Comma list of formats (video,static,carousel,text)", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list of winner categories (default: all)",
+      required: false
+    },
+    awareness: { type: "string", description: "Comma list of awareness stages", required: false },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold | 1_warm_engaged | 2_hot_visited | 3_customer (a cold brief takes 0_cold)",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads that only work if the viewer already knows the brand (ads not judged yet are kept). Use it when making ads for viewers who don't know the brand",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": { type: "string", description: "Restrict to these advertiser ids", required: false },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand",
+      required: false
+    },
+    "first-seen-after": { type: "string", description: "ISO date or datetime lower bound", required: false },
+    "first-seen-before": { type: "string", description: "ISO date or datetime upper bound", required: false },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of proven hook seeds (from `winning-ads hooks`) to narrow the search",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return Google search text, Shopping and app ads (default: designed pictures and videos only)",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "One varied set (different brands, containers, hooks): a reference per concept in one call",
+      required: false,
+      default: 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 DNA detail (angle, persona, hook, awareness, industry) + reach and media kind; mechanism, days_active, active, winner_category, audience_temperature, funnel_stage, advertiser_size and presumes_brand_knowledge are in the default output",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const searchArgs = {
+        query: args.query,
+        scope: args.scope,
+        refAdId: args["ref-ad-id"],
+        limit: args.limit,
+        maxPerAdvertiser: args["max-per-advertiser"],
+        minRelevance: args["min-relevance"],
+        sort: args.sort,
+        platform: args.platform,
+        format: args.format,
+        winnerCategory: args["winner-category"],
+        awareness: args.awareness,
+        audienceTemperature: args["audience-temperature"],
+        funnelStage: args["funnel-stage"],
+        advertiserSize: args["advertiser-size"],
+        excludeBrandReliant: args["exclude-brand-reliant"],
+        country: args.country,
+        language: args.language,
+        advertiserId: args["advertiser-id"],
+        excludeAdvertiser: args["exclude-advertiser"],
+        firstSeenAfter: args["first-seen-after"],
+        firstSeenBefore: args["first-seen-before"],
+        hookArchetype: args["hook-archetype"],
+        formatPattern: args["format-pattern"],
+        stage: args.stage,
+        survivedTest: args["survived-test"],
+        diverse: args.diverse
+      };
+      const fieldPlan = adFieldPlan(args.fields, args.full);
+      const body = designedByDefault(buildSearchBody(searchArgs), { allKinds: args["all-kinds"] });
+      const rejection = searchRejection(searchArgs, body);
+      if (rejection) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", ...rejection } });
+        process.exit(1);
+      }
+      const data = await apiPost("/api/ad-library/winners/search", body, {
+        timeoutMs: SEARCH_TIMEOUT_MS
+      });
+      writeSearchResult(data, { output: args.output || "json", ...fieldPlan });
+    } catch (err) {
+      reportSearchError(err);
+    }
+  }
+});
+
+export {
+  buildSearchBody,
+  designedByDefault,
+  searchHints,
+  unknownCountryFix,
+  searchErrorFix,
+  searchRejection,
+  searchCommand
+};
+//# sourceMappingURL=chunk-NQ47WGLK.js.map