@koda-sl/baker-cli 0.489.0 → 0.491.0

package/dist/companies-VYY22B6T.js

@@ -0,0 +1,195 @@
+import {
+  csvOrJson,
+  handleLinkedinError
+} from "./chunk-TTHM66TA.js";
+import {
+  TABLE_OUTPUT_FORMATS,
+  outputFormatRefusal,
+  writeAdsJson,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-SWL4AAPP.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-K3TNTBZJ.js";
+import {
+  linkedinCompaniesRequestSchema
+} from "./chunk-DAO63OOP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-WTJSMYY2.js";
+import {
+  apiPost
+} from "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import {
+  getEnv
+} from "./chunk-EE72SSB2.js";
+import "./chunk-WNSE7N75.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-VYY22B6T.js.map

package/dist/complete-5I32XM7P.js

@@ -0,0 +1,81 @@
+import {
+  failApi,
+  failValidation,
+  isTempId,
+  writeOk
+} from "./chunk-GBFL4TD2.js";
+import {
+  ACTION_COMPLETE_NOTE_MIN
+} from "./chunk-DAO63OOP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-WTJSMYY2.js";
+import {
+  apiPost,
+  validateConvexId
+} from "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import {
+  requireChatId
+} from "./chunk-EE72SSB2.js";
+import {
+  registerSchema
+} from "./chunk-WNSE7N75.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-5I32XM7P.js.map

package/dist/connect-EUFFQQ7O.js

@@ -0,0 +1,42 @@
+import {
+  attachDestination,
+  attachSettings,
+  attachStep,
+  connectCommand,
+  copyDestination,
+  destinationRefusal,
+  restatableTargets,
+  sealRequestFor,
+  targetsFor,
+  unpickedSteps,
+  unwiredHubspotForms,
+  unwiredSideEffects
+} from "./chunk-77ULVP62.js";
+import "./chunk-NLI7C3K2.js";
+import "./chunk-ITNHIZKK.js";
+import "./chunk-GBFL4TD2.js";
+import "./chunk-DAO63OOP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-WTJSMYY2.js";
+import "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import "./chunk-EE72SSB2.js";
+import "./chunk-WNSE7N75.js";
+import "./chunk-YQSBHWOI.js";
+export {
+  attachDestination,
+  attachSettings,
+  attachStep,
+  connectCommand,
+  copyDestination,
+  destinationRefusal,
+  restatableTargets,
+  sealRequestFor,
+  targetsFor,
+  unpickedSteps,
+  unwiredHubspotForms,
+  unwiredSideEffects
+};
+//# sourceMappingURL=connect-EUFFQQ7O.js.map

package/dist/conversation-D6KZHGPP.js

@@ -0,0 +1,93 @@
+import {
+  csvOrJson,
+  daysAgoIso,
+  handleLinkedinError,
+  todayIso
+} from "./chunk-TTHM66TA.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-SWL4AAPP.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-K3TNTBZJ.js";
+import "./chunk-DAO63OOP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-WTJSMYY2.js";
+import {
+  apiPost
+} from "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import "./chunk-EE72SSB2.js";
+import "./chunk-WNSE7N75.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-D6KZHGPP.js.map

package/dist/conversion-writes-ECZBVY7D.js

@@ -0,0 +1,120 @@
+import {
+  compact,
+  lowerArg,
+  schemaArgs,
+  stageChatgptOp
+} from "./chunk-AQM4JH62.js";
+import {
+  CHATGPT_ADS_REFERENCE,
+  runChatgptRead
+} from "./chunk-IG627WWY.js";
+import "./chunk-SWL4AAPP.js";
+import {
+  apiGet
+} from "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import "./chunk-EE72SSB2.js";
+import {
+  registerSchema
+} from "./chunk-WNSE7N75.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/conversion-writes.ts
+import { defineCommand } from "citty";
+var REFERENCE = CHATGPT_ADS_REFERENCE.conversions;
+var CREATE_ARGS = {
+  name: {
+    type: "string",
+    description: "What the conversion is called in reports, e.g. Quote requests",
+    required: true
+  },
+  event: {
+    type: "string",
+    description: "lead_created, appointment_scheduled, registration_completed, order_created, checkout_started, items_added, contents_viewed, page_viewed, subscription_created, trial_started \u2014 or custom",
+    required: true
+  },
+  "custom-name": {
+    type: "string",
+    description: "With --event custom: the exact event name the site sends (1\u201364 letters, digits, _ or -)"
+  },
+  pixel: {
+    type: "string",
+    description: "The pixel it counts from \u2014 its Pixel ID, its source id, or a pixel staged in this chat (chatgpt_temp_\u2026). Default: the account's only pixel"
+  }
+};
+function conversionCreateOp(args) {
+  return {
+    kind: "conversionEvent.create",
+    payload: compact({
+      name: args.name,
+      eventType: lowerArg(args.event),
+      customEventName: args["custom-name"],
+      sourceId: args.pixel
+    })
+  };
+}
+registerSchema({
+  command: "ads.chatgpt.conversions.create",
+  description: "Stage a conversion \u2014 one event from the account's pixel that ChatGPT Ads counts, standard or custom. Applies when the chat is published; it can never be deleted, and only ChatGPT Ads Manager can rename it. A custom one only measures; a conversions campaign optimises for a standard one.",
+  args: schemaArgs(CREATE_ARGS)
+});
+var conversionsCreateCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: `Stage a conversion (applies when the chat is published).
+
+Examples:
+  baker ads chatgpt conversions create --name "Leads" --event lead_created
+  baker ads chatgpt conversions create --name "Quote requests" --event custom --custom-name quote_requested`
+  },
+  args: CREATE_ARGS,
+  run: async ({ args }) => {
+    await stageChatgptOp(conversionCreateOp(args), REFERENCE, (staged) => [
+      `Measure it on a campaign with --conversion-event-ids ${staged.ref} (campaigns create or update).`,
+      "After the publish, trigger the event on the live page and confirm it arrives with `baker ads chatgpt conversions events`."
+    ]);
+  }
+});
+var EVENTS_ARGS = {
+  pixel: { type: "string", description: "Pixel ID or source id (default: the account's only pixel)" }
+};
+registerSchema({
+  command: "ads.chatgpt.conversions.events",
+  description: "The events a pixel delivered to ChatGPT Ads in about the last 15 minutes \u2014 type, custom name, browser or server, when. Proof the site sends them, not attribution: trigger one on the page first.",
+  args: schemaArgs(EVENTS_ARGS)
+});
+function eventHints(recent) {
+  if (recent.events.length === 0) {
+    return [
+      "Nothing arrived in the last 15 minutes. Trigger the event on the live page (load it, submit the form), then read again \u2014 the stream keeps only about 15 minutes."
+    ];
+  }
+  return [];
+}
+var conversionsEventsCommand = defineCommand({
+  meta: {
+    name: "events",
+    description: `What the pixel sent in about the last 15 minutes \u2014 check a conversion really arrives.
+
+Examples:
+  baker ads chatgpt conversions events
+  baker ads chatgpt conversions events --pixel 2bow4Axzw2JK7H44AfsLeY`
+  },
+  args: EVENTS_ARGS,
+  run: async ({ args }) => {
+    await runChatgptRead(
+      REFERENCE,
+      () => apiGet(
+        "/api/ads/chatgpt/conversions/events",
+        typeof args.pixel === "string" && args.pixel ? { pixel: args.pixel } : void 0
+      ),
+      eventHints
+    );
+  }
+});
+export {
+  conversionCreateOp,
+  conversionsCreateCommand,
+  conversionsEventsCommand
+};
+//# sourceMappingURL=conversion-writes-ECZBVY7D.js.map

package/dist/conversions-5QCSCRLI.js

@@ -0,0 +1,76 @@
+import {
+  CHATGPT_ADS_REFERENCE,
+  runChatgptListRead
+} from "./chunk-IG627WWY.js";
+import "./chunk-SWL4AAPP.js";
+import "./chunk-XDZVBX6L.js";
+import "./chunk-N5O67GK5.js";
+import "./chunk-EE72SSB2.js";
+import {
+  registerSchema
+} from "./chunk-WNSE7N75.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/conversions.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.chatgpt.conversions",
+  description: "What the connected ChatGPT Ads account measures: its pixels (with the pixel id a landing page installs) and its conversion events (standard type, attribution window, sources, the campaigns using each).",
+  args: {}
+});
+function conversionHints(conversions) {
+  const hints = [];
+  if (conversions.pixels === null) {
+    hints.push(
+      "ChatGPT Ads does not let this account list its pixels through the API. The pixel id is in Ads Manager \u2192 Conversions."
+    );
+  } else if (conversions.pixels.length === 0) {
+    hints.push(
+      "No pixel yet: without one on the landing pages, ChatGPT Ads counts no conversions and cannot optimise for them."
+    );
+  }
+  if (conversions.events.filter((event) => !event.archived).length === 0) {
+    hints.push(
+      "No conversion is defined, so no campaign measures or optimises for one. Stage one with `baker ads chatgpt conversions create`."
+    );
+  }
+  return hints;
+}
+var conversionsListCommand = defineCommand({
+  meta: { name: "list", description: "Pixels and conversions. Example: baker ads chatgpt conversions" },
+  args: {},
+  run: async () => {
+    await runChatgptListRead(
+      CHATGPT_ADS_REFERENCE.conversions,
+      "/api/ads/chatgpt/conversions",
+      void 0,
+      conversionHints
+    );
+  }
+});
+var conversionsCommand = defineCommand({
+  meta: {
+    name: "conversions",
+    description: `What a ChatGPT Ads account measures \u2014 its pixels and conversions \u2014 define a new conversion, and check the pixel's events arrive.
+
+Examples:
+  baker ads chatgpt conversions
+  baker ads chatgpt conversions create --name "Quote requests" --event custom --custom-name quote_requested
+  baker ads chatgpt conversions events
+  baker ads chatgpt conversions report --ids cmpn_123 --days 30   \u2014 click-through and view-through`
+  },
+  subCommands: {
+    list: conversionsListCommand,
+    create: () => import("./conversion-writes-ECZBVY7D.js").then((m) => m.conversionsCreateCommand),
+    events: () => import("./conversion-writes-ECZBVY7D.js").then((m) => m.conversionsEventsCommand),
+    report: () => import("./conversion-report-REOHVLCI.js").then((m) => m.conversionsReportCommand)
+  },
+  // A parent must never declare `run`: citty falls through to it after the matched subcommand.
+  args: {},
+  default: "list"
+});
+export {
+  conversionHints,
+  conversionsCommand
+};
+//# sourceMappingURL=conversions-5QCSCRLI.js.map