@koda-sl/baker-cli 0.447.0 → 0.448.0-dev.ccc3c9a37

package/dist/keyword-gap-CUOGKUMM.js

@@ -0,0 +1,130 @@
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-JZP5IODJ.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-SQ7DRYCC.js";
+import "./chunk-SEPPFM5S.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiPost
+} from "./chunk-MMOTJIV6.js";
+import "./chunk-2ZZR2SOF.js";
+import "./chunk-YPCVPDU7.js";
+import {
+  registerSchema
+} from "./chunk-D3RTGIT4.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/keyword-gap.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.keyword-gap",
+  description: "Find keywords a competitor ranks for (organic or paid) that you don't. Discovers expansion opportunities. If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
+  args: {
+    competitor: { type: "string", description: "Competitor domain (positional 1)", required: true },
+    ours: { type: "string", description: "Your domain (positional 2)", required: true },
+    location: {
+      type: "string",
+      description: "Country code (us, uk, es, de...) or DataForSEO location code. Defaults to us (United States); set it for any non-US market.",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name. Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
+    limit: { type: "string", description: "Max results per page (default: 50, max: 1000)", required: false },
+    offset: { type: "string", description: "Pagination offset (default: 0)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  keyword: "Keyword in the gap (they rank, you don't)",
+  search_volume: "Monthly search volume",
+  cpc: "Cost per click USD",
+  their_position: "Competitor's ranking position"
+};
+var keywordGapCommand = defineCommand({
+  meta: {
+    name: "keyword-gap",
+    description: `Find keywords a competitor has that you don't. Supports pagination via --offset.
+
+Examples:
+  baker research keyword-gap "competitor.com" "mysite.com"
+  baker research keyword-gap "competitor.com" "mysite.com" --type paid --limit 100
+  baker research keyword-gap "competitor.com" "mysite.com" --offset 50 --limit 50`
+  },
+  args: {
+    competitor: { type: "positional", description: "Competitor domain", required: true },
+    ours: { type: "positional", description: "Your domain", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
+    limit: { type: "string", description: "Max results per page (default: 50, max: 1000)", required: false },
+    offset: { type: "string", description: "Pagination offset (default: 0)", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const competitor = args.competitor;
+    const ours = args.ours;
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const type = args.type || void 0;
+    const limit = args.limit ? Number(args.limit) : void 0;
+    const offset = args.offset ? Number(args.offset) : void 0;
+    const skipCache = args["no-cache"] ? true : void 0;
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const result = await apiPost("/api/research/keyword-gap", {
+        competitor,
+        ours,
+        location,
+        language,
+        type,
+        limit,
+        offset,
+        skipCache
+      });
+      const currentOffset = offset ?? 0;
+      const currentLimit = limit ?? 50;
+      const hasMore = currentOffset + result.data.length < result.total_count;
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeResearchOutput(result.data, format);
+        writeResearchHints([RESEARCH_DATA_NOTE], format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        your_domain: ours,
+        competitor_domain: competitor,
+        data: result.data,
+        fields: FIELDS,
+        note: RESEARCH_DATA_NOTE,
+        total_count: result.total_count,
+        query_context: queryContext,
+        pagination: {
+          offset: currentOffset,
+          limit: currentLimit,
+          has_more: hasMore,
+          next_offset: hasMore ? currentOffset + currentLimit : void 0
+        }
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  keywordGapCommand
+};
+//# sourceMappingURL=keyword-gap-CUOGKUMM.js.map

package/dist/keyword-metrics-LK7FME4N.js

@@ -0,0 +1,197 @@
+import {
+  keywordMetricsHints
+} from "./chunk-PEWNEPDR.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-JZP5IODJ.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-SQ7DRYCC.js";
+import "./chunk-SEPPFM5S.js";
+import {
+  RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS
+} from "./chunk-MAGSNHYB.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiPost
+} from "./chunk-MMOTJIV6.js";
+import "./chunk-2ZZR2SOF.js";
+import "./chunk-YPCVPDU7.js";
+import {
+  registerSchema
+} from "./chunk-D3RTGIT4.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/keyword-metrics.ts
+import { defineCommand } from "citty";
+
+// src/commands/research/keyword-metrics-rows.ts
+var KEYWORD_METRICS_SOURCE = "keyword_planner_estimate_via_dataforseo";
+function toOutputRow(row, options) {
+  const out = {
+    source: KEYWORD_METRICS_SOURCE,
+    keyword: row.keyword,
+    planner_search_volume: row.search_volume,
+    planner_cpc: row.cpc,
+    planner_low_top_of_page_bid: row.low_top_of_page_bid,
+    planner_high_top_of_page_bid: row.high_top_of_page_bid,
+    planner_competition: row.competition,
+    planner_competition_index: row.competition_index
+  };
+  if (options.clickstream) {
+    out.clickstream_search_volume = row.clickstream_search_volume;
+  }
+  if (options.full) {
+    out.keyword_difficulty = row.keyword_difficulty;
+    out.main_intent = row.main_intent;
+    out.planner_monthly_searches = row.monthly_searches;
+  }
+  return out;
+}
+function keywordMetricsFields(options) {
+  const fields = {
+    source: `Always "${KEYWORD_METRICS_SOURCE}". Every planner_ column below is Google's Keyword Planner ESTIMATE of total market volume, resold by DataForSEO \u2014 the same number \`baker ads google keywords metrics\` returns, not an independent measurement of it. Columns without the planner_ prefix are DataForSEO's own.`,
+    keyword: "The keyword asked for. A row with every metric null means DataForSEO holds no data on it \u2014 not that nobody searches it.",
+    planner_search_volume: "ESTIMATE: average monthly searches across the whole market, last 12 months",
+    planner_cpc: "ESTIMATE: average cost per click in USD (a single blended figure, not a top-of-page range)",
+    planner_low_top_of_page_bid: "ESTIMATE: low-range top-of-page bid in USD",
+    planner_high_top_of_page_bid: "ESTIMATE: high-range top-of-page bid in USD",
+    planner_competition: "ESTIMATE: competition level \u2014 LOW, MEDIUM or HIGH",
+    planner_competition_index: "ESTIMATE: competition index 0-100 (higher = more advertisers)"
+  };
+  if (options.clickstream) {
+    fields.clickstream_search_volume = "DataForSEO's OWN volume estimate, from clickstream panels \u2014 not Google's, and the only number here that is a genuine second opinion on demand. Expect it to differ from planner_search_volume; that is the point.";
+  }
+  if (options.full) {
+    fields.keyword_difficulty = "DataForSEO's 0-100 estimate of how hard ranking in the organic top 10 would be";
+    fields.main_intent = "DataForSEO's intent classification: informational, navigational, commercial or transactional";
+    fields.planner_monthly_searches = "ESTIMATE: 12-month volume breakdown ({year, month, search_volume})";
+  }
+  return fields;
+}
+
+// src/commands/research/keyword-metrics.ts
+registerSchema({
+  command: "research.keyword-metrics",
+  description: "Search volume, CPC, top-of-page bids and competition for a list of keywords you name \u2014 no domain needed. This is the command for sizing a market you have keywords for; the domain-bound ones (keywords-for-site, keyword-gap) answer a different question and should not be used as a workaround for this one. The volume is Google's Keyword Planner figure resold by DataForSEO, so it is not a second opinion on `baker ads google keywords metrics` \u2014 for that, pass --clickstream. If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
+  args: {
+    keywords: {
+      type: "string",
+      description: `Comma-separated keywords (max ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS}, 80 chars each)`,
+      required: true
+    },
+    location: {
+      type: "string",
+      description: "Country code (us, mx, br, es...) or DataForSEO location code. Defaults to us (United States) if omitted \u2014 always set this for non-US markets",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name. Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    clickstream: {
+      type: "boolean",
+      description: "Also return DataForSEO's own panel-derived volume (clickstream_search_volume), the only genuinely independent estimate of demand available here. Costs 2x.",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "Add keyword difficulty, search intent and the 12-month volume trend to each row",
+      required: false
+    },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var keywordMetricsCommand = defineCommand({
+  meta: {
+    name: "keyword-metrics",
+    description: `Volume, CPC and competition for keywords you name. No domain required.
+
+Numbers are Keyword Planner ESTIMATES of total market volume, resold by DataForSEO \u2014 every column carrying one is named planner_. Pass --clickstream for DataForSEO's own independent estimate alongside.
+
+Examples:
+  baker research keyword-metrics "chatbot whatsapp,agente whatsapp ecommerce" --location mx --language es
+  baker research keyword-metrics "chatbot whatsapp" --location br --language pt --clickstream
+  baker research keyword-metrics "crm software,best crm" --full --output md`
+  },
+  args: {
+    keywords: { type: "positional", description: "Comma-separated keywords", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    clickstream: { type: "boolean", description: "Add DataForSEO's own volume estimate (costs 2x)", required: false },
+    full: { type: "boolean", description: "Add difficulty, intent and the 12-month trend", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const keywords = args.keywords.split(",").map((k) => k.trim()).filter(Boolean);
+    if (keywords.length === 0) {
+      writeResearchJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: "Provide at least one keyword" }
+      });
+      process.exit(1);
+    }
+    if (keywords.length > RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS) {
+      writeResearchJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Maximum ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS} keywords per request`,
+          fix: {
+            action: "retry_with_changes",
+            explanation: `You sent ${keywords.length}. Split the list into batches of ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS} and run the command once per batch \u2014 each batch is a separate charge, so batch by priority.`
+          }
+        }
+      });
+      process.exit(1);
+    }
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const clickstream = Boolean(args.clickstream);
+    const full = Boolean(args.full);
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const result = await apiPost("/api/research/keyword-metrics", {
+        keywords,
+        location,
+        language,
+        includeClickstream: clickstream,
+        skipCache: args["no-cache"] ? true : void 0
+      });
+      const columns = { clickstream, full };
+      const rows = result.data.map((row) => toOutputRow(row, columns));
+      const hints = keywordMetricsHints({ rows: result.data, asked: keywords, clickstream, queryContext });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeResearchOutput(rows, format);
+        writeResearchHints([...hints, RESEARCH_DATA_NOTE], format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data: rows,
+        fields: keywordMetricsFields(columns),
+        note: RESEARCH_DATA_NOTE,
+        hints,
+        query_context: queryContext
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  keywordMetricsCommand
+};
+//# sourceMappingURL=keyword-metrics-LK7FME4N.js.map

package/dist/keywords-for-site-4E7UU44P.js

@@ -0,0 +1,128 @@
+import {
+  keywordsForSiteHints
+} from "./chunk-PEWNEPDR.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-JZP5IODJ.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-SQ7DRYCC.js";
+import "./chunk-SEPPFM5S.js";
+import "./chunk-MAGSNHYB.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiPost
+} from "./chunk-MMOTJIV6.js";
+import "./chunk-2ZZR2SOF.js";
+import "./chunk-YPCVPDU7.js";
+import {
+  registerSchema
+} from "./chunk-D3RTGIT4.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/keywords-for-site.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.keywords-for-site",
+  description: "Get keywords a competitor targets in Google. Use --type paid to see only paid keywords, --type organic for organic only. If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
+  args: {
+    target: { type: "string", description: "Domain or URL to analyze (positional)", required: true },
+    location: {
+      type: "string",
+      description: "Country code (us, uk, es, de...) or DataForSEO location code. Defaults to us (United States) if omitted \u2014 always set this for non-US markets",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name. Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    sort: {
+      type: "string",
+      description: "Sort: search_volume, competition, cpc (default: search_volume)",
+      required: false
+    },
+    type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
+    limit: { type: "string", description: "Max results (default: 50, max: 1000)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  keyword: "Keyword the site targets",
+  search_volume: "Monthly search volume",
+  cpc: "Cost per click in USD",
+  competition: "LOW, MEDIUM, or HIGH",
+  competition_index: "Competition score 0-100"
+};
+var keywordsForSiteCommand = defineCommand({
+  meta: {
+    name: "keywords-for-site",
+    description: `Get keywords a competitor targets in Google. Use --type to filter paid/organic.
+
+Examples:
+  baker research keywords-for-site "competitor.com"
+  baker research keywords-for-site "competitor.com" --type paid --limit 20
+  baker research keywords-for-site "competitor.com" --type organic --location uk`
+  },
+  args: {
+    target: { type: "positional", description: "Domain or URL to analyze", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    sort: { type: "string", description: "Sort: search_volume, competition, cpc", required: false },
+    type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
+    limit: { type: "string", description: "Max results (default: 50, max: 1000)", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const target = args.target;
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const sort = args.sort || void 0;
+    const type = args.type || void 0;
+    const limit = args.limit ? Number(args.limit) : void 0;
+    const skipCache = args["no-cache"] ? true : void 0;
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const data = await apiPost("/api/research/keywords-for-site", {
+        target,
+        location,
+        language,
+        sort,
+        type,
+        limit,
+        skipCache
+      });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      const hints = keywordsForSiteHints(data.length, queryContext, type);
+      if (format !== "json") {
+        writeResearchOutput(data, format);
+        writeResearchHints(hints, format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data,
+        fields: FIELDS,
+        note: RESEARCH_DATA_NOTE,
+        query_context: queryContext,
+        hints
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  keywordsForSiteCommand
+};
+//# sourceMappingURL=keywords-for-site-4E7UU44P.js.map

package/dist/landing-I65PFN7H.js

@@ -0,0 +1,28 @@
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/landing/index.ts
+import { defineCommand } from "citty";
+var landingCommand = defineCommand({
+  meta: {
+    name: "landing",
+    description: `Design-quality tools for landing pages (src/pages/<slug>/), and downloading the published ones.
+
+Start here: \`baker landing critique <slug>\` after building or editing a landing.
+
+Subcommands:
+  baker landing inspiration      \u2014 reference library of real landing-page sections; search it during research, BEFORE writing the Direction Contract. Inspiration only: take the mechanism, never the words.
+  baker landing variant <control> <slug> \u2014 the alternative version of a page for an A/B test: shares the control's sections, forks only the component you name, so the two arms differ by exactly your hypothesis. Run \`baker experiment plan\` first.
+  baker landing critique <slug>   \u2014 design-quality critic (advisory): flags the known AI 'slop' tells (gradient text, overused fonts, side-tab borders, cream palettes, broken images) and reads the copy in any language for buzzwords, AI copy tells and positioning integrity (copy ranking a competitor above the client), tiered block/warn/advisory, respecting the client's brand. Records the critique the publish quality gate requires \u2014 run it before finishing a landing.
+  baker landing export start      \u2014 download the PUBLISHED landings as a ZIP of plain HTML ("download my landings", "send me the HTML"); \`baker landing export status <id>\` gives the link.`
+  },
+  subCommands: {
+    inspiration: () => import("./inspiration-TJJFUVY2.js").then((m) => m.inspirationCommand),
+    critique: () => import("./critique-56MNXW7R.js").then((m) => m.critiqueCommand),
+    variant: () => import("./variant-HULP57YI.js").then((m) => m.variantCommand),
+    export: () => import("./export-VGCFD7GL.js").then((m) => m.exportCommand)
+  }
+});
+export {
+  landingCommand
+};
+//# sourceMappingURL=landing-I65PFN7H.js.map

package/dist/landings-SQJWZOJR.js

@@ -0,0 +1,151 @@
+import {
+  reportError,
+  splitList
+} from "./chunk-ICJFL7DU.js";
+import {
+  apiGet,
+  apiPost
+} from "./chunk-MMOTJIV6.js";
+import "./chunk-2ZZR2SOF.js";
+import "./chunk-YPCVPDU7.js";
+import {
+  LANDING_ANALYSE_BATCH,
+  registerSchema,
+  writeJson
+} from "./chunk-D3RTGIT4.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/landings.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.landings",
+  description: "Every landing page one brand's ads send people to, the ones in use now first (a short or tracking link counts as the page it opens; Instant Forms, chats, app stores and social profiles are not pages): how many ads point there, how many still run, platforms, when each was used (`used`: one stretch per run of ads, `\u2192 now` while running), `address_only` on an address only Google search ads print (Google publishes no search ad's real destination, and the path need not exist \u2014 not analysed), and \u2014 once analysed \u2014 the page's headline, value propositions, offer, pricing, CTAs, proof, audience and sections in order. Compact by default; --full returns every field, the ads behind each page and its screenshot. --analyse studies the top pages not yet analysed (a few minutes each).",
+  args: {
+    advertiser: { type: "string", description: "Advertiser id (from `advertisers` or `following`)", required: true },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "Every field of every page", required: false, default: false },
+    analyse: {
+      type: "boolean",
+      description: `Analyse the top ${LANDING_ANALYSE_BATCH} pages not analysed yet (or those named in --pages)`,
+      required: false,
+      default: false
+    },
+    pages: {
+      type: "string",
+      description: `With --analyse: comma list of page urls to analyse instead (max ${LANDING_ANALYSE_BATCH})`,
+      required: false
+    }
+  }
+});
+var COMPACT_PAGES = 20;
+var COMPACT_VALUE_PROPS = 3;
+var day = (iso) => iso.slice(0, 10);
+function compactPage(p) {
+  const pitch = p.analysis.pitch;
+  return {
+    url: p.canonical_url,
+    in_use_now: p.active_ads > 0,
+    ads: p.ads,
+    running: p.active_ads,
+    platforms: p.platforms,
+    used: p.windows.map((w) => `${day(w.from)} \u2192 ${w.to ? day(w.to) : "now"}`),
+    last_seen_at: p.last_seen_at,
+    ...p.address_only ? { address_only: true } : {},
+    analysis: p.analysis.status,
+    ...pitch ? {
+      headline: pitch.headline,
+      value_propositions: pitch.value_propositions.slice(0, COMPACT_VALUE_PROPS),
+      offer: pitch.offer
+    } : {}
+  };
+}
+function compactLandings(report) {
+  return {
+    advertiser_id: report.advertiser_id,
+    total_pages: report.total_pages,
+    analysed: report.pages.filter((p) => p.analysis.status === "ready").length,
+    pages: report.pages.slice(0, COMPACT_PAGES).map(compactPage)
+  };
+}
+function pagesToAnalyse(report) {
+  return report.pages.filter((p) => !p.address_only && (p.analysis.status === "not_analysed" || p.analysis.status === "failed")).slice(0, LANDING_ANALYSE_BATCH).map((p) => p.canonical_url);
+}
+function landingsHints(report, advertiser) {
+  const hints = [];
+  const top = report.pages.slice(0, COMPACT_PAGES);
+  const pending = top.filter((p) => !p.address_only && p.analysis.status === "not_analysed").length;
+  const addressOnly = report.pages.filter((p) => p.address_only).length;
+  const analysing = report.pages.filter((p) => p.analysis.status === "analysing").length;
+  if (report.pages.length === 0) {
+    hints.push("No ad of this brand links to a landing page yet.");
+    return hints;
+  }
+  if (addressOnly > 0) {
+    hints.push(
+      `${addressOnly} ${addressOnly === 1 ? "address" : "addresses"} only Google search ads show (\`address_only\`): Google publishes no search ad's destination, only the address printed on it, whose path the brand types freely and need not exist. Quote it as the address the ad shows, never as a page the ads lead to; it is not analysed.`
+    );
+  }
+  if (pending > 0) {
+    hints.push(
+      `${pending} of the top pages are not analysed yet: \`baker winning-ads landings ${advertiser} --analyse\` studies the top ${LANDING_ANALYSE_BATCH} (value propositions, offer, pricing, proof, sections). It takes a few minutes; run this again to read them.`
+    );
+  }
+  if (analysing > 0) {
+    hints.push(`${analysing} pages are being analysed now: run this again in a few minutes.`);
+  }
+  if (report.pages.some((p) => p.analysis.status === "ready")) {
+    hints.push(
+      "--full returns each analysed page's whole read: pricing, CTAs, proof, audience and its sections in order."
+    );
+  }
+  return hints;
+}
+var landingsCommand = defineCommand({
+  meta: {
+    name: "landings",
+    description: "Every landing page a brand's ads point to, with how the page sells once analysed. Start here: baker winning-ads landings adv_123 (--analyse to study the top pages not analysed yet, --full for everything)"
+  },
+  args: {
+    advertiser: { type: "positional", description: "Advertiser id", required: true },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "Every field of every page", required: false, default: false },
+    analyse: {
+      type: "boolean",
+      description: `Analyse the top ${LANDING_ANALYSE_BATCH} pages not analysed yet`,
+      required: false,
+      default: false
+    },
+    pages: { type: "string", description: "With --analyse: comma list of page urls to analyse", required: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const advertiser = String(args.advertiser);
+      const params = { advertiser };
+      if (args.platform) params.platform = String(args.platform);
+      let report = await apiGet("/api/ad-library/landing-pages", params);
+      let started;
+      if (args.analyse) {
+        const named = args.pages ? splitList(String(args.pages)) : [];
+        const urls = named.length > 0 ? named.slice(0, LANDING_ANALYSE_BATCH) : pagesToAnalyse(report);
+        if (urls.length > 0) {
+          started = (await apiPost("/api/ad-library/landing-pages/analyse", { urls })).pages;
+          report = await apiGet("/api/ad-library/landing-pages", params);
+        }
+      }
+      writeJson({
+        ok: true,
+        data: { ...args.full ? report : compactLandings(report), ...started ? { analyse: started } : {} },
+        hints: landingsHints(report, advertiser)
+      });
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  compactLandings,
+  landingsCommand,
+  landingsHints,
+  pagesToAnalyse
+};
+//# sourceMappingURL=landings-SQJWZOJR.js.map

package/dist/landings-SQJWZOJR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/winning-ads/landings.ts"],"sourcesContent":["import {\n  type AnalyseLandingPagesResponse,\n  type BrandLandingPage,\n  type BrandLandingPages,\n  LANDING_ANALYSE_BATCH,\n} from \"@baker/api/ad-library\";\nimport { defineCommand } from \"citty\";\nimport { apiGet, apiPost } from \"../../client.ts\";\nimport { writeJson } from \"../../output.ts\";\nimport { registerSchema } from \"../../schemas.ts\";\nimport { reportError, splitList } from \"./shared.ts\";\n\nregisterSchema({\n  command: \"winning-ads.landings\",\n  description:\n    \"Every landing page one brand's ads send people to, the ones in use now first (a short or tracking link counts as the page it opens; Instant Forms, chats, app stores and social profiles are not pages): how many ads point there, how many still run, platforms, when each was used (`used`: one stretch per run of ads, `→ now` while running), `address_only` on an address only Google search ads print (Google publishes no search ad's real destination, and the path need not exist — not analysed), and — once analysed — the page's headline, value propositions, offer, pricing, CTAs, proof, audience and sections in order. Compact by default; --full returns every field, the ads behind each page and its screenshot. --analyse studies the top pages not yet analysed (a few minutes each).\",\n  args: {\n    advertiser: { type: \"string\", description: \"Advertiser id (from `advertisers` or `following`)\", required: true },\n    platform: { type: \"string\", description: \"Only this platform: meta|linkedin|tiktok|google\", required: false },\n    full: { type: \"boolean\", description: \"Every field of every page\", required: false, default: false },\n    analyse: {\n      type: \"boolean\",\n      description: `Analyse the top ${LANDING_ANALYSE_BATCH} pages not analysed yet (or those named in --pages)`,\n      required: false,\n      default: false,\n    },\n    pages: {\n      type: \"string\",\n      description: `With --analyse: comma list of page urls to analyse instead (max ${LANDING_ANALYSE_BATCH})`,\n      required: false,\n    },\n  },\n});\n\nconst COMPACT_PAGES = 20;\nconst COMPACT_VALUE_PROPS = 3;\n\nconst day = (iso: string) => iso.slice(0, 10);\n\nfunction compactPage(p: BrandLandingPage) {\n  const pitch = p.analysis.pitch;\n  return {\n    url: p.canonical_url,\n    in_use_now: p.active_ads > 0,\n    ads: p.ads,\n    running: p.active_ads,\n    platforms: p.platforms,\n    used: p.windows.map((w) => `${day(w.from)} → ${w.to ? day(w.to) : \"now\"}`),\n    last_seen_at: p.last_seen_at,\n    ...(p.address_only ? { address_only: true } : {}),\n    analysis: p.analysis.status,\n    ...(pitch\n      ? {\n          headline: pitch.headline,\n          value_propositions: pitch.value_propositions.slice(0, COMPACT_VALUE_PROPS),\n          offer: pitch.offer,\n        }\n      : {}),\n  };\n}\n\n/** The pages cut to what an agent needs to pick which to read: url, ads, what runs, the top of the pitch. */\nexport function compactLandings(report: BrandLandingPages) {\n  return {\n    advertiser_id: report.advertiser_id,\n    total_pages: report.total_pages,\n    analysed: report.pages.filter((p) => p.analysis.status === \"ready\").length,\n    pages: report.pages.slice(0, COMPACT_PAGES).map(compactPage),\n  };\n}\n\n/**\n * The top pages (in use now first) nobody has analysed, or whose analysis\n * failed, at most one batch. An address only Google search ads show is left\n * out: it need not be a page at all.\n */\nexport function pagesToAnalyse(report: BrandLandingPages): string[] {\n  return report.pages\n    .filter((p) => !p.address_only && (p.analysis.status === \"not_analysed\" || p.analysis.status === \"failed\"))\n    .slice(0, LANDING_ANALYSE_BATCH)\n    .map((p) => p.canonical_url);\n}\n\n/** Point at the pages still to analyse, and say when some are on their way. */\nexport function landingsHints(report: BrandLandingPages, advertiser: string): string[] {\n  const hints: string[] = [];\n  const top = report.pages.slice(0, COMPACT_PAGES);\n  const pending = top.filter((p) => !p.address_only && p.analysis.status === \"not_analysed\").length;\n  const addressOnly = report.pages.filter((p) => p.address_only).length;\n  const analysing = report.pages.filter((p) => p.analysis.status === \"analysing\").length;\n  if (report.pages.length === 0) {\n    hints.push(\"No ad of this brand links to a landing page yet.\");\n    return hints;\n  }\n  if (addressOnly > 0) {\n    hints.push(\n      `${addressOnly} ${addressOnly === 1 ? \"address\" : \"addresses\"} only Google search ads show (\\`address_only\\`): Google publishes no search ad's destination, only the address printed on it, whose path the brand types freely and need not exist. Quote it as the address the ad shows, never as a page the ads lead to; it is not analysed.`,\n    );\n  }\n  if (pending > 0) {\n    hints.push(\n      `${pending} of the top pages are not analysed yet: \\`baker winning-ads landings ${advertiser} --analyse\\` studies the top ${LANDING_ANALYSE_BATCH} (value propositions, offer, pricing, proof, sections). It takes a few minutes; run this again to read them.`,\n    );\n  }\n  if (analysing > 0) {\n    hints.push(`${analysing} pages are being analysed now: run this again in a few minutes.`);\n  }\n  if (report.pages.some((p) => p.analysis.status === \"ready\")) {\n    hints.push(\n      \"--full returns each analysed page's whole read: pricing, CTAs, proof, audience and its sections in order.\",\n    );\n  }\n  return hints;\n}\n\nexport const landingsCommand = defineCommand({\n  meta: {\n    name: \"landings\",\n    description:\n      \"Every landing page a brand's ads point to, with how the page sells once analysed. Start here: baker winning-ads landings adv_123 (--analyse to study the top pages not analysed yet, --full for everything)\",\n  },\n  args: {\n    advertiser: { type: \"positional\", description: \"Advertiser id\", required: true },\n    platform: { type: \"string\", description: \"Only this platform: meta|linkedin|tiktok|google\", required: false },\n    full: { type: \"boolean\", description: \"Every field of every page\", required: false, default: false },\n    analyse: {\n      type: \"boolean\",\n      description: `Analyse the top ${LANDING_ANALYSE_BATCH} pages not analysed yet`,\n      required: false,\n      default: false,\n    },\n    pages: { type: \"string\", description: \"With --analyse: comma list of page urls to analyse\", required: false },\n  },\n  run: async ({ args }) => {\n    try {\n      const advertiser = String(args.advertiser);\n      const params: Record<string, string> = { advertiser };\n      if (args.platform) params.platform = String(args.platform);\n      let report = await apiGet<BrandLandingPages>(\"/api/ad-library/landing-pages\", params);\n      let started: AnalyseLandingPagesResponse[\"pages\"] | undefined;\n      if (args.analyse) {\n        const named = args.pages ? splitList(String(args.pages)) : [];\n        const urls = named.length > 0 ? named.slice(0, LANDING_ANALYSE_BATCH) : pagesToAnalyse(report);\n        if (urls.length > 0) {\n          started = (await apiPost<AnalyseLandingPagesResponse>(\"/api/ad-library/landing-pages/analyse\", { urls }))\n            .pages;\n          report = await apiGet<BrandLandingPages>(\"/api/ad-library/landing-pages\", params);\n        }\n      }\n      writeJson({\n        ok: true,\n        data: { ...(args.full ? report : compactLandings(report)), ...(started ? { analyse: started } : {}) },\n        hints: landingsHints(report, advertiser),\n      });\n    } catch (err) {\n      reportError(err);\n    }\n  },\n});\n"],"mappings":"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","names":[]}