Linux_post_install/DOC/howto/entertainment.md

How-To: pos entertainment

Auto-published fun messages from public APIs, with per-plugin scheduling. Tools: config, enable, disable, send, status.

Tool	What it does
pos entertainment send	Fetch a plugin's message to stdout (dry-run)
pos entertainment enable <plugin> [interval]	Schedule auto-sends
pos entertainment disable <plugin>	Remove the schedule
pos entertainment status	List plugins + active schedules + last run
`pos entertainment config set	get

Plugins

Plugin	API	Config keys
weather	Open-Meteo (no key)	WEATHER_LAT, WEATHER_LON (req), WEATHER_CITY (opt)
joke	icanhazdadjoke (no key)	—
gold	goldprice.dev (no key)	—

Interval (systemd time): 5m, 10m, 15m, 30m, 45m, 1h, 2h, 6h, 12h, daily, weekly.

---

First run — configure, test, schedule

pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75 WEATHER_CITY="Berlin"
pos entertainment config get WEATHER_CITY

pos entertainment send weather     # stdout test — message for Telegram
pos entertainment send joke
pos entertainment send gold

pos entertainment enable weather daily     # once a day
pos entertainment enable joke 2h           # every 2 hours
pos entertainment disable gold

pos entertainment status                   # plugins + schedules + last run

How it works

• Scheduling uses systemd user timers only (unit pos-entertainment-<plugin>.timer in ~/.config/systemd/user/). Interval is resolved through the same OnCalendar mapper the system scheduler uses (lib/user-timers-lib.sh) — invalid values are rejected with a clear message.
• Delivery goes through notify_send, so the platform follows NOTIFY_PLATFORM (default Telegram). If no platform is configured, enable still works — the plugin fetches and tries to notify, silently no-ops when unconfigured.
• Last run — every send (except --print) records the plugin's exit code and timestamp to ~/.local/share/linux_post_install/entertainment/last/; pos entertainment status shows it per plugin, and a failed timer run also notifies the configured platforms.
• Interactive editing — pos entertainment config edit opens the same numbered-menu editor as pos config (already registered for pos entertainment).

Recipes:

• Morning weather + joke: enable weather daily, enable joke daily; the 08:00 health digest plus these make a nice wake-up.
• Add a plugin: it's a POS_PLUGIN script in entertainment/; stdout is the message, POS_KEYS lines declare config keys, and the message-safe helpers in lib/entertainment-plugin-lib.sh remove the boilerplate. See DOC/DEV.md → "Adding a plugin".

Troubleshooting:

• send weather prints an error about coordinates → set WEATHER_LAT/ WEATHER_LON (required keys) via config set.
• enable fails on the interval → the value isn't valid systemd time; use one of: 5m 10m 15m 30m 45m 1h 2h 6h 12h daily weekly.
• Nothing arrives even though status shows the timer → check notify.env (NOTIFY_PLATFORM) and that telegram.env is configured (see communication); confirm the timer fired: systemctl --user list-timers pos-ent-*.
• Public-API flakiness → the plugin outputs a clear failure; the notify call is silent-fail by design. pos entertainment status shows the last failed run (rc ≠ 0) so a missed timer is visible.

---

Related

• Reference + plugin list: DOC/POS.md → entertainment
• Notify platform: communication.md
• Writing a plugin: DOC/DEV.md