71 lines
4.6 KiB
Markdown
71 lines
4.6 KiB
Markdown
# storebound watch
|
|
|
|
Store events for every app on this machine, for people and agents. Read-only on the stores.
|
|
|
|
```
|
|
storebound watch # loop, every 15 minutes
|
|
storebound watch --once # one pass (cron, PM2 restarts)
|
|
storebound watch --dir ./my-app # one folder instead of the machine's app list
|
|
storebound watch --notify os,ntfy # choose the sinks (default: every configured one)
|
|
storebound watch --dry --json # print the events that would go out; nothing is sent or saved
|
|
storebound watch test # send one test event to every configured sink
|
|
storebound events --since 24h --kind rejected --json
|
|
```
|
|
|
|
Apps come from the machine's app folder list (`storebound apps folders`, the same list as the desktop app: folders
|
|
and store-only apps) or from `--dir`. Each app is read with the credentials its commands use (the project's
|
|
`.storebound/`, its profile, or the store-only app's account).
|
|
|
|
Each pass reads release state per store (like `release status`), crash / ANR health (like `health`, at most once an
|
|
hour) and new reviews (like `reviews list`), compares with `~/.storebound/watch-state.json` and emits events. The first
|
|
pass of an app only records the baseline: no event storm. A store that cannot be read in a pass keeps its last state
|
|
and produces no event.
|
|
|
|
## Events
|
|
|
|
| kind | when |
|
|
| --- | --- |
|
|
| `rejected` | a version went from in review to rejected (App Store; link to App Review) |
|
|
| `approved` | a version passed review and waits for release (App Store pending developer release) |
|
|
| `live` | a version became live, or its rollout started |
|
|
| `rollout_halted` | a Play staged rollout was halted, or an App Store phased release paused |
|
|
| `crash_threshold` | Play crash or ANR rate (28 d) crossed the bad behavior threshold; a new App Store metric or diagnostic rated poor |
|
|
| `review_low` | a new review of 2 stars or less |
|
|
| `review_needs_reply` | a new review of 3-5 stars without a reply |
|
|
|
|
Each event is one JSON object: `{ at, app, store, kind, version, from, to, detail, url }`, where `url` is the absolute
|
|
console link for the app. Events are appended to `~/.storebound/events.jsonl` (rotated at 5 MB, one `.1` file kept).
|
|
`STOREBOUND_HOME` moves `~/.storebound`. `storebound events` and the MCP tool `events_recent` read the file.
|
|
|
|
## Sinks
|
|
|
|
All optional. Configure with environment variables or `~/.storebound/watch.json`; values are never printed.
|
|
|
|
| sink | variables |
|
|
| --- | --- |
|
|
| ntfy | `STOREBOUND_NTFY_TOPIC` (required), `STOREBOUND_NTFY_URL` (default `https://ntfy.sh`), `STOREBOUND_NTFY_TOKEN` (optional). Title, Tags and Click headers; Priority high for `rejected` and `rollout_halted` |
|
|
| Telegram | `STOREBOUND_TELEGRAM_TOKEN` and `STOREBOUND_TELEGRAM_CHAT` |
|
|
| webhook | `STOREBOUND_WEBHOOK_URL` (JSON POST of the event) |
|
|
| ingest | `watch.json` `ingest` (or `STOREBOUND_INGEST_URL`, `STOREBOUND_INGEST_TOKEN_FILE`, `STOREBOUND_INGEST_CATEGORY`): JSON POST with `Authorization: Bearer <token>`; the token is read from `tokenFile` at send time (`~` expanded, trimmed, never logged; on POSIX a group- or world-readable file is refused). Body: `category`, `event`, `app` (slug), `platform` (`ios`/`android`), `version`, `detail` (max 300 chars), `url`, `dedupeKey`, at most 8 KiB. 202 = sent; 5xx and network errors retry once, 4xx do not (status and server message are logged). At most 60 sends a minute, the rest are dropped with a warning |
|
|
| OS notification | `--notify os`, or `"notify": ["os"]` in watch.json (Windows toast, macOS osascript, Linux notify-send; skipped quietly when unavailable) |
|
|
|
|
```json
|
|
{ "notify": ["os"], "ntfy": { "topic": "..." }, "telegram": { "token": "...", "chat": "..." }, "webhook": { "url": "..." },
|
|
"ingest": { "url": "https://push.example.com/api/notifications/ingest", "tokenFile": "~/.ingest-token", "category": "storebound" } }
|
|
```
|
|
|
|
Ingest events: `review-rejected`, `review-approved`, `live`, `rollout-halted`, `crash-threshold`, `low-reviews`, `review-reply`. Several sinks can be active at once (ntfy stays a fine fallback).
|
|
|
|
Network calls time out after 10 s and are retried once. A failing sink is logged (by name) and never stops the watch.
|
|
|
|
## On a server with PM2
|
|
|
|
```
|
|
pm2 start "npx -y storebound watch --notify ntfy" --name storebound-watch
|
|
pm2 save
|
|
```
|
|
|
|
Put the credentials profiles (`~/.storebound/credentials/`) and the app folder list (`storebound apps add <folder>`)
|
|
on that server, and the sink variables in the PM2 environment (`STOREBOUND_NTFY_TOPIC=...`). The loop polls every
|
|
`--every` (5m at least, 15m default, +-10 % jitter), backs off after failed passes (up to 4 h), writes one heartbeat
|
|
line per pass and stops cleanly on SIGINT / SIGTERM. With cron use `--once`.
|