Your Name
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# 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|unset|ls|edit` | Plugin keys in `entertainment.env` |
|
|
|
|
### 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
|
|
|
|
```bash
|
|
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"](../DEV.md).
|
|
|
|
**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](communication.md)); 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](../POS.md)
|
|
- Notify platform: [communication.md](communication.md)
|
|
- Writing a plugin: [DOC/DEV.md](../DEV.md)
|