@koda-sl/baker-cli 0.550.0 → 0.551.0-dev.ad2740332

package/dist/conversion-upload-command-WCLWA27O.js

@@ -0,0 +1,439 @@
+import {
+  failWriteValidation,
+  requireCustomerId,
+  stageGoogleOps
+} from "./chunk-ICEYCLRU.js";
+import "./chunk-ERSX3MKH.js";
+import "./chunk-3W4IORXH.js";
+import "./chunk-4NZ47VXO.js";
+import "./chunk-D5FY4FAK.js";
+import "./chunk-NGQ5J4FV.js";
+import "./chunk-QALAJNBG.js";
+import "./chunk-YKFGXS26.js";
+import "./chunk-MGWAZXY6.js";
+import "./chunk-VWOKPC3T.js";
+import "./chunk-BGT5ZA4L.js";
+import "./chunk-JF2XP76K.js";
+import "./chunk-SYLPRIFM.js";
+import "./chunk-XBR7TSZN.js";
+import "./chunk-DGUN7FUH.js";
+import "./chunk-NSBNIPIW.js";
+import {
+  CONVERSION_UPLOAD_MAX_ROWS
+} from "./chunk-H4CLWLYF.js";
+import "./chunk-B2OHCWYB.js";
+import "./chunk-SVUFNCOE.js";
+import "./chunk-E54435XT.js";
+import "./chunk-WCIS4FZH.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/google/conversion-upload-command.ts
+import { readFileSync } from "fs";
+import { defineCommand } from "citty";
+
+// src/commands/ads/google/conversion-rows.ts
+var COLUMN_ALIASES = {
+  orderId: ["orderid", "order", "ordernumber", "transactionid", "transaction", "submissionid", "conversionid", "id"],
+  conversionDateTime: [
+    "conversiondatetime",
+    "conversiontime",
+    "conversiondate",
+    "datetime",
+    "date",
+    "time",
+    "timestamp",
+    "occurredat",
+    "createdat"
+  ],
+  gclid: ["gclid"],
+  gbraid: ["gbraid"],
+  wbraid: ["wbraid"],
+  email: ["email", "emailaddress", "useremail", "mail"],
+  phone: ["phone", "phonenumber", "telephone", "mobile", "tel"],
+  value: ["value", "conversionvalue", "amount", "revenue", "price", "total"],
+  currency: ["currency", "currencycode", "conversioncurrency"],
+  conversionCount: ["conversioncount", "quantity", "count", "units"],
+  // Deliberately only the exact spelling: a `Source` or `Channel` column in a CRM export almost
+  // always holds an attribution channel, not one of Google's five event sources, and mapping it
+  // would refuse the whole file on a column an upload has no use for. Unmapped, it is dropped and
+  // named back in the hints, which is what those columns should get.
+  eventSource: ["eventsource"],
+  // Advanced matching. Each maps to one part of Google's address identifier; a row that carries the
+  // four required parts is matched on name + address as well as on whatever else it has.
+  // `name` is left out for the same reason: alone it produces a one-part `address`, and the
+  // contract requires all four parts, so a lone `Name` column would refuse the file.
+  givenName: ["givenname", "firstname", "forename"],
+  familyName: ["familyname", "lastname", "surname"],
+  regionCode: ["regioncode", "country", "countrycode"],
+  postalCode: ["postalcode", "postcode", "zip", "zipcode"],
+  addressLine: ["addressline", "address", "street", "streetaddress", "addressline1"],
+  city: ["city", "town", "locality"],
+  administrativeArea: ["administrativearea", "state", "province", "region"]
+};
+var NUMERIC_KEYS = /* @__PURE__ */ new Set(["value", "conversionCount"]);
+function normalizeColumn(raw) {
+  return raw.trim().toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function payloadKeyForColumn(column) {
+  const normalized = normalizeColumn(column);
+  for (const [key, aliases] of Object.entries(COLUMN_ALIASES)) {
+    if (normalizeColumn(key) === normalized || aliases.includes(normalized)) {
+      return key;
+    }
+  }
+  return void 0;
+}
+var ADDRESS_KEYS = [
+  "givenName",
+  "familyName",
+  "regionCode",
+  "postalCode",
+  "addressLine",
+  "city",
+  "administrativeArea"
+];
+function nestAddress(row) {
+  const address = {};
+  for (const key of ADDRESS_KEYS) {
+    if (row[key] !== void 0) {
+      address[key] = row[key];
+      delete row[key];
+    }
+  }
+  return Object.keys(address).length > 0 ? { ...row, address } : row;
+}
+function toRow(record) {
+  const row = {};
+  const ignored = [];
+  for (const [column, raw] of Object.entries(record)) {
+    const key = payloadKeyForColumn(column);
+    if (!key) {
+      if (column.trim() !== "") {
+        ignored.push(column.trim());
+      }
+      continue;
+    }
+    const value = cellValue(key, raw);
+    if (value !== void 0) {
+      row[key] = value;
+    }
+  }
+  return { row: nestAddress(row), ignored };
+}
+function cellValue(key, raw) {
+  const value = typeof raw === "string" ? raw.trim() : raw;
+  if (value === "" || value === null || value === void 0) {
+    return void 0;
+  }
+  if (!NUMERIC_KEYS.has(key)) {
+    return typeof value === "number" ? String(value) : value;
+  }
+  const numeric = typeof value === "number" ? value : Number(String(value).replace(/[^\d.-]/g, ""));
+  return Number.isFinite(numeric) ? numeric : value;
+}
+var CSV_SEPARATORS = /* @__PURE__ */ new Set([",", ";", "	"]);
+function splitCsvLine(line) {
+  const fields = [];
+  let current = "";
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quoted && char !== '"') {
+      current += char;
+    } else if (quoted) {
+      quoted = line[i + 1] === '"';
+      if (quoted) {
+        current += '"';
+        i += 1;
+      }
+    } else if (char === '"') {
+      quoted = true;
+    } else if (CSV_SEPARATORS.has(char ?? "")) {
+      fields.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  fields.push(current);
+  return fields.map((field) => field.trim());
+}
+function parseCsv(text) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const header = lines.shift();
+  if (!header) {
+    return { ok: false, error: "the file is empty" };
+  }
+  const columns = splitCsvLine(header);
+  if (!columns.some((column) => payloadKeyForColumn(column))) {
+    return {
+      ok: false,
+      error: `no column in "${columns.join(", ")}" is a conversion field \u2014 the file needs at least an order id, a date and something to match on (gclid / email / phone)`
+    };
+  }
+  const rows = [];
+  const ignored = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    const fields = splitCsvLine(line);
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = fields[index] ?? "";
+    });
+    const parsed = toRow(record);
+    for (const column of parsed.ignored) {
+      ignored.add(column);
+    }
+    rows.push(parsed.row);
+  }
+  return { ok: true, rows, ignoredColumns: [...ignored] };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordsOfJson(parsed) {
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+  if (!isRecord(parsed)) {
+    return void 0;
+  }
+  for (const key of ["conversions", "rows", "data", "results"]) {
+    const value = parsed[key];
+    if (Array.isArray(value)) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function parseJsonRecords(records) {
+  const rows = [];
+  const ignored = /* @__PURE__ */ new Set();
+  for (const [index, record] of records.entries()) {
+    if (!isRecord(record)) {
+      return { ok: false, error: `conversion ${index + 1} is not an object` };
+    }
+    const parsed = toRow(record);
+    for (const column of parsed.ignored) {
+      ignored.add(column);
+    }
+    rows.push(parsed.row);
+  }
+  return { ok: true, rows, ignoredColumns: [...ignored] };
+}
+function parseJsonText(trimmed) {
+  const lines = trimmed.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  if (lines.length > 1 && lines.every((line) => line.trim().startsWith("{"))) {
+    const records2 = [];
+    for (const [index, line] of lines.entries()) {
+      try {
+        records2.push(JSON.parse(line));
+      } catch {
+        return { ok: false, error: `line ${index + 1} is not valid JSON` };
+      }
+    }
+    return parseJsonRecords(records2);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    return { ok: false, error: `not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const records = recordsOfJson(parsed);
+  if (!records) {
+    return { ok: false, error: "expected a JSON array of conversions, or an object with a `conversions` array" };
+  }
+  return parseJsonRecords(records);
+}
+function parseConversionRowsText(text) {
+  const trimmed = text.trim();
+  if (trimmed === "") {
+    return { ok: false, error: "the file is empty" };
+  }
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    return parseJsonText(trimmed);
+  }
+  return parseCsv(trimmed);
+}
+function chunkConversionRows(rows, size) {
+  const chunks = [];
+  for (let i = 0; i < rows.length; i += size) {
+    chunks.push(rows.slice(i, i + size));
+  }
+  return chunks;
+}
+
+// src/commands/ads/google/conversion-upload-command.ts
+var UPLOAD_HINTS = [
+  "Nothing has been uploaded yet \u2014 the conversions are staged and go to Google when this chat is published.",
+  "Reuse each conversion's ORIGINAL order id (the Form submission id, the order number the site issued). Google recognises an upload it already holds by that id, which is what makes a re-send a correction instead of a second conversion \u2014 a made-up id cannot be taken back.",
+  "Say plainly what was uploaded and what it was for. A conversion upload changes what automated bidding optimises toward, so the client should hear the count and the action, not just that it worked."
+];
+function ignoredColumnHints(columns) {
+  if (columns.length === 0) {
+    return [];
+  }
+  return [
+    `Ignored ${columns.length} column(s) that are not part of a conversion: ${columns.join(", ")}. A conversion carries an order id, a date, and something to match on: a click id (gclid / gbraid / wbraid), an email, a phone, or all four of givenName + familyName + country + postalCode. Optionally a value + currency, conversionCount, and eventSource (WEB / APP / IN_STORE / PHONE / OTHER). A column named just \`Name\` is ignored on purpose \u2014 Google needs the first and last name separately, so split it before re-running.`
+  ];
+}
+function readRowsFile(path) {
+  const inline = path.trimStart().startsWith("[") || path.trimStart().startsWith("{");
+  let text;
+  try {
+    text = inline ? path : readFileSync(path, "utf8");
+  } catch (err) {
+    failWriteValidation(`could not read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const parsed = parseConversionRowsText(text);
+  if (!parsed.ok) {
+    failWriteValidation(`${inline ? "the conversions passed inline" : path}: ${parsed.error}`);
+  }
+  return { rows: parsed.rows, ignoredColumns: parsed.ignoredColumns };
+}
+function rowFromFlags(args) {
+  const entries = [
+    ["orderId", args["order-id"]],
+    ["conversionDateTime", args.date],
+    ["gclid", args.gclid],
+    ["gbraid", args.gbraid],
+    ["wbraid", args.wbraid],
+    ["email", args.email],
+    ["phone", args.phone],
+    ["currency", args.currency],
+    ["eventSource", args["event-source"]],
+    ["givenName", args["given-name"]],
+    ["familyName", args["family-name"]],
+    ["regionCode", args.country],
+    ["postalCode", args["postal-code"]]
+  ];
+  const row = {};
+  for (const [key, value] of entries) {
+    if (typeof value === "string" && value.trim() !== "") {
+      row[key] = value.trim();
+    }
+  }
+  nestAddressFlags(row);
+  readNumericFlags(args, row);
+  return Object.keys(row).length > 0 ? row : void 0;
+}
+function nestAddressFlags(row) {
+  const address = {};
+  for (const key of ["givenName", "familyName", "regionCode", "postalCode"]) {
+    if (row[key] !== void 0) {
+      address[key] = row[key];
+      delete row[key];
+    }
+  }
+  if (Object.keys(address).length > 0) {
+    row.address = address;
+  }
+}
+function readNumericFlags(args, row) {
+  if (args["conversion-count"] !== void 0 && args["conversion-count"] !== "") {
+    const count = Number(args["conversion-count"]);
+    if (!Number.isInteger(count) || count < 1) {
+      failWriteValidation("--conversion-count must be a whole number of conversions, e.g. 3");
+    }
+    row.conversionCount = count;
+  }
+  if (args.value !== void 0 && args.value !== "") {
+    const numeric = Number(args.value);
+    if (!Number.isFinite(numeric)) {
+      failWriteValidation("--value must be a number in major currency units, e.g. 49.90");
+    }
+    row.value = numeric;
+  }
+}
+var conversionsUploadCommand = defineCommand({
+  meta: {
+    name: "upload",
+    description: "Upload conversions Google never received \u2014 a backfill for a period where the tracking was broken. Start here: `conversions upload --customer-id 1234567890 --conversion-action 987654321 --file missing.csv`, where the file carries one conversion per row with an order id, a date, and a gclid and/or an email. Nothing reaches Google until the chat is published. Reuse each conversion's ORIGINAL order id so a re-send is treated as a correction rather than a second conversion. Read the account's actions first with: baker ads google query \"SELECT conversion_action.id, conversion_action.name, conversion_action.status FROM conversion_action\""
+  },
+  args: {
+    "customer-id": { type: "string", description: "10-digit Google Ads customer id" },
+    "conversion-action": {
+      type: "string",
+      description: "The conversion action to record these against \u2014 its numeric id or resource name"
+    },
+    file: {
+      type: "string",
+      description: "The conversions: a path to a CSV / JSON / JSONL file, or the JSON array written inline. Columns: orderId, conversionDateTime, gclid | gbraid | wbraid, email, phone, givenName + familyName + country + postalCode (advanced matching), value, currency, conversionCount, eventSource"
+    },
+    "order-id": { type: "string", description: "Single conversion: its original order / submission id" },
+    date: {
+      type: "string",
+      description: "Single conversion: when it happened, as an ISO-8601 instant WITH a timezone (2026-08-01T10:00:00Z or 2026-08-01T12:00:00+02:00)"
+    },
+    gclid: { type: "string", description: "Single conversion: the Google click id it came from" },
+    gbraid: { type: "string", description: "Single conversion: the gbraid click id (app-to-web)" },
+    wbraid: { type: "string", description: "Single conversion: the wbraid click id (web-to-app)" },
+    email: { type: "string", description: "Single conversion: the customer's email \u2014 hashed before it is stored" },
+    phone: {
+      type: "string",
+      description: "Single conversion: the customer's phone in E.164 \u2014 hashed before it is stored"
+    },
+    value: { type: "string", description: "Single conversion: what it was worth, in major currency units" },
+    currency: { type: "string", description: "Single conversion: the value's 3-letter currency code, e.g. EUR" },
+    "conversion-count": {
+      type: "string",
+      description: "Single conversion: how many conversions this row stands for. Only read on an EVERY-counting conversion action; defaults to 1"
+    },
+    "event-source": {
+      type: "string",
+      description: "Single conversion: where it happened \u2014 WEB (default), APP, IN_STORE, PHONE or OTHER"
+    },
+    "given-name": {
+      type: "string",
+      description: "Single conversion: the customer's first name \u2014 advanced matching, hashed before it is stored"
+    },
+    "family-name": {
+      type: "string",
+      description: "Single conversion: the customer's last name \u2014 advanced matching, hashed before it is stored"
+    },
+    country: {
+      type: "string",
+      description: "Single conversion: the customer's 2-letter country code, e.g. ES \u2014 required with a name/address match"
+    },
+    "postal-code": {
+      type: "string",
+      description: "Single conversion: the customer's postcode \u2014 required with a name/address match"
+    }
+  },
+  run: async ({ args }) => {
+    const customerId = requireCustomerId(args);
+    const conversionAction = typeof args["conversion-action"] === "string" ? args["conversion-action"].trim() : "";
+    if (conversionAction === "") {
+      failWriteValidation(
+        '--conversion-action is required: the action these conversions are recorded against. List them with: baker ads google query "SELECT conversion_action.id, conversion_action.name, conversion_action.status FROM conversion_action"'
+      );
+    }
+    const fromFile = typeof args.file === "string" && args.file.length > 0 ? readRowsFile(args.file) : void 0;
+    const fromFlags = rowFromFlags(args);
+    if (fromFile && fromFlags) {
+      failWriteValidation(
+        "pass either --file (a list of conversions) or the single-conversion flags, not both \u2014 otherwise it is ambiguous which row the flags belong to"
+      );
+    }
+    const rows = fromFile?.rows ?? (fromFlags ? [fromFlags] : []);
+    if (rows.length === 0) {
+      failWriteValidation(
+        "no conversions to upload \u2014 pass --file with the conversions, or describe one with --order-id, --date and a --gclid / --email"
+      );
+    }
+    const chunks = chunkConversionRows(rows, CONVERSION_UPLOAD_MAX_ROWS);
+    const ops = chunks.map((conversions) => ({
+      kind: "google.conversion.upload",
+      customerId,
+      payload: { conversionAction, conversions }
+    }));
+    const chunkHint = chunks.length > 1 ? [
+      `${rows.length} conversions staged as ${chunks.length} uploads of up to ${CONVERSION_UPLOAD_MAX_ROWS} each. They publish independently \u2014 report the result of all ${chunks.length}, not just the first.`
+    ] : [];
+    await stageGoogleOps(ops, [...chunkHint, ...ignoredColumnHints(fromFile?.ignoredColumns ?? []), ...UPLOAD_HINTS]);
+  }
+});
+export {
+  conversionsUploadCommand
+};
+//# sourceMappingURL=conversion-upload-command-WCLWA27O.js.map

package/dist/conversion-writes-XIQEIDPS.js

@@ -0,0 +1,122 @@
+import {
+  compact,
+  lowerArg,
+  schemaArgs,
+  stageChatgptOp
+} from "./chunk-64ALJ6TJ.js";
+import {
+  CHATGPT_ADS_REFERENCE,
+  runChatgptRead
+} from "./chunk-L7AJMZ6Z.js";
+import "./chunk-MGWAZXY6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import {
+  apiGet
+} from "./chunk-B2OHCWYB.js";
+import "./chunk-SVUFNCOE.js";
+import "./chunk-E54435XT.js";
+import {
+  registerSchema
+} from "./chunk-WCIS4FZH.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-XIQEIDPS.js.map