@truenas/api-client 9.0.1 → 9.0.3

package/README.md

@@ -71,15 +71,18 @@ promise.
 
 | Method | Use it for |
 |---|---|
-| `loginWithUserPass(username, password)` | Interactive logins. Resolves with `response_type: 'OTP_REQUIRED'` when two-factor is on. |
+| `loginWithUserPass(username, password, options?)` | Interactive logins. Resolves with `response_type: 'OTP_REQUIRED'` when two-factor is on. Pass `{ rememberPassword: false }` to keep the password out of memory once the login succeeds. |
 | `loginWithOtp(code)` | The second step of a two-factor login. |
 | `loginWithApiKey({ username, key })` | Services and scripts. |
 | `loginWithToken(token)` | Opening another session from a previous login's `reconnect_token`. |
 
 All four live on `client.authenticator`. Password and API-key sessions log back
-in by themselves after a reconnect. `authenticated$` tracks the session,
-`logout()` ends it, and a rejected login errors with an `AuthError` carrying an
-`AuthErrorCode`.
+in by themselves after a reconnect, unless the password login passed
+`rememberPassword: false`; a token session is the caller's to restore.
+`authenticated$` tracks the session, `logout()` ends it, and a rejected login
+errors with an `AuthError` carrying an `AuthErrorCode`, plus the refusing
+`response` when middleware answered with one (`response.response_type` tells
+`EXPIRED`, `DENIED` and `REDIRECT` apart from `AUTH_ERR`).
 
 ## Calls
 
@@ -168,6 +171,21 @@ client you get. A named `version` skips discovery and also selects the
 WebSocket endpoint, so name the version the appliance actually runs. The types
 follow it when the version is a literal.
 
+To be written against one version but run against whatever the appliance
+serves, as an appliance's own UI is, keep the `version` and move the socket:
+
+```typescript
+const client = await createTrueNasClient({
+  ...options,
+  version: 'v28.0.0',            // the surface you compile against
+  websocketPath: '/api/current', // the appliance's newest version, whichever it is
+});
+```
+
+The client then works against an older or newer release call for call; a
+method or field that release lacks fails when it is called rather than at
+compile time.
+
 For code that must run against any supported release, use `client.ops`. It
 offers the same calls on every version and maps them onto whatever that version
 provides:

package/dist/{chunk-U6V2Y3AE.cjs → chunk-DJCZ545I.cjs}

@@ -2193,9 +2193,16 @@ var AuthErrorCode = /* @__PURE__ */ ((AuthErrorCode2) => {
   return AuthErrorCode2;
 })(AuthErrorCode || {});
 var AuthError = class _AuthError extends Error {
-  constructor(code, message) {
+  /**
+   * @param response - the answer middleware refused the login with, when there was one.
+   * Its `response_type` is what tells `EXPIRED`, `DENIED` and `REDIRECT` apart from
+   * `AUTH_ERR`; the code alone says only which mechanism failed. Absent when the login
+   * never got an answer of that kind (an error frame, or a superseded login).
+   */
+  constructor(code, message, response) {
     super(message);
     this.code = code;
+    this.response = response;
     this.name = "AuthError";
     Object.setPrototypeOf(this, _AuthError.prototype);
   }
@@ -2733,7 +2740,7 @@ function getWebSocketPath(version) {
 // 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.throwError(() => new AuthError(code, message, response));
   }
   return rxjs.of(response);
 });
@@ -2870,7 +2877,8 @@ var TrueNasAuthenticator = class _TrueNasAuthenticator {
     }
     this.authenticating$.next(false);
   }
-  loginWithUserPass(username, password) {
+  loginWithUserPass(username, password, options = {}) {
+    const { rememberPassword = true } = options;
     const { sentDuring, callerInitiated } = this.beginLogin();
     let answered = false;
     const message = createJsonRpcMessage("auth.login_ex", [
@@ -2906,9 +2914,11 @@ var TrueNasAuthenticator = class _TrueNasAuthenticator {
       rxjs.tap((res) => {
         if (res.response_type === "SUCCESS" /* Success */) {
           this.assertNotSuperseded(sentDuring);
-          this.credentials = { username, password, key: "" };
+          this.credentials = rememberPassword ? { username, password, key: "" } : { username: "", password: "", key: "" };
           this.sessionLifetime = res.user_info?.attributes?.preferences?.lifetime ?? _TrueNasAuthenticator.DefaultSessionLifetime;
           this.authenticated$.next(true);
+        } else if (res.response_type === "OTP_REQUIRED" /* OtpRequired */ && !rememberPassword && this.authEpoch === sentDuring) {
+          this.credentials = { username: "", password: "", key: "" };
         }
       }),
       rxjs.finalize(() => {
@@ -3006,7 +3016,8 @@ var TrueNasAuthenticator = class _TrueNasAuthenticator {
         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.`
+            `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.`,
+            res
           );
         }
         return res;
@@ -4297,6 +4308,11 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
+  if (opts.websocketPath !== void 0 && !opts.websocketPath.startsWith("/")) {
+    throw new Error(
+      `Cannot create client for system ${uuid}: websocketPath must be an absolute path, got '${opts.websocketPath}'.`
+    );
+  }
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
     hostnames: hostnames.join(", "),
@@ -4326,7 +4342,7 @@ async function createTrueNasClient(opts) {
     logger.info("API version supplied by the caller, skipping discovery", {
       uuid: uuid.slice(0, 8),
       version: known.version,
-      websocketPath: known.websocketPath
+      websocketPath: opts.websocketPath ?? known.websocketPath
     });
     return instantiateClientForVersion(known, opts, logger);
   }
@@ -4345,7 +4361,7 @@ async function createTrueNasClient(opts) {
       // of them anyway.
       hostname: winner.hostname,
       version: version.version,
-      websocketPath: version.websocketPath
+      websocketPath: opts.websocketPath ?? version.websocketPath
     });
   } catch (error) {
     const errorMessage = errorMessageOrDefault(error, "Unknown error");
@@ -4471,6 +4487,7 @@ function clientClassFor(version) {
 function instantiateClientForVersion(version, opts, logger) {
   const { uuid, hostnames, enabled, systemName } = opts;
   const versionKey = clientVersionKey(version);
+  const endpoint = opts.websocketPath === void 0 ? version : { ...version, websocketPath: opts.websocketPath };
   const Client = CLIENT_BY_VERSION_KEY[versionKey];
   if (!Client) {
     logger.error("No client implementation for version", {
@@ -4485,12 +4502,13 @@ function instantiateClientForVersion(version, opts, logger) {
   logger.info(`Instantiating ${Client.name}`, {
     uuid: uuid.slice(0, 8),
     version: version.version,
-    versionKey
+    versionKey,
+    websocketPath: endpoint.websocketPath
   });
   return new Client(
     uuid,
     hostnames,
-    version,
+    endpoint,
     enabled,
     systemName,
     logger,
@@ -4557,5 +4575,5 @@ exports.v25_10_4_exports = v25_10_4_exports;
 exports.v25_10_5_exports = v25_10_5_exports;
 exports.v27_0_0_exports = v27_0_0_exports;
 exports.v28_0_0_exports = v28_0_0_exports;
-//# sourceMappingURL=chunk-U6V2Y3AE.cjs.map
-//# sourceMappingURL=chunk-U6V2Y3AE.cjs.map
+//# sourceMappingURL=chunk-DJCZ545I.cjs.map
+//# sourceMappingURL=chunk-DJCZ545I.cjs.map