Wiki Notify for Google Chat

@@ -0,0 +1,137 @@+# Wiki Notify for Google Chat (wiki-notify-gchat)++Turn wiki.adom.inc notification emails into a **live board in Google Chat** -+and keep your Gmail inbox clean.++```+wiki notification email ──poll──> per-item state ──render──> ONE card in YOUR Chat space+        │                         (open/closed)              newest first, row per item+        └──sweep──> trash / archive / label+```++The board is a single card, one row per issue: **status** (OPEN green /+CLOSED gray), **page + issue #**, **origination date**, **actor**, **title**,+**last activity**, and a **View link at the end of the row**. New activity+bubbles to the top. Open items stay on the board until resolved; when an item+is closed it shows CLOSED - so you get the satisfaction of seeing it done -+then drops off at **6am the next day** to keep the board fresh.++![The board card in Google Chat](docs/board.png)++## How it works (and why a webhook + delete swap)++Google Chat incoming webhooks can only *create* messages, and only Chat apps+can post cards. So on every change, the tool POSTs a fresh card through your+webhook and then deletes the previous card via `adom-google` - you created+the space, so you are a space manager and may delete the webhook's messages.+Net effect: always exactly one board card, always the newest message in the+space. No change, no repost.++All Gmail + Chat auth is delegated to+[adom-google](https://wiki.adom.inc/adom/adom-google) (safe mode is enough).+The only secret this tool holds is **your webhook URL**, in your private+config (`0600`, outside any repo - never commit it).++## Install++```bash+adom-wiki pkg install adom/wiki-notify-gchat+```++## Set up your own space + webhook (each team member does this once)++1. In Google Chat, create a space for yourself, e.g. **Wiki Notifications**.+2. In that space: space name > **Apps & integrations** > **Webhooks** >+   **Add webhook**, name it (e.g. `wiki-notify`), copy the URL.+3. `wiki-notify-gchat setup`, then paste the URL into `"webhook"` in+   `~/.config/wiki-notify-gchat/config.json`.+   The webhook URL is a secret: it lives only in that private config file.+   If you ever copy it anywhere else, keep it out of git (`.gitignore` it).+4. Optional: set `"timezone"` (IANA name, e.g. `America/New_York`) so the 6am+   closed-item purge happens in *your* morning, and pick your `"action"`.++```bash+wiki-notify-gchat health           # verify auth + config+wiki-notify-gchat run --dry-run    # preview: what would be ingested + swept+wiki-notify-gchat backfill         # seed the board from the last 30 days (no sweeping)+wiki-notify-gchat run              # ingest + sweep + post the board+wiki-notify-gchat install-cron     # keep it live every 2 minutes+```++![Dry-run preview and status](docs/dry-run.png)++## What happens to the emails++`"action"` in the config decides:++| action | effect |+|---|---|+| `trash` (default) | out of the inbox, recoverable from Trash for 30 days |+| `archive` | out of the inbox, stays in All Mail forever |+| `label` | out of the inbox, tagged with `labelName` (auto-created), e.g. `wiki-notify` |+| `keep` | left untouched (board only) |++A `requireInBody` guard (default `wiki.adom.inc`) means only genuine wiki+notifications are ever touched - anything else the sender mails stays in your+inbox. A failed board post never sweeps the email; it retries next pass.++## Board lifecycle++- **New issue / reopened** - row appears (or returns) as OPEN, jumps to the top.+- **Comment / mention** - row bumps to the top with `last: new comment` /+  `mentioned you`.+- **Closed** - row shows CLOSED (gray) and sticks around so you can enjoy it,+  then is removed at `purgeHour` (default 6am, your `timezone`) the next day.+- The board caps at `maxRows` (default 40); older items collapse into a+  `+N older item(s)` line.++## Config reference (`~/.config/wiki-notify-gchat/config.json`)++| Field | Default | Meaning |+|---|---|---|+| `webhook` | - | YOUR incoming-webhook URL (secret) |+| `query` | `from:[email protected] in:inbox` | Gmail search for candidate emails |+| `requireInBody` | `wiki.adom.inc` | body guard; non-matching mail is never touched |+| `action` | `trash` | `trash` / `archive` / `label` / `keep` |+| `labelName` | `wiki-notify` | label used when `action` = `label` |+| `pollSeconds` | `120` | poll + cron interval |+| `purgeHour` | `6` | hour (0-23) closed items drop off, day after closing |+| `timezone` | container local | IANA zone for dates + the purge |+| `maxRows` | `40` | card row cap |+| `boardTitle` | `Wiki Notifications` | card header |++## Commands++```+setup | health | run [--dry-run] | backfill [--days N] | board [--dry-run]+status | watch | install-cron | uninstall-cron | install+```++All commands accept `--json` for a `{status, data, hints}` envelope.+`board --dry-run` prints the exact card JSON without posting.++## Files++| Path | What |+|---|---|+| `~/.config/wiki-notify-gchat/config.json` | config incl. webhook (0600, private) |+| `~/.local/state/wiki-notify-gchat/state.json` | item state, processed ids, board message id |+| `~/.local/state/wiki-notify-gchat/activity.log` | one line per ingest/board/purge |+| `~/.local/state/wiki-notify-gchat/cron.log` | cron pass output |++## Troubleshooting++- `health` says not authorized: run `adom-google auth`.+- Board stopped updating after a container cold boot: `sudo service cron start`.+- Board card duplicated (old one not deleted): you must be a **space manager**+  of the space - use a space you created. The stray card is one manual delete+  away; the tool logs a WARN when this happens.+- Wrong purge time: set `"timezone"` to your IANA zone.++## Non-Adom orgs++Everything rides on adom-google; see+[its page](https://wiki.adom.inc/adom/adom-google) for standing up Google+OAuth outside Adom (self-hosted gateway or managed container via[email protected]). Adjust `query`/`requireInBody` to your own wiki's+notification sender.