feat(settings): unified server-URL resolver + field; adopt in Jellyseerr

Type a loose address (media.example.com, https://…, host:port) and the app finds the working, canonical URL.

- utils/serverUrl: generic candidate generator (https-first, port/path preserved, no Jellyfin-specific ports), parallel-probe resolver, numeric semver compare, and a Jellyseerr probe (/api/v1/status, min 2.0.0).

- useServerUrlResolver: idle -> resolving -> ok | error state machine with cancellation.

- ServerUrlField: shared input that auto-resolves on blur, inline status chip (tap to re-test) + resolved URL, persists the canonical URL.

- Jellyseerr settings adopt the field and log in with the resolved URL. Probe contract makes Streamystats/Jellyfin/Merlin a drop-in follow-up.

utils/serverUrl/candidates.ts

@@ -0,0 +1,75 @@
+/**
+ * Generic server-URL candidate generator.
+ *
+ * Turns loose user input (`media.uruk.dev`, `https://media.uruk.dev`,
+ * `host:8096`, `http://10.0.0.5:3000/path`) into an ordered list of full URLs
+ * to probe — https first, http as fallback — while preserving any explicit
+ * port and path. Service-agnostic: unlike the Jellyfin SDK's `getAddressCandidates`
+ * it adds no Jellyfin-specific ports, so it suits Jellyseerr/Streamystats/etc.
+ */
+
+// scheme? host (port)? (path/query/hash)?
+const URL_RE = /^(?:(https?):\/\/)?([^/:\s?#]+)(?::(\d+))?([/?#].*)?$/i;
+
+export interface ParsedServerInput {
+  scheme?: "http" | "https";
+  host: string;
+  port?: string;
+  /** Normalized path+query+hash, without a trailing slash; "" when none. */
+  path: string;
+}
+
+function normalizePath(path?: string): string {
+  if (!path || path === "/") return "";
+  return path.replace(/\/+$/, "");
+}
+
+/** Parse loose user input. Returns null when it can't be understood. */
+export function parseServerInput(input: string): ParsedServerInput | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  const match = URL_RE.exec(trimmed);
+  if (!match) return null;
+
+  const [, scheme, host, port, rawPath] = match;
+  return {
+    scheme: scheme ? (scheme.toLowerCase() as "http" | "https") : undefined,
+    host: host.toLowerCase(),
+    port,
+    path: normalizePath(rawPath),
+  };
+}
+
+function buildUrl(
+  scheme: "http" | "https",
+  host: string,
+  port: string | undefined,
+  path: string,
+): string {
+  return `${scheme}://${host}${port ? `:${port}` : ""}${path}`;
+}
+
+/**
+ * Ordered, de-duplicated candidate URLs for the given input.
+ *
+ * - Explicit scheme AND port → trusted as-is (single candidate).
+ * - Otherwise https is tried before http (prefer secure), keeping any port/path.
+ *
+ * @returns [] when the input can't be parsed.
+ */
+export function getServerUrlCandidates(input: string): string[] {
+  const parsed = parseServerInput(input);
+  if (!parsed) return [];
+
+  const { scheme, host, port, path } = parsed;
+
+  // Fully specified: don't second-guess the user.
+  if (scheme && port) return [buildUrl(scheme, host, port, path)];
+
+  // Secure-first; the typed scheme (if any) is still covered by this set.
+  const candidates = (["https", "http"] as const).map((s) =>
+    buildUrl(s, host, port, path),
+  );
+  return Array.from(new Set(candidates));
+}

utils/serverUrl/index.ts

@@ -0,0 +1,14 @@
+export {
+  getServerUrlCandidates,
+  type ParsedServerInput,
+  parseServerInput,
+} from "./candidates";
+export { jellyseerrProbe } from "./probes/jellyseerr";
+export {
+  type ResolveFailureReason,
+  type ResolveOptions,
+  type ResolveResult,
+  resolveServerUrl,
+} from "./resolve";
+export { isVersionBelow } from "./semver";
+export type { ServerProbe, ServerProbeOutcome } from "./types";

utils/serverUrl/probes/jellyseerr.ts

@@ -0,0 +1,41 @@
+import axios from "axios";
+import { isVersionBelow } from "../semver";
+import type { ServerProbe } from "../types";
+
+/** Jellyseerr/Overseerr minimum supported version. */
+const MIN_VERSION = "2.0.0";
+
+/**
+ * Probe for a Jellyseerr server. `/api/v1/status` is jellyseerr/overseerr
+ * specific and unauthenticated, so it both proves reachability and confirms
+ * we hit the right service.
+ */
+export const jellyseerrProbe: ServerProbe = async (url, signal) => {
+  try {
+    const { status, data } = await axios.get(`${url}/api/v1/status`, {
+      signal,
+      timeout: 8000, // backstop; the resolver aborts via signal first
+    });
+
+    if (status < 200 || status >= 300) return { status: "unreachable" };
+
+    const version: string | undefined =
+      typeof data?.version === "string" ? data.version : undefined;
+
+    // A JSON body carrying version/commitTag identifies a real jellyseerr.
+    if (
+      !version &&
+      !(data && typeof data === "object" && "commitTag" in data)
+    ) {
+      return { status: "wrong-service" };
+    }
+
+    if (version && isVersionBelow(version, MIN_VERSION)) {
+      return { status: "version-too-low", version };
+    }
+
+    return { status: "ok", meta: { version } };
+  } catch {
+    return { status: "unreachable" };
+  }
+};

utils/serverUrl/resolve.ts

@@ -0,0 +1,94 @@
+import { getServerUrlCandidates } from "./candidates";
+import type { ServerProbe, ServerProbeOutcome } from "./types";
+
+export type ResolveFailureReason =
+  | "empty"
+  | "invalid"
+  | "version-too-low"
+  | "wrong-service"
+  | "unreachable";
+
+export type ResolveResult =
+  | { ok: true; url: string; meta?: Record<string, unknown> }
+  | { ok: false; reason: ResolveFailureReason; version?: string };
+
+export interface ResolveOptions {
+  /** Per-candidate probe timeout in ms. Default 5000. */
+  timeoutMs?: number;
+  /** Abort the whole resolution (cancels every in-flight probe). */
+  signal?: AbortSignal;
+}
+
+// Order in which to surface a failure when no candidate validated:
+// the more specific/actionable the reason, the earlier it is reported.
+const FAILURE_PRIORITY = [
+  "version-too-low",
+  "wrong-service",
+  "unreachable",
+] as const satisfies ReadonlyArray<ResolveFailureReason>;
+
+/**
+ * Resolve loose user input to a single working, canonical server URL.
+ *
+ * Generates candidates (https-first), probes them in parallel with a per-candidate
+ * timeout, and returns the first candidate (in preference order) the probe
+ * accepted. When none work, the most actionable failure is returned.
+ */
+export async function resolveServerUrl(
+  input: string,
+  probe: ServerProbe,
+  options: ResolveOptions = {},
+): Promise<ResolveResult> {
+  const { timeoutMs = 5000, signal } = options;
+
+  if (!input.trim()) return { ok: false, reason: "empty" };
+
+  const candidates = getServerUrlCandidates(input);
+  if (candidates.length === 0) return { ok: false, reason: "invalid" };
+
+  const outcomes = await Promise.all(
+    candidates.map((url) => runProbe(url, probe, timeoutMs, signal)),
+  );
+
+  // Prefer the first candidate (https-first) that validated.
+  for (let i = 0; i < candidates.length; i++) {
+    const outcome = outcomes[i];
+    if (outcome.status === "ok") {
+      return { ok: true, url: candidates[i], meta: outcome.meta };
+    }
+  }
+
+  // Nothing validated: report the most useful failure.
+  for (const reason of FAILURE_PRIORITY) {
+    const hit = outcomes.find((outcome) => outcome.status === reason);
+    if (hit) {
+      return {
+        ok: false,
+        reason,
+        version: hit.status === "version-too-low" ? hit.version : undefined,
+      };
+    }
+  }
+  return { ok: false, reason: "unreachable" };
+}
+
+async function runProbe(
+  url: string,
+  probe: ServerProbe,
+  timeoutMs: number,
+  parentSignal?: AbortSignal,
+): Promise<ServerProbeOutcome> {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  parentSignal?.addEventListener("abort", abort);
+  const timer = setTimeout(abort, timeoutMs);
+
+  try {
+    return await probe(url, controller.signal);
+  } catch {
+    return { status: "unreachable" };
+  } finally {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", abort);
+  }
+}

utils/serverUrl/semver.ts

@@ -0,0 +1,22 @@
+/**
+ * Strict numeric "below" comparison for dotted versions.
+ *
+ * Avoids the string-comparison bug (`"1.9.9" < "2.0.0"` works by luck but
+ * `"2.10.0" < "2.0.0"` is wrongly true). Non-numeric/pre-release suffixes on a
+ * segment are ignored (e.g. `2.0.0-beta` → 2.0.0).
+ */
+export function isVersionBelow(version: string, minimum: string): boolean {
+  const parse = (v: string) =>
+    v.split(".").map((segment) => Number.parseInt(segment, 10) || 0);
+
+  const a = parse(version);
+  const b = parse(minimum);
+  const length = Math.max(a.length, b.length);
+
+  for (let i = 0; i < length; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}

utils/serverUrl/types.ts

@@ -0,0 +1,16 @@
+/** Result of probing a single candidate URL for a specific service. */
+export type ServerProbeOutcome =
+  | { status: "ok"; meta?: Record<string, unknown> }
+  | { status: "version-too-low"; version?: string }
+  | { status: "wrong-service" }
+  | { status: "unreachable" };
+
+/**
+ * Validates one fully-qualified candidate URL for a given service.
+ * Implementations must resolve (never reject) — map errors to "unreachable".
+ * The provided signal is aborted on timeout or cancellation.
+ */
+export type ServerProbe = (
+  url: string,
+  signal: AbortSignal,
+) => Promise<ServerProbeOutcome>;