feat(api): expose unifiOs widget summary query through tRPC router and request handler

Create unifiOs request handler with 60s cache and stale-on-error fallback, and tRPC router exposing clientApi.widget.unifiOs.summary query. Include minimal widget stub for type system.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/api/src/router/widgets/index.ts

@@ -33,6 +33,7 @@ export const widgetRouter = createTRPCRouter({
   options: lazy(() => import("./options").then((mod) => mod.optionsRouter)),
   releases: lazy(() => import("./releases").then((mod) => mod.releasesRouter)),
   networkController: lazy(() => import("./network-controller").then((mod) => mod.networkControllerRouter)),
+  unifiOs: lazy(() => import("./unifi-os").then((mod) => mod.unifiOsRouter)),
   firewall: lazy(() => import("./firewall").then((mod) => mod.firewallRouter)),
   notifications: lazy(() => import("./notifications").then((mod) => mod.notificationsRouter)),
   timetable: lazy(() => import("./timetable").then((mod) => mod.timetableRouter)),

packages/api/src/router/widgets/unifi-os.ts

@@ -0,0 +1,24 @@
+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,
+      };
+    });
+  }),
+});

packages/request-handler/src/unifi-os.ts

@@ -0,0 +1,16 @@
+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,
+});

packages/widgets/src/unifi-os/component.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import type { WidgetComponentProps } from "../definition";
+
+export default function UnifiOsWidgetComponent({ integrationIds }: WidgetComponentProps<"unifiOs">) {
+  return <div>UniFi OS Widget</div>;
+}

packages/widgets/src/unifi-os/index.ts

@@ -0,0 +1,12 @@
+import { IconWifi } from "@tabler/icons-react";
+
+import { createWidgetDefinition } from "../definition";
+import { optionsBuilder } from "../options";
+
+export const { definition, componentLoader } = createWidgetDefinition("unifiOs", {
+  icon: IconWifi,
+  createOptions() {
+    return optionsBuilder.from((factory) => ({}));
+  },
+  supportedIntegrations: ["unifiOs"],
+}).withDynamicImport(() => import("./component"));