@koda-sl/baker-cli 0.142.0 → 0.144.0

package/README.md

@@ -2132,7 +2132,11 @@ baker videos search "tutorial" --tags explainer,ugc --limit 5
 
 ### `baker videos get <id>`
 
-Get a single video by ID.
+Get a single video by ID. `--full` includes the auto-generated **transcript** (Baker transcribes every upload with speech-to-text), a `transcript_segment_count`, and the titled/timestamped **scene breakdown** — so you can read what a clip says and shows without watching it. Default JSON also returns the raw `transcript` + timed `transcriptSegments`; `--full` is what surfaces them in `--output md`/`files` too.
+
+```bash
+baker videos get j571abc123 --full --output md
+```
 
 ### `baker videos upload <file>`
 
@@ -2326,6 +2330,16 @@ Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winner
 baker winning-ads winners adv_123 --top 15 --output md
 ```
 
+### `baker winning-ads content <ad-id>`
+
+Read what's **inside** one ad → `GET /api/ad-library/ad-content`. `search`/`winners`/`feed` return a lean shortlist; this opens a single `ad_id` so you can understand a reference before reproducing it. For a **video** it returns the spoken `transcript`, the `on_screen_text` overlays, and the ad `copy` (`primary_text`/`headline`/`cta`); a **static** ad returns only the copy. Add `--full` for speech (voiceover style, speaker count, direct-address), pacing (scene count, shot length, key timeline moments), any recognised soundtrack, and each on-screen overlay's role + position (e.g. `GLOBAL PAYROLL @0.5s [hook, top]`) so you can place text faithfully. `--platform meta|linkedin` selects which platform the id is on (default `meta`).
+
+```bash
+baker winning-ads content adg_123                          # transcript + on-screen text + copy
+baker winning-ads content adg_123 --platform meta --full   # + speech, pacing, soundtrack
+baker winning-ads content adg_123 --full --output md
+```
+
 ### `baker winning-ads unfollow <advertiser>`
 
 Stop following a brand by advertiser id → `POST /api/ad-library/unfollow`. Returns `{ removed }`.

package/dist/cli.js

@@ -73,7 +73,7 @@ import {
 } from "./chunk-RK67WL4O.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand177, runMain } from "citty";
+import { defineCommand as defineCommand178, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand18 } from "citty";
@@ -145,6 +145,22 @@ function compactVideo(video) {
     status: String(video.status ?? "")
   };
 }
+function sceneLines(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((s) => {
+    const scene = asRecord(s);
+    const title = typeof scene.title === "string" ? scene.title : "";
+    if (!title) {
+      return [];
+    }
+    const start = round2(scene.startSecond);
+    const end = round2(scene.endSecond);
+    const range = start !== null && end !== null ? ` (${start}-${end}s)` : "";
+    return [`${title}${range}`];
+  });
+}
 function fullVideo(video) {
   const compact = compactVideo(video);
   return {
@@ -152,6 +168,12 @@ function fullVideo(video) {
     duration: video.duration ?? null,
     muxPlaybackId: String(video.muxPlaybackId ?? ""),
     source: String(video.source ?? ""),
+    // The spoken transcript + AI scene breakdown of the client's own clip — the
+    // "understand what's in this video" payload. Kept out of the compact/search
+    // projection (too large for a list) and surfaced here on --full.
+    transcript: video.transcript ?? null,
+    transcript_segment_count: Array.isArray(video.transcriptSegments) ? video.transcriptSegments.length : 0,
+    scenes: sceneLines(video.scenes),
     createdAt: video.createdAt ?? null
   };
 }
@@ -243,6 +265,76 @@ function winningAdNormalizer(record, full) {
   }
   return compactWinningAd(record);
 }
+function overlayLines(value, detailed = false) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((o) => {
+    const item = asRecord(o);
+    const text = typeof item.text === "string" ? item.text : "";
+    if (!text) {
+      return [];
+    }
+    const at = round2(item.appears_at_s);
+    let line = at !== null ? `${text} @${at}s` : text;
+    if (detailed) {
+      const tags = [item.role, item.position].filter((t) => typeof t === "string" && t.length > 0);
+      if (tags.length) {
+        line += ` [${tags.join(", ")}]`;
+      }
+    }
+    return [line];
+  });
+}
+function compactAdContent(record) {
+  return {
+    ad_id: record.ad_id ?? null,
+    advertiser: record.advertiser ?? null,
+    format: record.format ?? null,
+    media_kind: record.media_kind ?? null,
+    media_url: record.media_url ?? null,
+    summary: record.summary ?? null,
+    transcript: record.transcript ?? null,
+    on_screen_text: overlayLines(record.on_screen_text),
+    has_captions: typeof record.has_captions === "boolean" ? record.has_captions : null,
+    primary_text: record.primary_text ?? null,
+    headline: record.headline ?? null,
+    cta: record.cta ?? null
+  };
+}
+function fullAdContent(record) {
+  const speech = asRecord(record.speech);
+  const pacing = asRecord(record.pacing);
+  const music = asRecord(record.music);
+  return {
+    ...compactAdContent(record),
+    platform: record.platform ?? null,
+    // Re-derive with role/position tags — the lean compact version dropped them.
+    on_screen_text: overlayLines(record.on_screen_text, true),
+    winner_score: round2(record.winner_score),
+    winner_category: record.winner_category ?? null,
+    angle: record.angle ?? null,
+    hook_archetype: record.hook_archetype ?? null,
+    caption_style: record.caption_style ?? null,
+    has_speech: typeof record.has_speech === "boolean" ? record.has_speech : null,
+    speech_pct_of_runtime: round2(speech.speech_pct_of_runtime),
+    speaker_count: speech.speaker_count ?? null,
+    voiceover_vs_sync: speech.voiceover_vs_sync ?? null,
+    is_direct_address: typeof speech.is_direct_address === "boolean" ? speech.is_direct_address : null,
+    speech_emotion_dominant: speech.speech_emotion_dominant ?? null,
+    scene_count: pacing.scene_count ?? null,
+    avg_shot_length_s: round2(pacing.avg_shot_length_s),
+    pacing_shape: pacing.pacing_shape ?? null,
+    hook_ends_at_s: round2(pacing.hook_ends_at_s),
+    cta_first_shown_at_s: round2(pacing.cta_first_shown_at_s),
+    product_first_appears_at_s: round2(pacing.product_first_appears_at_s),
+    music_track_title: music.track_title ?? null,
+    music_track_artist: music.track_artist ?? null
+  };
+}
+function adContentNormalizer(record, full) {
+  return full ? fullAdContent(record) : compactAdContent(record);
+}
 function applyFieldMask(data, fields) {
   const result = {};
   for (const field of fields) {
@@ -1135,6 +1227,65 @@ var seedCatalogResponseSchema = z2.object({
   segment: seedCatalogSegmentSchema.nullable(),
   patterns: z2.array(patternSeedSchema)
 });
+var adContentRequestSchema = z2.object({
+  ad_id: z2.string().min(1),
+  platform: adLibraryPlatformSchema.optional()
+});
+var adContentOverlaySchema = z2.object({
+  text: z2.string(),
+  appears_at_s: z2.number().nullable(),
+  position: z2.string().nullable(),
+  role: z2.string().nullable()
+});
+var adContentSpeechSchema = z2.object({
+  speech_pct_of_runtime: z2.number().nullable(),
+  speaker_count: z2.number().nullable(),
+  voiceover_vs_sync: z2.string().nullable(),
+  is_direct_address: z2.boolean().nullable(),
+  speech_emotion_dominant: z2.string().nullable()
+});
+var adContentPacingSchema = z2.object({
+  scene_count: z2.number().nullable(),
+  avg_shot_length_s: z2.number().nullable(),
+  pacing_shape: z2.string().nullable(),
+  hook_ends_at_s: z2.number().nullable(),
+  cta_first_shown_at_s: z2.number().nullable(),
+  product_first_appears_at_s: z2.number().nullable()
+});
+var adContentMusicSchema = z2.object({
+  track_title: z2.string().nullable(),
+  track_artist: z2.string().nullable()
+});
+var adContentSchema = z2.object({
+  ad_id: z2.string().nullable(),
+  advertiser: z2.string().nullable(),
+  advertiser_id: z2.string().nullable(),
+  platform: z2.string().nullable(),
+  format: z2.string().nullable(),
+  media_kind: z2.string().nullable(),
+  media_url: z2.string().nullable(),
+  winner_score: z2.number().nullable(),
+  winner_category: z2.string().nullable(),
+  summary: z2.string().nullable(),
+  angle: z2.string().nullable(),
+  hook_archetype: z2.string().nullable(),
+  // Spoken words (video only; null when the ad has no speech track).
+  transcript: z2.string().nullable(),
+  has_speech: z2.boolean().nullable(),
+  speech: adContentSpeechSchema,
+  // On-screen text / captions.
+  has_captions: z2.boolean().nullable(),
+  caption_style: z2.string().nullable(),
+  on_screen_text: z2.array(adContentOverlaySchema),
+  // Copy the viewer reads outside the media.
+  primary_text: z2.string().nullable(),
+  headline: z2.string().nullable(),
+  cta: z2.string().nullable(),
+  // Structure + soundtrack.
+  pacing: adContentPacingSchema,
+  music: adContentMusicSchema
+});
+var adContentResponseSchema = z2.object({ ad: adContentSchema });
 
 // ../api/src/ads-linkedin/limits.ts
 var LINKEDIN_LIMITS = {
@@ -4923,7 +5074,7 @@ var demandGenAdSchema = z12.object({
   squareImageAssets: z12.array(refSchema).optional(),
   logoImageAssets: z12.array(refSchema).optional()
 });
-var adContentSchema = z12.discriminatedUnion("format", [
+var adContentSchema2 = z12.discriminatedUnion("format", [
   responsiveSearchAdSchema,
   responsiveDisplayAdSchema,
   callAdSchema,
@@ -4934,7 +5085,7 @@ var adContentSchema = z12.discriminatedUnion("format", [
 var adCreateSchema = z12.object({
   adGroup: refSchema,
   status: stageableStatusSchema2.default("PAUSED"),
-  content: adContentSchema
+  content: adContentSchema2
 });
 var adUpdateSchema = z12.object({
   status: z12.enum(["ENABLED", "PAUSED", "REMOVED"]).optional(),
@@ -29434,7 +29585,7 @@ Full guide: __tooling__/docs/tools/baker/videos.md`
 });
 
 // src/commands/winning-ads/index.ts
-import { defineCommand as defineCommand176 } from "citty";
+import { defineCommand as defineCommand177 } from "citty";
 
 // src/commands/winning-ads/advertisers.ts
 import { defineCommand as defineCommand165 } from "citty";
@@ -29629,8 +29780,70 @@ var briefCommand = defineCommand166({
   }
 });
 
-// src/commands/winning-ads/feed.ts
+// src/commands/winning-ads/content.ts
 import { defineCommand as defineCommand167 } from "citty";
+registerSchema({
+  command: "winning-ads.content",
+  description: "Read what's INSIDE one winning ad: the spoken transcript, the on-screen text, and the ad copy. Use this after `search`/`winners`/`feed` return a shortlist \u2014 pass an ad_id to understand a reference before reproducing it. Add --full for speech, pacing, and soundtrack detail. Video ads carry the transcript/on-screen text; static ads carry only the copy.",
+  args: {
+    "ad-id": { type: "string", description: "The ad id to open (from search/winners/feed results)", required: true },
+    platform: {
+      type: "string",
+      description: "Which platform the ad id is on: meta|linkedin (default meta)",
+      required: false
+    }
+  }
+});
+var contentCommand = defineCommand167({
+  meta: {
+    name: "content",
+    description: "Read the transcript + on-screen text + copy of one winning ad. Example: baker winning-ads content adg_123 --platform meta --full --output md"
+  },
+  args: {
+    "ad-id": { type: "positional", description: "Ad id (from search/winners/feed)", required: true },
+    platform: {
+      type: "string",
+      description: "Platform the ad id is on: meta|linkedin (default meta)",
+      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 speech, pacing, and soundtrack detail",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = { id: String(args["ad-id"]) };
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const data = await apiGet("/api/ad-library/ad-content", params);
+      const output = args.output || "json";
+      const full = args.full;
+      const ad = data?.ad ?? {};
+      if (output === "json") {
+        writeJson({ ok: true, data: { ad: adContentNormalizer(ad, full) } });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: ad },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        adContentNormalizer
+      );
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+
+// src/commands/winning-ads/feed.ts
+import { defineCommand as defineCommand168 } from "citty";
 function buildFeedParams(input) {
   const params = {};
   const advertiser = splitList(input.advertiser);
@@ -29682,7 +29895,7 @@ registerSchema({
     format: { type: "string", description: "Comma-separated formats to include (e.g. static,video)", required: false }
   }
 });
-var feedCommand = defineCommand167({
+var feedCommand = defineCommand168({
   meta: {
     name: "feed",
     description: "Winners across every brand you follow (browse, then trim per advertiser). Example: baker winning-ads feed --per-advertiser 5 --output md"
@@ -29767,7 +29980,7 @@ var feedCommand = defineCommand167({
 });
 
 // src/commands/winning-ads/follow.ts
-import { defineCommand as defineCommand168 } from "citty";
+import { defineCommand as defineCommand169 } from "citty";
 var PLATFORMS = ["meta", "linkedin"];
 registerSchema({
   command: "winning-ads.follow",
@@ -29782,7 +29995,7 @@ registerSchema({
     label: { type: "string", description: "Optional display label (defaults to the resolved name)", required: false }
   }
 });
-var followCommand = defineCommand168({
+var followCommand = defineCommand169({
   meta: {
     name: "follow",
     description: 'Follow a brand to track ALL its ads \u2014 every platform and country. --platform is how we read your input, not a limit. A domain tracks both Meta + LinkedIn. Example: baker winning-ads follow "deel.com" --platform meta'
@@ -29829,7 +30042,7 @@ var followCommand = defineCommand168({
 });
 
 // src/commands/winning-ads/follow-competitors.ts
-import { defineCommand as defineCommand169 } from "citty";
+import { defineCommand as defineCommand170 } from "citty";
 var PLATFORMS2 = ["meta", "linkedin"];
 var BATCH_TIMEOUT_MS = 3e5;
 function buildFollowBatchBody(input) {
@@ -29862,7 +30075,7 @@ registerSchema({
     }
   }
 });
-var followCompetitorsCommand = defineCommand169({
+var followCompetitorsCommand = defineCommand170({
   meta: {
     name: "follow-competitors",
     description: 'Follow many brands at once by domain \u2014 add every competitor in one call. Example: baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"'
@@ -29937,7 +30150,7 @@ var followCompetitorsCommand = defineCommand169({
 });
 
 // src/commands/winning-ads/following.ts
-import { defineCommand as defineCommand170 } from "citty";
+import { defineCommand as defineCommand171 } from "citty";
 registerSchema({
   command: "winning-ads.following",
   description: "List the brands you follow in your ad-dna library, with each one's status (ready vs still adding) and cached ad counts.",
@@ -29970,7 +30183,7 @@ function followingNormalizer(record, full) {
     platforms: Array.isArray(record.platforms) ? record.platforms : []
   };
 }
-var followingCommand = defineCommand170({
+var followingCommand = defineCommand171({
   meta: {
     name: "following",
     description: "List brands you follow, with status (ready / adding\u2026) and cached counts. Example: baker winning-ads following --output md"
@@ -30005,7 +30218,7 @@ var followingCommand = defineCommand170({
 });
 
 // src/commands/winning-ads/patterns.ts
-import { defineCommand as defineCommand171 } from "citty";
+import { defineCommand as defineCommand172 } from "citty";
 registerSchema({
   command: "winning-ads.patterns",
   description: "Mine what separates two cohorts of ads: pass a comma-list of winning ad ids (--winners) and a comma-list of weaker ad ids (--duds). Returns the discriminating DNA fields.",
@@ -30044,7 +30257,7 @@ function discriminatorRow(record) {
     top_values_duds: Array.isArray(record.top_values_b) ? record.top_values_b.join(", ") : ""
   };
 }
-var patternsCommand = defineCommand171({
+var patternsCommand = defineCommand172({
   meta: {
     name: "patterns",
     description: "Discover what separates winning ads from weak ones. Example: baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --output md"
@@ -30100,7 +30313,7 @@ var patternsCommand = defineCommand171({
 });
 
 // src/commands/winning-ads/search.ts
-import { defineCommand as defineCommand172 } from "citty";
+import { defineCommand as defineCommand173 } 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.",
@@ -30208,7 +30421,7 @@ function buildSearchBody(args) {
   }
   return body;
 }
-var searchCommand4 = defineCommand172({
+var searchCommand4 = defineCommand173({
   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"
@@ -30323,7 +30536,7 @@ var searchCommand4 = defineCommand172({
 });
 
 // src/commands/winning-ads/seeds.ts
-import { defineCommand as defineCommand173 } from "citty";
+import { defineCommand as defineCommand174 } from "citty";
 function leanRow(r) {
   return {
     key: r.key,
@@ -30351,7 +30564,7 @@ function makeSeedCommand(opts) {
       limit: { type: "number", description: "Max keys 1-100 (default 20)", required: false, default: 20 }
     }
   });
-  return defineCommand173({
+  return defineCommand174({
     meta: { name: opts.name, description: opts.description },
     args: {
       platform: { type: "string", description: "Single platform to segment on", required: false },
@@ -30400,7 +30613,7 @@ var formatsCommand = makeSeedCommand({
 });
 
 // src/commands/winning-ads/unfollow.ts
-import { defineCommand as defineCommand174 } from "citty";
+import { defineCommand as defineCommand175 } from "citty";
 registerSchema({
   command: "winning-ads.unfollow",
   description: "Stop following a brand \u2014 removes it from your ad-dna library by advertiser id.",
@@ -30408,7 +30621,7 @@ registerSchema({
     advertiser: { type: "string", description: "Advertiser id to unfollow", required: true }
   }
 });
-var unfollowCommand = defineCommand174({
+var unfollowCommand = defineCommand175({
   meta: {
     name: "unfollow",
     description: "Stop following a brand by advertiser id. Example: baker winning-ads unfollow adv_123"
@@ -30429,7 +30642,7 @@ var unfollowCommand = defineCommand174({
 });
 
 // src/commands/winning-ads/winners.ts
-import { defineCommand as defineCommand175 } from "citty";
+import { defineCommand as defineCommand176 } from "citty";
 registerSchema({
   command: "winning-ads.winners",
   description: "Top winning ads for one advertiser id (from `advertisers` or `following`). Returns lean winner cards; add --full for DNA + longevity.",
@@ -30439,7 +30652,7 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin", required: false }
   }
 });
-var winnersCommand = defineCommand175({
+var winnersCommand = defineCommand176({
   meta: {
     name: "winners",
     description: "Top winning ads for a specific advertiser id. Example: baker winning-ads winners adv_123 --top 15 --output md"
@@ -30489,7 +30702,7 @@ var winnersCommand = defineCommand175({
 });
 
 // src/commands/winning-ads/index.ts
-var winningAdsCommand = defineCommand176({
+var winningAdsCommand = defineCommand177({
   meta: {
     name: "winning-ads",
     description: `Search the ad-dna corpus of scored "winning" ads for reference creatives to reproduce, and manage the brands your library tracks. Proxied through the Baker backend (BAKER_API_KEY) \u2014 no separate token needed.
@@ -30504,6 +30717,7 @@ Subcommands:
   baker winning-ads following                 \u2014 list brands you follow (status + counts)
   baker winning-ads feed                      \u2014 winners across EVERY brand you follow; trim with --advertiser
   baker winning-ads winners <advertiser>      \u2014 top winners for one advertiser id
+  baker winning-ads content <ad-id>           \u2014 read ONE ad's transcript + on-screen text + copy (understand a reference before reproducing it)
   baker winning-ads unfollow <advertiser>     \u2014 stop following a brand
   baker winning-ads brief                     \u2014 creative brief grounded in similar winners
   baker winning-ads patterns --winners \u2026 --duds \u2026   \u2014 what separates a winning cohort from a weak one
@@ -30519,6 +30733,7 @@ Examples:
   baker winning-ads feed --per-advertiser 5 --output md
   baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
   baker winning-ads winners adv_123 --top 15 --output md
+  baker winning-ads content adg_123 --full --output md
   baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
   baker winning-ads search "fintech onboarding" --hook-archetype callout --winner-category winner --output md
   baker winning-ads patterns --winners a_1,a_2 --duds a_9,a_8 --output md
@@ -30532,6 +30747,7 @@ Full guide: __tooling__/docs/tools/baker/winning-ads.md`
     following: followingCommand,
     feed: feedCommand,
     winners: winnersCommand,
+    content: contentCommand,
     unfollow: unfollowCommand,
     brief: briefCommand,
     patterns: patternsCommand,
@@ -30558,7 +30774,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand177({
+var main = defineCommand178({
   meta: {
     name: "baker",
     version: getCliVersion(),