@truenas/api-client 3.0.4 → 3.0.5

package/dist/index.js

@@ -367,775 +367,153 @@ var TrueNasApi = class {
   }
 };
 
-// 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/generated/v25_10_0/index.ts
+var v25_10_0_exports = {};
+__export(v25_10_0_exports, {
+  ACLTemplateEntryAcltypeInput: () => ACLTemplateEntryAcltypeInput,
+  Aclmode: () => Aclmode,
+  Acltype: () => Acltype,
+  Action: () => Action,
+  Advpowermgmt: () => Advpowermgmt,
+  Algorithm: () => Algorithm,
+  AppContainerDetailsStateInput: () => AppContainerDetailsStateInput,
+  Atime: () => Atime,
+  Authenticator: () => Authenticator,
+  Authmethod: () => Authmethod,
+  Autotrim: () => Autotrim,
+  Basic: () => Basic,
+  Blocksize: () => Blocksize,
+  Bootloader: () => Bootloader,
+  Casesensitivity: () => Casesensitivity,
+  CloudBackupSnapshotItemType: () => CloudBackupSnapshotItemType,
+  CloudSyncCreateDirection: () => CloudSyncCreateDirection,
+  CloudSyncCreateDirectionInput: () => CloudSyncCreateDirectionInput,
+  CloudTaskAttributesEncryptionInput: () => CloudTaskAttributesEncryptionInput,
+  Code: () => Code,
+  Compression: () => Compression,
+  CorePingRemoteTypeInput: () => CorePingRemoteTypeInput,
+  Credentials: () => Credentials,
+  DeviceGetInfoOtherTypeInput: () => DeviceGetInfoOtherTypeInput,
+  DiskDetailsTypeInput: () => DiskDetailsTypeInput,
+  DiskWipeModeInput: () => DiskWipeModeInput,
+  DockerStatusInfoStatusInput: () => DockerStatusInfoStatusInput,
+  Enclosure2SetSlotStatusStatusInput: () => Enclosure2SetSlotStatusStatusInput,
+  Encryption: () => Encryption,
+  Endpoint: () => Endpoint,
+  Exec: () => Exec,
+  Feature: () => Feature,
+  FilesystemDirEntryType: () => FilesystemDirEntryType,
+  Function: () => Function,
+  GetDisplayDeviceType: () => GetDisplayDeviceType,
+  Hddstandby: () => Hddstandby,
+  InitShutdownScriptCreateType: () => InitShutdownScriptCreateType,
+  InitShutdownScriptCreateTypeInput: () => InitShutdownScriptCreateTypeInput,
+  InterfaceCreateAliasTypeInput: () => InterfaceCreateAliasTypeInput,
+  InterfaceCreateTypeInput: () => InterfaceCreateTypeInput,
+  Iotype: () => Iotype,
+  IpmiChassisIdentifyVerb: () => IpmiChassisIdentifyVerb,
+  IscsiExtentCreateType: () => IscsiExtentCreateType,
+  IscsiExtentCreateTypeInput: () => IscsiExtentCreateTypeInput,
+  IscsiTargetCreateMode: () => IscsiTargetCreateMode,
+  IscsiTargetCreateModeInput: () => IscsiTargetCreateModeInput,
+  KeychainCredentialEntryType: () => KeychainCredentialEntryType,
+  KeychainCredentialEntryTypeInput: () => KeychainCredentialEntryTypeInput,
+  Level: () => Level,
+  NFS4ACEType: () => NFS4ACEType,
+  NFS4ACETypeInput: () => NFS4ACETypeInput,
+  Name: () => Name,
+  Policy: () => Policy,
+  PoolCreateChecksum: () => PoolCreateChecksum,
+  PoolCreateDeduplication: () => PoolCreateDeduplication,
+  PoolCreateTopologyDataVdevDRAIDTypeInput: () => PoolCreateTopologyDataVdevDRAIDTypeInput,
+  PoolDatasetCreateFilesystemAcltypeInput: () => PoolDatasetCreateFilesystemAcltypeInput,
+  PoolDatasetCreateFilesystemChecksum: () => PoolDatasetCreateFilesystemChecksum,
+  PoolDatasetCreateFilesystemDeduplication: () => PoolDatasetCreateFilesystemDeduplication,
+  PoolDatasetCreateFilesystemReadonlyInput: () => PoolDatasetCreateFilesystemReadonlyInput,
+  PoolDatasetDeleteResult: () => PoolDatasetDeleteResult,
+  PoolScanStateInput: () => PoolScanStateInput,
+  Protocol: () => Protocol,
+  Purpose: () => Purpose,
+  Readonly: () => Readonly,
+  ReplicationCountEligibleManualSnapshotsTransportInput: () => ReplicationCountEligibleManualSnapshotsTransportInput,
+  ReplicationCreateReadonlyInput: () => ReplicationCreateReadonlyInput,
+  Resolution: () => Resolution,
+  Rpm: () => Rpm,
+  RsyncTaskCreateDirection: () => RsyncTaskCreateDirection,
+  RsyncTaskCreateDirectionInput: () => RsyncTaskCreateDirectionInput,
+  RsyncTaskCreateMode: () => RsyncTaskCreateMode,
+  RsyncTaskCreateModeInput: () => RsyncTaskCreateModeInput,
+  SMBEntryEncryptionInput: () => SMBEntryEncryptionInput,
+  STIGType: () => STIGType,
+  Schema: () => Schema,
+  Security: () => Security,
+  Serialspeed: () => Serialspeed,
+  ServiceControlVerb: () => ServiceControlVerb,
+  SharingSMBEntryPurposeInput: () => SharingSMBEntryPurposeInput,
+  SharingSMBEntryPurposeInput2: () => SharingSMBEntryPurposeInput2,
+  Shutdown: () => Shutdown,
+  Snapdev: () => Snapdev,
+  Snapdir: () => Snapdir,
+  Source: () => Source,
+  SourceInput: () => SourceInput,
+  State: () => State,
+  Status: () => Status,
+  SupportNewTicketCommunityTypeInput: () => SupportNewTicketCommunityTypeInput,
+  Sync: () => Sync,
+  SyslogServerTransportInput: () => SyslogServerTransportInput,
+  Sysloglevel: () => Sysloglevel,
+  SystemProductTypeResult: () => SystemProductTypeResult,
+  SystemStateResult: () => SystemStateResult,
+  Tag: () => Tag,
+  Target: () => Target,
+  Time: () => Time,
+  Transport: () => Transport,
+  TruecommandConfigChangedEventFieldsStatus: () => TruecommandConfigChangedEventFieldsStatus,
+  TruecommandConfigChangedEventFieldsStatusInput: () => TruecommandConfigChangedEventFieldsStatusInput,
+  TunableCreateType: () => TunableCreateType,
+  TunableCreateTypeInput: () => TunableCreateTypeInput,
+  UPSEntryMode: () => UPSEntryMode,
+  UPSEntryModeInput: () => UPSEntryModeInput,
+  Unixcharset: () => Unixcharset,
+  Username: () => Username,
+  VMDiskDeviceType: () => VMDiskDeviceType,
+  VMDiskDeviceTypeInput: () => VMDiskDeviceTypeInput,
+  VMWareEntryStateStateInput: () => VMWareEntryStateStateInput,
+  VMWareMatchDatastoresWithDatasetsResultFilesystemType: () => VMWareMatchDatastoresWithDatasetsResultFilesystemType,
+  Vendor: () => Vendor,
+  Volblocksize: () => Volblocksize,
+  When: () => When,
+  ZfsTierRewriteJobEntryStatusInput: () => ZfsTierRewriteJobEntryStatusInput
+});
 
-// 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/generated/v25_10_0/api-types.ts
+var Aclmode = {
+  Passthrough: "PASSTHROUGH",
+  Restricted: "RESTRICTED",
+  Discard: "DISCARD",
+  Inherit: "INHERIT"
 };
-
-// src/auth/truenas-authenticator.ts
-var throwOnAuthenticationFailure = (code, message) => switchMap((response) => {
-  if (response.response_type === "AUTH_ERR" /* AuthErr */) {
-    return throwError(() => new AuthError(code, message));
-  }
-  return 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 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 BehaviorSubject(false);
-    this.credentials = { username: "", password: "", key: "" };
-    this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
-    this.connection.opened.pipe(
-      filter(
-        (isOpen) => !!(isOpen && this.credentials?.username && (this.credentials.password || this.credentials.key))
-      ),
-      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),
-      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."
-      ),
-      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"
-            );
-          }
-        }
-      }),
-      finalize(() => {
-        this.authenticating$.next(false);
-      }),
-      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),
-      map((msg) => {
-        if (msg.error) {
-          const errorMessage = getApiErrorMessage(
-            msg.error,
-            "Authentication failed"
-          );
-          throw new Error(errorMessage);
-        }
-        return msg.result;
-      }),
-      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."
-      ),
-      finalize(() => {
-        this.authenticating$.next(false);
-      }),
-      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),
-      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?"
-      ),
-      tap((res) => {
-        this.credentials.username = username;
-        this.credentials.key = key;
-        this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
-        this.authenticated$.next(true);
-      }),
-      finalize(() => {
-        this.authenticating$.next(false);
-      }),
-      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),
-      map((msg) => {
-        if (msg.error) {
-          const errorMessage = getApiErrorMessage(
-            msg.error,
-            "Failed to create API key"
-          );
-          throw new Error(errorMessage);
-        }
-        return msg.result;
-      }),
-      take(1)
-    );
-  }
-  logout() {
-    const message = createJsonRpcMessage("auth.logout");
-    this.connection.send(message);
-    const messageId = message.id ?? "";
-    return this.connection.messages().pipe(
-      withId(messageId),
-      map((msg) => {
-        if (msg.error) {
-          return false;
-        }
-        return msg.result;
-      }),
-      tap((success) => {
-        this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
-        this.authenticated$.next(!success);
-      }),
-      take(1)
-    );
-  }
+var ACLTemplateEntryAcltypeInput = {
+  Nfs4: "NFS4",
+  Posix1e: "POSIX1E"
 };
-
-// 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 Acltype = {
+  Nfs4: "NFS4",
+  Posix1e: "POSIX1E"
 };
-var noop = () => void 0;
-var noopLogger = {
-  trace: noop,
-  debug: noop,
-  info: noop,
-  warn: noop,
-  error: noop
+var Action = {
+  Start: "START",
+  Stop: "STOP",
+  Pause: "PAUSE"
 };
-
-// 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(this.config);
-  }
-  messages() {
-    return this.socket;
-  }
-  next(msg) {
-    this.socket.next(msg);
-  }
-  complete() {
-    this.socket.complete();
-  }
-};
-
-// src/types/transport.type.ts
-function httpScheme(protocol) {
-  return protocol === "http:" ? "http:" : "https:";
-}
-function socketScheme(protocol) {
-  return protocol === "http:" ? "ws:" : "wss:";
-}
-
-// 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, protocol = "https:") {
-    this.hostnames = hostnames;
-    this.systemUuid = systemUuid;
-    this.websocketPath = websocketPath;
-    this.systemName = systemName;
-    this.retryDelay = retryDelay;
-    this.maxRetry = maxRetry;
-    this.logger = logger;
-    this.protocol = protocol;
-    // compatibility properties
-    this.opened = new BehaviorSubject(false);
-    this.closed = new Subject();
-    this.hostname = new BehaviorSubject("");
-    this.connectionAttempts = new BehaviorSubject(0);
-    this.lastErrorMessage = new BehaviorSubject(null);
-    /**
-     * emits when the connection is manually closed.
-     */
-    this.closeConnection = new 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 BehaviorSubject(false);
-    /**
-     * observable which emits the current gate value and only emits again when it changes.
-     */
-    this.enabledChange$ = this.enabled$.pipe(distinctUntilChanged());
-    /**
-     * observable that handles the entire connection lifecycle.
-     */
-    this.connection$ = this.enabledChange$.pipe(
-      switchMap((enabled) => {
-        if (enabled) {
-          return this.connect().pipe(
-            map((conn) => makeActiveConnection(conn.ws, conn.hostname))
-          );
-        }
-        return of(closedConnection);
-      }),
-      switchMap((connection) => {
-        if (connection.state !== "active") {
-          return of(connection);
-        }
-        const initMessage = createJsonRpcMessage("core.set_options", [
-          { legacy_jobs: false }
-        ]);
-        connection.ws.next(initMessage);
-        return connection.ws.messages().pipe(
-          filter((msg) => msg.id === initMessage.id),
-          take(1),
-          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.
-      catchError$1((err) => {
-        this.logger.error("All connections failed - retrying", { message: err?.message, hostname: err?.hostname });
-        return concat(
-          of(makeConnectionError(err.message, err.hostname)),
-          // since this error will immediately get caught by `retry` there's no reason to build a real error.
-          throwError(() => null)
-        );
-      }),
-      retry(),
-      // start with a closed connection.
-      startWith(closedConnection),
-      // prevent multiple subscriptions from re-evaluating the entire pipeline.
-      shareReplay$1({ bufferSize: 1, refCount: false }),
-      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(
-      map((conn) => conn.state === "active" ? conn.ws : null)
-    );
-    /**
-     * current hostname we used to build the URL for this connection.
-     */
-    this.hostname$ = this.connection$.pipe(
-      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(
-      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(
-      map((conn) => conn.state),
-      distinctUntilChanged(),
-      map((state) => state === "active")
-    );
-    /**
-     * emits when the connection state goes from open to closed.
-     */
-    this.closed$ = this.connection$.pipe(
-      map((conn) => conn.state),
-      distinctUntilChanged(),
-      filter((state) => state === "closed" || state === "error"),
-      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(
-      map((conn) => conn.state === "error"),
-      takeUntil(this.closeConnection)
-    );
-    /**
-     * observable which always emits messages from the current socket.
-     */
-    this.messages$ = this.ws$.pipe(
-      filter((ws) => ws !== null),
-      switchMap((ws) => ws.messages().pipe(
-        catchError$1(() => EMPTY)
-      ))
-    );
-    combineLatest([
-      interval(twentySeconds),
-      this.ws$
-    ]).pipe(
-      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(filter(Boolean)).subscribe((name) => this.hostname.next(name));
-    this.ws$.pipe(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.
-   */
-  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(
-      filter((ws) => ws !== null),
-      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 = `${socketScheme(this.protocol)}//${hostname}${this.websocketPath}`;
-    let hasOpened = false;
-    return new Observable((subscriber) => {
-      const ws = new TrueNasSocket({
-        url,
-        openObserver: {
-          next: () => {
-            hasOpened = true;
-            this.connectionAttempts.next(0);
-            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
-      timeout({ first: tenSeconds }),
-      retry({
-        //   * while still *establishing*: wait `retryDelay` before trying again, giving up
-        //     after `maxRetry` retries.
-        count: this.maxRetry,
-        //   * we use a custom `delay` function here to ensure no retries are performed
-        //     once a socket is *opened*.
-        //     basically: a later death must propagate out rather than being retried
-        //     so it can be handled by the `connection$` observable.
-        delay: (error) => {
-          if (hasOpened) {
-            return throwError(() => error);
-          }
-          return timer(this.retryDelay);
-        }
-      })
-    );
-  }
-  /**
-   * helper function which actually performs the parallel connection `race`.
-   */
-  connect() {
-    return race(
-      this.hostnames.map(this.createSocket.bind(this))
-    ).pipe(
-      tap((conn) => this.logger.debug(`TrueNas socket opened to ${conn.hostname}.`)),
-      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/generated/v25_10_0/index.ts
-var v25_10_0_exports = {};
-__export(v25_10_0_exports, {
-  ACLTemplateEntryAcltypeInput: () => ACLTemplateEntryAcltypeInput,
-  Aclmode: () => Aclmode,
-  Acltype: () => Acltype,
-  Action: () => Action,
-  Advpowermgmt: () => Advpowermgmt,
-  Algorithm: () => Algorithm,
-  AppContainerDetailsStateInput: () => AppContainerDetailsStateInput,
-  Atime: () => Atime,
-  Authenticator: () => Authenticator,
-  Authmethod: () => Authmethod,
-  Autotrim: () => Autotrim,
-  Basic: () => Basic,
-  Blocksize: () => Blocksize,
-  Bootloader: () => Bootloader,
-  Casesensitivity: () => Casesensitivity,
-  CloudBackupSnapshotItemType: () => CloudBackupSnapshotItemType,
-  CloudSyncCreateDirection: () => CloudSyncCreateDirection,
-  CloudSyncCreateDirectionInput: () => CloudSyncCreateDirectionInput,
-  CloudTaskAttributesEncryptionInput: () => CloudTaskAttributesEncryptionInput,
-  Code: () => Code,
-  Compression: () => Compression,
-  CorePingRemoteTypeInput: () => CorePingRemoteTypeInput,
-  Credentials: () => Credentials,
-  DeviceGetInfoOtherTypeInput: () => DeviceGetInfoOtherTypeInput,
-  DiskDetailsTypeInput: () => DiskDetailsTypeInput,
-  DiskWipeModeInput: () => DiskWipeModeInput,
-  DockerStatusInfoStatusInput: () => DockerStatusInfoStatusInput,
-  Enclosure2SetSlotStatusStatusInput: () => Enclosure2SetSlotStatusStatusInput,
-  Encryption: () => Encryption,
-  Endpoint: () => Endpoint,
-  Exec: () => Exec,
-  Feature: () => Feature,
-  FilesystemDirEntryType: () => FilesystemDirEntryType,
-  Function: () => Function,
-  GetDisplayDeviceType: () => GetDisplayDeviceType,
-  Hddstandby: () => Hddstandby,
-  InitShutdownScriptCreateType: () => InitShutdownScriptCreateType,
-  InitShutdownScriptCreateTypeInput: () => InitShutdownScriptCreateTypeInput,
-  InterfaceCreateAliasTypeInput: () => InterfaceCreateAliasTypeInput,
-  InterfaceCreateTypeInput: () => InterfaceCreateTypeInput,
-  Iotype: () => Iotype,
-  IpmiChassisIdentifyVerb: () => IpmiChassisIdentifyVerb,
-  IscsiExtentCreateType: () => IscsiExtentCreateType,
-  IscsiExtentCreateTypeInput: () => IscsiExtentCreateTypeInput,
-  IscsiTargetCreateMode: () => IscsiTargetCreateMode,
-  IscsiTargetCreateModeInput: () => IscsiTargetCreateModeInput,
-  KeychainCredentialEntryType: () => KeychainCredentialEntryType,
-  KeychainCredentialEntryTypeInput: () => KeychainCredentialEntryTypeInput,
-  Level: () => Level,
-  NFS4ACEType: () => NFS4ACEType,
-  NFS4ACETypeInput: () => NFS4ACETypeInput,
-  Name: () => Name,
-  Policy: () => Policy,
-  PoolCreateChecksum: () => PoolCreateChecksum,
-  PoolCreateDeduplication: () => PoolCreateDeduplication,
-  PoolCreateTopologyDataVdevDRAIDTypeInput: () => PoolCreateTopologyDataVdevDRAIDTypeInput,
-  PoolDatasetCreateFilesystemAcltypeInput: () => PoolDatasetCreateFilesystemAcltypeInput,
-  PoolDatasetCreateFilesystemChecksum: () => PoolDatasetCreateFilesystemChecksum,
-  PoolDatasetCreateFilesystemDeduplication: () => PoolDatasetCreateFilesystemDeduplication,
-  PoolDatasetCreateFilesystemReadonlyInput: () => PoolDatasetCreateFilesystemReadonlyInput,
-  PoolDatasetDeleteResult: () => PoolDatasetDeleteResult,
-  PoolScanStateInput: () => PoolScanStateInput,
-  Protocol: () => Protocol,
-  Purpose: () => Purpose,
-  Readonly: () => Readonly,
-  ReplicationCountEligibleManualSnapshotsTransportInput: () => ReplicationCountEligibleManualSnapshotsTransportInput,
-  ReplicationCreateReadonlyInput: () => ReplicationCreateReadonlyInput,
-  Resolution: () => Resolution,
-  Rpm: () => Rpm,
-  RsyncTaskCreateDirection: () => RsyncTaskCreateDirection,
-  RsyncTaskCreateDirectionInput: () => RsyncTaskCreateDirectionInput,
-  RsyncTaskCreateMode: () => RsyncTaskCreateMode,
-  RsyncTaskCreateModeInput: () => RsyncTaskCreateModeInput,
-  SMBEntryEncryptionInput: () => SMBEntryEncryptionInput,
-  STIGType: () => STIGType,
-  Schema: () => Schema,
-  Security: () => Security,
-  Serialspeed: () => Serialspeed,
-  ServiceControlVerb: () => ServiceControlVerb,
-  SharingSMBEntryPurposeInput: () => SharingSMBEntryPurposeInput,
-  SharingSMBEntryPurposeInput2: () => SharingSMBEntryPurposeInput2,
-  Shutdown: () => Shutdown,
-  Snapdev: () => Snapdev,
-  Snapdir: () => Snapdir,
-  Source: () => Source,
-  SourceInput: () => SourceInput,
-  State: () => State,
-  Status: () => Status,
-  SupportNewTicketCommunityTypeInput: () => SupportNewTicketCommunityTypeInput,
-  Sync: () => Sync,
-  SyslogServerTransportInput: () => SyslogServerTransportInput,
-  Sysloglevel: () => Sysloglevel,
-  SystemProductTypeResult: () => SystemProductTypeResult,
-  SystemStateResult: () => SystemStateResult,
-  Tag: () => Tag,
-  Target: () => Target,
-  Time: () => Time,
-  Transport: () => Transport,
-  TruecommandConfigChangedEventFieldsStatus: () => TruecommandConfigChangedEventFieldsStatus,
-  TruecommandConfigChangedEventFieldsStatusInput: () => TruecommandConfigChangedEventFieldsStatusInput,
-  TunableCreateType: () => TunableCreateType,
-  TunableCreateTypeInput: () => TunableCreateTypeInput,
-  UPSEntryMode: () => UPSEntryMode,
-  UPSEntryModeInput: () => UPSEntryModeInput,
-  Unixcharset: () => Unixcharset,
-  Username: () => Username,
-  VMDiskDeviceType: () => VMDiskDeviceType,
-  VMDiskDeviceTypeInput: () => VMDiskDeviceTypeInput,
-  VMWareEntryStateStateInput: () => VMWareEntryStateStateInput,
-  VMWareMatchDatastoresWithDatasetsResultFilesystemType: () => VMWareMatchDatastoresWithDatasetsResultFilesystemType,
-  Vendor: () => Vendor,
-  Volblocksize: () => Volblocksize,
-  When: () => When,
-  ZfsTierRewriteJobEntryStatusInput: () => ZfsTierRewriteJobEntryStatusInput
-});
-
-// src/generated/v25_10_0/api-types.ts
-var Aclmode = {
-  Passthrough: "PASSTHROUGH",
-  Restricted: "RESTRICTED",
-  Discard: "DISCARD",
-  Inherit: "INHERIT"
-};
-var ACLTemplateEntryAcltypeInput = {
-  Nfs4: "NFS4",
-  Posix1e: "POSIX1E"
-};
-var Acltype = {
-  Nfs4: "NFS4",
-  Posix1e: "POSIX1E"
-};
-var Action = {
-  Start: "START",
-  Stop: "STOP",
-  Pause: "PAUSE"
-};
-var Advpowermgmt = {
-  Disabled: "DISABLED",
-  "1": "1",
-  "64": "64",
-  "127": "127",
-  "128": "128",
-  "192": "192",
-  "254": "254"
+var Advpowermgmt = {
+  Disabled: "DISABLED",
+  "1": "1",
+  "64": "64",
+  "127": "127",
+  "128": "128",
+  "192": "192",
+  "254": "254"
 };
 var Algorithm = {
   Aes128Ccm: "AES-128-CCM",
@@ -2870,141 +2248,871 @@ __export(v27_0_0_exports, {
   ZpoolScrubRunAction: () => ZpoolScrubRunAction
 });
 
-// src/generated/index.ts
-var SUPPORTED_API_VERSIONS = [
-  "v25.10.0",
-  "v25.10.1",
-  "v25.10.2",
-  "v25.10.3",
-  "v25.10.4",
-  "v25.10.5",
-  "v26.0.0",
-  "v27.0.0"
-];
+// src/generated/index.ts
+var SUPPORTED_API_VERSIONS = [
+  "v25.10.0",
+  "v25.10.1",
+  "v25.10.2",
+  "v25.10.3",
+  "v25.10.4",
+  "v25.10.5",
+  "v26.0.0",
+  "v27.0.0"
+];
+
+// src/config/api-version.config.ts
+var apiVersionConfig = {
+  /**
+   * Minimum supported API version. Systems below it are rejected.
+   *
+   * DERIVED, not declared. The client supports exactly the versions it ships
+   * types for, so the oldest generated version *is* the minimum — there is no
+   * second decision to make, and therefore nothing to keep in sync.
+   *
+   * To move the floor, change `--min-version` in the `generate:api` script in
+   * package.json and regenerate; this follows on its own. Written as a literal
+   * it would duplicate that value with nothing enforcing agreement, so raising
+   * one and forgetting the other would silently keep generating types for
+   * versions the client rejects.
+   */
+  MIN_SUPPORTED_VERSION: SUPPORTED_API_VERSIONS[0],
+  /**
+   * Maximum supported API version. Systems above it are rejected.
+   *
+   * NOT derived, deliberately — and for a different reason than it used to
+   * lag. It sat at v26.0.0 while types for v27 already shipped, because
+   * `CLIENT_BY_VERSION_KEY` had no `27` and a v27 system would have passed the
+   * range check only to throw on client selection. `TrueNasApiClientV27` now
+   * exists, so this moves up with it.
+   *
+   * What it must not become is `SUPPORTED_API_VERSIONS[length - 1]`, the mirror
+   * of how MIN is derived. MIN is safe to derive because the oldest generated
+   * version always has a client — it is the floor the clients were built from.
+   * The ceiling is not symmetric: generating types for v28 does not write a v28
+   * client, so deriving this would re-create the exact gap described above on
+   * the next regeneration, silently. The real invariant is "the newest version
+   * a client can be built for", which lives in `CLIENT_BY_VERSION_KEY`; a
+   * factory test asserts the two agree, which is the check that keeps this
+   * literal honest without importing the factory here.
+   */
+  MAX_SUPPORTED_VERSION: "v27.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/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["TokenAuthFailed"] = "TOKEN_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) => switchMap((response) => {
+  if (response.response_type === "AUTH_ERR" /* AuthErr */) {
+    return throwError(() => new AuthError(code, message));
+  }
+  return of(response);
+});
+var TrueNasAuthenticator = class _TrueNasAuthenticator {
+  constructor(connection, version) {
+    this.connection = connection;
+    this.version = version;
+    // 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 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 BehaviorSubject(false);
+    this.credentials = { username: "", password: "", key: "" };
+    this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
+    this.connection.opened.pipe(
+      filter(
+        (isOpen) => !!(isOpen && this.credentials?.username && (this.credentials.password || this.credentials.key))
+      ),
+      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;
+  }
+  /**
+   * `login_options` asking for a reconnect token, when the server understands it.
+   *
+   * Omitted below v26. `AuthCommonOptions` is `additionalProperties: false`
+   * there and has only `user_info`, so sending the member is a validation
+   * error, not an ignored field — it would fail login outright on the oldest
+   * version this client supports.
+   */
+  /**
+   * Two things this does not do, both deliberate and both worth knowing.
+   *
+   * There is no way for a consumer to decline: every v26+ password login now
+   * mints a single-use credential carrying that session's roles, whether or not
+   * the caller wants one. And the auto-relogin in the constructor subscribes
+   * with no observer, so the token it mints is dropped — a caller reconnecting
+   * repeatedly holds an ageing token while the appliance mints fresh ones
+   * nobody reads. Tokens are single-use with a 600s TTL, so that is the
+   * reconnect case the feature is named for.
+   */
+  reconnectTokenOption() {
+    if (!this.version || this.version.year <= legacyCutoffYear) return void 0;
+    return { login_options: { reconnect_token: true } };
+  }
+  loginWithUserPass(username, password) {
+    const message = createJsonRpcMessage("auth.login_ex", [
+      {
+        mechanism: "PASSWORD_PLAIN" /* Password */,
+        username,
+        password,
+        ...this.reconnectTokenOption()
+      }
+    ]);
+    this.authenticating$.next(true);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      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."
+      ),
+      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"
+            );
+          }
+        }
+      }),
+      finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      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),
+      map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Authentication failed"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      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."
+      ),
+      finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      take(1)
+    );
+  }
+  /**
+   * Re-authenticate with a token from a previous login's `reconnect_token`.
+   *
+   * This is what lets a second connection to the same appliance authenticate
+   * without asking the user for a password again — middleware sessions are
+   * per-connection, so a second socket has its own to establish.
+   *
+   * The token is single-use and short-lived. On v26+ a successful login mints
+   * another on the response, so a caller keeping a session alive across
+   * reconnects stores the newest each time; below v26 nothing is minted and
+   * there is no chain to keep.
+   *
+   * Re-login is the caller's to drive. A token session is not covered by the
+   * automatic reconnect this class does for password and api-key sessions,
+   * which is deliberate — the token is single-use — but it means a dropped
+   * socket needs the stored token spending explicitly. Middleware holds tokens
+   * in memory, so a `middlewared` restart voids them, and that is a common
+   * reason the socket dropped in the first place.
+   */
+  loginWithToken(token) {
+    const message = createJsonRpcMessage("auth.login_ex", [
+      {
+        mechanism: "TOKEN_PLAIN" /* Token */,
+        token,
+        ...this.reconnectTokenOption()
+      }
+    ]);
+    this.authenticating$.next(true);
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Authentication failed"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      // Password login lets non-`AUTH_ERR` answers through because it has to
+      // hand `OTP_REQUIRED` back to the caller. Token login has no such case:
+      // middleware answers `EXPIRED` for an account locked or expired between
+      // minting and spending, and `DENIED` for a permission refusal, so letting
+      // those reach `next` would report a failed login as a successful one.
+      map((res) => {
+        if (res.response_type !== "SUCCESS" /* Success */) {
+          throw new AuthError(
+            "TOKEN_AUTH_FAILED" /* TokenAuthFailed */,
+            `TrueNAS token authentication failed (${res.response_type}). The token may have expired or been used, or the account may no longer be permitted to log in.`
+          );
+        }
+        return res;
+      }),
+      tap((res) => {
+        if (res.response_type === "SUCCESS" /* Success */) {
+          if (res.user_info?.privilege.roles.$set.includes("FULL_ADMIN" /* FullAdmin */)) {
+            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"
+            );
+          }
+        }
+      }),
+      finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      take(1)
+    );
+  }
+  /**
+   * No reconnect token is requested here, though v26+ would mint one: an
+   * api-key session already reconnects without a prompt, since the key is held
+   * and replayed. The token exists for the credential that cannot be.
+   */
+  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),
+      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?"
+      ),
+      tap((res) => {
+        this.credentials.username = username;
+        this.credentials.key = key;
+        this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
+        this.authenticated$.next(true);
+      }),
+      finalize(() => {
+        this.authenticating$.next(false);
+      }),
+      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),
+      map((msg) => {
+        if (msg.error) {
+          const errorMessage = getApiErrorMessage(
+            msg.error,
+            "Failed to create API key"
+          );
+          throw new Error(errorMessage);
+        }
+        return msg.result;
+      }),
+      take(1)
+    );
+  }
+  logout() {
+    const message = createJsonRpcMessage("auth.logout");
+    this.connection.send(message);
+    const messageId = message.id ?? "";
+    return this.connection.messages().pipe(
+      withId(messageId),
+      map((msg) => {
+        if (msg.error) {
+          return false;
+        }
+        return msg.result;
+      }),
+      tap((success) => {
+        this.sessionLifetime = _TrueNasAuthenticator.DefaultSessionLifetime;
+        this.authenticated$.next(!success);
+      }),
+      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/config/api-version.config.ts
-var apiVersionConfig = {
+// 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(this.config);
+  }
+  messages() {
+    return this.socket;
+  }
+  next(msg) {
+    this.socket.next(msg);
+  }
+  complete() {
+    this.socket.complete();
+  }
+};
+
+// src/types/transport.type.ts
+function httpScheme(protocol) {
+  return protocol === "http:" ? "http:" : "https:";
+}
+function socketScheme(protocol) {
+  return protocol === "http:" ? "ws:" : "wss:";
+}
+
+// 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, protocol = "https:") {
+    this.hostnames = hostnames;
+    this.systemUuid = systemUuid;
+    this.websocketPath = websocketPath;
+    this.systemName = systemName;
+    this.retryDelay = retryDelay;
+    this.maxRetry = maxRetry;
+    this.logger = logger;
+    this.protocol = protocol;
+    // compatibility properties
+    this.opened = new BehaviorSubject(false);
+    this.closed = new Subject();
+    this.hostname = new BehaviorSubject("");
+    this.connectionAttempts = new BehaviorSubject(0);
+    this.lastErrorMessage = new BehaviorSubject(null);
+    /**
+     * emits when the connection is manually closed.
+     */
+    this.closeConnection = new 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 BehaviorSubject(false);
+    /**
+     * observable which emits the current gate value and only emits again when it changes.
+     */
+    this.enabledChange$ = this.enabled$.pipe(distinctUntilChanged());
+    /**
+     * observable that handles the entire connection lifecycle.
+     */
+    this.connection$ = this.enabledChange$.pipe(
+      switchMap((enabled) => {
+        if (enabled) {
+          return this.connect().pipe(
+            map((conn) => makeActiveConnection(conn.ws, conn.hostname))
+          );
+        }
+        return of(closedConnection);
+      }),
+      switchMap((connection) => {
+        if (connection.state !== "active") {
+          return of(connection);
+        }
+        const initMessage = createJsonRpcMessage("core.set_options", [
+          { legacy_jobs: false }
+        ]);
+        connection.ws.next(initMessage);
+        return connection.ws.messages().pipe(
+          filter((msg) => msg.id === initMessage.id),
+          take(1),
+          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.
+      catchError$1((err) => {
+        this.logger.error("All connections failed - retrying", { message: err?.message, hostname: err?.hostname });
+        return concat(
+          of(makeConnectionError(err.message, err.hostname)),
+          // since this error will immediately get caught by `retry` there's no reason to build a real error.
+          throwError(() => null)
+        );
+      }),
+      retry(),
+      // start with a closed connection.
+      startWith(closedConnection),
+      // prevent multiple subscriptions from re-evaluating the entire pipeline.
+      shareReplay$1({ bufferSize: 1, refCount: false }),
+      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(
+      map((conn) => conn.state === "active" ? conn.ws : null)
+    );
+    /**
+     * current hostname we used to build the URL for this connection.
+     */
+    this.hostname$ = this.connection$.pipe(
+      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(
+      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(
+      map((conn) => conn.state),
+      distinctUntilChanged(),
+      map((state) => state === "active")
+    );
+    /**
+     * emits when the connection state goes from open to closed.
+     */
+    this.closed$ = this.connection$.pipe(
+      map((conn) => conn.state),
+      distinctUntilChanged(),
+      filter((state) => state === "closed" || state === "error"),
+      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(
+      map((conn) => conn.state === "error"),
+      takeUntil(this.closeConnection)
+    );
+    /**
+     * observable which always emits messages from the current socket.
+     */
+    this.messages$ = this.ws$.pipe(
+      filter((ws) => ws !== null),
+      switchMap((ws) => ws.messages().pipe(
+        catchError$1(() => EMPTY)
+      ))
+    );
+    combineLatest([
+      interval(twentySeconds),
+      this.ws$
+    ]).pipe(
+      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(filter(Boolean)).subscribe((name) => this.hostname.next(name));
+    this.ws$.pipe(filter(Boolean)).subscribe((ws) => this.ws = ws);
+    this.lastErrorMessage$.subscribe((msg) => this.lastErrorMessage.next(msg));
+    this.enabled$.next(initialEnabled);
+  }
   /**
-   * Minimum supported API version. Systems below it are rejected.
-   *
-   * DERIVED, not declared. The client supports exactly the versions it ships
-   * types for, so the oldest generated version *is* the minimum — there is no
-   * second decision to make, and therefore nothing to keep in sync.
+   * 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.)
    *
-   * To move the floor, change `--min-version` in the `generate:api` script in
-   * package.json and regenerate; this follows on its own. Written as a literal
-   * it would duplicate that value with nothing enforcing agreement, so raising
-   * one and forgetting the other would silently keep generating types for
-   * versions the client rejects.
+   * `true` when the lifetime `connectionAttempts` count exceeds `hostnames.length * maxRetry`,
+   * OR when an error message is currently set. Ported from the source (tncui) behavior.
    */
-  MIN_SUPPORTED_VERSION: SUPPORTED_API_VERSIONS[0],
+  hasExhaustedRetries() {
+    const attemptsExhausted = this.connectionAttempts.value > this.hostnames.length * this.maxRetry;
+    const hasErrorMessage = this.lastErrorMessage.value !== null;
+    return attemptsExhausted || hasErrorMessage;
+  }
   /**
-   * Maximum supported API version. Systems above it are rejected.
-   *
-   * NOT derived, deliberately — and for a different reason than it used to
-   * lag. It sat at v26.0.0 while types for v27 already shipped, because
-   * `CLIENT_BY_VERSION_KEY` had no `27` and a v27 system would have passed the
-   * range check only to throw on client selection. `TrueNasApiClientV27` now
-   * exists, so this moves up with it.
-   *
-   * What it must not become is `SUPPORTED_API_VERSIONS[length - 1]`, the mirror
-   * of how MIN is derived. MIN is safe to derive because the oldest generated
-   * version always has a client — it is the floor the clients were built from.
-   * The ceiling is not symmetric: generating types for v28 does not write a v28
-   * client, so deriving this would re-create the exact gap described above on
-   * the next regeneration, silently. The real invariant is "the newest version
-   * a client can be built for", which lives in `CLIENT_BY_VERSION_KEY`; a
-   * factory test asserts the two agree, which is the check that keeps this
-   * literal honest without importing the factory here.
+   * enables or disables the connection gate. the app calls this when its `SystemState`
+   * changes (mapping `SystemState.Active -> true`, everything else -> `false`).
    */
-  MAX_SUPPORTED_VERSION: "v27.0.0",
+  setEnabled(enabled) {
+    this.enabled$.next(enabled);
+  }
   /**
-   * 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).
+   * 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.
    */
-  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;
+  messages() {
+    return this.messages$;
   }
-  if (a.minor !== b.minor) {
-    return a.minor - b.minor;
+  /**
+   * 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(
+      filter((ws) => ws !== null),
+      take(1)
+    ).subscribe((ws) => ws.next(message));
   }
-  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 */;
+  /**
+   * manually closes this connection and prevents it from retrying/opening any more.
+   */
+  close() {
+    this.closeConnection.next();
+    this.closeConnection.complete();
   }
-  if (compareVersions(version, minVersion) < 0) {
-    return "too-old" /* TooOld */;
+  /**
+   * 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 = `${socketScheme(this.protocol)}//${hostname}${this.websocketPath}`;
+    let hasOpened = false;
+    return new Observable((subscriber) => {
+      const ws = new TrueNasSocket({
+        url,
+        openObserver: {
+          next: () => {
+            hasOpened = true;
+            this.connectionAttempts.next(0);
+            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
+      timeout({ first: tenSeconds }),
+      retry({
+        //   * while still *establishing*: wait `retryDelay` before trying again, giving up
+        //     after `maxRetry` retries.
+        count: this.maxRetry,
+        //   * we use a custom `delay` function here to ensure no retries are performed
+        //     once a socket is *opened*.
+        //     basically: a later death must propagate out rather than being retried
+        //     so it can be handled by the `connection$` observable.
+        delay: (error) => {
+          if (hasOpened) {
+            return throwError(() => error);
+          }
+          return timer(this.retryDelay);
+        }
+      })
+    );
   }
-  if (compareVersions(version, maxVersion) > 0) {
-    return "too-new" /* TooNew */;
+  /**
+   * helper function which actually performs the parallel connection `race`.
+   */
+  connect() {
+    return race(
+      this.hostnames.map(this.createSocket.bind(this))
+    ).pipe(
+      tap((conn) => this.logger.debug(`TrueNas socket opened to ${conn.hostname}.`)),
+      takeUntil(this.closeConnection)
+    );
   }
-  return "compatible" /* Compatible */;
-}
-function isVersionSupported(version) {
-  return checkVersionCompatibility(version) === "compatible" /* Compatible */;
-}
-function filterCompatibleVersions(versions) {
-  return versions.filter(isVersionSupported);
-}
-function getWebSocketPath(version) {
-  return version.websocketPath;
-}
+};
+var makeActiveConnection = (ws, hostname) => ({
+  ws,
+  hostname,
+  state: "active"
+});
+var makeConnectionError = (message, hostname) => ({
+  name: "ConnectionError",
+  message,
+  hostname,
+  state: "error"
+});
+var closedConnection = { state: "closed" };
 
 // src/client/truenas-api-client.ts
 var TrueNasApiClient = class {
@@ -3074,7 +3182,7 @@ var TrueNasApiClient = class {
    * Override in subclasses to provide version-specific authentication.
    */
   createAuthenticator() {
-    return new TrueNasAuthenticator(this.connection);
+    return new TrueNasAuthenticator(this.connection, this.version);
   }
 };