feat: Tracearr integration

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

@@ -26,4 +26,5 @@ export const widgetRouter = createTRPCRouter({
   networkController: lazy(() => import("./network-controller").then((mod) => mod.networkControllerRouter)),
   firewall: lazy(() => import("./firewall").then((mod) => mod.firewallRouter)),
   notifications: lazy(() => import("./notifications").then((mod) => mod.notificationsRouter)),
+  tracearr: lazy(() => import("./tracearr").then((mod) => mod.tracearrRouter)),
 });

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

@@ -0,0 +1,48 @@
+import { observable } from "@trpc/server/observable";
+
+import type { TracearrDashboardData } from "@homarr/integrations/types";
+import { tracearrRequestHandler } from "@homarr/request-handler/tracearr";
+
+import { createManyIntegrationMiddleware } from "../../middlewares/integration";
+import { createTRPCRouter, publicProcedure } from "../../trpc";
+
+export const tracearrRouter = createTRPCRouter({
+  getDashboard: publicProcedure.concat(createManyIntegrationMiddleware("query", "tracearr")).query(async ({ ctx }) => {
+    const results = await Promise.all(
+      ctx.integrations.map(async (integration) => {
+        const innerHandler = tracearrRequestHandler.handler(integration, {});
+        const { data, timestamp } = await innerHandler.getCachedOrUpdatedDataAsync({ forceUpdate: false });
+
+        return {
+          integrationId: integration.id,
+          integrationName: integration.name,
+          integrationUrl: integration.url,
+          dashboard: data,
+          updatedAt: timestamp,
+        };
+      }),
+    );
+
+    return results;
+  }),
+  subscribeToDashboard: publicProcedure
+    .concat(createManyIntegrationMiddleware("query", "tracearr"))
+    .subscription(({ ctx }) => {
+      return observable<{ integrationId: string; dashboard: TracearrDashboardData; timestamp: Date }>((emit) => {
+        const unsubscribes = ctx.integrations.map((integration) => {
+          const innerHandler = tracearrRequestHandler.handler(integration, {});
+          return innerHandler.subscribe((dashboard) => {
+            emit.next({
+              integrationId: integration.id,
+              dashboard,
+              timestamp: new Date(),
+            });
+          });
+        });
+
+        return () => {
+          unsubscribes.forEach((unsubscribe) => unsubscribe());
+        };
+      });
+    }),
+});

packages/common/src/date.ts

@@ -6,6 +6,17 @@ dayjs.extend(isBetween);
 
 const validUnits = ["h", "d", "w", "M", "y"] as UnitTypeShort[];
 
+export function formatDuration(milliseconds: number) {
+  const totalSeconds = Math.floor(milliseconds / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  }
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
 export const isDateWithin = (date: Date, relativeDate: string): boolean => {
   if (relativeDate.length < 2) {
     throw new Error("Relative date must be at least 2 characters long");

packages/cron-jobs/src/index.ts

@@ -18,6 +18,7 @@ import { mediaServerJob } from "./jobs/integrations/media-server";
 import { mediaTranscodingJob } from "./jobs/integrations/media-transcoding";
 import { networkControllerJob } from "./jobs/integrations/network-controller";
 import { refreshNotificationsJob } from "./jobs/integrations/notifications";
+import { tracearrJob } from "./jobs/integrations/tracearr";
 import { minecraftServerStatusJob } from "./jobs/minecraft-server-status";
 import { pingJob } from "./jobs/ping";
 import { rssFeedsJob } from "./jobs/rss-feeds";
@@ -50,6 +51,7 @@ export const jobGroup = createCronJobGroup({
   firewallInterfaces: firewallInterfacesJob,
   refreshNotifications: refreshNotificationsJob,
   weather: weatherJob,
+  tracearr: tracearrJob,
 });
 
 export type JobGroupKeys = ReturnType<(typeof jobGroup)["getKeys"]>[number];

packages/cron-jobs/src/jobs/integrations/tracearr.ts

@@ -0,0 +1,14 @@
+import { EVERY_5_SECONDS } from "@homarr/cron-jobs-core/expressions";
+import { createRequestIntegrationJobHandler } from "@homarr/request-handler/lib/cached-request-integration-job-handler";
+import { tracearrRequestHandler } from "@homarr/request-handler/tracearr";
+
+import { createCronJob } from "../../lib";
+
+export const tracearrJob = createCronJob("tracearr", EVERY_5_SECONDS).withCallback(
+  createRequestIntegrationJobHandler(tracearrRequestHandler.handler, {
+    widgetKinds: ["tracearr"],
+    getInput: {
+      tracearr: () => ({}),
+    },
+  }),
+);

packages/definitions/src/integration.ts

@@ -342,6 +342,14 @@ export const integrationDefs = {
     // @ts-expect-error TS2345
     documentationUrl: createDocumentationLink("/docs/integrations/immich"),
   },
+  tracearr: {
+    name: "Tracearr",
+    secretKinds: [["apiKey"]],
+    iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/tracearr.svg",
+    category: ["mediaMonitoring"],
+    // @ts-expect-error - docs page will be created when integration is merged
+    documentationUrl: createDocumentationLink("/docs/integrations/tracearr"),
+  },
   // This integration only returns mock data, it is used during development (but can also be used in production by directly going to the create page)
   mock: {
     name: "Mock",
@@ -429,6 +437,7 @@ export const integrationCategories = [
   "notifications",
   "firewall",
   "photoService",
+  "mediaMonitoring",
 ] as const;
 
 export type IntegrationCategory = (typeof integrationCategories)[number];

packages/definitions/src/widget.ts

@@ -33,5 +33,6 @@ export const widgetKinds = [
   "systemDisks",
   "immich-serverStats",
   "immich-albumCarousel",
+  "tracearr",
 ] as const;
 export type WidgetKind = (typeof widgetKinds)[number];

packages/integrations/src/base/creator.ts

@@ -41,6 +41,7 @@ import { ProwlarrIntegration } from "../prowlarr/prowlarr-integration";
 import { ProxmoxIntegration } from "../proxmox/proxmox-integration";
 import { QuayIntegration } from "../quay/quay-integration";
 import { SeerrIntegration } from "../seerr/seerr-integration";
+import { TracearrIntegration } from "../tracearr/tracearr-integration";
 import { TrueNasIntegration } from "../truenas/truenas-integration";
 import { UnifiControllerIntegration } from "../unifi-controller/unifi-controller-integration";
 import { UnraidIntegration } from "../unraid/unraid-integration";
@@ -111,6 +112,7 @@ export const integrationCreators = {
   truenas: TrueNasIntegration,
   unraid: UnraidIntegration,
   coolify: CoolifyIntegration,
+  tracearr: TracearrIntegration,
   glances: GlancesIntegration,
   immich: ImmichIntegration,
 } satisfies Record<IntegrationKind, IntegrationInstance | [(input: IntegrationInput) => Promise<Integration>]>;

packages/integrations/src/base/integration.ts

@@ -58,24 +58,30 @@ export abstract class Integration {
   private createUrl(
     inputUrl: string,
     path: `/${string}`,
-    queryParams?: Record<string, string | Date | number | boolean>,
+    queryParams?: Record<string, string | Date | number | boolean | null | undefined>,
   ) {
     const baseUrl = removeTrailingSlash(inputUrl);
     const url = new URL(`${baseUrl}${path}`);
 
     if (queryParams) {
       for (const [key, value] of Object.entries(queryParams)) {
+        if (value === null || value === undefined) {
+          continue;
+        }
         url.searchParams.set(key, value instanceof Date ? value.toISOString() : value.toString());
       }
     }
 
     return url;
   }
-  protected url(path: `/${string}`, queryParams?: Record<string, string | Date | number | boolean>) {
+  protected url(path: `/${string}`, queryParams?: Record<string, string | Date | number | boolean | null | undefined>) {
     return this.createUrl(this.integration.url, path, queryParams);
   }
 
-  protected externalUrl(path: `/${string}`, queryParams?: Record<string, string | Date | number | boolean>) {
+  protected externalUrl(
+    path: `/${string}`,
+    queryParams?: Record<string, string | Date | number | boolean | null | undefined>,
+  ) {
     return this.createUrl(this.integration.externalUrl ?? this.integration.url, path, queryParams);
   }
 

packages/integrations/src/index.ts

@@ -30,6 +30,7 @@ export { OPNsenseIntegration } from "./opnsense/opnsense-integration";
 export { ICalIntegration } from "./ical/ical-integration";
 export { CoolifyIntegration } from "./coolify/coolify-integration";
 export { ImmichIntegration } from "./immich/immich-integration";
+export { TracearrIntegration } from "./tracearr/tracearr-integration";
 
 // Types
 export type { IntegrationInput } from "./base/integration";
@@ -56,6 +57,7 @@ export type {
 export type { ReleasesRepository, ReleaseResponse } from "./interfaces/releases-providers/releases-providers-types";
 export type { Notification } from "./interfaces/notifications/notification-types";
 export type { ImmichServerStats, ImmichAlbum, ImmichAsset } from "./immich/immich-integration";
+export type { TracearrDashboardData } from "./tracearr/tracearr-types";
 
 // Schemas
 export { downloadClientItemSchema } from "./interfaces/downloads/download-client-items";