@esri/arcgis-rest-basemap-sessions 1.0.0 → 4.8.0

package/dist/bundled/basemap-sessions.umd.js

@@ -1,376 +1,420 @@
 /* @preserve
-* @esri/arcgis-rest-basemap-sessions - v1.0.0 - Apache-2.0
-* Copyright (c) 2017-2025 Esri, Inc.
-* Wed Jul 30 2025 12:24:38 GMT-0700 (Pacific Daylight Time)
+* @esri/arcgis-rest-basemap-sessions - v4.8.0 - Apache-2.0
+* Copyright (c) 2017-2026 Esri, Inc.
+* Fri Jan 16 2026 01:29:33 GMT+0000 (Coordinated Universal Time)
 */
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@esri/arcgis-rest-request')) :
-  typeof define === 'function' && define.amd ? define(['exports', '@esri/arcgis-rest-request'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.arcgisRest = global.arcgisRest || {}, global.arcgisRest));
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@esri/arcgis-rest-request')) :
+    typeof define === 'function' && define.amd ? define(['exports', '@esri/arcgis-rest-request'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.arcgisRest = global.arcgisRest || {}, global.arcgisRest));
 })(this, (function (exports, arcgisRestRequest) { 'use strict';
 
-  function mitt(n){return {all:n=n||new Map,on:function(t,e){var i=n.get(t);i?i.push(e):n.set(t,[e]);},off:function(t,e){var i=n.get(t);i&&(e?i.splice(i.indexOf(e)>>>0,1):n.set(t,[]));},emit:function(t,e){var i=n.get(t);i&&i.slice().map(function(n){n(e);}),(i=n.get("*"))&&i.slice().map(function(n){n(t,e);});}}}
+    function mitt(n){return {all:n=n||new Map,on:function(t,e){var i=n.get(t);i?i.push(e):n.set(t,[e]);},off:function(t,e){var i=n.get(t);i&&(e?i.splice(i.indexOf(e)>>>0,1):n.set(t,[]));},emit:function(t,e){var i=n.get(t);i&&i.slice().map(function(n){n(e);}),(i=n.get("*"))&&i.slice().map(function(n){n(t,e);});}}}
 
-  const DEFAULT_START_BASEMAP_STYLE_SESSION_URL = "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/sessions/start";
-  const DEFAULT_SAFETY_MARGIN = 5 * 60; // Default to 5 minutes in seconds
-  const DEFAULT_CHECK_EXPIRATION_INTERVAL = 10; // Default to 10 seconds
-  const DEFAULT_DURATION = 12 * 60 * 60; // Default to 12 hours in seconds
+    const DEFAULT_START_BASEMAP_STYLE_SESSION_URL = "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/sessions/start";
+    const DEFAULT_SAFETY_MARGIN = 5 * 60; // Default to 5 minutes in seconds
+    const DEFAULT_CHECK_EXPIRATION_INTERVAL = 10; // Default to 10 seconds
+    const DEFAULT_DURATION = 12 * 60 * 60; // Default to 12 hours in seconds
 
-  function startNewSession({ startSessionUrl, authentication, styleFamily = "arcgis", duration = DEFAULT_DURATION }) {
-      return arcgisRestRequest.request(startSessionUrl, {
-          httpMethod: "GET",
-          authentication: authentication,
-          params: { styleFamily, durationSeconds: duration }
-      });
-  }
+    function startNewSession({ startSessionUrl, authentication, styleFamily = "arcgis", duration = DEFAULT_DURATION }) {
+        return arcgisRestRequest.request(startSessionUrl, {
+            httpMethod: "GET",
+            authentication: authentication,
+            params: { styleFamily, durationSeconds: duration }
+        });
+    }
 
-  function determineSafetyMargin(duration, safetyMargin) {
-      if (safetyMargin) {
-          return safetyMargin;
-      }
-      // common cases are
-      // duration is 60 seconds, this will return a 1 second safety margin
-      // duration is 43200 seconds, this will return a 300 second (5 minutes) safety margin
-      return Math.min(Math.max(duration / 100, 1), DEFAULT_SAFETY_MARGIN);
-  }
+    function determineSafetyMargin(duration, safetyMargin) {
+        if (safetyMargin) {
+            return safetyMargin;
+        }
+        // common cases are
+        // duration is 60 seconds, this will return a 1 second safety margin
+        // duration is 43200 seconds, this will return a 300 second (5 minutes) safety margin
+        return Math.min(Math.max(duration / 100, 1), DEFAULT_SAFETY_MARGIN);
+    }
 
-  /**
-   * The base class for all basemap sessions. This class implements the {@linkcode IAuthenticationManager} interface and provides methods to start, refresh, and check the expiration of a session.
-   * This is not intendet to be used directly, but instead is extended by other classes such as {@linkcode BasemapStyleSession} and {@linkcode StaticBasemapTilesSession}.
-   *
-   * @abstract
-   * @implements {IAuthenticationManager}
-   */
-  class BaseSession {
-      /**
-       * Creates a new instance of the BaseSession class. Generally you should not create an instance of this class directly, but instead use the static methods to start a session or deserialize a session.
-       *
-       * You may need to create an instance of this class directly if you are  not using the built in deserialize method.
-       *
-       * @param params - The parameters for the session.
-       * @param params.startSessionUrl - The URL to start the session.
-       * @param params.token - The token for the session.
-       * @param params.styleFamily - The style family of the session.
-       * @param params.authentication - The authentication manager or token used for the session.
-       * @param params.expires - The expiration date of the session.
-       * @param params.startTime - The start time of the session.
-       * @param params.endTime - The end time of the session.
-       * @param params.safetyMargin - The safety margin in milliseconds.
-       * @param params.duration - Indicates if this is a test session.
-       */
-      constructor(params) {
-          /**
-           * The ID of the timer used to check the expiration time of the session.
-           */
-          this.expirationTimerId = null;
-          /**
-           * A handler that is used to automatically refresh the session when it expires.
-           */
-          this.autoRefreshHandler = null;
-          this.startSessionUrl = params.startSessionUrl;
-          this.token = params.token;
-          this.styleFamily = params.styleFamily || "arcgis";
-          this.authentication = params.authentication;
-          this.duration = params.duration || DEFAULT_DURATION;
-          this.startTime = params.startTime;
-          this.endTime = params.endTime;
-          this.expires = params.expires;
-          this.safetyMargin = params.safetyMargin;
-          this.expirationCheckInterval =
-              Math.min(this.duration / 100, DEFAULT_CHECK_EXPIRATION_INTERVAL) * 1000;
-          this.emitter = mitt();
-      }
-      /**
-       * Checks if the session is expired. If it is expired, it emits an "expired" event. The event will fire **before** the method returns true.
-       *
-       * @returns {boolean} - Returns true if the session is expired, otherwise false.
-       */
-      isSessionExpired() {
-          if (this.isExpired) {
-              this.emitter.emit("expired", {
-                  token: this.token,
-                  startTime: this.startTime,
-                  endTime: this.endTime,
-                  expires: this.expires
-              });
-          }
-          return this.isExpired;
-      }
-      /**
-       * Starts checking the expiration time of the session. This will check the expiration time immediately and then on an interval.
-       * If the session is expired, it will emit an "expired" event.
-       */
-      startCheckingExpirationTime() {
-          const check = () => {
-              this.isSessionExpired();
-          };
-          if (!this.expirationTimerId) {
-              this.expirationTimerId = setInterval(check, 
-              // check every 10 seconds or 1/100th of the duration, whichever is smaller
-              this.expirationCheckInterval); // check immediatly then on an interval
-          }
-          setTimeout(() => {
-              check(); // check immediately after starting the interval
-          }, 10);
-          return this.expirationTimerId; // return the timer ID so it can be stopped later
-      }
-      /**
-       * Stops checking the expiration time of the session. This will clear the interval that was set by {@linkcode BaseSession.startCheckingExpirationTime}.
-       */
-      stopCheckingExpirationTime() {
-          if (this.expirationTimerId) {
-              clearInterval(this.expirationTimerId);
-              this.expirationTimerId = null;
-          }
-      }
-      /**
-       * Indicates if the session is currently checking for expiration time.
-       *
-       * @returns {boolean} - Returns true if the session is checking for expiration time, otherwise false.
-       */
-      get checkingExpirationTime() {
-          return !!this.expirationTimerId;
-      }
-      /**
-       * Starts a new session using the provided parameters and returns an instance of the session class.
-       *
-       * @param params - The parameters for starting the session.
-       * @param SessionClass - The class to use for the session.
-       * @returns A promise that resolves to an instance of the session class.
-       */
-      static async startSession({ startSessionUrl, styleFamily = "arcgis", authentication, safetyMargin, duration = DEFAULT_DURATION, autoRefresh = true }, SessionClass) {
-          const sessionResponse = await startNewSession({
-              startSessionUrl,
-              styleFamily,
-              authentication,
-              duration
-          });
-          const actualSafetyMargin = determineSafetyMargin(duration, safetyMargin);
-          const session = new SessionClass({
-              startSessionUrl: startSessionUrl,
-              token: sessionResponse.sessionToken,
-              styleFamily,
-              authentication,
-              safetyMargin: actualSafetyMargin,
-              expires: new Date(sessionResponse.endTime - actualSafetyMargin * 1000),
-              startTime: new Date(sessionResponse.startTime),
-              endTime: new Date(sessionResponse.endTime),
-              duration
-          });
-          session.startCheckingExpirationTime();
-          if (autoRefresh) {
-              session.startAutoRefresh();
-          }
-          return session;
-      }
-      /**
-       * Checks if the session is expired.
-       *
-       */
-      get isExpired() {
-          return this.expires < new Date();
-      }
-      /**
-       * Gets the session token. If the session is expired, it will refresh the credentials and return the new token.
-       *
-       * @returns A promise that resolves to the session token.
-       */
-      getToken() {
-          if (this.isExpired) {
-              return this.refreshCredentials().then(() => this.token);
-          }
-          return Promise.resolve(this.token);
-      }
-      /**
-       * Indicates if the session can be refreshed. This is always true for this class.
-       *
-       * @returns {boolean} - Always returns true.
-       */
-      get canRefresh() {
-          return true;
-      }
-      /**
-       * Indicates if the session is set to automatically refresh when it expires.
-       *
-       * @returns {boolean} - Returns true if auto-refresh is enabled, otherwise false.
-       */
-      get autoRefresh() {
-          return !!this.autoRefreshHandler && !!this.expirationTimerId;
-      }
-      /**
-       * Refreshes the session credentials by starting a new session.
-       * This will emit a "refreshed" event with the previous and current session details.
-       *
-       * @returns A promise that resolves to the current instance of the session.
-       */
-      async refreshCredentials() {
-          // @TODO switch this to structured clone when we upgrade to Node 20+ types so we don't have to parse the dates later
-          const previous = JSON.parse(JSON.stringify({
-              token: this.token,
-              startTime: this.startTime,
-              endTime: this.endTime,
-              expires: this.expires
-          }));
-          try {
-              const newSession = await startNewSession({
-                  startSessionUrl: this.startSessionUrl,
-                  styleFamily: this.styleFamily,
-                  authentication: this.authentication,
-                  duration: this.duration
-              });
-              this.setToken(newSession.sessionToken);
-              this.setStartTime(new Date(newSession.startTime));
-              this.setEndTime(new Date(newSession.endTime));
-              this.setExpires(new Date(newSession.endTime - this.safetyMargin * 1000));
-              this.emitter.emit("refreshed", {
-                  previous: {
-                      token: previous.token,
-                      startTime: new Date(previous.startTime),
-                      endTime: new Date(previous.endTime),
-                      expires: new Date(previous.expires)
-                  },
-                  current: {
-                      token: this.token,
-                      startTime: this.startTime,
-                      endTime: this.endTime,
-                      expires: this.expires
-                  }
-              });
-          }
-          catch (error) {
-              this.emitter.emit("error", error);
-              throw error;
-          }
-          return this;
-      }
-      /**
-       * Enables auto-refresh for the session. This will automatically refresh the session when it expires.
-       * It will also start checking the expiration time of the session if it is not already started via {@linkcode BaseSession.startCheckingExpirationTime}.
-       */
-      startAutoRefresh() {
-          if (!this.expirationTimerId) {
-              this.startCheckingExpirationTime();
-          }
-          this.autoRefreshHandler = () => {
-              this.refreshCredentials().catch((error) => {
-                  this.emitter.emit("error", error);
-              });
-          };
-          this.on("expired", this.autoRefreshHandler);
-      }
-      /**
-       * Disables auto-refresh for the session. This will stop automatically refreshing the session when it expires.
-       * This will  **not** stop checking the expiration time of the session. If you want to stop automated expiration
-       * checking, call {@linkcode BaseSession.stopCheckingExpirationTime} after calling this method.
-       */
-      stopAutoRefresh() {
-          if (this.autoRefreshHandler) {
-              this.off("expired", this.autoRefreshHandler);
-              this.autoRefreshHandler = null;
-          }
-      }
-      on(eventName, handler) {
-          this.emitter.on(eventName, handler);
-          this.isSessionExpired(); // check if the session is expired immediately after adding the handler
-      }
-      once(eventName, handler) {
-          const fn = (e) => {
-              this.emitter.off(eventName, fn);
-              handler(e);
-          };
-          this.emitter.on(eventName, fn);
-      }
-      off(eventName, handler) {
-          this.emitter.off(eventName, handler);
-      }
-      /**
-       * These private methods are used to set the internal state of the session.
-       */
-      setToken(token) {
-          this.token = token;
-      }
-      setStartTime(startTime) {
-          this.startTime = startTime;
-      }
-      setEndTime(endTime) {
-          this.endTime = endTime;
-      }
-      setExpires(expires) {
-          this.expires = expires;
-      }
-  }
-  // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
-  /* istanbul ignore next -- @preserve */
-  /**
-   * Event handler for when an error occurs during session management.
-   */
-  BaseSession.error = function error(e) { }; // eslint-disable-line @typescript-eslint/no-empty-function
-  // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
-  /* istanbul ignore next -- @preserve */
-  /**
-   * Event handler for when a session expires and the `token` it no longer valid.
-   *
-   * @event expired
-   * @param e - The parameters for the expired event.
-   * @param e.token - The session token that expired.
-   * @param e.startTime - The start time of the session.
-   * @param e.endTime - The end time of the session.
-   * @param e.expires - The expiration time of the session.
-   */
-  BaseSession.expired = function expired(e) { }; // eslint-disable-line @typescript-eslint/no-empty-function
-  // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
-  /* istanbul ignore next -- @preserve */
-  /**
-   * Event handler for when a session refreshes and a new `token` is available.
-   *
-   * @event refreshed
-   * @param e. - The parameters for the refreshed event.
-   * @param e.previous - The previous session details.
-   * @param e.previous.token - The previous session token.
-   * @param e.previous.startTime - The start time of the previous session.
-   * @param e.previous.endTime - The end time of the previous session.
-   * @param e.previous.expires - The expiration time of the previous session.
-   * @param e.current - The current session details.
-   * @param e.current.token - The current session token.
-   * @param e.current.startTime - The start time of the current token.
-   * @param e.current.endTime - The end time of the current session.
-   * @param e.current.expires - The expiration time of the current token.
-   */
-  BaseSession.refreshed = function refreshed(e) { }; // eslint-disable-line @typescript-eslint/no-empty-function
+    /**
+     * The base class for all basemap sessions. This class implements the {@linkcode @esri/arcgis-rest-request!IAuthenticationManager} interface and provides methods to start, refresh, and check the expiration of a session.
+     * This is not intended to be used directly, but instead is extended by other classes such as {@linkcode BasemapStyleSession} .
+     *
+     * @abstract
+     */
+    class BaseSession {
+        /**
+         * Creates a new instance of the BaseSession class. Generally you should not create an instance of this class directly, but instead use the static methods to start a session or deserialize a session.
+         *
+         * You may need to create an instance of this class directly if you are  not using the built in deserialize method.
+         *
+         * @param params - The parameters for the session.
+         * @param params.startSessionUrl - The URL to start the session.
+         * @param params.token - The token for the session.
+         * @param params.styleFamily - The style family of the session.
+         * @param params.authentication - The authentication manager or token used for the session.
+         * @param params.expires - The expiration date of the session.
+         * @param params.startTime - The start time of the session.
+         * @param params.endTime - The end time of the session.
+         * @param params.safetyMargin - The safety margin in milliseconds.
+         * @param params.duration - Indicates if this is a test session.
+         */
+        constructor(params) {
+            /**
+             * The ID of the timer used to check the expiration time of the session.
+             */
+            this.expirationTimerId = null;
+            /**
+             * A pending session that is being refreshed. This is used to prevent multiple refreshes from happening at the same time.
+             */
+            this.pendingSession = null;
+            /**
+             * A handler that is used to automatically refresh the session when it expires.
+             */
+            this.autoRefreshHandler = null;
+            this.startSessionUrl = params.startSessionUrl;
+            this.token = params.token;
+            this.styleFamily = params.styleFamily || "arcgis";
+            this.authentication = params.authentication;
+            this.duration = params.duration || DEFAULT_DURATION;
+            this.startTime = params.startTime;
+            this.endTime = params.endTime;
+            this.expires = params.expires;
+            this.safetyMargin = params.safetyMargin;
+            this.expirationCheckInterval =
+                Math.min(this.duration / 100, DEFAULT_CHECK_EXPIRATION_INTERVAL) * 1000;
+            this.emitter = mitt();
+        }
+        /**
+         * Checks if the session is expired. If it is expired, it emits an "expired" event and disables expiration time checking. The event will fire **before** the method returns true.
+         *
+         * @returns {boolean} - Returns true if the session is expired, otherwise false.
+         */
+        isSessionExpired() {
+            if (this.isExpired) {
+                this.disableCheckingExpirationTime();
+                this.emitter.emit("expired", {
+                    token: this.token,
+                    startTime: this.startTime,
+                    endTime: this.endTime,
+                    expires: this.expires
+                });
+            }
+            return this.isExpired;
+        }
+        /**
+         * Starts checking the expiration time of the session. This will check the expiration time immediately and then on an interval.
+         * If the session is expired, it will emit an "expired" event.
+         */
+        enableCheckingExpirationTime() {
+            const check = () => {
+                this.isSessionExpired();
+            };
+            if (!this.expirationTimerId) {
+                this.expirationTimerId = setInterval(check, 
+                // check every 10 seconds or 1/100th of the duration, whichever is smaller
+                this.expirationCheckInterval); // check immediately then on an interval
+            }
+            setTimeout(() => {
+                check(); // check immediately after starting the interval
+            }, 10);
+            return this.expirationTimerId; // return the timer ID so it can be stopped later
+        }
+        /**
+         * Stops checking the expiration time of the session. This will clear the `setInterval()` that was started by {@linkcode BaseSession.enableCheckingExpirationTime}.
+         */
+        disableCheckingExpirationTime() {
+            if (this.expirationTimerId) {
+                clearInterval(this.expirationTimerId);
+                this.expirationTimerId = null;
+            }
+        }
+        /**
+         * Starts a new session using the provided parameters and returns an instance of the session class.
+         *
+         * @param params - The parameters for starting the session.
+         * @param SessionClass - The class to use for the session.
+         * @returns A promise that resolves to an instance of the session class.
+         */
+        static async startSession({ startSessionUrl, styleFamily = "arcgis", authentication, safetyMargin, duration = DEFAULT_DURATION, autoRefresh = false }, SessionClass) {
+            if (duration < 10) {
+                throw new Error("Session duration must be at least 10 seconds.");
+            }
+            if (duration > 43200) {
+                throw new Error("Session duration cannot exceed 12 hours (43200 seconds).");
+            }
+            const sessionResponse = await startNewSession({
+                startSessionUrl,
+                styleFamily,
+                authentication,
+                duration
+            });
+            const actualSafetyMargin = determineSafetyMargin(duration, safetyMargin);
+            const session = new SessionClass({
+                startSessionUrl: startSessionUrl,
+                token: sessionResponse.sessionToken,
+                styleFamily,
+                authentication,
+                safetyMargin: actualSafetyMargin,
+                expires: new Date(sessionResponse.endTime - actualSafetyMargin * 1000),
+                startTime: new Date(sessionResponse.startTime),
+                endTime: new Date(sessionResponse.endTime),
+                duration
+            });
+            session.enableCheckingExpirationTime();
+            if (autoRefresh) {
+                session.enableAutoRefresh();
+            }
+            return session;
+        }
+        /**
+         * Indicates if the session is currently checking for expiration time.
+         *
+         * @returns {boolean} - Returns true if the session is checking for expiration time, otherwise false.
+         */
+        get checkingExpirationTime() {
+            return !!this.expirationTimerId;
+        }
+        /**
+         * Returns the number of seconds until the session is no longer valid rounded down. If the session is expired, it will return 0.
+         */
+        get secondsUntilExpiration() {
+            return Math.floor(this.millisecondsUntilExpiration / 1000);
+        }
+        /**
+         * Returns the number of milliseconds until the session token is no longer valid. If the session is expired, it will return 0.
+         */
+        get millisecondsUntilExpiration() {
+            if (this.isExpired) {
+                return 0;
+            }
+            const now = new Date();
+            const millisecondsLeft = this.endTime.getTime() - now.getTime();
+            return millisecondsLeft;
+        }
+        /**
+         * Checks if the session is expired.
+         *
+         */
+        get isExpired() {
+            return this.expires < new Date();
+        }
+        /**
+         * Gets the session token. If the session is expired, it will refresh the credentials and return the new token.
+         *
+         * @returns A promise that resolves to the session token.
+         */
+        getToken() {
+            if (this.isExpired) {
+                return this.refreshCredentials().then(() => this.token);
+            }
+            return Promise.resolve(this.token);
+        }
+        /**
+         * Indicates if the session can be refreshed. This is always true for this basemap sessions.
+         *
+         * @returns {boolean} - Always returns true.
+         */
+        get canRefresh() {
+            return true;
+        }
+        /**
+         * Indicates if the session is set to automatically refresh when it expires.
+         *
+         * @returns {boolean} - Returns true if auto-refresh is enabled, otherwise false.
+         */
+        get autoRefresh() {
+            return !!this.autoRefreshHandler && !!this.expirationTimerId;
+        }
+        /**
+         * Refreshes the session credentials by starting a new session.
+         * This will emit a "refreshed" event with the previous and current session details.
+         *
+         * @returns A promise that resolves to the current instance of the session.
+         */
+        async refreshCredentials() {
+            if (this.pendingSession) {
+                // if there is a pending session, wait for it to resolve
+                await this.pendingSession;
+                return this;
+            }
+            // @TODO switch this to structured clone when we upgrade to Node 20+ types so we don't have to parse the dates later
+            const previous = JSON.parse(JSON.stringify({
+                token: this.token,
+                startTime: this.startTime,
+                endTime: this.endTime,
+                expires: this.expires
+            }));
+            try {
+                this.pendingSession = startNewSession({
+                    startSessionUrl: this.startSessionUrl,
+                    styleFamily: this.styleFamily,
+                    authentication: this.authentication,
+                    duration: this.duration
+                });
+                const newSession = await this.pendingSession;
+                this.pendingSession = null; // reset the pending session
+                this.setToken(newSession.sessionToken);
+                this.setStartTime(new Date(newSession.startTime));
+                this.setEndTime(new Date(newSession.endTime));
+                this.setExpires(new Date(newSession.endTime - this.safetyMargin * 1000));
+                this.enableCheckingExpirationTime(); // restart checking expiration time after refreshing credentials
+                this.emitter.emit("refreshed", {
+                    previous: {
+                        token: previous.token,
+                        startTime: new Date(previous.startTime),
+                        endTime: new Date(previous.endTime),
+                        expires: new Date(previous.expires)
+                    },
+                    current: {
+                        token: this.token,
+                        startTime: this.startTime,
+                        endTime: this.endTime,
+                        expires: this.expires
+                    }
+                });
+            }
+            catch (error) {
+                this.emitter.emit("error", error);
+                throw error;
+            }
+            return this;
+        }
+        /**
+         * Enables auto-refresh for the session. This will automatically refresh the session when it expires.
+         * It will also start checking the expiration time of the session if it is not already started via {@linkcode BaseSession.enableCheckingExpirationTime}.
+         */
+        enableAutoRefresh() {
+            if (!this.expirationTimerId) {
+                this.enableCheckingExpirationTime();
+            }
+            this.autoRefreshHandler = () => {
+                this.refreshCredentials().catch((error) => {
+                    this.emitter.emit("error", error);
+                });
+            };
+            this.on("expired", this.autoRefreshHandler);
+        }
+        /**
+         * Disables auto-refresh for the session. This will stop automatically refreshing the session when it expires.
+         * This will  **not** stop checking the expiration time of the session. If you want to stop automated expiration
+         * checking, call {@linkcode BaseSession.disableCheckingExpirationTime} after calling this method.
+         */
+        disableAutoRefresh() {
+            if (this.autoRefreshHandler) {
+                this.off("expired", this.autoRefreshHandler);
+                this.autoRefreshHandler = null;
+            }
+        }
+        /**
+         * Removes all event listeners and disables auto-refresh and expiration time checking. This is useful for cleaning up the session when it is no longer needed or replaced with a new session.
+         */
+        destroy() {
+            this.disableAutoRefresh();
+            this.disableCheckingExpirationTime();
+            this.emitter.off("expired");
+            this.emitter.off("refreshed");
+            this.emitter.off("error");
+            this.emitter.off("*");
+        }
+        on(event, handler) {
+            this.emitter.on(event, handler);
+            this.isSessionExpired(); // check if the session is expired immediately after adding the handler
+        }
+        once(event, handler) {
+            const fn = (e) => {
+                this.emitter.off(event, fn);
+                handler(e);
+            };
+            this.emitter.on(event, fn);
+        }
+        off(event, handler) {
+            this.emitter.off(event, handler);
+        }
+        /**
+         * These private methods are used to set the internal state of the session.
+         */
+        setToken(token) {
+            this.token = token;
+        }
+        setStartTime(startTime) {
+            this.startTime = startTime;
+        }
+        setEndTime(endTime) {
+            this.endTime = endTime;
+        }
+        setExpires(expires) {
+            this.expires = expires;
+        }
+    }
+    // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
+    /* istanbul ignore next -- @preserve */
+    /**
+     * Event handler for when an error occurs during session management.
+     */
+    BaseSession.error = function error(e) { };
+    // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
+    /* istanbul ignore next -- @preserve */
+    /**
+     * Event handler for when the current session expires and the session token it no longer valid. This event will only fire if {@linkcode BaseSession.checkingExpirationTime}
+     * is `true` which is the default. Once this event fires, {@linkcode BaseSession.checkingExpirationTime} will be set to `false` until the session is refreshed with
+     * {@linkcode BaseSession.refreshCredentials}.
+     *
+     * @event expired
+     * @param e.token - The session token that expired.
+     * @param e.startTime - The start time of the session.
+     * @param e.endTime - The end time of the session.
+     * @param e.expires - The expiration time of the session.
+     */
+    BaseSession.expired = function expired(e) { };
+    // the static methods for event handlers are used to provide doc via typedoc and do not need to be tested.
+    /* istanbul ignore next -- @preserve */
+    /**
+     * Event handler for when a session refreshes and a new `token` is available.
+     *
+     * @event refreshed
+     * @param e.previous - The previous session details.
+     * @param e.previous.token - The previous session token.
+     * @param e.previous.startTime - The start time of the previous session.
+     * @param e.previous.endTime - The end time of the previous session.
+     * @param e.previous.expires - The expiration time of the previous session.
+     * @param e.current - The current session details.
+     * @param e.current.token - The current session token.
+     * @param e.current.startTime - The start time of the current token.
+     * @param e.current.endTime - The end time of the current session.
+     * @param e.current.expires - The expiration time of the current token.
+     */
+    BaseSession.refreshed = function refreshed(e) { };
 
-  /**
-   * `BasemapStyleSession` is a class that extends {@linkcode BaseSession} to manage sessions
-   * for basemap styles. It provides methods to {@linkcode BasemapStyleSession.start} a new session
-   * which should be used instead of constructing a new instance directly.
-   *
-   * @class BasemapStyleSession
-   * @extends BaseSession
-   */
-  class BasemapStyleSession extends BaseSession {
-      /**
-       * Creates an instance of `BasemapStyleSession`. Constructing `BasemapStyleSession` directly is discouraged.
-       * Instead, use the static method {@linkcode BasemapStyleSession.start} to start a new session.
-       */
-      constructor(params) {
-          super(params);
-      }
-      /**
-       * Starts a new basemap style session.
-       */
-      static async start(params) {
-          return BaseSession.startSession(Object.assign(Object.assign({}, params), { startSessionUrl: (params === null || params === void 0 ? void 0 : params.startSessionUrl) || DEFAULT_START_BASEMAP_STYLE_SESSION_URL }), BasemapStyleSession);
-      }
-  }
+    /**
+     * `BasemapStyleSession` is a class that extends {@linkcode BaseSession} to manage sessions
+     * for basemap styles. It provides methods to {@linkcode BasemapStyleSession.start} a new session
+     * which should be used instead of constructing a new instance directly.
+     *
+     * @class BasemapStyleSession
+     * @extends BaseSession
+     */
+    class BasemapStyleSession extends BaseSession {
+        /**
+         * Creates an instance of `BasemapStyleSession`. Constructing `BasemapStyleSession` directly is discouraged.
+         * Instead, use the static method {@linkcode BasemapStyleSession.start} to start a new session.
+         */
+        constructor(params) {
+            super(params);
+        }
+        /**
+         * Starts a new basemap style session.
+         */
+        static async start(params) {
+            return BaseSession.startSession(Object.assign(Object.assign({}, params), { startSessionUrl: (params === null || params === void 0 ? void 0 : params.startSessionUrl) || DEFAULT_START_BASEMAP_STYLE_SESSION_URL }), BasemapStyleSession);
+        }
+    }
 
-  exports.BaseSession = BaseSession;
-  exports.BasemapStyleSession = BasemapStyleSession;
-  exports.DEFAULT_CHECK_EXPIRATION_INTERVAL = DEFAULT_CHECK_EXPIRATION_INTERVAL;
-  exports.DEFAULT_DURATION = DEFAULT_DURATION;
-  exports.DEFAULT_SAFETY_MARGIN = DEFAULT_SAFETY_MARGIN;
-  exports.DEFAULT_START_BASEMAP_STYLE_SESSION_URL = DEFAULT_START_BASEMAP_STYLE_SESSION_URL;
-  exports.startNewSession = startNewSession;
-
-  Object.defineProperty(exports, '__esModule', { value: true });
+    exports.BaseSession = BaseSession;
+    exports.BasemapStyleSession = BasemapStyleSession;
+    exports.DEFAULT_CHECK_EXPIRATION_INTERVAL = DEFAULT_CHECK_EXPIRATION_INTERVAL;
+    exports.DEFAULT_DURATION = DEFAULT_DURATION;
+    exports.DEFAULT_SAFETY_MARGIN = DEFAULT_SAFETY_MARGIN;
+    exports.DEFAULT_START_BASEMAP_STYLE_SESSION_URL = DEFAULT_START_BASEMAP_STYLE_SESSION_URL;
+    exports.startNewSession = startNewSession;
 
 }));
 //# sourceMappingURL=basemap-sessions.umd.js.map