@koda-sl/baker-cli 0.307.0-dev.5c40193fb → 0.307.0-dev.ce3b0e7c2

package/dist/cli.js

@@ -4816,6 +4816,8 @@ var chatChangeTypeSchema = z13.enum([
   "conversion-sends",
   // The company's sources: a HubSpot event made or changed. Staged, applied at Publish.
   "event-sources",
+  // What the company counts as a conversion, when an agent changed it. Staged, applied at Publish.
+  "conversions",
   // An A/B test between a landing and its alternative. Staged, not immediate.
   "experiment",
   "briefs"
@@ -14950,7 +14952,9 @@ var analyticsConversionRowSchema = z30.object({
    * The doors its events came in by in the window, in
    * {@link ANALYTICS_EVENT_DOORS} order. Empty when it has not fired.
    */
-  doors: z30.array(z30.enum(ANALYTICS_EVENT_DOORS)).default([])
+  doors: z30.array(z30.enum(ANALYTICS_EVENT_DOORS)).default([]),
+  /** Proposed in this chat: counted from when it is published, so every report reads it as nothing until then. */
+  staged: z30.boolean().optional()
 });
 var analyticsEventCatalogRowSchema = z30.object({
   /** `form:…` | `submit:…` | `page:…` | `exit:…` — parse with `parseEventKey`. */
@@ -15558,14 +15562,24 @@ var analyticsConversionsRequestSchema = z30.object({
 var analyticsConversionsResponseSchema = z30.object({
   ok: z30.literal(true),
   data: z30.object({
+    /**
+     * What the company counts — inside a chat, with this chat's proposal on
+     * top: `staged` marks a definition that applies when the chat is published.
+     */
     definitions: z30.array(
       z30.object({
         eventKey: z30.string(),
         name: z30.string(),
         countMode: z30.string(),
-        updatedAt: z30.number()
+        updatedAt: z30.number(),
+        staged: z30.boolean().optional()
       })
-    )
+    ),
+    /** This chat's proposal, when it has one: counted from Publish, and gone if the chat is discarded. */
+    staged: z30.object({
+      set: z30.array(z30.object({ eventKey: z30.string(), name: z30.string() })),
+      remove: z30.array(z30.string())
+    }).optional()
   }),
   hints: z30.array(z30.string()).optional()
 });
@@ -23163,6 +23177,20 @@ var lookalikeSpecSchema = z31.object({
   ratio: z31.number().min(0.01).max(0.2).optional(),
   country: z31.string().length(2).optional()
 });
+function valuesOfKey(node, key) {
+  if (Array.isArray(node)) return node.flatMap((entry) => valuesOfKey(entry, key));
+  if (!node || typeof node !== "object") return [];
+  const record = node;
+  return [
+    ...key in record ? [record[key]] : [],
+    ...Object.values(record).flatMap((value) => valuesOfKey(value, key))
+  ];
+}
+function mixedEventSourceTypes(rule) {
+  const types = valuesOfKey(rule, "event_sources").flatMap((sources) => Array.isArray(sources) ? sources : []).map((source) => source?.type).filter((type) => typeof type === "string");
+  const distinct = [...new Set(types)].sort();
+  return distinct.length > 1 ? distinct : [];
+}
 var customAudienceCreateSchema = z31.object({
   name: z31.string().min(1).max(META_LIMITS.audience.nameMax),
   subtype: z31.enum(CUSTOM_AUDIENCE_SUBTYPES),
@@ -23179,6 +23207,21 @@ var customAudienceCreateSchema = z31.object({
   if ((p.subtype === "WEBSITE" || p.subtype === "ENGAGEMENT") && !p.rule) {
     ctx.addIssue({ code: "custom", path: ["rule"], message: `${p.subtype} audiences need a rule (use --file)` });
   }
+  if (p.rule && p.retention_days !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["retention_days"],
+      message: "a rule carries its own window in retention_seconds, so drop retention_days \u2014 Meta takes it only on a customer-file audience, and sending both leaves the review showing a window the audience will not have"
+    });
+  }
+  const mixed = mixedEventSourceTypes(p.rule);
+  if (mixed.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["rule"],
+      message: `one audience covers one kind of source, but this rule mixes ${mixed.join(" and ")} \u2014 split it into one audience per source`
+    });
+  }
 });
 var customAudienceUpdateSchema = z31.object({
   name: z31.string().min(1).max(META_LIMITS.audience.nameMax).optional(),
@@ -23919,6 +23962,7 @@ var audiencesCreateCommand2 = defineCommand57({
     name: "create",
     description: `Stage a new custom audience shell. ${STAGED_NOTE2}
 LOOKALIKE/WEBSITE/ENGAGEMENT specifics go via --file (lookalike_spec / rule). Member-list upload is not staged in v1.
+A WEBSITE/ENGAGEMENT rule carries its own window in retention_seconds, so --retention-days is refused next to one, and one audience covers one kind of event source (a Page and an Instagram profile are two audiences).
 Example: baker ads meta audiences create --name "Site visitors 30d" --subtype WEBSITE --file rule.json`
   },
   args: {
@@ -23926,7 +23970,10 @@ Example: baker ads meta audiences create --name "Site visitors 30d" --subtype WE
     name: { type: "string", description: "Audience name" },
     subtype: { type: "string", description: "CUSTOM|WEBSITE|ENGAGEMENT|LOOKALIKE" },
     description: { type: "string", description: "Description" },
-    "retention-days": { type: "string", description: "Retention window in days" },
+    "retention-days": {
+      type: "string",
+      description: "Retention window in days \u2014 customer-file audiences only; a rule carries its own retention_seconds"
+    },
     file: { type: "string", description: "JSON file with lookalike_spec / rule / full payload" }
   },
   run: async ({ args: args4 }) => {
@@ -29245,6 +29292,14 @@ function namingHints(definitions) {
     `Names in use here: ${names.join(", ")}. Reuse one EXACTLY when another Form produces the same outcome \u2014 that is what makes them one number \u2014 and use \`--rename "<old>" --to "<existing>"\` to merge two that should always have been one.`
   ];
 }
+function stagedHints(definitions) {
+  const staged = definitions.filter((row) => row.staged === true);
+  if (staged.length === 0) return [];
+  return [
+    `Staged on this chat, not counted yet: ${staged.map((row) => `"${row.name}"`).join(", ")}. The person sees ${staged.length === 1 ? "it" : "them"} under Conversions in the chat's changes, and ${staged.length === 1 ? "it counts" : "they count"} \u2014 history included \u2014 from when they publish the chat; discarding the chat drops ${staged.length === 1 ? "it" : "them"}. Tell them that, not that it is already counted.`,
+    'When you talk to the person, call each event by its name ("Appointment scheduled"), never its key (`page:Appointment scheduled`): the key is how Baker spells it internally, and the `page:` part means nothing to them.'
+  ];
+}
 
 // src/commands/analytics/conversionList.ts
 function mergeStoredWithCounts(stored, reported) {
@@ -29270,7 +29325,8 @@ function mergeStoredWithCounts(stored, reported) {
       conversions: counted?.conversions ?? 0,
       convertingVisits: counted?.convertingVisits ?? 0,
       lastSeen: counted?.lastSeen ?? null,
-      doors: counted?.doors ?? []
+      doors: counted?.doors ?? [],
+      ...rows.some((row) => row.staged === true) ? { staged: true } : {}
     };
   }).sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -31397,6 +31453,7 @@ function conversionsEnvelope(args4, definitions, candidates) {
   const hints2 = [
     ...flow ? flowConversionHints(flow.slug, flow.endings, flow.noConversionReason) : [],
     ...flowCoverageHints(coverage),
+    ...stagedHints(definitions),
     ...page.hints,
     ...namingHints(definitions)
   ];
@@ -31415,7 +31472,7 @@ var conversionsCommand3 = (() => {
   const args4 = {
     event: {
       type: "string",
-      description: "The event to start counting, from the `candidates` or `--flow` list: form:<form>:<step>:<trigger>, submit:<form>, page:<name>, or exit:<host>. Requires --name. REPEATABLE \u2014 pass it several times with one --name to count all of them as that single outcome, which is the whole point of the name. Applies immediately and scores the WHOLE history, not just from now on, so counting the right event today also corrects last month's reports. An event a client's system sends (the API, HubSpot) counts here too: it is credited to the LAST LANDING its person viewed, up to 90 days before, so a deal won weeks later is that landing's conversion. A person who never saw a landing is not counted at all. Such an event is usually also a funnel step (`baker funnel`) and a send (`baker analytics sends`)",
+      description: "The event to start counting, from the `candidates` or `--flow` list: form:<form>:<step>:<trigger>, submit:<form>, page:<name>, or exit:<host>. Requires --name. REPEATABLE \u2014 pass it several times with one --name to count all of them as that single outcome, which is the whole point of the name. Inside a chat it is STAGED: the chat lists it under Conversions and it counts from when the chat is published \u2014 then it scores the WHOLE history, not just from then on, so counting the right event also corrects last month's reports. An event a client's system sends (the API, HubSpot) counts here too: it is credited to the LAST LANDING its person viewed, up to 90 days before, so a deal won weeks later is that landing's conversion. A person who never saw a landing is not counted at all. Such an event is usually also a funnel step (`baker funnel`) and a send (`baker analytics sends`)",
       required: false
     },
     name: {
@@ -31472,7 +31529,7 @@ var conversionsCommand3 = (() => {
   return defineCommand97({
     meta: {
       name: "conversions",
-      description: "What this company counts as a conversion ON ITS PAGES \u2014 a browser event, once per visit: the numerator of every conversion rate on Measure, and nothing more. An event one of the client's systems sends (a deal won in HubSpot, an order the server posts) is not a page conversion: it is a step on the funnel (`baker funnel`) and can be sent to an ad platform (`baker analytics sends`). Run with no flags first: an empty `definitions` list means every conversion number in every other report is zero \u2014 not because nobody converted, but because nothing is marked as converting, and Baker never guesses. Add `--candidates` to see everything these pages actually do (every Form step, every data-baker-* event, every outbound destination) with counts and whether it is already counted; that list is where an event key comes from, so never invent one. Then `--event <key> --name 'Booked a call'` to count it. It applies IMMEDIATELY and retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers the moment you name the right event. Nothing here is staged and publishing is not involved. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
+      description: "What this company counts as a conversion \u2014 the numerator of every conversion rate on Measure. A page event (a Form ending, a data-baker-* event) and an event one of the client's systems sends (a HubSpot event made with `baker analytics sources --create-hubspot`, an order the server posts) both count; a system's event is credited to the last landing its person viewed. A HubSpot event is `page:<its name>` here \u2014 `--event 'page:Deal won' --name 'Deal won'`. Run with no flags first: an empty `definitions` list means every conversion number in every other report is zero \u2014 not because nobody converted, but because nothing is marked as converting, and Baker never guesses. Add `--candidates` to see everything these pages actually do (every Form step, every data-baker-* event, every outbound destination) with counts and whether it is already counted; that list is where an event key comes from, so never invent one. Then `--event <key> --name 'Booked a call'` to count it. Inside a chat a change is STAGED: the person sees it under Conversions in the chat's changes and it applies when they publish, retroactively \u2014 the whole history is rescored, so a company that has been running for a month gets a month of correct numbers. A read shows a proposal marked `staged`. Call an event by its name when you talk to the person, never by its key. Two events given the SAME --name are one row and one number. `--remove <key>` stops counting one. `--flow <slug>` answers the other direction \u2014 what one Form counts, with every ending it has already spelled as an event key, read from the Form itself so it works before a single visitor has seen it. Run it whenever you create or edit a Form: a Form nobody named an outcome for is published converting nobody, and no report says so."
     },
     args: args4,
     run: async ({ args: raw }) => {
@@ -31503,12 +31560,8 @@ var conversionsCommand3 = (() => {
     }
   });
 })();
-var SYSTEM_EVENTS_HINT = "Events your systems send are not listed: a system's event is a funnel step (`baker funnel`) and is sent to an ad platform with `baker analytics sends`, never counted as a page conversion.";
 function pageCandidates(definitions, catalogue, listing) {
-  const candidates = catalogue.filter((row) => row.origin !== "systems");
-  const hints2 = conversionHints(definitions, candidates, listing);
-  if (listing && candidates.length < catalogue.length) hints2.push(SYSTEM_EVENTS_HINT);
-  return { candidates, hints: hints2 };
+  return { candidates: [...catalogue], hints: conversionHints(definitions, catalogue, listing) };
 }
 function parsePairs(raw) {
   if (raw === void 0) return void 0;
@@ -45255,12 +45308,37 @@ function splitParts(raw) {
   }
   return parts.map((part) => part.trim()).filter((part) => part.length > 0);
 }
+var TRANSFORM_REFUSAL = "A value cannot run code. Map the field as it is (firstname=full_name), or split it in the step with a codeExecution that exposes first_name and last_name and map code:first_name.";
+var METHOD_CALL = /\.\s*[A-Za-z_$][\w$]*\s*\(/;
+var TRAILING_INDEX = /\[[^\]]*\]$/;
+function mentionPart(inner) {
+  if (inner.startsWith("tracking.")) return { kind: "tracking", name: inner.slice("tracking.".length) };
+  if (inner.startsWith("global.")) return { kind: "global", name: inner.slice("global.".length) };
+  return referencePart(inner);
+}
+function referencePart(ref) {
+  return /\.codeExecution\.[^.]+$/.test(ref) ? { kind: "code", ref } : { kind: "field", ref };
+}
 function parsePart(part) {
   if (part.startsWith('"') && part.endsWith('"') && part.length >= 2) {
     return { kind: "text", text: part.slice(1, -1) };
   }
+  if (METHOD_CALL.test(part) || TRAILING_INDEX.test(part)) {
+    throw new MappingError(TRANSFORM_REFUSAL);
+  }
+  if (part.startsWith("{{")) {
+    const close = part.indexOf("}}");
+    if (close < 0) {
+      throw new MappingError(
+        `Unclosed \`{{\` in value \`${part}\`.`,
+        "A mention is written {{<stepId>.customForm.<field>}}."
+      );
+    }
+    if (part.slice(close + 2).trim()) throw new MappingError(TRANSFORM_REFUSAL);
+    return mentionPart(part.slice(2, close).trim());
+  }
   const colon = part.indexOf(":");
-  if (colon <= 0) return { kind: "field", ref: part };
+  if (colon <= 0) return referencePart(part);
   const prefix = part.slice(0, colon);
   const rest = part.slice(colon + 1).trim();
   if (!PREFIXES.includes(prefix)) {
@@ -45318,7 +45396,12 @@ function fieldOwners(tree) {
     ];
   });
 }
-function splitRef(ref) {
+function splitRef(ref, segment) {
+  const marker = `.${segment}.`;
+  const at = ref.lastIndexOf(marker);
+  if (at > 0 && !ref.slice(at + marker.length).includes(".")) {
+    return { step: ref.slice(0, at), name: ref.slice(at + marker.length) };
+  }
   const dot = ref.lastIndexOf(".");
   if (dot <= 0) return { name: ref };
   return { step: ref.slice(0, dot), name: ref.slice(dot + 1) };
@@ -45330,7 +45413,7 @@ function titleize(value) {
   return value.split(/[_-]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 function resolveField(tree, ref) {
-  const { step, name } = splitRef(ref);
+  const { step, name } = splitRef(ref, "customForm");
   const owners = fieldOwners(tree);
   const inventory = owners.map((owner2) => `  ${owner2.name} (${owner2.id}): ${owner2.fields.join(", ") || "(no fields)"}`).join("\n");
   const candidates = owners.filter(
@@ -45373,7 +45456,7 @@ function resolveGlobal(tree, name) {
   return mention(id, id);
 }
 function resolveCode(tree, ref) {
-  const { step, name } = splitRef(ref);
+  const { step, name } = splitRef(ref, "codeExecution");
   const owners = walkNodes(tree).flatMap((node) => {
     const exposed = externalOf(node).codeExecution?.exposedValues ?? [];
     const names = exposed.map((value) => value?.name).filter((value) => typeof value === "string");
@@ -45917,7 +46000,7 @@ function describeDestination(chosen) {
       // two different questions with two different answers, and the type is the
       // one an agent does not know it is being asked until a mapping is refused.
       ...slots.flatMap((slot) => slot.fieldTypes ? [`${slot.slot} field types \u2014 ${slot.fieldTypes}`] : []),
-      'Values (right of the `=`) are the same for every slot: a form field, tracking:<var>, global:<name>, code:<name>, a "literal", or those joined with +.'
+      'Values (right of the `=`) are the same for every slot: a form field, tracking:<var>, global:<name>, code:<name>, a "literal", or those joined with +. A field may also be written as the file stores it, {{<stepId>.customForm.<field>}}. A value cannot run code (no .split(), .slice(), [0]).'
     ]
   });
 }
@@ -59508,7 +59591,7 @@ registerSchema({
     },
     sort: {
       type: "string",
-      description: "Sort: relevance, search_volume, competition, cpc (default: search_volume)",
+      description: "Sort: search_volume, competition, cpc (default: search_volume)",
       required: false
     },
     type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
@@ -59537,7 +59620,7 @@ Examples:
     target: { type: "positional", description: "Domain or URL to analyze", required: true },
     location: { type: "string", description: "Country code or location code (default: us)", required: false },
     language: { type: "string", description: "Language code or name (default: en)", required: false },
-    sort: { type: "string", description: "Sort: relevance, search_volume, competition, cpc", required: false },
+    sort: { type: "string", description: "Sort: search_volume, competition, cpc", required: false },
     type: { type: "string", description: "Filter: paid, organic, all (default: all)", required: false },
     limit: { type: "string", description: "Max results (default: 50, max: 1000)", required: false },
     output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },