@koda-sl/baker-cli 0.468.0 → 0.469.0-dev.42f26270e

package/dist/chunk-HKSLIV4T.js

@@ -1,533 +0,0 @@
-import {
-  adFieldPlan,
-  adRows
-} from "./chunk-57XJ7QF7.js";
-import {
-  reportError,
-  splitList
-} from "./chunk-ICJFL7DU.js";
-import {
-  ApiError,
-  apiPost
-} from "./chunk-MMOTJIV6.js";
-import {
-  registerSchema,
-  scopedWinnersSearchRequestSchema,
-  staticFormatPatternSchema,
-  winnerSearchScopeSchema,
-  winnersSortSchema,
-  winningAdNormalizer,
-  writeJson,
-  writeOutput
-} from "./chunk-D3RTGIT4.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-HKSLIV4T.js.map