Files
homarr/docs/superpowers/plans/2026-09-08-unifi-os-integration.md
T

2076 lines
75 KiB
Markdown

# Plan d'implémentation — Intégration UniFi OS
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal :** Ajouter à Homarr une intégration `unifiOs` lisant l'API d'intégration officielle d'UniFi OS (clé `X-API-KEY`), enrichie optionnellement par l'API cloud Site Manager, et un widget dédié pour l'afficher.
**Architecture :** Quatre modules aux responsabilités disjointes dans `packages/integrations/src/unifi-os/` — un client HTTP local, un client HTTP cloud optionnel à cache interne, un module de schémas et de mappers purs, et une classe `Integration` qui orchestre. Le tout branché sur les cinq points d'attache habituels du monorepo (definitions, request-handler, api, widgets, translation).
**Tech Stack :** TypeScript, zod v4 (`zod/v4`), vitest, undici `fetch`, Mantine v9, tRPC, Turbo/pnpm.
**Spec :** `docs/superpowers/specs/2026-09-08-unifi-os-integration-design.md`
## Global Constraints
- **Branche de travail :** `feat/unifi-os-integration`. Ne jamais committer sur `dev` ni `main`.
- **Lint / format :** oxlint et oxfmt, **pas** ESLint ni Prettier. `pnpm lint` et `pnpm format`.
- **UI :** Mantine v9, **pas** Tailwind. Icônes `@tabler/icons-react`.
- **zod :** importer `{ z } from "zod/v4"` (convention de l'intégration `patchmon`, la plus récente). Objets tolérants aux champs inconnus via `z.looseObject`.
- **Tests :** vitest. Fichiers `*.spec.ts` sous `packages/integrations/src/unifi-os/test/`. En-tête `// @vitest-environment node` pour les tests d'intégration. Lancement : `pnpm test`.
- **Erreurs :** `ParseError` et `ResponseError` depuis `@homarr/common/server` ; `TestConnectionError` depuis `../base/test-connection/test-connection-error`.
- **Base d'URL locale :** l'utilisateur saisit l'origine de la console. Le client préfixe `/proxy/network/integration/v1`. Ce préfixe n'est jamais exposé à la configuration.
- **Base d'URL cloud :** `https://api.ui.com`, en dur, jamais configurable.
- **`limit` de l'API locale est plafonné à 200.** Mesuré. Toute pagination doit en tenir compte.
- **Syntaxe de filtrage locale : préfixe.** `and(type.eq('WIRED'),access.type.eq('DEFAULT'))`. Les formes infixes renvoient `400 api.request.invalid-filter`.
- **Aucun secret, MAC réel, IP publique ou nom de client réel dans le dépôt.** Fixtures anonymisées.
- **`NetworkControllerSummary` ne doit pas être modifié.** Aucun fichier de `unifi-controller/` ni d'`opnsense/` ne doit apparaître dans un diff.
- **Nommer la catégorie `unifiOs`, jamais `networkController`** (voir §5.3 de la spec : la catégorie est un mécanisme de câblage, pas une étiquette).
---
## Structure des fichiers
**Créés :**
| Fichier | Responsabilité |
|---|---|
| `packages/integrations/src/unifi-os/unifi-os-types.ts` | Schémas zod et fonctions pures de mapping. Aucun accès réseau. |
| `packages/integrations/src/unifi-os/unifi-os-api.ts` | Client HTTP de la console locale. Ne connaît pas Homarr. |
| `packages/integrations/src/unifi-os/unifi-sm-api.ts` | Client HTTP du cloud Site Manager. Cache interne. Optionnel. |
| `packages/integrations/src/unifi-os/unifi-os-integration.ts` | Classe `Integration`. Orchestration et dégradation. |
| `packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts` | Interface consommée par le request-handler. |
| `packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts` | Tests des mappers, sans réseau. |
| `packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts` | Tests du client local, `fetch` injecté. |
| `packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts` | Tests du client cloud et du cache. |
| `packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts` | Tests d'orchestration et de dégradation. |
| `packages/request-handler/src/unifi-os.ts` | Handler de cache. |
| `packages/api/src/router/widgets/unifi-os.ts` | Routeur tRPC. |
| `packages/widgets/src/unifi-os/index.ts` | Définition du widget. |
| `packages/widgets/src/unifi-os/component.tsx` | Composant Mantine. |
**Modifiés :**
| Fichier | Modification |
|---|---|
| `packages/definitions/src/integration.ts` | secret `siteManagerApiKey`, catégorie `unifiOs`, kind `unifiOs` |
| `packages/definitions/src/widget.ts` | `WidgetKind` `unifiOs` |
| `packages/definitions/src/widget-integration-map.ts` | `unifiOs: ["unifiOs"]` |
| `packages/integrations/src/base/creator.ts` | import + entrée `unifiOs` |
| `packages/integrations/src/index.ts` | export de la classe |
| `packages/integrations/src/types.ts` | export des types |
| `packages/api/src/router/widgets/index.ts` | entrée `unifiOs` |
| `packages/widgets/src/manifest.ts` | deux entrées (module + composant) |
| `packages/widgets/src/index.tsx` | import + entrée |
| `packages/widgets/src/catalog.ts` | icône — **vérifié par `manifest.spec.ts`** |
| `packages/widgets/src/refetch-intervals.ts` | intervalle 60 s |
| `packages/translation/src/lang/en.json` | libellés + `integration.category.unifiOs` |
---
## Task 1 : Déclarations dans `@homarr/definitions`
Poser le vocabulaire avant tout le reste. Sans ces déclarations, rien d'autre ne compile.
**Files:**
- Modify: `packages/definitions/src/integration.ts`
- Modify: `packages/definitions/src/widget.ts`
- Modify: `packages/definitions/src/widget-integration-map.ts`
- Modify: `packages/translation/src/lang/en.json`
**Interfaces:**
- Consumes: rien.
- Produces: le kind d'intégration `"unifiOs"`, la catégorie `"unifiOs"`, le secret `"siteManagerApiKey"`, le `WidgetKind` `"unifiOs"`. Toutes les tâches suivantes en dépendent.
- [ ] **Step 1 : Ajouter le secret**
Dans `packages/definitions/src/integration.ts`, dans `integrationSecretKindObject`, juste après la ligne `apiKey`, ajouter :
```ts
siteManagerApiKey: { isPublic: false, multiline: false },
```
- [ ] **Step 2 : Ajouter la catégorie**
Dans le même fichier, dans le tableau `integrationCategories`, avant la ligne `] as const;`, ajouter :
```ts
"unifiOs",
```
- [ ] **Step 3 : Ajouter le kind d'intégration**
Toujours dans le même fichier, dans `integrationDefs`, **immédiatement après** le bloc `unifiController` (qui se termine par `defaultPort: 8443,` puis `},`), ajouter :
```ts
unifiOs: {
name: "UniFi OS",
secretKinds: [["apiKey"], ["apiKey", "siteManagerApiKey"]],
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/unifi.png",
category: ["unifiOs"],
documentationUrl: null,
defaultPort: 443,
},
```
`documentationUrl: null` est volontaire : la décision D1 de la spec exclut la documentation Docusaurus. Le champ accepte `string | null`.
`secretKinds` déclare deux jeux alternatifs. Le premier — `["apiKey"]` — rend la clé cloud facultative. Motif identique à `ntfy`.
- [ ] **Step 4 : Ajouter le WidgetKind**
Dans `packages/definitions/src/widget.ts`, dans le tableau `widgetKinds`, après `"networkControllerStatus",` ajouter :
```ts
"unifiOs",
```
- [ ] **Step 5 : Câbler la carte widget → intégrations**
Dans `packages/definitions/src/widget-integration-map.ts`, dans `widgetIntegrationSupport`, après la ligne `networkControllerStatus: getIntegrationKindsByCategory("networkController"),` ajouter :
```ts
unifiOs: ["unifiOs"],
```
Liste littérale et non `getIntegrationKindsByCategory("unifiOs")` : le widget ne supporte qu'une intégration, et l'écrire en clair rend la relation évidente à la lecture. C'est ce que fait déjà `coolify: ["coolify"]`.
- [ ] **Step 6 : Ajouter la traduction de catégorie**
Dans `packages/translation/src/lang/en.json`, dans l'objet `integration.category`, à côté de `"networkController": "Network"`, ajouter :
```json
"unifiOs": "UniFi OS",
```
- [ ] **Step 7 : Vérifier que le typage tient**
Run: `pnpm turbo typecheck --filter=@homarr/definitions`
Expected: PASS.
Si `@homarr/widgets` est aussi typé à ce stade, il **échouera** — c'est attendu : le `WidgetKind` `unifiOs` n'a pas encore d'entrée dans le manifeste. La Task 7 le corrige. Ne pas contourner en retirant le kind.
- [ ] **Step 8 : Committer**
```bash
git add packages/definitions/src/integration.ts packages/definitions/src/widget.ts packages/definitions/src/widget-integration-map.ts packages/translation/src/lang/en.json
git commit -m "feat(definitions): declare unifiOs integration kind, category and widget kind"
```
---
## Task 2 : Schémas et mappers purs
Le cœur testable de l'intégration. Aucun réseau, donc aucun mock : ces tests restent valables même si Ubiquiti change ses endpoints.
**Files:**
- Create: `packages/integrations/src/unifi-os/unifi-os-types.ts`
- Test: `packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts`
**Interfaces:**
- Consumes: rien.
- Produces :
- `UnifiOsSummary`, `UnifiOsIspMetrics`, `UnifiOsClientCounts`, `UnifiOsDeviceCounts`, `UnifiOsGateway`
- `unifiOsInfoSchema`, `unifiOsSiteSchema`, `unifiOsClientSchema`, `unifiOsDeviceSchema`, `unifiOsDeviceStatisticsSchema`, `unifiOsVpnServerSchema`, `createUnifiOsPageSchema`
- `unifiSmSiteSchema`, `unifiSmIspMetricsResponseSchema`
- `parseUnifiOsAsync<T>(value: unknown, schema: z.ZodType<T>, message: string): Promise<T>`
- `normalizeMacAddress(mac: string): string`
- `countClients(clients: UnifiOsClient[]): UnifiOsClientCounts`
- `summarizeDevices(devices: UnifiOsDevice[]): UnifiOsDeviceCounts`
- `findGateway(devices: UnifiOsDevice[]): UnifiOsDevice | null`
- `matchCloudSite<T extends { meta: { gatewayMac?: string } }>(gatewayMac: string | null, sites: T[]): T | null`
- [ ] **Step 1 : Écrire les tests qui échouent**
Créer `packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts` :
```ts
import { describe, expect, test } from "vitest";
import type { UnifiOsClient, UnifiOsDevice } from "../unifi-os-types";
import {
countClients,
findGateway,
matchCloudSite,
normalizeMacAddress,
summarizeDevices,
unifiOsClientSchema,
} from "../unifi-os-types";
const client = (type: string, accessType = "DEFAULT"): UnifiOsClient => ({
id: `client-${type}-${accessType}-${Math.random()}`,
name: "client",
type,
access: { type: accessType },
});
const device = (overrides: Partial<UnifiOsDevice> = {}): UnifiOsDevice => ({
id: "device-1",
name: "device",
model: "USW Lite 8",
macAddress: "aa:bb:cc:11:22:33",
state: "ONLINE",
firmwareUpdatable: false,
features: ["switching"],
...overrides,
});
describe("normalizeMacAddress", () => {
test("lowercases and strips separators so both APIs compare equal", () => {
expect(normalizeMacAddress("AA:BB:CC:11:22:33")).toBe("aabbcc112233");
expect(normalizeMacAddress("aa-bb-cc-11-22-33")).toBe("aabbcc112233");
expect(normalizeMacAddress("AABBCC112233")).toBe("aabbcc112233");
});
});
describe("countClients", () => {
test("counts each connection type separately", () => {
const counts = countClients([
client("WIRED"),
client("WIRED"),
client("WIRELESS"),
client("VPN"),
client("TELEPORT"),
]);
expect(counts).toEqual({ total: 5, wired: 2, wireless: 1, vpn: 2, guests: 0 });
});
test("folds TELEPORT into vpn because both are remote access", () => {
expect(countClients([client("TELEPORT")]).vpn).toBe(1);
});
test("counts guests across every connection type", () => {
const counts = countClients([client("WIRELESS", "GUEST"), client("WIRED", "GUEST"), client("WIRED")]);
expect(counts.guests).toBe(2);
expect(counts.wired).toBe(2);
});
test("treats an unknown connection type as counted but unclassified", () => {
const counts = countClients([client("SOMETHING_NEW")]);
expect(counts.total).toBe(1);
expect(counts.wired + counts.wireless + counts.vpn).toBe(0);
});
test("tolerates a client without an access block", () => {
const counts = countClients([{ id: "x", name: "x", type: "WIRED" }]);
expect(counts).toEqual({ total: 1, wired: 1, wireless: 0, vpn: 0, guests: 0 });
});
});
describe("summarizeDevices", () => {
test("splits online from everything else and counts pending firmware", () => {
const counts = summarizeDevices([
device({ id: "a", state: "ONLINE", firmwareUpdatable: true }),
device({ id: "b", state: "OFFLINE" }),
device({ id: "c", state: "UPDATING", firmwareUpdatable: true }),
]);
expect(counts).toEqual({ total: 3, online: 1, offline: 2, firmwareUpdatable: 2 });
});
test("returns zeroes for an empty site rather than throwing", () => {
expect(summarizeDevices([])).toEqual({ total: 0, online: 0, offline: 0, firmwareUpdatable: 0 });
});
});
describe("findGateway", () => {
test("prefers the device advertising the gateway feature", () => {
const gateway = device({ id: "gw", features: ["gateway"], model: "UXG Pro" });
expect(findGateway([device(), gateway])?.id).toBe("gw");
});
test("falls back to a gateway-looking model when features are empty", () => {
const gateway = device({ id: "gw", features: [], model: "Gateway Pro" });
expect(findGateway([device(), gateway])?.id).toBe("gw");
});
test("returns null when no gateway is present instead of picking any device", () => {
expect(findGateway([device()])).toBeNull();
});
});
describe("matchCloudSite", () => {
const siteA = { siteId: "a", meta: { gatewayMac: "AA:BB:CC:11:22:33" } };
const siteB = { siteId: "b", meta: { gatewayMac: "dd:ee:ff:44:55:66" } };
test("matches on the gateway MAC regardless of formatting", () => {
expect(matchCloudSite("aa-bb-cc-11-22-33", [siteB, siteA])?.siteId).toBe("a");
});
test("returns null rather than another account site when nothing matches", () => {
expect(matchCloudSite("11:22:33:44:55:66", [siteA, siteB])).toBeNull();
});
test("returns null when the local gateway is unknown", () => {
expect(matchCloudSite(null, [siteA, siteB])).toBeNull();
});
});
describe("unifiOsClientSchema", () => {
test("keeps fields the published OpenAPI does not document", () => {
const parsed = unifiOsClientSchema.parse({
id: "1",
name: "n",
type: "WIRED",
access: { type: "DEFAULT" },
macAddress: "aa:bb:cc:11:22:33",
uplinkDeviceId: "u1",
});
expect(parsed).toMatchObject({ macAddress: "aa:bb:cc:11:22:33", uplinkDeviceId: "u1" });
});
});
```
- [ ] **Step 2 : Lancer les tests pour vérifier qu'ils échouent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts`
Expected: FAIL — `Cannot find module '../unifi-os-types'`.
- [ ] **Step 3 : Écrire l'implémentation**
Créer `packages/integrations/src/unifi-os/unifi-os-types.ts` :
```ts
import { ParseError } from "@homarr/common/server";
import { z } from "zod/v4";
/**
* Ubiquiti ne publie l'OpenAPI que pour la 10.4.57 alors que les consoles sont
* en 10.6.x et renvoient déjà des champs absents du spec. Tous les objets sont
* donc « loose » : un champ inattendu ne doit jamais faire échouer un widget.
*/
export const unifiOsInfoSchema = z.looseObject({
applicationVersion: z.string(),
});
export const unifiOsSiteSchema = z.looseObject({
id: z.string(),
name: z.string(),
internalReference: z.string().optional(),
});
export const unifiOsClientSchema = z.looseObject({
id: z.string(),
name: z.string(),
type: z.string(),
access: z.looseObject({ type: z.string() }).optional(),
});
export const unifiOsDeviceSchema = z.looseObject({
id: z.string(),
name: z.string(),
model: z.string(),
macAddress: z.string(),
state: z.string(),
firmwareUpdatable: z.boolean().optional(),
features: z.array(z.string()).default([]),
});
export const unifiOsDeviceStatisticsSchema = z.looseObject({
uptimeSec: z.number().optional(),
cpuUtilizationPct: z.number().optional(),
memoryUtilizationPct: z.number().optional(),
uplink: z.looseObject({ txRateBps: z.number(), rxRateBps: z.number() }).optional(),
});
export const unifiOsVpnServerSchema = z.looseObject({
id: z.string(),
name: z.string().optional(),
enabled: z.boolean(),
});
/** Enveloppe de pagination commune à tous les endpoints de liste. */
export const createUnifiOsPageSchema = <TItem extends z.ZodType>(item: TItem) =>
z.looseObject({
offset: z.number(),
limit: z.number(),
count: z.number(),
totalCount: z.number(),
data: z.array(item),
});
export const unifiSmSiteSchema = z.looseObject({
siteId: z.string(),
hostId: z.string().optional(),
meta: z.looseObject({
desc: z.string().optional(),
name: z.string().optional(),
gatewayMac: z.string().optional(),
}),
statistics: z
.looseObject({
ispInfo: z.looseObject({ name: z.string().optional() }).optional(),
percentages: z.looseObject({ wanUptime: z.number().optional() }).optional(),
wans: z.record(z.string(), z.looseObject({ externalIp: z.string().optional() })).optional(),
})
.optional(),
});
const unifiSmWanMetricsSchema = z.looseObject({
avgLatency: z.number().optional(),
maxLatency: z.number().optional(),
packetLoss: z.number().optional(),
uptime: z.number().optional(),
ispName: z.string().optional(),
});
export const unifiSmIspMetricsResponseSchema = z.looseObject({
data: z.looseObject({
metrics: z.array(
z.looseObject({
periods: z.array(
z.looseObject({
metricTime: z.string(),
data: z.looseObject({ wan: unifiSmWanMetricsSchema.optional() }),
}),
),
}),
),
}),
});
export type UnifiOsClient = z.infer<typeof unifiOsClientSchema>;
export type UnifiOsDevice = z.infer<typeof unifiOsDeviceSchema>;
export type UnifiOsSite = z.infer<typeof unifiOsSiteSchema>;
export type UnifiOsDeviceStatistics = z.infer<typeof unifiOsDeviceStatisticsSchema>;
export interface UnifiOsClientCounts {
total: number;
wired: number;
wireless: number;
vpn: number;
guests: number;
}
export interface UnifiOsDeviceCounts {
total: number;
online: number;
offline: number;
firmwareUpdatable: number;
}
export interface UnifiOsGateway {
name: string;
model: string;
macAddress: string;
uptimeSec: number | null;
cpuPct: number | null;
memoryPct: number | null;
}
export interface UnifiOsIspMetrics {
name: string;
externalIp: string | null;
latencyMs: number;
maxLatencyMs: number;
packetLossPct: number;
uptimePct: number;
/** Horodatage de la mesure : la donnée cloud accuse ~27 min de retard. */
measuredAt: Date;
}
export interface UnifiOsSummary {
site: {
id: string;
name: string;
applicationVersion: string;
};
wan: {
state: "online" | "offline" | "unknown";
throughput: { txBps: number; rxBps: number } | null;
isp: UnifiOsIspMetrics | null;
};
clients: UnifiOsClientCounts;
devices: UnifiOsDeviceCounts;
gateway: UnifiOsGateway | null;
}
export const parseUnifiOsAsync = async <TOutput>(
value: unknown,
schema: z.ZodType<TOutput>,
message: string,
): Promise<TOutput> => {
const result = await schema.safeParseAsync(value);
if (!result.success) {
throw new ParseError(message, { cause: result.error });
}
return result.data;
};
/**
* L'API locale renvoie `aa:bb:cc:11:22:33`, le cloud peut renvoyer une autre
* casse ou d'autres séparateurs. La comparaison se fait sur une forme canonique.
*/
export const normalizeMacAddress = (mac: string): string => mac.toLowerCase().replace(/[^0-9a-f]/g, "");
const VPN_CLIENT_TYPES = new Set(["VPN", "TELEPORT"]);
export const countClients = (clients: UnifiOsClient[]): UnifiOsClientCounts => {
const counts: UnifiOsClientCounts = { total: 0, wired: 0, wireless: 0, vpn: 0, guests: 0 };
for (const client of clients) {
counts.total += 1;
if (client.type === "WIRED") counts.wired += 1;
else if (client.type === "WIRELESS") counts.wireless += 1;
else if (VPN_CLIENT_TYPES.has(client.type)) counts.vpn += 1;
if (client.access?.type === "GUEST") counts.guests += 1;
}
return counts;
};
export const summarizeDevices = (devices: UnifiOsDevice[]): UnifiOsDeviceCounts => {
const online = devices.filter((device) => device.state === "ONLINE").length;
return {
total: devices.length,
online,
// Tout ce qui n'est pas ONLINE est indisponible du point de vue du dashboard,
// qu'il s'agisse d'OFFLINE, d'UPDATING ou d'un état futur inconnu.
offline: devices.length - online,
firmwareUpdatable: devices.filter((device) => device.firmwareUpdatable === true).length,
};
};
const GATEWAY_MODEL_HINT = /gateway|udm|uxg|ucg|usg/i;
export const findGateway = (devices: UnifiOsDevice[]): UnifiOsDevice | null =>
devices.find((device) => device.features.includes("gateway")) ??
devices.find((device) => GATEWAY_MODEL_HINT.test(device.model)) ??
null;
/**
* Une clé Site Manager voit tous les sites du compte, y compris ceux d'autres
* consoles. Sans correspondance stricte sur le MAC du gateway, on afficherait
* la latence d'un autre réseau. Renvoyer null est le seul comportement sûr.
*/
export const matchCloudSite = <TSite extends { meta: { gatewayMac?: string } }>(
gatewayMac: string | null,
sites: TSite[],
): TSite | null => {
if (gatewayMac === null) return null;
const normalized = normalizeMacAddress(gatewayMac);
return sites.find((site) => site.meta.gatewayMac !== undefined && normalizeMacAddress(site.meta.gatewayMac) === normalized) ?? null;
};
```
- [ ] **Step 4 : Lancer les tests pour vérifier qu'ils passent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts`
Expected: PASS, 15 tests.
- [ ] **Step 5 : Formater et committer**
```bash
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add UniFi OS schemas and pure mappers"
```
---
## Task 3 : Client HTTP local
**Files:**
- Create: `packages/integrations/src/unifi-os/unifi-os-api.ts`
- Test: `packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts`
**Interfaces:**
- Consumes: tout ce que produit la Task 2.
- Produces :
- `type UnifiOsFetch = (url: string, init?: RequestInit & { timeout?: number }) => Promise<Response>`
- `class UnifiOsApi` — constructeur `(origin: string, apiKey: string, fetchAsync: UnifiOsFetch)`
- `getInfoAsync(): Promise<{ applicationVersion: string }>`
- `getFirstSiteAsync(): Promise<UnifiOsSite | null>`
- `getClientCountsAsync(siteId: string): Promise<UnifiOsClientCounts>`
- `getDevicesAsync(siteId: string): Promise<UnifiOsDevice[]>`
- `getDeviceStatisticsAsync(siteId, deviceId): Promise<UnifiOsDeviceStatistics>`
- `getVpnServersAsync(siteId: string): Promise<{ enabled: boolean }[]>`
Le `fetchAsync` est **injecté** plutôt que mocké au niveau du module : les tests
deviennent lisibles et n'ont pas besoin de `vi.mock`.
- [ ] **Step 1 : Écrire les tests qui échouent**
Créer `packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts` :
```ts
import { Response } from "undici";
import { describe, expect, test, vi } from "vitest";
import { ResponseError } from "@homarr/common/server";
import { UnifiOsApi } from "../unifi-os-api";
const ORIGIN = "https://console.example.test";
const API_KEY = "test-key";
const jsonResponse = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
const page = (data: unknown[], totalCount = data.length, limit = 200) => ({
offset: 0,
limit,
count: data.length,
totalCount,
data,
});
const createApi = (handler: (url: string) => Promise<Response>) => {
const fetchAsync = vi.fn(async (url: string) => await handler(url));
return { api: new UnifiOsApi(ORIGIN, API_KEY, fetchAsync as never), fetchAsync };
};
describe("UnifiOsApi request shape", () => {
test("prefixes the integration path and sends the API key header", async () => {
const fetchAsync = vi.fn(async () => jsonResponse({ applicationVersion: "10.6.102" }));
const api = new UnifiOsApi(ORIGIN, API_KEY, fetchAsync as never);
await api.getInfoAsync();
expect(fetchAsync).toHaveBeenCalledWith(
`${ORIGIN}/proxy/network/integration/v1/info`,
expect.objectContaining({ headers: expect.objectContaining({ "X-API-KEY": API_KEY }) }),
);
});
test("does not double a slash when the origin has a trailing one", async () => {
const fetchAsync = vi.fn(async () => jsonResponse({ applicationVersion: "10.6.102" }));
const api = new UnifiOsApi(`${ORIGIN}/`, API_KEY, fetchAsync as never);
await api.getInfoAsync();
expect(fetchAsync.mock.calls[0]?.[0]).toBe(`${ORIGIN}/proxy/network/integration/v1/info`);
});
test("throws ResponseError on a non-ok status instead of parsing the body", async () => {
const { api } = createApi(async () => jsonResponse({ error: { code: 401 } }, 401));
await expect(api.getInfoAsync()).rejects.toBeInstanceOf(ResponseError);
});
});
describe("UnifiOsApi getClientCountsAsync", () => {
test("counts from a single page when totalCount fits under the API limit", async () => {
const { api, fetchAsync } = createApi(async () =>
jsonResponse(
page([
{ id: "1", name: "a", type: "WIRED", access: { type: "DEFAULT" } },
{ id: "2", name: "b", type: "WIRELESS", access: { type: "GUEST" } },
]),
),
);
const counts = await api.getClientCountsAsync("site-1");
expect(counts).toEqual({ total: 2, wired: 1, wireless: 1, vpn: 0, guests: 1 });
expect(fetchAsync).toHaveBeenCalledTimes(1);
});
test("switches to filtered count queries when the site exceeds the 200 limit", async () => {
const requested: string[] = [];
const { api } = createApi(async (url) => {
requested.push(url);
if (!url.includes("filter=")) return jsonResponse(page([], 512));
if (url.includes("WIRED")) return jsonResponse(page([], 400, 1));
if (url.includes("WIRELESS")) return jsonResponse(page([], 100, 1));
if (url.includes("TELEPORT")) return jsonResponse(page([], 2, 1));
if (url.includes("VPN")) return jsonResponse(page([], 10, 1));
return jsonResponse(page([], 5, 1));
});
const counts = await api.getClientCountsAsync("site-1");
expect(counts).toEqual({ total: 512, wired: 400, wireless: 100, vpn: 12, guests: 5 });
expect(requested.some((url) => url.includes("and("))).toBe(false);
expect(requested.filter((url) => url.includes("filter=")).length).toBe(5);
});
test("uses the prefix filter syntax the API actually accepts", async () => {
const requested: string[] = [];
const { api } = createApi(async (url) => {
requested.push(url);
return jsonResponse(page([], url.includes("filter=") ? 1 : 512, 1));
});
await api.getClientCountsAsync("site-1");
const guestQuery = requested.find((url) => url.includes("GUEST"));
expect(decodeURIComponent(guestQuery ?? "")).toContain("access.type.eq('GUEST')");
expect(decodeURIComponent(guestQuery ?? "")).not.toContain(" and ");
});
});
describe("UnifiOsApi getFirstSiteAsync", () => {
test("returns null for a console exposing no site rather than throwing", async () => {
const { api } = createApi(async () => jsonResponse(page([])));
expect(await api.getFirstSiteAsync()).toBeNull();
});
});
```
- [ ] **Step 2 : Lancer les tests pour vérifier qu'ils échouent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts`
Expected: FAIL — `Cannot find module '../unifi-os-api'`.
- [ ] **Step 3 : Écrire l'implémentation**
Créer `packages/integrations/src/unifi-os/unifi-os-api.ts` :
```ts
import { ResponseError } from "@homarr/common/server";
import type { z } from "zod/v4";
import type {
UnifiOsClientCounts,
UnifiOsDevice,
UnifiOsDeviceStatistics,
UnifiOsSite,
} from "./unifi-os-types";
import {
countClients,
createUnifiOsPageSchema,
parseUnifiOsAsync,
unifiOsClientSchema,
unifiOsDeviceSchema,
unifiOsDeviceStatisticsSchema,
unifiOsInfoSchema,
unifiOsSiteSchema,
unifiOsVpnServerSchema,
} from "./unifi-os-types";
export type UnifiOsFetch = (url: string, init?: RequestInit & { timeout?: number }) => Promise<Response>;
const INTEGRATION_PATH = "/proxy/network/integration/v1";
const REQUEST_TIMEOUT_MS = 10_000;
/** Plafond imposé par l'API : demander davantage renvoie quand même 200. */
const MAX_PAGE_LIMIT = 200;
const PARSE_ERROR_MESSAGE = "Invalid UniFi OS response";
const clientPageSchema = createUnifiOsPageSchema(unifiOsClientSchema);
const devicePageSchema = createUnifiOsPageSchema(unifiOsDeviceSchema);
const sitePageSchema = createUnifiOsPageSchema(unifiOsSiteSchema);
const vpnServerPageSchema = createUnifiOsPageSchema(unifiOsVpnServerSchema);
/**
* Client de l'API d'intégration locale d'UniFi OS.
*
* Ne connaît ni Homarr ni la notion d'intégration : il ne sait que parler à une
* console. Le `fetch` est injecté pour que les tests n'aient pas à mocker un module.
*/
export class UnifiOsApi {
private readonly baseUrl: string;
constructor(
origin: string,
private readonly apiKey: string,
private readonly fetchAsync: UnifiOsFetch,
) {
this.baseUrl = `${origin.replace(/\/+$/, "")}${INTEGRATION_PATH}`;
}
public async getInfoAsync(): Promise<{ applicationVersion: string }> {
return await this.requestAsync("/info", unifiOsInfoSchema);
}
public async getFirstSiteAsync(): Promise<UnifiOsSite | null> {
const page = await this.requestAsync("/sites", sitePageSchema);
return page.data[0] ?? null;
}
public async getDevicesAsync(siteId: string): Promise<UnifiOsDevice[]> {
const page = await this.requestAsync(`/sites/${encodeURIComponent(siteId)}/devices?limit=${MAX_PAGE_LIMIT}`, devicePageSchema);
return page.data;
}
public async getDeviceStatisticsAsync(siteId: string, deviceId: string): Promise<UnifiOsDeviceStatistics> {
return await this.requestAsync(
`/sites/${encodeURIComponent(siteId)}/devices/${encodeURIComponent(deviceId)}/statistics/latest`,
unifiOsDeviceStatisticsSchema,
);
}
public async getVpnServersAsync(siteId: string): Promise<{ enabled: boolean }[]> {
const page = await this.requestAsync(`/sites/${encodeURIComponent(siteId)}/vpn/servers`, vpnServerPageSchema);
return page.data;
}
/**
* Sous le plafond de 200 clients, une seule page suffit et le comptage se fait
* en mémoire. Au-delà, rapatrier tous les enregistrements pour n'en tirer que
* des compteurs coûterait plus cher que cinq requêtes bornées.
*/
public async getClientCountsAsync(siteId: string): Promise<UnifiOsClientCounts> {
const path = `/sites/${encodeURIComponent(siteId)}/clients`;
const firstPage = await this.requestAsync(`${path}?limit=${MAX_PAGE_LIMIT}`, clientPageSchema);
if (firstPage.totalCount <= MAX_PAGE_LIMIT) {
return countClients(firstPage.data);
}
const countByFilterAsync = async (filter: string) => {
const page = await this.requestAsync(`${path}?limit=1&filter=${encodeURIComponent(filter)}`, clientPageSchema);
return page.totalCount;
};
const [wired, wireless, vpn, teleport, guests] = await Promise.all([
countByFilterAsync("type.eq('WIRED')"),
countByFilterAsync("type.eq('WIRELESS')"),
countByFilterAsync("type.eq('VPN')"),
countByFilterAsync("type.eq('TELEPORT')"),
countByFilterAsync("access.type.eq('GUEST')"),
]);
return { total: firstPage.totalCount, wired, wireless, vpn: vpn + teleport, guests };
}
private async requestAsync<TOutput>(path: string, schema: z.ZodType<TOutput>): Promise<TOutput> {
const response = await this.fetchAsync(`${this.baseUrl}${path}`, {
headers: { "X-API-KEY": this.apiKey, Accept: "application/json" },
timeout: REQUEST_TIMEOUT_MS,
});
if (!response.ok) {
throw new ResponseError(response);
}
return await parseUnifiOsAsync(await response.json(), schema, PARSE_ERROR_MESSAGE);
}
}
```
- [ ] **Step 4 : Lancer les tests pour vérifier qu'ils passent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts`
Expected: PASS, 7 tests.
- [ ] **Step 5 : Committer**
```bash
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add UniFi OS local API client"
```
---
## Task 4 : Client HTTP cloud, optionnel et caché
**Files:**
- Create: `packages/integrations/src/unifi-os/unifi-sm-api.ts`
- Test: `packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts`
**Interfaces:**
- Consumes: `unifiSmSiteSchema`, `unifiSmIspMetricsResponseSchema`, `matchCloudSite`, `parseUnifiOsAsync`, `UnifiOsIspMetrics` de la Task 2 ; `UnifiOsFetch` de la Task 3.
- Produces :
- `class UnifiSmApi` — constructeur `(apiKey: string, fetchAsync: UnifiOsFetch)`
- `getIspMetricsAsync(gatewayMac: string | null): Promise<UnifiOsIspMetrics | null>`
- `static clearCache(): void` — réservé aux tests
- [ ] **Step 1 : Écrire les tests qui échouent**
Créer `packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts` :
```ts
import { Response } from "undici";
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
import { UnifiSmApi } from "../unifi-sm-api";
const GATEWAY_MAC = "aa:bb:cc:11:22:33";
const OTHER_MAC = "dd:ee:ff:44:55:66";
const jsonResponse = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
const sitesBody = {
data: [
{ siteId: "mine", meta: { desc: "Mine", gatewayMac: GATEWAY_MAC }, statistics: { wans: { WAN: { externalIp: "203.0.113.10" } } } },
{ siteId: "theirs", meta: { desc: "Theirs", gatewayMac: OTHER_MAC } },
],
};
const metricsBody = (metricTime: string) => ({
data: {
metrics: [
{
periods: [
{ metricTime: "2026-09-08T08:00:00Z", data: { wan: { avgLatency: 99, maxLatency: 99, packetLoss: 5, uptime: 90, ispName: "Old" } } },
{ metricTime, data: { wan: { avgLatency: 11, maxLatency: 12, packetLoss: 0, uptime: 100, ispName: "Example ISP" } } },
],
},
],
},
});
const createApi = () => {
const fetchAsync = vi.fn(async (url: string) =>
url.includes("isp-metrics") ? jsonResponse(metricsBody("2026-09-08T09:10:00Z")) : jsonResponse(sitesBody),
);
return { api: new UnifiSmApi("cloud-key", fetchAsync as never), fetchAsync };
};
beforeEach(() => {
UnifiSmApi.clearCache();
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-09-08T09:37:00Z"));
});
afterEach(() => {
vi.useRealTimers();
});
describe("UnifiSmApi getIspMetricsAsync", () => {
test("returns the newest period of the site matching the gateway MAC", async () => {
const { api } = createApi();
const metrics = await api.getIspMetricsAsync(GATEWAY_MAC);
expect(metrics).toEqual({
name: "Example ISP",
externalIp: "203.0.113.10",
latencyMs: 11,
maxLatencyMs: 12,
packetLossPct: 0,
uptimePct: 100,
measuredAt: new Date("2026-09-08T09:10:00Z"),
});
});
test("returns null when no cloud site matches, never another account site", async () => {
const { api } = createApi();
expect(await api.getIspMetricsAsync("11:22:33:44:55:66")).toBeNull();
});
test("returns null when the local gateway could not be identified", async () => {
const { api, fetchAsync } = createApi();
expect(await api.getIspMetricsAsync(null)).toBeNull();
expect(fetchAsync).not.toHaveBeenCalled();
});
test("queries a window wide enough for the cloud lag", async () => {
const { api, fetchAsync } = createApi();
await api.getIspMetricsAsync(GATEWAY_MAC);
const body = JSON.parse(String(fetchAsync.mock.calls.find(([url]) => String(url).includes("isp-metrics"))?.[1]?.body));
const begin = new Date(body.sites[0].beginTimestamp).getTime();
const end = new Date(body.sites[0].endTimestamp).getTime();
// Une fenêtre de 15 min renvoie un tableau vide sur l'API réelle.
expect(end - begin).toBeGreaterThanOrEqual(3 * 60 * 60 * 1000);
});
test("serves a second call from cache instead of hitting the cloud again", async () => {
const { api, fetchAsync } = createApi();
await api.getIspMetricsAsync(GATEWAY_MAC);
const callsAfterFirst = fetchAsync.mock.calls.length;
await api.getIspMetricsAsync(GATEWAY_MAC);
expect(fetchAsync.mock.calls.length).toBe(callsAfterFirst);
});
test("refetches once the cache entry has expired", async () => {
const { api, fetchAsync } = createApi();
await api.getIspMetricsAsync(GATEWAY_MAC);
const callsAfterFirst = fetchAsync.mock.calls.length;
vi.setSystemTime(new Date("2026-09-08T09:43:00Z"));
await api.getIspMetricsAsync(GATEWAY_MAC);
expect(fetchAsync.mock.calls.length).toBeGreaterThan(callsAfterFirst);
});
test("returns null when the cloud rejects the key rather than propagating", async () => {
const fetchAsync = vi.fn(async () => jsonResponse({ message: "unauthorized" }, 401));
const api = new UnifiSmApi("bad-key", fetchAsync as never);
expect(await api.getIspMetricsAsync(GATEWAY_MAC)).toBeNull();
});
});
```
- [ ] **Step 2 : Lancer les tests pour vérifier qu'ils échouent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts`
Expected: FAIL — `Cannot find module '../unifi-sm-api'`.
- [ ] **Step 3 : Écrire l'implémentation**
Créer `packages/integrations/src/unifi-os/unifi-sm-api.ts` :
```ts
import { createLogger } from "@homarr/core/infrastructure/logs";
import type { UnifiOsFetch } from "./unifi-os-api";
import type { UnifiOsIspMetrics } from "./unifi-os-types";
import { matchCloudSite, parseUnifiOsAsync, unifiSmIspMetricsResponseSchema, unifiSmSiteSchema } from "./unifi-os-types";
import { z } from "zod/v4";
const logger = createLogger({ module: "unifiSmApi" });
const BASE_URL = "https://api.ui.com";
const REQUEST_TIMEOUT_MS = 15_000;
/**
* Les métriques cloud sont agrégées par tranches de 5 min et publiées avec un
* retard mesuré d'environ 27 min. Les rafraîchir plus souvent que le cache
* n'apporterait aucune donnée nouvelle et rapprocherait d'une limitation de débit.
*/
const CACHE_TTL_MS = 5 * 60 * 1000;
/** Une fenêtre de 15 min renvoie un tableau vide sur l'API réelle ; 3 h fonctionne. */
const QUERY_WINDOW_MS = 3 * 60 * 60 * 1000;
const siteListSchema = z.looseObject({ data: z.array(unifiSmSiteSchema) });
interface CacheEntry {
expiresAt: number;
value: UnifiOsIspMetrics | null;
}
/**
* Client de l'API cloud Site Manager. Entièrement optionnel : il n'est instancié
* que lorsqu'une clé Site Manager est configurée.
*
* Toute erreur est absorbée et convertie en `null`. Le cloud est un enrichissement ;
* son indisponibilité ne doit jamais faire tomber le widget.
*/
export class UnifiSmApi {
private static readonly cache = new Map<string, CacheEntry>();
constructor(
private readonly apiKey: string,
private readonly fetchAsync: UnifiOsFetch,
) {}
/** Réservé aux tests : le cache est statique et survivrait d'un cas à l'autre. */
public static clearCache(): void {
UnifiSmApi.cache.clear();
}
public async getIspMetricsAsync(gatewayMac: string | null): Promise<UnifiOsIspMetrics | null> {
if (gatewayMac === null) return null;
const cached = UnifiSmApi.cache.get(gatewayMac);
if (cached !== undefined && cached.expiresAt > Date.now()) {
return cached.value;
}
let value: UnifiOsIspMetrics | null = null;
try {
value = await this.fetchIspMetricsAsync(gatewayMac);
} catch (error) {
logger.warn("Failed to read UniFi Site Manager metrics", { error });
}
UnifiSmApi.cache.set(gatewayMac, { expiresAt: Date.now() + CACHE_TTL_MS, value });
return value;
}
private async fetchIspMetricsAsync(gatewayMac: string): Promise<UnifiOsIspMetrics | null> {
const sitesResponse = await this.fetchAsync(`${BASE_URL}/v1/sites`, {
headers: { "X-API-KEY": this.apiKey, Accept: "application/json" },
timeout: REQUEST_TIMEOUT_MS,
});
if (!sitesResponse.ok) return null;
const sites = await parseUnifiOsAsync(await sitesResponse.json(), siteListSchema, "Invalid Site Manager sites response");
const site = matchCloudSite(gatewayMac, sites.data);
if (site === null) return null;
const end = new Date();
const begin = new Date(end.getTime() - QUERY_WINDOW_MS);
const metricsResponse = await this.fetchAsync(`${BASE_URL}/v1/isp-metrics/5m/query`, {
method: "POST",
headers: { "X-API-KEY": this.apiKey, Accept: "application/json", "Content-Type": "application/json" },
timeout: REQUEST_TIMEOUT_MS,
body: JSON.stringify({
sites: [
{
hostId: site.hostId,
siteId: site.siteId,
beginTimestamp: begin.toISOString(),
endTimestamp: end.toISOString(),
},
],
}),
});
if (!metricsResponse.ok) return null;
const parsed = await parseUnifiOsAsync(
await metricsResponse.json(),
unifiSmIspMetricsResponseSchema,
"Invalid Site Manager ISP metrics response",
);
const periods = parsed.data.metrics[0]?.periods ?? [];
const latest = periods.at(-1);
const wan = latest?.data.wan;
if (latest === undefined || wan === undefined) return null;
const externalIp = Object.values(site.statistics?.wans ?? {})
.map((entry) => entry.externalIp)
.find((ip) => ip !== undefined);
return {
name: wan.ispName ?? site.statistics?.ispInfo?.name ?? "",
externalIp: externalIp ?? null,
latencyMs: wan.avgLatency ?? 0,
maxLatencyMs: wan.maxLatency ?? 0,
packetLossPct: wan.packetLoss ?? 0,
uptimePct: wan.uptime ?? site.statistics?.percentages?.wanUptime ?? 0,
measuredAt: new Date(latest.metricTime),
};
}
}
```
- [ ] **Step 4 : Lancer les tests pour vérifier qu'ils passent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts`
Expected: PASS, 7 tests.
- [ ] **Step 5 : Committer**
```bash
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add optional UniFi Site Manager client with 5min cache"
```
---
## Task 5 : Classe d'intégration et enregistrement
**Files:**
- Create: `packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts`
- Create: `packages/integrations/src/unifi-os/unifi-os-integration.ts`
- Test: `packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts`
- Modify: `packages/integrations/src/base/creator.ts`
- Modify: `packages/integrations/src/index.ts`
- Modify: `packages/integrations/src/types.ts`
**Interfaces:**
- Consumes: `UnifiOsApi` (Task 3), `UnifiSmApi` (Task 4), les mappers et types (Task 2), le kind `unifiOs` (Task 1).
- Produces :
- `interface UnifiOsSummaryIntegration { getUnifiOsSummaryAsync(): Promise<UnifiOsSummary> }`
- `class UnifiOsIntegration extends Integration implements UnifiOsSummaryIntegration`
- entrée `unifiOs` dans `integrationCreators`
- [ ] **Step 1 : Écrire les tests qui échouent**
Créer `packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts` :
```ts
// @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);
});
});
```
- [ ] **Step 2 : Lancer les tests pour vérifier qu'ils échouent**
Run: `pnpm test packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts`
Expected: FAIL — `Cannot find module '../unifi-os-integration'`.
- [ ] **Step 3 : Écrire l'interface**
Créer `packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts` :
```ts
import type { UnifiOsSummary } from "../../unifi-os/unifi-os-types";
export interface UnifiOsSummaryIntegration {
getUnifiOsSummaryAsync(): Promise<UnifiOsSummary>;
}
```
- [ ] **Step 4 : Écrire la classe d'intégration**
Créer `packages/integrations/src/unifi-os/unifi-os-integration.ts` :
```ts
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 type { UnifiOsSummaryIntegration } from "../interfaces/unifi-os-summary/unifi-os-summary-integration";
import type { UnifiOsFetch } from "./unifi-os-api";
import { UnifiOsApi } from "./unifi-os-api";
import { UnifiSmApi } from "./unifi-sm-api";
import type { UnifiOsDevice, UnifiOsDeviceStatistics, UnifiOsSummary } from "./unifi-os-types";
import { findGateway, summarizeDevices } from "./unifi-os-types";
const EMPTY_CLIENT_COUNTS = { total: 0, wired: 0, wireless: 0, vpn: 0, guests: 0 } as const;
const EMPTY_DEVICE_COUNTS = { total: 0, online: 0, offline: 0, firmwareUpdatable: 0 } as const;
/** `Promise.allSettled` renvoie `rejected` sans valeur ; on retombe sur un défaut. */
const settledValue = <T>(result: PromiseSettledResult<T>, fallback: T): T =>
result.status === "fulfilled" ? result.value : fallback;
export class UnifiOsIntegration extends Integration implements UnifiOsSummaryIntegration {
public async getUnifiOsSummaryAsync(): Promise<UnifiOsSummary> {
return await this.buildSummaryAsync(fetchWithTrustedCertificatesAsync as UnifiOsFetch);
}
protected async testingAsync({ fetchAsync }: IntegrationTestingInput): Promise<TestingResult> {
const api = this.createLocalApi(fetchAsync as unknown as UnifiOsFetch);
try {
await api.getInfoAsync();
} catch (error) {
return TestConnectionError.UnknownResult(error);
}
const site = await api.getFirstSiteAsync();
if (site === null) {
// Une clé valide sur une console sans site est configurable mais inutile :
// mieux vaut le dire au moment du test que laisser un widget vide.
return TestConnectionError.UnknownResult(new Error("The UniFi OS console exposes no site"));
}
return { success: true };
}
private createLocalApi(fetchAsync: UnifiOsFetch) {
return new UnifiOsApi(this.integration.url, this.getSecretValue("apiKey"), fetchAsync);
}
private async buildSummaryAsync(fetchAsync: UnifiOsFetch): Promise<UnifiOsSummary> {
const api = this.createLocalApi(fetchAsync);
const [info, site] = await Promise.all([api.getInfoAsync(), api.getFirstSiteAsync()]);
if (site === null) {
throw new Error("The UniFi OS console exposes no site");
}
const [clientsResult, devicesResult] = await Promise.allSettled([
api.getClientCountsAsync(site.id),
api.getDevicesAsync(site.id),
]);
const clients = settledValue(clientsResult, { ...EMPTY_CLIENT_COUNTS });
const devices = settledValue<UnifiOsDevice[]>(devicesResult, []);
const gatewayDevice = findGateway(devices);
// Les statistiques dépendent du gateway : sans gateway identifié, il n'y a
// rien à demander. Un échec ici ne doit vider que le débit et l'uptime.
let statistics: UnifiOsDeviceStatistics | null = null;
if (gatewayDevice !== null) {
try {
statistics = await api.getDeviceStatisticsAsync(site.id, gatewayDevice.id);
} catch {
statistics = null;
}
}
const isp = await this.readIspMetricsAsync(fetchAsync, gatewayDevice?.macAddress ?? null);
return {
site: { id: site.id, name: site.name, applicationVersion: info.applicationVersion },
wan: {
state: gatewayDevice === null ? "unknown" : gatewayDevice.state === "ONLINE" ? "online" : "offline",
throughput:
statistics?.uplink === undefined
? null
: { txBps: statistics.uplink.txRateBps, rxBps: statistics.uplink.rxRateBps },
isp,
},
clients,
devices: devicesResult.status === "fulfilled" ? summarizeDevices(devices) : { ...EMPTY_DEVICE_COUNTS },
gateway:
gatewayDevice === null
? null
: {
name: gatewayDevice.name,
model: gatewayDevice.model,
macAddress: gatewayDevice.macAddress,
uptimeSec: statistics?.uptimeSec ?? null,
cpuPct: statistics?.cpuUtilizationPct ?? null,
memoryPct: statistics?.memoryUtilizationPct ?? null,
},
};
}
/**
* Le cloud n'est jamais interrogé sans clé configurée : le module n'est même
* pas instancié, ce qui rend impossible un appel réseau accidentel.
*/
private async readIspMetricsAsync(fetchAsync: UnifiOsFetch, gatewayMac: string | null) {
if (!this.hasSecretValue("siteManagerApiKey")) return null;
const smApi = new UnifiSmApi(this.getSecretValue("siteManagerApiKey"), fetchAsync);
return await smApi.getIspMetricsAsync(gatewayMac);
}
}
```
- [ ] **Step 5 : Enregistrer la classe**
Dans `packages/integrations/src/base/creator.ts`, ajouter l'import à côté de celui de `UnifiControllerIntegration` :
```ts
import { UnifiOsIntegration } from "../unifi-os/unifi-os-integration";
```
et, dans l'objet des créateurs, juste après `unifiController: UnifiControllerIntegration,` :
```ts
unifiOs: UnifiOsIntegration,
```
Dans `packages/integrations/src/index.ts`, ajouter :
```ts
export { UnifiOsIntegration } from "./unifi-os/unifi-os-integration";
```
Dans `packages/integrations/src/types.ts`, à côté de la ligne `export * from "./unifi-controller/unifi-controller-types";` :
```ts
export * from "./unifi-os/unifi-os-types";
export * from "./interfaces/unifi-os-summary/unifi-os-summary-integration";
```
- [ ] **Step 6 : Lancer les tests pour vérifier qu'ils passent**
Run: `pnpm test packages/integrations/src/unifi-os/`
Expected: PASS, l'ensemble des tests des tâches 2 à 5.
- [ ] **Step 7 : Vérifier le typage**
Run: `pnpm turbo typecheck --filter=@homarr/integrations`
Expected: PASS.
- [ ] **Step 8 : Vérifier qu'aucune intégration existante n'a bougé**
```bash
git status --short packages/integrations/src/unifi-controller packages/integrations/src/opnsense packages/integrations/src/interfaces/network-controller-summary
```
Expected: aucune sortie. Une sortie non vide signifie que la contrainte « ne pas toucher aux intégrations existantes » a été violée — annuler ces modifications.
- [ ] **Step 9 : Committer**
```bash
pnpm format
git add packages/integrations/
git commit -m "feat(integrations): add UnifiOsIntegration with optional cloud enrichment"
```
---
## Task 6 : Request handler et routeur tRPC
**Files:**
- Create: `packages/request-handler/src/unifi-os.ts`
- Create: `packages/api/src/router/widgets/unifi-os.ts`
- Modify: `packages/api/src/router/widgets/index.ts`
**Interfaces:**
- Consumes: `UnifiOsIntegration.getUnifiOsSummaryAsync()` et le type `UnifiOsSummary` (Task 5).
- Produces :
- `unifiOsRequestHandler` avec `.handler(integration, {}).getDataAsync()`
- `unifiOsRouter` exposant `clientApi.widget.unifiOs.summary.useQuery({ integrationIds })`
- [ ] **Step 1 : Écrire le request handler**
Créer `packages/request-handler/src/unifi-os.ts`, calqué sur `network-controller.ts` :
```ts
import { createIntegrationAsync } from "@homarr/integrations";
import type { UnifiOsSummary } from "@homarr/integrations/types";
import { createIntegrationRequestHandler } from "./lib/integration-request-handler";
export const unifiOsRequestHandler = createIntegrationRequestHandler<UnifiOsSummary, "unifiOs", Record<string, never>>({
async requestAsync(integration, _input) {
const integrationInstance = await createIntegrationAsync(integration);
return await integrationInstance.getUnifiOsSummaryAsync();
},
cacheTtlMs: 60 * 1000,
// Une console momentanément injoignable doit afficher la dernière valeur connue
// plutôt qu'une tuile d'erreur ; le widget signale la péremption.
fallbackToStaleOnError: true,
staleIfErrorTtlMs: 10 * 60 * 1000,
});
```
Le paramètre de kind est ici le littéral `"unifiOs"` et non `IntegrationKindByCategory<"unifiOs">` : une seule intégration appartient à cette catégorie, et l'écrire en clair évite un aller-retour de lecture.
- [ ] **Step 2 : Écrire le routeur tRPC**
Créer `packages/api/src/router/widgets/unifi-os.ts` :
```ts
import { unifiOsRequestHandler } from "@homarr/request-handler/unifi-os";
import { createManyIntegrationMiddleware } from "../../middlewares/integration";
import { settleIntegrationQueries } from "../../settle-integrations";
import { createTRPCRouter, publicProcedure } from "../../trpc";
export const unifiOsRouter = createTRPCRouter({
summary: publicProcedure.concat(createManyIntegrationMiddleware("query", "unifiOs")).query(async ({ ctx }) => {
return await settleIntegrationQueries(ctx.integrations, async (integration) => {
const innerHandler = unifiOsRequestHandler.handler(integration, {});
const { data, timestamp } = await innerHandler.getDataAsync();
return {
integration: {
id: integration.id,
name: integration.name,
kind: integration.kind,
},
summary: data,
updatedAt: timestamp,
};
});
}),
});
```
- [ ] **Step 3 : Enregistrer le routeur**
Dans `packages/api/src/router/widgets/index.ts`, à côté de la ligne `networkController: lazy(...)`, ajouter :
```ts
unifiOs: lazy(() => import("./unifi-os").then((mod) => mod.unifiOsRouter)),
```
- [ ] **Step 4 : Vérifier l'export du sous-chemin `@homarr/request-handler/unifi-os`**
Run: `grep -n '"./\*"\|exports' packages/request-handler/package.json`
Expected: le champ `exports` utilise un motif générique (`"./*"`). Si ce n'est pas le cas, ajouter explicitement l'entrée `"./unifi-os"` en copiant la forme de `"./network-controller"`.
- [ ] **Step 5 : Vérifier le typage**
Run: `pnpm turbo typecheck --filter=@homarr/api --filter=@homarr/request-handler`
Expected: PASS.
- [ ] **Step 6 : Committer**
```bash
pnpm format
git add packages/request-handler/src/unifi-os.ts packages/api/src/router/widgets/
git commit -m "feat(api): expose unifiOs widget summary query"
```
---
## Task 7 : Widget
**Files:**
- Create: `packages/widgets/src/unifi-os/index.ts`
- Create: `packages/widgets/src/unifi-os/component.tsx`
- Modify: `packages/widgets/src/manifest.ts`
- Modify: `packages/widgets/src/index.tsx`
- Modify: `packages/widgets/src/catalog.ts`
- Modify: `packages/widgets/src/refetch-intervals.ts`
- Modify: `packages/translation/src/lang/en.json`
**Interfaces:**
- Consumes: `clientApi.widget.unifiOs.summary` (Task 6), `UnifiOsSummary` (Task 2), le `WidgetKind` `unifiOs` (Task 1).
- Produces: le widget affichable, disposition « bandeau WAN + lignes » de la spec §8.
- [ ] **Step 1 : Écrire la définition du widget**
Créer `packages/widgets/src/unifi-os/index.ts` :
```ts
import { IconRouter, IconServerOff } from "@tabler/icons-react";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("unifiOs", {
icon: IconRouter,
supportedIntegrations: ["unifiOs"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from((factory) => ({
showIsp: factory.switch({ defaultValue: true, withDescription: true }),
showDevices: factory.switch({ defaultValue: true, withDescription: true }),
showFirmwareUpdates: factory.switch({ defaultValue: true, withDescription: true }),
}));
},
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
message: (t) => t("widget.unifiOs.error.internalServerError"),
},
},
}).withDynamicImport(() => import("./component"));
```
- [ ] **Step 2 : Écrire le composant**
Créer `packages/widgets/src/unifi-os/component.tsx`. Disposition : bandeau WAN
dominant, puis une ligne par thème.
```tsx
"use client";
import { useMemo } from "react";
import { Badge, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
import { IconCircleFilled } from "@tabler/icons-react";
import dayjs from "dayjs";
import relativeTime from "dayjs/plugin/relativeTime";
import { clientApi } from "@homarr/api/client";
import { useI18n } from "@homarr/translation/client";
import type { WidgetComponentProps } from "../definition";
dayjs.extend(relativeTime);
const formatBitsPerSecond = (bps: number): string => {
const units = ["b/s", "Kb/s", "Mb/s", "Gb/s"];
let value = bps;
let unitIndex = 0;
while (value >= 1000 && unitIndex < units.length - 1) {
value /= 1000;
unitIndex += 1;
}
return `${value.toFixed(value >= 100 || unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
};
const formatUptime = (seconds: number): string => {
const days = Math.floor(seconds / 86400);
const hours = Math.floor((seconds % 86400) / 3600);
return days > 0 ? `${days}d ${hours}h` : `${hours}h`;
};
export default function UnifiOsWidget({ integrationIds, options }: WidgetComponentProps<"unifiOs">) {
const t = useI18n();
const { data: results = [] } = clientApi.widget.unifiOs.summary.useQuery({ integrationIds });
const summary = useMemo(() => results[0]?.summary ?? null, [results]);
if (summary === null) {
return (
<Box h="100%" p="sm">
<Text c="dimmed" size="sm">
{t("widget.unifiOs.error.noData")}
</Text>
</Box>
);
}
const wanColor = summary.wan.state === "online" ? "green" : summary.wan.state === "offline" ? "red" : "gray";
return (
<Stack h="100%" p="sm" gap="xs" justify="space-between">
{/* Le nom du site n'est pas décoratif : une console peut héberger plusieurs
sites et le widget n'en affiche qu'un. L'afficher rend ce choix visible. */}
<Group gap={6} wrap="nowrap">
<IconCircleFilled size={8} color={`var(--mantine-color-${wanColor}-6)`} />
<Text size="xs" c="dimmed" tt="uppercase" fw={600} truncate>
{summary.site.name}
</Text>
</Group>
<Stack gap={4} p="xs" style={{ borderRadius: "var(--mantine-radius-md)", background: "var(--mantine-color-default-hover)" }}>
<Group justify="space-between" wrap="nowrap" gap="xs">
<Group gap={6} wrap="nowrap">
<IconCircleFilled size={10} color={`var(--mantine-color-${wanColor}-6)`} />
<Text fw={600} size="sm">
{t("widget.unifiOs.card.internet")}
</Text>
</Group>
{summary.wan.throughput !== null && (
<Text size="sm" ff="monospace">
↑{formatBitsPerSecond(summary.wan.throughput.txBps)} ↓{formatBitsPerSecond(summary.wan.throughput.rxBps)}
</Text>
)}
</Group>
{options.showIsp && summary.wan.isp !== null && (
<Group justify="space-between" wrap="nowrap" gap="xs">
<Text size="xs" c="dimmed" truncate>
{summary.wan.isp.name}
{summary.wan.isp.externalIp !== null ? ` · ${summary.wan.isp.externalIp}` : ""}
</Text>
<Group gap={6} wrap="nowrap">
<Text size="xs">
{t("widget.unifiOs.card.latency", { value: `${summary.wan.isp.latencyMs}` })}
</Text>
<Tooltip label={t("widget.unifiOs.card.measuredAt", { time: dayjs(summary.wan.isp.measuredAt).format("HH:mm") })}>
<Badge size="xs" variant="light" color="yellow">
{dayjs(summary.wan.isp.measuredAt).fromNow()}
</Badge>
</Tooltip>
</Group>
</Group>
)}
</Stack>
<Stack gap={2}>
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.clients")}
</Text>
<Text size="sm" fw={600}>
{t("widget.unifiOs.card.clientBreakdown", {
total: `${summary.clients.total}`,
wired: `${summary.clients.wired}`,
wireless: `${summary.clients.wireless}`,
})}
</Text>
</Group>
{options.showDevices && (
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.devices")}
</Text>
<Text size="sm" fw={600} c={summary.devices.offline > 0 ? "red" : undefined}>
{t("widget.unifiOs.card.devicesOnline", {
online: `${summary.devices.online}`,
total: `${summary.devices.total}`,
})}
</Text>
</Group>
)}
{options.showFirmwareUpdates && summary.devices.firmwareUpdatable > 0 && (
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.firmware")}
</Text>
<Text size="sm" fw={600} c="yellow">
{t("widget.unifiOs.card.firmwarePending", { count: `${summary.devices.firmwareUpdatable}` })}
</Text>
</Group>
)}
</Stack>
<Group justify="space-between" wrap="nowrap">
<Text size="xs" c="dimmed" truncate>
{t("widget.unifiOs.card.version", { version: summary.site.applicationVersion })}
</Text>
{summary.gateway?.uptimeSec != null && (
<Text size="xs" c="dimmed">
{t("widget.unifiOs.card.gatewayUptime", { uptime: formatUptime(summary.gateway.uptimeSec) })}
</Text>
)}
</Group>
</Stack>
);
}
```
- [ ] **Step 3 : Enregistrer dans le manifeste**
Dans `packages/widgets/src/manifest.ts`, ajouter dans la carte des modules (à côté de `networkControllerSummary`) :
```ts
unifiOs: () => import("./unifi-os") as Promise<WidgetModule>,
```
et dans la carte des composants :
```ts
unifiOs: () => import("./unifi-os/component") as Promise<WidgetComponentModule>,
```
- [ ] **Step 4 : Enregistrer dans l'index et le catalogue**
Dans `packages/widgets/src/index.tsx`, ajouter l'import à côté de `networkControllerSummary` :
```ts
import * as unifiOs from "./unifi-os";
```
et l'entrée correspondante dans l'objet exporté :
```ts
unifiOs,
```
Dans `packages/widgets/src/catalog.ts`, importer `IconRouter` depuis `@tabler/icons-react` (en respectant l'ordre alphabétique de la liste d'imports existante) et ajouter au `widgetCatalogIcons` :
```ts
unifiOs: IconRouter,
```
**L'icône doit être exactement la même que celle de la définition** — `manifest.spec.ts` compare les deux par identité (`toBe`).
- [ ] **Step 5 : Déclarer l'intervalle de rafraîchissement**
Dans `packages/widgets/src/refetch-intervals.ts`, ajouter à `widgetQueryRefetchIntervals` :
```ts
{ queryKey: [["widget", "unifiOs"]], intervalSeconds: 60 },
```
- [ ] **Step 6 : Ajouter les traductions**
Dans `packages/translation/src/lang/en.json`, dans l'objet `widget`, ajouter :
```json
"unifiOs": {
"name": "UniFi OS",
"description": "Network overview from a UniFi OS console",
"option": {
"showIsp": { "label": "Show ISP details", "description": "Requires a Site Manager API key" },
"showDevices": { "label": "Show devices", "description": "Display how many devices are online" },
"showFirmwareUpdates": { "label": "Show firmware updates", "description": "Display how many devices have a pending firmware update" }
},
"card": {
"internet": "Internet",
"latency": "{value} ms",
"measuredAt": "Measured at {time}",
"clients": "Clients",
"clientBreakdown": "{total} · {wired} wired · {wireless} Wi-Fi",
"devices": "Devices",
"devicesOnline": "{online} / {total} online",
"firmware": "Firmware",
"firmwarePending": "{count} to update",
"version": "Network {version}",
"gatewayUptime": "Gateway up {uptime}"
},
"error": {
"internalServerError": "Could not reach the UniFi OS console",
"noData": "No data available"
}
}
```
- [ ] **Step 7 : Lancer les tests du paquet widgets**
Run: `pnpm test packages/widgets/src/manifest.spec.ts`
Expected: PASS. Ce test vérifie que le nouveau `WidgetKind` est présent dans le manifeste, dans le catalogue avec la **même** icône, et dans les intervalles de rafraîchissement. Un échec ici indique un point d'enregistrement oublié.
- [ ] **Step 8 : Vérifier le typage global**
Run: `pnpm turbo typecheck`
Expected: PASS sur tous les paquets.
- [ ] **Step 9 : Lint**
Run: `pnpm lint`
Expected: PASS.
- [ ] **Step 10 : Committer**
```bash
pnpm format
git add packages/widgets/ packages/translation/src/lang/en.json
git commit -m "feat(widgets): add UniFi OS widget"
```
---
## Task 8 : Vérification contre la console réelle
Les tâches précédentes prouvent que le code fait ce qu'on croit. Celle-ci prouve
que ce qu'on croit correspond à la réalité.
**Files:**
- Aucun fichier versionné n'est créé. Le script de vérification reste hors dépôt.
**Interfaces:**
- Consumes: l'intégralité des tâches 1 à 7.
- Produces: la confirmation que les valeurs affichées correspondent à la console.
- [ ] **Step 1 : Démarrer l'environnement de développement**
```bash
corepack enable
pnpm install
pnpm docker:dev:up
pnpm dev
```
- [ ] **Step 2 : Créer l'intégration dans l'interface**
Dans Homarr, créer une intégration de type **UniFi OS** :
- URL : l'origine de la console, sans chemin.
- `apiKey` : clé générée dans l'application Network (Paramètres → Control Plane → Integrations). **Pas** une clé du site manager : elle serait rejetée en `401`.
- `siteManagerApiKey` : optionnelle, générée sur `unifi.ui.com`.
Puis lancer le **test de connexion**.
Expected: succès. Un échec ici concerne la couche cliente, pas l'interface.
- [ ] **Step 3 : Comparer les valeurs à la console**
Ajouter le widget UniFi OS sur un board et comparer, champ par champ, avec
l'interface UniFi :
| Champ | Où vérifier dans UniFi |
|---|---|
| Clients filaires / Wi-Fi | Client Devices, filtré par type de connexion |
| Équipements en ligne | UniFi Devices |
| Firmwares en attente | UniFi Devices, colonne de mise à jour |
| Débit WAN | Tableau de bord, graphe du gateway |
| Latence et fraîcheur | Site Manager cloud — l'écart d'environ 27 min est **attendu** |
- [ ] **Step 4 : Vérifier la dégradation**
Retirer la `siteManagerApiKey` de l'intégration et recharger.
Expected: le bloc ISP disparaît, tout le reste continue de s'afficher.
- [ ] **Step 5 : Consigner l'écart éventuel**
Si un chiffre diverge, ne pas ajuster le widget : corriger le mapper de la Task 2
et **ajouter un test** reproduisant le cas. Un chiffre corrigé sans test revient
la fois suivante.
---
## Task 9 : Build et déploiement sur le LXC
**Files:**
- Aucun fichier versionné.
**Interfaces:**
- Consumes: une branche `feat/unifi-os-integration` dont toutes les tâches sont validées.
- Produces: l'instance de production servant le widget.
⚠️ Ne pas démarrer cette tâche tant que la Task 8 n'est pas concluante.
- [ ] **Step 1 : Vérifier l'alignement des migrations avant toute chose**
```bash
ls packages/db/migrations/sqlite/ | tail -3
ssh zachary@10.70.1.13 'ls /opt/homarr/db/migrations/*/ | tail -3'
```
Expected: la dernière migration est identique des deux côtés. **Si elles
divergent, arrêter** et traiter la mise à jour de schéma comme un sujet distinct :
le rollback ne serait plus une simple restauration d'archive.
- [ ] **Step 2 : Construire**
```bash
pnpm turbo build
```
Expected: build complet sans erreur.
- [ ] **Step 3 : Sauvegarder l'instance**
```bash
ssh zachary@10.70.1.13 'sudo tar czf /root/homarr-backup-$(date +%F-%H%M).tar.gz /opt/homarr && sudo ls -la /root/ | grep homarr-backup'
```
Expected: l'archive existe et n'est pas vide. Sauvegarder également la base
selon le `DB_DRIVER` déclaré dans `/etc/homarr/homarr.env`.
- [ ] **Step 4 : Arrêter le service**
```bash
ssh zachary@10.70.1.13 'sudo systemctl stop homarr && systemctl is-active homarr || true'
```
Expected: `inactive`. Ne jamais rsync sur un Next.js en cours d'exécution.
- [ ] **Step 5 : Déployer**
Reproduire la disposition existante de `/opt/homarr` (`apps/`, `packages/`,
`build/`, `node_modules/`) à partir de la sortie standalone du build. **Ne pas
toucher** à `/etc/homarr/homarr.env` ni à `run.sh`, `nginx.conf`, `redis.conf`,
`entrypoint.sh`, qui appartiennent à l'installation et non au build.
- [ ] **Step 6 : Redémarrer et vérifier**
```bash
ssh zachary@10.70.1.13 'sudo systemctl start homarr && sleep 10 && systemctl is-active homarr && sudo journalctl -u homarr -n 40 --no-pager'
```
Expected: `active`, aucune erreur de migration dans les journaux.
- [ ] **Step 7 : Vérifier dans le navigateur**
Ouvrir l'instance de production, vérifier que le widget affiche les mêmes valeurs
qu'en développement, et que les intégrations **préexistantes** fonctionnent
toujours — c'est le contrôle qui prouve que `SECRET_ENCRYPTION_KEY` est intact.
- [ ] **Step 8 : En cas de problème, restaurer**
```bash
ssh zachary@10.70.1.13 'sudo systemctl stop homarr && sudo rm -rf /opt/homarr && sudo tar xzf /root/homarr-backup-<horodatage>.tar.gz -C / && sudo systemctl start homarr'
```
---
## Points laissés ouverts
À trancher hors de ce plan, sans bloquer son exécution :
1. **Où pousser le fork.** Une instance Gitea est disponible. Sans dépôt distant,
la branche n'existe que sur le poste — une panne de disque effacerait le travail.
2. **Stratégie de rebase.** Homarr publie fréquemment. Les modifications sont
concentrées dans un dossier neuf, mais les douze points d'attache du §5.2 de la
spec sont autant de sources de conflit à chaque montée de version.
3. **Révocation des clés d'API** utilisées pendant la conception.