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 styled like the wiki digest posts: one divider-ruled row per issue. The left column is the wiki page's hero image (clickable, opens the page - resolved to the public raster blob via adom-wiki page stats, since Chat's image proxy cannot render the SVG /hero/ endpoint). The right column leads with the colored OPEN/CLOSED status in the digest's [new]/[updated] slot, then the hyperlinked item ref (page #N, opens the issue), the description, Created by <name> on <date> <time>, <Event> by <name> on <date> <time> (Opened / Commented / Closed / Reopened / Mentioned), and your involvement - "Drew owns this fix" (assigned) > "Drew opened this" > "Drew owns this page" (you authored the wiki page) > "Drew was mentioned" / "commented on this" > "Drew watches this page" - from the mail's "You're receiving this because..." footer plus page authorship. Set fullName in the config (e.g. "Drew Owens") for the ownership check; it is otherwise derived from the notification's To header. New activity bubbles to the top. (Chat cards have no native table widget: the columns widget caps at 2 and grid tiles are equal-width and unreadable, so the table is this 2-column layout; set "style": "blocks" for the compact per-item layout with View buttons.) 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.

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 (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

adom-wiki pkg install adom/wiki-notify-gchat

Setup (each team member does this once, ~3 minutes)

Prerequisite: an authorized adom-google (adom-google status must show a refresh token; if not, run adom-google auth).

Step 1 - create your own Chat space + webhook (the one manual bit, in the Google Chat UI):

1. Create a space for yourself, e.g. Wiki Notifications. It must be a space you create - the tool deletes its old board card as space manager.
2. Click the space name > Apps & integrations > Webhooks > Add webhook, name it (e.g. wiki-notify), and copy the URL.

Step 2 - configure from the CLI (no file editing needed):

wiki-notify-gchat setup                                  # writes the starter config
wiki-notify-gchat config set webhook '<paste the URL>'   # YOUR secret - stays in the 0600 config
wiki-notify-gchat config set timezone America/Chicago    # IANA zone; the 6am purge follows it
wiki-notify-gchat config set meName Drew                 # first name, for the involvement line
wiki-notify-gchat config set fullName 'Drew Owens'       # wiki author name, detects pages you own
wiki-notify-gchat config set action trash                # or archive | label | keep
wiki-notify-gchat config show                            # review everything (token masked)

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).

Step 3 - verify, seed, go live:

wiki-notify-gchat health           # checks auth, config, webhook shape, cron
wiki-notify-gchat run --dry-run    # preview: what would be ingested + swept (sends nothing)
wiki-notify-gchat backfill         # seed the board from the last 30 days (no sweeping)
wiki-notify-gchat run              # ingest + sweep + post the board for real
wiki-notify-gchat install-cron     # keep it live every 2 minutes

Every command prints OK:/ERROR: plus Hint: lines telling you (or your agent) the exact next step, and accepts --json.

What happens to the emails

"action" in the config decides:

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)

Staying alive and staying current (zero maintenance)

• Cold boots self-heal. install-cron wires three recovery triggers - a cron @reboot entry, a ~/.bashrc snippet, and a Claude Code UserPromptSubmit hook - all calling wiki-notify-gchat ensure (throttled, 15 min). ensure restarts the cron service via passwordless sudo; if cron cannot start at all it launches a detached watch loop instead (and retires it once cron is back). Nobody ever runs sudo by hand.
• Updates are automatic. adom-hook (part of every adom/core install) runs adom-wiki pkg update on a throttled schedule, which pulls new wiki-notify-gchat versions and re-runs the install script. Nothing to do.
• Overlapping passes are impossible: run takes a file lock, so cron, the watch fallback, and ensure never double-post the board.

Commands

setup | config [set <key> <value>] | health | run [--dry-run]
backfill [--days N] | board [--dry-run] | status | watch
install-cron | ensure [--force] | uninstall-cron | install

All commands accept --json for a {status, data, hints} envelope. board --dry-run prints the exact card JSON without posting.

Files

For future devs

docs/DESIGN.md records why things are built this way: the Chat API constraints (webhooks are create-only; only apps can send cards; the delete-repost swap and the deleted-message-tombstone trap), the card layouts we tried and killed (pipe tables, grids), the Gmail search quirks, the two-source involvement line, the cron/cold-boot lessons, and why a central service container was deliberately rejected. Read it before redesigning anything.

Troubleshooting

• health says not authorized: run adom-google auth.
• Board stopped updating after a container cold boot: it self-heals on the next terminal open or Claude prompt (see above); to force it immediately, wiki-notify-gchat ensure --force.
• 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 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.