@koda-sl/baker-cli 0.234.0 → 0.236.0

package/README.md

@@ -796,6 +796,13 @@ baker ads meta activities --account-id act_123 --days 7
 # "Which Page should this ad run from?"
 baker ads meta pages                                                 # Facebook Pages the user manages (tasks shows which can ADVERTISE)
 
+# "What is the lead form collecting, and how many came in?"
+baker ads meta lead-forms --page-id 100635183117758                  # instant forms on a Page + lead counts
+baker ads meta lead-forms --page-id 100635183117758 --full           # also each form's questions
+baker ads meta leads --form-id 987654321 --since 2026-08-01 --until 2026-08-31
+baker ads meta leads --form-id 987654321 --after <nextCursor>        # results are PAGED — follow the cursor
+baker ads meta leads --form-id 987654321 --full                      # raw contact details (CRM hand-off only)
+
 # "What are we running right now?"
 baker ads meta campaigns --account-id act_123                        # ACTIVE only by default
 baker ads meta ads --account-id act_123 --all-statuses               # widen to everything
@@ -818,6 +825,9 @@ baker ads meta pixels --account-id act_123
 baker ads meta pixels --pixel-id 9988 --stats --days 7
 ```
 
+**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.
+
+
 #### Staged writes (`baker ads meta campaigns|adsets|ads|creatives|audiences|media|draft`)
 
 Meta writes mirror the Google/LinkedIn model: they **never hit the Graph API when you run them**. Each op is validated at stage time (field shapes, budget rules, page/Instagram identity ownership, CBO/ABO exclusivity, status-transition legality), shows in the dashboard chat as a pending Meta change, and applies only when the chat is published. Meta has no atomic batch mutate, so ops apply **sequentially** on publish — one failure skips its dependents but the publish completes.
@@ -1151,6 +1161,70 @@ Each finding: `{id, area, check, status, severity, evidence, fix: {explanation,
 
 ---
 
+### First-party web analytics (`baker analytics`)
+
+Baker's own measurement of the pages it publishes. No connection to set up and nothing to configure — data exists from the moment a page is published — and it is the only source that reports drop-off **per Form step**.
+
+Preset-first; `overview` answers most questions in one call.
+
+```bash
+baker analytics overview --output md      # traffic, top pages, sources, and every Form's worst step
+baker analytics overview --days 7
+baker analytics traffic --days 90 --full  # full breakdowns plus the per-day trend
+baker analytics funnel --flow contact     # which step loses people
+baker analytics page --path /pricing      # one page in detail
+baker analytics triggers --flow contact   # what visitors did in the Form, wired up or not
+baker analytics releases                  # traffic and conversions per published build
+baker analytics landings                  # every page side by side, with a sparkline each
+baker analytics landings --tag q4         # only the pages filed under one campaign tag
+baker analytics tags                      # the same numbers rolled up per campaign
+baker analytics events                    # the events the pages define for themselves
+baker analytics events --event video_progress --property milestone
+baker analytics events --steps hero_view,pricing_view,demo_click   # an ordered page funnel
+baker analytics devices --grain viewport  # which widths the page has to survive
+baker analytics geo --grain postal_code --country ES
+baker analytics bots                      # which crawlers fetch the site
+baker analytics presets                   # what each report answers
+baker analytics ads --platform google     # what Google's traffic carries, in Google's vocabulary
+baker analytics map --platform google --set kw=keyword    # name a parameter, seen or not yet
+baker analytics map --platform google --remove kw         # take that answer back
+baker analytics delivery --page 2         # the next page of a long list
+baker analytics submissions --flow contact  # every attempt at a Form, delivered or not
+```
+
+Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-MM-DD`, end inclusive); `--full`; `--compare` to also return the preceding window of the same length; `--timezone <IANA>` and `--granularity hour|day|week|month` to shape a series. Every call reads live — there is no cache layer, so there is nothing to bypass.
+
+**`--output md` when the numbers are going to be read.** Every report is emitted as compact JSON by default, and `--output md` renders each block as a Markdown table instead — one header rather than the keys repeated on every row, with the identical `warnings` and `hints`. Measured across all sixteen presets against a real deployment, the two changes together take the family from 110 KB to 44 KB — **about 60% smaller overall**, 38% at worst (`ads`, which is dense numeric data with nothing to prune) and 77% at best (`landings`). Three further economies apply to both formats, because the reader is usually an LLM with a context window rather than a browser:
+
+- Fields that would be `""` or `[]` are omitted; `null` and `0` are always sent, and they mean different things.
+- The `sparkline` on `landings` is dropped unless `--full`, and resampled to 30 points when present. It is bucketed by `--granularity` upstream, so ninety days at `hour` is 2,160 numbers per page.
+- Past ~25 rows the response carries a hint naming the row count and pointing at `--output md`.
+
+**Paging the list reports.** `people`, `submissions` and `delivery` are lists of individual things rather than breakdowns — `delivery` and `submissions` are the ones the CLI exposes, `people` backs the dashboard's People screen over the same wire — and only they take `--page <n>` (1-based) and `--page-size <n>` (up to 200, default 50). The response carries `pageInfo` with `hasMore` — when it is true there **are** more rows, so a total must never be reported from one page. Pass neither flag and a list comes back at the size it always did.
+
+**Campaign parameters are per platform, and so are the numbers.** `baker analytics ads` returns `adPlatformTraffic` (visits, conversions and *tagged* visits for each of the nine platforms), `adParams` for the platform in `--platform` only, and `adParamsUnattributed` for names arriving on visits with no click id and no recognisable source. Read `adPlatformTraffic` first: a platform with visits and zero tagged visits has untagged ad URLs, and no mapping can fix that from Baker's side. `baker analytics map` needs `--platform` for any change, accepts a parameter name **nobody has sent yet** — which is how a tracking template is configured before its campaign runs — and takes an answer back with `--remove`. `--set <name>=ignore` says a parameter is not campaign information at all, so Baker stops storing it and stops listing it.
+
+An unrecognised `--timezone` is refused with a `VALIDATION_ERROR` rather than defaulting to UTC, and `--output` accepts only `json` or `md`. Pass `--timezone` whenever the client is not in UTC. Day boundaries are drawn in UTC by default, which moves two hours of every Spanish evening onto the following day — not a rounding error on a day-of-week comparison, but the wrong day.
+
+Reading the output:
+
+- `visitors` and `sessions` are counted from explicit `visitor_new` / `session_start` events, so a session begins when the page says it did rather than when a query guesses.
+- `pageViews` prefers the server-side count, which ad blockers cannot suppress, so it usually exceeds a script-only measurement of the same period.
+- Rates are `null`, never `0`, when there is no denominator — `null` means "no data", `0` means "genuinely none".
+- `warnings[]` and `hints[]` carry caveats (small sample, sampled data) that belong in the answer, not in the footnotes.
+- `triggers[]` reports what visitors *did* inside a Form — a link click that redirects them off the site, a scheduling widget, an embedded checkout posting back — none of which produces a funnel step. `sideEffectsFired` says how many of those fires actually did something; a trigger with many fires and none is real behaviour with nothing wired to it.
+- `submissions[]` is one row per **attempt** at a Form — one visitor, one Form, one visit — whether they finished, abandoned it halfway, or completed a Form wired to no destination. `delivery` is built from dispatches and so cannot show that last case at all, which is why the two are separate reports and why the gap between them must never be presented as lost leads without saying which it is.
+- `releases[]` gives one row per published build, so a change to a page can be compared before and after instead of against a date. Only events carrying a build are counted, so its `pageViews` sits below the site total for the same period.
+
+- `landings[]` is one row per page with its real name and campaign tags, joined from a dimension Baker mirrors on every publish. An empty `name` means the mirror has not caught up — say "not synced yet" rather than showing the id as a title.
+- `trend[]` returns **every** bucket in the window, including ones with no traffic. A quiet day is a real zero rather than a missing row, so a chart cannot draw a straight line through it and imply traffic that did not happen.
+- `customEvents[]` covers only events a page defined for itself through `data-baker-*` attributes or `window.baker.track()`. Each row lists the property keys it carries, which is what tells you what you can break it down by.
+- `customFunnel[]` is **ordered**: a session counts at step N only if it produced step N after step N-1. Reordering `--steps` answers a different question.
+
+Data is retained for 400 days; a window reaching further back comes back with a `BEYOND_RETENTION` warning, and the older part is missing rather than zero.
+
+---
+
 ### Google Analytics 4 (`baker ga4`)
 
 GA4 commands for multi-channel audits **and** for configuring what the property measures. Playbook-aligned report presets, property health audits, free-form Data API queries, and staged Admin API writes.