Skip to main content

Unifi Fabric

@sntxrr/unifi-fabricv2026.10.14.1· MIT(was none)· 1mo agoBEHAVIORS
01README

Structural health monitoring for a UniFi fabric. The @sntxrr/unifi-fabric/topology model's check method compares a declared topology against live /stat/device rows and reports the failures that outcome-based monitoring cannot see: a device expected on the wire that has silently fallen back to a wireless mesh uplink, attachment to the wrong upstream device, links negotiated below their expected speed, ports carrying error counters, and — the one with no equivalent elsewhere — ports that are down but have carried real traffic before, which identifies a run that used to work. The first three are detectors and gate inSync; error counters and dark ports are cumulative totals rather than rates, so both are reported as diagnostics and deliberately do not, since a single snapshot cannot tell a severed run from a client that went to sleep. An access point that loses its wired uplink does not fail; it meshes, keeps serving clients, and every uptime check stays green while latency quietly goes from sub-millisecond to tens of milliseconds and jittery. uplink.type flipping from wire to wireless is a boolean, so it is asserted exactly rather than thresholded. Read-only: never writes to the controller. Emits a flat Prometheus-ready metric series alongside the verdict, including for healthy devices, so alerts can fire on a series dropping to zero rather than on a document changing shape. Authenticates with an API key over X-API-KEY, which sidesteps the HTTP 499 that MFA-enabled SSO accounts return for password logins.

02Release Notes

Declare SPDX license (MIT) in manifest.

03Behaviors1
@sntxrr/unifi-fabric/topologyv2026.10.07.1unifi_fabric.ts

Global Arguments

ArgumentTypeDescription
hoststringUniFi OS console IP or hostname, e.g. 192.0.2.1
apiKeystringAPI key issued under Settings → Control Plane → Integrations (use a
site?stringUniFi site name
links?arrayHow each device should be attached. Used by `check` when the call
ports?arrayPorts whose speed is worth asserting. Used by `check` when the call
fn check(links?: array, ports?: array, darkPortByteThreshold?: number)
Compare a desired fabric topology against live UniFi devices. Reports wireless uplinks where wire was expected, wrong uplink parents, under-negotiated links, erroring ports and down-but-previously-used ports. Read-only — never writes to the controller.
ArgumentTypeDescription
links?arrayHow each device should be attached to the fabric. Defaults to the
ports?arraySwitch ports whose speed is worth asserting. Defaults to the
darkPortByteThreshold?numberBytes a down port must have carried before it is reported as a run

Resources

fabric(infinite)— Comparison between a desired UniFi fabric topology and how devices are actually attached, plus port speed and error health.
04Previous Versions2
2026.10.07.1
2026.08.20.1
05Stats
A
100 / 100
Downloads
36
Archive size
16.9 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels