feat(releases-widget): define providers as integrations (#3253)

Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>

packages/integrations/src/base/creator.ts

@@ -4,7 +4,9 @@ import type { Integration as DbIntegration } from "@homarr/db/schema";
 import type { IntegrationKind, IntegrationSecretKind } from "@homarr/definitions";
 
 import { AdGuardHomeIntegration } from "../adguard-home/adguard-home-integration";
+import { CodebergIntegration } from "../codeberg/codeberg-integration";
 import { DashDotIntegration } from "../dashdot/dashdot-integration";
+import { DockerHubIntegration } from "../docker-hub/docker-hub-integration";
 import { Aria2Integration } from "../download-client/aria2/aria2-integration";
 import { DelugeIntegration } from "../download-client/deluge/deluge-integration";
 import { NzbGetIntegration } from "../download-client/nzbget/nzbget-integration";
@@ -12,6 +14,8 @@ import { QBitTorrentIntegration } from "../download-client/qbittorrent/qbittorre
 import { SabnzbdIntegration } from "../download-client/sabnzbd/sabnzbd-integration";
 import { TransmissionIntegration } from "../download-client/transmission/transmission-integration";
 import { EmbyIntegration } from "../emby/emby-integration";
+import { GithubIntegration } from "../github/github-integration";
+import { GitlabIntegration } from "../gitlab/gitlab-integration";
 import { HomeAssistantIntegration } from "../homeassistant/homeassistant-integration";
 import { JellyfinIntegration } from "../jellyfin/jellyfin-integration";
 import { JellyseerrIntegration } from "../jellyseerr/jellyseerr-integration";
@@ -22,6 +26,7 @@ import { SonarrIntegration } from "../media-organizer/sonarr/sonarr-integration"
 import { TdarrIntegration } from "../media-transcoding/tdarr-integration";
 import { MockIntegration } from "../mock/mock-integration";
 import { NextcloudIntegration } from "../nextcloud/nextcloud.integration";
+import { NPMIntegration } from "../npm/npm-integration";
 import { NTFYIntegration } from "../ntfy/ntfy-integration";
 import { OpenMediaVaultIntegration } from "../openmediavault/openmediavault-integration";
 import { OverseerrIntegration } from "../overseerr/overseerr-integration";
@@ -94,6 +99,11 @@ export const integrationCreators = {
   emby: EmbyIntegration,
   nextcloud: NextcloudIntegration,
   unifiController: UnifiControllerIntegration,
+  github: GithubIntegration,
+  dockerHub: DockerHubIntegration,
+  gitlab: GitlabIntegration,
+  npm: NPMIntegration,
+  codeberg: CodebergIntegration,
   ntfy: NTFYIntegration,
   mock: MockIntegration,
 } satisfies Record<IntegrationKind, IntegrationInstance | [(input: IntegrationInput) => Promise<Integration>]>;

packages/integrations/src/codeberg/codeberg-integration.ts

@@ -0,0 +1,143 @@
+import type { RequestInit, Response } from "undici";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+import { logger } from "@homarr/log";
+
+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 { ReleasesProviderIntegration } from "../interfaces/releases-providers/releases-providers-integration";
+import { getLatestRelease } from "../interfaces/releases-providers/releases-providers-integration";
+import type {
+  DetailsProviderResponse,
+  ReleasesRepository,
+  ReleasesResponse,
+} from "../interfaces/releases-providers/releases-providers-types";
+import { detailsResponseSchema, releasesResponseSchema } from "./codeberg-schemas";
+
+const localLogger = logger.child({ module: "CodebergIntegration" });
+
+export class CodebergIntegration extends Integration implements ReleasesProviderIntegration {
+  private async withHeadersAsync(callback: (headers: RequestInit["headers"]) => Promise<Response>): Promise<Response> {
+    if (!this.hasSecretValue("personalAccessToken")) return await callback({});
+
+    return await callback({
+      Authorization: `token ${this.getSecretValue("personalAccessToken")}`,
+    });
+  }
+
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const response = await this.withHeadersAsync(async (headers) => {
+      return await input.fetchAsync(this.url("/version"), {
+        headers,
+      });
+    });
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult(response);
+    }
+
+    return {
+      success: true,
+    };
+  }
+
+  public async getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse> {
+    const [owner, name] = repository.identifier.split("/");
+    if (!owner || !name) {
+      localLogger.warn(
+        `Invalid identifier format. Expected 'owner/name', for ${repository.identifier} with Codeberg integration`,
+        {
+          identifier: repository.identifier,
+        },
+      );
+      return {
+        id: repository.id,
+        error: { code: "invalidIdentifier" },
+      };
+    }
+
+    const details = await this.getDetailsAsync(owner, name);
+
+    const releasesResponse = await this.withHeadersAsync(async (headers) => {
+      return fetchWithTrustedCertificatesAsync(
+        this.url(`/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/releases`),
+        { headers },
+      );
+    });
+
+    if (!releasesResponse.ok) {
+      return {
+        id: repository.id,
+        error: { message: releasesResponse.statusText },
+      };
+    }
+
+    const releasesResponseJson: unknown = await releasesResponse.json();
+    const { data, success, error } = releasesResponseSchema.safeParse(releasesResponseJson);
+
+    if (!success) {
+      return {
+        id: repository.id,
+        error: {
+          message: releasesResponseJson ? JSON.stringify(releasesResponseJson, null, 2) : error.message,
+        },
+      };
+    } else {
+      const formattedReleases = data.map((tag) => ({
+        latestRelease: tag.tag_name,
+        latestReleaseAt: tag.published_at,
+        releaseUrl: tag.url,
+        releaseDescription: tag.body,
+        isPreRelease: tag.prerelease,
+      }));
+      return getLatestRelease(formattedReleases, repository, details);
+    }
+  }
+
+  protected async getDetailsAsync(owner: string, name: string): Promise<DetailsProviderResponse | undefined> {
+    const response = await this.withHeadersAsync(async (headers) => {
+      return await fetchWithTrustedCertificatesAsync(
+        this.url(`/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`),
+        {
+          headers,
+        },
+      );
+    });
+
+    if (!response.ok) {
+      localLogger.warn(`Failed to get details response for ${owner}/${name} with Codeberg integration`, {
+        owner,
+        name,
+        error: response.statusText,
+      });
+
+      return undefined;
+    }
+
+    const responseJson = await response.json();
+    const { data, success, error } = detailsResponseSchema.safeParse(responseJson);
+
+    if (!success) {
+      localLogger.warn(`Failed to parse details response for ${owner}/${name} with Codeberg integration`, {
+        owner,
+        name,
+        error,
+      });
+
+      return undefined;
+    }
+
+    return {
+      projectUrl: data.html_url,
+      projectDescription: data.description,
+      isFork: data.fork,
+      isArchived: data.archived,
+      createdAt: data.created_at,
+      starsCount: data.stars_count,
+      openIssues: data.open_issues_count,
+      forksCount: data.forks_count,
+    };
+  }
+}

packages/integrations/src/codeberg/codeberg-schemas.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const releasesResponseSchema = z.array(
+  z.object({
+    tag_name: z.string(),
+    published_at: z.string().transform((value) => new Date(value)),
+    url: z.string(),
+    body: z.string(),
+    prerelease: z.boolean(),
+  }),
+);
+
+export const detailsResponseSchema = z.object({
+  html_url: z.string(),
+  description: z.string(),
+  fork: z.boolean(),
+  archived: z.boolean(),
+  created_at: z.string().transform((value) => new Date(value)),
+  stars_count: z.number(),
+  open_issues_count: z.number(),
+  forks_count: z.number(),
+});

packages/integrations/src/docker-hub/docker-hub-integration.ts

@@ -0,0 +1,190 @@
+import type { fetch, RequestInit, Response } from "undici";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+import { ResponseError } from "@homarr/common/server";
+import { logger } from "@homarr/log";
+
+import type { IntegrationInput, IntegrationTestingInput } from "../base/integration";
+import { Integration } from "../base/integration";
+import type { SessionStore } from "../base/session-store";
+import { createSessionStore } from "../base/session-store";
+import { TestConnectionError } from "../base/test-connection/test-connection-error";
+import type { TestingResult } from "../base/test-connection/test-connection-service";
+import type { ReleasesProviderIntegration } from "../interfaces/releases-providers/releases-providers-integration";
+import { getLatestRelease } from "../interfaces/releases-providers/releases-providers-integration";
+import type {
+  DetailsProviderResponse,
+  ReleasesRepository,
+  ReleasesResponse,
+} from "../interfaces/releases-providers/releases-providers-types";
+import { accessTokenResponseSchema, detailsResponseSchema, releasesResponseSchema } from "./docker-hub-schemas";
+
+const localLogger = logger.child({ module: "DockerHubIntegration" });
+
+export class DockerHubIntegration extends Integration implements ReleasesProviderIntegration {
+  private readonly sessionStore: SessionStore<string>;
+
+  constructor(integration: IntegrationInput) {
+    super(integration);
+    this.sessionStore = createSessionStore(integration);
+  }
+
+  private async withHeadersAsync(callback: (headers: RequestInit["headers"]) => Promise<Response>): Promise<Response> {
+    if (!this.hasSecretValue("username") || !this.hasSecretValue("personalAccessToken")) return await callback({});
+
+    const storedSession = await this.sessionStore.getAsync();
+
+    if (storedSession) {
+      localLogger.debug("Using stored session for request", { integrationId: this.integration.id });
+      const response = await callback({
+        Authorization: `Bearer ${storedSession}`,
+      });
+      if (response.status !== 401) {
+        return response;
+      }
+
+      localLogger.debug("Session expired, getting new session", { integrationId: this.integration.id });
+    }
+
+    const accessToken = await this.getSessionAsync();
+    await this.sessionStore.setAsync(accessToken);
+    return await callback({
+      Authorization: `Bearer ${accessToken}`,
+    });
+  }
+
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const hasAuth = this.hasSecretValue("username") && this.hasSecretValue("personalAccessToken");
+
+    if (hasAuth) {
+      localLogger.debug("Testing DockerHub connection with authentication", { integrationId: this.integration.id });
+      await this.getSessionAsync(input.fetchAsync);
+    } else {
+      localLogger.debug("Testing DockerHub connection without authentication", { integrationId: this.integration.id });
+      const response = await input.fetchAsync(this.url("/v2/repositories/library"));
+      if (!response.ok) {
+        return TestConnectionError.StatusResult(response);
+      }
+    }
+
+    return {
+      success: true,
+    };
+  }
+
+  public async getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse> {
+    const relativeUrl = this.getRelativeUrl(repository.identifier);
+    if (relativeUrl === "/") {
+      localLogger.warn(
+        `Invalid identifier format. Expected 'owner/name' or 'name', for ${repository.identifier} on DockerHub`,
+        {
+          identifier: repository.identifier,
+        },
+      );
+      return {
+        id: repository.id,
+        error: { code: "invalidIdentifier" },
+      };
+    }
+
+    const details = await this.getDetailsAsync(relativeUrl);
+
+    const releasesResponse = await this.withHeadersAsync(async (headers) => {
+      return await fetchWithTrustedCertificatesAsync(this.url(`${relativeUrl}/tags?page_size=100`), {
+        headers,
+      });
+    });
+
+    if (!releasesResponse.ok) {
+      return {
+        id: repository.id,
+        error: { message: releasesResponse.statusText },
+      };
+    }
+
+    const releasesResponseJson: unknown = await releasesResponse.json();
+    const releasesResult = releasesResponseSchema.safeParse(releasesResponseJson);
+
+    if (!releasesResult.success) {
+      return {
+        id: repository.id,
+        error: {
+          message: releasesResponseJson ? JSON.stringify(releasesResponseJson, null, 2) : releasesResult.error.message,
+        },
+      };
+    } else {
+      return getLatestRelease(releasesResult.data.results, repository, details);
+    }
+  }
+
+  private async getDetailsAsync(relativeUrl: `/${string}`): Promise<DetailsProviderResponse | undefined> {
+    const response = await this.withHeadersAsync(async (headers) => {
+      return await fetchWithTrustedCertificatesAsync(this.url(`${relativeUrl}/`), {
+        headers,
+      });
+    });
+
+    if (!response.ok) {
+      localLogger.warn(`Failed to get details response for ${relativeUrl} with DockerHub integration`, {
+        relativeUrl,
+        error: response.statusText,
+      });
+
+      return undefined;
+    }
+
+    const responseJson = await response.json();
+    const { data, success, error } = detailsResponseSchema.safeParse(responseJson);
+
+    if (!success) {
+      localLogger.warn(`Failed to parse details response for ${relativeUrl} with DockerHub integration`, {
+        relativeUrl,
+        error,
+      });
+
+      return undefined;
+    }
+
+    return {
+      projectUrl: `https://hub.docker.com/r/${data.namespace === "library" ? "_" : data.namespace}/${data.name}`,
+      projectDescription: data.description,
+      createdAt: data.date_registered,
+      starsCount: data.star_count,
+    };
+  }
+
+  private getRelativeUrl(identifier: string): `/${string}` {
+    if (identifier.indexOf("/") > 0) {
+      const [owner, name] = identifier.split("/");
+      if (!owner || !name) {
+        return "/";
+      }
+      return `/v2/namespaces/${encodeURIComponent(owner)}/repositories/${encodeURIComponent(name)}`;
+    } else {
+      return `/v2/repositories/library/${encodeURIComponent(identifier)}`;
+    }
+  }
+
+  private async getSessionAsync(fetchAsync: typeof fetch = fetchWithTrustedCertificatesAsync): Promise<string> {
+    const response = await fetchAsync(this.url("/v2/auth/token"), {
+      method: "POST",
+      body: JSON.stringify({
+        identifier: this.getSecretValue("username"),
+        secret: this.getSecretValue("personalAccessToken"),
+      }),
+    });
+
+    if (!response.ok) throw new ResponseError(response);
+
+    const data = await response.json();
+    const result = await accessTokenResponseSchema.parseAsync(data);
+
+    if (!result.access_token) {
+      throw new ResponseError({ status: 401, url: response.url });
+    }
+
+    localLogger.info("Received session successfully", { integrationId: this.integration.id });
+
+    return result.access_token;
+  }
+}

packages/integrations/src/docker-hub/docker-hub-schemas.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const accessTokenResponseSchema = z.object({
+  access_token: z.string(),
+});
+
+export const releasesResponseSchema = z.object({
+  results: z.array(
+    z.object({ name: z.string(), last_updated: z.string().transform((value) => new Date(value)) }).transform((tag) => ({
+      latestRelease: tag.name,
+      latestReleaseAt: tag.last_updated,
+    })),
+  ),
+});
+
+export const detailsResponseSchema = z.object({
+  name: z.string(),
+  namespace: z.string(),
+  description: z.string(),
+  star_count: z.number(),
+  date_registered: z.string().transform((value) => new Date(value)),
+});

packages/integrations/src/github/github-integration.ts

@@ -0,0 +1,152 @@
+import { Octokit, RequestError } from "octokit";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+import { logger } from "@homarr/log";
+
+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 { ReleasesProviderIntegration } from "../interfaces/releases-providers/releases-providers-integration";
+import { getLatestRelease } from "../interfaces/releases-providers/releases-providers-integration";
+import type {
+  DetailsProviderResponse,
+  ReleaseProviderResponse,
+  ReleasesRepository,
+  ReleasesResponse,
+} from "../interfaces/releases-providers/releases-providers-types";
+
+const localLogger = logger.child({ module: "GithubIntegration" });
+
+export class GithubIntegration extends Integration implements ReleasesProviderIntegration {
+  private static readonly userAgent = "Homarr-Lab/Homarr:GithubIntegration";
+
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const headers: RequestInit["headers"] = {
+      "User-Agent": GithubIntegration.userAgent,
+    };
+
+    if (this.hasSecretValue("personalAccessToken"))
+      headers.Authorization = `Bearer ${this.getSecretValue("personalAccessToken")}`;
+
+    const response = await input.fetchAsync(this.url("/octocat"), {
+      headers,
+    });
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult(response);
+    }
+
+    return {
+      success: true,
+    };
+  }
+
+  public async getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse> {
+    const [owner, name] = repository.identifier.split("/");
+    if (!owner || !name) {
+      localLogger.warn(
+        `Invalid identifier format. Expected 'owner/name', for ${repository.identifier} with Github integration`,
+        {
+          identifier: repository.identifier,
+        },
+      );
+      return {
+        id: repository.id,
+        error: { code: "invalidIdentifier" },
+      };
+    }
+
+    const api = this.getApi();
+
+    const details = await this.getDetailsAsync(api, owner, name);
+
+    try {
+      const releasesResponse = await api.rest.repos.listReleases({
+        owner,
+        repo: name,
+      });
+
+      if (releasesResponse.data.length === 0) {
+        localLogger.warn(`No releases found, for ${repository.identifier} with Github integration`, {
+          identifier: repository.identifier,
+        });
+        return {
+          id: repository.id,
+          error: { code: "noReleasesFound" },
+        };
+      }
+
+      const releasesProviderResponse = releasesResponse.data.reduce<ReleaseProviderResponse[]>((acc, release) => {
+        if (!release.published_at) return acc;
+
+        acc.push({
+          latestRelease: release.tag_name,
+          latestReleaseAt: new Date(release.published_at),
+          releaseUrl: release.html_url,
+          releaseDescription: release.body ?? undefined,
+          isPreRelease: release.prerelease,
+        });
+        return acc;
+      }, []);
+
+      return getLatestRelease(releasesProviderResponse, repository, details);
+    } catch (error) {
+      const errorMessage = error instanceof RequestError ? error.message : String(error);
+
+      localLogger.warn(`Failed to get releases for ${owner}\\${name} with Github integration`, {
+        owner,
+        name,
+        error: errorMessage,
+      });
+
+      return {
+        id: repository.id,
+        error: { message: errorMessage },
+      };
+    }
+  }
+
+  protected async getDetailsAsync(
+    api: Octokit,
+    owner: string,
+    name: string,
+  ): Promise<DetailsProviderResponse | undefined> {
+    try {
+      const response = await api.rest.repos.get({
+        owner,
+        repo: name,
+      });
+
+      return {
+        projectUrl: response.data.html_url,
+        projectDescription: response.data.description ?? undefined,
+        isFork: response.data.fork,
+        isArchived: response.data.archived,
+        createdAt: new Date(response.data.created_at),
+        starsCount: response.data.stargazers_count,
+        openIssues: response.data.open_issues_count,
+        forksCount: response.data.forks_count,
+      };
+    } catch (error) {
+      localLogger.warn(`Failed to get details for ${owner}\\${name} with Github integration`, {
+        owner,
+        name,
+        error: error instanceof RequestError ? error.message : String(error),
+      });
+      return undefined;
+    }
+  }
+
+  private getApi() {
+    return new Octokit({
+      baseUrl: this.url("/").origin,
+      request: {
+        fetch: fetchWithTrustedCertificatesAsync,
+      },
+      userAgent: GithubIntegration.userAgent,
+      throttle: { enabled: false }, // Disable throttling for this integration, Octokit will retry by default after a set time, thus delaying the repsonse to the user in case of errors. Errors will be shown to the user, no need to retry the request.
+      ...(this.hasSecretValue("personalAccessToken") ? { auth: this.getSecretValue("personalAccessToken") } : {}),
+    });
+  }
+}

packages/integrations/src/gitlab/gitlab-integration.ts

@@ -0,0 +1,159 @@
+import type { Gitlab as CoreGitlab } from "@gitbeaker/core";
+import { createRequesterFn, defaultOptionsHandler } from "@gitbeaker/requester-utils";
+import type { FormattedResponse, RequestOptions, ResourceOptions } from "@gitbeaker/requester-utils";
+import { Gitlab } from "@gitbeaker/rest";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+import { logger } from "@homarr/log";
+
+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 { ReleasesProviderIntegration } from "../interfaces/releases-providers/releases-providers-integration";
+import { getLatestRelease } from "../interfaces/releases-providers/releases-providers-integration";
+import type {
+  DetailsProviderResponse,
+  ReleaseProviderResponse,
+  ReleasesRepository,
+  ReleasesResponse,
+} from "../interfaces/releases-providers/releases-providers-types";
+
+const localLogger = logger.child({ module: "GitlabIntegration" });
+
+export class GitlabIntegration extends Integration implements ReleasesProviderIntegration {
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const response = await input.fetchAsync(this.url("/api/v4/projects"), {
+      headers: {
+        ...(this.hasSecretValue("personalAccessToken")
+          ? { Authorization: `Bearer ${this.getSecretValue("personalAccessToken")}` }
+          : {}),
+      },
+    });
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult(response);
+    }
+
+    return {
+      success: true,
+    };
+  }
+
+  public async getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse> {
+    const api = this.getApi();
+
+    const details = await this.getDetailsAsync(api, repository.identifier);
+
+    try {
+      const releasesResponse = await api.ProjectReleases.all(repository.identifier, {
+        perPage: 100,
+      });
+
+      if (releasesResponse instanceof Error) {
+        localLogger.warn(`Failed to get releases for ${repository.identifier} with Gitlab integration`, {
+          identifier: repository.identifier,
+          error: releasesResponse.message,
+        });
+        return {
+          id: repository.id,
+          error: { code: "noReleasesFound" },
+        };
+      }
+
+      const releasesProviderResponse = releasesResponse.reduce<ReleaseProviderResponse[]>((acc, release) => {
+        if (!release.released_at) return acc;
+
+        const releaseDate = new Date(release.released_at);
+
+        acc.push({
+          latestRelease: release.name ?? release.tag_name,
+          latestReleaseAt: releaseDate,
+          releaseUrl: release._links.self,
+          releaseDescription: release.description ?? undefined,
+          isPreRelease: releaseDate > new Date(), // For upcoming releases the `released_at` will be set to the future (https://docs.gitlab.com/api/releases/#upcoming-releases). Gitbreaker doesn't currently support the `upcoming_release` field (https://github.com/jdalrymple/gitbeaker/issues/3730)
+        });
+        return acc;
+      }, []);
+
+      return getLatestRelease(releasesProviderResponse, repository, details);
+    } catch (error) {
+      localLogger.warn(`Failed to get releases for ${repository.identifier} with Gitlab integration`, {
+        identifier: repository.identifier,
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        id: repository.id,
+        error: { code: "noReleasesFound" },
+      };
+    }
+  }
+
+  protected async getDetailsAsync(api: CoreGitlab, identifier: string): Promise<DetailsProviderResponse | undefined> {
+    try {
+      const response = await api.Projects.show(identifier);
+
+      if (response instanceof Error) {
+        localLogger.warn(`Failed to get details for ${identifier} with Gitlab integration`, {
+          identifier,
+          error: response.message,
+        });
+
+        return undefined;
+      }
+
+      if (!response.web_url) {
+        localLogger.warn(`No web URL found for ${identifier} with Gitlab integration`, {
+          identifier,
+        });
+        return undefined;
+      }
+
+      return {
+        projectUrl: response.web_url,
+        projectDescription: response.description,
+        isFork: response.forked_from_project !== null,
+        isArchived: response.archived,
+        createdAt: new Date(response.created_at),
+        starsCount: response.star_count,
+        openIssues: response.open_issues_count,
+        forksCount: response.forks_count,
+      };
+    } catch (error) {
+      localLogger.warn(`Failed to get details for ${identifier} with Gitlab integration`, {
+        identifier,
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return undefined;
+    }
+  }
+
+  private getApi() {
+    return new Gitlab({
+      host: this.url("/").origin,
+      requesterFn: createRequesterFn(
+        async (serviceOptions: ResourceOptions, _: RequestOptions) => await defaultOptionsHandler(serviceOptions),
+        async (endpoint: string, options?: Record<string, unknown>): Promise<FormattedResponse> => {
+          if (options === undefined) {
+            throw new Error("Gitlab library is not configured correctly. Options must be provided.");
+          }
+
+          const response = await fetchWithTrustedCertificatesAsync(
+            `${options.prefixUrl as string}${endpoint}`,
+            options,
+          );
+          const headers = Object.fromEntries(response.headers.entries());
+
+          return {
+            status: response.status,
+            headers,
+            body: await response.json(),
+          } as FormattedResponse;
+        },
+      ),
+      ...(this.hasSecretValue("personalAccessToken") ? { token: this.getSecretValue("personalAccessToken") } : {}),
+    });
+  }
+}

packages/integrations/src/index.ts

@@ -27,6 +27,7 @@ export type { IntegrationInput } from "./base/integration";
 export type { DownloadClientJobsAndStatus } from "./interfaces/downloads/download-client-data";
 export type { ExtendedDownloadClientItem } from "./interfaces/downloads/download-client-items";
 export type { ExtendedClientStatus } from "./interfaces/downloads/download-client-status";
+
 export type { SystemHealthMonitoring } from "./interfaces/health-monitoring/health-monitoring-types";
 export { MediaRequestStatus } from "./interfaces/media-requests/media-request-types";
 export type { MediaRequestList, MediaRequestStats } from "./interfaces/media-requests/media-request-types";
@@ -37,6 +38,7 @@ export type {
   TdarrStatistics,
   TdarrWorker,
 } from "./interfaces/media-transcoding/media-transcoding-types";
+export type { ReleasesResponse } from "./interfaces/releases-providers/releases-providers-types";
 export type { Notification } from "./interfaces/notifications/notification-types";
 
 // Schemas

packages/integrations/src/interfaces/releases-providers/releases-providers-integration.ts

@@ -0,0 +1,47 @@
+import type {
+  DetailsProviderResponse,
+  ReleaseProviderResponse,
+  ReleasesRepository,
+  ReleasesResponse,
+} from "./releases-providers-types";
+
+export const getLatestRelease = (
+  releases: ReleaseProviderResponse[],
+  repository: ReleasesRepository,
+  details?: DetailsProviderResponse,
+): ReleasesResponse => {
+  const validReleases = releases.filter((result) => {
+    if (result.latestRelease) {
+      return repository.versionRegex ? new RegExp(repository.versionRegex).test(result.latestRelease) : true;
+    }
+
+    return true;
+  });
+
+  const latest =
+    validReleases.length === 0
+      ? ({
+          id: repository.id,
+          error: { code: "noMatchingVersion" },
+        } as ReleasesResponse)
+      : validReleases.reduce(
+          (latest, result) => {
+            return {
+              ...details,
+              ...(result.latestReleaseAt > latest.latestReleaseAt ? result : latest),
+              id: repository.id,
+            };
+          },
+          {
+            id: "",
+            latestRelease: "",
+            latestReleaseAt: new Date(0),
+          },
+        );
+
+  return latest;
+};
+
+export interface ReleasesProviderIntegration {
+  getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse>;
+}

packages/integrations/src/interfaces/releases-providers/releases-providers-types.ts

@@ -0,0 +1,53 @@
+import type { TranslationObject } from "@homarr/translation";
+
+export interface DetailsProviderResponse {
+  projectUrl?: string;
+  projectDescription?: string;
+  isFork?: boolean;
+  isArchived?: boolean;
+  createdAt?: Date;
+  starsCount?: number;
+  openIssues?: number;
+  forksCount?: number;
+}
+
+export interface ReleaseProviderResponse {
+  latestRelease: string;
+  latestReleaseAt: Date;
+  releaseUrl?: string;
+  releaseDescription?: string;
+  isPreRelease?: boolean;
+}
+
+export interface ReleasesRepository {
+  id: string;
+  identifier: string;
+  versionRegex?: string;
+}
+
+type ReleasesErrorKeys = keyof TranslationObject["widget"]["releases"]["error"]["messages"];
+
+export interface ReleasesResponse {
+  id: string;
+  latestRelease?: string;
+  latestReleaseAt?: Date;
+  releaseUrl?: string;
+  releaseDescription?: string;
+  isPreRelease?: boolean;
+  projectUrl?: string;
+  projectDescription?: string;
+  isFork?: boolean;
+  isArchived?: boolean;
+  createdAt?: Date;
+  starsCount?: number;
+  openIssues?: number;
+  forksCount?: number;
+
+  error?:
+    | {
+        code: ReleasesErrorKeys;
+      }
+    | {
+        message: string;
+      };
+}

packages/integrations/src/npm/npm-integration.ts

@@ -0,0 +1,56 @@
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+
+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 { ReleasesProviderIntegration } from "../interfaces/releases-providers/releases-providers-integration";
+import { getLatestRelease } from "../interfaces/releases-providers/releases-providers-integration";
+import type { ReleasesRepository, ReleasesResponse } from "../interfaces/releases-providers/releases-providers-types";
+import { releasesResponseSchema } from "./npm-schemas";
+
+export class NPMIntegration extends Integration implements ReleasesProviderIntegration {
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const response = await input.fetchAsync(this.url("/"));
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult(response);
+    }
+
+    return {
+      success: true,
+    };
+  }
+
+  public async getLatestMatchingReleaseAsync(repository: ReleasesRepository): Promise<ReleasesResponse> {
+    const releasesResponse = await fetchWithTrustedCertificatesAsync(
+      this.url(`/${encodeURIComponent(repository.identifier)}`),
+    );
+
+    if (!releasesResponse.ok) {
+      return {
+        id: repository.id,
+        error: { message: releasesResponse.statusText },
+      };
+    }
+
+    const releasesResponseJson: unknown = await releasesResponse.json();
+    const { data, success, error } = releasesResponseSchema.safeParse(releasesResponseJson);
+
+    if (!success) {
+      return {
+        id: repository.id,
+        error: {
+          message: releasesResponseJson ? JSON.stringify(releasesResponseJson, null, 2) : error.message,
+        },
+      };
+    } else {
+      const formattedReleases = data.time.map((tag) => ({
+        ...tag,
+        releaseUrl: `https://www.npmjs.com/package/${encodeURIComponent(data.name)}/v/${encodeURIComponent(tag.latestRelease)}`,
+        releaseDescription: data.versions[tag.latestRelease]?.description ?? "",
+      }));
+      return getLatestRelease(formattedReleases, repository);
+    }
+  }
+}

packages/integrations/src/npm/npm-schemas.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+export const releasesResponseSchema = z.object({
+  time: z.record(z.string().transform((value) => new Date(value))).transform((version) =>
+    Object.entries(version).map(([key, value]) => ({
+      latestRelease: key,
+      latestReleaseAt: value,
+    })),
+  ),
+  versions: z.record(z.object({ description: z.string() })),
+  name: z.string(),
+});

packages/integrations/src/openmediavault/openmediavault-integration.ts

@@ -155,7 +155,7 @@ export class OpenMediaVaultIntegration extends Integration implements ISystemHea
         return response;
       }
 
-      localLogger.info("Session expired, getting new session", { integrationId: this.integration.id });
+      localLogger.debug("Session expired, getting new session", { integrationId: this.integration.id });
     }
 
     const session = await this.getSessionAsync();

packages/integrations/src/pi-hole/v6/pi-hole-integration-v6.ts

@@ -128,7 +128,7 @@ export class PiHoleIntegrationV6 extends Integration implements DnsHoleSummaryIn
         return response;
       }
 
-      localLogger.info("Session expired, getting new session", { integrationId: this.integration.id });
+      localLogger.debug("Session expired, getting new session", { integrationId: this.integration.id });
     }
 
     const sessionId = await this.getSessionAsync();