@koda-sl/baker-cli 0.309.0 → 0.310.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.