@koda-sl/baker-cli 0.575.0-dev.85f21462e → 0.576.0

package/dist/alerts-4FE3PUUK.js

@@ -0,0 +1,151 @@
+import {
+  invalidArgsMessage
+} from "./chunk-LJ4AMUHS.js";
+import "./chunk-7HZTVVO7.js";
+import "./chunk-IPEQHZ5H.js";
+import "./chunk-GRQ2AXDX.js";
+import "./chunk-VJUVTMHY.js";
+import {
+  failApi
+} from "./chunk-Y25W6RSY.js";
+import {
+  calendarDaySchema
+} from "./chunk-IPDDXD5K.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-3WOFZTGC.js";
+import "./chunk-XHWHBGKX.js";
+import {
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+
+// ../api/src/accounts/alerts.ts
+import { z } from "zod";
+var ACCOUNTS_ALERTS_DEFAULT_LIMIT = 100;
+var ACCOUNTS_ALERTS_MAX_LIMIT = 1e3;
+var accountsAlertsRequestSchema = z.object({
+  /** Alerts on or after this day (UTC), `YYYY-MM-DD`. */
+  since: calendarDaySchema.optional(),
+  /** One company's alerts: its LinkedIn id or `urn:li:organization:` URN. */
+  orgId: z.string().transform((value) => value.replace(/^urn:li:organization:/, "")).pipe(z.string().regex(/^\d+$/, "use the LinkedIn company id or its urn:li:organization URN")).optional(),
+  limit: z.number().int().min(1).max(ACCOUNTS_ALERTS_MAX_LIMIT).default(ACCOUNTS_ALERTS_DEFAULT_LIMIT),
+  /** Each alert's Scheduled agent id, run and month too. */
+  full: z.boolean().default(false)
+});
+var accountAlertSchema = z.object({
+  /** LinkedIn organization id. */
+  orgId: z.string(),
+  name: z.string(),
+  domain: z.string(),
+  /** When the alert went out, ISO. */
+  alertedAt: z.string(),
+  isTarget: z.boolean(),
+  /** Its tier on the target list; null when none. */
+  tier: z.string().nullable(),
+  /** The Scheduled agent that was told, by name. */
+  agent: z.string(),
+  /** `--full` only. */
+  scheduledAgentId: z.string().optional(),
+  /** `--full` only: the run the alert opened; null when the agent held it (an AI check, an occurrences rule). */
+  runChatId: z.string().nullable().optional(),
+  /** `--full` only: the month it warmed in, `YYYY-MM`. */
+  month: z.string().optional()
+});
+var accountsAlertsResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    alerts: z.array(accountAlertSchema),
+    /** More alerts match than `limit` returned. */
+    truncated: z.boolean()
+  })
+});
+
+// src/commands/accounts/alerts.ts
+import { defineCommand } from "citty";
+function alertsHints(data, request) {
+  if (data.alerts.length === 0) {
+    return [
+      "No warm-account alert has gone out in this period. Alerts come from a Scheduled agent on the account.warmed trigger (`baker scheduled-agents`)."
+    ];
+  }
+  const targets = data.alerts.filter((alert) => alert.isTarget).length;
+  const hints = [
+    `${targets} of ${data.alerts.length} alerted companies are target accounts.`,
+    "To see what came of them: `baker accounts company <domain>` for one company's deals, or `baker accounts influenced --basis open --targets <file>` for the pipeline."
+  ];
+  if (data.truncated) hints.push(`More alerts match than --limit ${request.limit}; raise it, or narrow with --since.`);
+  return hints;
+}
+var ALERTS_ARGS = {
+  since: {
+    type: "string",
+    description: "Alerts on or after this day, YYYY-MM-DD (default: all kept)",
+    required: false
+  },
+  company: {
+    type: "string",
+    description: "One company's alerts: its LinkedIn company id or urn:li:organization URN",
+    required: false
+  },
+  limit: {
+    type: "string",
+    description: `Most alerts listed, newest first (1-${ACCOUNTS_ALERTS_MAX_LIMIT}, default ${ACCOUNTS_ALERTS_DEFAULT_LIMIT})`,
+    required: false
+  },
+  full: {
+    type: "boolean",
+    description: "Each alert's Scheduled agent id, run id and month too",
+    required: false,
+    default: false
+  }
+};
+registerSchema({
+  command: "accounts.alerts",
+  description: "Start here for 'which accounts did we alert sales about' or 'did the warm-account alerts lead anywhere'. Every warming company a Scheduled agent on the account.warmed trigger was handed, newest first: {orgId, name, domain, alertedAt, isTarget, tier, agent}. Each agent hears a company at most once a month. --since YYYY-MM-DD, --company <LinkedIn id> for one company's, --full adds scheduledAgentId, runChatId and month. Then `baker accounts company <domain>` shows what happened with that company's deals.",
+  args: ALERTS_ARGS
+});
+function optionalString(raw) {
+  return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : void 0;
+}
+var alertsCommand = defineCommand({
+  meta: {
+    name: "alerts",
+    description: "Every warming company a warm-account alert named, newest first. Example: baker accounts alerts --since 2026-10-01"
+  },
+  args: ALERTS_ARGS,
+  run: async ({ args }) => {
+    const limit = optionalString(args.limit);
+    const parsed = accountsAlertsRequestSchema.safeParse({
+      since: optionalString(args.since),
+      orgId: optionalString(args.company),
+      ...limit === void 0 ? {} : { limit: Number(limit) },
+      full: Boolean(args.full)
+    });
+    if (!parsed.success) {
+      writeJson({ ok: false, error: { code: "INVALID_ARGS", message: invalidArgsMessage(parsed.error.issues) } });
+      process.exit(1);
+    }
+    try {
+      const response = await apiPost("/api/accounts/alerts", parsed.data);
+      const hints = alertsHints(response.data, parsed.data);
+      writeJson({ ...response, meta: { count: response.data.alerts.length }, ...hints.length > 0 ? { hints } : {} });
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+export {
+  alertsCommand,
+  alertsHints
+};
+//# sourceMappingURL=alerts-4FE3PUUK.js.map

package/dist/analytics-HZDE5TKC.js

@@ -0,0 +1,447 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleLinkedinError,
+  resolveAccountIdArg,
+  todayIso
+} from "./chunk-TQIEDVJB.js";
+import {
+  syncedFirstHint
+} from "./chunk-Y2FAUFWK.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-VJUVTMHY.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-HPF3USL2.js";
+import "./chunk-IPDDXD5K.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-3WOFZTGC.js";
+import "./chunk-XHWHBGKX.js";
+import {
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import "./chunk-NXNOXZGB.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-HZDE5TKC.js.map