feat(beszel): add Beszel integration with system monitoring widgets (#5900)

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

@@ -0,0 +1,269 @@
+import { ResponseError } from "@homarr/common/server";
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+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 {
+  BeszelAlert,
+  BeszelAlertHistory,
+  BeszelAuthResponse,
+  BeszelContainer,
+  BeszelContainerStatsRecord,
+  BeszelSmartDevice,
+  BeszelSystem,
+  BeszelSystemDetails,
+  BeszelSystemdService,
+  BeszelSystemStatsRecord,
+  CreateAlertInput,
+  PocketBaseListResponse,
+  UpdateAlertInput,
+} from "./beszel-types";
+
+const escapeFilterValue = (value: string) => value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+
+interface BeszelSession {
+  token: string;
+  userId: string;
+}
+
+export class BeszelIntegration extends Integration {
+  private readonly sessionStore: SessionStore<BeszelSession>;
+
+  constructor(integration: IntegrationInput) {
+    super(integration);
+    this.sessionStore = createSessionStore(integration);
+  }
+
+  private async authenticateAsync(): Promise<BeszelSession> {
+    const existingSession = await this.sessionStore.getAsync();
+    if (existingSession) {
+      return existingSession;
+    }
+
+    const response = await fetchWithTrustedCertificatesAsync(this.url("/api/collections/users/auth-with-password"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        identity: this.getSecretValue("username"),
+        password: this.getSecretValue("password"),
+      }),
+    });
+
+    if (!response.ok) {
+      throw new ResponseError(response);
+    }
+
+    const data = (await response.json()) as BeszelAuthResponse;
+    const session: BeszelSession = { token: data.token, userId: data.record.id };
+    await this.sessionStore.setAsync(session);
+    return session;
+  }
+
+  private async fetchWithAuthAsync(url: URL, options: { method?: string; body?: string } = {}) {
+    let session = await this.authenticateAsync();
+
+    const doFetch = (token: string) =>
+      fetchWithTrustedCertificatesAsync(url, {
+        method: options.method ?? "GET",
+        headers: {
+          Authorization: token,
+          ...(options.body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: options.body,
+      });
+
+    let response = await doFetch(session.token);
+
+    if (response.status === 401) {
+      await this.sessionStore.clearAsync();
+      session = await this.authenticateAsync();
+      response = await doFetch(session.token);
+    }
+
+    if (!response.ok) {
+      throw new ResponseError(response);
+    }
+
+    return response;
+  }
+
+  public async getSystemsAsync(): Promise<BeszelSystem[]> {
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/systems/records", { perPage: "500", sort: "-updated" }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelSystem>;
+    return data.items;
+  }
+
+  public async getSystemDetailsAsync(systemId: string): Promise<BeszelSystemDetails> {
+    const response = await this.fetchWithAuthAsync(
+      this.url(`/api/collections/system_details/records/${systemId}` as `/${string}`),
+    );
+    return (await response.json()) as BeszelSystemDetails;
+  }
+
+  public async getSystemStatsAsync(systemId: string, type = "1m", perPage = 60): Promise<BeszelSystemStatsRecord[]> {
+    const filter = `system='${escapeFilterValue(systemId)}' && type='${escapeFilterValue(type)}'`;
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/system_stats/records", {
+        filter,
+        sort: "-created",
+        perPage: String(perPage),
+      }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelSystemStatsRecord>;
+    return data.items;
+  }
+
+  public async getContainersAsync(systemId: string): Promise<BeszelContainer[]> {
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/containers/records", {
+        filter: `system='${escapeFilterValue(systemId)}'`,
+        sort: "-updated",
+        perPage: "500",
+      }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelContainer>;
+    return data.items;
+  }
+
+  public async getContainerStatsAsync(
+    systemId: string,
+    type = "1m",
+    perPage = 60,
+  ): Promise<BeszelContainerStatsRecord[]> {
+    const filter = `system='${escapeFilterValue(systemId)}' && type='${escapeFilterValue(type)}'`;
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/container_stats/records", {
+        filter,
+        sort: "-created",
+        perPage: String(perPage),
+      }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelContainerStatsRecord>;
+    return data.items;
+  }
+
+  public async getSmartDevicesAsync(systemId: string): Promise<BeszelSmartDevice[]> {
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/smart_devices/records", {
+        filter: `system='${escapeFilterValue(systemId)}'`,
+      }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelSmartDevice>;
+    return data.items;
+  }
+
+  public async getSystemdServicesAsync(systemId: string): Promise<BeszelSystemdService[]> {
+    const response = await this.fetchWithAuthAsync(
+      this.url("/api/collections/systemd_services/records", {
+        filter: `system='${escapeFilterValue(systemId)}'`,
+        sort: "name",
+      }),
+    );
+    const data = (await response.json()) as PocketBaseListResponse<BeszelSystemdService>;
+    return data.items;
+  }
+
+  public async getAlertsAsync(systemId?: string): Promise<BeszelAlert[]> {
+    const params: Record<string, string> = { perPage: "500" };
+    if (systemId) {
+      params.filter = `system='${escapeFilterValue(systemId)}'`;
+    }
+    const response = await this.fetchWithAuthAsync(this.url("/api/collections/alerts/records", params));
+    const data = (await response.json()) as PocketBaseListResponse<BeszelAlert>;
+    return data.items;
+  }
+
+  public async getAlertHistoryAsync(systemId?: string, perPage = 50): Promise<BeszelAlertHistory[]> {
+    const params: Record<string, string> = {
+      sort: "-created",
+      perPage: String(perPage),
+    };
+    if (systemId) {
+      params.filter = `system='${escapeFilterValue(systemId)}'`;
+    }
+    const response = await this.fetchWithAuthAsync(this.url("/api/collections/alerts_history/records", params));
+    const data = (await response.json()) as PocketBaseListResponse<BeszelAlertHistory>;
+    return data.items;
+  }
+
+  public async createAlertAsync(systemId: string, input: CreateAlertInput): Promise<BeszelAlert> {
+    const session = await this.authenticateAsync();
+    const response = await this.fetchWithAuthAsync(this.url("/api/collections/alerts/records"), {
+      method: "POST",
+      body: JSON.stringify({
+        system: systemId,
+        user: session.userId,
+        name: input.name,
+        value: input.value,
+        min: input.min ?? 0,
+        triggered: false,
+      }),
+    });
+    return (await response.json()) as BeszelAlert;
+  }
+
+  public async updateAlertAsync(alertId: string, input: UpdateAlertInput): Promise<BeszelAlert> {
+    const response = await this.fetchWithAuthAsync(
+      this.url(`/api/collections/alerts/records/${alertId}` as `/${string}`),
+      {
+        method: "PATCH",
+        body: JSON.stringify(input),
+      },
+    );
+    return (await response.json()) as BeszelAlert;
+  }
+
+  public async deleteAlertAsync(alertId: string): Promise<void> {
+    await this.fetchWithAuthAsync(this.url(`/api/collections/alerts/records/${alertId}` as `/${string}`), {
+      method: "DELETE",
+    });
+  }
+
+  public async pauseSystemAsync(systemId: string): Promise<void> {
+    await this.fetchWithAuthAsync(this.url(`/api/collections/systems/records/${systemId}` as `/${string}`), {
+      method: "PATCH",
+      body: JSON.stringify({ status: "paused" }),
+    });
+  }
+
+  public async resumeSystemAsync(systemId: string): Promise<void> {
+    await this.fetchWithAuthAsync(this.url(`/api/collections/systems/records/${systemId}` as `/${string}`), {
+      method: "PATCH",
+      body: JSON.stringify({ status: "pending" }),
+    });
+  }
+
+  public async deleteSystemAsync(systemId: string): Promise<void> {
+    await this.fetchWithAuthAsync(this.url(`/api/collections/systems/records/${systemId}` as `/${string}`), {
+      method: "DELETE",
+    });
+  }
+
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const response = await input.fetchAsync(this.url("/api/collections/users/auth-with-password"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        identity: this.getSecretValue("username"),
+        password: this.getSecretValue("password"),
+      }),
+    });
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult({ status: response.status, url: response.url });
+    }
+
+    const data = (await response.json()) as BeszelAuthResponse;
+    if (!data.token) {
+      return TestConnectionError.UnauthorizedResult(401);
+    }
+
+    return { success: true };
+  }
+}

packages/integrations/src/beszel/beszel-types.ts

@@ -0,0 +1,389 @@
+export interface BeszelAuthResponse {
+  token: string;
+  record: {
+    id: string;
+    email: string;
+    username: string;
+    verified: boolean;
+  };
+}
+
+export type BeszelSystemStatus = "up" | "down" | "paused" | "pending";
+
+/**
+ * Real-time system info snapshot from Beszel agent.
+ * Returned as `system.info` on each BeszelSystem record.
+ * All resource values are percentages or already-scaled summaries.
+ */
+export interface BeszelSystemInfo {
+  /** hostname */
+  h?: string;
+  /** CPU usage (%) */
+  cpu: number;
+  /** temperature (°C), overall */
+  t?: number;
+  /** CPU core count */
+  c?: number;
+  /** CPU thread count */
+  ct?: number;
+  /** CPU model string */
+  m?: string;
+  /** load average [1m, 5m, 15m] */
+  la?: [number, number, number];
+  /** OS identifier string */
+  o?: string;
+  /** uptime (seconds) */
+  u: number;
+  /** memory usage (%) */
+  mp: number;
+  /** disk usage (%) */
+  dp: number;
+  /** battery [level%, charging state] */
+  bat?: [number, number];
+  /** bandwidth — public interface (Mbps, legacy). Use bb when available */
+  b?: number;
+  /** bandwidth — public interface (bytes/s, newer format). Preferred over b */
+  bb?: number;
+  /** agent version */
+  v: string;
+  /** podman mode */
+  p?: boolean;
+  /** GPU usage (%) */
+  g?: number;
+  /** disk temperature (°C) */
+  dt?: number;
+  /** OS type identifier */
+  os?: number;
+  /** extra filesystem usage (%) keyed by mount path */
+  efs?: Record<string, number>;
+  /** systemd services [running, total] */
+  sv?: [number, number];
+}
+
+export interface BeszelSystem {
+  id: string;
+  name: string;
+  host: string;
+  port: string;
+  status: BeszelSystemStatus;
+  info: BeszelSystemInfo;
+  users?: string[];
+  created: string;
+  updated: string;
+}
+
+export interface BeszelSystemDetails {
+  id: string;
+  system: string;
+  hostname: string;
+  kernel: string;
+  cores: number;
+  threads: number;
+  cpu: string;
+  os: number;
+  os_name: string;
+  arch: string;
+  memory: number;
+  podman: boolean;
+  updated: string;
+}
+
+/**
+ * Historical system stats record from Beszel PocketBase.
+ * Stored per-interval (1m, 10m, 20m, 120m, 480m depending on time range).
+ *
+ * Units:
+ * - CPU/GPU/memory/disk percentages: 0–100
+ * - Memory/disk absolute values (mu, du, etc.): bytes
+ * - Disk I/O (dr, dw): bytes/s
+ * - Network (ns, nr): bytes/s — all interfaces (including loopback, docker bridges)
+ * - Bandwidth (b): bytes/s [sent, recv] — public interfaces only. Prefer b over ns/nr for user-facing charts
+ */
+export interface BeszelSystemStats {
+  /** CPU usage (%) */
+  cpu: number;
+  /** CPU usage max (%) */
+  cpum?: number;
+  /** per-core busy (%) */
+  cpub?: number[];
+  /** per-core speed (MHz) */
+  cpus?: number[];
+  /** load average [1m, 5m, 15m] */
+  la?: [number, number, number];
+  /** total memory (bytes) */
+  m: number;
+  /** memory used (bytes) */
+  mu: number;
+  /** memory usage (%) */
+  mp: number;
+  /** memory buffer/cache (bytes) */
+  mb: number;
+  /** memory max used (bytes) */
+  mm?: number;
+  /** memory zfs arc (bytes) */
+  mz?: number;
+  /** total swap (bytes) */
+  s: number;
+  /** swap used (bytes) */
+  su: number;
+  /** total disk (bytes) */
+  d: number;
+  /** disk used (bytes) */
+  du: number;
+  /** disk usage (%) */
+  dp: number;
+  /** disk read (bytes/s) */
+  dr: number;
+  /** disk write (bytes/s) */
+  dw: number;
+  /** disk read max (bytes/s) */
+  drm?: number;
+  /** disk write max (bytes/s) */
+  dwm?: number;
+  /** disk IOPS [read, write] */
+  dio?: [number, number];
+  /** disk IOPS max [read, write] */
+  diom?: [number, number];
+  /** network sent — all interfaces (bytes/s) */
+  ns: number;
+  /** network received — all interfaces (bytes/s) */
+  nr: number;
+  /** bandwidth — public interfaces only (bytes/s) [sent, recv]. Prefer over ns/nr */
+  b?: [number, number];
+  /** network sent max (bytes/s) */
+  nsm?: number;
+  /** network received max (bytes/s) */
+  nrm?: number;
+  /** bandwidth max [sent, recv] (bytes/s) */
+  bm?: [number, number];
+  /** temperatures keyed by sensor name (°C) */
+  t?: Record<string, number>;
+  /** extra filesystem stats keyed by mount path */
+  efs?: Record<string, BeszelExtraFsStats>;
+  /** GPU stats keyed by device id */
+  g?: Record<string, BeszelGPUData>;
+  /** battery [level%, charging state] */
+  bat?: [number, number];
+  /** network interfaces [rx bytes/s, tx bytes/s, rx max, tx max] */
+  ni?: Record<string, [number, number, number, number]>;
+}
+
+export interface BeszelExtraFsStats {
+  /** total disk (bytes) */
+  d: number;
+  /** disk used (bytes) */
+  du: number;
+  /** read (bytes/s) */
+  r: number;
+  /** write (bytes/s) */
+  w: number;
+  /** read max (bytes/s) */
+  rm: number;
+  /** write max (bytes/s) */
+  wm: number;
+  /** read (IOPS) */
+  rb: number;
+  /** write (IOPS) */
+  wb: number;
+  /** read max (IOPS) */
+  rbm: number;
+  /** write max (IOPS) */
+  wbm: number;
+}
+
+export interface BeszelGPUData {
+  /** GPU name/model */
+  n: string;
+  /** memory used (bytes) */
+  mu?: number;
+  /** memory total (bytes) */
+  mt?: number;
+  /** GPU utilization (%) */
+  u: number;
+  /** power draw (W) */
+  p?: number;
+  /** power peak (W) */
+  pp?: number;
+  /** encoder utilization keyed by engine name (%) */
+  e?: Record<string, number>;
+}
+
+export interface BeszelSystemStatsRecord {
+  id: string;
+  system: string;
+  stats: BeszelSystemStats;
+  type: string;
+  created: string;
+  updated: string;
+}
+
+export interface BeszelContainer {
+  id: string;
+  system: string;
+  name: string;
+  image: string;
+  status: string;
+  health: number;
+  cpu: number;
+  memory: number;
+  net: number;
+  ports?: string;
+  updated: number;
+}
+
+/**
+ * Per-container resource stats from Beszel agent.
+ * One entry per container in a BeszelContainerStatsRecord.
+ *
+ * Network fields: b (bandwidth) is preferred when available; fall back to ns/nr.
+ */
+export interface BeszelContainerStats {
+  /** container name */
+  n: string;
+  /** CPU usage (%) */
+  c: number;
+  /** memory usage (bytes) */
+  m: number;
+  /** network sent (bytes/s) — legacy, use b when available */
+  ns?: number;
+  /** network received (bytes/s) — legacy, use b when available */
+  nr?: number;
+  /** network bandwidth [sent, recv] (bytes/s) — preferred over ns/nr */
+  b?: [number, number];
+}
+
+export interface BeszelContainerStatsRecord {
+  id: string;
+  system: string;
+  stats: BeszelContainerStats[];
+  type: string;
+  created: string;
+  updated: string;
+}
+
+export interface BeszelSmartDevice {
+  id: string;
+  system: string;
+  name: string;
+  model: string;
+  state: string;
+  capacity: number;
+  temp: number;
+  firmware: string;
+  serial: string;
+  type: string;
+  hours: number;
+  cycles: number;
+  attributes: BeszelSmartAttribute[];
+  updated: string;
+}
+
+export interface BeszelSmartAttribute {
+  /** attribute ID */
+  id?: number;
+  /** attribute name */
+  n: string;
+  /** current value */
+  v: number;
+  /** worst value */
+  w?: number;
+  /** threshold */
+  t?: number;
+  /** raw value (numeric) */
+  rv?: number;
+  /** raw value (string) */
+  rs?: string;
+  /** when failed */
+  wf?: string;
+}
+
+export interface BeszelSystemdService {
+  id: string;
+  system: string;
+  name: string;
+  state: number;
+  sub: number;
+  cpu: number;
+  cpuPeak: number;
+  memory: number;
+  memPeak: number;
+  updated: number;
+}
+
+export interface BeszelAlert {
+  id: string;
+  user: string;
+  system: string;
+  name: string;
+  triggered: boolean;
+  value: number;
+  min: number;
+}
+
+export interface BeszelAlertHistory {
+  id: string;
+  alert: string;
+  user: string;
+  system: string;
+  name: string;
+  val: number;
+  created: string;
+  resolved?: string | null;
+}
+
+export interface CreateAlertInput {
+  name: string;
+  value: number;
+  min?: number;
+}
+
+export interface UpdateAlertInput {
+  value?: number;
+  min?: number;
+}
+
+export interface PocketBaseListResponse<T> {
+  page: number;
+  perPage: number;
+  totalItems: number;
+  totalPages: number;
+  items: T[];
+}
+
+/**
+ * Normalized view model for a Beszel-monitored system.
+ * Constructed by mapToSystemRow() in request-handler from BeszelSystem + BeszelSystemDetails.
+ * This is the shape consumed by grid/table widgets — all values are pre-scaled for display.
+ */
+export interface BeszelSystemRow {
+  id: string;
+  name: string;
+  status: BeszelSystemStatus;
+  /** CPU usage (%) */
+  cpu: number;
+  /** memory usage (%) */
+  memory: number;
+  /** disk usage (%) */
+  disk: number;
+  /** GPU usage (%) */
+  gpu: number;
+  /** load average [1m, 5m, 15m] */
+  loadAvg: [number, number, number] | null;
+  /** public interface bandwidth (bytes/s). From info.bb or info.b * 1M */
+  netBytes: number;
+  /** temperature (°C) */
+  temp: number | null;
+  /** battery [level%, charging state] */
+  battery: [number, number] | null;
+  /** running systemd services count */
+  services: number;
+  /** uptime (seconds) */
+  uptime: number;
+  agentVersion: string;
+  hostname: string;
+  cpuModel: string;
+  cores: number;
+  /** total memory (bytes) */
+  memoryTotal: number;
+  osName: string;
+}

packages/integrations/src/beszel/test/beszel-integration.spec.ts

@@ -0,0 +1,226 @@
+// @vitest-environment node
+import { beforeAll, describe, expect, test, vi } from "vitest";
+
+vi.hoisted(() => {
+  process.env.SKIP_ENV_VALIDATION = "true";
+  process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
+  process.env.ENABLE_DNS_CACHING = "false";
+});
+
+const BESZEL_URL = process.env.BESZEL_TEST_URL ?? "http://localhost:8090";
+const BESZEL_EMAIL = process.env.BESZEL_TEST_EMAIL ?? "";
+const BESZEL_PASSWORD = process.env.BESZEL_TEST_PASSWORD ?? "";
+
+vi.mock("@homarr/redis", () => ({
+  createGetSetChannel: () => ({
+    getAsync: vi.fn().mockResolvedValue(null),
+    setAsync: vi.fn().mockResolvedValue(undefined),
+    removeAsync: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+vi.mock("@homarr/core/infrastructure/logs", () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  }),
+  ErrorWithMetadata: class extends Error {},
+}));
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  fetchWithTrustedCertificatesAsync: (url: URL | string, init?: RequestInit) => fetch(url, init),
+  createAxiosCertificateInstanceAsync: vi.fn().mockResolvedValue({}),
+  createCertificateAgentAsync: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@homarr/core/infrastructure/certificates", () => ({
+  getTrustedCertificateHostnamesAsync: vi.fn().mockResolvedValue([]),
+  getAllTrustedCertificatesAsync: vi.fn().mockResolvedValue([]),
+}));
+
+import { BeszelIntegration } from "../beszel-integration";
+
+function createBeszelIntegration() {
+  return new BeszelIntegration({
+    id: "test-beszel",
+    name: "Test Beszel",
+    url: BESZEL_URL,
+    externalUrl: null,
+    decryptedSecrets: [
+      { kind: "username", value: BESZEL_EMAIL },
+      { kind: "password", value: BESZEL_PASSWORD },
+    ],
+  });
+}
+
+const shouldRun = BESZEL_EMAIL && BESZEL_PASSWORD;
+
+describe.skipIf(!shouldRun)("BeszelIntegration (real instance)", () => {
+  let integration: BeszelIntegration;
+  let systemId: string;
+
+  beforeAll(() => {
+    integration = createBeszelIntegration();
+  });
+
+  describe("getSystemsAsync", () => {
+    test("returns an array of systems", async () => {
+      const systems = await integration.getSystemsAsync();
+      expect(systems).toBeInstanceOf(Array);
+      expect(systems.length).toBeGreaterThan(0);
+    });
+
+    test("each system has required fields", async () => {
+      const systems = await integration.getSystemsAsync();
+      const system = systems[0];
+      if (!system) {
+        throw new Error("Expected at least one system");
+      }
+      systemId = system.id;
+
+      expect(system.id).toBeDefined();
+      expect(system.name).toBeDefined();
+      expect(system.status).toMatch(/^(up|down|paused|pending)$/);
+      expect(system.info).toBeDefined();
+      expect(typeof system.info.cpu).toBe("number");
+      expect(typeof system.info.mp).toBe("number");
+      expect(typeof system.info.dp).toBe("number");
+    });
+  });
+
+  describe("getSystemDetailsAsync", () => {
+    test("returns system details with hardware info", async () => {
+      const systems = await integration.getSystemsAsync();
+      systemId = systems[0]?.id ?? "";
+
+      const details = await integration.getSystemDetailsAsync(systemId);
+
+      expect(details.hostname).toBeDefined();
+      expect(details.cpu).toBeDefined();
+      expect(typeof details.cores).toBe("number");
+      expect(details.cores).toBeGreaterThan(0);
+      expect(typeof details.memory).toBe("number");
+      expect(details.memory).toBeGreaterThan(0);
+      expect(details.os_name).toBeDefined();
+    });
+  });
+
+  describe("getSystemStatsAsync", () => {
+    test("returns time-series stats records", async () => {
+      const systems = await integration.getSystemsAsync();
+      systemId = systems[0]?.id ?? "";
+
+      const stats = await integration.getSystemStatsAsync(systemId, "1m", 5);
+
+      expect(stats).toBeInstanceOf(Array);
+      if (stats.length === 0) return;
+
+      const record = stats[0];
+      expect(record?.stats).toBeDefined();
+      expect(typeof record?.stats.cpu).toBe("number");
+      expect(typeof record?.stats.mp).toBe("number");
+      expect(typeof record?.stats.dp).toBe("number");
+      expect(record?.created).toBeDefined();
+    });
+  });
+
+  describe("getContainersAsync", () => {
+    test("returns container list", async () => {
+      const systems = await integration.getSystemsAsync();
+      systemId = systems[0]?.id ?? "";
+
+      const containers = await integration.getContainersAsync(systemId);
+      expect(containers).toBeInstanceOf(Array);
+
+      if (containers.length > 0) {
+        const container = containers[0];
+        expect(container?.name).toBeDefined();
+        expect(container?.image).toBeDefined();
+        expect(container?.status).toBeDefined();
+        expect(typeof container?.cpu).toBe("number");
+        expect(typeof container?.memory).toBe("number");
+      }
+    });
+  });
+
+  describe("alert CRUD", () => {
+    let alertId: string;
+
+    test("creates an alert", async () => {
+      const systems = await integration.getSystemsAsync();
+      systemId = systems[0]?.id ?? "";
+
+      const alert = await integration.createAlertAsync(systemId, {
+        name: "CPU",
+        value: 90,
+        min: 1,
+      });
+
+      expect(alert.id).toBeDefined();
+      expect(alert.name).toBe("CPU");
+      expect(alert.value).toBe(90);
+      expect(alert.system).toBe(systemId);
+      alertId = alert.id;
+    });
+
+    test("lists alerts including the created one", async () => {
+      const alerts = await integration.getAlertsAsync(systemId);
+      const found = alerts.find((a) => a.id === alertId);
+      expect(found).toBeDefined();
+      expect(found?.name).toBe("CPU");
+    });
+
+    test("updates alert threshold", async () => {
+      const updated = await integration.updateAlertAsync(alertId, { value: 95 });
+      expect(updated.value).toBe(95);
+    });
+
+    test("deletes alert", async () => {
+      await integration.deleteAlertAsync(alertId);
+      const alerts = await integration.getAlertsAsync(systemId);
+      const found = alerts.find((a) => a.id === alertId);
+      expect(found).toBeUndefined();
+    });
+  });
+
+  describe("system actions", () => {
+    test("pauses and resumes a system", async () => {
+      const systems = await integration.getSystemsAsync();
+      systemId = systems[0]?.id ?? "";
+
+      await integration.pauseSystemAsync(systemId);
+      const afterPause = await integration.getSystemsAsync();
+      const paused = afterPause.find((s) => s.id === systemId);
+      expect(paused?.status).toBe("paused");
+
+      await integration.resumeSystemAsync(systemId);
+      const afterResume = await integration.getSystemsAsync();
+      const resumed = afterResume.find((s) => s.id === systemId);
+      expect(resumed?.status).toMatch(/^(up|pending)$/);
+    });
+  });
+
+  describe("authentication", () => {
+    test("authenticates with valid credentials", async () => {
+      const systems = await integration.getSystemsAsync();
+      expect(systems.length).toBeGreaterThan(0);
+    });
+
+    test("fails with invalid credentials", async () => {
+      const badIntegration = new BeszelIntegration({
+        id: "test-bad",
+        name: "Bad Beszel",
+        url: BESZEL_URL,
+        externalUrl: null,
+        decryptedSecrets: [
+          { kind: "username", value: "wrong@example.com" },
+          { kind: "password", value: "wrongpassword" },
+        ],
+      });
+
+      await expect(badIntegration.getSystemsAsync()).rejects.toThrow();
+    });
+  });
+});