@truenas/api-client 3.0.4 → 3.0.5

package/dist/index.d.cts

@@ -12798,6 +12798,49 @@ declare class TrueNasApi<D extends ApiDirectoryShape = BaseApiDirectory> {
     private initializeJobEventsSubscription;
 }
 
+/**
+ * Response from the /api/versions endpoint
+ * Returns an array of version strings directly
+ * Example: ["v25.10.0", "v25.10.1", "v26.0.0"]
+ */
+type ApiVersionResponse = string[];
+/**
+ * Parsed API version information
+ *
+ * Version format:
+ * - Legacy (v25.x): vYY.MM.PATCH (e.g., v25.10.0 = October 2025, patch 0)
+ * - New (v26+): vYY.MINOR.PATCH (e.g., v26.0.0 = 2026, minor 0, patch 0)
+ *
+ * Note: The second segment has different semantics based on the year:
+ * - Year 25: month (1-12)
+ * - Year 26+: minor version (0-99)
+ */
+interface ApiVersion {
+    /** Full version string (e.g., "v26.0.0") */
+    version: string;
+    /** Two-digit year (e.g., 26 = 2026) */
+    year: number;
+    /**
+     * Second version segment (semantics depend on year):
+     * - For v25.x: month (1-12, e.g., 10 = October)
+     * - For v26+: minor version (0-99)
+     */
+    minor: number;
+    /** Patch version number (e.g., 0, 1, 2) */
+    patch: number;
+    /** WebSocket path for this version (e.g., "/api/v26.0.0") */
+    websocketPath: string;
+}
+/**
+ * Version compatibility status
+ */
+declare enum VersionCompatibility {
+    Compatible = "compatible",
+    TooOld = "too-old",
+    TooNew = "too-new",
+    Invalid = "invalid"
+}
+
 interface ApiKeyCreate {
     id: number;
     key: string;
@@ -12824,6 +12867,24 @@ interface AuthResponse {
     response_type: AuthResponseType;
     username?: string;
     authenticator?: 'LEVEL_1' | 'LEVEL_2' | 'LEVEL_3';
+    /**
+     * A token for re-authenticating without credentials.
+     *
+     * Absent below v26: `AuthRespSuccess` there declares only `response_type`,
+     * `user_info` and `authenticator`. From v26 it is always present and is
+     * `null` when no token was minted — because none was asked for, or because
+     * the session cannot have one. Middleware refuses for a session authenticated
+     * by a one-time *password* (`auth.generate_onetime_password`), which is not
+     * the same thing as 2FA despite this codebase spelling 2FA "OTP" throughout.
+     *
+     * A 2FA account gets `null` for a different reason, and it is this client's
+     * doing rather than the server's: the password request carrying the option is
+     * answered `OTP_REQUIRED` before anything is minted, and `loginWithOtp` does
+     * not send `login_options` on the second step. Middleware would honour it
+     * there — `auth.login_ex_continue` re-enters `login_ex`, and a 2FA session
+     * may hold a token — so this is a gap to close, not a limit to work around.
+     */
+    reconnect_token?: string | null;
     max_session_age?: number;
     max_inactivity?: number;
     urls?: string[];
@@ -12877,6 +12938,7 @@ interface AuthResponse {
  */
 declare class TrueNasAuthenticator {
     private connection;
+    private readonly version?;
     static readonly DefaultSessionLifetime = 300;
     /**
      * whether or not the system is currently authenticated and accessible.
@@ -12896,9 +12958,54 @@ declare class TrueNasAuthenticator {
         key: string;
     };
     sessionLifetime: number;
-    constructor(connection: TrueNasConnection);
+    constructor(connection: TrueNasConnection, version?: ApiVersion | undefined);
+    /**
+     * `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.
+     */
+    private reconnectTokenOption;
     loginWithUserPass(username: string, password: string): rxjs.Observable<AuthResponse>;
     loginWithOtp(code: string): rxjs.Observable<AuthResponse>;
+    /**
+     * 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: string): rxjs.Observable<AuthResponse>;
+    /**
+     * 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: {
         username: string;
         key: string;
@@ -12907,49 +13014,6 @@ declare class TrueNasAuthenticator {
     logout(): rxjs.Observable<boolean>;
 }
 
-/**
- * Response from the /api/versions endpoint
- * Returns an array of version strings directly
- * Example: ["v25.10.0", "v25.10.1", "v26.0.0"]
- */
-type ApiVersionResponse = string[];
-/**
- * Parsed API version information
- *
- * Version format:
- * - Legacy (v25.x): vYY.MM.PATCH (e.g., v25.10.0 = October 2025, patch 0)
- * - New (v26+): vYY.MINOR.PATCH (e.g., v26.0.0 = 2026, minor 0, patch 0)
- *
- * Note: The second segment has different semantics based on the year:
- * - Year 25: month (1-12)
- * - Year 26+: minor version (0-99)
- */
-interface ApiVersion {
-    /** Full version string (e.g., "v26.0.0") */
-    version: string;
-    /** Two-digit year (e.g., 26 = 2026) */
-    year: number;
-    /**
-     * Second version segment (semantics depend on year):
-     * - For v25.x: month (1-12, e.g., 10 = October)
-     * - For v26+: minor version (0-99)
-     */
-    minor: number;
-    /** Patch version number (e.g., 0, 1, 2) */
-    patch: number;
-    /** WebSocket path for this version (e.g., "/api/v26.0.0") */
-    websocketPath: string;
-}
-/**
- * Version compatibility status
- */
-declare enum VersionCompatibility {
-    Compatible = "compatible",
-    TooOld = "too-old",
-    TooNew = "too-new",
-    Invalid = "invalid"
-}
-
 /**
  * The state `Container.status` is narrowed to.
  *
@@ -28043,6 +28107,7 @@ declare enum AuthErrorCode {
     PasswordAuthFailed = "PASSWORD_AUTH_FAILED",
     OtpAuthFailed = "OTP_AUTH_FAILED",
     ApiKeyAuthFailed = "API_KEY_AUTH_FAILED",
+    TokenAuthFailed = "TOKEN_AUTH_FAILED",
     FullAdminRequired = "FULL_ADMIN_REQUIRED"
 }
 declare class AuthError extends Error {

package/dist/index.d.ts

@@ -12798,6 +12798,49 @@ declare class TrueNasApi<D extends ApiDirectoryShape = BaseApiDirectory> {
     private initializeJobEventsSubscription;
 }
 
+/**
+ * Response from the /api/versions endpoint
+ * Returns an array of version strings directly
+ * Example: ["v25.10.0", "v25.10.1", "v26.0.0"]
+ */
+type ApiVersionResponse = string[];
+/**
+ * Parsed API version information
+ *
+ * Version format:
+ * - Legacy (v25.x): vYY.MM.PATCH (e.g., v25.10.0 = October 2025, patch 0)
+ * - New (v26+): vYY.MINOR.PATCH (e.g., v26.0.0 = 2026, minor 0, patch 0)
+ *
+ * Note: The second segment has different semantics based on the year:
+ * - Year 25: month (1-12)
+ * - Year 26+: minor version (0-99)
+ */
+interface ApiVersion {
+    /** Full version string (e.g., "v26.0.0") */
+    version: string;
+    /** Two-digit year (e.g., 26 = 2026) */
+    year: number;
+    /**
+     * Second version segment (semantics depend on year):
+     * - For v25.x: month (1-12, e.g., 10 = October)
+     * - For v26+: minor version (0-99)
+     */
+    minor: number;
+    /** Patch version number (e.g., 0, 1, 2) */
+    patch: number;
+    /** WebSocket path for this version (e.g., "/api/v26.0.0") */
+    websocketPath: string;
+}
+/**
+ * Version compatibility status
+ */
+declare enum VersionCompatibility {
+    Compatible = "compatible",
+    TooOld = "too-old",
+    TooNew = "too-new",
+    Invalid = "invalid"
+}
+
 interface ApiKeyCreate {
     id: number;
     key: string;
@@ -12824,6 +12867,24 @@ interface AuthResponse {
     response_type: AuthResponseType;
     username?: string;
     authenticator?: 'LEVEL_1' | 'LEVEL_2' | 'LEVEL_3';
+    /**
+     * A token for re-authenticating without credentials.
+     *
+     * Absent below v26: `AuthRespSuccess` there declares only `response_type`,
+     * `user_info` and `authenticator`. From v26 it is always present and is
+     * `null` when no token was minted — because none was asked for, or because
+     * the session cannot have one. Middleware refuses for a session authenticated
+     * by a one-time *password* (`auth.generate_onetime_password`), which is not
+     * the same thing as 2FA despite this codebase spelling 2FA "OTP" throughout.
+     *
+     * A 2FA account gets `null` for a different reason, and it is this client's
+     * doing rather than the server's: the password request carrying the option is
+     * answered `OTP_REQUIRED` before anything is minted, and `loginWithOtp` does
+     * not send `login_options` on the second step. Middleware would honour it
+     * there — `auth.login_ex_continue` re-enters `login_ex`, and a 2FA session
+     * may hold a token — so this is a gap to close, not a limit to work around.
+     */
+    reconnect_token?: string | null;
     max_session_age?: number;
     max_inactivity?: number;
     urls?: string[];
@@ -12877,6 +12938,7 @@ interface AuthResponse {
  */
 declare class TrueNasAuthenticator {
     private connection;
+    private readonly version?;
     static readonly DefaultSessionLifetime = 300;
     /**
      * whether or not the system is currently authenticated and accessible.
@@ -12896,9 +12958,54 @@ declare class TrueNasAuthenticator {
         key: string;
     };
     sessionLifetime: number;
-    constructor(connection: TrueNasConnection);
+    constructor(connection: TrueNasConnection, version?: ApiVersion | undefined);
+    /**
+     * `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.
+     */
+    private reconnectTokenOption;
     loginWithUserPass(username: string, password: string): rxjs.Observable<AuthResponse>;
     loginWithOtp(code: string): rxjs.Observable<AuthResponse>;
+    /**
+     * 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: string): rxjs.Observable<AuthResponse>;
+    /**
+     * 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: {
         username: string;
         key: string;
@@ -12907,49 +13014,6 @@ declare class TrueNasAuthenticator {
     logout(): rxjs.Observable<boolean>;
 }
 
-/**
- * Response from the /api/versions endpoint
- * Returns an array of version strings directly
- * Example: ["v25.10.0", "v25.10.1", "v26.0.0"]
- */
-type ApiVersionResponse = string[];
-/**
- * Parsed API version information
- *
- * Version format:
- * - Legacy (v25.x): vYY.MM.PATCH (e.g., v25.10.0 = October 2025, patch 0)
- * - New (v26+): vYY.MINOR.PATCH (e.g., v26.0.0 = 2026, minor 0, patch 0)
- *
- * Note: The second segment has different semantics based on the year:
- * - Year 25: month (1-12)
- * - Year 26+: minor version (0-99)
- */
-interface ApiVersion {
-    /** Full version string (e.g., "v26.0.0") */
-    version: string;
-    /** Two-digit year (e.g., 26 = 2026) */
-    year: number;
-    /**
-     * Second version segment (semantics depend on year):
-     * - For v25.x: month (1-12, e.g., 10 = October)
-     * - For v26+: minor version (0-99)
-     */
-    minor: number;
-    /** Patch version number (e.g., 0, 1, 2) */
-    patch: number;
-    /** WebSocket path for this version (e.g., "/api/v26.0.0") */
-    websocketPath: string;
-}
-/**
- * Version compatibility status
- */
-declare enum VersionCompatibility {
-    Compatible = "compatible",
-    TooOld = "too-old",
-    TooNew = "too-new",
-    Invalid = "invalid"
-}
-
 /**
  * The state `Container.status` is narrowed to.
  *
@@ -28043,6 +28107,7 @@ declare enum AuthErrorCode {
     PasswordAuthFailed = "PASSWORD_AUTH_FAILED",
     OtpAuthFailed = "OTP_AUTH_FAILED",
     ApiKeyAuthFailed = "API_KEY_AUTH_FAILED",
+    TokenAuthFailed = "TOKEN_AUTH_FAILED",
     FullAdminRequired = "FULL_ADMIN_REQUIRED"
 }
 declare class AuthError extends Error {