Files
Homelab-manager/server/src/integrations/fieldSchemas.ts
T
bobbanandClaude Sonnet 5.5 1ef686d1ba Let each kind of game server alert be switched off
Three tick boxes on the Fragnet integration: do not alert about disk space,
memory or backups. The page still shows the figures (a switched-off bar is blue
and the backups tile says not judged); /metrics is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 22:36:54 +01:00

317 lines
21 KiB
TypeScript

import type { IntegrationType } from "../db/schema.js";
import type { IntegrationField } from "./types.js";
/**
* Field schema per integration type. Only types with a working adapter appear
* here — the "Add integration" form only offers what's actually implemented.
*/
export const INTEGRATION_FIELDS: Partial<Record<IntegrationType, IntegrationField[]>> = {
tailscale: [
{
key: "tailnet",
label: "Tailnet",
secret: false,
placeholder: "yourorg.github — or - for your default tailnet",
},
{ key: "apiKey", label: "API key", secret: true, type: "password" },
],
gitea: [
{ key: "url", label: "Gitea URL", secret: false, placeholder: "https://gitea.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password" },
],
dockhand: [
{ key: "url", label: "Dockhand URL", secret: false, placeholder: "https://dockhand.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "dh_..." },
],
semaphore: [
{ key: "url", label: "Semaphore URL", secret: false, placeholder: "https://semaphore.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password" },
],
proxmox: [
{ key: "url", label: "Proxmox URL", secret: false, placeholder: "https://pve.example.lan:8006" },
{ key: "tokenId", label: "API token ID", secret: false, placeholder: "root@pam!homelab-manager" },
{ key: "tokenSecret", label: "API token secret", secret: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
synology: [
{ key: "url", label: "Synology DSM URL", secret: false, placeholder: "https://nas.example.lan:5001" },
{ key: "username", label: "Username", secret: false },
{ key: "password", label: "Password", secret: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
uptimekuma: [
{ key: "url", label: "Uptime Kuma URL", secret: false, placeholder: "https://kuma.example.lan" },
{
key: "username",
label: "Username (leave blank when using an API key)",
secret: false,
optional: true,
placeholder: "only needed on very old installs without API keys",
},
{ key: "password", label: "API key (or password, on old installs)", secret: true, type: "password" },
// Uptime Kuma only shares its maintenance schedule over its dashboard connection, which takes a login and not an API key.
{
key: "loginUsername",
label: "Login username, to read maintenance schedules (optional)",
secret: false,
optional: true,
placeholder: "a Kuma account without two-factor — it can change anything in Kuma, so use a dedicated one",
},
{ key: "loginPassword", label: "Login password (optional)", secret: true, optional: true, type: "password" },
{ key: "syncMaintenance", label: "Keep maintenance windows in step with Uptime Kuma's schedule", secret: false, type: "checkbox" },
],
phpipam: [
{ key: "url", label: "phpIPAM URL", secret: false, placeholder: "https://ipam.example.lan" },
{ key: "appId", label: "API app ID", secret: false, placeholder: "as set under Administration → API" },
{ key: "token", label: "App token (API code)", secret: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
pbs: [
{ key: "url", label: "Proxmox Backup Server URL", secret: false, placeholder: "https://pbs.example.lan:8007" },
{ key: "tokenId", label: "API token ID", secret: false, placeholder: "root@pam!homelab-manager" },
{ key: "tokenSecret", label: "API token secret", secret: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
unifi: [
{ key: "url", label: "UniFi controller URL", secret: false, placeholder: "https://unifi.example.lan (or https://host:8443 for a self-hosted controller)" },
{
key: "apiKey",
label: "API key (Network 9 or later)",
secret: true,
optional: true,
type: "password",
placeholder: "made under Settings → Control Plane → Integrations; leave blank to log in instead",
},
{ key: "username", label: "Username (instead of an API key)", secret: false, optional: true, placeholder: "a local, read-only account — not a Ubiquiti cloud account" },
{ key: "password", label: "Password (instead of an API key)", secret: true, optional: true, type: "password" },
{ key: "site", label: "Only this site (optional)", secret: false, optional: true, placeholder: "the site's name as shown in UniFi; blank reads every site" },
{ key: "selfHosted", label: "A self-hosted Network application, not a UniFi OS console (UDM, Cloud Gateway, Cloud Key)", secret: false, type: "checkbox" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
npm: [
{ key: "url", label: "Nginx Proxy Manager URL", secret: false, placeholder: "https://npm.example.lan:81 (its admin page)" },
{ key: "email", label: "Email of a user that may view", secret: false, placeholder: "a dedicated user with view-only access to proxy hosts and certificates" },
{ key: "password", label: "Password", secret: true, type: "password" },
{ key: "manageEmail", label: "Email of a user that may manage (optional)", secret: false, optional: true, placeholder: "only to make, change and delete proxy hosts from here; a user with Manage on Proxy Hosts, without two-factor sign-in" },
{ key: "managePassword", label: "Password of that user (optional)", secret: true, optional: true, type: "password" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
homeassistant: [
{ key: "url", label: "Home Assistant URL", secret: false, placeholder: "https://homeassistant.example.lan:8123" },
{ key: "token", label: "Long-lived access token", secret: true, type: "password", placeholder: "made on your profile page in Home Assistant" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
nextcloud: [
{ key: "url", label: "Nextcloud URL", secret: false, placeholder: "https://cloud.example.lan" },
{ key: "username", label: "Administrator's name (optional)", secret: false, optional: true, placeholder: "for the disk, the users and the app updates" },
{ key: "appPassword", label: "App password (optional)", secret: true, optional: true, type: "password", placeholder: "Personal settings → Security → Devices & sessions" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
speedtest: [
{ key: "url", label: "Speedtest Tracker URL", secret: false, placeholder: "http://speedtest.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "profile menu → API tokens, with the results:read ability" },
{ key: "expectedDownload", label: "Download you pay for, Mbit/s (optional)", secret: false, optional: true, placeholder: "300 — alerts only judge what you give" },
{ key: "expectedUpload", label: "Upload you pay for, Mbit/s (optional)", secret: false, optional: true, placeholder: "30" },
{ key: "minPercent", label: "Warn below this share of it, % (optional)", secret: false, optional: true, placeholder: "60" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
hetzner: [{ key: "token", label: "API token", secret: true, type: "password", placeholder: "Hetzner Console → the project → Security → API tokens; Read is enough" }],
hetznerrobot: [
{ key: "user", label: "Webservice user name", secret: false, placeholder: "#ws+… (Robot → Settings → Webservice and app settings)" },
{ key: "password", label: "Webservice password", secret: true, type: "password", placeholder: "the webservice user's own password, not the Robot login" },
],
sonarr: [
{ key: "url", label: "Sonarr URL", secret: false, placeholder: "http://sonarr.example.lan:8989" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → General → Security → API Key" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
radarr: [
{ key: "url", label: "Radarr URL", secret: false, placeholder: "http://radarr.example.lan:7878" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → General → Security → API Key" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
lidarr: [
{ key: "url", label: "Lidarr URL", secret: false, placeholder: "http://lidarr.example.lan:8686" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → General → Security → API Key" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
readarr: [
{ key: "url", label: "Readarr URL", secret: false, placeholder: "http://readarr.example.lan:8787" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → General → Security → API Key" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
prowlarr: [
{ key: "url", label: "Prowlarr URL", secret: false, placeholder: "http://prowlarr.example.lan:9696" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → General → Security → API Key" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
qbittorrent: [
{ key: "url", label: "qBittorrent Web UI URL", secret: false, placeholder: "http://qbittorrent.example.lan:8080" },
{ key: "username", label: "User name (optional)", secret: false, optional: true, placeholder: "empty when qBittorrent lets this address in without signing in" },
{ key: "password", label: "Password (optional)", secret: true, optional: true, type: "password", placeholder: "Tools → Options → Web UI" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
sabnzbd: [
{ key: "url", label: "SABnzbd URL", secret: false, placeholder: "http://sabnzbd.example.lan:8080" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Config → General → Security → API Key (the API key, not the NZB key)" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
adguard: [
{ key: "url", label: "AdGuard Home URL", secret: false, placeholder: "http://adguard.example.lan:3000" },
{ key: "username", label: "User name (optional)", secret: false, optional: true, placeholder: "empty when AdGuard Home has no sign-in" },
{ key: "password", label: "Password (optional)", secret: true, optional: true, type: "password" },
{ key: "dnsHost", label: "DNS server address (optional)", secret: false, optional: true, placeholder: "the host of the URL — only if its DNS server is somewhere else" },
{ key: "probeDomain", label: "Name to test DNS with (optional)", secret: false, optional: true, placeholder: "example.com" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
technitium: [
{ key: "url", label: "Technitium web console URL", secret: false, placeholder: "http://dns.example.lan:5380" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "Administration → Sessions → Create Token (a user who may view the dashboard, settings and zones)" },
{ key: "dnsHost", label: "DNS server address (optional)", secret: false, optional: true, placeholder: "the host of the URL — only if its DNS server is somewhere else" },
{ key: "probeDomain", label: "Name to test DNS with (optional)", secret: false, optional: true, placeholder: "example.com" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
grafana: [
{ key: "url", label: "Grafana URL", secret: false, placeholder: "http://grafana.example.lan:3000" },
{ key: "token", label: "Service account token", secret: true, type: "password", placeholder: "Administration → Service accounts → add a token (role Viewer)" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
fragnet: [
{ key: "token", label: "API key", secret: true, type: "password", placeholder: "ptlc_… — the game panel: profile → API Credentials (not an Application key, ptla_)" },
{ key: "url", label: "Panel address (optional)", secret: false, optional: true, placeholder: "https://panel.fragnet.net — only if yours is somewhere else" },
{ key: "backupDays", label: "Warn when the newest backup is older than, days (optional)", secret: false, optional: true, placeholder: "7 — 0 to not judge backups" },
{ key: "fullPercent", label: "Warn when disk or memory is fuller than, % (optional)", secret: false, optional: true, placeholder: "90" },
{ key: "ignoreBackups", label: "Servers whose backups are not judged (optional)", secret: false, optional: true, placeholder: "names, separated by commas" },
{ key: "muteDisk", label: "Do not alert about disk space (the page still shows it)", secret: false, optional: true, type: "checkbox" },
{ key: "muteMemory", label: "Do not alert about memory (the page still shows it)", secret: false, optional: true, type: "checkbox" },
{ key: "muteBackups", label: "Do not alert about backups (the page still shows them)", secret: false, optional: true, type: "checkbox" },
],
netbox: [
{ key: "url", label: "NetBox URL", secret: false, placeholder: "https://netbox.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "your profile → API Tokens; read-only is enough" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
n8n: [
{ key: "url", label: "n8n URL", secret: false, placeholder: "http://n8n.example.lan:5678" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Settings → n8n API" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
paperless: [
{ key: "url", label: "Paperless-ngx URL", secret: false, placeholder: "http://paperless.example.lan:8000" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "your profile → API Auth Token; a superuser's, for the system status" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
immich: [
{ key: "url", label: "Immich URL", secret: false, placeholder: "http://immich.example.lan:2283" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "Account Settings → API Keys; read permissions are enough" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
prometheus: [
{ key: "url", label: "Prometheus URL", secret: false, placeholder: "http://prometheus.example.lan:9090" },
{ key: "token", label: "Bearer token (optional)", secret: true, optional: true, type: "password", placeholder: "only if something in front of Prometheus asks for one" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
authentik: [
{ key: "url", label: "Authentik URL", secret: false, placeholder: "https://auth.example.lan" },
{ key: "token", label: "API token", secret: true, type: "password", placeholder: "Directory → Tokens and App passwords, intent API Token" },
{ key: "writeToken", label: "Token for making and managing users (optional)", secret: true, optional: true, type: "password", placeholder: "only to make, switch off and delete users from here; an account that may. Leave blank to only watch" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
jellyfin: [
{ key: "url", label: "Jellyfin URL", secret: false, placeholder: "http://jellyfin.example.lan:8096" },
{ key: "apiKey", label: "API key", secret: true, type: "password", placeholder: "made under Dashboard → API Keys in Jellyfin" },
{ key: "insecure", label: "Allow self-signed certificate", secret: false, type: "checkbox" },
],
ups: [
{ key: "host", label: "Host name or address", secret: false, placeholder: "the machine running NUT (upsd), or the UPS's network card" },
{ key: "snmp", label: "Read it over SNMP (version 2c) instead of NUT", secret: false, type: "checkbox" },
{ key: "port", label: "Port", secret: false, optional: true, placeholder: "3493 for NUT, 161 for SNMP" },
{ key: "upsName", label: "NUT: the UPS's name", secret: false, optional: true, placeholder: "as in ups.conf; the first one listed when blank" },
{ key: "community", label: "SNMP: read community", secret: true, optional: true, type: "password", placeholder: "public when blank" },
],
osticket: [
{ key: "host", label: "Database host", secret: false, placeholder: "osticket-db.example.lan" },
{ key: "port", label: "Database port", secret: false, optional: true, placeholder: "3306" },
{ key: "database", label: "Database name", secret: false, placeholder: "osticket" },
{ key: "username", label: "Database username", secret: false, placeholder: "read-only user" },
{ key: "password", label: "Database password", secret: true, type: "password" },
{
key: "tablePrefix",
label: "Table prefix",
secret: false,
optional: true,
placeholder: "ost_ (osTicket's default, unless changed at install)",
},
// Only for opening tickets from alerts (Alert settings → Alert tickets). The rest of this integration reads the database and never writes.
{
key: "apiUrl",
label: "Ticket API address (optional)",
secret: false,
optional: true,
placeholder: "https://osticket.example.lan/ (the folder that contains api/tickets.json)",
},
{ key: "apiKey", label: "Ticket API key (optional)", secret: true, optional: true, type: "password" },
{ key: "apiInsecure", label: "Allow self-signed certificate (ticket API)", secret: false, type: "checkbox" },
// Only for closing a ticket from the Alerts page. osTicket's API cannot close tickets, so this writes to its database (src/integrations/osticket/closeTicket.ts): a separate login, never the read-only one above.
{ key: "closeUsername", label: "Database username for closing tickets (optional)", secret: false, optional: true, placeholder: "a separate user that may update tickets — see INTEGRATIONS.md" },
{ key: "closePassword", label: "Database password for closing tickets (optional)", secret: true, optional: true, type: "password" },
],
};
/** Fixed base URL per integration type, stored on the row for display/reference. */
export const INTEGRATION_BASE_URLS: Partial<Record<IntegrationType, string>> = {
tailscale: "https://api.tailscale.com",
hetzner: "https://api.hetzner.cloud",
hetznerrobot: "https://robot-ws.your-server.de",
fragnet: "https://panel.fragnet.net",
};
/**
* Resolves the value to store in the integrations.baseUrl column: types that
* collect their own URL as a config field (e.g. Gitea) use that; others fall
* back to a fixed constant (e.g. Tailscale's API is always api.tailscale.com).
*/
export function resolveBaseUrl(
type: IntegrationType,
nonSecretFields: Record<string, string | boolean | undefined>,
): string {
const url = nonSecretFields.url;
if (typeof url === "string" && url) return url;
// A UPS has no web address; the host it is read from is what the card shows.
const host = nonSecretFields.host;
if (type === "ups" && typeof host === "string" && host) return host;
return INTEGRATION_BASE_URLS[type] ?? "";
}
export function splitIntegrationConfig(
type: IntegrationType,
input: Record<string, string | boolean>,
): { secretFields: Record<string, string | boolean>; nonSecretFields: Record<string, string | boolean> } {
const fields = INTEGRATION_FIELDS[type] ?? [];
const secretFields: Record<string, string | boolean> = {};
const nonSecretFields: Record<string, string | boolean> = {};
for (const field of fields) {
if (input[field.key] === undefined) continue;
if (field.secret) secretFields[field.key] = input[field.key];
else nonSecretFields[field.key] = input[field.key];
}
return { secretFields, nonSecretFields };
}
export function validateIntegrationConfig(
type: IntegrationType,
merged: Record<string, string | boolean | undefined>,
): string[] {
const fields = INTEGRATION_FIELDS[type] ?? [];
const missing = fields
.filter((f) => f.type !== "checkbox" && !f.optional)
.filter((f) => merged[f.key] === undefined || merged[f.key] === "")
.map((f) => f.key);
// UniFi takes an API key, or a username with its password: one way in is required, which no single field says.
if (type === "unifi") {
const has = (k: string) => typeof merged[k] === "string" && (merged[k] as string).trim() !== "";
if (!has("apiKey") && !(has("username") && has("password"))) missing.push(has("username") ? "password" : "apiKey");
}
return missing;
}