@koda-sl/baker-cli 0.452.0 → 0.453.0-dev.914a088e4

package/dist/chunk-XNLCAM4S.js

@@ -0,0 +1,534 @@
+import {
+  reportError,
+  splitList
+} from "./chunk-5EEWYHOR.js";
+import {
+  scopedWinnersSearchRequestSchema,
+  staticFormatPatternSchema,
+  winnerSearchScopeSchema,
+  winnersSortSchema
+} from "./chunk-TEINLN64.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-PCKVSSVT.js";
+import {
+  applyFieldMask,
+  compactWinningAd,
+  fullWinningAd,
+  registerSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-NU7JSWVA.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 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. A value outside a closed list (--platform, --format, --winner-category, --awareness, --audience-temperature, --funnel-stage, --advertiser-size, --format-pattern, --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",
+      required: false
+    },
+    format: { type: "string", description: "Comma list: video,static,carousel", 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
+    },
+    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);
+  if (Object.keys(hardFilters).length) {
+    body.hard_filters = hardFilters;
+  }
+  return body;
+}
+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 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 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"
+};
+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);
+}
+var EVERY_SIGNAL = {
+  dna: {
+    visual: "-",
+    container: "-",
+    mechanism: "-",
+    audience_temperature: "-",
+    funnel_stage: "-",
+    advertiser_size: "-",
+    presumes_brand_knowledge: true,
+    brand_knowledge_reason: "-"
+  },
+  baker_uses: { companies: 1, ours: true, approved: 1, rejected: 1 },
+  source: "followed"
+};
+var COMPACT_FIELDS = new Set(Object.keys(compactWinningAd(EVERY_SIGNAL)));
+var ALL_FIELDS = Object.keys(fullWinningAd(EVERY_SIGNAL));
+function searchFields(requested, full) {
+  if (!requested) return { fields: void 0, full };
+  const fields = requested.map((f) => f.trim()).filter(Boolean);
+  const invalid = fields.filter((f) => !ALL_FIELDS.includes(f));
+  if (invalid.length > 0) return { invalid, valid: ALL_FIELDS };
+  return { fields, full: full || fields.some((f) => !COMPACT_FIELDS.has(f)) };
+}
+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 = rawResults.map((r) => {
+      const row = winningAdNormalizer(r, opts.full);
+      return opts.fields ? applyFieldMask(row, opts.fields) : row;
+    });
+    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. 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) \u2014 search one or several",
+      required: false
+    },
+    format: { type: "string", description: "Comma list of formats (video,static,carousel)", 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
+    },
+    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"],
+        diverse: args.diverse
+      };
+      const fieldPlan = searchFields(
+        args.fields ? args.fields.split(",") : void 0,
+        args.full
+      );
+      if ("invalid" in fieldPlan) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `Unknown --fields: ${fieldPlan.invalid.join(", ")}`,
+            fix: {
+              action: "retry_with_valid_values",
+              explanation: "Pass only fields a search row carries.",
+              flag: "--fields",
+              invalidValues: fieldPlan.invalid,
+              validValues: fieldPlan.valid
+            }
+          }
+        });
+        process.exit(1);
+      }
+      const body = buildSearchBody(searchArgs);
+      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,
+  searchHints,
+  unknownCountryFix,
+  searchErrorFix,
+  searchRejection,
+  searchFields,
+  searchCommand
+};
+//# sourceMappingURL=chunk-XNLCAM4S.js.map