@koda-sl/baker-cli 0.311.0-dev.64b243bc4 → 0.312.0

package/README.md

@@ -886,8 +886,17 @@ baker ads meta audiences --account-id act_123
 # "Is the pixel firing?"
 baker ads meta pixels --account-id act_123
 baker ads meta pixels --pixel-id 9988 --stats --days 7
+
+# "Why isn't it using MY conversions?"
+baker ads meta custom-conversions --account-id act_123          # id, event category, pixel, and the rule as a phrase
+baker ads meta custom-conversions --account-id act_123 --full   # raw rule JSON, retention, timestamps
 ```
 
+**Custom Conversions** — a marketer's own conversion (a pixel event narrowed by a rule, e.g. "PageView on /gracias"), which is what "my conversions" almost always means. To optimize an ad set toward one, pass `--custom-conversion-id <id>` and nothing else: Baker reads the conversion off Meta at stage time and fills its pixel, event category and rule, the same four fields Ads Manager stores. Staging refuses an archived or unavailable conversion, one not built on a pixel, and one belonging to another ad account. Deleting one — in Events Manager or over the API — archives it: it leaves the panel but stays readable on the account, so the listing still shows it flagged `archived`.
+
+`custom-conversions create` stages a new one (`--name`, `--pixel-id`, `--custom-event-type`, plus `--url-contains "/gracias"` or `--rule-file`). A rule is a tree of `and`/`or` over `{"<field>":{"<operator>":<value>}}` leaves, where the field is `URL`, `event`, `referrer` or any event parameter the pixel sends (`value`, `content_category`, or your own), so `--url-contains` is only the single-URL shortcut and `--rule-file` reaches the rest. Meta accepts an unmatchable rule and reports success, so staging refuses unknown operators, bare values, empty branches and two conditions written side by side where `and` was meant, before the op is staged. A case-sensitive `contains` is a real operator and gets through — on a URL always write `i_contains`. It is create-only, because Meta's edge offers neither update nor a delete that removes — which is also why staging refuses a create whose pixel, event category and rule already exist, live on the account or staged earlier in the same chat, or one that would pass Meta's cap of 100 per account. An ad set in the same chat can chain to it with `--custom-conversion-id meta_temp_*`.
+
+
 **Instant-form leads** — `leads` returns **one page** plus a `nextCursor`; a response carrying one is not the whole set, so follow it before quoting any total. Email and phone answers come back masked unless `--full`. Both commands need Meta lead ads switched on for the company (`pages_manage_ads` + `leads_retrieval`, granted at connect time — a company switched on after connecting must reconnect Meta first); each says which of the two is missing.
 
 
@@ -1373,7 +1382,7 @@ baker funnel --steps '[...]'                          # the whole funnel, restat
 
 **Every write says what it dropped.** `--step` changes one step and leaves the rest as it stands; `--steps` replaces the whole funnel and `--preset` draws over it. Every write returns `removed[]` and a `REMOVED steps:` hint when a step went, so a restatement written from a stale read is caught in the same turn.
 
-**A step says what triggers it, and every trigger is PICKED from `--moments`.** `triggers` is a list and any one of them firing is enough. Three kinds: `{"kind":"event","eventKey":"submit:contact"}` for anything the company's Forms, pages or systems produced (`moments.events`, `moments.sources`), `{"kind":"landing","landingId":"<id>"}` for one landing being viewed (`moments.landings`), and `{"kind":"any_landing"}` for any landing — what the default first step listens for. Nothing has to be named first: the event is used by its own key, and the step shows it by its own words. `moments.events[].origin` tells a page's event (`site`) from one the client's own systems sent (`systems`); `moments.sources` lists the client's systems by the `page:<name>` key each raises, pickable before the first send arrives. **A Form's own endings need nothing set up first** — no Source, no conversion: a Baker page raises them natively, so every Form in the workspace contributes one row to `moments.events` — its **outcome** — at zero, carrying `outcome: true`, `seen: false` and the `step` it happens on. It is the same ending `baker analytics conversions` recommends counting, so a step and a conversion land on the same event; `baker analytics conversions --flow <slug>` lists all of one Form's endings when a step wants another. `baker funnel` also hints, in one line, every workspace Form that reaches no step, with its outcome key. Place one with **`baker funnel --add-trigger <step-key> --event <key>`**, which adds a single way in and leaves the step's name, stage, `after[]` and other triggers untouched — `--step` takes a whole step and silently drops any trigger a restatement forgets. That is what makes a Form built minutes ago pickable. A key typed from memory saves, publishes and counts nobody forever — the hint "has a trigger and nobody reached it while N people entered" is that mistake caught after the fact. A step written with `offlineConversions`, a `conversion` trigger or an `analytics` trigger is refused before any round trip, with the shape to use.
+**A step says what triggers it, and every trigger is PICKED from `--moments`.** `triggers` is a list and any one of them firing is enough. Three kinds: `{"kind":"event","eventKey":"submit:contact"}` for anything the company's Forms, pages or systems produced (`moments.events`, `moments.sources`), `{"kind":"landing","landingId":"<id>"}` for one landing being viewed (`moments.landings`), and `{"kind":"any_landing"}` for any landing — what the default first step listens for. Nothing has to be named first: the event is used by its own key, and the step shows it by its own words. `moments.events[].origin` tells a page's event (`site`) from one the client's own systems sent (`systems`); `moments.sources` lists the client's systems by the `page:<name>` key each raises, pickable before the first send arrives. A key typed from memory saves, publishes and counts nobody forever — the hint "has a trigger and nobody reached it while N people entered" is that mistake caught after the fact. A step written with `offlineConversions`, a `conversion` trigger or an `analytics` trigger is refused before any round trip, with the shape to use.
 
 **A landing being viewed can be a step** — where most funnels start — and never a conversion: `baker analytics conversions` refuses a `view:` key.
 

package/dist/{chunk-ZBC4NFST.js → chunk-WONWYE7B.js}

@@ -17,9 +17,9 @@ import {
   shouldEscalate
 } from "./chunk-UIQJZGBG.js";
 
-// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/index.js
+// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
-  "../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/index.js"(exports, module) {
+  "../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js"(exports, module) {
     "use strict";
     var { hasOwnProperty } = Object.prototype;
     var stringify = configure2();
@@ -1111,7 +1111,7 @@ function resolveAdaptFormats(params) {
   return params.formats ?? [];
 }
 
-// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/esm/wrapper.js
+// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/esm/wrapper.js
 var import__ = __toESM(require_safe_stable_stringify(), 1);
 var configure = import__.default.configure;
 var wrapper_default = import__.default;
@@ -9661,4 +9661,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-ZBC4NFST.js.map
+//# sourceMappingURL=chunk-WONWYE7B.js.map