@koda-sl/baker-cli 0.460.0 → 0.462.0

package/dist/companies-X57P3WYA.js

@@ -0,0 +1,194 @@
+import {
+  csvOrJson,
+  handleLinkedinError
+} from "./chunk-WSYGMU3A.js";
+import {
+  TABLE_OUTPUT_FORMATS,
+  outputFormatRefusal,
+  writeAdsJson,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-V44SLD5J.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-X7ZODEXJ.js";
+import {
+  linkedinCompaniesRequestSchema
+} from "./chunk-ZJVHZHYP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost
+} from "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import {
+  getEnv
+} from "./chunk-NBPJBJJD.js";
+import "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/companies.ts
+import { defineCommand } from "citty";
+var COMPANIES_PAGE_SIZE = 100;
+var COMPANIES_TIMEOUT_MS = 18e4;
+var CSV_FIELDS = [
+  "org",
+  "name",
+  "domain",
+  "domainSource",
+  "impressions",
+  "clicks",
+  "engagements",
+  "costLocal",
+  "videoViews",
+  "months",
+  "campaigns"
+];
+function companiesHints(data, request) {
+  const hints = [];
+  if (data.rows.length === 0) {
+    hints.push(
+      `No company shows up for ${data.query.start} to ${data.query.end}${data.query.minImpressions > 0 ? ` at --min-impressions ${data.query.minImpressions}` : ""}. LinkedIn reports companies 12-24h late and leaves out any with fewer than 3 events in a month, so a small or new campaign can have none yet. Try a longer period (--last-months 24), drop --min-impressions, or check the campaigns delivered with \`baker ads linkedin analytics\`.`
+    );
+    return hints;
+  }
+  const withDomain = data.rows.filter((row) => row.domain !== void 0).length;
+  if (withDomain > 0) {
+    hints.push(
+      `${withDomain} companies came back with a website domain \u2014 if HubSpot is connected, \`baker hubspot companies search --domains <domain,domain,\u2026> --with-deals\` (up to 100 per call) shows which are already accounts and which have deals.`
+    );
+  } else if (!request.withDomains && data.rows.length > 0) {
+    hints.push(
+      "Add --with-domains to get each company's website domain, ready for matching against your customer list."
+    );
+  }
+  if (data.totalCompanies > data.rows.length) {
+    const page = data.page ?? 1;
+    const first = (page - 1) * COMPANIES_PAGE_SIZE + 1;
+    const last = first + data.rows.length - 1;
+    const next = last < data.totalCompanies ? ` \u2014 --page ${page + 1} for the next ${COMPANIES_PAGE_SIZE}, ` : " \u2014 ";
+    hints.push(
+      `Showing companies ${first}-${last} of ${data.totalCompanies.toLocaleString("en")}, most engaged first${next}--full for all, or --min-impressions to trim the tail.`
+    );
+  }
+  if (data.query.by === "none" && data.rows.length > 0) {
+    hints.push("--by month shows when each company warmed up; --by campaign shows which campaigns reached it.");
+  }
+  return hints;
+}
+function csvList(raw) {
+  if (typeof raw !== "string") return void 0;
+  const items = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+var FLAG_OF_FIELD = {
+  accountId: "--account-id",
+  campaignIds: "--campaign-id",
+  lastMonths: "--last-months",
+  start: "--start",
+  end: "--end",
+  by: "--by",
+  minImpressions: "--min-impressions",
+  page: "--page"
+};
+function flagOf(field) {
+  return FLAG_OF_FIELD[field.split(".")[0] ?? ""] ?? (field || "args");
+}
+function optionalNumber(raw) {
+  return typeof raw === "string" && raw.trim() !== "" ? Number(raw) : void 0;
+}
+function bareAccountId(raw) {
+  return raw?.startsWith("urn:") ? raw.split(":").pop() : raw;
+}
+var companiesCommand = defineCommand({
+  meta: {
+    name: "companies",
+    description: `Which companies your LinkedIn ads reached \u2014 one row per company over the whole period, most engaged first.
+
+Start here for "which companies are our ads warming", ABM reporting, or building a warm-account list.
+Rows: {org, name, impressions, clicks, engagements, costLocal}. Defaults: the last 12 calendar
+months, the only selected ad account, 100 companies a page (--page 2 for the next, --full for all).
+
+Examples:
+  baker ads linkedin companies                                          # last 12 months, whole account
+  baker ads linkedin companies --page 2                                 # the next 100 companies
+  baker ads linkedin companies --by month --min-impressions 50          # when each company warmed up
+  baker ads linkedin companies --campaign-id 333728193,810055513 --by campaign
+  baker ads linkedin companies --with-domains --output csv              # + website domain, for CRM matching
+  baker ads linkedin companies --last-months 3 --stats                  # + how complete LinkedIn's data is
+
+LinkedIn reports companies 12-24h late and leaves out any company with fewer than 3 events in a month,
+so small companies are undercounted. engagements = LinkedIn's totalEngagements.`
+  },
+  args: {
+    "account-id": {
+      type: "string",
+      description: "Ad account id (numeric or urn:li:sponsoredAccount:N). Default: the only selected account"
+    },
+    "campaign-id": { type: "string", description: "Comma-separated campaign ids \u2014 read only these campaigns" },
+    "last-months": { type: "string", description: "Calendar months back, including this one (1-24, default 12)" },
+    start: { type: "string", description: "Start date YYYY-MM-DD (instead of --last-months)" },
+    end: { type: "string", description: "End date YYYY-MM-DD (default today)" },
+    by: { type: "string", description: "none | month | campaign \u2014 break each company down (default none)" },
+    "with-domains": { type: "boolean", description: "Add each company's website domain and domainSource" },
+    "min-impressions": { type: "string", description: "Leave out companies under N impressions over the period" },
+    full: { type: "boolean", description: "Every company (not just a page of 100), plus videoViews" },
+    page: {
+      type: "string",
+      description: "Which page of 100 companies, most engaged first (default 1); totalCompanies counts them all"
+    },
+    stats: { type: "boolean", description: "Add read-quality stats: row counts, cost/reach/domain coverage" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "json|csv|jsonl|md", default: "json" }
+  },
+  run: async ({ args }) => {
+    const input = {
+      accountId: bareAccountId(args["account-id"] || getEnv().BAKER_LINKEDIN_AD_ACCOUNT_ID),
+      campaignIds: csvList(args["campaign-id"]),
+      lastMonths: optionalNumber(args["last-months"]),
+      start: args.start,
+      end: args.end,
+      by: args.by,
+      withDomains: Boolean(args["with-domains"]),
+      minImpressions: optionalNumber(args["min-impressions"]),
+      full: Boolean(args.full),
+      page: optionalNumber(args.page),
+      stats: Boolean(args.stats),
+      skipCache: Boolean(args["no-cache"])
+    };
+    const parsed = linkedinCompaniesRequestSchema.safeParse(input);
+    const formatRefusal = outputFormatRefusal(csvOrJson(args), TABLE_OUTPUT_FORMATS);
+    if (!parsed.success || formatRefusal !== null) {
+      const issues = parsed.success ? [] : parsed.error.issues;
+      const messages = issues.map((issue) => `${flagOf(issue.path.join("."))}: ${issue.message}`);
+      writeAdsJson({
+        ok: false,
+        error: { code: "INVALID_ARGS", message: [...messages, ...formatRefusal ? [formatRefusal] : []].join("; ") }
+      });
+      process.exit(1);
+    }
+    try {
+      const { data } = await apiPost(
+        "/api/ads/linkedin/companies",
+        input,
+        { timeoutMs: COMPANIES_TIMEOUT_MS }
+      );
+      const hints = companiesHints(data, parsed.data);
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        const notes = [...data.warnings.map((w) => `${w.code}: ${w.message}`), ...hints];
+        writeAdsOutput(data.rows, fmt, CSV_FIELDS, notes);
+        return;
+      }
+      writeJsonEnvelope(hints.length > 0 ? { ok: true, data, hints } : { ok: true, data });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  companiesCommand,
+  companiesHints
+};
+//# sourceMappingURL=companies-X57P3WYA.js.map

package/dist/complete-AXJKIV3E.js

@@ -0,0 +1,80 @@
+import {
+  failApi,
+  failValidation,
+  isTempId,
+  writeOk
+} from "./chunk-R5LKE2E5.js";
+import {
+  ACTION_COMPLETE_NOTE_MIN
+} from "./chunk-ZJVHZHYP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost,
+  validateConvexId
+} from "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import {
+  requireChatId
+} from "./chunk-NBPJBJJD.js";
+import {
+  registerSchema
+} from "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/actions/complete.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "actions.complete",
+  description: "Stage completion of an action (it was done). Accepts a real action ID (must be claimed) or a temp ID from the same draft. The action becomes completed when the chat is published. --note is required and must describe what you actually did to resolve it (what changed, where, and the outcome) \u2014 it is the client-facing record surfaced by `baker actions log`. Don't use this to drop an action you no longer want \u2014 to remove a staged op use `actions draft remove`, to close an unwanted published action use `actions discard`.",
+  args: {
+    id: { type: "string", description: "Action ID or temp ID", required: true },
+    note: {
+      type: "string",
+      description: "REQUIRED. Detailed description of what you did to resolve this: what changed, where, and the outcome. This is the durable, client-facing record shown by `baker actions log`.",
+      required: true
+    }
+  }
+});
+var completeCommand = defineCommand({
+  meta: {
+    name: "complete",
+    description: "Stage completion of an action. Accepts real IDs (claimed) or temp IDs (same draft). Example: baker actions complete <id>"
+  },
+  args: {
+    id: { type: "positional", description: "Action ID or temp ID", required: false },
+    "action-id": { type: "string", description: "Action ID or temp ID", required: false },
+    note: {
+      type: "string",
+      description: "REQUIRED. What you did to resolve this: what changed, where, and the outcome.",
+      required: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const id = args.id || args["action-id"];
+      if (!id) {
+        failValidation("Action ID is required.");
+      }
+      if (!isTempId(id)) {
+        validateConvexId(id);
+      }
+      const note = args.note?.trim() ?? "";
+      if (note.length < ACTION_COMPLETE_NOTE_MIN) {
+        failValidation(
+          `--note is required and must describe what you did (\u2265${ACTION_COMPLETE_NOTE_MIN} chars): what changed, where, and the outcome. This becomes the client-facing record surfaced by \`baker actions log\`.`
+        );
+      }
+      const chatId = requireChatId();
+      await apiPost("/api/actions/complete", { chatId, actionRef: id, note });
+      writeOk();
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+export {
+  completeCommand
+};
+//# sourceMappingURL=complete-AXJKIV3E.js.map

package/dist/config-BRV224RN.js

@@ -0,0 +1,88 @@
+import {
+  handleError
+} from "./chunk-SZVONWMY.js";
+import "./chunk-D5FY4FAK.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-V44SLD5J.js";
+import {
+  apiPost
+} from "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import "./chunk-NBPJBJJD.js";
+import {
+  registerSchema
+} from "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ga4/config.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ga4.config",
+  description: "Read how a Google Analytics property is configured to measure: key events (conversions), custom dimensions and metrics, custom events, audiences, linked Google Ads accounts, data streams and the data retention window. Start here before staging any change \u2014 every id an update or removal targets comes from this, and `canWrite` says whether this connection may change anything at all. Compact by default; pass --full for the raw Analytics objects AND each website stream's enhanced measurement settings (the automatic events), which are the only way to see what is on before changing a toggle.",
+  args: {
+    "property-id": { type: "string", description: "GA4 property id (optional when one is connected)", required: false },
+    full: {
+      type: "boolean",
+      description: "Include the raw Analytics object for each entity, plus each website stream's enhanced measurement settings",
+      required: false
+    }
+  }
+});
+function configHints(config) {
+  const hints = [];
+  if (!config.canWrite) {
+    hints.push(
+      "This connection can READ this property but not change it. Do not promise to configure anything \u2014 ask the user to reconnect Google Analytics in the dashboard first, and carry on with the reporting side of the job."
+    );
+  }
+  if (config.keyEvents.length === 0) {
+    hints.push(
+      "This property has no key events, so nothing is being counted as a conversion and Google Ads has nothing to import. Ask what counts as a lead or sale before proposing anything else."
+    );
+  }
+  if (config.dataRetention.eventDataRetention === "TWO_MONTHS") {
+    hints.push(
+      "Event data is only kept for 2 months, which makes any long-window analysis impossible. `baker ga4 data-retention set --event-data 14` stages the fix."
+    );
+  }
+  if (config.dataStreams.filter((stream) => stream.type === "WEB_DATA_STREAM").length > 1) {
+    hints.push("This property has more than one website data stream \u2014 pass --data-stream when staging a custom event.");
+  }
+  return hints;
+}
+var configCommand = defineCommand({
+  meta: {
+    name: "config",
+    description: `Read how the property is configured to measure \u2014 key events, custom definitions, custom events, retention
+
+Examples:
+  baker ga4 config
+  baker ga4 config --property-id 123456789
+  baker ga4 config --full          # + the automatic events each website stream collects today`
+  },
+  args: {
+    "property-id": { type: "string", description: "GA4 property id", required: false },
+    full: {
+      type: "boolean",
+      description: "Include raw Analytics objects and enhanced measurement settings",
+      required: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const data = await apiPost("/api/ga4/config", {
+        ...typeof args["property-id"] === "string" ? { propertyId: args["property-id"] } : {},
+        ...args.full === true ? { full: true } : {}
+      });
+      writeJsonEnvelope({ ok: true, data, hints: configHints(data) });
+    } catch (err) {
+      handleError(err);
+    }
+  }
+});
+export {
+  configCommand,
+  configHints
+};
+//# sourceMappingURL=config-BRV224RN.js.map

package/dist/connect-4CVX7OVQ.js

@@ -0,0 +1,41 @@
+import {
+  attachDestination,
+  attachSettings,
+  attachStep,
+  connectCommand,
+  copyDestination,
+  destinationRefusal,
+  restatableTargets,
+  sealRequestFor,
+  targetsFor,
+  unpickedSteps,
+  unwiredHubspotForms,
+  unwiredSideEffects
+} from "./chunk-4SVCH527.js";
+import "./chunk-MNU3BEO3.js";
+import "./chunk-GSKY6ZGP.js";
+import "./chunk-R5LKE2E5.js";
+import "./chunk-ZJVHZHYP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import "./chunk-NBPJBJJD.js";
+import "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+export {
+  attachDestination,
+  attachSettings,
+  attachStep,
+  connectCommand,
+  copyDestination,
+  destinationRefusal,
+  restatableTargets,
+  sealRequestFor,
+  targetsFor,
+  unpickedSteps,
+  unwiredHubspotForms,
+  unwiredSideEffects
+};
+//# sourceMappingURL=connect-4CVX7OVQ.js.map

package/dist/content-ZRHORHLG.js

@@ -0,0 +1,85 @@
+import {
+  reportError,
+  splitList
+} from "./chunk-POSV2BIJ.js";
+import {
+  apiGet
+} from "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import "./chunk-NBPJBJJD.js";
+import {
+  adContentNormalizer,
+  applyFieldMask,
+  registerSchema,
+  writeJson,
+  writeOutput
+} from "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/content.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.content",
+  description: "Read what's INSIDE one winning ad: the spoken transcript, the on-screen text, and the ad copy. Use this after `search`/`winners`/`feed` return a shortlist \u2014 pass an ad_id to understand a reference before reproducing it. Static and carousel ads return the text drawn into the image with the job each piece does (headline, benefit, cta\u2026), the card it sits on, and their format_pattern. It also says where the ad is in its life (stage: new, testing, proven, evergreen, killed_early, retired, unverified) and, when it is one version of a concept its brand tested, the test: whether this version was kept or cut and what the kept one did differently. Add --full for how it is built (composition, colours, CTA, markers), how it persuades (awareness, mechanism, pains, desires, proof, objections), what it offers (offer type, price, guarantee, urgency), plus speech, pacing and soundtrack for video.",
+  args: {
+    "ad-id": { type: "string", description: "The ad id to open (from search/winners/feed results)", required: true },
+    platform: {
+      type: "string",
+      description: "Which platform the ad id is on: meta|linkedin|tiktok|google (default meta)",
+      required: false
+    }
+  }
+});
+var contentCommand = defineCommand({
+  meta: {
+    name: "content",
+    description: "Read the transcript + on-screen text + copy of one winning ad; --full adds its build, persuasion and offer. Example: baker winning-ads content adg_123 --platform meta --full --output md"
+  },
+  args: {
+    "ad-id": { type: "positional", description: "Ad id (from search/winners/feed)", required: true },
+    platform: {
+      type: "string",
+      description: "Platform the ad id is on: meta|linkedin|tiktok|google (default meta)",
+      required: false
+    },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: { type: "string", description: "Comma-separated field names to include", required: false },
+    full: {
+      type: "boolean",
+      description: "Include build (layout, colours, CTA), persuasion (awareness, pains, proof), offer, and video speech/pacing/soundtrack",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = { id: String(args["ad-id"]) };
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const data = await apiGet("/api/ad-library/ad-content", params);
+      const output = args.output || "json";
+      const full = args.full;
+      const ad = data?.ad ?? {};
+      if (output === "json") {
+        const fields = splitList(args.fields);
+        const read = adContentNormalizer(ad, full);
+        writeJson({ ok: true, data: { ad: fields.length > 0 ? applyFieldMask(read, fields) : read } });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: ad },
+        output,
+        args.fields ? args.fields.split(",") : void 0,
+        full,
+        adContentNormalizer
+      );
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  contentCommand
+};
+//# sourceMappingURL=content-ZRHORHLG.js.map

package/dist/conversation-P5Y3G7DN.js

@@ -0,0 +1,92 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleLinkedinError,
+  todayIso
+} from "./chunk-WSYGMU3A.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-V44SLD5J.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-X7ZODEXJ.js";
+import "./chunk-ZJVHZHYP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-ML7DLFFY.js";
+import {
+  apiPost
+} from "./chunk-D4N5ZXEO.js";
+import "./chunk-QYDJJLEE.js";
+import "./chunk-NBPJBJJD.js";
+import "./chunk-4TCMKTJG.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/conversation.ts
+import { defineCommand } from "citty";
+var conversationCommand = defineCommand({
+  meta: {
+    name: "conversation",
+    description: `Per-button click rates inside Sponsored Messaging / Conversation Ads.
+
+Returns one row per CONVERSATION_NODE_BUTTON pivot, sorted by clicks desc.
+Use this to A/B test button copy and the cascade tree.
+
+Examples:
+  baker ads linkedin conversation --campaign-id 1234
+  baker ads linkedin conversation --campaign-id 1234 --last-days 30 --output csv`
+  },
+  args: {
+    "campaign-id": {
+      type: "string",
+      description: "Comma-separated campaign IDs (Conversation Ad campaigns)",
+      required: true
+    },
+    start: { type: "string", description: "Start date YYYY-MM-DD" },
+    end: { type: "string", description: "End date YYYY-MM-DD" },
+    "last-days": { type: "string", description: "Window relative to today (default: 30)" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "json|csv|jsonl|md", default: "json" }
+  },
+  run: async ({ args }) => {
+    const campaignIdsRaw = args["campaign-id"];
+    if (!campaignIdsRaw) {
+      handleLinkedinError(new Error("--campaign-id is required"));
+    }
+    const ids = campaignIdsRaw.split(",").map((s) => s.trim()).filter(Boolean);
+    const start = args.start ?? daysAgoIso(args["last-days"] ? Number(args["last-days"]) : 30);
+    const end = args.end ?? todayIso();
+    try {
+      const data = await apiPost("/api/ads/linkedin/analytics", {
+        request: {
+          level: "campaign",
+          ids,
+          intent: "inmail",
+          pivot: "conversation-node-button",
+          start,
+          end,
+          granularity: "ALL",
+          limit: 500
+        },
+        skipCache: Boolean(args["no-cache"])
+      });
+      const sorted = [...data.rows].sort((a, b) => Number(b.clicks ?? 0) - Number(a.clicks ?? 0));
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        writeAdsOutput(sorted, fmt, data.fields);
+        return;
+      }
+      writeAdsJson({
+        ok: true,
+        data: { query: { campaigns: ids, start, end }, rows: sorted, warnings: data.warnings }
+      });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  conversationCommand
+};
+//# sourceMappingURL=conversation-P5Y3G7DN.js.map