@koda-sl/baker-cli 0.156.0 → 0.158.0

package/README.md

@@ -160,6 +160,34 @@ baker ads google currency --customer-id 5904042878
 
 ---
 
+### `baker ads google url-options`
+
+The UTM / tracking parameters in force on the account: the account-level Final URL Suffix and tracking template, plus every campaign that overrides them. Start here for any "add `utm_agency=…`" or agency-tag question.
+
+```bash
+baker ads google url-options --customer-id 1234567890          # overriding campaigns only
+baker ads google url-options --customer-id 1234567890 --full   # every campaign read
+```
+
+Every value is a tagged union, never a bare string, so an unread level can never be reported as an unset one:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "account": { "final_url_suffix": { "state": "set", "value": "utm_source=google" } },
+    "campaigns": { "overriding": [], "omitted": 12 },
+    "levels_not_read": ["ad_group", "ad"]
+  }
+}
+```
+
+`set` holds a value · `not_set` means Google carries none at that level · `not_read` means it was never observed. **Only `not_set` is a finding.**
+
+Writing it: `baker ads google campaigns update <id> --final-url-suffix "utm_source=google&utm_agency=baker"` stages a campaign-level override (it *replaces* the account value for that campaign, it does not merge). The **account** level is deliberately not stageable — Google writes it through `CustomerService`, outside the atomic publish batch, so it could not be published atomically nor reversed by discarding the chat. `--level account` stages nothing and returns a structured `error.fix` naming where to set it.
+
+---
+
 ### `baker ads google query`
 
 Run arbitrary GAQL queries. The most powerful command.
@@ -191,22 +219,46 @@ baker ads google query --list-presets
   "ok": true,
   "data": [
     { "campaign.name": "Brand US", "metrics.clicks": 4521, "metrics.cost_micros": 2850000000 }
-  ],
+  ]
+}
+```
+
+`--full` adds a `fields` dictionary describing each selected column. It is off by default — the rows already carry the data, and the glossary is a per-call cost.
+
+```json
+{
+  "ok": true,
+  "data": [...],
   "fields": {
     "campaign.name": "Campaign display name",
-    "metrics.clicks": "Total clicks (integer)",
-    "metrics.cost_micros": "Total cost in micros (÷ 1,000,000 for actual currency)"
+    "metrics.clicks": "Total clicks (integer)"
   }
 }
 ```
 
+**Absent is not empty.** Google omits a field entirely from a row when it holds no value, so a missing key means *this read did not observe it*, never *the setting is unset*. When one or more selected fields come back on **no** row, the response carries a `MISSING_FIELDS` warning naming them:
+
+```json
+{
+  "ok": true,
+  "data": [...],
+  "warnings": [
+    {
+      "code": "MISSING_FIELDS",
+      "message": "These SELECTed fields came back on no row: ad_group_ad.ad.final_url_suffix. ..."
+    }
+  ]
+}
+```
+
+Read it before interpreting any null. It does not fire on the `--out` path (rows stream to disk), and `.resource_name` is never reported (the server strips it from every row).
+
 **Response (with pagination):**
 
 ```json
 {
   "ok": true,
   "data": [...],
-  "fields": { ... },
   "pagination": { "hasMore": true, "cursor": "eyJwYWdl..." }
 }
 ```
@@ -823,6 +875,12 @@ baker ads linkedin bid-pricing --account-id 503001492 \
 
 **Listings** (`campaign-groups`/`campaigns`/`creatives`) default to `ACTIVE` only — pass `--all-statuses` to widen, or `--statuses ACTIVE,PAUSED` for a custom set.
 
+**`creatives` is compact by default** — `id`, `urn`, `campaign`, `intendedStatus`, `isServing`, `reviewStatus`, `format`, and the resolved destination. The destination is read out of the format-specific `content` block for you: direct-content ads (text, spotlight) report a `landingUrl`; post-based ads (image, video, carousel, document, article, event, TLA) report a `postUrn`, because their destination lives in the sponsored post and is not reachable through the ads API. Pass `--fields id,content.textAd.landingPage` for specific dotted paths, or `--full` for the complete raw records.
+
+**Many ids, one call.** `creatives update` and every `pause`/`resume`/`archive` accept a list — `creatives pause 111,222,333`, or `--ids-file ads.txt` (one id per line or comma-separated, `#` comments skipped). The whole set stages in a single all-or-nothing request: if any id fails validation the draft is left untouched and the error names the offending index, so there is never a half-applied batch to reason about. A single id takes the exact same path as before, including `li_temp_*` amends (amends stay single-id — pass those on their own).
+
+**Post-based ads are not editable.** Image, video, carousel, document, article, event and TLA creatives sponsor a LinkedIn post; the copy, media and destination belong to the post, not the ad. Both `creatives update` and `creatives duplicate` reject content flags on these rather than accepting them and silently dropping them. To change the copy, stage a new `creatives create` and pause the old ad. Direct-content formats (text, spotlight, follower, jobs) do update in place.
+
 **Pagination** is auto-drained (start/count loop hidden).
 
 **Demographic pivots** (`MEMBER_*`) come back delayed 12-24h with a ≥3-event privacy floor — small buckets are dropped. The CLI surfaces `DELAYED_DEMOGRAPHIC` and (when results are unexpectedly empty) `BELOW_PRIVACY_FLOOR` warnings.