@webex/webex-core 3.12.0-task-refactor.1 → 3.12.0-webex-services-ready.2

package/dist/lib/services/services.js

@@ -11,12 +11,16 @@ _Object$defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = exports.DEFAULT_CLUSTER_SERVICE = exports.DEFAULT_CLUSTER = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime-corejs2/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/asyncToGenerator"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/defineProperty"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/slicedToArray"));
 var _weakMap = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/weak-map"));
 var _entries = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/entries"));
 var _keys = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/keys"));
 var _promise = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/promise"));
+var _now = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/date/now"));
+var _stringify = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/json/stringify"));
 var _sha = _interopRequireDefault(require("crypto-js/sha256"));
 var _lodash = require("lodash");
 var _webexPlugin = _interopRequireDefault(require("../webex-plugin"));
@@ -36,6 +40,14 @@ var DEFAULT_CLUSTER = exports.DEFAULT_CLUSTER = 'urn:TEAM:us-east-2_a';
 var DEFAULT_CLUSTER_SERVICE = exports.DEFAULT_CLUSTER_SERVICE = 'identityLookup';
 var CLUSTER_SERVICE = process.env.WEBEX_CONVERSATION_CLUSTER_SERVICE || DEFAULT_CLUSTER_SERVICE;
 var DEFAULT_CLUSTER_IDENTIFIER = process.env.WEBEX_CONVERSATION_DEFAULT_CLUSTER || "".concat(DEFAULT_CLUSTER, ":").concat(CLUSTER_SERVICE);
+var CATALOG_CACHE_KEY_V1 = 'services.v1.u2cHostMap';
+var CATALOG_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+// Maximum time we will wait for the initial catalog collection before letting
+// `services.ready` (and therefore `webex.ready`) fire anyway. A hung request
+// must never leave the app on a permanent spinner - past this point downstream
+// consumers must fall through to their normal error/login paths.
+var SERVICES_INIT_TIMEOUT_MS = 15000;
 
 /* eslint-disable no-underscore-dangle */
 /**
@@ -67,6 +79,21 @@ var Services = _webexPlugin.default.extend({
     validateDomains: ['boolean', false, true],
     initFailed: ['boolean', false, false]
   },
+  session: {
+    /**
+     * Becomes `true` once the initial catalog collection has completed
+     * (successfully or otherwise) and any in-flight credentials refresh has
+     * settled. Blocks `webex.ready` so consumers can rely on `webex.ready`
+     * implying "catalogs populated AND credential state stable".
+     * @instance
+     * @memberof Services
+     * @type {boolean}
+     */
+    ready: {
+      default: false,
+      type: 'boolean'
+    }
+  },
   _catalogs: new _weakMap.default(),
   _serviceUrls: null,
   _hostCatalog: null,
@@ -101,6 +128,45 @@ var Services = _webexPlugin.default.extend({
   _getCatalog: function _getCatalog() {
     return this._catalogs.get(this.webex);
   },
+  /**
+   * Safely access localStorage if available; returns the Storage or null.
+   * @returns {Storage|null}
+   */
+  _getLocalStorageSafe: function _getLocalStorageSafe() {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      return window.localStorage;
+    }
+    return null;
+  },
+  /**
+   * Determine the intended preauth selection based on the current context.
+   * @param {string|undefined} currentOrgId
+   * @returns {{selectionType: string, selectionValue: string}}
+   */
+  getIntendedPreauthSelection: function getIntendedPreauthSelection(currentOrgId) {
+    var _this$webex$credentia;
+    if ((_this$webex$credentia = this.webex.credentials) !== null && _this$webex$credentia !== void 0 && _this$webex$credentia.canAuthorize) {
+      if (currentOrgId) {
+        return {
+          selectionType: 'orgId',
+          selectionValue: currentOrgId
+        };
+      }
+    }
+    var emailConfig = this.webex.config && this.webex.config.email;
+    if (typeof emailConfig === 'string' && emailConfig.trim()) {
+      return {
+        selectionType: 'emailhash',
+        selectionValue: (0, _sha.default)(emailConfig.toLowerCase()).toString()
+      };
+    }
+
+    // fall back to proximity mode when no orgId or email available
+    return {
+      selectionType: 'mode',
+      selectionValue: 'DEFAULT_BY_PROXIMITY'
+    };
+  },
   /**
    * Get a service url from the current services list by name
    * from the associated instance catalog.
@@ -161,9 +227,10 @@ var Services = _webexPlugin.default.extend({
   },
   /**
    * Get all Mobius cluster host entries from the legacy host catalog.
-   * @returns {Array<Object>}
+   * @returns {Array<{host: string, id: string, ttl: number, priority: number}>}
    */
   getMobiusClusters: function getMobiusClusters() {
+    this.logger.info('services: fetching mobius clusters');
     var clusters = [];
     var hostCatalog = this._hostCatalog || {};
     (0, _entries.default)(hostCatalog).forEach(function (_ref) {
@@ -197,6 +264,24 @@ var Services = _webexPlugin.default.extend({
     var hostCatalog = this._hostCatalog || {};
     return !!((_hostCatalog$host = hostCatalog[host]) !== null && _hostCatalog$host !== void 0 && _hostCatalog$host.length);
   },
+  /**
+   * Checks if the current environment is an integration (INT) environment
+   * by examining the u2c discovery URL from webex config.
+   * INT environments use discovery URLs containing 'intb' (e.g., u2c-intb.ciscospark.com).
+   * @returns {boolean} True if INT environment, false otherwise
+   */
+  isIntegrationEnvironment: function isIntegrationEnvironment() {
+    try {
+      var _this$webex, _this$webex$config, _this$webex$config$se, _this$webex$config$se2;
+      var u2cUrl = ((_this$webex = this.webex) === null || _this$webex === void 0 ? void 0 : (_this$webex$config = _this$webex.config) === null || _this$webex$config === void 0 ? void 0 : (_this$webex$config$se = _this$webex$config.services) === null || _this$webex$config$se === void 0 ? void 0 : (_this$webex$config$se2 = _this$webex$config$se.discovery) === null || _this$webex$config$se2 === void 0 ? void 0 : _this$webex$config$se2.u2c) || '';
+      var isInt = u2cUrl.includes('intb');
+      this.logger.info("services: isIntegrationEnvironment: ".concat(isInt));
+      return isInt;
+    } catch (error) {
+      this.logger.error('services: failed to determine integration environment', error);
+      return false;
+    }
+  },
   /**
    * Merge provided active cluster mappings into current state.
    * @param {Record<string,string>} activeServices
@@ -235,63 +320,88 @@ var Services = _webexPlugin.default.extend({
    * @returns {Promise<object>}
    */
   updateServices: function updateServices() {
-    var _this = this;
-    var _ref3 = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
-      from = _ref3.from,
-      query = _ref3.query,
-      token = _ref3.token,
-      forceRefresh = _ref3.forceRefresh;
-    var catalog = this._getCatalog();
-    var formattedQuery;
-    var serviceGroup;
-
-    // map catalog name to service group name.
-    switch (from) {
-      case 'limited':
-        serviceGroup = 'preauth';
-        break;
-      case 'signin':
-        serviceGroup = 'signin';
-        break;
-      default:
-        serviceGroup = 'postauth';
-        break;
-    }
-
-    // confirm catalog update for group is not in progress.
-    if (catalog.status[serviceGroup].collecting) {
-      return this.waitForCatalog(serviceGroup);
-    }
-    catalog.status[serviceGroup].collecting = true;
-    if (serviceGroup === 'preauth') {
-      var queryKey = query && (0, _keys.default)(query)[0];
-      if (!['email', 'emailhash', 'userId', 'orgId', 'mode'].includes(queryKey)) {
-        return _promise.default.reject(new Error('a query param of email, emailhash, userId, orgId, or mode is required'));
-      }
-    }
-    // encode email when query key is email
-    if (serviceGroup === 'preauth' || serviceGroup === 'signin') {
-      var _queryKey = (0, _keys.default)(query)[0];
-      formattedQuery = {};
-      if (_queryKey === 'email' && query.email) {
-        formattedQuery.emailhash = (0, _sha.default)(query.email.toLowerCase()).toString();
-      } else {
-        formattedQuery[_queryKey] = query[_queryKey];
-      }
-    }
-    return this._fetchNewServiceHostmap({
-      from: from,
-      token: token,
-      query: formattedQuery,
-      forceRefresh: forceRefresh
-    }).then(function (serviceHostMap) {
-      catalog.updateServiceUrls(serviceGroup, serviceHostMap);
-      _this.updateCredentialsConfig();
-      catalog.status[serviceGroup].collecting = false;
-    }).catch(function (error) {
-      catalog.status[serviceGroup].collecting = false;
-      return _promise.default.reject(error);
-    });
+    var _arguments = arguments,
+      _this = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee() {
+      var _ref3, from, query, token, forceRefresh, catalog, formattedQuery, serviceGroup, queryKey, _queryKey, _t;
+      return _regenerator.default.wrap(function (_context) {
+        while (1) switch (_context.prev = _context.next) {
+          case 0:
+            _ref3 = _arguments.length > 0 && _arguments[0] !== undefined ? _arguments[0] : {}, from = _ref3.from, query = _ref3.query, token = _ref3.token, forceRefresh = _ref3.forceRefresh;
+            catalog = _this._getCatalog();
+            _t = from;
+            _context.next = _t === 'limited' ? 1 : _t === 'signin' ? 2 : 3;
+            break;
+          case 1:
+            serviceGroup = 'preauth';
+            return _context.abrupt("continue", 4);
+          case 2:
+            serviceGroup = 'signin';
+            return _context.abrupt("continue", 4);
+          case 3:
+            serviceGroup = 'postauth';
+            return _context.abrupt("continue", 4);
+          case 4:
+            if (!catalog.status[serviceGroup].collecting) {
+              _context.next = 5;
+              break;
+            }
+            return _context.abrupt("return", _this.waitForCatalog(serviceGroup));
+          case 5:
+            catalog.status[serviceGroup].collecting = true;
+            if (!(serviceGroup === 'preauth')) {
+              _context.next = 6;
+              break;
+            }
+            queryKey = query && (0, _keys.default)(query)[0];
+            if (['email', 'emailhash', 'userId', 'orgId', 'mode'].includes(queryKey)) {
+              _context.next = 6;
+              break;
+            }
+            return _context.abrupt("return", _promise.default.reject(new Error('a query param of email, emailhash, userId, orgId, or mode is required')));
+          case 6:
+            // encode email when query key is email
+            if (serviceGroup === 'preauth' || serviceGroup === 'signin') {
+              _queryKey = (0, _keys.default)(query)[0];
+              formattedQuery = {};
+              if (_queryKey === 'email' && query.email) {
+                formattedQuery.emailhash = (0, _sha.default)(query.email.toLowerCase()).toString();
+              } else {
+                formattedQuery[_queryKey] = query[_queryKey];
+              }
+            }
+            return _context.abrupt("return", _this._fetchNewServiceHostmap({
+              from: from,
+              token: token,
+              query: formattedQuery,
+              forceRefresh: forceRefresh
+            }).then(function (serviceHostMap) {
+              var formattedServiceHostMap = _this._formatReceivedHostmap(serviceHostMap);
+              // Build selection metadata for caching discrimination
+              var selectionMeta;
+              if (serviceGroup === 'preauth' || serviceGroup === 'signin') {
+                var key = formattedQuery && (0, _keys.default)(formattedQuery || {})[0];
+                if (key) {
+                  selectionMeta = {
+                    selectionType: key,
+                    selectionValue: formattedQuery[key]
+                  };
+                }
+              }
+              _this._cacheCatalog(serviceGroup, serviceHostMap, selectionMeta);
+              catalog.updateServiceUrls(serviceGroup, formattedServiceHostMap);
+              _this.updateCredentialsConfig();
+              catalog.status[serviceGroup].collecting = false;
+            }).catch(function (error) {
+              catalog.status[serviceGroup].collecting = false;
+              return _promise.default.reject(error);
+            }));
+          case 7:
+          case "end":
+            return _context.stop();
+        }
+      }, _callee);
+    }))();
   },
   /**
    * User validation parameter transfer object for {@link validateUser}.
@@ -362,9 +472,9 @@ var Services = _webexPlugin.default.extend({
 
     // Destructure the client authorization details.
     /* eslint-disable camelcase */
-    var _this$webex$credentia = this.webex.credentials.config,
-      client_id = _this$webex$credentia.client_id,
-      client_secret = _this$webex$credentia.client_secret;
+    var _this$webex$credentia2 = this.webex.credentials.config,
+      client_id = _this$webex$credentia2.client_id,
+      client_secret = _this$webex$credentia2.client_secret;
 
     // Validate that client authentication details exist.
     if (!client_id || !client_secret) {
@@ -975,9 +1085,223 @@ var Services = _webexPlugin.default.extend({
       return _this7.request(requestObject);
     }, 'internal.get.u2c.time').then(function (_ref12) {
       var body = _ref12.body;
-      return _this7._formatReceivedHostmap(body);
+      return body;
     });
   },
+  /**
+   * Cache the catalog in the bounded storage.
+   * @param {string} serviceGroup - preauth, signin, postauth
+   * @param {object} hostMap - The hostmap to cache
+   * @param {object} [meta] - Optional selection metadata used to validate cache reuse
+   * @returns {Promise<void>}
+   *
+   */
+  _cacheCatalog: function _cacheCatalog(serviceGroup, hostMap, meta) {
+    var _this8 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee2() {
+      var current, orgId, _this8$webex$config, _this8$webex$config$c, _this8$webex, _this8$webex$config2, _this8$webex2, _this8$webex2$config, _this8$webex2$config$, _this8$webex2$config$2, _ls, cachedJson, credentials, _current, env, fedramp, u2cDiscoveryUrl, updated, ls, _t2;
+      return _regenerator.default.wrap(function (_context2) {
+        while (1) switch (_context2.prev = _context2.next) {
+          case 0:
+            current = {};
+            _context2.prev = 1;
+            if ((_this8$webex$config = _this8.webex.config) !== null && _this8$webex$config !== void 0 && (_this8$webex$config$c = _this8$webex$config.calling) !== null && _this8$webex$config$c !== void 0 && _this8$webex$config$c.cacheU2C) {
+              _context2.next = 2;
+              break;
+            }
+            _this8.logger.info("services: skipping cache write for ".concat(serviceGroup, " as per the config"));
+            return _context2.abrupt("return");
+          case 2:
+            // Persist to localStorage to survive browser refresh
+            try {
+              _ls = _this8._getLocalStorageSafe();
+              cachedJson = _ls ? _ls.getItem(CATALOG_CACHE_KEY_V1) : null;
+              current = cachedJson ? JSON.parse(cachedJson) : {};
+            } catch (e) {
+              current = {};
+            }
+            try {
+              credentials = _this8.webex.credentials;
+              orgId = credentials.getOrgId();
+            } catch (e) {
+              orgId = current.orgId;
+            }
+
+            // Capture environment fingerprint to invalidate cache across env changes
+            _current = current, env = _current.env;
+            fedramp = !!((_this8$webex = _this8.webex) !== null && _this8$webex !== void 0 && (_this8$webex$config2 = _this8$webex.config) !== null && _this8$webex$config2 !== void 0 && _this8$webex$config2.fedramp);
+            u2cDiscoveryUrl = (_this8$webex2 = _this8.webex) === null || _this8$webex2 === void 0 ? void 0 : (_this8$webex2$config = _this8$webex2.config) === null || _this8$webex2$config === void 0 ? void 0 : (_this8$webex2$config$ = _this8$webex2$config.services) === null || _this8$webex2$config$ === void 0 ? void 0 : (_this8$webex2$config$2 = _this8$webex2$config$.discovery) === null || _this8$webex2$config$2 === void 0 ? void 0 : _this8$webex2$config$2.u2c;
+            env = {
+              fedramp: fedramp,
+              u2cDiscoveryUrl: u2cDiscoveryUrl
+            };
+            updated = _objectSpread(_objectSpread({}, current), {}, (0, _defineProperty2.default)((0, _defineProperty2.default)({
+              orgId: orgId || current.orgId,
+              env: env || current.env
+            }, serviceGroup, meta ? {
+              hostMap: hostMap,
+              meta: meta
+            } : hostMap), "cachedAt", (0, _now.default)()));
+            ls = _this8._getLocalStorageSafe();
+            if (ls) {
+              ls.setItem(CATALOG_CACHE_KEY_V1, (0, _stringify.default)(updated));
+            }
+            _context2.next = 4;
+            break;
+          case 3:
+            _context2.prev = 3;
+            _t2 = _context2["catch"](1);
+            _this8.logger.warn('services: error caching catalog', _t2);
+          case 4:
+          case "end":
+            return _context2.stop();
+        }
+      }, _callee2, null, [[1, 3]]);
+    }))();
+  },
+  /**
+   * Load the catalog from cache and hydrate the in-memory ServiceCatalog.
+   * @returns {Promise<boolean>} true if cache was loaded, false otherwise
+   */
+  _loadCatalogFromCache: function _loadCatalogFromCache() {
+    var _this9 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee3() {
+      var currentOrgId, _this9$webex$config, _this9$webex$config$c, _this9$webex$config2, _this9$webex$config3, _this9$webex$config3$, _this9$webex$config3$2, ls, cachedJson, cached, cachedAt, _this9$webex$credenti, credentials, fedramp, u2cDiscoveryUrl, currentEnv, sameEnv, catalog, groups, _t3, _t4;
+      return _regenerator.default.wrap(function (_context3) {
+        while (1) switch (_context3.prev = _context3.next) {
+          case 0:
+            _context3.prev = 0;
+            if ((_this9$webex$config = _this9.webex.config) !== null && _this9$webex$config !== void 0 && (_this9$webex$config$c = _this9$webex$config.calling) !== null && _this9$webex$config$c !== void 0 && _this9$webex$config$c.cacheU2C) {
+              _context3.next = 1;
+              break;
+            }
+            _this9.logger.info('services: skipping cache warm-up as per the cache config');
+            return _context3.abrupt("return", false);
+          case 1:
+            ls = _this9._getLocalStorageSafe();
+            if (ls) {
+              _context3.next = 2;
+              break;
+            }
+            _this9.logger.info('services: skipping cache warm-up as no localStorage is available');
+            return _context3.abrupt("return", false);
+          case 2:
+            cachedJson = ls.getItem(CATALOG_CACHE_KEY_V1);
+            cached = cachedJson ? JSON.parse(cachedJson) : undefined;
+            if (cached) {
+              _context3.next = 3;
+              break;
+            }
+            return _context3.abrupt("return", false);
+          case 3:
+            // TTL enforcement: clear if older than 24 hours
+            cachedAt = Number(cached.cachedAt) || 0;
+            if (!(!cachedAt || (0, _now.default)() - cachedAt > CATALOG_TTL_MS)) {
+              _context3.next = 4;
+              break;
+            }
+            _this9.clearCatalogCache();
+            return _context3.abrupt("return", false);
+          case 4:
+            _context3.prev = 4;
+            if (!((_this9$webex$credenti = _this9.webex.credentials) !== null && _this9$webex$credenti !== void 0 && _this9$webex$credenti.canAuthorize)) {
+              _context3.next = 5;
+              break;
+            }
+            credentials = _this9.webex.credentials;
+            currentOrgId = credentials.getOrgId();
+            if (!(cached.orgId && cached.orgId !== currentOrgId)) {
+              _context3.next = 5;
+              break;
+            }
+            return _context3.abrupt("return", false);
+          case 5:
+            _context3.next = 7;
+            break;
+          case 6:
+            _context3.prev = 6;
+            _t3 = _context3["catch"](4);
+            _this9.logger.warn('services: error checking orgId', _t3);
+          case 7:
+            // Ensure cached environment matches current environment
+            fedramp = !!((_this9$webex$config2 = _this9.webex.config) !== null && _this9$webex$config2 !== void 0 && _this9$webex$config2.fedramp);
+            u2cDiscoveryUrl = (_this9$webex$config3 = _this9.webex.config) === null || _this9$webex$config3 === void 0 ? void 0 : (_this9$webex$config3$ = _this9$webex$config3.services) === null || _this9$webex$config3$ === void 0 ? void 0 : (_this9$webex$config3$2 = _this9$webex$config3$.discovery) === null || _this9$webex$config3$2 === void 0 ? void 0 : _this9$webex$config3$2.u2c;
+            currentEnv = {
+              fedramp: fedramp,
+              u2cDiscoveryUrl: u2cDiscoveryUrl
+            };
+            if (!cached.env) {
+              _context3.next = 8;
+              break;
+            }
+            sameEnv = cached.env.fedramp === currentEnv.fedramp && cached.env.u2cDiscoveryUrl === currentEnv.u2cDiscoveryUrl;
+            if (sameEnv) {
+              _context3.next = 8;
+              break;
+            }
+            _this9.logger.info('services: skipping cache warm due to environment mismatch');
+            return _context3.abrupt("return", false);
+          case 8:
+            catalog = _this9._getCatalog(); // Apply any cached groups (with preauth selection validation if available)
+            groups = ['preauth', 'signin', 'postauth'];
+            groups.forEach(function (serviceGroup) {
+              var cachedGroup = cached[serviceGroup];
+              if (!cachedGroup) {
+                return;
+              }
+
+              // Support legacy (hostMap) and new ({hostMap, meta}) shapes
+              var hostMap = cachedGroup && cachedGroup.hostMap ? cachedGroup.hostMap : cachedGroup;
+              var meta = cachedGroup === null || cachedGroup === void 0 ? void 0 : cachedGroup.meta;
+              if (serviceGroup === 'preauth' && meta) {
+                // For proximity-based selection, always fetch fresh to respect IP/region changes
+                if (meta.selectionType === 'mode') {
+                  _this9.logger.info('services: skipping preauth cache warm for proximity mode');
+                  return;
+                }
+                var intended = _this9.getIntendedPreauthSelection(currentOrgId);
+                var matches = intended && intended.selectionType === meta.selectionType && intended.selectionValue === meta.selectionValue;
+                if (!matches) {
+                  _this9.logger.info('services: skipping preauth cache warm due to selection mismatch');
+                  return;
+                }
+              }
+              if (hostMap) {
+                var formatted = _this9._formatReceivedHostmap(hostMap);
+                catalog.updateServiceUrls(serviceGroup, formatted);
+              }
+            });
+
+            // Align credentials against warmed catalog
+            _this9.updateCredentialsConfig();
+            return _context3.abrupt("return", true);
+          case 9:
+            _context3.prev = 9;
+            _t4 = _context3["catch"](0);
+            _this9.logger.warn('services: error loading catalog from cache', _t4);
+            return _context3.abrupt("return", false);
+          case 10:
+          case "end":
+            return _context3.stop();
+        }
+      }, _callee3, null, [[0, 9], [4, 6]]);
+    }))();
+  },
+  /**
+   * Clear the catalog cache from the bounded storage.
+   * @returns {Promise<void>}
+   */
+  clearCatalogCache: function clearCatalogCache() {
+    try {
+      var ls = this._getLocalStorageSafe();
+      if (ls) {
+        ls.removeItem(CATALOG_CACHE_KEY_V1);
+      }
+    } catch (e) {
+      this.logger.warn('services: error clearing catalog cache', e);
+    }
+    return _promise.default.resolve();
+  },
   /**
    * Initialize the discovery services and the whitelisted services.
    *
@@ -986,9 +1310,9 @@ var Services = _webexPlugin.default.extend({
   initConfig: function initConfig() {
     // Get the catalog and destructure the services config.
     var catalog = this._getCatalog();
-    var _this$webex$config = this.webex.config,
-      services = _this$webex$config.services,
-      fedramp = _this$webex$config.fedramp;
+    var _this$webex$config2 = this.webex.config,
+      services = _this$webex$config2.services,
+      fedramp = _this$webex$config2.fedramp;
 
     // Validate that the services configuration exists.
     if (services) {
@@ -1042,7 +1366,7 @@ var Services = _webexPlugin.default.extend({
    * @returns {Promise<void, Error>} - Errors if the token is unavailable.
    */
   initServiceCatalogs: function initServiceCatalogs() {
-    var _this8 = this;
+    var _this0 = this;
     this.logger.info('services: initializing initial service catalogs');
 
     // Destructure the credentials plugin.
@@ -1057,16 +1381,17 @@ var Services = _webexPlugin.default.extend({
     })
     // Begin collecting the preauth/limited catalog.
     .then(function (orgId) {
-      return _this8.collectPreauthCatalog({
+      return _this0.collectPreauthCatalog({
         orgId: orgId
       });
     }).then(function () {
       // Validate if the token is authorized.
       if (credentials.canAuthorize) {
         // Attempt to collect the postauth catalog.
-        return _this8.updateServices().catch(function () {
-          _this8.initFailed = true;
-          _this8.logger.warn('services: cannot retrieve postauth catalog');
+
+        return _this0.updateServices().catch(function () {
+          _this0.initFailed = true;
+          _this0.logger.warn('services: cannot retrieve postauth catalog');
         });
       }
 
@@ -1074,6 +1399,42 @@ var Services = _webexPlugin.default.extend({
       return _promise.default.resolve();
     });
   },
+  /**
+   * Await any in-flight credentials refresh, then flip `services.ready` so
+   * `webex.ready` can fire. Closes the parallel-refresh window: if a credential
+   * refresh is in flight when initial catalog collection settles, we must not
+   * signal ready until the refresh has resolved - otherwise downstream
+   * consumers may observe `canAuthorize`/token state that is about to change
+   * under them.
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  _finalizeReady: function _finalizeReady() {
+    var _this1 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee4() {
+      var credentials;
+      return _regenerator.default.wrap(function (_context4) {
+        while (1) switch (_context4.prev = _context4.next) {
+          case 0:
+            credentials = _this1.webex.credentials;
+            if (!(credentials && credentials.isRefreshing)) {
+              _context4.next = 1;
+              break;
+            }
+            _context4.next = 1;
+            return new _promise.default(function (resolve) {
+              credentials.once('change:isRefreshing', resolve);
+            });
+          case 1:
+            _this1.ready = true;
+          case 2:
+          case "end":
+            return _context4.stop();
+        }
+      }, _callee4);
+    }))();
+  },
   /**
    * Initializer
    *
@@ -1082,7 +1443,7 @@ var Services = _webexPlugin.default.extend({
    * @returns {Services}
    */
   initialize: function initialize() {
-    var _this9 = this;
+    var _this10 = this;
     var catalog = new _serviceCatalog.default();
     var registry = new _serviceRegistry.default();
     var state = new _serviceState.default();
@@ -1090,35 +1451,163 @@ var Services = _webexPlugin.default.extend({
     this.registries.set(this.webex, registry);
     this.states.set(this.webex, state);
 
-    // Listen for configuration changes once.
+    // Listen for configuration changes once. The config is not populated on the
+    // webex instance until the `change:config` event fires, so any decision that
+    // depends on config values (such as the gated-vs-ungated init below) must be
+    // made from within this handler rather than synchronously in `initialize()`.
     this.listenToOnce(this.webex, 'change:config', function () {
-      _this9.initConfig();
-    });
+      var _this10$webex$config, _this10$webex$config$;
+      _this10.initConfig();
 
-    // wait for webex instance to be ready before attempting
-    // to update the service catalogs
-    this.listenToOnce(this.webex, 'ready', function () {
-      var supertoken = _this9.webex.credentials.supertoken;
-      // Validate if the supertoken exists.
-      if (supertoken && supertoken.access_token) {
-        _this9.initServiceCatalogs().then(function () {
-          catalog.isReady = true;
-        }).catch(function (error) {
-          _this9.initFailed = true;
-          _this9.logger.error("services: failed to init initial services when credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
-        });
+      // Feature flag: when enabled, `webex.ready` is blocked until the initial
+      // catalog collection has settled AND any in-flight credentials refresh has
+      // completed. When disabled (the default), preserves the pre-existing
+      // behavior where `webex.ready` fires as soon as `webex.loaded` does and
+      // the catalog is collected out-of-band.
+      var waitForCatalogInit = ((_this10$webex$config = _this10.webex.config) === null || _this10$webex$config === void 0 ? void 0 : (_this10$webex$config$ = _this10$webex$config.services) === null || _this10$webex$config$ === void 0 ? void 0 : _this10$webex$config$.waitForCatalogInit) === true;
+      if (waitForCatalogInit) {
+        _this10._initializeCatalogsGated(catalog);
       } else {
-        var email = _this9.webex.config.email;
-        _this9.collectPreauthCatalog(email ? {
-          email: email
-        } : undefined).catch(function (error) {
-          _this9.initFailed = true;
-          _this9.logger.error("services: failed to init initial services when no credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
-        });
+        // Not gating - immediately mark ready so we do not block webex.ready.
+        _this10.ready = true;
+        _this10._initializeCatalogsUngated(catalog);
       }
     });
   },
-  version: "3.12.0-task-refactor.1"
+  /**
+   * Original (pre-verified-ready) initialization path. Runs on `webex.ready`
+   * and collects catalogs opportunistically without blocking anything.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsUngated: function _initializeCatalogsUngated(catalog) {
+    var _this11 = this;
+    // wait for webex instance to be ready before attempting
+    // to update the service catalogs
+    // this can cause a race condition because credentials may
+    // not be valid when services is initialized
+    this.listenToOnce(this.webex, 'ready', /*#__PURE__*/(0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee5() {
+      var cachedCatalog, supertoken, email;
+      return _regenerator.default.wrap(function (_context5) {
+        while (1) switch (_context5.prev = _context5.next) {
+          case 0:
+            _context5.next = 1;
+            return _this11._loadCatalogFromCache();
+          case 1:
+            cachedCatalog = _context5.sent;
+            if (!cachedCatalog) {
+              _context5.next = 2;
+              break;
+            }
+            catalog.isReady = true;
+            return _context5.abrupt("return");
+          case 2:
+            supertoken = _this11.webex.credentials.supertoken; // Validate if the supertoken exists.
+            if (supertoken && supertoken.access_token) {
+              _this11.initServiceCatalogs().then(function () {
+                catalog.isReady = true;
+              }).catch(function (error) {
+                _this11.initFailed = true;
+                _this11.logger.error("services: failed to init initial services when credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              });
+            } else {
+              email = _this11.webex.config.email;
+              _this11.collectPreauthCatalog(email ? {
+                email: email
+              } : undefined).catch(function (error) {
+                _this11.initFailed = true;
+                _this11.logger.error("services: failed to init initial services when no credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              });
+            }
+          case 3:
+          case "end":
+            return _context5.stop();
+        }
+      }, _callee5);
+    })));
+  },
+  /**
+   * Verified-ready initialization path. Blocks `webex.ready` until the initial
+   * catalog fetch has settled (or timed out) AND any in-flight credentials
+   * refresh has completed. Also handles the fresh-login case where OAuth
+   * completes after `loaded` fires.
+   *
+   * @private
+   * @param {ServiceCatalog} catalog
+   * @returns {void}
+   */
+  _initializeCatalogsGated: function _initializeCatalogsGated(catalog) {
+    var _this12 = this;
+    // Wait for storage to be loaded before attempting to update the service
+    // catalogs. We listen for 'loaded' instead of 'ready' because `services.ready`
+    // now blocks `webex.ready` - listening to 'ready' would deadlock.
+    this.listenToOnce(this.webex, 'loaded', /*#__PURE__*/(0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee6() {
+      var cachedCatalog, supertoken, timeout, email;
+      return _regenerator.default.wrap(function (_context6) {
+        while (1) switch (_context6.prev = _context6.next) {
+          case 0:
+            _context6.next = 1;
+            return _this12._loadCatalogFromCache();
+          case 1:
+            cachedCatalog = _context6.sent;
+            if (!cachedCatalog) {
+              _context6.next = 3;
+              break;
+            }
+            catalog.isReady = true;
+            _context6.next = 2;
+            return _this12._finalizeReady();
+          case 2:
+            return _context6.abrupt("return");
+          case 3:
+            supertoken = _this12.webex.credentials.supertoken; // Race init against a hard timeout so a hung request never leaves
+            // `services.ready` false forever - that would stall `webex.ready` and
+            // leave the app on a permanent spinner.
+            timeout = new _promise.default(function (_, reject) {
+              setTimeout(function () {
+                return reject(new Error("services: init timed out after ".concat(SERVICES_INIT_TIMEOUT_MS, "ms")));
+              }, SERVICES_INIT_TIMEOUT_MS);
+            }); // Validate if the supertoken exists.
+            if (supertoken && supertoken.access_token) {
+              _promise.default.race([_this12.initServiceCatalogs(), timeout]).then(function () {
+                catalog.isReady = true;
+              }).catch(function (error) {
+                _this12.initFailed = true;
+                _this12.logger.error("services: failed to init initial services when credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              }).finally(function () {
+                return _this12._finalizeReady();
+              });
+            } else {
+              email = _this12.webex.config.email;
+              _promise.default.race([_this12.collectPreauthCatalog(email ? {
+                email: email
+              } : undefined), timeout]).catch(function (error) {
+                _this12.initFailed = true;
+                _this12.logger.error("services: failed to init initial services when no credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              }).finally(function () {
+                return _this12._finalizeReady();
+              });
+
+              // Handle fresh login: 'loaded' fires before OAuth completes, so listen
+              // for `canAuthorize` flipping true and then collect the postauth catalog.
+              _this12.listenToOnce(_this12.webex, 'change:canAuthorize', function () {
+                if (_this12.webex.canAuthorize && !catalog.status.postauth.ready) {
+                  _this12.initServiceCatalogs().catch(function (error) {
+                    _this12.logger.error("services: failed to init service catalogs after auth, ".concat(error === null || error === void 0 ? void 0 : error.message));
+                  });
+                }
+              });
+            }
+          case 4:
+          case "end":
+            return _context6.stop();
+        }
+      }, _callee6);
+    })));
+  },
+  version: "3.12.0-webex-services-ready.2"
 });
 /* eslint-enable no-underscore-dangle */
 var _default = exports.default = Services;