@koda-sl/baker-cli 0.71.2 → 0.74.0

package/README.md

@@ -2219,6 +2219,60 @@ baker testimonials list --source google --sentiment positive --limit 20
 
 ---
 
+### Winning Ads (`baker winning-ads`)
+
+Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
+
+> Backend env: the Convex deployment must have `AD_DNA_API_TOKEN` set (`npx convex env set AD_DNA_API_TOKEN …`). `AD_DNA_API_URL` is optional and defaults to `https://ads.withbaker.com`.
+
+### `baker winning-ads search <query>`
+
+Semantic search (dense recall + BM25 + rerank). The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size` and `match_confidence`. `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+
+> `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
+
+> Results are already de-junked and winner-first: the corpus auto-drops measured failures (duds, thrash) and ranks `final = relevance^0.25 × winner_score^0.75`. So `--winner-category winner` is usually unnecessary — it's a stricter filter that also removes `untested` (unproven-but-maybe-fresh) ads. Rely on the default + `--min-relevance`; only add `--winner-category` to force-exclude unproven creatives. (Restricting to a single `--advertiser-id` turns the failure-exclusion off — you then see that brand's duds too.)
+
+```bash
+# Only LinkedIn video ads:
+baker winning-ads search "B2B lead gen demo" --platform linkedin --format video --output md
+# Cross-platform, exclude our own brand + an advertiser we already mined:
+baker winning-ads search "fintech onboarding" --exclude-advertiser adv_ourbrand,adv_usedbefore --output md
+# Similar-to a reference ad, recent only:
+baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00:00Z --limit 5 --output md
+```
+
+| Flag | Purpose |
+|---|---|
+| `query` (positional) | Free-text natural-language query |
+| `--ref-ad-id <id>` | Find ads similar to this ad (instead of free text) |
+| `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
+| `--max-per-advertiser <n>` | Cap results per advertiser 1–50 (default 3) |
+| `--min-relevance <0-1>` | Relevance floor; trims weak matches |
+| `--platform <list>` | One or many of `meta,tiktok,linkedin,google_search,google_display,youtube,reddit,x,pinterest,snapchat` — pass a single value to search **only** that platform |
+| `--format <list>` | `video,static,carousel` |
+| `--winner-category <list>` | `winner,scaled_winner,evergreen,rising,untested,dud,…` (default: all) |
+| `--awareness <list>` | `unaware,problem_aware,solution_aware,product_aware,most_aware` |
+| `--advertiser-id <list>` | **Restrict to** these advertiser ids (browse one brand's winners) |
+| `--exclude-advertiser <list>` | **Drop** these advertiser ids — your own brand + already-used references |
+| `--country <list>` / `--language <list>` | Filter by country / language codes |
+| `--first-seen-after` / `--first-seen-before` | ISO datetime bounds (recency) |
+| `--output json\|md\|files` | Output format (default json) |
+| `--full` | Include DNA detail + longevity |
+
+Reading the scores: **`relevance`** (0–1) = match of the creative to your query; **`winner_score`** = how proven the ad is in-market. Pick references that are both relevant *and* proven.
+
+### `baker winning-ads advertisers <brand>`
+
+Resolve a brand name → `advertiser_id`(s) in the corpus. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id`). Returns `advertiser_id`, `label`, `active_ads`, `total_ads`.
+
+```bash
+baker winning-ads advertisers "Acme" --output md          # find our own advertiser id
+baker winning-ads advertisers "Deel" --platform meta --output md
+```
+
+---
+
 ### Scheduled Actions (`baker scheduled-actions`)
 
 Manage company-scoped scheduled recipes that spawn Work Actions later or on a cadence. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `trigger` runs immediately on a published scheduled action and does not require a chat id. Use a regular Work Action instead when there is no date or cadence.

package/dist/cli.js

@@ -12,7 +12,7 @@ import {
 } from "./chunk-JIDZ37KG.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand138, runMain } from "citty";
+import { defineCommand as defineCommand141, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand12 } from "citty";
@@ -314,6 +314,52 @@ function testimonialNormalizer(record, full) {
   }
   return compactTestimonial(record);
 }
+function round2(value) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    return null;
+  }
+  return Math.round(value * 100) / 100;
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function compactWinningAd(record) {
+  const dna = asRecord(record.dna);
+  return {
+    advertiser: String(record.advertiser ?? ""),
+    platform: String(record.platform ?? ""),
+    format: String(record.format ?? ""),
+    relevance: round2(record.relevance),
+    winner_score: round2(record.winner_score),
+    summary: String(dna.creative_concept ?? ""),
+    advertiser_id: String(record.advertiser_id ?? ""),
+    ad_id: String(record.ad_id ?? ""),
+    media_url: String(record.media_url ?? "")
+  };
+}
+function fullWinningAd(record) {
+  const compact = compactWinningAd(record);
+  const dna = asRecord(record.dna);
+  return {
+    ...compact,
+    winner_category: String(record.winner_category ?? ""),
+    media_kind: record.media_kind ?? null,
+    days_active: record.days_active ?? null,
+    reach: record.reach ?? null,
+    active: typeof record.active === "boolean" ? record.active : null,
+    angle: dna.angle ?? null,
+    awareness_stage: dna.awareness_stage ?? null,
+    target_persona: dna.target_persona ?? null,
+    hook_archetype: dna.hook_archetype ?? null,
+    industry: dna.industry ?? null
+  };
+}
+function winningAdNormalizer(record, full) {
+  if (full) {
+    return fullWinningAd(record);
+  }
+  return compactWinningAd(record);
+}
 function applyFieldMask(data, fields) {
   const result = {};
   for (const field of fields) {
@@ -5633,10 +5679,10 @@ var IDENTITY_FIELDS_BY_LEVEL = {
 };
 function composeFields2(intent, level) {
   const intentFields = INSIGHTS_INTENTS[intent].fields;
-  const identity = IDENTITY_FIELDS_BY_LEVEL[level];
+  const identity2 = IDENTITY_FIELDS_BY_LEVEL[level];
   const seen = /* @__PURE__ */ new Set();
   const out = [];
-  for (const f of [...identity, ...intentFields]) {
+  for (const f of [...identity2, ...intentFields]) {
     if (!seen.has(f)) {
       seen.add(f);
       out.push(f);
@@ -14600,6 +14646,317 @@ Examples:
   }
 });
 
+// src/commands/winning-ads/index.ts
+import { defineCommand as defineCommand140 } from "citty";
+
+// src/commands/winning-ads/advertisers.ts
+import { defineCommand as defineCommand138 } from "citty";
+registerSchema({
+  command: "winning-ads.advertisers",
+  description: "Resolve a brand name to advertiser_id(s) in the ad-dna corpus \u2014 to find your OWN advertiser (to --exclude-advertiser) or a competitor (to --advertiser-id).",
+  args: {
+    query: { type: "string", description: "Brand / advertiser name to match (case-insensitive)", required: false },
+    limit: { type: "number", description: "Max results (default 20)", required: false, default: 20 },
+    platform: { type: "string", description: "Filter to a single platform", required: false }
+  }
+});
+function identity(record) {
+  return record;
+}
+var advertisersCommand2 = defineCommand138({
+  meta: {
+    name: "advertisers",
+    description: 'Resolve a brand name to advertiser_id(s). Use it to find your own advertiser for --exclude-advertiser, or a competitor for --advertiser-id. Example: baker winning-ads advertisers "Deel" --output md'
+  },
+  args: {
+    query: { type: "positional", description: "Brand / advertiser name", required: false },
+    limit: { type: "string", description: "Max results (default 20)", required: false },
+    platform: { type: "string", description: "Filter to a single platform", 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 }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = {};
+      const query = args.query;
+      if (query) {
+        params.q = query;
+      }
+      if (args.limit) {
+        params.limit = String(args.limit);
+      }
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const data = await apiGet("/api/winning-ads/advertisers", params);
+      const output = args.output || "json";
+      if (output === "json") {
+        writeJson({ ok: true, data });
+        return;
+      }
+      const list = Array.isArray(data?.advertisers) ? data.advertisers : [];
+      writeOutput(
+        { ok: true, data: list },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        false,
+        identity
+      );
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/winning-ads/search.ts
+import { defineCommand as defineCommand139 } from "citty";
+registerSchema({
+  command: "winning-ads.search",
+  description: "Search the ad-dna corpus of scored winning ads. Returns a lean shortlist (advertiser, summary, scores, media_url) to pick a reference to reproduce.",
+  args: {
+    query: { type: "string", description: "Free-text natural-language query", required: false },
+    "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: "Cap results per advertiser 1-50 (default 3)",
+      required: false,
+      default: 3
+    },
+    "min-relevance": { type: "number", description: "Relevance floor 0-1; trims weak matches", required: false },
+    platform: {
+      type: "string",
+      description: "Comma list: meta,tiktok,linkedin,google_search,google_display,youtube,reddit,x,pinterest,snapchat",
+      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
+    },
+    country: { type: "string", description: "Comma list of country codes", required: false },
+    language: { type: "string", description: "Comma list of language codes", 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 \u2014 your own brand + already-used references",
+      required: false
+    },
+    "first-seen-after": {
+      type: "string",
+      description: "ISO datetime; only ads first seen after this",
+      required: false
+    },
+    "first-seen-before": {
+      type: "string",
+      description: "ISO datetime; only ads first seen before this",
+      required: false
+    }
+  }
+});
+function splitList(value) {
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((v) => v.trim()).filter(Boolean);
+}
+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;
+  }
+  setNumber(body, "limit", args.limit);
+  setNumber(body, "max_per_advertiser", args.maxPerAdvertiser);
+  setNumber(body, "min_relevance", args.minRelevance);
+  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, "country", args.country);
+  setList(hardFilters, "language", args.language);
+  setList(hardFilters, "advertiser_ids", args.advertiserId);
+  setList(hardFilters, "exclude_advertiser_ids", args.excludeAdvertiser);
+  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;
+}
+var searchCommand4 = defineCommand139({
+  meta: {
+    name: "search",
+    description: "Search winning reference ads. Example: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --winner-category winner --exclude-advertiser adv_123 --output md"
+  },
+  args: {
+    query: { type: "positional", description: "Free-text search query", 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: "Cap results per advertiser 1-50 (default 3)",
+      required: false
+    },
+    "min-relevance": { type: "string", description: "Relevance floor 0-1", required: false },
+    platform: {
+      type: "string",
+      description: "Comma list of platforms (meta,linkedin,tiktok,\u2026) \u2014 search one or many",
+      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 },
+    country: { type: "string", description: "Comma list of country codes", required: false },
+    language: { type: "string", description: "Comma list of language codes", required: false },
+    "advertiser-id": { type: "string", description: "Restrict to these advertiser ids", required: false },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids (your own + already-used)",
+      required: false
+    },
+    "first-seen-after": { type: "string", description: "ISO datetime lower bound", required: false },
+    "first-seen-before": { type: "string", description: "ISO datetime upper bound", 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 DNA detail (angle, persona, hook) + longevity",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const searchArgs = {
+        query: args.query,
+        refAdId: args["ref-ad-id"],
+        limit: args.limit,
+        maxPerAdvertiser: args["max-per-advertiser"],
+        minRelevance: args["min-relevance"],
+        platform: args.platform,
+        format: args.format,
+        winnerCategory: args["winner-category"],
+        awareness: args.awareness,
+        country: args.country,
+        language: args.language,
+        advertiserId: args["advertiser-id"],
+        excludeAdvertiser: args["exclude-advertiser"],
+        firstSeenAfter: args["first-seen-after"],
+        firstSeenBefore: args["first-seen-before"]
+      };
+      const body = buildSearchBody(searchArgs);
+      if (!("free_text_query" in body) && !("ref_ad_id" in body) && !("hard_filters" in body)) {
+        writeJson({
+          ok: false,
+          error: { code: "VALIDATION_ERROR", message: "Provide a query, --ref-ad-id, or a filter flag" }
+        });
+        process.exit(1);
+      }
+      const data = await apiPost(
+        "/api/winning-ads/search",
+        body
+      );
+      const output = args.output || "json";
+      const full = args.full;
+      const rawResults = Array.isArray(data?.results) ? data.results : [];
+      if (output === "json") {
+        const results = rawResults.map((r) => winningAdNormalizer(r, full));
+        writeJson({
+          ok: true,
+          data: { results, pool_size: data?.pool_size ?? null, match_confidence: data?.match_confidence ?? null }
+        });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: rawResults },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        winningAdNormalizer
+      );
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/winning-ads/index.ts
+var winningAdsCommand = defineCommand140({
+  meta: {
+    name: "winning-ads",
+    description: `Search the ad-dna corpus of scored "winning" ads for reference creatives to reproduce. Proxied through the Baker backend (BAKER_API_KEY) \u2014 no separate token needed.
+
+Auth: BAKER_API_KEY (must start with bk_) + BAKER_API_URL (your Convex .convex.site URL).
+
+Subcommands:
+  baker winning-ads search "<free text>"   \u2014 semantic search; returns a lean shortlist (advertiser, summary, scores, media_url)
+  baker winning-ads advertisers "<brand>"  \u2014 resolve a brand \u2192 advertiser_id(s), to --exclude-advertiser (your own) or --advertiser-id (a competitor)
+
+Examples:
+  baker winning-ads search "B2B SaaS ad: before/after of an overworked team replaced by AI automation" --platform meta --format static
+  baker winning-ads search "skincare UGC testimonial" --platform tiktok --format video --output md
+  baker winning-ads search "fintech onboarding" --winner-category winner --exclude-advertiser adv_ourbrand,adv_usedbefore --output md
+  baker winning-ads advertisers "Acme" --output md   # find our own advertiser id to exclude`
+  },
+  subCommands: {
+    search: searchCommand4,
+    advertisers: advertisersCommand2
+  }
+});
+
 // src/version.ts
 import { readFileSync as readFileSync8 } from "fs";
 function packageJsonUrl() {
@@ -14617,7 +14974,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand138({
+var main = defineCommand141({
   meta: {
     name: "baker",
     version: getCliVersion(),
@@ -14640,6 +14997,7 @@ Introspection: Run 'baker schema <command>' to inspect argument schemas.`
     videos: videosCommand,
     testimonials: testimonialsCommand,
     canvas: canvasCommand,
+    "winning-ads": winningAdsCommand,
     schema: schemaCommand
   }
 });