UniFi integration: network devices, Wi-Fi and networks, as part of the dependency map

A UniFi controller (API key on Network 9+, or a read-only local login on any
version) is read every five minutes. Its switches, access points and gateways
are kept with state, IP, uptime, firmware and uplink; its networks and Wi-Fi
names beside them (passphrases are never read). Nothing is written to the
controller.

Network > Network devices lists them. Devices are a new node type in the
dependency map: uplinks become dependencies by themselves, others can be
written by hand. A device offline past a limit is an offline alert, folds what
depends on it, can be silenced with maintenance and have runbooks.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-20 00:35:48 +02:00
1 parent 73a06ebe63
commit 396e074108
48 files changed
+6893 -102

No files matched your search

+78 -5
View File
@@ -173,10 +173,10 @@ export interface SessionSummary {
expiresAt: string | null;
}
export type MaintenanceTargetType = "server" | "integration" | "dns_provider";
export type MaintenanceTargetType = "server" | "integration" | "dns_provider" | "device";
/** A whole group at once: every server, every enabled integration, every enabled DNS provider, or all of those. */
export type MaintenanceBulkScope = "everything" | "servers" | "integrations" | "dns_providers";
export type MaintenanceBulkScope = "everything" | "servers" | "integrations" | "dns_providers" | "devices";
export interface MaintenanceWindow {
id: number;
@@ -206,6 +206,8 @@ export interface MaintenanceTargets {
servers: { id: number; name: string }[];
integrations: { id: number; name: string; type: string }[];
dnsProviders: { id: number; name: string; providerType: string }[];
/** Network devices read from a UniFi controller. */
devices: { id: number; name: string; kind: string }[];
}
export interface AuditLogEntry {
@@ -512,6 +514,8 @@ export interface HealthCheckSettings {
newPortAlerts: boolean;
/** An alert raised this many times within an hour is "flapping": one message says so and its further messages are held until it has been quiet for an hour. 0 is off. */
flapRaises: number;
/** Minutes a UniFi device may be offline before it is raised. */
deviceOfflineMinutes: number;
}
/** The monthly report: last month's availability, incidents, updates and renewals, in one message on a day of the month. */
@@ -1109,7 +1113,7 @@ export interface LifecycleReport {
export type AssetKind = "server" | "storage" | "network" | "power" | "client" | "other";
export type DependencyNodeType = "server" | "integration";
export type DependencyNodeType = "server" | "integration" | "device";
/** Something that would be affected if another went down (or that it needs): `distance` 1 is directly, 2 through one other, and so on. */
export interface DependencyImpactItem {
@@ -1136,7 +1140,7 @@ export interface DependencyGraphNode {
export interface DependencyGraph {
nodes: DependencyGraphNode[];
/** From the thing that is needed to the thing that needs it. */
edges: { from: string; to: string; kind: "written" | "runs-on" }[];
edges: { from: string; to: string; kind: "written" | "runs-on" | "uplink" }[];
}
export interface DependencyNode {
key: string;
@@ -1152,6 +1156,71 @@ export interface DependenciesResponse {
nodes: DependencyNode[];
}
export type NetworkDeviceKind = "gateway" | "switch" | "access_point" | "other";
export type NetworkDeviceState = "online" | "offline" | "updating" | "pending" | "other";
/** A switch, access point or gateway read from a UniFi controller. */
export interface NetworkDevice {
id: number;
integrationId: number;
integrationName: string;
siteName: string | null;
name: string;
model: string | null;
kind: NetworkDeviceKind;
ip: string | null;
mac: string | null;
state: NetworkDeviceState;
uptimeSeconds: number | null;
firmware: string | null;
firmwareUpdatable: boolean;
/** The device it is connected through, as the controller says. */
uplink: { id: number; name: string } | null;
offlineSince: string | null;
lastOnlineAt: string | null;
updatedAt: string;
/** How many things need it (directly or through others), and how many it needs. */
dependents: number;
needs: number;
inMaintenance: boolean;
}
/** A network (VLAN) or a Wi-Fi name a controller has set up. */
export interface NetworkSegment {
id: number;
integrationId: number;
integrationName: string;
externalId: string;
siteName: string | null;
name: string;
enabled: boolean;
vlanId: number | null;
subnet: string | null;
purpose: string | null;
security: string | null;
networkName: string | null;
updatedAt: string;
}
export interface UnifiSyncStatus {
/** When the controller was last read successfully. */
at: string;
ok: boolean;
error: string | null;
sites: string[];
mode: "api_key" | "login" | null;
devices: number;
networks: number;
ssids: number;
}
export interface NetworkOverview {
integrations: { id: number; name: string; enabled: boolean; status: UnifiSyncStatus | null }[];
devices: NetworkDevice[];
networks: NetworkSegment[];
ssids: NetworkSegment[];
}
/** A piece of hardware in the inventory. */
export interface Asset {
id: number;
@@ -1566,7 +1635,7 @@ export interface ManualTaskInput {
enabled?: boolean;
}
export type IntegrationType = "proxmox" | "synology" | "semaphore" | "tailscale" | "gitea" | "dockhand" | "uptimekuma" | "phpipam" | "pbs" | "osticket";
export type IntegrationType = "proxmox" | "synology" | "semaphore" | "tailscale" | "gitea" | "dockhand" | "uptimekuma" | "phpipam" | "pbs" | "osticket" | "unifi";
export interface IntegrationField {
key: string;
@@ -2154,6 +2223,10 @@ export const api = {
request<{ minSeverity: string | null; categories: AlertCategory[] | null }>(`/api/push/${id}`, { method: "PATCH", body: JSON.stringify(data) }),
test: () => request<{ sent: number; removed: number; failed: number }>("/api/push/test", { method: "POST" }),
},
network: {
overview: () => request<NetworkOverview>("/api/network"),
sync: (integrationId?: number) => request<{ statuses: Record<number, UnifiSyncStatus> }>("/api/network/sync", { method: "POST", body: JSON.stringify(integrationId ? { integrationId } : {}) }),
},
dependencies: {
list: () => request<DependenciesResponse>("/api/dependencies"),
impact: (type: DependencyNodeType, id: number) => request<DependencyImpact>(`/api/dependencies/impact?type=${type}&id=${id}`),