@truenas/api-client 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1561 @@
+'use strict';
+
+var rxjs = require('rxjs');
+var webSocket = require('rxjs/webSocket');
+var operators = require('rxjs/operators');
+
+// src/factory.ts
+
+// src/enums/truenas-endpoint.enum.ts
+var TrueNasEndpoint = /* @__PURE__ */ ((TrueNasEndpoint2) => {
+  TrueNasEndpoint2["UpdateStatus"] = "update.status";
+  TrueNasEndpoint2["AppQuery"] = "app.query";
+  TrueNasEndpoint2["AppStart"] = "app.start";
+  TrueNasEndpoint2["AppStop"] = "app.stop";
+  TrueNasEndpoint2["AppRedeploy"] = "app.redeploy";
+  TrueNasEndpoint2["AppUpgrade"] = "app.upgrade";
+  TrueNasEndpoint2["CoreSubscribe"] = "core.subscribe";
+  TrueNasEndpoint2["ReplicationQuery"] = "replication.query";
+  TrueNasEndpoint2["ReplicationRun"] = "replication.run";
+  TrueNasEndpoint2["InterfaceQuery"] = "interface.query";
+  TrueNasEndpoint2["CloudBackupQuery"] = "cloud_backup.query";
+  TrueNasEndpoint2["CloudSyncQuery"] = "cloudsync.query";
+  TrueNasEndpoint2["VirtualInstanceQuery"] = "virt.instance.query";
+  TrueNasEndpoint2["VirtualInstanceStop"] = "virt.instance.stop";
+  TrueNasEndpoint2["VirtualInstanceStart"] = "virt.instance.start";
+  TrueNasEndpoint2["VirtualInstanceRestart"] = "virt.instance.restart";
+  TrueNasEndpoint2["ContainerQuery"] = "container.query";
+  TrueNasEndpoint2["ContainerStart"] = "container.start";
+  TrueNasEndpoint2["ContainerStop"] = "container.stop";
+  TrueNasEndpoint2["VmQuery"] = "vm.query";
+  TrueNasEndpoint2["VmStart"] = "vm.start";
+  TrueNasEndpoint2["VmStop"] = "vm.stop";
+  TrueNasEndpoint2["VmRestart"] = "vm.restart";
+  TrueNasEndpoint2["CoreDownload"] = "core.download";
+  TrueNasEndpoint2["CoreGetJobs"] = "core.get_jobs";
+  TrueNasEndpoint2["SystemInfo"] = "system.info";
+  TrueNasEndpoint2["SystemProductType"] = "system.product_type";
+  TrueNasEndpoint2["ExtendedSystemInfo"] = "webui.main.dashboard.sys_info";
+  TrueNasEndpoint2["DiskQuery"] = "disk.query";
+  TrueNasEndpoint2["DeviceGetInfo"] = "device.get_info";
+  TrueNasEndpoint2["CorePing"] = "core.ping";
+  TrueNasEndpoint2["GenerateToken"] = "auth.generate_token";
+  TrueNasEndpoint2["AlertList"] = "alert.list";
+  TrueNasEndpoint2["AuthLogin"] = "auth.login_ex";
+  TrueNasEndpoint2["AuthLogout"] = "auth.logout";
+  TrueNasEndpoint2["ApiKeyQuery"] = "api_key.query";
+  TrueNasEndpoint2["ApiKeyCreate"] = "api_key.create";
+  TrueNasEndpoint2["ApiKeyDelete"] = "api_key.delete";
+  TrueNasEndpoint2["FailOverStatus"] = "failover.status";
+  TrueNasEndpoint2["FailOverNode"] = "failover.node";
+  TrueNasEndpoint2["FailOverDisabledReasons"] = "failover.disabled.reasons";
+  TrueNasEndpoint2["PoolQuery"] = "pool.query";
+  TrueNasEndpoint2["DatasetQuery"] = "pool.dataset.query";
+  TrueNasEndpoint2["DatasetCreate"] = "pool.dataset.create";
+  TrueNasEndpoint2["DatasetDelete"] = "pool.dataset.delete";
+  TrueNasEndpoint2["SnapshotTaskCreate"] = "pool.snapshottask.create";
+  TrueNasEndpoint2["SnapshotTaskQuery"] = "pool.snapshottask.query";
+  TrueNasEndpoint2["SnapshotTaskDelete"] = "pool.snapshottask.delete";
+  TrueNasEndpoint2["SnapshotCreate"] = "pool.snapshot.create";
+  TrueNasEndpoint2["SnapshotDelete"] = "pool.snapshot.delete";
+  TrueNasEndpoint2["ReplicationCountEligibleSnapshots"] = "replication.count_eligible_manual_snapshots";
+  TrueNasEndpoint2["BootGetState"] = "boot.get_state";
+  TrueNasEndpoint2["TnConnectUpdate"] = "tn_connect.update";
+  TrueNasEndpoint2["HardwareVirtualizationVariant"] = "hardware.virtualization.variant";
+  TrueNasEndpoint2["KeychainCredentialGenerateSshKeyPair"] = "keychaincredential.generate_ssh_key_pair";
+  TrueNasEndpoint2["KeychainCredentialCreate"] = "keychaincredential.create";
+  TrueNasEndpoint2["KeychainCredentialRemoteSshHostKeyScan"] = "keychaincredential.remote_ssh_host_key_scan";
+  TrueNasEndpoint2["KeychainCredentialDelete"] = "keychaincredential.delete";
+  TrueNasEndpoint2["ReplicationCreate"] = "replication.create";
+  TrueNasEndpoint2["UserQuery"] = "user.query";
+  TrueNasEndpoint2["UserUpdate"] = "user.update";
+  TrueNasEndpoint2["NetworkConfiguration"] = "network.configuration.config";
+  TrueNasEndpoint2["ServiceQuery"] = "service.query";
+  TrueNasEndpoint2["ServiceUpdate"] = "service.update";
+  TrueNasEndpoint2["ServiceControl"] = "service.control";
+  return TrueNasEndpoint2;
+})(TrueNasEndpoint || {});
+
+// src/types/api-error.type.ts
+function isJsonRpcError(error) {
+  return typeof error === "object" && error !== null && "message" in error && typeof error.message === "string";
+}
+function isTrueNasError(error) {
+  return typeof error === "object" && error !== null && "reason" in error && typeof error.reason === "string";
+}
+function getApiErrorMessage(error, fallback = "API call failed") {
+  if (isJsonRpcError(error) && error.data && isTrueNasError(error.data)) {
+    return error.data.reason;
+  }
+  if (isTrueNasError(error)) {
+    return error.reason;
+  }
+  if (isJsonRpcError(error)) {
+    return error.message;
+  }
+  return fallback;
+}
+
+// src/types/job.type.ts
+var JobState = /* @__PURE__ */ ((JobState2) => {
+  JobState2["Pending"] = "PENDING";
+  JobState2["Running"] = "RUNNING";
+  JobState2["Hold"] = "HOLD";
+  JobState2["Error"] = "ERROR";
+  JobState2["Failed"] = "FAILED";
+  JobState2["Aborted"] = "ABORTED";
+  JobState2["Success"] = "SUCCESS";
+  JobState2["Finished"] = "FINISHED";
+  JobState2["Locked"] = "LOCKED";
+  JobState2["Waiting"] = "WAITING";
+  return JobState2;
+})(JobState || {});
+var withId = (id) => rxjs.filter((msg) => msg.id === id);
+function randomUUID() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto === "undefined" || typeof crypto.getRandomValues !== "function") {
+    throw new Error("Web Crypto API unavailable: cannot generate a UUID");
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = crypto.getRandomValues(new Uint8Array(1))[0] % 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+
+// src/utils/jsonrpc.utils.ts
+function createJsonRpcMessage(method, params) {
+  return {
+    jsonrpc: "2.0",
+    id: randomUUID(),
+    method,
+    params: params ?? []
+  };
+}
+
+// src/api/truenas-api.ts
+var TrueNasApi = class {
+  constructor(authenticated, connection) {
+    this.authenticated = authenticated;
+    this.connection = connection;
+    /**
+     * Stream of job events from websocket.
+     * JSON-RPC 2.0 events have structure: { method: 'collection_update', params: { collection, fields, ... } }
+     */
+    this.jobEvents = this.connection.messages().pipe(
+      rxjs.filter(
+        (res) => res.method === "collection_update" && res.params?.collection === "core.get_jobs"
+      ),
+      rxjs.map((event) => event.params.fields),
+      rxjs.filter((job) => !!job?.id),
+      rxjs.share()
+    );
+    this.initializeJobEventsSubscription();
+  }
+  call(method, params) {
+    const message = createJsonRpcMessage(method, params);
+    this.connection.ws.next(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(msg.error, "API call failed");
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      rxjs.take(1)
+    );
+  }
+  /**
+   * Makes an API call and returns the job ID from the websocket event.
+   * Used for v26 where API calls return null but job events contain the job ID.
+   *
+   * The job ID is extracted from the first job event where message_ids contains
+   * the original request ID.
+   *
+   * @param method The API method to call
+   * @param params The parameters for the API call
+   * @returns Observable that emits the job ID when received from websocket events
+   */
+  callAndGetJobId(method, params) {
+    const message = createJsonRpcMessage(method, params);
+    this.connection.ws.next(message);
+    const requestId = message.id ?? "";
+    return this.jobEvents.pipe(
+      rxjs.filter((job) => job.message_ids?.includes(requestId) ?? false),
+      rxjs.map((job) => job.id),
+      rxjs.take(1)
+    );
+  }
+  events(eventName) {
+    this.authenticated.pipe(rxjs.filter(Boolean), rxjs.take(1)).subscribe(() => {
+      const message = createJsonRpcMessage("core.subscribe", [eventName]);
+      this.connection.ws.next(message);
+    });
+    return this.connection.messages().pipe(
+      rxjs.filter((res) => {
+        const params = res.params;
+        return res.method === "collection_update" && params?.collection === eventName && ["added", "changed", "removed"].includes(params?.msg || "") && params.fields !== void 0;
+      })
+    );
+  }
+  /**
+   * Convenience wrapper for auth.generate_token API call.
+   */
+  generateToken(ttl = 600, matchOrigin = false, singleUse = true) {
+    return this.call("auth.generate_token" /* GenerateToken */, [
+      ttl,
+      {},
+      matchOrigin,
+      singleUse
+    ]);
+  }
+  trackJob(jobId) {
+    const completedStates = [
+      "SUCCESS" /* Success */,
+      "FAILED" /* Failed */,
+      "ABORTED" /* Aborted */,
+      "ERROR" /* Error */,
+      "FINISHED" /* Finished */
+    ];
+    const currentJobState$ = this.call("core.get_jobs", [
+      [["id", "=", jobId]]
+    ]).pipe(
+      rxjs.map((jobs) => jobs[0]),
+      rxjs.filter((job) => job !== void 0)
+    );
+    const jobUpdates$ = this.jobEvents.pipe(
+      rxjs.filter((job) => job.id === jobId),
+      rxjs.takeWhile((job) => !completedStates.includes(job.state), true)
+      // Include the final state
+    );
+    return currentJobState$.pipe(
+      rxjs.switchMap((currentJob) => {
+        if (completedStates.includes(currentJob.state)) {
+          return rxjs.of(currentJob);
+        }
+        return rxjs.merge(rxjs.of(currentJob), jobUpdates$);
+      })
+    );
+  }
+  initializeJobEventsSubscription() {
+    this.authenticated.pipe(rxjs.filter(Boolean), rxjs.take(1)).subscribe(() => {
+      const message = createJsonRpcMessage("core.subscribe", ["core.get_jobs"]);
+      this.connection.ws.next(message);
+    });
+  }
+};
+
+// src/enums/truenas-auth-mechanism.enum.ts
+var TrueNasAuthMechanism = /* @__PURE__ */ ((TrueNasAuthMechanism2) => {
+  TrueNasAuthMechanism2["ApiKey"] = "API_KEY_PLAIN";
+  TrueNasAuthMechanism2["Password"] = "PASSWORD_PLAIN";
+  TrueNasAuthMechanism2["Otp"] = "OTP_TOKEN";
+  TrueNasAuthMechanism2["Token"] = "TOKEN_PLAIN";
+  return TrueNasAuthMechanism2;
+})(TrueNasAuthMechanism || {});
+
+// src/errors/auth.errors.ts
+var AuthErrorCode = /* @__PURE__ */ ((AuthErrorCode2) => {
+  AuthErrorCode2["PasswordAuthFailed"] = "PASSWORD_AUTH_FAILED";
+  AuthErrorCode2["OtpAuthFailed"] = "OTP_AUTH_FAILED";
+  AuthErrorCode2["ApiKeyAuthFailed"] = "API_KEY_AUTH_FAILED";
+  AuthErrorCode2["FullAdminRequired"] = "FULL_ADMIN_REQUIRED";
+  return AuthErrorCode2;
+})(AuthErrorCode || {});
+var AuthError = class _AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+
+// src/auth/truenas-authenticator.ts
+var throwOnAuthenticationFailure = (code, message) => rxjs.switchMap((response) => {
+  if (response.response_type === "AUTH_ERR" /* AuthErr */) {
+    return rxjs.throwError(() => new AuthError(code, message));
+  }
+  return rxjs.of(response);
+});
+var TrueNasAuthenticator = class _TrueNasAuthenticator {
+  constructor(connection) {
+    this.connection = connection;
+    // in seconds (5 minutes)
+    /**
+     * whether or not the system is currently authenticated and accessible.
+     * this is a `BehaviorSubject` instead of a signal, since we use its `getValue` method
+     * throughout a lot of the codebase.
+     */
+    this.authenticated$ = new rxjs.BehaviorSubject(false);
+    /**
+     * `true` when the system is currently being authenticated to, and `false` otherwise.
+     * does not indicate whatsoever if authentication is successful or not, just whether the process
+     * is ongoing.
+     */
+    this.authenticating$ = new rxjs.BehaviorSubject(false);
+    this.credentials = { username: "", password: "", key: "" };
+    this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
+    this.connection.opened.pipe(
+      rxjs.filter(
+        (isOpen) => !!(isOpen && this.credentials?.username && (this.credentials.password || this.credentials.key))
+      ),
+      rxjs.switchMap(() => {
+        if (this.credentials.password) {
+          return this.loginWithUserPass(
+            this.credentials.username,
+            this.credentials.password
+          );
+        }
+        return this.loginWithApiKey({
+          username: this.credentials.username,
+          key: this.credentials.key
+        });
+      })
+    ).subscribe();
+    connection.closed.subscribe(() => {
+      this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
+      this.authenticated$.next(false);
+    });
+  }
+  static {
+    this.DefaultSessionLifetime = 300;
+  }
+  loginWithUserPass(username, password) {
+    const message = createJsonRpcMessage("auth.login_ex", [
+      {
+        mechanism: "PASSWORD_PLAIN" /* Password */,
+        username,
+        password
+      }
+    ]);
+    this.authenticating$.next(true);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Authentication failed"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      throwOnAuthenticationFailure(
+        "PASSWORD_AUTH_FAILED" /* PasswordAuthFailed */,
+        "TrueNAS authentication failed. Please verify your TrueNAS user credentials and try again."
+      ),
+      rxjs.tap((res) => {
+        if (res.response_type === "SUCCESS" /* Success */) {
+          if (res.user_info?.privilege.roles.$set.includes("FULL_ADMIN" /* FullAdmin */)) {
+            this.credentials.username = username;
+            this.credentials.password = password;
+            this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
+            this.authenticated$.next(true);
+          } else {
+            this.logout();
+            this.authenticated$.next(false);
+            throw new AuthError(
+              "FULL_ADMIN_REQUIRED" /* FullAdminRequired */,
+              "User account must have full admin privileges"
+            );
+          }
+        }
+      }),
+      rxjs.finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      rxjs.take(1)
+    );
+  }
+  loginWithOtp(code) {
+    const message = createJsonRpcMessage("auth.login_ex", [
+      {
+        mechanism: "OTP_TOKEN" /* Otp */,
+        otp_token: code
+      }
+    ]);
+    this.authenticating$.next(true);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Authentication failed"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      rxjs.tap((res) => {
+        if (res?.response_type === "SUCCESS" /* Success */) {
+          this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
+          this.authenticated$.next(true);
+        }
+      }),
+      throwOnAuthenticationFailure(
+        "OTP_AUTH_FAILED" /* OtpAuthFailed */,
+        "TrueNAS authentication failed. Please verify your one-time passcode and try again."
+      ),
+      rxjs.finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      rxjs.take(1)
+    );
+  }
+  loginWithApiKey(credentials) {
+    const { username, key } = credentials;
+    const message = createJsonRpcMessage("auth.login_ex", [
+      {
+        mechanism: "API_KEY_PLAIN" /* ApiKey */,
+        username,
+        api_key: key
+      }
+    ]);
+    this.authenticating$.next(true);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Authentication failed"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      throwOnAuthenticationFailure(
+        "API_KEY_AUTH_FAILED" /* ApiKeyAuthFailed */,
+        "TrueNAS authentication failed. Has the TrueNAS Connect API key been removed from your TrueNAS server?"
+      ),
+      rxjs.tap((res) => {
+        this.credentials.username = username;
+        this.credentials.key = key;
+        this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
+        this.authenticated$.next(true);
+      }),
+      rxjs.finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      rxjs.take(1)
+    );
+  }
+  newApiKey(username) {
+    const message = createJsonRpcMessage("api_key.create", [
+      { name: `tnc-${randomUUID()}`, username }
+    ]);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Failed to create API key"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      rxjs.take(1)
+    );
+  }
+  logout() {
+    const message = createJsonRpcMessage("auth.logout");
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      rxjs.map((msg) => {
+        if (msg.error) {
+          return false;
+        }
+        return msg.result;
+      }),
+      rxjs.tap((success) => {
+        this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
+        this.authenticated$.next(!success);
+      }),
+      rxjs.take(1)
+    );
+  }
+};
+
+// src/logger.ts
+var consoleLogger = {
+  trace: (message, ...args) => console.trace(message, ...args),
+  debug: (message, ...args) => console.debug(message, ...args),
+  info: (message, ...args) => console.info(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+var noop = () => void 0;
+var noopLogger = {
+  trace: noop,
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop
+};
+
+// src/utils/truenas-connection.utils.ts
+function isHttpStatusError(reason) {
+  return ["404", "502", "503"].some((code) => reason.includes(code));
+}
+function getHttpError(reason) {
+  if (reason.includes("404")) {
+    return "API endpoint not found - System may not support versioned API";
+  }
+  if (reason.includes("502")) {
+    return "Bad Gateway - System may be starting up";
+  }
+  if (reason.includes("503")) {
+    return "Service Unavailable - System may be overloaded";
+  }
+  return "";
+}
+function getWebSocketError(code) {
+  switch (code) {
+    case 1e3:
+      return "Connection closed normally";
+    case 1001:
+      return "Server is shutting down or restarting";
+    case 1002:
+      return "Protocol error - Invalid WebSocket communication";
+    case 1003:
+      return "Unsupported data format received";
+    case 1006:
+      return "Connection lost unexpectedly - Check network connectivity";
+    case 1007:
+      return "Invalid data received from server";
+    case 1008:
+      return "Connection terminated due to policy violation";
+    case 1009:
+      return "Message size exceeded server limits";
+    case 1011:
+      return "Server encountered an internal error";
+    case 1012:
+      return "Service is restarting";
+    case 1013:
+      return "Server temporarily overloaded - Try again later";
+    case 1015:
+      return "TLS/Certificate error - Certificate may be expired";
+    default:
+      return "Network connection failed - Check IP address and connectivity";
+  }
+}
+var TrueNasSocket = class {
+  constructor(config) {
+    this.config = config;
+    this.socket = webSocket.webSocket(this.config);
+  }
+  messages() {
+    return this.socket;
+  }
+  next(msg) {
+    this.socket.next(msg);
+  }
+  complete() {
+    this.socket.complete();
+  }
+};
+
+// src/connection/truenas-connection.ts
+var tenSeconds = 10 * 1e3;
+var twentySeconds = 20 * 1e3;
+var TrueNasConnection = class {
+  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger) {
+    this.hostnames = hostnames;
+    this.systemUuid = systemUuid;
+    this.websocketPath = websocketPath;
+    this.systemName = systemName;
+    this.retryDelay = retryDelay;
+    this.maxRetry = maxRetry;
+    this.logger = logger;
+    // compatibility properties
+    this.opened = new rxjs.BehaviorSubject(false);
+    this.closed = new rxjs.Subject();
+    this.hostname = new rxjs.BehaviorSubject("");
+    this.connectionAttempts = new rxjs.BehaviorSubject(0);
+    this.lastErrorMessage = new rxjs.BehaviorSubject(null);
+    /**
+     * emits when the connection is manually closed.
+     */
+    this.closeConnection = new rxjs.Subject();
+    /**
+     * the connection only establishes a socket while this gate is `true`. consumers
+     * flip it via `setEnabled()` (the app maps `SystemState.Active -> true`).
+     */
+    this.enabled$ = new rxjs.BehaviorSubject(false);
+    /**
+     * observable which emits the current gate value and only emits again when it changes.
+     */
+    this.enabledChange$ = this.enabled$.pipe(rxjs.distinctUntilChanged());
+    /**
+     * observable that handles the entire connection lifecycle.
+     */
+    this.connection$ = this.enabledChange$.pipe(
+      rxjs.switchMap((enabled) => {
+        if (enabled) {
+          return this.connect().pipe(
+            rxjs.map((conn) => makeActiveConnection(conn.ws, conn.hostname))
+          );
+        }
+        return rxjs.of(closedConnection);
+      }),
+      rxjs.switchMap((connection) => {
+        if (connection.state !== "active") {
+          return rxjs.of(connection);
+        }
+        const initMessage = createJsonRpcMessage("core.set_options", [
+          { legacy_jobs: false }
+        ]);
+        connection.ws.next(initMessage);
+        return connection.ws.messages().pipe(
+          rxjs.filter((msg) => msg.id === initMessage.id),
+          rxjs.take(1),
+          rxjs.map(() => connection)
+        );
+      }),
+      // in the event of an error, do two things:
+      //   1. emit an errored connection downstream to inform consumers that
+      //      the connection is dead.
+      //   2. re-throw an error so the downstream `retry` will re-subscribe.
+      rxjs.catchError((err) => {
+        this.logger.error("All connections failed - retrying", { message: err?.message, hostname: err?.hostname });
+        return rxjs.concat(
+          rxjs.of(makeConnectionError(err.message, err.hostname)),
+          // since this error will immediately get caught by `retry` there's no reason to build a real error.
+          rxjs.throwError(() => null)
+        );
+      }),
+      rxjs.retry(),
+      // start with a closed connection.
+      rxjs.startWith(closedConnection),
+      // prevent multiple subscriptions from re-evaluating the entire pipeline.
+      rxjs.shareReplay({ bufferSize: 1, refCount: false }),
+      rxjs.takeUntil(this.closeConnection)
+    );
+    /**
+     * observable which is either an instance of the current `TrueNasSocket` used for the connection
+     * or `null` if the connection is closed or errored for any reason.
+     */
+    this.ws$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state === "active" ? conn.ws : null)
+    );
+    /**
+     * current hostname we used to build the URL for this connection.
+     */
+    this.hostname$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state === "active" ? conn.hostname : null)
+    );
+    /**
+     * emits error messages from the connection pipeline. this is used to derive the
+     * corresponding compatibility property.
+     */
+    this.lastErrorMessage$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state === "error" ? conn.message : null)
+    );
+    /**
+     * emits when the connection state *changes*, so it'll never emit `true` twice
+     * in a row nor `false` twice in a row.
+     */
+    this.opened$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state),
+      rxjs.distinctUntilChanged(),
+      rxjs.map((state) => state === "active")
+    );
+    /**
+     * emits when the connection state goes from open to closed.
+     */
+    this.closed$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state),
+      rxjs.distinctUntilChanged(),
+      rxjs.filter((state) => state === "closed" || state === "error"),
+      rxjs.map(() => {
+      })
+    );
+    /**
+     * whether to display a connection error to the user — the **live** signal.
+     *
+     * `true` only while `connection$` is currently a `ConnectionError`, meaning the entire race +
+     * retry cycle has been exhausted for all hostnames right now; it flips back to `false` once a
+     * connection is re-established. individual socket losses during a race are expected and not surfaced.
+     *
+     * NOTE: this is NOT the same as the `hasExhaustedRetries()` method, which is a **cumulative**
+     * snapshot (see there). The two can disagree — prefer this observable for "is the connection
+     * errored right now?".
+     */
+    this.hasConnectionError$ = this.connection$.pipe(
+      rxjs.map((conn) => conn.state === "error"),
+      rxjs.takeUntil(this.closeConnection)
+    );
+    /**
+     * observable which always emits messages from the current socket.
+     */
+    this.messages$ = this.ws$.pipe(
+      rxjs.filter((ws) => ws !== null),
+      rxjs.switchMap((ws) => ws.messages())
+    );
+    rxjs.combineLatest([
+      rxjs.interval(twentySeconds),
+      this.ws$
+    ]).pipe(
+      rxjs.takeUntil(this.closeConnection)
+    ).subscribe(([, ws]) => {
+      if (ws) {
+        const pingMessage = createJsonRpcMessage("core.ping");
+        ws.next(pingMessage);
+      }
+    });
+    this.opened$.subscribe((val) => this.opened.next(val));
+    this.closed$.subscribe(() => this.closed.next());
+    this.hostname$.pipe(rxjs.filter(Boolean)).subscribe((name) => this.hostname.next(name));
+    this.ws$.pipe(rxjs.filter(Boolean)).subscribe((ws) => this.ws = ws);
+    this.lastErrorMessage$.subscribe((msg) => this.lastErrorMessage.next(msg));
+    this.enabled$.next(initialEnabled);
+  }
+  /**
+   * whether the connection has exhausted its retries — the **cumulative** snapshot, read
+   * synchronously. (Formerly `hasConnectionError()`; renamed to disambiguate it from the
+   * live `hasConnectionError$` observable, with which it can disagree.)
+   *
+   * `true` when the lifetime `connectionAttempts` count exceeds `hostnames.length * maxRetry`,
+   * OR when an error message is currently set. Ported from the source (tncui) behavior.
+   *
+   * CAVEAT (pre-existing tncui behavior, preserved here): `connectionAttempts` only ever grows —
+   * it is never reset on a successful (re)connection — so over a long-lived connection with
+   * reconnect churn this can latch to `true` even while the connection is currently healthy. For
+   * "is it errored right now?" use the live `hasConnectionError$` observable instead.
+   */
+  hasExhaustedRetries() {
+    const attemptsExhausted = this.connectionAttempts.value > this.hostnames.length * this.maxRetry;
+    const hasErrorMessage = this.lastErrorMessage.value !== null;
+    return attemptsExhausted || hasErrorMessage;
+  }
+  /**
+   * enables or disables the connection gate. the app calls this when its `SystemState`
+   * changes (mapping `SystemState.Active -> true`, everything else -> `false`).
+   */
+  setEnabled(enabled) {
+    this.enabled$.next(enabled);
+  }
+  /**
+   * compatibility method which just returns the public `messages$` observable.
+   * this is used in a few places in the codebase that relied upon the old implementation.
+   */
+  messages() {
+    return this.messages$;
+  }
+  /**
+   * sends a message over the current websocket OR queues it to send once
+   * the next websocket is opened. messages sent via `send` will not be lost until after
+   * the next `closed$` emission.
+   */
+  send(message) {
+    return this.ws$.pipe(
+      rxjs.filter((ws) => ws !== null),
+      rxjs.take(1)
+    ).subscribe((ws) => ws.next(message));
+  }
+  /**
+   * manually closes this connection and prevents it from retrying/opening any more.
+   */
+  close() {
+    this.closeConnection.next();
+    this.closeConnection.complete();
+  }
+  /**
+   * helper method which creates an `Observable` which emits an `ActiveConnection`
+   * after it establishes a connection to the given hostname. the observable will emit an
+   * error if the connection is never established and will not complete until unsubscribed from or closed.
+   */
+  createSocket(hostname) {
+    const url = `wss://${hostname}${this.websocketPath}`;
+    return new rxjs.Observable((subscriber) => {
+      const ws = new TrueNasSocket({
+        url,
+        openObserver: {
+          next: () => {
+            subscriber.next({ ws, hostname });
+          }
+        },
+        closeObserver: {
+          next: (event) => {
+            const reason = event.reason || "";
+            let errorMessage;
+            if (isHttpStatusError(reason)) {
+              errorMessage = getHttpError(reason);
+            } else {
+              errorMessage = getWebSocketError(event.code);
+            }
+            this.connectionAttempts.next(this.connectionAttempts.value + 1);
+            subscriber.error(makeConnectionError(errorMessage, hostname));
+          }
+        }
+      });
+      const startupSub = ws.socket.subscribe({
+        error: () => {
+        }
+      });
+      return () => {
+        startupSub.unsubscribe();
+        ws.complete();
+      };
+    }).pipe(
+      // retry logic:
+      //   * if a connection is not established in 10 seconds, consider that an error
+      rxjs.timeout({ first: tenSeconds }),
+      //   * if an error happens, wait `retryDelay` before trying again.
+      //     after `maxRetry` retries, give up.
+      rxjs.retry({ count: this.maxRetry, delay: this.retryDelay })
+    );
+  }
+  /**
+   * helper function which actually performs the parallel connection `race`.
+   */
+  connect() {
+    return rxjs.race(
+      this.hostnames.map(this.createSocket.bind(this))
+    ).pipe(
+      rxjs.tap((conn) => this.logger.debug(`TrueNas socket opened to ${conn.hostname}.`)),
+      rxjs.takeUntil(this.closeConnection)
+    );
+  }
+};
+var makeActiveConnection = (ws, hostname) => ({
+  ws,
+  hostname,
+  state: "active"
+});
+var makeConnectionError = (message, hostname) => ({
+  name: "ConnectionError",
+  message,
+  hostname,
+  state: "error"
+});
+var closedConnection = { state: "closed" };
+
+// src/config/api-version.config.ts
+var apiVersionConfig = {
+  /**
+   * Minimum supported API version.
+   * Systems with older API versions will be rejected.
+   */
+  MIN_SUPPORTED_VERSION: "v25.10.0",
+  /**
+   * Maximum supported API version.
+   * Systems with newer API versions will be rejected.
+   */
+  MAX_SUPPORTED_VERSION: "v26.0.0",
+  /**
+   * Fallback version to use when version discovery fails due to CORS/network errors.
+   * When /api/versions returns HTTP status 0 (CORS block, network down, etc.),
+   * the system will attempt to connect using this version as a best-effort fallback.
+   *
+   * WARNING: Status 0 errors have multiple causes:
+   * - CORS policy blocking the request
+   * - Network disconnected
+   * - DNS lookup failure
+   * - Server unreachable
+   *
+   * Using this fallback means systems with genuine network issues will still
+   * attempt connection (and fail during WebSocket handshake instead of immediately).
+   */
+  FALLBACK_VERSION: "v25.10.0"
+};
+
+// src/types/api-version.type.ts
+var VersionCompatibility = /* @__PURE__ */ ((VersionCompatibility2) => {
+  VersionCompatibility2["Compatible"] = "compatible";
+  VersionCompatibility2["TooOld"] = "too-old";
+  VersionCompatibility2["TooNew"] = "too-new";
+  VersionCompatibility2["Invalid"] = "invalid";
+  return VersionCompatibility2;
+})(VersionCompatibility || {});
+
+// src/utils/api-version.utils.ts
+var legacyCutoffYear = 25;
+function parseApiVersion(versionString) {
+  const regex = /^v(\d{2})\.(\d+)\.(\d+)$/;
+  const match = versionString.match(regex);
+  if (!match) {
+    return null;
+  }
+  const [, yearStr, minorStr, patchStr] = match;
+  const year = parseInt(yearStr, 10);
+  const minor = parseInt(minorStr, 10);
+  const patch = parseInt(patchStr, 10);
+  if (year <= legacyCutoffYear) {
+    if (minor < 1 || minor > 12) {
+      return null;
+    }
+  } else if (year >= 26) {
+    if (minor < 0 || minor > 99) {
+      return null;
+    }
+  }
+  return {
+    version: versionString,
+    year,
+    minor,
+    patch,
+    websocketPath: `/api/${versionString}`
+  };
+}
+function compareVersions(a, b) {
+  if (a.year !== b.year) {
+    return a.year - b.year;
+  }
+  if (a.minor !== b.minor) {
+    return a.minor - b.minor;
+  }
+  return a.patch - b.patch;
+}
+function checkVersionCompatibility(version) {
+  const minVersion = parseApiVersion(apiVersionConfig.MIN_SUPPORTED_VERSION);
+  const maxVersion = parseApiVersion(apiVersionConfig.MAX_SUPPORTED_VERSION);
+  if (!minVersion || !maxVersion) {
+    return "invalid" /* Invalid */;
+  }
+  if (compareVersions(version, minVersion) < 0) {
+    return "too-old" /* TooOld */;
+  }
+  if (compareVersions(version, maxVersion) > 0) {
+    return "too-new" /* TooNew */;
+  }
+  return "compatible" /* Compatible */;
+}
+function isVersionSupported(version) {
+  return checkVersionCompatibility(version) === "compatible" /* Compatible */;
+}
+function filterCompatibleVersions(versions) {
+  return versions.filter(isVersionSupported);
+}
+function getWebSocketPath(version) {
+  return version.websocketPath;
+}
+
+// src/client/truenas-api-client.ts
+var TrueNasApiClient = class {
+  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger) {
+    this.uuid = uuid;
+    this.hostnames = hostnames;
+    this.version = version;
+    this.enabled = enabled;
+    this.systemName = systemName;
+    this.logger = logger;
+    this.connection = this.createConnection();
+    this.authenticator = this.createAuthenticator();
+    this.api = this.createApi();
+    this.ops = this.createOperations();
+  }
+  /**
+   * Get current connection status.
+   * @returns true if WebSocket is connected
+   */
+  get connected() {
+    return this.connection.opened.getValue();
+  }
+  /**
+   * Get current authentication status.
+   * @returns true if authenticated with the system
+   */
+  get authenticated() {
+    return this.authenticator.authenticated$.getValue();
+  }
+  /**
+   * Close the WebSocket connection.
+   * Connection will automatically retry if retry is enabled.
+   */
+  close() {
+    this.connection.close();
+  }
+  /**
+   * Factory method to create the WebSocket connection.
+   * Override in subclasses to provide version-specific connection handling.
+   */
+  createConnection() {
+    const websocketPath = getWebSocketPath(this.version);
+    return new TrueNasConnection(
+      this.enabled,
+      this.hostnames,
+      this.uuid,
+      websocketPath,
+      this.systemName,
+      void 0,
+      // retryDelay (use default)
+      void 0,
+      // maxRetry (use default)
+      this.logger
+    );
+  }
+  /**
+   * Factory method to create the API handler.
+   * Override in subclasses to provide version-specific API implementations.
+   */
+  createApi() {
+    return new TrueNasApi(this.authenticator.authenticated$, this.connection);
+  }
+  /**
+   * Factory method to create the authenticator.
+   * Override in subclasses to provide version-specific authentication.
+   */
+  createAuthenticator() {
+    return new TrueNasAuthenticator(this.connection);
+  }
+};
+
+// src/client/truenas-api-client-v25-10.ts
+var TrueNasApiClientV2510 = class extends TrueNasApiClient {
+  /**
+   * Create v25.10-specific operation mappings
+   *
+   * virt.instance.* APIs return boolean (true) but emit job events via websocket.
+   * We use callAndGetJobId to capture the job ID, then track the job.
+   * All operations emit Job updates until the operation completes.
+   */
+  createOperations() {
+    return {
+      containerQuery: () => this.api.call("virt.instance.query" /* VirtualInstanceQuery */, [
+        [["type", "=", "CONTAINER" /* Container */]]
+      ]).pipe(rxjs.map((instances) => instances.map(this.toContainer))),
+      containerStart: (id) => this.api.callAndGetJobId("virt.instance.start" /* VirtualInstanceStart */, [id]).pipe(rxjs.switchMap((jobId) => this.api.trackJob(jobId))),
+      containerStop: (id, options) => this.api.callAndGetJobId("virt.instance.stop" /* VirtualInstanceStop */, [id, options]).pipe(rxjs.switchMap((jobId) => this.api.trackJob(jobId))),
+      containerRestart: (id, options) => this.api.callAndGetJobId("virt.instance.restart" /* VirtualInstanceRestart */, [
+        id,
+        options
+      ]).pipe(rxjs.switchMap((jobId) => this.api.trackJob(jobId)))
+    };
+  }
+  /**
+   * Transform VirtualInstanceQuery to unified Container type
+   */
+  toContainer(instance) {
+    return {
+      id: instance.id,
+      name: instance.name,
+      status: instance.status,
+      autostart: instance.autostart,
+      cpu: instance.cpu,
+      memory: instance.memory,
+      image: instance.image
+    };
+  }
+};
+var TrueNasApiClientV26 = class _TrueNasApiClientV26 extends TrueNasApiClient {
+  /**
+   * Map v26 status state string to AppState enum
+   */
+  static mapStatus(state) {
+    switch (state.toUpperCase()) {
+      case "RUNNING":
+        return "RUNNING" /* Running */;
+      case "STOPPED":
+        return "STOPPED" /* Stopped */;
+      case "STOPPING":
+        return "STOPPING" /* Stopping */;
+      default:
+        return "STOPPED" /* Stopped */;
+    }
+  }
+  /**
+   * Create v26-specific operation mappings
+   *
+   * Operations return Observable<Job | null>:
+   * - Async operations emit Job updates until complete
+   * - Sync operations emit null once
+   */
+  createOperations() {
+    return {
+      containerQuery: () => this.api.call("container.query" /* ContainerQuery */, [[]]).pipe(rxjs.map((containers) => containers.map(this.toContainer))),
+      // container.start is synchronous in v26.0.0 - emit null
+      containerStart: (id) => this.api.call("container.start" /* ContainerStart */, [parseInt(id, 10)]).pipe(rxjs.map(() => null)),
+      // container.stop emits job updates
+      containerStop: (id, options) => this.api.callAndGetJobId("container.stop" /* ContainerStop */, [
+        parseInt(id, 10),
+        {
+          force: options.force,
+          force_after_timeout: options.force
+        }
+      ]).pipe(rxjs.switchMap((jobId) => this.api.trackJob(jobId))),
+      // v26.0.0 doesn't have container.restart - chain stop + start
+      // Emits Job updates during stop, then null when start completes
+      containerRestart: (id, options) => {
+        const numericId = parseInt(id, 10);
+        return this.api.callAndGetJobId("container.stop" /* ContainerStop */, [
+          numericId,
+          {
+            force: options.force,
+            force_after_timeout: options.force
+          }
+        ]).pipe(
+          // Track stop job until it completes
+          rxjs.switchMap((stopJobId) => this.api.trackJob(stopJobId)),
+          // Collect all job updates to ensure stop fully completes
+          rxjs.toArray(),
+          // Re-emit job updates, then call start after stop is done
+          rxjs.switchMap(
+            (jobUpdates) => rxjs.concat(
+              rxjs.from(jobUpdates),
+              this.api.call("container.start" /* ContainerStart */, [numericId]).pipe(rxjs.map(() => null))
+            )
+          )
+        );
+      }
+    };
+  }
+  /**
+   * Transform v26 ContainerQueryV26 to unified Container type
+   */
+  toContainer(container) {
+    return {
+      id: container.id.toString(),
+      name: container.name,
+      status: _TrueNasApiClientV26.mapStatus(container.status.state),
+      autostart: container.autostart,
+      description: container.description
+      // cpu and memory are not available in v26 container.query
+      // image is not available in v26 container.query
+    };
+  }
+};
+
+// src/errors/version-discovery.errors.ts
+var VersionDiscoveryError = class extends Error {
+  constructor(message, hostname) {
+    super(message);
+    this.hostname = hostname;
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var VersionTooOldError = class extends VersionDiscoveryError {
+  constructor(hostname, availableVersions, minRequired = apiVersionConfig.MIN_SUPPORTED_VERSION) {
+    super(
+      `System API version is too old. Minimum supported: ${minRequired}. Available versions: ${availableVersions.join(
+        ", "
+      )}`,
+      hostname
+    );
+    this.availableVersions = availableVersions;
+    this.minRequired = minRequired;
+  }
+};
+var VersionTooNewError = class extends VersionDiscoveryError {
+  constructor(hostname, availableVersions, maxSupported = apiVersionConfig.MAX_SUPPORTED_VERSION) {
+    super(
+      `System API version is too new. Maximum supported: ${maxSupported}. Available versions: ${availableVersions.join(
+        ", "
+      )}`,
+      hostname
+    );
+    this.availableVersions = availableVersions;
+    this.maxSupported = maxSupported;
+  }
+};
+var VersionEndpointNotFoundError = class extends VersionDiscoveryError {
+  constructor(hostname, statusCode = 404) {
+    super(
+      `Version discovery endpoint not found: ${hostname} (HTTP ${String(
+        statusCode
+      )})`,
+      hostname
+    );
+    this.statusCode = statusCode;
+  }
+};
+var VersionDiscoveryTimeoutError = class extends VersionDiscoveryError {
+  constructor(hostname, timeoutMs = 5e3) {
+    super(
+      `Cannot connect to system (timeout after ${String(
+        timeoutMs
+      )}ms): ${hostname}`,
+      hostname
+    );
+    this.timeoutMs = timeoutMs;
+  }
+};
+var VersionDiscoveryNetworkError = class extends VersionDiscoveryError {
+  constructor(hostname, originalError) {
+    super(
+      `Network error connecting to ${hostname}: ${originalError.message}`,
+      hostname
+    );
+    this.originalError = originalError;
+  }
+};
+var NoCompatibleVersionsError = class extends VersionDiscoveryError {
+  constructor(hostname, availableVersions, supportedRange = {
+    min: apiVersionConfig.MIN_SUPPORTED_VERSION,
+    max: apiVersionConfig.MAX_SUPPORTED_VERSION
+  }) {
+    super(
+      `No compatible API versions available. Supported: ${supportedRange.min} to ${supportedRange.max}. Available: ${availableVersions.join(", ")}`,
+      hostname
+    );
+    this.availableVersions = availableVersions;
+    this.supportedRange = supportedRange;
+  }
+};
+var InvalidVersionResponseError = class extends VersionDiscoveryError {
+  constructor(hostname, reason) {
+    super(`Invalid API response format from ${hostname}: ${reason}`, hostname);
+    this.reason = reason;
+  }
+};
+var discoveryTimeoutMs = 5e3;
+function hasErrorName(error, expected) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === expected;
+}
+var VersionDiscovery = class {
+  constructor(logger = noopLogger) {
+    this.logger = logger;
+    this.versionCache = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Discovers the API version for a given hostname.
+   *
+   * Makes a GET request to `https://{hostname}/api/versions` and returns the latest
+   * compatible version. Results are cached per hostname; the cache entry is removed
+   * on failure so the next call retries.
+   *
+   * @param hostname - The TrueNAS system hostname (e.g., "truenas.local")
+   * @returns Observable that emits the selected ApiVersion
+   * @throws VersionDiscoveryError subclasses for specific failure scenarios
+   */
+  discoverVersion(hostname) {
+    const cached = this.versionCache.get(hostname);
+    if (cached) {
+      this.logger.info("Version discovery cache hit", { hostname });
+      return cached;
+    }
+    const url = `https://${hostname}/api/versions`;
+    this.logger.info("Starting version discovery", { hostname, url });
+    const discovery$ = rxjs.defer(() => rxjs.from(this.fetchVersions(hostname))).pipe(
+      operators.map((versionStrings) => this.selectVersion(hostname, versionStrings)),
+      operators.catchError((error) => {
+        this.versionCache.delete(hostname);
+        this.logger.error("Version discovery failed", { hostname, error });
+        return rxjs.throwError(() => this.classify(error, hostname));
+      }),
+      operators.shareReplay(1)
+    );
+    this.versionCache.set(hostname, discovery$);
+    return discovery$;
+  }
+  /**
+   * Clears the version cache for a specific hostname or all hostnames.
+   *
+   * @param hostname - Optional hostname to clear. If omitted, clears all cached versions.
+   */
+  clearCache(hostname) {
+    if (hostname) {
+      this.versionCache.delete(hostname);
+    } else {
+      this.versionCache.clear();
+    }
+  }
+  /**
+   * Performs the `fetch` with a 5-second `AbortController` timeout and inspects the
+   * *resolved* Response (fetch does not reject on non-2xx). Throws
+   * `VersionEndpointNotFoundError` on 404 and `InvalidVersionResponseError` on any
+   * other non-2xx or a body that is not an array of strings; lets `TypeError`
+   * (network) and `AbortError` (timeout) bubble to `classify`.
+   *
+   * The element-type check matters: a reachable server returning an array of
+   * non-strings (e.g. `[1, 2, 3]`) would otherwise reach `parseApiVersion`, whose
+   * `.match()` throws a `TypeError` on a non-string — which `classify` would then
+   * misfile as a network error. Validating here keeps it an `InvalidVersionResponseError`.
+   */
+  async fetchVersions(hostname) {
+    const url = `https://${hostname}/api/versions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), discoveryTimeoutMs);
+    try {
+      const response = await fetch(url, { signal: controller.signal });
+      if (response.status === 404) {
+        throw new VersionEndpointNotFoundError(hostname);
+      }
+      if (!response.ok) {
+        throw new InvalidVersionResponseError(
+          hostname,
+          `HTTP ${String(response.status)}`
+        );
+      }
+      const body = await response.json();
+      if (!Array.isArray(body) || !body.every((v) => typeof v === "string")) {
+        throw new InvalidVersionResponseError(
+          hostname,
+          "Response was not an array of version strings"
+        );
+      }
+      return body;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Parses, filters, and selects the latest compatible version from the raw response
+   * array. Throws the appropriate typed error when no valid/compatible version exists.
+   */
+  selectVersion(hostname, versionStrings) {
+    this.logger.info("Version discovery response received", {
+      hostname,
+      versionCount: versionStrings.length,
+      versions: versionStrings
+    });
+    const parsedVersions = versionStrings.map(parseApiVersion).filter((v) => v !== null);
+    if (parsedVersions.length === 0) {
+      this.logger.error("No valid versions in response", {
+        hostname,
+        versionStrings
+      });
+      throw new InvalidVersionResponseError(
+        hostname,
+        "No valid API versions found in response"
+      );
+    }
+    const compatibleVersions = filterCompatibleVersions(parsedVersions);
+    this.logger.info("Version compatibility check", {
+      hostname,
+      total: parsedVersions.length,
+      compatible: compatibleVersions.length,
+      supportedRange: {
+        min: apiVersionConfig.MIN_SUPPORTED_VERSION,
+        max: apiVersionConfig.MAX_SUPPORTED_VERSION
+      }
+    });
+    if (compatibleVersions.length === 0) {
+      const allTooOld = parsedVersions.every(
+        (v) => checkVersionCompatibility(v) === "too-old" /* TooOld */
+      );
+      const allTooNew = parsedVersions.every(
+        (v) => checkVersionCompatibility(v) === "too-new" /* TooNew */
+      );
+      const availableVersions = parsedVersions.map((v) => v.version);
+      if (allTooOld) {
+        this.logger.warn("All available versions too old", {
+          hostname,
+          availableVersions
+        });
+        throw new VersionTooOldError(hostname, availableVersions);
+      } else if (allTooNew) {
+        this.logger.warn("All available versions too new", {
+          hostname,
+          availableVersions
+        });
+        throw new VersionTooNewError(hostname, availableVersions);
+      } else {
+        this.logger.warn("No compatible versions found", {
+          hostname,
+          availableVersions
+        });
+        throw new NoCompatibleVersionsError(hostname, availableVersions);
+      }
+    }
+    const sortedVersions = compatibleVersions.sort(
+      (a, b) => compareVersions(b, a)
+    );
+    const selectedVersion = sortedVersions[0];
+    this.logger.info("Version selected", {
+      hostname,
+      selected: selectedVersion.version,
+      websocketPath: selectedVersion.websocketPath
+    });
+    return selectedVersion;
+  }
+  /**
+   * Maps a raw failure to a typed {@link VersionDiscoveryError}. Errors thrown by
+   * `fetchVersions`/`selectVersion` are already typed and pass through unchanged; a
+   * `fetch` `TypeError` becomes {@link VersionDiscoveryNetworkError} (the CORS/network
+   * sentinel), an `AbortError` becomes {@link VersionDiscoveryTimeoutError}, and any
+   * other failure (e.g. an unparseable body's `SyntaxError`) becomes
+   * {@link InvalidVersionResponseError}.
+   */
+  classify(error, hostname) {
+    if (error instanceof VersionDiscoveryError) {
+      return error;
+    }
+    if (hasErrorName(error, "AbortError")) {
+      this.logger.warn("Version discovery timeout", { hostname });
+      return new VersionDiscoveryTimeoutError(hostname);
+    }
+    if (error instanceof TypeError) {
+      this.logger.warn("Version discovery network error", {
+        hostname,
+        message: error.message
+      });
+      return new VersionDiscoveryNetworkError(hostname, error);
+    }
+    const reason = error instanceof Error ? error.message : "Unknown error";
+    this.logger.warn("Version discovery failed with unknown error", {
+      hostname,
+      reason
+    });
+    return new InvalidVersionResponseError(
+      hostname,
+      `Versioned API not available. This system may be running an older TrueNAS version (requires v25.10.0+). ${reason}`
+    );
+  }
+};
+
+// src/factory.ts
+async function createTrueNasClient(opts) {
+  const { uuid, hostnames, systemName } = opts;
+  const logger = opts.logger ?? noopLogger;
+  if (!hostnames || hostnames.length === 0) {
+    throw new Error(
+      `Cannot create client for system ${uuid}: hostnames array is empty`
+    );
+  }
+  const primaryHostname = hostnames[0];
+  const versionDiscovery = new VersionDiscovery(logger);
+  logger.info("Creating versioned API client", {
+    uuid: uuid.slice(0, 8),
+    hostname: primaryHostname,
+    systemName
+  });
+  let version;
+  try {
+    version = await rxjs.firstValueFrom(
+      versionDiscovery.discoverVersion(primaryHostname)
+    );
+    logger.info("API version discovered, instantiating client", {
+      uuid: uuid.slice(0, 8),
+      version: version.version,
+      websocketPath: version.websocketPath
+    });
+  } catch (error) {
+    const errorMessage = errorMessageOrDefault(error, "Unknown error");
+    if (!(error instanceof VersionDiscoveryNetworkError)) {
+      logger.error("Version discovery failed", {
+        uuid: uuid.slice(0, 8),
+        hostname: primaryHostname,
+        error: errorMessage,
+        errorType: error instanceof Error ? error.constructor.name : typeof error
+      });
+      throw error;
+    }
+    const fallbackVersionString = apiVersionConfig.FALLBACK_VERSION;
+    const fallbackVersion = parseApiVersion(fallbackVersionString);
+    if (!fallbackVersion) {
+      logger.error("Invalid fallback version configuration", {
+        uuid: uuid.slice(0, 8),
+        hostname: primaryHostname,
+        fallbackVersion: fallbackVersionString
+      });
+      throw error;
+    }
+    logger.warn(
+      "Version discovery failed with a network error (possible CORS or network issue), falling back to assumed version",
+      {
+        uuid: uuid.slice(0, 8),
+        hostname: primaryHostname,
+        fallbackVersion: fallbackVersionString,
+        originalError: errorMessage,
+        warning: "A network error has multiple causes (CORS, network down, DNS failure). The connection may still fail during the WebSocket handshake."
+      }
+    );
+    version = fallbackVersion;
+  }
+  return instantiateClientForVersion(version, opts, logger);
+}
+function instantiateClientForVersion(version, opts, logger) {
+  const { uuid, hostnames, enabled, systemName } = opts;
+  let versionKey;
+  if (version.year <= legacyCutoffYear) {
+    const monthPadded = version.minor.toString().padStart(2, "0");
+    versionKey = `${version.year.toString()}.${monthPadded}`;
+  } else {
+    versionKey = version.year.toString();
+  }
+  switch (versionKey) {
+    case "25.10":
+      logger.info("Instantiating TrueNasApiClientV2510", {
+        uuid: uuid.slice(0, 8),
+        version: version.version,
+        versionKey
+      });
+      return new TrueNasApiClientV2510(
+        uuid,
+        hostnames,
+        version,
+        enabled,
+        systemName,
+        logger
+      );
+    case "26":
+      logger.info("Instantiating TrueNasApiClientV26", {
+        uuid: uuid.slice(0, 8),
+        version: version.version,
+        versionKey
+      });
+      return new TrueNasApiClientV26(
+        uuid,
+        hostnames,
+        version,
+        enabled,
+        systemName,
+        logger
+      );
+    default:
+      logger.error("No client implementation for version", {
+        uuid: uuid.slice(0, 8),
+        version: version.version,
+        versionKey
+      });
+      throw new Error(
+        `No client implementation for API version ${version.version}. Supported versions: v25.10.x, v26.x.y. Version key: ${versionKey}`
+      );
+  }
+}
+function errorMessageOrDefault(error, fallback) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return fallback;
+}
+
+exports.AuthError = AuthError;
+exports.AuthErrorCode = AuthErrorCode;
+exports.InvalidVersionResponseError = InvalidVersionResponseError;
+exports.JobState = JobState;
+exports.NoCompatibleVersionsError = NoCompatibleVersionsError;
+exports.TrueNasApiClient = TrueNasApiClient;
+exports.TrueNasApiClientV2510 = TrueNasApiClientV2510;
+exports.TrueNasApiClientV26 = TrueNasApiClientV26;
+exports.TrueNasAuthMechanism = TrueNasAuthMechanism;
+exports.TrueNasEndpoint = TrueNasEndpoint;
+exports.VersionCompatibility = VersionCompatibility;
+exports.VersionDiscovery = VersionDiscovery;
+exports.VersionDiscoveryError = VersionDiscoveryError;
+exports.VersionDiscoveryNetworkError = VersionDiscoveryNetworkError;
+exports.VersionDiscoveryTimeoutError = VersionDiscoveryTimeoutError;
+exports.VersionEndpointNotFoundError = VersionEndpointNotFoundError;
+exports.VersionTooNewError = VersionTooNewError;
+exports.VersionTooOldError = VersionTooOldError;
+exports.consoleLogger = consoleLogger;
+exports.createTrueNasClient = createTrueNasClient;
+exports.getApiErrorMessage = getApiErrorMessage;
+exports.noopLogger = noopLogger;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map