@koda-sl/baker-cli 0.468.0 → 0.469.0

package/dist/advertisers-XHIAWVLX.js

@@ -0,0 +1,120 @@
+import {
+  advertisersHints
+} from "./chunk-YT74ZEVP.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-LKSJVVIN.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-FEELV5IV.js";
+import "./chunk-7VHPAGPK.js";
+import "./chunk-WXC3I4CT.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost
+} from "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import "./chunk-NVBBZPJP.js";
+import {
+  registerSchema
+} from "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/advertisers.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.advertisers",
+  description: 'Returns a ranked list of domains competing for one keyword in Google, with avg SERP position, relevance rating, estimated traffic value and visibility \u2014 domain economics, not ad copy. Despite the name it returns no headlines, descriptions or creative of any kind; for a competitor\'s actual ad copy use `baker research google-ads <competitor.com> --copy` (Google) or `baker winning-ads content <adId>` (Meta/LinkedIn). Start here: `baker research advertisers "<keyword>" --location <cc> --language <code>` to size up who owns a term. 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: {
+    keyword: {
+      type: "string",
+      description: "Keyword to search (positional). One search term, not a brand or a domain \u2014 this is a SERP query, not an advertiser lookup",
+      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 (en, es, spanish...). Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    limit: { type: "string", description: "Max results (default: 20, max: 100)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  domain: "Competing domain (no ad copy is returned \u2014 see hints)",
+  avg_position: "Average SERP position (1 = top)",
+  rating: "Domain relevance rating (0-100)",
+  etv: "Estimated traffic value (USD)",
+  visibility: "SERP visibility score (0-1)"
+};
+var advertisersCommand = defineCommand({
+  meta: {
+    name: "advertisers",
+    description: `Domains competing for a keyword in Google SERPs, with position, relevance, traffic value and visibility. Returns NO ad copy \u2014 for a competitor's headlines and body copy use \`baker research google-ads <competitor.com> --copy\` (Google) or \`baker winning-ads content <adId>\` (Meta/LinkedIn).
+
+Examples:
+  baker research advertisers "running shoes"
+  baker research advertisers "crm software" --location uk --limit 10
+  baker research advertisers "zapatos" --location es --language spanish`
+  },
+  args: {
+    keyword: { type: "positional", description: "Keyword to search", 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 },
+    limit: { type: "string", description: "Max results (default: 20, max: 100)", 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 keyword = args.keyword;
+    const location = args.location || void 0;
+    const language = args.language || 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/advertisers", {
+        keyword,
+        location,
+        language,
+        limit,
+        skipCache
+      });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      const hints = advertisersHints(data.length, queryContext);
+      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 {
+  advertisersCommand
+};
+//# sourceMappingURL=advertisers-XHIAWVLX.js.map

package/dist/analytics-JK53QUDI.js

@@ -0,0 +1,433 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleLinkedinError,
+  resolveAccountIdArg,
+  todayIso
+} from "./chunk-XQ2FGDOQ.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-JM7C6OHU.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-Z3GHDRUA.js";
+import "./chunk-WXC3I4CT.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost
+} from "./chunk-CK5ZNZ3I.js";
+import "./chunk-7QDVAEB6.js";
+import "./chunk-NVBBZPJP.js";
+import "./chunk-KCA5CDCU.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/analytics.ts
+import { defineCommand } from "citty";
+
+// src/commands/ads/linkedin/presets.ts
+var INTENTS = {
+  baseline: {
+    name: "baseline",
+    description: "Spend, impressions, clicks. The default 'how is delivery?' question. Derives CTR, CPC, CPM.",
+    metrics: ["impressions", "clicks", "costInUsd", "costInLocalCurrency", "approximateUniqueImpressions"],
+    derived: ["ctr", "cpc", "cpm", "frequency"]
+  },
+  revenue: {
+    name: "revenue",
+    description: "Spend, conversions, conversion value. 'How much money are we making?'",
+    metrics: [
+      "costInUsd",
+      "externalWebsiteConversions",
+      "externalWebsitePostClickConversions",
+      "externalWebsitePostViewConversions",
+      "conversionValueInLocalCurrency",
+      "oneClickLeads"
+    ]
+  },
+  funnel: {
+    name: "funnel",
+    description: "Impression \u2192 click \u2192 landing \u2192 form open \u2192 lead \u2192 conversion. 'Where do users drop off?'",
+    metrics: [
+      "impressions",
+      "clicks",
+      "landingPageClicks",
+      "oneClickLeadFormOpens",
+      "oneClickLeads",
+      "externalWebsiteConversions",
+      "costInUsd"
+    ],
+    derived: ["ctr", "leadCompletionRate"]
+  },
+  engagement: {
+    name: "engagement",
+    description: "Likes, comments, shares, follows + viral spillover. TLA-aware \u2014 measures organic reach effect.",
+    metrics: [
+      "impressions",
+      "likes",
+      "comments",
+      "shares",
+      "reactions",
+      "follows",
+      "totalEngagements",
+      "viralImpressions",
+      "viralLikes",
+      "viralShares",
+      "viralOneClickLeads",
+      "costInUsd"
+    ]
+  },
+  video: {
+    name: "video",
+    description: "Video watch quartiles + cost. 'How are video creatives holding attention?'",
+    metrics: [
+      "videoStarts",
+      "videoFirstQuartileCompletions",
+      "videoMidpointCompletions",
+      "videoThirdQuartileCompletions",
+      "videoCompletions",
+      "videoViews",
+      "fullScreenPlays",
+      "costInUsd",
+      "impressions"
+    ]
+  },
+  "lead-gen": {
+    name: "lead-gen",
+    description: "Lead Gen Form opens + completions. CLI derives form-completion-rate.",
+    metrics: [
+      "oneClickLeadFormOpens",
+      "oneClickLeads",
+      "viralOneClickLeads",
+      "viralOneClickLeadFormOpens",
+      "costInUsd"
+    ],
+    derived: ["leadCompletionRate"]
+  },
+  inmail: {
+    name: "inmail",
+    description: "Sponsored Message / Conversation Ads \u2014 sends, opens, clicks, lead-gen taps.",
+    metrics: [
+      "sends",
+      "opens",
+      "clicks",
+      "costInUsd",
+      "leadGenerationMailContactInfoShares",
+      "leadGenerationMailInterestedClicks"
+    ]
+  },
+  document: {
+    name: "document",
+    description: "Document Ads \u2014 quartile read-through, completion, downloads.",
+    metrics: [
+      "documentFirstQuartileCompletions",
+      "documentMidpointCompletions",
+      "documentThirdQuartileCompletions",
+      "documentCompletions",
+      "downloadClicks",
+      "costInUsd",
+      "impressions"
+    ]
+  },
+  ranking: {
+    name: "ranking",
+    description: "Frequency + reach metrics for fatigue detection. CLI derives frequency = impressions/uniqueImpressions.",
+    metrics: ["impressions", "clicks", "costInUsd", "approximateUniqueImpressions"],
+    derived: ["frequency", "ctr"]
+  },
+  identity: {
+    name: "identity",
+    description: "Just spend + impressions. Cheap roll-up.",
+    metrics: ["costInUsd", "impressions"]
+  }
+};
+var MEMBER_PIVOTS = /* @__PURE__ */ new Set([
+  "company",
+  "job-title",
+  "job-function",
+  "seniority",
+  "industry",
+  "company-size",
+  "country",
+  "region",
+  "dma"
+]);
+var ALL_PIVOTS = [
+  "none",
+  "campaign",
+  "campaign-group",
+  "creative",
+  "company",
+  "account",
+  "conversion",
+  "job-title",
+  "job-function",
+  "seniority",
+  "industry",
+  "company-size",
+  "country",
+  "region",
+  "dma",
+  "device",
+  "placement",
+  "serving-location",
+  "card-index",
+  "objective",
+  "conversation-node",
+  "conversation-node-button"
+];
+var ALL_LEVELS = ["account", "campaign-group", "campaign", "creative"];
+function listIntents() {
+  return Object.values(INTENTS);
+}
+function isPivot(slug) {
+  return ALL_PIVOTS.includes(slug);
+}
+function isLevel(slug) {
+  return ALL_LEVELS.includes(slug);
+}
+function composeFields(intent, _level, metricsOverride) {
+  const base = metricsOverride && metricsOverride.length > 0 ? metricsOverride : INTENTS[intent].metrics;
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const f of ["pivotValues", "dateRange", ...base]) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      out.push(f);
+    }
+  }
+  return out;
+}
+
+// src/commands/ads/linkedin/analytics.ts
+function commaSplit(input) {
+  if (!input) return void 0;
+  return input.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseGranularity(raw) {
+  const v = (raw ?? "DAILY").toUpperCase();
+  if (v === "DAILY" || v === "MONTHLY" || v === "YEARLY" || v === "ALL") {
+    return v;
+  }
+  handleLinkedinError(new Error(`Invalid --granularity "${raw}". Use DAILY | MONTHLY | YEARLY | ALL.`));
+}
+function parseLevel(raw) {
+  const v = raw ?? "account";
+  if (!isLevel(v)) {
+    handleLinkedinError(new Error(`Invalid --level "${raw}". Use one of: ${ALL_LEVELS.join(", ")}.`));
+  }
+  return v;
+}
+function parsePivot(raw) {
+  const v = raw ?? "none";
+  if (!isPivot(v)) {
+    handleLinkedinError(new Error(`Invalid --pivot "${raw}". Use one of: ${ALL_PIVOTS.join(", ")}.`));
+  }
+  return v;
+}
+function parseIntent(raw) {
+  const v = raw ?? "baseline";
+  const known = [
+    "baseline",
+    "revenue",
+    "funnel",
+    "engagement",
+    "video",
+    "lead-gen",
+    "inmail",
+    "document",
+    "ranking",
+    "identity"
+  ];
+  if (!known.includes(v)) {
+    handleLinkedinError(new Error(`Invalid --intent "${raw}". Run --list-intents to see options.`));
+  }
+  return v;
+}
+function resolveDateRange(args) {
+  const start = args.start;
+  const end = args.end;
+  if (start) {
+    return { start, end };
+  }
+  const lastDaysRaw = args["last-days"];
+  const days = lastDaysRaw ? Number(lastDaysRaw) : 7;
+  if (!Number.isFinite(days) || days < 1 || days > 730) {
+    handleLinkedinError(new Error(`Invalid --last-days "${lastDaysRaw}". Use a positive number \u2264 730.`));
+  }
+  return { start: daysAgoIso(days), end: todayIso() };
+}
+function resolveScopeIds(args, level) {
+  if (level === "account") {
+    const id = resolveAccountIdArg(args);
+    return [id];
+  }
+  if (level === "campaign-group") {
+    const raw2 = args["campaign-group-id"] ?? args.ids;
+    if (!raw2) {
+      handleLinkedinError(new Error("Pass --campaign-group-id (CSV for multi) when --level campaign-group."));
+    }
+    return commaSplit(raw2) ?? [];
+  }
+  if (level === "campaign") {
+    const raw2 = args["campaign-id"] ?? args.ids;
+    if (!raw2) {
+      handleLinkedinError(new Error("Pass --campaign-id (CSV for multi) when --level campaign."));
+    }
+    return commaSplit(raw2) ?? [];
+  }
+  const raw = args["creative-id"] ?? args.ids;
+  if (!raw) {
+    handleLinkedinError(new Error("Pass --creative-id (CSV for multi) when --level creative."));
+  }
+  return commaSplit(raw) ?? [];
+}
+function sortRows(rows) {
+  return [...rows].sort((a, b) => {
+    const cs = numberOf(b.costInUsd) - numberOf(a.costInUsd);
+    if (cs !== 0) return cs;
+    return numberOf(b.impressions) - numberOf(a.impressions);
+  });
+}
+function numberOf(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : 0;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+var analyticsCommand = defineCommand({
+  meta: {
+    name: "analytics",
+    description: `Performance reporting \u2014 the workhorse for AI agents.
+
+Three-axis design (LinkedIn's superpower over Meta/Google):
+  --level   account | campaign-group | campaign | creative
+  --intent  baseline | revenue | funnel | engagement | video | lead-gen | inmail | document | ranking | identity
+  --pivot   none | job-title | company | industry | seniority | function | company-size | country | region | dma
+            | device | placement | serving-location | card-index | objective
+            | conversation-node | conversation-node-button
+
+Smart defaults:
+  --level account, --intent baseline, --pivot none, --granularity DAILY, last 7 days
+  Pivot on a MEMBER_* dim \u2192 granularity auto-forced to ALL (LinkedIn rejects DAILY+demographic)
+  Demographic data delayed 12-24h with \u22653-event privacy floor \u2014 the CLI flags this in warnings.
+  --pivot dma \u2192 US Nielsen DMA\xAE regions, names resolved. Any report built from it must write "DMA\xAE"
+  and carry Nielsen's notice (returned as the DMA_ATTRIBUTION_REQUIRED warning).
+  Derived metrics injected client-side: ctr, cpc, cpm, frequency, leadCompletionRate
+
+Examples \u2014 common AI questions:
+  # "How is this account doing this week?"
+  baker ads linkedin analytics
+
+  # "Who are we reaching, by job title?" (the LinkedIn killer)
+  baker ads linkedin analytics --level campaign --campaign-id 1234 --pivot job-title --intent baseline --last-days 30
+
+  # "Top companies seeing my ads" (ABM feedback loop)
+  baker ads linkedin analytics --level campaign --campaign-id 1234 --pivot company --last-days 30
+
+  # "Revenue by campaign over Q1"
+  baker ads linkedin analytics --level campaign --campaign-id 1,2,3 --intent revenue --start 2026-01-01 --end 2026-03-31 --granularity MONTHLY
+
+  # "How is the lead form converting?"
+  baker ads linkedin analytics --level campaign --campaign-id 1234 --intent lead-gen
+
+  # Custom field set (escape hatch)
+  baker ads linkedin analytics --metrics impressions,clicks,oneClickLeads --intent identity`
+  },
+  args: {
+    level: { type: "string", description: "Object scope (default: account)" },
+    "account-id": { type: "string", description: "Account ID \u2014 numeric or urn:li:sponsoredAccount:N (level=account)" },
+    "account-urn": { type: "string", description: "Alias for --account-id (URN form)" },
+    "campaign-group-id": { type: "string", description: "Comma-separated IDs (level=campaign-group)" },
+    "campaign-id": { type: "string", description: "Comma-separated IDs (level=campaign)" },
+    "creative-id": { type: "string", description: "Comma-separated IDs (level=creative)" },
+    ids: { type: "string", description: "Generic CSV of IDs at the chosen level (alternative to per-level flags)" },
+    intent: {
+      type: "string",
+      description: "baseline|revenue|funnel|engagement|video|lead-gen|inmail|document|ranking|identity"
+    },
+    pivot: { type: "string", description: "Pivot dim. Default: none. See `--list-pivots`." },
+    metrics: { type: "string", description: "CSV metric override \u2014 bypass --intent's bundle" },
+    "list-intents": { type: "boolean", description: "Print intent definitions and exit" },
+    "list-pivots": { type: "boolean", description: "Print pivot slugs and exit" },
+    start: { type: "string", description: "Start date YYYY-MM-DD (overrides --last-days)" },
+    end: { type: "string", description: "End date YYYY-MM-DD" },
+    "last-days": { type: "string", description: "Window relative to today (default: 7)" },
+    granularity: { type: "string", description: "DAILY|MONTHLY|YEARLY|ALL (default: DAILY)" },
+    limit: { type: "string", description: "Max rows (default: 1000)" },
+    "no-sort": { type: "boolean", description: "Skip default sort by costInUsd desc" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "Output format json|csv|jsonl|md", default: "json" }
+  },
+  run: async ({ args }) => {
+    if (args["list-intents"]) {
+      writeAdsJson({ ok: true, data: listIntents() });
+      return;
+    }
+    if (args["list-pivots"]) {
+      writeAdsJson({ ok: true, data: ALL_PIVOTS });
+      return;
+    }
+    const level = parseLevel(args.level);
+    const intent = parseIntent(args.intent);
+    const pivot = parsePivot(args.pivot);
+    let granularity = parseGranularity(args.granularity);
+    if (MEMBER_PIVOTS.has(pivot) && granularity === "DAILY") {
+      process.stderr.write(`note: pivot=${pivot} forces --granularity ALL (LinkedIn rejects DAILY + demographic).
+`);
+      granularity = "ALL";
+    }
+    const ids = resolveScopeIds(args, level);
+    if (ids.length === 0) {
+      handleLinkedinError(new Error(`No IDs resolved for --level ${level}`));
+    }
+    const range = resolveDateRange(args);
+    const metrics = commaSplit(args.metrics);
+    const limit = args.limit ? Number(args.limit) : 1e3;
+    const request = {
+      level,
+      ids,
+      intent,
+      pivot,
+      metrics,
+      start: range.start,
+      end: range.end,
+      granularity,
+      limit
+    };
+    try {
+      const data = await apiPost("/api/ads/linkedin/analytics", {
+        request,
+        skipCache: Boolean(args["no-cache"])
+      });
+      const rows = args["no-sort"] ? data.rows : sortRows(data.rows);
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        writeAdsOutput(rows, fmt, data.fields);
+        return;
+      }
+      writeAdsJson({
+        ok: true,
+        data: {
+          rows,
+          fields: data.fields,
+          warnings: data.warnings,
+          query: data.query,
+          // Echo composed fields so an offline agent can pre-flight w/o this network call.
+          composedFields: composeFields(intent, level, metrics)
+        }
+      });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  analyticsCommand
+};
+//# sourceMappingURL=analytics-JK53QUDI.js.map