feat: add Uptime Kuma, Audiobookshelf, Paperless-ngx, and Navidrome integrations (#5910)

This commit is contained in:
Thomas authored and GitHub committed 2026-06-10 18:27:24 +02:00
1 parent a4db9cf0dc
commit d77c6f8d4e
46 files changed
+2994 -16

No files matched your search

@@ -0,0 +1,162 @@
import { Response } from "undici";
import { beforeEach, describe, expect, test, vi } from "vitest";
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import type { IntegrationSecret } from "../../base/types";
import { UptimeKumaIntegration } from "../uptime-kuma-integration";
import { uptimeKumaHeartbeatCategoryMap } from "../uptime-kuma-types";
vi.mock("@homarr/core/infrastructure/http", () => ({
fetchWithTrustedCertificatesAsync: vi.fn(),
}));
const TEST_URL = "https://uptime.example.com";
const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
const toUrlString = (url: unknown): string => String(url);
const createIntegration = (secrets: IntegrationSecret[] = []) =>
new UptimeKumaIntegration({
id: "test-uptime-kuma",
name: "Test Uptime Kuma",
url: TEST_URL,
externalUrl: null,
decryptedSecrets: secrets,
});
beforeEach(() => {
mockFetch.mockReset();
});
describe("uptimeKumaHeartbeatCategoryMap", () => {
test("maps status 0 (down) to 'down'", () => {
expect(uptimeKumaHeartbeatCategoryMap[0]).toBe("down");
});
test("maps status 1 (up) to 'up'", () => {
expect(uptimeKumaHeartbeatCategoryMap[1]).toBe("up");
});
test("maps status 2 (pending) to 'paused'", () => {
expect(uptimeKumaHeartbeatCategoryMap[2]).toBe("paused");
});
test("maps status 3 (maintenance) to 'paused'", () => {
expect(uptimeKumaHeartbeatCategoryMap[3]).toBe("paused");
});
test("returns undefined for unknown status codes", () => {
expect(uptimeKumaHeartbeatCategoryMap[99]).toBeUndefined();
});
});
describe("UptimeKumaIntegration.getDashboardDataAsync", () => {
const statusPageResponse = {
publicGroupList: [
{
id: 1,
name: "Services",
monitorList: [
{ id: 10, name: "Web" },
{ id: 20, name: "API" },
{ id: 30, name: "DB" },
],
},
],
};
const heartbeatResponse = {
heartbeatList: {
"10": [{ status: 1, time: "2025-01-01" }],
"20": [{ status: 0, time: "2025-01-01" }],
"30": [{ status: 2, time: "2025-01-01" }],
},
uptimeList: {
"10_24": 0.995,
"20_24": 0.5,
"30_24": 0.8,
},
};
const mockResponses = () => {
mockFetch.mockImplementation((url) => {
const urlStr = toUrlString(url);
if (urlStr.includes("/heartbeat/")) {
return Promise.resolve(
new Response(JSON.stringify(heartbeatResponse), { status: 200 }),
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
}
return Promise.resolve(
new Response(JSON.stringify(statusPageResponse), { status: 200 }),
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
});
};
test("aggregates monitor counts correctly", async () => {
mockResponses();
const integration = createIntegration([{ kind: "slug", value: "default" }]);
const result = await integration.getDashboardDataAsync();
expect(result.totalMonitors).toBe(3);
expect(result.upCount).toBe(1);
expect(result.downCount).toBe(1);
expect(result.pausedCount).toBe(1);
});
test("computes average uptime from uptimeList", async () => {
mockResponses();
const integration = createIntegration([{ kind: "slug", value: "default" }]);
const result = await integration.getDashboardDataAsync();
const expectedAverage = ((0.995 + 0.5 + 0.8) * 100) / 3;
expect(result.averageUptimePercent).toBeCloseTo(expectedAverage, 5);
});
test("defaults unknown heartbeat status to 'down'", async () => {
const unknownHeartbeat = {
heartbeatList: { "10": [{ status: 99, time: "2025-01-01" }] },
uptimeList: { "10_24": 1 },
};
mockFetch.mockImplementation((url) => {
const urlStr = toUrlString(url);
if (urlStr.includes("/heartbeat/")) {
return Promise.resolve(
new Response(JSON.stringify(unknownHeartbeat), { status: 200 }),
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
}
return Promise.resolve(
new Response(
JSON.stringify({
publicGroupList: [{ id: 1, name: "G", monitorList: [{ id: 10, name: "Svc" }] }],
}),
{ status: 200 },
),
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
});
const integration = createIntegration([{ kind: "slug", value: "default" }]);
const result = await integration.getDashboardDataAsync();
expect(result.monitors[0]?.status).toBe("down");
expect(result.downCount).toBe(1);
});
test("handles empty monitor list gracefully", async () => {
mockFetch.mockImplementation(
() =>
Promise.resolve(
new Response(JSON.stringify({ publicGroupList: [], heartbeatList: {}, uptimeList: {} }), { status: 200 }),
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>,
);
const integration = createIntegration([{ kind: "slug", value: "default" }]);
const result = await integration.getDashboardDataAsync();
expect(result.totalMonitors).toBe(0);
expect(result.averageUptimePercent).toBe(0);
});
});
@@ -0,0 +1,140 @@
import { ParseError, ResponseError } from "@homarr/common/server";
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import type { IntegrationTestingInput } from "../base/integration";
import { Integration } from "../base/integration";
import { TestConnectionError } from "../base/test-connection/test-connection-error";
import type { TestingResult } from "../base/test-connection/test-connection-service";
import {
uptimeKumaHeartbeatCategoryMap,
uptimeKumaHeartbeatResponseSchema,
uptimeKumaStatusPageResponseSchema,
} from "./uptime-kuma-types";
import type { UptimeKumaDashboardData, UptimeKumaMonitor, UptimeKumaMonitorCategory } from "./uptime-kuma-types";
export class UptimeKumaIntegration extends Integration {
protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
const statusPageResponse = await input.fetchAsync(this.statusPageUrl());
if (!statusPageResponse.ok) {
return TestConnectionError.StatusResult(statusPageResponse);
}
const statusPageParsed = uptimeKumaStatusPageResponseSchema.safeParse(await statusPageResponse.json());
if (!statusPageParsed.success) {
return TestConnectionError.ParseResult(
new ParseError("Invalid Uptime Kuma status page response", { cause: statusPageParsed.error }),
);
}
const heartbeatResponse = await input.fetchAsync(this.heartbeatUrl());
if (!heartbeatResponse.ok) {
return TestConnectionError.StatusResult(heartbeatResponse);
}
const heartbeatParsed = uptimeKumaHeartbeatResponseSchema.safeParse(await heartbeatResponse.json());
if (!heartbeatParsed.success) {
return TestConnectionError.ParseResult(
new ParseError("Invalid Uptime Kuma heartbeat response", { cause: heartbeatParsed.error }),
);
}
return { success: true };
}
public async getDashboardDataAsync(): Promise<UptimeKumaDashboardData> {
const [statusPageResponse, heartbeatResponse] = await Promise.all([
this.getStatusPageAsync(),
this.getHeartbeatAsync(),
]);
const statusPage = uptimeKumaStatusPageResponseSchema.parse(await statusPageResponse.json());
const heartbeat = uptimeKumaHeartbeatResponseSchema.parse(await heartbeatResponse.json());
const monitors = statusPage.publicGroupList.flatMap((group) =>
group.monitorList.map((monitor) => this.mapMonitor(monitor, heartbeat)),
);
return this.buildDashboardData(monitors);
}
private mapMonitor(
monitor: { id: number; name: string },
heartbeat: { heartbeatList: Record<string, { status: number }[]>; uptimeList: Record<string, number> },
): UptimeKumaMonitor {
const heartbeats = heartbeat.heartbeatList[String(monitor.id)] ?? [];
const latestHeartbeat = heartbeats.at(-1);
const uptimeKey = `${monitor.id}_24`;
const uptimeRaw = heartbeat.uptimeList[uptimeKey];
const uptimePercent24h = typeof uptimeRaw === "number" ? uptimeRaw * 100 : null;
const status: UptimeKumaMonitorCategory =
(latestHeartbeat && (uptimeKumaHeartbeatCategoryMap[latestHeartbeat.status] ?? "down")) || "paused";
return {
id: monitor.id,
name: monitor.name,
status,
uptimePercent24h,
};
}
private buildDashboardData(monitors: UptimeKumaMonitor[]): UptimeKumaDashboardData {
const counts = monitors.reduce(
(acc, monitor) => {
acc[monitor.status] += 1;
return acc;
},
{ up: 0, down: 0, paused: 0 },
);
const uptimeValues = monitors
.map((monitor) => monitor.uptimePercent24h)
.filter((value): value is number => value !== null);
const averageUptimePercent = uptimeValues.reduce((sum, value) => sum + value, 0) / Math.max(uptimeValues.length, 1);
return {
totalMonitors: monitors.length,
upCount: counts.up,
downCount: counts.down,
pausedCount: counts.paused,
averageUptimePercent,
monitors,
};
}
private async fetchOkAsync(url: string | URL) {
const response = await fetchWithTrustedCertificatesAsync(url);
if (!response.ok) {
throw new ResponseError(response);
}
return response;
}
private getStatusPageAsync() {
return this.fetchOkAsync(this.statusPageUrl());
}
private getHeartbeatAsync() {
return this.fetchOkAsync(this.heartbeatUrl());
}
private statusPageUrl() {
return this.url(`/api/status-page/${this.getSlug()}`);
}
private heartbeatUrl() {
return this.url(`/api/status-page/heartbeat/${this.getSlug()}`);
}
private getSlug() {
if (this.hasSecretValue("slug")) {
return this.getSecretValue("slug").toLowerCase();
}
return "default";
}
}
@@ -0,0 +1,62 @@
import { z } from "zod";
export const uptimeKumaHeartbeatStatus = {
down: 0,
up: 1,
pending: 2,
maintenance: 3,
} as const;
export type UptimeKumaMonitorCategory = "up" | "down" | "paused";
export const uptimeKumaHeartbeatCategoryMap: Record<number, UptimeKumaMonitorCategory> = {
[uptimeKumaHeartbeatStatus.down]: "down",
[uptimeKumaHeartbeatStatus.up]: "up",
[uptimeKumaHeartbeatStatus.pending]: "paused",
[uptimeKumaHeartbeatStatus.maintenance]: "paused",
};
export const uptimeKumaStatusPageMonitorSchema = z.object({
id: z.number().int(),
name: z.string(),
});
export const uptimeKumaStatusPageGroupSchema = z.object({
id: z.number().int(),
name: z.string(),
monitorList: z.array(uptimeKumaStatusPageMonitorSchema),
});
export const uptimeKumaStatusPageResponseSchema = z.object({
publicGroupList: z.array(uptimeKumaStatusPageGroupSchema),
});
export const uptimeKumaHeartbeatEntrySchema = z.object({
status: z.number().int(),
time: z.string(),
ping: z.number().nullable().optional(),
});
export const uptimeKumaHeartbeatResponseSchema = z.object({
heartbeatList: z.record(z.string(), z.array(uptimeKumaHeartbeatEntrySchema)),
uptimeList: z.record(z.string(), z.number()),
});
export interface UptimeKumaMonitor {
id: number;
name: string;
status: UptimeKumaMonitorCategory;
uptimePercent24h: number | null;
}
export interface UptimeKumaDashboardData {
totalMonitors: number;
upCount: number;
downCount: number;
pausedCount: number;
averageUptimePercent: number;
monitors: UptimeKumaMonitor[];
}
export type UptimeKumaStatusPageResponse = z.infer<typeof uptimeKumaStatusPageResponseSchema>;
export type UptimeKumaHeartbeatResponse = z.infer<typeof uptimeKumaHeartbeatResponseSchema>;