analytics and reports for a collector: store-only configs, --json snapshot, App Usage and Play install stock numbers, per-day sales ranges for both stores

skills/store-analytics/SKILL.md

@@ -16,7 +16,8 @@ CLI: `storebound analytics setup | snapshot | compare`. MCP: `analytics_snapshot
   (`stoppedDueToInactivity`); `setup` makes a new one. storebound reads "App Store Discovery and Engagement" (Event
   Impression / Page view, Counts and Unique Counts) and "App Store Downloads" (First-time Download, Redownload; updates
   are left out), checks each segment's md5 checksum and keeps, per day, the newest processing of that day.
-  Conversion = (first-time downloads + redownloads) / unique impressions. Source:
+  Conversion = (first-time downloads + redownloads) / unique impressions. App Usage (sessions, active devices, crashes) comes from the
+  "App Sessions" and "App Crashes" reports of the same request. Source:
   https://developer.apple.com/documentation/appstoreconnectapi/downloading-analytics-reports
 - **Google Play**: there is **no API** for store listing statistics (the Play Developer Reporting API only has
   vitals). Play Console writes monthly CSV exports into your own Cloud Storage bucket; storebound reads them with
@@ -28,6 +29,29 @@ CLI: `storebound analytics setup | snapshot | compare`. MCP: `analytics_snapshot
   results (read them in the consoles; `storebound apple ppo status` shows the App Store test state), Play
   "Explore" search terms beyond the traffic source file.
 
+## For a collector (store-only config, JSON on stdout)
+A script that reads many apps needs no project: a config with `apple.appId` (`bundleId` null or left out) and
+`play.packageName` is valid for `analytics` and `reports` reads (every write still needs the bundle id).
+- `storebound analytics snapshot --store apple|play --days 30 --config <virtual.json> --account <profile> --json`
+  prints the snapshot as one JSON document on stdout (logs go to stderr); the file in `--dir` is still written, add
+  `--no-write` to skip it. A store that failed carries `{ "error": ... }`; when every store failed the JSON is printed
+  and the exit code is 1. Non-fatal gaps are in `notes`.
+- Play bucket without `play.reportsBucket`: env `PLAY_REPORTS_BUCKET`, else the credential profile's `reportsBucket`
+  (a bucket name, not a secret). Same for `reports play-*`.
+- Active users, per day. App Store: `sessions`, `activeDevices`, `sessionSeconds`, `crashes` from the App Usage
+  reports (App Sessions, App Crashes; `activeDevices` is the sum of the rows' Unique Devices, so a device seen in two
+  rows, e.g. two app versions, counts twice; totals: `sessions`, `crashes`, `activeDevicesAvg`). They appear a day or
+  two after the report request exists; until then the snapshot has the rest and a `notes` line. Play: `installs` (Daily
+  User Installs), `activeDeviceInstalls` (Active Device Installs) and `totalUserInstalls` (Total User Installs) from the
+  installs overview file (all countries; else the country file summed). The last two are stock numbers: totals take the
+  newest day, never a sum.
+- Revenue per day: `storebound reports apple-sales --days 30 --json` (or `--from 2026-10-01 [--to 2026-10-25]`) reads
+  the daily SALES reports of the range (4 at a time): `days[]` with `summary` per SKU and currency and `totals` per
+  currency, `totals` for the range per currency, `missing` (days with no report: no sales, or not out yet; never an
+  error). `storebound reports play-sales --days 30 --json` groups the estimated sales by order charged date and
+  currency of sale: `orders`, `refunds`, `itemPrice`, `taxes`, `charged` (tax included), `refunded` (negative),
+  `net`, plus `emptyDays` and `missingMonths`. Play's earnings (proceeds after Google's fee) are monthly only.
+
 ## Flow
 1. Once: `storebound analytics setup` (App Store) and `play.reportsBucket` (Play).
 2. Weekly: `storebound analytics snapshot` (default the last 28 days; `--dry` prints totals only).