@koda-sl/baker-cli 0.503.0 → 0.505.0-dev.eb0521917

package/dist/analytics-THGHCXEC.js

@@ -0,0 +1,445 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleLinkedinError,
+  resolveAccountIdArg,
+  todayIso
+} from "./chunk-NW2BKBEZ.js";
+import {
+  syncedFirstHint
+} from "./chunk-TWKZVPOA.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-ZRP7Y2DM.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-AGBBTTKA.js";
+import "./chunk-OR7PFL2W.js";
+import "./chunk-CAZGM2NX.js";
+import "./chunk-NZS3KEQ2.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-UI6BKYQD.js";
+import "./chunk-HNNCAJNF.js";
+import {
+  apiPost
+} from "./chunk-X7VQFLHI.js";
+import "./chunk-LU4HI4KI.js";
+import "./chunk-LGK7UWBN.js";
+import "./chunk-Q7US4OOA.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.`));
+}
+var SYNCED_LEVEL = {
+  account: "account",
+  "campaign-group": "campaign",
+  campaign: "ad_group",
+  creative: "ad"
+};
+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)
+        },
+        // Member pivots (job title, company, seniority…) exist only live.
+        ...pivot === "none" ? { hints: [syncedFirstHint("linkedin", SYNCED_LEVEL[level])] } : {}
+      });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  analyticsCommand
+};
+//# sourceMappingURL=analytics-THGHCXEC.js.map