feat(integrations): add UnifiOsIntegration with optional cloud enrichment

Introduces UnifiOsIntegration, orchestrating UnifiOsApi (local) and
UnifiSmApi (optional cloud) to build the UnifiOsSummary. Local endpoint
calls degrade independently via Promise.allSettled; the cloud client is
never instantiated without a configured siteManagerApiKey secret.
Registers the unifiOs kind in the integration creator, index, and types
barrels, resolving the previously-failing typecheck.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
zacharyandClaude Opus 5 committed 2026-10-08 00:22:04 +02:00
1 parent 2de3063dc1
commit 0abde13101
6 files changed
+323

No files matched your search

@@ -0,0 +1,197 @@
// @vitest-environment node
import { Response } from "undici";
import { beforeEach, describe, expect, test, vi } from "vitest";
vi.hoisted(() => {
process.env.SKIP_ENV_VALIDATION = "true";
process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
});
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import type { IntegrationSecret } from "../../base/types";
import { UnifiSmApi } from "../unifi-sm-api";
import { UnifiOsIntegration } from "../unifi-os-integration";
vi.mock("@homarr/core/infrastructure/http", () => ({
fetchWithTrustedCertificatesAsync: vi.fn(),
}));
const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
const GATEWAY_MAC = "aa:bb:cc:11:22:33";
const jsonResponse = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
const page = (data: unknown[]) => ({ offset: 0, limit: 200, count: data.length, totalCount: data.length, data });
const localRoutes: Record<string, unknown> = {
"/info": { applicationVersion: "10.6.102" },
"/sites": page([{ id: "site-1", name: "Example site", internalReference: "default" }]),
"/sites/site-1/clients": page([
{ id: "c1", name: "a", type: "WIRED", access: { type: "DEFAULT" } },
{ id: "c2", name: "b", type: "WIRELESS", access: { type: "DEFAULT" } },
]),
"/sites/site-1/devices": page([
{
id: "gw",
name: "Gateway",
model: "UXG Pro",
macAddress: GATEWAY_MAC,
state: "ONLINE",
firmwareUpdatable: true,
features: ["gateway"],
},
{
id: "sw",
name: "Switch",
model: "USW Lite 8",
macAddress: "aa:bb:cc:99:88:77",
state: "OFFLINE",
firmwareUpdatable: false,
features: ["switching"],
},
]),
"/sites/site-1/devices/gw/statistics/latest": {
uptimeSec: 1009049,
cpuUtilizationPct: 19.1,
memoryUtilizationPct: 63.1,
uplink: { txRateBps: 14140912, rxRateBps: 3346784 },
},
"/sites/site-1/vpn/servers": page([{ id: "v1", name: "vpn", enabled: true }]),
};
const routeLocal = (rawUrl: string): Response | null => {
const path = new URL(rawUrl).pathname.replace("/proxy/network/integration/v1", "");
const body = localRoutes[path];
return body === undefined ? null : jsonResponse(body);
};
const createIntegration = (decryptedSecrets: IntegrationSecret[]) =>
new UnifiOsIntegration({
id: "test-unifi-os",
name: "Test UniFi OS",
url: "https://console.example.test",
externalUrl: null,
decryptedSecrets,
});
const localOnlySecrets: IntegrationSecret[] = [{ kind: "apiKey", value: "local-key" }];
const hybridSecrets: IntegrationSecret[] = [
{ kind: "apiKey", value: "local-key" },
{ kind: "siteManagerApiKey", value: "cloud-key" },
];
beforeEach(() => {
mockFetch.mockReset();
UnifiSmApi.clearCache();
});
describe("UnifiOsIntegration getUnifiOsSummaryAsync", () => {
test("builds the summary from the local API alone", async () => {
mockFetch.mockImplementation(async (url) => routeLocal(String(url)) ?? jsonResponse({}, 404));
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
expect(summary.site).toEqual({ id: "site-1", name: "Example site", applicationVersion: "10.6.102" });
expect(summary.clients).toEqual({ total: 2, wired: 1, wireless: 1, vpn: 0, guests: 0 });
expect(summary.devices).toEqual({ total: 2, online: 1, offline: 1, firmwareUpdatable: 1 });
expect(summary.wan.state).toBe("online");
expect(summary.wan.throughput).toEqual({ txBps: 14140912, rxBps: 3346784 });
expect(summary.gateway).toMatchObject({ name: "Gateway", uptimeSec: 1009049, cpuPct: 19.1 });
});
test("leaves the ISP block null when no Site Manager key is configured", async () => {
mockFetch.mockImplementation(async (url) => routeLocal(String(url)) ?? jsonResponse({}, 404));
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
expect(summary.wan.isp).toBeNull();
expect(mockFetch.mock.calls.every(([url]) => !String(url).startsWith("https://api.ui.com"))).toBe(true);
});
test("fills the ISP block when a Site Manager key is configured", async () => {
mockFetch.mockImplementation(async (url) => {
const raw = String(url);
if (raw.startsWith("https://api.ui.com/v1/sites")) {
return jsonResponse({
data: [
{
siteId: "cloud-1",
hostId: "host-1",
meta: { gatewayMac: GATEWAY_MAC },
statistics: { wans: { WAN: { externalIp: "203.0.113.10" } } },
},
],
});
}
if (raw.includes("isp-metrics")) {
return jsonResponse({
data: {
metrics: [
{
periods: [
{
metricTime: "2026-09-08T09:10:00Z",
data: {
wan: { avgLatency: 11, maxLatency: 12, packetLoss: 0, uptime: 100, ispName: "Example ISP" },
},
},
],
},
],
},
});
}
return routeLocal(raw) ?? jsonResponse({}, 404);
});
const summary = await createIntegration(hybridSecrets).getUnifiOsSummaryAsync();
expect(summary.wan.isp).toMatchObject({ name: "Example ISP", latencyMs: 11, externalIp: "203.0.113.10" });
expect(summary.wan.isp?.measuredAt).toEqual(new Date("2026-09-08T09:10:00Z"));
});
test("degrades only the affected block when one local endpoint fails", async () => {
mockFetch.mockImplementation(async (url) => {
const raw = String(url);
if (raw.includes("/vpn/servers")) return jsonResponse({ error: "boom" }, 500);
return routeLocal(raw) ?? jsonResponse({}, 404);
});
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
expect(summary.clients.total).toBe(2);
expect(summary.devices.total).toBe(2);
});
test("keeps clients and devices when the gateway cannot be identified", async () => {
mockFetch.mockImplementation(async (url) => {
const raw = String(url);
if (raw.endsWith("/devices?limit=200")) {
return jsonResponse(
page([
{
id: "sw",
name: "Switch",
model: "USW Lite 8",
macAddress: "aa:bb:cc:99:88:77",
state: "ONLINE",
firmwareUpdatable: false,
features: ["switching"],
},
]),
);
}
return routeLocal(raw) ?? jsonResponse({}, 404);
});
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
expect(summary.gateway).toBeNull();
expect(summary.wan.throughput).toBeNull();
expect(summary.wan.state).toBe("unknown");
expect(summary.clients.total).toBe(2);
});
});