@koda-sl/baker-cli 0.244.0 → 0.245.0

package/README.md

@@ -278,7 +278,31 @@ baker ads google query --list-presets
 }
 ```
 
-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).
+Read it before interpreting any null. Field coverage is folded page by page on the `--out` path too, so the file summary reports it; `.resource_name` is never reported (the server strips it from every row).
+
+**A page is not the data set.** Without `--all`, a query returns one page capped by `--limit` (default 200, or the `LIMIT` in the statement, whichever is smaller). With `--all` every page is followed, but the statement's `LIMIT` still caps the read — and preflight adds one at `--limit` to any query that arrives without it, so `--all` on its own still stops at 200 rows. When the rows fill whichever cap is in force, or the API returns a cursor the run did not follow, the response carries a `TRUNCATED_RESULTS` warning:
+
+```json
+{
+  "ok": true,
+  "warnings": [{ "code": "TRUNCATED_RESULTS", "message": "INCOMPLETE READ — ..." }],
+  "pagination": { "hasMore": true, "cursor": "eyJwYWdl..." },
+  "data": [...],
+  "notice": "Read the \"warnings\" above before using these rows: TRUNCATED_RESULTS."
+}
+```
+
+Never total or count from a response carrying it — re-run with `--all --limit 10000 --out data.csv` (the API accepts page sizes up to 10,000) and check the re-run came back without the warning. Warnings reach every output format, so no `--output` choice can hide one:
+
+| `--output` | Where warnings land |
+|------------|---------------------|
+| `json`     | `warnings` and `pagination` **before** `data`, one-line `notice` last |
+| `csv`      | `# baker <CODE>: …` comment lines under the header and after the last row |
+| `md`       | `> **<CODE>** — …` blockquote above and below the table |
+| `jsonl`    | a `{"_baker_warning":{…}}` line first and last |
+| `--out`    | the file summary carries `complete: true|false`, every warning, and the `notice` |
+
+The same lines also go to stderr. A read with nothing to report prints none of it.
 
 **Response (with pagination):**
 
@@ -311,7 +335,7 @@ Read it before interpreting any null. It does not fire on the `--out` path (rows
 | `--include-paused` | Include paused entities in preset results. Off by default: presets return only actually-serving entities (enabled campaign **and** ad group **and** ad). Google Ads has no single serving flag, so the whole chain must be `ENABLED` for an entity to serve. |
 | `--limit`       | Max rows per page (default 200)                              |
 | `--cursor`      | Pagination cursor from previous response                     |
-| `--all`         | Auto-paginate all results                                    |
+| `--all`         | Auto-paginate all results. Exhausts the pages, not the statement's `LIMIT` — pair it with a `--limit` above the expected row count, and a read that still fills its cap is flagged `TRUNCATED_RESULTS` either way |
 | `--out`         | Write data to file (format from extension: .csv, .jsonl, .json) |
 | `--append`      | Append to existing file (skip CSV headers)                   |
 | `--output`      | Output format: `json` \| `csv` \| `jsonl` \| `md`           |
@@ -337,7 +361,7 @@ Read it before interpreting any null. It does not fire on the `--out` path (rows
 
 Every preset except the negatives lists and `account-summary` filters to **actually-serving entities** by default — the full status chain (`campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED'`, as applicable) — and selects the status columns so you can see them. Pass `--include-paused` to widen to `!= 'REMOVED'` (keeps paused, still drops removed). Raw GAQL (no `--preset`) has no such default: a query over a serving-hierarchy resource without a status filter emits a `SERVING_SCOPE` warning reminding you to add the chain, because Google Ads has no single serving flag.
 
-**"Eligible (Limited)" keywords:** an enabled keyword that barely shows is invisible in the performance presets — near-zero impressions look the same whether it is outbid, low quality, or rarely searched. `--preset keyword-serving` reads the signals behind Google Ads' status column: `ad_group_criterion.primary_status` and `primary_status_reasons` (the status enum has no `LIMITED` value — "(Limited)" lives in the reasons while the status stays `ELIGIBLE`), `position_estimates.first_page_cpc_micros` (the number in "Below first page bid (€3.63)"), the max CPC actually in force and where it comes from, quality score split into ad relevance / landing page / expected CTR, approval status, and `system_serving_status`. Any read whose rows carry those fields — preset or raw GAQL — comes back with a `KEYWORD_SERVING_LIMITED` warning naming the affected keywords (each by its ad group, since one keyword's copies share a criterion id) and the bid each would need. Below-first-page-bid and low-quality want opposite fixes (raise the bid vs. improve relevance), so the warning reports them separately. On `--out` the verdict is folded across pages as they stream to disk and returned on the file summary; as with `MISSING_FIELDS`, `--output csv|jsonl|md` emits rows only and carries no warnings.
+**"Eligible (Limited)" keywords:** an enabled keyword that barely shows is invisible in the performance presets — near-zero impressions look the same whether it is outbid, low quality, or rarely searched. `--preset keyword-serving` reads the signals behind Google Ads' status column: `ad_group_criterion.primary_status` and `primary_status_reasons` (the status enum has no `LIMITED` value — "(Limited)" lives in the reasons while the status stays `ELIGIBLE`), `position_estimates.first_page_cpc_micros` (the number in "Below first page bid (€3.63)"), the max CPC actually in force and where it comes from, quality score split into ad relevance / landing page / expected CTR, approval status, and `system_serving_status`. Any read whose rows carry those fields — preset or raw GAQL — comes back with a `KEYWORD_SERVING_LIMITED` warning naming the affected keywords (each by its ad group, since one keyword's copies share a criterion id) and the bid each would need. Below-first-page-bid and low-quality want opposite fixes (raise the bid vs. improve relevance), so the warning reports them separately. On `--out` the verdict is folded across pages as they stream to disk and returned on the file summary; like every other warning it also travels in `--output csv|jsonl|md`.
 
 The warning defers to Google: when the query selects `primary_status_reasons`, a keyword Google did not flag is not reported, even if its bid sits under the first-page estimate — the estimate is advisory and the bid may not be the criterion's to set under a portfolio strategy. Only an estimates-only read (no reasons selected) falls back to inferring the limit from the bid gap.
 
@@ -432,13 +456,14 @@ baker ads google keywords discover --customer-id 1234567890 --url "https://compe
   "data": {
     "keywords": [
       {
+        "source": "keyword_planner_estimate",
         "keyword": "student services",
-        "avg_monthly_searches": "1000",
-        "competition": "LOW",
-        "competition_index": "4",
-        "low_top_of_page_bid_micros": 0,
-        "high_top_of_page_bid_micros": 0,
-        "monthly_search_volumes": [
+        "planner_avg_monthly_searches": "1000",
+        "planner_competition": "LOW",
+        "planner_competition_index": "4",
+        "planner_low_top_of_page_bid_micros": 0,
+        "planner_high_top_of_page_bid_micros": 0,
+        "planner_monthly_search_volumes": [
           { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
         ]
       }
@@ -447,12 +472,13 @@ baker ads google keywords discover --customer-id 1234567890 --url "https://compe
     "next_page_token": "..."
   },
   "fields": {
+    "source": "Always \"keyword_planner_estimate\" — these rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data",
     "keyword": "Suggested keyword text",
-    "avg_monthly_searches": "Average monthly search volume",
-    "competition": "Competition level: LOW, MEDIUM, HIGH, UNKNOWN",
-    "competition_index": "Competition index 0-100 (higher = more competitive)",
-    "low_top_of_page_bid_micros": "Low-range CPC bid in micros (÷ 1,000,000 for currency)",
-    "high_top_of_page_bid_micros": "High-range CPC bid in micros (÷ 1,000,000 for currency)"
+    "planner_avg_monthly_searches": "ESTIMATE: average monthly searches across the whole market",
+    "planner_competition": "ESTIMATE: competition level — LOW, MEDIUM, HIGH, UNKNOWN",
+    "planner_competition_index": "ESTIMATE: competition index 0-100 (higher = more competitive)",
+    "planner_low_top_of_page_bid_micros": "ESTIMATE: low-range CPC bid in micros (÷ 1,000,000 for currency)",
+    "planner_high_top_of_page_bid_micros": "ESTIMATE: high-range CPC bid in micros (÷ 1,000,000 for currency)"
   }
 }
 ```
@@ -491,13 +517,14 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
   "data": {
     "historical_metrics": [
       {
+        "source": "keyword_planner_estimate",
         "keyword": "running shoes",
-        "avg_monthly_searches": "1000",
-        "competition": "LOW",
-        "competition_index": "4",
-        "low_top_of_page_bid_micros": 0,
-        "high_top_of_page_bid_micros": 0,
-        "monthly_search_volumes": [
+        "planner_avg_monthly_searches": "1000",
+        "planner_competition": "LOW",
+        "planner_competition_index": "4",
+        "planner_low_top_of_page_bid_micros": 0,
+        "planner_high_top_of_page_bid_micros": 0,
+        "planner_monthly_search_volumes": [
           { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
         ]
       }