Phase 3: scheduled background checks + Discord notifications

.env.example

@@ -29,6 +29,15 @@ SESSION_TTL=604800
 # If this starts with https, the login cookie is marked Secure.
 BASE_URL=http://localhost:5000
 
+# --- Background checks & notifications (all optional; also editable in the UI) ---
+# Whether the server checks for updates on a schedule. Default: true.
+# BACKGROUND_CHECK_ENABLED=true
+# How often the background check runs, in hours (1-168). Default: 6.
+# CHECK_INTERVAL_HOURS=6
+# Discord (or compatible) webhook URL to notify when updates are found.
+# Leave unset to disable notifications.
+# DISCORD_WEBHOOK_URL=
+
 # Name of this app's OWN container. It is excluded from the dashboard so it
 # can't be told to update (and thereby restart) itself mid-update. Defaults to
 # "diun-updater" (the container_name in the shipped docker-compose.yml); change

API_CONTRACT.md

@@ -145,20 +145,42 @@ separate section, but can still be updated by hand.
 - Auth: cookie.
 - Response: `200` — current settings, fully populated with defaults:
   ```json
-  { "defaultFilter": "updates", "autoCheckOnOpen": true }
+  {
+    "defaultFilter": "updates",
+    "autoCheckOnOpen": true,
+    "backgroundCheckEnabled": true,
+    "backgroundCheckIntervalHours": 6,
+    "discordEnabled": false,
+    "discordWebhookUrl": ""
+  }
   ```
   - `defaultFilter` — `"updates"` or `"all"`; the view the dashboard opens in.
   - `autoCheckOnOpen` — whether the dashboard runs a check automatically on
     first open.
+  - `backgroundCheckEnabled` — whether the server runs a scheduled check.
+  - `backgroundCheckIntervalHours` — interval for that check (1–168).
+  - `discordEnabled` — whether to send Discord notifications on new updates.
+  - `discordWebhookUrl` — Discord (or compatible) webhook URL, or `""`.
 
 ### `PUT /api/settings`
 
 - Auth: cookie.
 - Body: a partial patch of the settings object, e.g. `{ "defaultFilter":
   "all" }`. Unknown keys are ignored; invalid values for known keys return
-  `400 { "error": "invalid_value" }`.
+  `400 { "error": "invalid_value" }`. Changing the interval/enable re-arms the
+  background scheduler immediately.
 - Response: `200` — the full, updated settings object.
 
+### `POST /api/notify/test`
+
+- Auth: cookie.
+- Body: `{ "url": "string" }` (optional) — a webhook URL to test; falls back to
+  the configured `discordWebhookUrl`.
+- Sends a one-off test message to the webhook.
+- Response: `200 { "ok": true }` on success; `400 { "error": "no_webhook" }` if
+  no URL is configured; `502 { "error": "webhook_failed" }` if the webhook
+  rejected the message.
+
 ### `GET /api/health`
 
 - Auth: none.

README.md

@@ -296,6 +296,21 @@ over the standard token flow — Docker Hub, GHCR, lscr.io, quay.io, etc. for
 public images. Private images that require credentials are skipped (counted
 under `errors`).
 
+### Background checks & Discord notifications
+
+By default the server also checks on a schedule (every 6h) so badges stay fresh
+even when the app is closed. Configure it under **Settings → Background checks &
+Discord**:
+
+- **Background checks** on/off and interval.
+- **Discord webhook URL** — paste a Discord channel webhook to get a message when
+  updates are found, then use **Send test message** to verify it. Each update is
+  announced once (no repeats on every check).
+
+These can also be seeded from the environment (`BACKGROUND_CHECK_ENABLED`,
+`CHECK_INTERVAL_HOURS`, `DISCORD_WEBHOOK_URL`); the Settings UI overrides at
+runtime.
+
 ---
 
 ## Configuration reference
@@ -312,6 +327,9 @@ All configuration is via environment variables (see `.env.example`).
 | `DATA_DIR` | `/data` | | SQLite (`app.db`) location; persist via a volume. |
 | `SESSION_TTL` | `604800` | | Login cookie lifetime in seconds (7 days). |
 | `BASE_URL` | `http://localhost:5000` | | Public URL; if `https`, the cookie is set `Secure`. |
+| `DISCORD_WEBHOOK_URL` | — | | Discord webhook for update notifications (optional; also set in Settings). |
+| `CHECK_INTERVAL_HOURS` | `6` | | Background check interval in hours (1–168). |
+| `BACKGROUND_CHECK_ENABLED` | `true` | | Whether the scheduled background check runs. |
 | `SELF_CONTAINER_NAME` | `diun-updater` | | This app's own container name, excluded from the dashboard so it can't update itself. |
 
 The two required vars are enforced at startup — the server refuses to boot

client/src/api.js

@@ -121,4 +121,8 @@ export function updateSettings(patch) {
   return request('PUT', '/settings', patch);
 }
 
+export function testNotify(url) {
+  return post('/notify/test', url ? { url } : {});
+}
+
 export { ApiError };

client/src/pages/SettingsPage.jsx

@@ -1,11 +1,5 @@
 import React, { useCallback, useEffect, useState } from 'react';
-import {
-  get,
-  getPinned,
-  unpin,
-  getSettings,
-  updateSettings,
-} from '../api.js';
+import { get, getPinned, unpin, getSettings, updateSettings, testNotify } from '../api.js';
 import { useTheme } from '../hooks/useTheme.js';
 
 export default function SettingsPage() {
@@ -19,6 +13,11 @@ export default function SettingsPage() {
   const [settings, setSettings] = useState(null);
   const [settingsError, setSettingsError] = useState('');
 
+  const [webhookDraft, setWebhookDraft] = useState('');
+  const [webhookInit, setWebhookInit] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [testStatus, setTestStatus] = useState('');
+
   const [health, setHealth] = useState(null); // null = unknown, true/false once checked
 
   const loadPinned = useCallback(async () => {
@@ -42,26 +41,48 @@ export default function SettingsPage() {
       .catch((err) => setSettingsError(err.message || 'Failed to load settings'));
   }, []);
 
+  // Seed the webhook input once settings arrive.
+  useEffect(() => {
+    if (settings && !webhookInit) {
+      setWebhookDraft(settings.discordWebhookUrl || '');
+      setWebhookInit(true);
+    }
+  }, [settings, webhookInit]);
+
   useEffect(() => {
     get('/health')
       .then((data) => setHealth(!!(data && data.ok)))
       .catch(() => setHealth(false));
   }, []);
 
-  const saveSetting = useCallback(
-    async (patch) => {
-      // optimistic
-      setSettings((prev) => ({ ...prev, ...patch }));
-      setSettingsError('');
-      try {
-        const updated = await updateSettings(patch);
-        setSettings(updated);
-      } catch (err) {
-        setSettingsError(err.message || 'Failed to save settings');
+  const saveSetting = useCallback(async (patch) => {
+    setSettings((prev) => ({ ...prev, ...patch })); // optimistic
+    setSettingsError('');
+    try {
+      const updated = await updateSettings(patch);
+      setSettings(updated);
+      return updated;
+    } catch (err) {
+      setSettingsError(err.message || 'Failed to save settings');
+      throw err;
+    }
+  }, []);
+
+  const runTest = useCallback(async () => {
+    setTesting(true);
+    setTestStatus('');
+    try {
+      if (settings && webhookDraft !== settings.discordWebhookUrl) {
+        await saveSetting({ discordWebhookUrl: webhookDraft });
       }
-    },
-    []
-  );
+      await testNotify(webhookDraft || undefined);
+      setTestStatus('Sent — check your Discord channel.');
+    } catch (err) {
+      setTestStatus(err.message || 'Test failed');
+    } finally {
+      setTesting(false);
+    }
+  }, [webhookDraft, settings, saveSetting]);
 
   const handleUnpin = useCallback(
     async (ref) => {
@@ -120,15 +141,15 @@ export default function SettingsPage() {
             <button
               type="button"
               className={`chip${settings?.defaultFilter !== 'all' ? ' is-active' : ''}`}
-              onClick={() => saveSetting({ defaultFilter: 'updates' })}
+              onClick={() => saveSetting({ defaultFilter: 'updates' }).catch(() => {})}
               disabled={!settings}
             >
               Updates only
             </button>
             <button
               type="button"
               className={`chip${settings?.defaultFilter === 'all' ? ' is-active' : ''}`}
-              onClick={() => saveSetting({ defaultFilter: 'all' })}
+              onClick={() => saveSetting({ defaultFilter: 'all' }).catch(() => {})}
               disabled={!settings}
             >
               All
@@ -148,7 +169,7 @@ export default function SettingsPage() {
             role="switch"
             aria-checked={!!settings?.autoCheckOnOpen}
             aria-label="Toggle check on open"
-            onClick={() => saveSetting({ autoCheckOnOpen: !settings?.autoCheckOnOpen })}
+            onClick={() => saveSetting({ autoCheckOnOpen: !settings?.autoCheckOnOpen }).catch(() => {})}
             disabled={!settings}
           >
             <span className="theme-switch-track">
@@ -159,6 +180,107 @@ export default function SettingsPage() {
         </div>
       </section>
 
+      <section className="settings-section">
+        <h3>Background checks &amp; Discord</h3>
+        <div className="settings-row">
+          <div className="settings-row-label">
+            <span>Background checks</span>
+            <span className="settings-row-desc">
+              Periodically check for updates even when the app is closed.
+            </span>
+          </div>
+          <button
+            type="button"
+            className="theme-switch"
+            role="switch"
+            aria-checked={!!settings?.backgroundCheckEnabled}
+            aria-label="Toggle background checks"
+            onClick={() =>
+              saveSetting({ backgroundCheckEnabled: !settings?.backgroundCheckEnabled }).catch(() => {})
+            }
+            disabled={!settings}
+          >
+            <span className="theme-switch-track">
+              <span className="theme-switch-thumb" />
+            </span>
+            <span className="theme-switch-text">{settings?.backgroundCheckEnabled ? 'On' : 'Off'}</span>
+          </button>
+        </div>
+        <div className="settings-row">
+          <div className="settings-row-label">
+            <span>Check every</span>
+            <span className="settings-row-desc">How often the background check runs.</span>
+          </div>
+          <select
+            className="settings-select"
+            value={settings?.backgroundCheckIntervalHours ?? 6}
+            onChange={(e) =>
+              saveSetting({ backgroundCheckIntervalHours: Number(e.target.value) }).catch(() => {})
+            }
+            disabled={!settings || !settings?.backgroundCheckEnabled}
+          >
+            <option value={1}>1 hour</option>
+            <option value={3}>3 hours</option>
+            <option value={6}>6 hours</option>
+            <option value={12}>12 hours</option>
+            <option value={24}>24 hours</option>
+          </select>
+        </div>
+        <div className="settings-row settings-row-stack">
+          <div className="settings-row-label">
+            <span>Discord webhook URL</span>
+            <span className="settings-row-desc">
+              Get pinged when updates are found. Paste a Discord channel webhook URL.
+            </span>
+          </div>
+          <input
+            type="url"
+            className="settings-input"
+            placeholder="https://discord.com/api/webhooks/…"
+            value={webhookDraft}
+            onChange={(e) => setWebhookDraft(e.target.value)}
+            onBlur={() => {
+              if (settings && webhookDraft !== settings.discordWebhookUrl) {
+                saveSetting({ discordWebhookUrl: webhookDraft }).catch(() => {});
+              }
+            }}
+            disabled={!settings}
+          />
+        </div>
+        <div className="settings-row">
+          <div className="settings-row-label">
+            <span>Send notifications</span>
+            <span className="settings-row-desc">Enable Discord notifications for background checks.</span>
+          </div>
+          <button
+            type="button"
+            className="theme-switch"
+            role="switch"
+            aria-checked={!!settings?.discordEnabled}
+            aria-label="Toggle Discord notifications"
+            onClick={() => saveSetting({ discordEnabled: !settings?.discordEnabled }).catch(() => {})}
+            disabled={!settings}
+          >
+            <span className="theme-switch-track">
+              <span className="theme-switch-thumb" />
+            </span>
+            <span className="theme-switch-text">{settings?.discordEnabled ? 'On' : 'Off'}</span>
+          </button>
+        </div>
+        <div className="settings-row">
+          <button
+            type="button"
+            className="btn btn-sm"
+            onClick={runTest}
+            disabled={testing || !webhookDraft}
+          >
+            {testing && <span className="spinner" aria-hidden="true" />}
+            Send test message
+          </button>
+          {testStatus && <span className="settings-test-status">{testStatus}</span>}
+        </div>
+      </section>
+
       <section className="settings-section">
         <h3>Pinned versions</h3>
         {pinnedLoading && (

client/src/styles/app.css

@@ -1184,3 +1184,32 @@ a {
   color: var(--color-accent);
   background: var(--color-elevated);
 }
+
+/* ---------- Settings inputs (Phase 3) ---------- */
+
+.settings-input,
+.settings-select {
+  min-height: var(--touch-target);
+  padding: 8px 12px;
+  background: var(--color-bg);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  color: var(--color-text);
+  font-size: 0.9rem;
+}
+
+.settings-input {
+  width: 100%;
+}
+
+.settings-row-stack {
+  flex-direction: column;
+  align-items: stretch;
+  gap: 8px;
+}
+
+.settings-test-status {
+  margin-left: 10px;
+  font-size: 0.82rem;
+  color: var(--color-text-muted);
+}