feat(integrations): teach externalUrl to handle path-only bases

Address review comment from @Meierschlumpf on PR homarr-labs#5595 about the
integration-middleware externalUrl pass-through.

Reverting middleware to `app?.href ?? null` would have crashed `new URL`
inside `createUrl` for path-only bases (e.g. "/cockpit/"). This commit
makes path-only externalUrl a first-class state instead.

- packages/integrations/src/base/integration.ts: new RenderablePath
  class mirrors just enough of the WHATWG URL surface (toString,
  pathname, hostname, searchParams) for the existing externalUrl
  caller set. The `externalUrl` method branches on `startsWith("/")`
  and returns a RenderablePath for path-only bases or a URL for
  absolute bases (existing behavior). All 19 caller sites continue to
  work unchanged: 17 immediately call `.toString()` and the two
  outliers (ntfy reads `.hostname` and `.pathname` for a fallback
  title; overseerr returns the value up to a `.toString()` caller in
  constructAvatarUrl) keep behaving sensibly for path-only.

- packages/api/src/middlewares/integration.ts: restore
  `externalUrl: rest.app?.href ?? null` at both call sites per the
  reviewer's suggestion. Path-only hrefs now flow through to
  integrations untouched, where the new RenderablePath branch in
  createUrl handles them. The same fix automatically resolves the
  pre-existing pattern in
  packages/request-handler/src/lib/cached-request-integration-job-handler.ts:97
  where externalUrl is built the same way.

- packages/integrations/test/base.spec.ts: six new tests covering
  absolute and path-only externalUrl, query-param merging in both,
  path-embedded query strings combined with extra query-params for
  path-only, and the null-externalUrl fallback to integration.url.

Net effect: integrations bound to path-only-href apps render their
hrefs against the user's current origin (e.g. Jellyfin "Watch movie"
links resolve as /signalk-server/... instead of the internal
http://signalk:3000/...). Materially better for the multi-hostname
use case this PR is built for.

resolveServerUrl stays in packages/api/src/router/widgets/app.ts for
the ping endpoint - the server genuinely cannot ping a hostless URL,
so CONFLICT is still the right signal there. The middleware case is
different because the value is rendered, not fetched.

Author: mairas

packages/api/src/middlewares/integration.ts

@@ -4,7 +4,6 @@ import { z } from "zod/v4";
 import type { Session } from "@homarr/auth";
 import { hasQueryAccessToIntegrationsAsync } from "@homarr/auth/server";
 import { constructIntegrationPermissions } from "@homarr/auth/shared";
-import { resolveServerUrl } from "@homarr/common";
 import { decryptSecret } from "@homarr/common/server";
 import type { AtLeastOneOf } from "@homarr/common/types";
 import type { Database } from "@homarr/db";
@@ -67,7 +66,7 @@ export const createOneIntegrationMiddleware = <TKind extends IntegrationKind>(
       ctx: {
         integration: {
           ...rest,
-          externalUrl: rest.app ? resolveServerUrl(rest.app) : null,
+          externalUrl: rest.app?.href ?? null,
           kind: kind as TKind,
           decryptedSecrets: secrets.map((secret) => ({
             ...secret,
@@ -129,7 +128,7 @@ export const createManyIntegrationMiddleware = <TKind extends IntegrationKind>(
         integrations: dbIntegrations.map(
           ({ secrets, kind, items: _ignore1, groupPermissions: _ignore2, userPermissions: _ignore3, ...rest }) => ({
             ...rest,
-            externalUrl: rest.app ? resolveServerUrl(rest.app) : null,
+            externalUrl: rest.app?.href ?? null,
             kind: kind as TKind,
             decryptedSecrets: secrets.map((secret) => ({
               ...secret,

packages/integrations/src/base/integration.ts

@@ -81,8 +81,15 @@ export abstract class Integration {
   protected externalUrl(
     path: `/${string}`,
     queryParams?: Record<string, string | Date | number | boolean | null | undefined>,
-  ) {
-    return this.createUrl(this.integration.externalUrl ?? this.integration.url, path, queryParams);
+  ): URL | RenderablePath {
+    const base = this.integration.externalUrl ?? this.integration.url;
+    // Path-only externalUrl (e.g. "/cockpit/") cannot be parsed by `new URL`,
+    // but the rendered href ends up on the client where the browser resolves
+    // it against the current origin. Build a hostless RenderablePath instead.
+    if (base.startsWith("/")) {
+      return new RenderablePath(base, path, queryParams);
+    }
+    return this.createUrl(base, path, queryParams);
   }
 
   public async testConnectionAsync(): Promise<TestingResult> {
@@ -125,3 +132,58 @@ export abstract class Integration {
    */
   protected abstract testingAsync(input: IntegrationTestingInput): Promise<TestingResult>;
 }
+
+/**
+ * URL-shaped wrapper for path-only externalUrl bases (e.g. "/cockpit/").
+ *
+ * Path-only externalUrl is meaningful only on the client, where the browser
+ * resolves it against the current origin. The integration helpers can't use
+ * `new URL` server-side because there's no host to parse. RenderablePath
+ * mirrors just enough of the `URL` surface — `toString()`, `pathname`,
+ * `hostname`, `searchParams` — to keep the 19 caller sites of
+ * `super.externalUrl(...)` working unchanged. `hostname` is always the empty
+ * string for a path-only base; `pathname` is the joined base + path.
+ */
+export class RenderablePath {
+  public readonly searchParams: URLSearchParams;
+  private readonly pathOnly: string;
+
+  constructor(
+    base: string,
+    path: `/${string}`,
+    queryParams?: Record<string, string | Date | number | boolean | null | undefined>,
+  ) {
+    const trimmedBase = removeTrailingSlash(base);
+    const combined = `${trimmedBase}${path}`;
+    const queryIndex = combined.indexOf("?");
+    if (queryIndex === -1) {
+      this.pathOnly = combined;
+      this.searchParams = new URLSearchParams();
+    } else {
+      this.pathOnly = combined.substring(0, queryIndex);
+      this.searchParams = new URLSearchParams(combined.substring(queryIndex + 1));
+    }
+
+    if (queryParams) {
+      for (const [key, value] of Object.entries(queryParams)) {
+        if (value === null || value === undefined) {
+          continue;
+        }
+        this.searchParams.set(key, value instanceof Date ? value.toISOString() : value.toString());
+      }
+    }
+  }
+
+  public get hostname(): string {
+    return "";
+  }
+
+  public get pathname(): string {
+    return this.pathOnly;
+  }
+
+  public toString(): string {
+    const query = this.searchParams.toString();
+    return query ? `${this.pathOnly}?${query}` : this.pathOnly;
+  }
+}

packages/integrations/test/base.spec.ts

@@ -4,7 +4,7 @@ import { ResponseError } from "@homarr/common/server";
 import { createDb } from "@homarr/db/test";
 
 import type { IntegrationTestingInput } from "../src/base/integration";
-import { Integration } from "../src/base/integration";
+import { Integration, RenderablePath } from "../src/base/integration";
 import type { TestingResult } from "../src/base/test-connection/test-connection-service";
 
 vi.mock("@homarr/db", async (importActual) => {
@@ -42,22 +42,73 @@ describe("Base integration", () => {
     expect(result.error.data.url).toContain("https://example.com");
     expect(result.error.data.reason).toBe("internalServerError");
   });
+
+  describe("externalUrl", () => {
+    test("returns a URL for an absolute externalUrl", () => {
+      const integration = new FakeIntegration(undefined, undefined, "https://example.com");
+      const result = integration.callExternalUrl("/items/42");
+      expect(result).toBeInstanceOf(URL);
+      expect(result.toString()).toBe("https://example.com/items/42");
+    });
+
+    test("merges queryParams onto an absolute externalUrl", () => {
+      const integration = new FakeIntegration(undefined, undefined, "https://example.com");
+      const result = integration.callExternalUrl("/items", { id: "42", since: new Date("2026-01-01T00:00:00Z") });
+      expect(result.toString()).toBe("https://example.com/items?id=42&since=2026-01-01T00%3A00%3A00.000Z");
+    });
+
+    test("returns a RenderablePath for a path-only externalUrl", () => {
+      const integration = new FakeIntegration(undefined, undefined, "/cockpit/");
+      const result = integration.callExternalUrl("/web/index.html");
+      expect(result).toBeInstanceOf(RenderablePath);
+      expect(result.toString()).toBe("/cockpit/web/index.html");
+      expect(result.pathname).toBe("/cockpit/web/index.html");
+      expect(result.hostname).toBe("");
+    });
+
+    test("merges queryParams onto a path-only externalUrl", () => {
+      const integration = new FakeIntegration(undefined, undefined, "/cockpit/");
+      const result = integration.callExternalUrl("/web/index.html", { id: "42" });
+      expect(result.toString()).toBe("/cockpit/web/index.html?id=42");
+    });
+
+    test("merges path-embedded query with extra queryParams on a path-only externalUrl", () => {
+      const integration = new FakeIntegration(undefined, undefined, "/signalk-server/");
+      const result = integration.callExternalUrl("/items/42?width=100", { quality: "90" });
+      expect(result.pathname).toBe("/signalk-server/items/42");
+      expect(result.toString()).toBe("/signalk-server/items/42?width=100&quality=90");
+    });
+
+    test("falls back to integration.url when externalUrl is null and the integration url is absolute", () => {
+      const integration = new FakeIntegration(undefined, undefined, null);
+      const result = integration.callExternalUrl("/items/42");
+      expect(result.toString()).toBe("https://example.com/items/42");
+    });
+  });
 });
 
 class FakeIntegration extends Integration {
   constructor(
     private testingResult?: TestingResult,
     private error?: Error,
+    externalUrl: string | null = null,
   ) {
     super({
       id: "test",
       name: "Test",
       url: "https://example.com",
       decryptedSecrets: [],
-      externalUrl: null,
+      externalUrl,
     });
   }
 
+  public callExternalUrl(
+    path: `/${string}`,
+    queryParams?: Record<string, string | Date | number | boolean | null | undefined>,
+  ) {
+    return this.externalUrl(path, queryParams);
+  }
+
   // eslint-disable-next-line no-restricted-syntax
   protected testingAsync(_: IntegrationTestingInput): Promise<TestingResult> {
     if (this.error) {