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

package/dist/lib/services-v2/services-v2.js

@@ -11,6 +11,8 @@ _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 _slicedToArray2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/slicedToArray"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/defineProperty"));
 var _weakMap = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/weak-map"));
@@ -18,6 +20,8 @@ var _isArray = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/ar
 var _keys = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/keys"));
 var _promise = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/promise"));
 var _values = _interopRequireDefault(require("@babel/runtime-corejs2/core-js/object/values"));
+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"));
@@ -35,6 +39,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_V2 = 'services.v2.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 */
 /**
@@ -46,6 +58,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(),
   _activeServices: {},
   _services: [],
@@ -58,6 +85,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} [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.
@@ -104,6 +170,7 @@ var Services = _webexPlugin.default.extend({
    * @returns {Array<ServiceHost>} - An array of `ServiceHost` objects.
    */
   getMobiusClusters: function getMobiusClusters() {
+    this.logger.info('services: fetching mobius clusters');
     var clusters = [];
     var services = this._services || [];
     services.filter(function (service) {
@@ -140,6 +207,24 @@ var Services = _webexPlugin.default.extend({
       });
     });
   },
+  /**
+   * 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;
+    }
+  },
   /**
    * saves all the services from the pre and post catalog service
    * @param {ActiveServices} activeServices
@@ -222,6 +307,18 @@ var Services = _webexPlugin.default.extend({
       forceRefresh: forceRefresh
     }).then(function (serviceHostMap) {
       catalog.updateServiceGroups(serviceGroup, serviceHostMap === null || serviceHostMap === void 0 ? void 0 : serviceHostMap.services, serviceHostMap === null || serviceHostMap === void 0 ? void 0 : serviceHostMap.timestamp);
+      // Build selection metadata for caching discrimination (preauth/signin)
+      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);
       _this.updateCredentialsConfig();
       catalog.status[serviceGroup].collecting = false;
     }).catch(function (error) {
@@ -298,9 +395,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) {
@@ -876,6 +973,213 @@ var Services = _webexPlugin.default.extend({
     }
     return url.replace(data.defaultUrl, data.priorityUrl);
   },
+  /**
+   * @private
+   * Cache the catalog in the bounded storage.
+   * @param {ServiceGroup} serviceGroup - preauth, signin, postauth
+   * @param {ServiceHostmap} hostMap - The hostmap to cache
+   * @param {object} [meta] - Optional selection metadata for cache discrimination
+   * @returns {Promise<void>}
+   */
+  _cacheCatalog: function _cacheCatalog(serviceGroup, hostMap, meta) {
+    var _this9 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee() {
+      var current, orgId, _this9$webex$config, _this9$webex$config$c, _this9$webex, _this9$webex$config2, _this9$webex2, _this9$webex2$config, _this9$webex2$config$, _this9$webex2$config$2, _ls, cachedJson, credentials, _current, env, fedramp, u2cDiscoveryUrl, updated, ls, _t;
+      return _regenerator.default.wrap(function (_context) {
+        while (1) switch (_context.prev = _context.next) {
+          case 0:
+            current = {};
+            _context.prev = 1;
+            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) {
+              _context.next = 2;
+              break;
+            }
+            _this9.logger.info("services: skipping cache write for ".concat(serviceGroup, " as per the config"));
+            return _context.abrupt("return");
+          case 2:
+            try {
+              _ls = _this9._getLocalStorageSafe();
+              cachedJson = _ls ? _ls.getItem(CATALOG_CACHE_KEY_V2) : null;
+              current = cachedJson ? JSON.parse(cachedJson) : {};
+            } catch (_unused2) {
+              current = {};
+            }
+            try {
+              credentials = _this9.webex.credentials;
+              orgId = credentials.getOrgId();
+            } catch (_unused3) {
+              orgId = current.orgId;
+            }
+
+            // Capture environment fingerprint to invalidate cache across env changes
+            _current = current, env = _current.env;
+            fedramp = !!((_this9$webex = _this9.webex) !== null && _this9$webex !== void 0 && (_this9$webex$config2 = _this9$webex.config) !== null && _this9$webex$config2 !== void 0 && _this9$webex$config2.fedramp);
+            u2cDiscoveryUrl = (_this9$webex2 = _this9.webex) === null || _this9$webex2 === void 0 ? void 0 : (_this9$webex2$config = _this9$webex2.config) === null || _this9$webex2$config === void 0 ? void 0 : (_this9$webex2$config$ = _this9$webex2$config.services) === null || _this9$webex2$config$ === void 0 ? void 0 : (_this9$webex2$config$2 = _this9$webex2$config$.discovery) === null || _this9$webex2$config$2 === void 0 ? void 0 : _this9$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 = _this9._getLocalStorageSafe();
+            if (ls) {
+              ls.setItem(CATALOG_CACHE_KEY_V2, (0, _stringify.default)(updated));
+            }
+            _context.next = 4;
+            break;
+          case 3:
+            _context.prev = 3;
+            _t = _context["catch"](1);
+            _this9.logger.warn('services: error caching catalog', _t);
+          case 4:
+          case "end":
+            return _context.stop();
+        }
+      }, _callee, null, [[1, 3]]);
+    }))();
+  },
+  /**
+   * @private
+   * 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 _this0 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee2() {
+      var currentOrgId, _this0$webex$config, _this0$webex$config$c, _this0$webex$config2, _this0$webex$config3, _this0$webex$config3$, _this0$webex$config3$2, ls, cachedJson, cached, cachedAt, _this0$webex$credenti, credentials, fedramp, u2cDiscoveryUrl, currentEnv, sameEnv, catalog, groups, _t2, _t3;
+      return _regenerator.default.wrap(function (_context2) {
+        while (1) switch (_context2.prev = _context2.next) {
+          case 0:
+            _context2.prev = 0;
+            if ((_this0$webex$config = _this0.webex.config) !== null && _this0$webex$config !== void 0 && (_this0$webex$config$c = _this0$webex$config.calling) !== null && _this0$webex$config$c !== void 0 && _this0$webex$config$c.cacheU2C) {
+              _context2.next = 1;
+              break;
+            }
+            _this0.logger.info('services: skipping cache warm-up as per the cache config');
+            return _context2.abrupt("return", false);
+          case 1:
+            ls = _this0._getLocalStorageSafe();
+            if (ls) {
+              _context2.next = 2;
+              break;
+            }
+            _this0.logger.info('services: skipping cache warm-up as no localStorage is available');
+            return _context2.abrupt("return", false);
+          case 2:
+            cachedJson = ls.getItem(CATALOG_CACHE_KEY_V2);
+            cached = cachedJson ? JSON.parse(cachedJson) : undefined;
+            if (cached) {
+              _context2.next = 3;
+              break;
+            }
+            return _context2.abrupt("return", false);
+          case 3:
+            // TTL enforcement
+            cachedAt = Number(cached.cachedAt) || 0;
+            if (!(!cachedAt || (0, _now.default)() - cachedAt > CATALOG_TTL_MS)) {
+              _context2.next = 4;
+              break;
+            }
+            _this0.clearCatalogCache();
+            return _context2.abrupt("return", false);
+          case 4:
+            _context2.prev = 4;
+            if (!((_this0$webex$credenti = _this0.webex.credentials) !== null && _this0$webex$credenti !== void 0 && _this0$webex$credenti.canAuthorize)) {
+              _context2.next = 5;
+              break;
+            }
+            credentials = _this0.webex.credentials;
+            currentOrgId = credentials.getOrgId();
+            if (!(cached.orgId && cached.orgId !== currentOrgId)) {
+              _context2.next = 5;
+              break;
+            }
+            return _context2.abrupt("return", false);
+          case 5:
+            _context2.next = 7;
+            break;
+          case 6:
+            _context2.prev = 6;
+            _t2 = _context2["catch"](4);
+            _this0.logger.warn('services: error checking orgId', _t2);
+          case 7:
+            // Ensure cached environment matches current environment
+            fedramp = !!((_this0$webex$config2 = _this0.webex.config) !== null && _this0$webex$config2 !== void 0 && _this0$webex$config2.fedramp);
+            u2cDiscoveryUrl = (_this0$webex$config3 = _this0.webex.config) === null || _this0$webex$config3 === void 0 ? void 0 : (_this0$webex$config3$ = _this0$webex$config3.services) === null || _this0$webex$config3$ === void 0 ? void 0 : (_this0$webex$config3$2 = _this0$webex$config3$.discovery) === null || _this0$webex$config3$2 === void 0 ? void 0 : _this0$webex$config3$2.u2c;
+            currentEnv = {
+              fedramp: fedramp,
+              u2cDiscoveryUrl: u2cDiscoveryUrl
+            };
+            if (!cached.env) {
+              _context2.next = 8;
+              break;
+            }
+            sameEnv = cached.env.fedramp === currentEnv.fedramp && cached.env.u2cDiscoveryUrl === currentEnv.u2cDiscoveryUrl;
+            if (sameEnv) {
+              _context2.next = 8;
+              break;
+            }
+            return _context2.abrupt("return", false);
+          case 8:
+            catalog = _this0._getCatalog();
+            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') {
+                  return;
+                }
+                var intended = _this0.getIntendedPreauthSelection(currentOrgId);
+                var matches = intended && intended.selectionType === meta.selectionType && intended.selectionValue === meta.selectionValue;
+                if (!matches) {
+                  return;
+                }
+              }
+              if (hostMap) {
+                catalog.updateServiceGroups(serviceGroup, hostMap === null || hostMap === void 0 ? void 0 : hostMap.services, hostMap === null || hostMap === void 0 ? void 0 : hostMap.timestamp);
+              }
+            });
+            _this0.updateCredentialsConfig();
+            return _context2.abrupt("return", true);
+          case 9:
+            _context2.prev = 9;
+            _t3 = _context2["catch"](0);
+            return _context2.abrupt("return", false);
+          case 10:
+          case "end":
+            return _context2.stop();
+        }
+      }, _callee2, null, [[0, 9], [4, 6]]);
+    }))();
+  },
+  /**
+   * Clear the catalog cache from the bounded storage (v2).
+   * @returns {Promise<void>}
+   */
+  clearCatalogCache: function clearCatalogCache() {
+    try {
+      var ls = this._getLocalStorageSafe();
+      if (ls) {
+        ls.removeItem(CATALOG_CACHE_KEY_V2);
+      }
+    } catch (e) {
+      this.logger.warn('services: error clearing catalog cache', e);
+    }
+    return _promise.default.resolve();
+  },
   /**
    * @private
    * Simplified method wrapper for sending a request to get
@@ -890,7 +1194,7 @@ var Services = _webexPlugin.default.extend({
    * @returns {Promise<object>}
    */
   _fetchNewServiceHostmap: function _fetchNewServiceHostmap() {
-    var _this9 = this;
+    var _this1 = this;
     var _ref11 = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
       from = _ref11.from,
       query = _ref11.query,
@@ -917,10 +1221,10 @@ var Services = _webexPlugin.default.extend({
       };
     }
     return this.webex.internal.newMetrics.callDiagnosticLatencies.measureLatency(function () {
-      return _this9.request(requestObject);
+      return _this1.request(requestObject);
     }, 'internal.get.u2c.time').then(function (_ref12) {
       var body = _ref12.body;
-      return _this9._formatReceivedHostmap(body || {});
+      return _this1._formatReceivedHostmap(body || {});
     });
   },
   /**
@@ -929,12 +1233,12 @@ var Services = _webexPlugin.default.extend({
    * @returns {void}
    */
   initConfig: function initConfig() {
-    var _this0 = this;
+    var _this10 = this;
     // 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) {
@@ -945,7 +1249,7 @@ var Services = _webexPlugin.default.extend({
       if (services.discovery) {
         // Format the discovery configuration into an injectable array.
         var formattedDiscoveryServices = (0, _keys.default)(services.discovery).map(function (key) {
-          return _this0._formatHostMapEntry({
+          return _this10._formatHostMapEntry({
             id: key,
             serviceName: key,
             serviceUrls: [{
@@ -961,7 +1265,7 @@ var Services = _webexPlugin.default.extend({
       if (services.override) {
         // Format the override configuration into an injectable array.
         var formattedOverrideServices = (0, _keys.default)(services.override).map(function (key) {
-          return _this0._formatHostMapEntry({
+          return _this10._formatHostMapEntry({
             id: key,
             serviceName: key,
             serviceUrls: [{
@@ -996,7 +1300,7 @@ var Services = _webexPlugin.default.extend({
    * @returns {Promise<void, Error>} - Errors if the token is unavailable.
    */
   initServiceCatalogs: function initServiceCatalogs() {
-    var _this1 = this;
+    var _this11 = this;
     var refresh = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
     this.logger.info('services: initializing initial service catalogs');
 
@@ -1012,18 +1316,18 @@ var Services = _webexPlugin.default.extend({
     })
     // Begin collecting the preauth/limited catalog.
     .then(function (orgId) {
-      return _this1.collectPreauthCatalog({
+      return _this11.collectPreauthCatalog({
         orgId: orgId
       }, refresh);
     }).then(function () {
       // Validate if the token is authorized.
       if (credentials.canAuthorize) {
         // Attempt to collect the postauth catalog.
-        return _this1.updateServices({
+        return _this11.updateServices({
           forceRefresh: refresh
         }).catch(function () {
-          _this1.initFailed = true;
-          _this1.logger.warn('services: cannot retrieve postauth catalog');
+          _this11.initFailed = true;
+          _this11.logger.warn('services: cannot retrieve postauth catalog');
         });
       }
 
@@ -1031,6 +1335,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 _this12 = this;
+    return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee3() {
+      var credentials;
+      return _regenerator.default.wrap(function (_context3) {
+        while (1) switch (_context3.prev = _context3.next) {
+          case 0:
+            credentials = _this12.webex.credentials;
+            if (!(credentials && credentials.isRefreshing)) {
+              _context3.next = 1;
+              break;
+            }
+            _context3.next = 1;
+            return new _promise.default(function (resolve) {
+              credentials.once('change:isRefreshing', resolve);
+            });
+          case 1:
+            _this12.ready = true;
+          case 2:
+          case "end":
+            return _context3.stop();
+        }
+      }, _callee3);
+    }))();
+  },
   /**
    * Initializer
    *
@@ -1039,39 +1379,165 @@ var Services = _webexPlugin.default.extend({
    * @returns {Services}
    */
   initialize: function initialize() {
-    var _this10 = this;
+    var _this13 = this;
     var catalog = new _serviceCatalog.default();
     this._catalogs.set(this.webex, catalog);
 
-    // 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 () {
-      _this10.initConfig();
-    });
+      var _this13$webex$config, _this13$webex$config$;
+      _this13.initConfig();
 
-    // wait for webex instance to be ready before attempting
-    // to update the service catalogs
-    this.listenToOnce(this.webex, 'ready', function () {
-      var supertoken = _this10.webex.credentials.supertoken;
-      // Validate if the supertoken exists.
-      if (supertoken && supertoken.access_token) {
-        _this10.initServiceCatalogs().then(function () {
-          catalog.isReady = true;
-        }).catch(function (error) {
-          _this10.initFailed = true;
-          _this10.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 = ((_this13$webex$config = _this13.webex.config) === null || _this13$webex$config === void 0 ? void 0 : (_this13$webex$config$ = _this13$webex$config.services) === null || _this13$webex$config$ === void 0 ? void 0 : _this13$webex$config$.waitForCatalogInit) === true;
+      if (waitForCatalogInit) {
+        _this13._initializeCatalogsGated(catalog);
       } else {
-        var email = _this10.webex.config.email;
-        _this10.collectPreauthCatalog(email ? {
-          email: email
-        } : undefined).catch(function (error) {
-          _this10.initFailed = true;
-          _this10.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.
+        _this13.ready = true;
+        _this13._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 _this14 = this;
+    // wait for webex instance to be ready before attempting
+    // to update the service catalogs
+    this.listenToOnce(this.webex, 'ready', /*#__PURE__*/(0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee4() {
+      var warmed, supertoken, email;
+      return _regenerator.default.wrap(function (_context4) {
+        while (1) switch (_context4.prev = _context4.next) {
+          case 0:
+            _context4.next = 1;
+            return _this14._loadCatalogFromCache();
+          case 1:
+            warmed = _context4.sent;
+            if (!warmed) {
+              _context4.next = 2;
+              break;
+            }
+            catalog.isReady = true;
+            return _context4.abrupt("return");
+          case 2:
+            supertoken = _this14.webex.credentials.supertoken; // Validate if the supertoken exists.
+            if (supertoken && supertoken.access_token) {
+              _this14.initServiceCatalogs().then(function () {
+                catalog.isReady = true;
+              }).catch(function (error) {
+                _this14.initFailed = true;
+                _this14.logger.error("services: failed to init initial services when credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              });
+            } else {
+              email = _this14.webex.config.email;
+              _this14.collectPreauthCatalog(email ? {
+                email: email
+              } : undefined).catch(function (error) {
+                _this14.initFailed = true;
+                _this14.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 _context4.stop();
+        }
+      }, _callee4);
+    })));
+  },
+  /**
+   * 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 _this15 = 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 _callee5() {
+      var warmed, supertoken, timeout, email;
+      return _regenerator.default.wrap(function (_context5) {
+        while (1) switch (_context5.prev = _context5.next) {
+          case 0:
+            _context5.next = 1;
+            return _this15._loadCatalogFromCache();
+          case 1:
+            warmed = _context5.sent;
+            if (!warmed) {
+              _context5.next = 3;
+              break;
+            }
+            catalog.isReady = true;
+            _context5.next = 2;
+            return _this15._finalizeReady();
+          case 2:
+            return _context5.abrupt("return");
+          case 3:
+            supertoken = _this15.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([_this15.initServiceCatalogs(), timeout]).then(function () {
+                catalog.isReady = true;
+              }).catch(function (error) {
+                _this15.initFailed = true;
+                _this15.logger.error("services: failed to init initial services when credentials available, ".concat(error === null || error === void 0 ? void 0 : error.message));
+              }).finally(function () {
+                return _this15._finalizeReady();
+              });
+            } else {
+              email = _this15.webex.config.email;
+              _promise.default.race([_this15.collectPreauthCatalog(email ? {
+                email: email
+              } : undefined), timeout]).catch(function (error) {
+                _this15.initFailed = true;
+                _this15.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 _this15._finalizeReady();
+              });
+
+              // Handle fresh login: 'loaded' fires before OAuth completes, so listen
+              // for `canAuthorize` flipping true and then collect the postauth catalog.
+              _this15.listenToOnce(_this15.webex, 'change:canAuthorize', function () {
+                if (_this15.webex.canAuthorize && !catalog.status.postauth.ready) {
+                  _this15.initServiceCatalogs().catch(function (error) {
+                    _this15.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 _context5.stop();
+        }
+      }, _callee5);
+    })));
+  },
+  version: "3.12.0-webex-services-ready.2"
 });
 /* eslint-enable no-underscore-dangle */
 var _default = exports.default = Services;