feat: custom widgets (#5889)

packages/api/src/root.ts

@@ -29,6 +29,7 @@ export const appRouter = createTRPCRouter({
   certificates: lazy(() => import("./router/certificates/certificate-router").then((mod) => mod.certificateRouter)),
   bangs: lazy(() => import("./router/bangs/bangs-router").then((mod) => mod.bangsRouter)),
   info: lazy(() => import("./router/info").then((mod) => mod.infoRouter)),
+  customWidget: lazy(() => import("./router/custom-widget/custom-widget-router").then((mod) => mod.customWidgetRouter)),
 });
 
 // export type definition of API

packages/api/src/router/board.ts

@@ -2,6 +2,7 @@ import { TRPCError } from "@trpc/server";
 import superjson from "superjson";
 import { z } from "zod/v4";
 
+import { createLogger } from "@homarr/core/infrastructure/logs";
 import { constructBoardPermissions } from "@homarr/auth/shared";
 import { createId } from "@homarr/common";
 import type { DeviceType } from "@homarr/common/server";
@@ -1768,7 +1769,7 @@ const getFullBoardWithWhereAsync = async (db: Database, where: SQL<unknown>, use
           options: superjson.parse<Record<string, unknown>>(item.options),
         }),
       )
-      .filter((item) => item !== null),
+      .filter((item): item is NonNullable<typeof item> => item !== null),
   };
 };
 
@@ -1780,10 +1781,13 @@ const forKind = <T extends WidgetKind>(kind: T) =>
 
 const outputItemSchema = zodUnionFromArray(widgetKinds.map((kind) => forKind(kind))).and(sharedItemSchema);
 
+const boardLogger = createLogger({ module: "board" });
+
 const parseItem = (item: unknown) => {
   const result = outputItemSchema.safeParse(item);
 
   if (!result.success) {
+    boardLogger.warn("Failed to parse board item, skipping", { error: result.error.message });
     return null;
   }
   return result.data;

packages/api/src/router/custom-widget/auth.ts

@@ -0,0 +1,41 @@
+export const AUTH_HANDLERS: Record<string, (headers: Headers, url: URL, apiKey: string, headerName?: string) => void> =
+  {
+    bearer: (headers, _url, apiKey) => {
+      headers.set("Authorization", `Bearer ${apiKey}`);
+    },
+    apiKeyHeader: (headers, _url, apiKey, headerName) => {
+      headers.set(headerName ?? "X-API-Key", apiKey);
+    },
+    apiKeyQuery: (_headers, url, apiKey, headerName) => {
+      url.searchParams.set(headerName ?? "api_key", apiKey);
+    },
+  };
+
+export function buildSecretMap(secrets: Array<{ kind: string; value: string }>): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const secret of secrets) {
+    map[secret.kind] = secret.value;
+  }
+  return map;
+}
+
+export function applyAuth(
+  headers: Headers,
+  url: URL,
+  authType: string,
+  secrets: Array<{ kind: string; value: string }>,
+  headerName?: string | null,
+): void {
+  const secretMap = buildSecretMap(secrets);
+
+  if (authType === "basic" && secretMap.username && secretMap.password) {
+    const credentials = Buffer.from(`${secretMap.username}:${secretMap.password}`).toString("base64");
+    headers.set("Authorization", `Basic ${credentials}`);
+    return;
+  }
+
+  const handler = AUTH_HANDLERS[authType];
+  if (handler && secretMap.apiKey) {
+    handler(headers, url, secretMap.apiKey, headerName ?? undefined);
+  }
+}

packages/api/src/router/custom-widget/custom-widget-router.ts

@@ -0,0 +1,456 @@
+import { TRPCError } from "@trpc/server";
+import superjson from "superjson";
+import { z } from "zod/v4";
+
+import { createId } from "@homarr/common";
+import { decryptSecret, encryptSecret } from "@homarr/common/server";
+import { customWidgetDefinitions, customWidgetSecrets } from "@homarr/db/schema";
+import { eq } from "@homarr/db";
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import {
+  customWidgetAuthTypes,
+  customWidgetCreateSchema,
+  customWidgetDisplayTypes,
+  customWidgetImportSchema,
+  customWidgetMethods,
+  customWidgetSecretKinds,
+  customWidgetUpdateSchema,
+  displayConfigSchema,
+} from "@homarr/validation/custom-widget";
+
+import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../../trpc";
+import { applyAuth } from "./auth";
+import { extractDisplayDataWithFallback } from "./display-data";
+import { parseDisplayConfig } from "./parse-display-config";
+
+const adminProcedure = permissionRequiredProcedure.requiresPermission("admin");
+
+const logger = createLogger({ module: "custom-widget" });
+
+const FETCH_TIMEOUT_MS = 10_000;
+
+const validateUrl = (urlString: string): URL => new URL(urlString);
+
+const updateFieldSerializers: Record<string, (value: unknown) => unknown> = {
+  displayConfig: (value) => superjson.stringify(value),
+};
+
+let _importJsonSchema: Record<string, unknown> | null = null;
+function getImportJsonSchema() {
+  if (!_importJsonSchema) {
+    _importJsonSchema = {
+      ...z.toJSONSchema(customWidgetImportSchema),
+      title: "Homarr Custom Widget",
+      description:
+        "Schema for importing/exporting custom widget definitions in Homarr. " +
+        "All jsonPath fields use JSONPath syntax (e.g. $.data.count, $.items[0].name). " +
+        "The displayConfig must match the chosen displayType. " +
+        "Secrets (API keys, passwords) are not included in exports and must be configured separately after import.",
+    };
+  }
+  return _importJsonSchema;
+}
+
+export const customWidgetRouter = createTRPCRouter({
+  schema: publicProcedure.query(() => getImportJsonSchema()),
+
+  all: protectedProcedure.query(async ({ ctx }) => {
+    const definitions = await ctx.db.query.customWidgetDefinitions.findMany({
+      orderBy: (table, { asc }) => asc(table.name),
+    });
+
+    return definitions.map((def) => ({
+      id: def.id,
+      name: def.name,
+      description: def.description,
+      iconUrl: def.iconUrl,
+      url: def.url,
+      method: def.method,
+      displayType: def.displayType,
+      authType: def.authType,
+      enabled: def.enabled,
+    }));
+  }),
+
+  byId: protectedProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
+    const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.id),
+      with: { secrets: true },
+    });
+
+    if (!definition) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Custom widget definition not found" });
+    }
+
+    const displayConfig = parseDisplayConfig(
+      definition.displayConfig,
+      input.id,
+      logger,
+      "Corrupt displayConfig in custom widget",
+    );
+
+    return {
+      ...definition,
+      enabled: definition.enabled,
+      displayConfig,
+      secrets: definition.secrets.map((s) => ({
+        kind: s.kind,
+        hasValue: true,
+        updatedAt: s.updatedAt,
+      })),
+    };
+  }),
+
+  create: adminProcedure.input(customWidgetCreateSchema).mutation(async ({ ctx, input }) => {
+    const id = createId();
+
+    await ctx.db.insert(customWidgetDefinitions).values({
+      id,
+      name: input.name,
+      description: input.description,
+      iconUrl: input.iconUrl,
+      url: input.url,
+      authType: input.authType,
+      headerName: input.headerName,
+      method: input.method,
+      requestBody: input.requestBody,
+      displayType: input.displayType,
+      displayConfig: superjson.stringify(input.displayConfig),
+      creatorId: ctx.session.user.id,
+    });
+
+    if (input.secrets.length > 0) {
+      await ctx.db.insert(customWidgetSecrets).values(
+        input.secrets.map((secret) => ({
+          kind: secret.kind,
+          value: encryptSecret(secret.value),
+          definitionId: id,
+          updatedAt: new Date(),
+        })),
+      );
+    }
+
+    logger.info("Created custom widget definition", { id, name: input.name });
+    return { id };
+  }),
+
+  update: adminProcedure.input(customWidgetUpdateSchema).mutation(async ({ ctx, input }) => {
+    const existing = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.id),
+    });
+
+    if (!existing) {
+      throw new TRPCError({ code: "NOT_FOUND" });
+    }
+
+    const { id, secrets, ...updateFields } = input;
+    const updateValues: Record<string, unknown> = { updatedAt: new Date() };
+
+    for (const [key, value] of Object.entries(updateFields)) {
+      if (value === undefined) continue;
+      const serialize = updateFieldSerializers[key];
+      if (serialize) {
+        updateValues[key] = serialize(value);
+      } else {
+        updateValues[key] = value;
+      }
+    }
+
+    await ctx.db.update(customWidgetDefinitions).set(updateValues).where(eq(customWidgetDefinitions.id, id));
+
+    if (secrets !== undefined) {
+      const effectiveAuthType = (updateFields.authType as string | undefined) ?? existing.authType;
+
+      if (secrets.length > 0) {
+        await ctx.db.delete(customWidgetSecrets).where(eq(customWidgetSecrets.definitionId, id));
+        await ctx.db.insert(customWidgetSecrets).values(
+          secrets.map((secret) => ({
+            kind: secret.kind,
+            value: encryptSecret(secret.value),
+            definitionId: id,
+            updatedAt: new Date(),
+          })),
+        );
+      } else if (effectiveAuthType === "none") {
+        await ctx.db.delete(customWidgetSecrets).where(eq(customWidgetSecrets.definitionId, id));
+      }
+    }
+
+    logger.info("Updated custom widget definition", { id });
+  }),
+
+  toggleEnabled: adminProcedure
+    .input(z.object({ id: z.string(), enabled: z.boolean() }))
+    .mutation(async ({ ctx, input }) => {
+      const existing = await ctx.db.query.customWidgetDefinitions.findFirst({
+        where: eq(customWidgetDefinitions.id, input.id),
+      });
+
+      if (!existing) {
+        throw new TRPCError({ code: "NOT_FOUND" });
+      }
+
+      await ctx.db
+        .update(customWidgetDefinitions)
+        .set({ enabled: input.enabled, updatedAt: new Date() })
+        .where(eq(customWidgetDefinitions.id, input.id));
+    }),
+
+  delete: adminProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
+    const existing = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.id),
+    });
+
+    if (!existing) {
+      throw new TRPCError({ code: "NOT_FOUND" });
+    }
+
+    await ctx.db.delete(customWidgetDefinitions).where(eq(customWidgetDefinitions.id, input.id));
+    logger.info("Deleted custom widget definition", { id: input.id });
+  }),
+
+  export: adminProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
+    const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.id),
+    });
+
+    if (!definition) {
+      throw new TRPCError({ code: "NOT_FOUND" });
+    }
+
+    return {
+      $schema: "homarr-custom-widget-v2" as const,
+      name: definition.name,
+      description: definition.description,
+      iconUrl: definition.iconUrl,
+      url: definition.url,
+      authType: definition.authType,
+      headerName: definition.headerName,
+      method: definition.method,
+      requestBody: definition.requestBody,
+      displayType: definition.displayType,
+      displayConfig: parseDisplayConfig(
+        definition.displayConfig,
+        input.id,
+        logger,
+        "Corrupt displayConfig during export",
+      ),
+    };
+  }),
+
+  import: adminProcedure.input(customWidgetImportSchema).mutation(async ({ ctx, input }) => {
+    const id = createId();
+
+    await ctx.db.insert(customWidgetDefinitions).values({
+      id,
+      name: input.name,
+      description: input.description,
+      iconUrl: input.iconUrl,
+      url: input.url,
+      authType: input.authType,
+      headerName: input.headerName,
+      method: input.method,
+      requestBody: input.requestBody,
+      displayType: input.displayType,
+      displayConfig: superjson.stringify(input.displayConfig),
+      creatorId: ctx.session.user.id,
+    });
+
+    logger.info("Imported custom widget definition", { id, name: input.name });
+    return { id };
+  }),
+
+  preview: adminProcedure
+    .input(
+      z.object({
+        url: z.string().url(),
+        method: z.enum(customWidgetMethods),
+        authType: z.enum(customWidgetAuthTypes),
+        headerName: z.string().optional(),
+        requestBody: z.string().optional(),
+        displayType: z.enum(customWidgetDisplayTypes),
+        displayConfig: displayConfigSchema,
+        secrets: z.array(z.object({ kind: z.enum(customWidgetSecretKinds), value: z.string() })),
+        definitionId: z.string().optional(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const secrets = [...input.secrets];
+
+      if (input.definitionId) {
+        const existing = await ctx.db.query.customWidgetDefinitions.findFirst({
+          where: eq(customWidgetDefinitions.id, input.definitionId),
+          with: { secrets: true },
+        });
+        if (existing) {
+          for (const dbSecret of existing.secrets) {
+            if (!secrets.some((s) => s.kind === dbSecret.kind)) {
+              secrets.push({ kind: dbSecret.kind, value: decryptSecret(dbSecret.value) });
+            }
+          }
+        }
+      }
+
+      const url = validateUrl(input.url);
+      const headers = new Headers({ Accept: "application/json" });
+
+      if (input.method !== "GET" && input.requestBody) {
+        headers.set("Content-Type", "application/json");
+      }
+
+      applyAuth(headers, url, input.authType, secrets, input.headerName);
+
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+      try {
+        const response = await fetch(url.toString(), {
+          method: input.method,
+          headers,
+          body: input.method !== "GET" ? input.requestBody : undefined,
+          redirect: "follow",
+          signal: controller.signal,
+        });
+
+        const responseInfo = { status: response.status, statusText: response.statusText };
+
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          return {
+            success: false as const,
+            error: `HTTP ${response.status}: ${response.statusText}`,
+            responseInfo,
+            rawResponse: body,
+          };
+        }
+
+        const json: unknown = await response.json();
+        const displayData = extractDisplayDataWithFallback(json, input.displayType, input.displayConfig);
+
+        return {
+          success: true as const,
+          responseInfo,
+          rawResponse: JSON.stringify(json, null, 2),
+          displayData,
+        };
+      } catch (error) {
+        if (error instanceof TRPCError) throw error;
+        logger.error("Custom widget preview failed", { error });
+        return {
+          success: false as const,
+          error: error instanceof Error ? error.message : "Failed to fetch data",
+          responseInfo: null,
+          rawResponse: null,
+        };
+      } finally {
+        clearTimeout(timeout);
+      }
+    }),
+
+  duplicate: adminProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
+    const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.id),
+      with: { secrets: true },
+    });
+
+    if (!definition) {
+      throw new TRPCError({ code: "NOT_FOUND" });
+    }
+
+    const newId = createId();
+    await ctx.db.insert(customWidgetDefinitions).values({
+      id: newId,
+      name: `${definition.name} (copy)`,
+      description: definition.description,
+      iconUrl: definition.iconUrl,
+      url: definition.url,
+      authType: definition.authType,
+      headerName: definition.headerName,
+      method: definition.method,
+      requestBody: definition.requestBody,
+      displayType: definition.displayType,
+      displayConfig: definition.displayConfig,
+      enabled: definition.enabled,
+      creatorId: ctx.session.user.id,
+    });
+
+    if (definition.secrets.length > 0) {
+      await ctx.db.insert(customWidgetSecrets).values(
+        definition.secrets.map((s) => ({
+          kind: s.kind,
+          value: s.value,
+          definitionId: newId,
+          updatedAt: new Date(),
+        })),
+      );
+    }
+
+    logger.info("Duplicated custom widget definition", { sourceId: input.id, newId });
+    return { id: newId, name: `${definition.name} (copy)` };
+  }),
+
+  execute: protectedProcedure.input(z.object({ definitionId: z.string() })).mutation(async ({ ctx, input }) => {
+    const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.definitionId),
+      with: { secrets: true },
+    });
+
+    if (!definition) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Custom widget definition not found" });
+    }
+
+    if (!definition.enabled) {
+      throw new TRPCError({ code: "FORBIDDEN", message: "Widget is disabled" });
+    }
+
+    if (definition.displayType !== "actionButton") {
+      throw new TRPCError({ code: "BAD_REQUEST", message: "Only actionButton widgets can be executed" });
+    }
+
+    const decryptedSecrets = definition.secrets.map((s) => ({
+      kind: s.kind,
+      value: decryptSecret(s.value),
+    }));
+
+    const url = validateUrl(definition.url);
+    const headers = new Headers({ Accept: "application/json" });
+
+    if (definition.method !== "GET" && definition.requestBody) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    applyAuth(headers, url, definition.authType, decryptedSecrets, definition.headerName);
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: definition.method,
+        headers,
+        body: definition.method !== "GET" ? definition.requestBody : undefined,
+        redirect: "follow",
+        signal: controller.signal,
+      });
+
+      const responseInfo = { status: response.status, statusText: response.statusText };
+
+      if (!response.ok) {
+        return { success: false as const, error: `HTTP ${response.status}: ${response.statusText}`, responseInfo };
+      }
+
+      logger.info("Executed custom widget action", { definitionId: input.definitionId, status: response.status });
+      return { success: true as const, responseInfo };
+    } catch (error) {
+      if (error instanceof TRPCError) throw error;
+      logger.error("Custom widget execute failed", { definitionId: input.definitionId, error });
+      return {
+        success: false as const,
+        error: error instanceof Error ? error.message : "Request failed",
+        responseInfo: null,
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }),
+});

packages/api/src/router/custom-widget/display-data.ts

@@ -0,0 +1,145 @@
+import { JSONPath } from "jsonpath-plus";
+
+type Config = Record<string, unknown>;
+type Extractor = (json: unknown, config: Config) => unknown;
+
+const query = (json: unknown, path: string) => JSONPath({ path, json: json as object, wrap: false });
+
+const queryRows = (json: unknown, path: string): unknown[] => {
+  const rows = JSONPath({ path, json: json as object, wrap: true }) as unknown[];
+  const first = rows[0];
+  if (Array.isArray(first)) return first as unknown[];
+  return rows;
+};
+
+const toNumber = (value: unknown, fallback: number): number => {
+  const num = Number(value);
+  if (num) return num;
+  return fallback;
+};
+
+const optionalMax = (max: unknown): number | undefined => {
+  if (max === undefined) return undefined;
+  return toNumber(max, 100);
+};
+
+const isGoodValue = (value: unknown, goodValues: string[]): boolean =>
+  goodValues.some((gv) => String(value).toLowerCase() === gv.toLowerCase());
+
+const extractors: Record<string, Extractor> = {
+  singleValue: (json, c) => ({
+    type: "singleValue",
+    label: (c.label as string) ?? "",
+    unit: (c.unit as string) ?? "",
+    value: query(json, (c.jsonPath as string) ?? "$"),
+    valueSize: c.valueSize ?? "lg",
+    labelPosition: c.labelPosition ?? "below",
+  }),
+  keyValue: (json, c) => ({
+    type: "keyValue",
+    entries: ((c.mappings as Array<{ label: string; jsonPath: string; unit: string }>) ?? []).map((m) => ({
+      label: m.label,
+      unit: m.unit,
+      value: query(json, m.jsonPath),
+    })),
+    layout: c.layout ?? "list",
+    columns: c.columns ?? 2,
+  }),
+  table: (json, c) => {
+    const columns = (c.columns as Array<{ header: string; jsonPath: string }>) ?? [];
+    const flatRows = queryRows(json, (c.tablePath as string) ?? "$");
+    return {
+      type: "table",
+      columns: columns.map((col) => col.header),
+      rows: flatRows.map((row) => columns.map((col) => query(row, col.jsonPath))),
+      striped: c.striped ?? true,
+      compact: c.compact ?? false,
+    };
+  },
+  statGrid: (json, c) => ({
+    type: "statGrid",
+    items: ((c.items as Array<{ label: string; jsonPath: string; unit: string; color?: string }>) ?? []).map(
+      (item) => ({
+        label: item.label,
+        unit: item.unit,
+        color: item.color ?? "blue",
+        value: query(json, item.jsonPath),
+      }),
+    ),
+    columns: c.columns ?? 2,
+    cardStyle: c.cardStyle ?? "filled",
+  }),
+  progressBars: (json, c) => ({
+    type: "progressBars",
+    bars: (
+      (c.bars as Array<{ label: string; valuePath: string; maxPath?: string; unit: string; color?: string }>) ?? []
+    ).map((bar) => {
+      const value = query(json, bar.valuePath);
+      const max = bar.maxPath ? query(json, bar.maxPath) : undefined;
+      return {
+        label: bar.label,
+        unit: bar.unit,
+        color: bar.color ?? "blue",
+        value: toNumber(value, 0),
+        max: optionalMax(max),
+      };
+    }),
+    showPercentage: c.showPercentage ?? true,
+    barSize: c.barSize ?? "md",
+  }),
+  statusIndicator: (json, c) => ({
+    type: "statusIndicator",
+    items: ((c.items as Array<{ label: string; jsonPath: string; goodValues: string[] }>) ?? []).map((item) => {
+      const value = query(json, item.jsonPath);
+      return { label: item.label, value: String(value ?? "unknown"), isGood: isGoodValue(value, item.goodValues) };
+    }),
+    layout: c.layout ?? "list",
+    dotSize: c.dotSize ?? "md",
+  }),
+  countGrid: (json, c) => ({
+    type: "countGrid",
+    items: ((c.items as Array<{ label: string; jsonPath: string; unit: string }>) ?? []).map((item) => ({
+      label: item.label,
+      unit: item.unit,
+      value: query(json, item.jsonPath),
+    })),
+    columns: c.columns ?? 2,
+    valueSize: c.valueSize ?? "md",
+  }),
+  raw: (json, c) => ({
+    type: "raw",
+    data: query(json, (c.jsonPath as string) ?? "$"),
+    maxHeight: c.maxHeight ?? 300,
+  }),
+  actionButton: (_json, c) => ({
+    type: "actionButton",
+    buttonLabel: c.buttonLabel ?? "Execute",
+    buttonColor: c.buttonColor ?? "blue",
+    confirmText: c.confirmText ?? "",
+    successMessage: c.successMessage ?? "",
+  }),
+  customJsx: (json, config) => ({
+    type: "customJsx" as const,
+    template: config.template as string,
+    data: json,
+  }),
+};
+
+export function extractDisplayData(json: unknown, displayType: string, displayConfig: Config): unknown {
+  const type = (displayConfig.type as string) ?? displayType;
+  const extractor = extractors[type];
+  if (!extractor) {
+    throw new Error(`Unknown display type: ${type}`);
+  }
+  return extractor(json, displayConfig);
+}
+
+export function extractDisplayDataWithFallback(json: unknown, displayType: string, displayConfig: Config): unknown {
+  const type = (displayConfig.type as string) ?? displayType;
+  const extractor = extractors[type] ?? extractors.singleValue;
+  return extractor?.(json, displayConfig);
+}
+
+export function extractActionButtonDisplay(displayConfig: Config): unknown {
+  return extractors.actionButton?.(null, displayConfig);
+}

packages/api/src/router/custom-widget/parse-display-config.ts

@@ -0,0 +1,15 @@
+import { TRPCError } from "@trpc/server";
+import superjson from "superjson";
+
+import type { createLogger } from "@homarr/core/infrastructure/logs";
+
+type Logger = ReturnType<typeof createLogger>;
+
+export function parseDisplayConfig(raw: string, id: string, logger: Logger, context: string): Record<string, unknown> {
+  try {
+    return superjson.parse(raw) as Record<string, unknown>;
+  } catch {
+    logger.error(context, { id });
+    throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "Widget has corrupt display configuration" });
+  }
+}

packages/api/src/router/widgets/__tests__/custom-api-extractors.spec.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+import { JSONPath } from "jsonpath-plus";
+
+import {
+  sonarrResponse,
+  sonarrStatGridConfig,
+  proxmoxResponse,
+  proxmoxProgressBarsConfig,
+  diskUsageResponse,
+  diskTableConfig,
+  piholeResponse,
+  piholeStatusIndicatorConfig,
+  piholeCountGridConfig,
+  radarrResponse,
+  radarrStatGridConfig,
+  jellyfinItemCountsResponse,
+  jellyfinCountGridConfig,
+} from "./custom-api-fixtures";
+
+const extractors: Record<string, (json: unknown, config: Record<string, unknown>) => unknown> = {
+  singleValue: (json, c) => ({
+    type: "singleValue",
+    label: (c.label as string) ?? "",
+    unit: (c.unit as string) ?? "",
+    value: JSONPath({ path: (c.jsonPath as string) ?? "$", json: json as object, wrap: false }),
+    valueSize: c.valueSize ?? "lg",
+    labelPosition: c.labelPosition ?? "below",
+  }),
+  keyValue: (json, c) => ({
+    type: "keyValue",
+    entries: ((c.mappings as Array<{ label: string; jsonPath: string; unit: string }>) ?? []).map((m) => ({
+      label: m.label,
+      unit: m.unit,
+      value: JSONPath({ path: m.jsonPath, json: json as object, wrap: false }),
+    })),
+    layout: c.layout ?? "list",
+    columns: c.columns ?? 2,
+  }),
+  table: (json, c) => {
+    const tablePath = (c.tablePath as string) ?? "$";
+    const columns = (c.columns as Array<{ header: string; jsonPath: string }>) ?? [];
+    const rows = JSONPath({ path: tablePath, json: json as object, wrap: true }) as unknown[];
+    const flatRows = Array.isArray(rows[0]) ? (rows[0] as unknown[]) : rows;
+    return {
+      type: "table",
+      columns: columns.map((col) => col.header),
+      rows: flatRows.map((row) =>
+        columns.map((col) => JSONPath({ path: col.jsonPath, json: row as object, wrap: false })),
+      ),
+      striped: c.striped ?? true,
+      compact: c.compact ?? false,
+    };
+  },
+  statGrid: (json, c) => ({
+    type: "statGrid",
+    items: ((c.items as Array<{ label: string; jsonPath: string; unit: string; color?: string }>) ?? []).map(
+      (item) => ({
+        label: item.label,
+        unit: item.unit,
+        color: item.color ?? "blue",
+        value: JSONPath({ path: item.jsonPath, json: json as object, wrap: false }),
+      }),
+    ),
+    columns: c.columns ?? 2,
+    cardStyle: c.cardStyle ?? "filled",
+  }),
+  progressBars: (json, c) => ({
+    type: "progressBars",
+    bars: (
+      (c.bars as Array<{ label: string; valuePath: string; maxPath?: string; unit: string; color?: string }>) ?? []
+    ).map((bar) => {
+      const value = JSONPath({ path: bar.valuePath, json: json as object, wrap: false });
+      const max = bar.maxPath ? JSONPath({ path: bar.maxPath, json: json as object, wrap: false }) : undefined;
+      return {
+        label: bar.label,
+        unit: bar.unit,
+        color: bar.color ?? "blue",
+        value: Number(value) || 0,
+        max: max !== undefined ? Number(max) || 100 : undefined,
+      };
+    }),
+    showPercentage: c.showPercentage ?? true,
+    barSize: c.barSize ?? "md",
+  }),
+  statusIndicator: (json, c) => ({
+    type: "statusIndicator",
+    items: ((c.items as Array<{ label: string; jsonPath: string; goodValues: string[] }>) ?? []).map((item) => {
+      const value = JSONPath({ path: item.jsonPath, json: json as object, wrap: false });
+      const isGood = item.goodValues.some((gv) => String(value).toLowerCase() === gv.toLowerCase());
+      return { label: item.label, value: String(value ?? "unknown"), isGood };
+    }),
+    layout: c.layout ?? "list",
+    dotSize: c.dotSize ?? "md",
+  }),
+  countGrid: (json, c) => ({
+    type: "countGrid",
+    items: ((c.items as Array<{ label: string; jsonPath: string; unit: string }>) ?? []).map((item) => ({
+      label: item.label,
+      unit: item.unit,
+      value: JSONPath({ path: item.jsonPath, json: json as object, wrap: false }),
+    })),
+    columns: c.columns ?? 2,
+    valueSize: c.valueSize ?? "md",
+  }),
+  raw: (json, c) => ({
+    type: "raw",
+    data: JSONPath({ path: (c.jsonPath as string) ?? "$", json: json as object, wrap: false }),
+    maxHeight: c.maxHeight ?? 300,
+  }),
+  customJsx: (json, config) => ({
+    type: "customJsx" as const,
+    template: config.template as string,
+    data: json,
+  }),
+};
+
+function extract(type: string, json: unknown, config: Record<string, unknown>) {
+  const fn = extractors[type];
+  if (!fn) throw new Error(`No extractor for type: ${type}`);
+  return fn(json, config);
+}
+
+describe("custom-api extractors", () => {
+  it("sonarr statGrid extracts missing and queue counts", () => {
+    const result = extract("statGrid", sonarrResponse, sonarrStatGridConfig) as {
+      type: string;
+      items: Array<{ label: string; value: unknown; color: string }>;
+    };
+
+    expect(result.type).toBe("statGrid");
+    expect(result.items).toHaveLength(2);
+    expect(result.items[0]?.value).toBe(42);
+    expect(result.items[0]?.label).toBe("Missing");
+    expect(result.items[0]?.color).toBe("red");
+    expect(result.items[1]?.value).toBe(5);
+  });
+
+  it("proxmox progressBars extracts memory and disk usage", () => {
+    const result = extract("progressBars", proxmoxResponse, proxmoxProgressBarsConfig) as {
+      type: string;
+      bars: Array<{ label: string; value: number; max: number }>;
+    };
+
+    expect(result.type).toBe("progressBars");
+    expect(result.bars).toHaveLength(2);
+    expect(result.bars[0]?.value).toBe(12_884_901_888);
+    expect(result.bars[0]?.max).toBe(34_359_738_368);
+    expect(result.bars[1]?.label).toBe("Disk");
+  });
+
+  it("disk table extracts filesystem rows", () => {
+    const result = extract("table", diskUsageResponse, diskTableConfig) as {
+      type: string;
+      columns: string[];
+      rows: unknown[][];
+    };
+
+    expect(result.type).toBe("table");
+    expect(result.columns).toEqual(["Mount", "Size", "Used"]);
+    expect(result.rows).toHaveLength(3);
+    expect(result.rows[0]?.[0]).toBe("/");
+    expect(result.rows[2]?.[2]).toBe("95%");
+  });
+
+  it("pihole statusIndicator detects enabled state", () => {
+    const result = extract("statusIndicator", piholeResponse, piholeStatusIndicatorConfig) as {
+      type: string;
+      items: Array<{ label: string; value: string; isGood: boolean }>;
+    };
+
+    expect(result.type).toBe("statusIndicator");
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]?.isGood).toBe(true);
+    expect(result.items[0]?.value).toBe("enabled");
+  });
+
+  it("pihole countGrid extracts all 4 stats", () => {
+    const result = extract("countGrid", piholeResponse, piholeCountGridConfig) as {
+      type: string;
+      items: Array<{ label: string; value: unknown; unit: string }>;
+    };
+
+    expect(result.type).toBe("countGrid");
+    expect(result.items).toHaveLength(4);
+    expect(result.items[0]?.value).toBe(12_847);
+    expect(result.items[1]?.value).toBe(48_291);
+    expect(result.items[2]?.value).toBe(26.6);
+    expect(result.items[2]?.unit).toBe("%");
+    expect(result.items[3]?.value).toBe(14);
+  });
+
+  it("radarr statGrid with outline card style", () => {
+    const result = extract("statGrid", radarrResponse, radarrStatGridConfig) as {
+      type: string;
+      items: Array<{ label: string; value: unknown }>;
+      cardStyle: string;
+    };
+
+    expect(result.type).toBe("statGrid");
+    expect(result.cardStyle).toBe("outline");
+    expect(result.items[0]?.value).toBe(15);
+    expect(result.items[1]?.value).toBe(3);
+  });
+
+  it("raw extractor returns raw data at path", () => {
+    const result = extract("raw", piholeResponse, { type: "raw", jsonPath: "$.status", maxHeight: 200 }) as {
+      type: string;
+      data: unknown;
+      maxHeight: number;
+    };
+
+    expect(result.type).toBe("raw");
+    expect(result.data).toBe("enabled");
+    expect(result.maxHeight).toBe(200);
+  });
+
+  it("customJsx passes full JSON and template through", () => {
+    const json = { title: "Status", items: [{ name: "CPU", value: 42 }] };
+    const config = {
+      type: "customJsx" as const,
+      template: "<Stack><Title>{data.title}</Title></Stack>",
+    };
+
+    const result = extract("customJsx", json, config) as {
+      type: string;
+      template: string;
+      data: typeof json;
+    };
+
+    expect(result.type).toBe("customJsx");
+    expect(result.template).toBe(config.template);
+    expect(result.data).toEqual(json);
+  });
+
+  it("jellyfin countGrid extracts movies/series/episodes/songs in 4-column grid", () => {
+    const result = extract("countGrid", jellyfinItemCountsResponse, jellyfinCountGridConfig) as {
+      type: string;
+      items: Array<{ label: string; value: unknown; unit: string }>;
+      columns: number;
+      valueSize: string;
+    };
+
+    expect(result.type).toBe("countGrid");
+    expect(result.columns).toBe(4);
+    expect(result.valueSize).toBe("lg");
+    expect(result.items).toHaveLength(4);
+    expect(result.items[0]).toEqual({ label: "Movies", value: 185, unit: "" });
+    expect(result.items[1]).toEqual({ label: "Series", value: 38, unit: "" });
+    expect(result.items[2]).toEqual({ label: "Episodes", value: 770, unit: "" });
+    expect(result.items[3]).toEqual({ label: "Songs", value: 0, unit: "" });
+  });
+});

packages/api/src/router/widgets/__tests__/custom-api-fixtures.ts

@@ -0,0 +1,142 @@
+export const sonarrResponse = {
+  wanted: { totalRecords: 42 },
+  queue: { totalRecords: 5 },
+  series: [
+    { title: "Breaking Bad", seasons: 5, episodeCount: 62, episodeFileCount: 60 },
+    { title: "The Wire", seasons: 5, episodeCount: 60, episodeFileCount: 55 },
+  ],
+  diskspace: [
+    { path: "/tv", label: "TV Shows", freeSpace: 150_000_000_000, totalSpace: 500_000_000_000 },
+    { path: "/movies", label: "Movies", freeSpace: 80_000_000_000, totalSpace: 250_000_000_000 },
+  ],
+};
+
+export const sonarrStatGridConfig = {
+  type: "statGrid" as const,
+  items: [
+    { label: "Missing", jsonPath: "$.wanted.totalRecords", unit: "", color: "red" },
+    { label: "Queue", jsonPath: "$.queue.totalRecords", unit: "", color: "blue" },
+  ],
+  columns: 2,
+  cardStyle: "filled" as const,
+};
+
+export const proxmoxResponse = {
+  data: {
+    cpu: 0.23,
+    memory: { used: 12_884_901_888, total: 34_359_738_368 },
+    rootfs: { used: 42_949_672_960, total: 107_374_182_400 },
+    uptime: 864_000,
+    status: "running",
+    maxcpu: 8,
+    maxmem: 34_359_738_368,
+    name: "proxmox-node1",
+  },
+};
+
+export const proxmoxProgressBarsConfig = {
+  type: "progressBars" as const,
+  bars: [
+    { label: "Memory", valuePath: "$.data.memory.used", maxPath: "$.data.memory.total", unit: "B", color: "blue" },
+    { label: "Disk", valuePath: "$.data.rootfs.used", maxPath: "$.data.rootfs.total", unit: "B", color: "orange" },
+  ],
+  showPercentage: true,
+  barSize: "md" as const,
+};
+
+export const diskUsageResponse = {
+  filesystems: [
+    { filesystem: "/dev/sda1", size: "500G", used: "350G", avail: "150G", usePct: "70%", mountedOn: "/" },
+    { filesystem: "/dev/sdb1", size: "2T", used: "1.2T", avail: "800G", usePct: "60%", mountedOn: "/data" },
+    { filesystem: "/dev/sdc1", size: "4T", used: "3.8T", avail: "200G", usePct: "95%", mountedOn: "/media" },
+  ],
+};
+
+export const diskTableConfig = {
+  type: "table" as const,
+  tablePath: "$.filesystems",
+  columns: [
+    { header: "Mount", jsonPath: "$.mountedOn" },
+    { header: "Size", jsonPath: "$.size" },
+    { header: "Used", jsonPath: "$.usePct" },
+  ],
+  striped: true,
+  compact: false,
+};
+
+export const piholeResponse = {
+  domains_being_blocked: 125_432,
+  dns_queries_today: 48_291,
+  ads_blocked_today: 12_847,
+  ads_percentage_today: 26.6,
+  unique_clients: 14,
+  status: "enabled",
+  gravity_last_updated: { relative: { days: 2, hours: 3 } },
+};
+
+export const piholeStatusIndicatorConfig = {
+  type: "statusIndicator" as const,
+  items: [{ label: "Pi-Hole", jsonPath: "$.status", goodValues: ["enabled"] }],
+  layout: "list" as const,
+  dotSize: "md" as const,
+};
+
+export const piholeCountGridConfig = {
+  type: "countGrid" as const,
+  items: [
+    { label: "Blocked Today", jsonPath: "$.ads_blocked_today", unit: "" },
+    { label: "DNS Queries", jsonPath: "$.dns_queries_today", unit: "" },
+    { label: "Block Rate", jsonPath: "$.ads_percentage_today", unit: "%" },
+    { label: "Clients", jsonPath: "$.unique_clients", unit: "" },
+  ],
+  columns: 2,
+  valueSize: "md" as const,
+};
+
+export const radarrResponse = {
+  wanted: { totalRecords: 15 },
+  queue: { totalRecords: 3 },
+  movie: [
+    { title: "Inception", hasFile: true, monitored: true, runtime: 148, year: 2010 },
+    { title: "Interstellar", hasFile: false, monitored: true, runtime: 169, year: 2014 },
+    { title: "The Dark Knight", hasFile: true, monitored: false, runtime: 152, year: 2008 },
+  ],
+  rootfolder: [{ path: "/movies", freeSpace: 200_000_000_000, totalSpace: 1_000_000_000_000 }],
+};
+
+export const radarrStatGridConfig = {
+  type: "statGrid" as const,
+  items: [
+    { label: "Missing", jsonPath: "$.wanted.totalRecords", unit: "", color: "red" },
+    { label: "Queue", jsonPath: "$.queue.totalRecords", unit: "", color: "teal" },
+  ],
+  columns: 2,
+  cardStyle: "outline" as const,
+};
+
+export const jellyfinItemCountsResponse = {
+  MovieCount: 185,
+  SeriesCount: 38,
+  EpisodeCount: 770,
+  ArtistCount: 0,
+  ProgramCount: 0,
+  TrailerCount: 0,
+  SongCount: 0,
+  AlbumCount: 0,
+  MusicVideoCount: 0,
+  BoxSetCount: 12,
+  BookCount: 0,
+  ItemCount: 0,
+};
+
+export const jellyfinCountGridConfig = {
+  type: "countGrid" as const,
+  items: [
+    { label: "Movies", jsonPath: "$.MovieCount", unit: "" },
+    { label: "Series", jsonPath: "$.SeriesCount", unit: "" },
+    { label: "Episodes", jsonPath: "$.EpisodeCount", unit: "" },
+    { label: "Songs", jsonPath: "$.SongCount", unit: "" },
+  ],
+  columns: 4,
+  valueSize: "lg" as const,
+};

packages/api/src/router/widgets/custom-api.ts

@@ -0,0 +1,91 @@
+import { TRPCError } from "@trpc/server";
+import superjson from "superjson";
+import { z } from "zod/v4";
+
+import { decryptSecret } from "@homarr/common/server";
+import { customWidgetDefinitions } from "@homarr/db/schema";
+import { eq } from "@homarr/db";
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { createTRPCRouter, protectedProcedure } from "../../trpc";
+import { applyAuth } from "../custom-widget/auth";
+import { extractActionButtonDisplay, extractDisplayDataWithFallback } from "../custom-widget/display-data";
+
+const logger = createLogger({ module: "widget:customApi" });
+
+const FETCH_TIMEOUT_MS = 10_000;
+
+const validateUrl = (urlString: string): URL => new URL(urlString);
+
+export const customApiRouter = createTRPCRouter({
+  getData: protectedProcedure.input(z.object({ definitionId: z.string() })).query(async ({ ctx, input }) => {
+    const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
+      where: eq(customWidgetDefinitions.id, input.definitionId),
+      with: { secrets: true },
+    });
+
+    if (!definition) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Custom widget definition not found" });
+    }
+
+    if (!definition.enabled) {
+      return { type: "disabled" };
+    }
+
+    let displayConfig: Record<string, unknown>;
+    try {
+      displayConfig = superjson.parse(definition.displayConfig) as Record<string, unknown>;
+    } catch {
+      throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "Widget has corrupt display configuration" });
+    }
+
+    if (definition.displayType === "actionButton") {
+      return extractActionButtonDisplay(displayConfig);
+    }
+
+    const decryptedSecrets = definition.secrets.map((s) => ({
+      kind: s.kind,
+      value: decryptSecret(s.value),
+    }));
+
+    const url = validateUrl(definition.url);
+    const headers = new Headers({ Accept: "application/json" });
+
+    if (definition.method !== "GET" && definition.requestBody) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    applyAuth(headers, url, definition.authType, decryptedSecrets, definition.headerName);
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: definition.method,
+        headers,
+        body: definition.method !== "GET" ? definition.requestBody : undefined,
+        redirect: "follow",
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: `API returned ${response.status}: ${response.statusText}`,
+        });
+      }
+
+      const json: unknown = await response.json();
+      return extractDisplayDataWithFallback(json, definition.displayType, displayConfig);
+    } catch (error) {
+      if (error instanceof TRPCError) throw error;
+      logger.error("Failed to fetch custom API data", { definitionId: input.definitionId, error });
+      throw new TRPCError({
+        code: "INTERNAL_SERVER_ERROR",
+        message: error instanceof Error ? error.message : "Failed to fetch data from external API",
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }),
+});

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

@@ -36,4 +36,5 @@ export const widgetRouter = createTRPCRouter({
   audioStats: lazy(() => import("./audio-stats").then((mod) => mod.audioStatsRouter)),
   umami: lazy(() => import("./umami").then((mod) => mod.umamiRouter)),
   ups: lazy(() => import("./ups").then((mod) => mod.upsRouter)),
+  customApi: lazy(() => import("./custom-api").then((mod) => mod.customApiRouter)),
 });