@xh/hoist 73.0.0-SNAPSHOT.1741793208717 → 73.0.0-SNAPSHOT.1741808956502

package/CHANGELOG.md

@@ -4,11 +4,12 @@
 
 ### 🎁 New Features
 
-* Modify `TabContainerModel` to make more methods `protected`, improving extensibility for advanced
-use-cases.
-* Enhance `XH.reloadApp` with new argument to clear query parameters before loading.
-* Enhance exception handling in `FetchService` to capture messages returned as raw strings, or without
-explicit names.
+* Modified `TabContainerModel` to make more methods `protected`, improving extensibility for
+  advanced use-cases.
+* Enhanced `XH.reloadApp` with new argument to clear query parameters before loading.
+* Enhanced exception handling in `FetchService` to capture messages returned as raw strings, or
+  without explicit names.
+* Added dedicated columns to the Admin Console "Client Errors" tab for error names and messages.
 
 ### 🐞 Bug Fixes
 

package/admin/tabs/activity/clienterrors/ClientErrorsModel.ts

@@ -9,7 +9,7 @@ import * as Col from '@xh/hoist/admin/columns';
 import {FilterChooserModel} from '@xh/hoist/cmp/filter';
 import {FormModel} from '@xh/hoist/cmp/form';
 import {GridModel} from '@xh/hoist/cmp/grid';
-import {HoistModel, LoadSpec, managed, XH} from '@xh/hoist/core';
+import {HoistModel, LoadSpec, managed, PlainObject, XH} from '@xh/hoist/core';
 import {StoreRecord} from '@xh/hoist/data';
 import {fmtJson} from '@xh/hoist/format';
 import {action, bindable, comparer, computed, makeObservable, observable} from '@xh/hoist/mobx';
@@ -62,6 +62,14 @@ export class ClientErrorsModel extends HoistModel {
                 {...Col.appVersion},
                 {...Col.appEnvironment},
                 {...Col.msg, displayName: 'User Message', hidden},
+                {
+                    field: {name: 'errorName', type: 'string'},
+                    autosizeMaxWidth: 400
+                },
+                {
+                    field: {name: 'errorMessage', type: 'string'},
+                    autosizeMaxWidth: 400
+                },
                 {...Col.error, hidden},
                 {...Col.url},
                 {...Col.correlationId},
@@ -119,18 +127,29 @@ export class ClientErrorsModel extends HoistModel {
     }
 
     override async doLoadAsync(loadSpec: LoadSpec) {
-        const {gridModel} = this;
+        const {query, gridModel} = this;
 
         try {
-            const data = await XH.fetchService.postJson({
+            const data: PlainObject[] = await XH.fetchService.postJson({
                 url: 'clientErrorAdmin',
-                body: this.query,
+                body: query,
                 loadSpec
             });
 
+            // Parse name + message from JSON-serialized error object out to top-level properties.
+            data.forEach(it => {
+                try {
+                    const error = JSON.parse(it.error);
+                    it.errorName = error?.name;
+                    it.errorMessage = error?.message;
+                } catch (ignored) {}
+            });
+
             gridModel.loadData(data);
             await gridModel.preSelectFirstAsync();
         } catch (e) {
+            if (loadSpec.isStale || loadSpec.isAutoRefresh) return;
+
             gridModel.clear();
             XH.handleException(e);
         }

package/build/types/security/BaseOAuthClient.d.ts

@@ -1,7 +1,8 @@
 import { HoistBase } from '@xh/hoist/core';
-import { Token, TokenMap } from '@xh/hoist/security/Token';
+import { Token } from '@xh/hoist/security/Token';
+import { AccessTokenSpec, TokenMap } from './Types';
 export type LoginMethod = 'REDIRECT' | 'POPUP';
-export interface BaseOAuthClientConfig<S> {
+export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
     /** Client ID (GUID) of your app registered with your Oauth provider. */
     clientId: string;
     /**
@@ -23,24 +24,16 @@ export interface BaseOAuthClientConfig<S> {
      * Governs an optional refresh timer that will work to keep the tokens fresh.
      *
      * A typical refresh will use the underlying provider cache, and should not result in
-     * network activity. However, if any token lifetime falls below`autoRefreshSkipCacheSecs`,
+     * network activity. However, if any token would expire before the next autoRefresh,
      * this client will force a call to the underlying provider to get the token.
      *
      * In order to allow aging tokens to be replaced in a timely manner, this value should be
      * significantly shorter than both the minimum token lifetime that will be
-     * returned by the underlying API and `autoRefreshSkipCacheSecs`.
+     * returned by the underlying API.
      *
      * Default is -1, disabling this behavior.
      */
     autoRefreshSecs?: number;
-    /**
-     * During auto-refresh, if the remaining lifetime for any token is below this threshold,
-     * force the provider to skip the local cache and go directly to the underlying provider for
-     * new tokens and refresh tokens.
-     *
-     * Default is -1, disabling this behavior.
-     */
-    autoRefreshSkipCacheSecs?: number;
     /**
      * Scopes to request - if any - beyond the core `['openid', 'email']` scopes, which
      * this client will always request.
@@ -68,7 +61,7 @@ export interface BaseOAuthClientConfig<S> {
  * server-side `AuthenticationService` implementation to validate the token and actually resolve
  * the user.) On init, the client impl will initiate a pop-up or redirect flow as necessary.
  */
-export declare abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> extends HoistBase {
+export declare abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S extends AccessTokenSpec> extends HoistBase {
     /** Config loaded from UI server + init method. */
     protected config: C;
     /** ID Scopes */
@@ -100,9 +93,12 @@ export declare abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>
      */
     getAccessTokenAsync(key: string): Promise<Token>;
     /**
-     * Get all available tokens.
+     * Get all configured tokens.
      */
-    getAllTokensAsync(): Promise<TokenMap>;
+    getAllTokensAsync(opts?: {
+        eagerOnly?: boolean;
+        useCache?: boolean;
+    }): Promise<TokenMap>;
     /**
      * The last authenticated OAuth username.
      *
@@ -143,7 +139,10 @@ export declare abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>
     protected restoreRedirectState(key: string): void;
     /** Call after requesting the provider library redirect the user away for auth. */
     protected maskAfterRedirectAsync(): Promise<void>;
-    protected fetchAllTokensAsync(useCache?: boolean): Promise<TokenMap>;
+    protected fetchAllTokensAsync(opts?: {
+        eagerOnly?: boolean;
+        useCache?: boolean;
+    }): Promise<TokenMap>;
     protected getLocalStorage(key: string, defaultValue?: any): any;
     protected setLocalStorage(key: string, value: any): void;
     private fetchIdTokenSafeAsync;

package/build/types/security/Token.d.ts

@@ -1,5 +1,4 @@
 import { PlainObject } from '@xh/hoist/core';
-export type TokenMap = Record<string, Token>;
 export declare class Token {
     readonly value: string;
     readonly decoded: PlainObject;

package/build/types/security/Types.d.ts

@@ -0,0 +1,12 @@
+import { Token } from './Token';
+export type TokenMap = Record<string, Token>;
+export interface AccessTokenSpec {
+    /**
+     * Mode governing when the access token should be requested from provider.
+     *      eager (default) - initiate lookup on initialization, but do not block on failure.
+     *      lazy - lookup when requested by client.
+     */
+    fetchMode: 'eager' | 'lazy';
+    /** Scopes for the desired access token.*/
+    scopes: string[];
+}

package/build/types/security/authzero/AuthZeroClient.d.ts

@@ -1,5 +1,6 @@
 import type { Auth0ClientOptions } from '@auth0/auth0-spa-js';
-import { Token, TokenMap } from '@xh/hoist/security/Token';
+import { Token } from '@xh/hoist/security/Token';
+import { AccessTokenSpec, TokenMap } from '../Types';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
 export interface AuthZeroClientConfig extends BaseOAuthClientConfig<AuthZeroTokenSpec> {
     /** Domain of your app registered with Auth0.  */
@@ -24,9 +25,7 @@ export interface AuthZeroClientConfig extends BaseOAuthClientConfig<AuthZeroToke
      */
     authZeroClientOptions?: Partial<Auth0ClientOptions>;
 }
-export interface AuthZeroTokenSpec {
-    /** Scopes for the desired access token.*/
-    scopes: string[];
+export interface AuthZeroTokenSpec extends AccessTokenSpec {
     /**
      * Audience (i.e. API) identifier for AccessToken.  Must be registered with Auth0.
      * Note that this is required to ensure that issued token is a JWT and not an opaque string.

package/build/types/security/msal/MsalClient.d.ts

@@ -1,6 +1,7 @@
 import * as msal from '@azure/msal-browser';
 import { LogLevel } from '@azure/msal-browser';
-import { Token, TokenMap } from '@xh/hoist/security/Token';
+import { Token } from '@xh/hoist/security/Token';
+import { AccessTokenSpec, TokenMap } from '../Types';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
@@ -44,9 +45,7 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
      */
     msalClientOptions?: Partial<msal.Configuration>;
 }
-export interface MsalTokenSpec {
-    /** Scopes for the desired access token. */
-    scopes: string[];
+export interface MsalTokenSpec extends AccessTokenSpec {
     /**
      * Scopes to be added to the scopes requested during interactive and SSO logins.
      * See the `scopes` property on  `PopupRequest`, `RedirectRequest`, and `SSORequest`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "73.0.0-SNAPSHOT.1741793208717",
+  "version": "73.0.0-SNAPSHOT.1741808956502",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/security/BaseOAuthClient.ts

@@ -9,16 +9,17 @@ import {HoistBase, managed, XH} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
 import {action, makeObservable} from '@xh/hoist/mobx';
 import {never, wait} from '@xh/hoist/promise';
-import {Token, TokenMap} from '@xh/hoist/security/Token';
+import {Token} from '@xh/hoist/security/Token';
+import {AccessTokenSpec, TokenMap} from './Types';
 import {Timer} from '@xh/hoist/utils/async';
 import {MINUTES, olderThan, ONE_MINUTE, SECONDS} from '@xh/hoist/utils/datetime';
 import {isJSON, throwIf} from '@xh/hoist/utils/js';
-import {find, forEach, isEmpty, isObject, keys, pickBy, union} from 'lodash';
+import {find, forEach, isEmpty, isObject, keys, pickBy, toPairs, union} from 'lodash';
 import ShortUniqueId from 'short-unique-id';
 
 export type LoginMethod = 'REDIRECT' | 'POPUP';
 
-export interface BaseOAuthClientConfig<S> {
+export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
     /** Client ID (GUID) of your app registered with your Oauth provider. */
     clientId: string;
 
@@ -45,26 +46,17 @@ export interface BaseOAuthClientConfig<S> {
      * Governs an optional refresh timer that will work to keep the tokens fresh.
      *
      * A typical refresh will use the underlying provider cache, and should not result in
-     * network activity. However, if any token lifetime falls below`autoRefreshSkipCacheSecs`,
+     * network activity. However, if any token would expire before the next autoRefresh,
      * this client will force a call to the underlying provider to get the token.
      *
      * In order to allow aging tokens to be replaced in a timely manner, this value should be
      * significantly shorter than both the minimum token lifetime that will be
-     * returned by the underlying API and `autoRefreshSkipCacheSecs`.
+     * returned by the underlying API.
      *
      * Default is -1, disabling this behavior.
      */
     autoRefreshSecs?: number;
 
-    /**
-     * During auto-refresh, if the remaining lifetime for any token is below this threshold,
-     * force the provider to skip the local cache and go directly to the underlying provider for
-     * new tokens and refresh tokens.
-     *
-     * Default is -1, disabling this behavior.
-     */
-    autoRefreshSkipCacheSecs?: number;
-
     /**
      * Scopes to request - if any - beyond the core `['openid', 'email']` scopes, which
      * this client will always request.
@@ -94,7 +86,10 @@ export interface BaseOAuthClientConfig<S> {
  * server-side `AuthenticationService` implementation to validate the token and actually resolve
  * the user.) On init, the client impl will initiate a pop-up or redirect flow as necessary.
  */
-export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> extends HoistBase {
+export abstract class BaseOAuthClient<
+    C extends BaseOAuthClientConfig<S>,
+    S extends AccessTokenSpec
+> extends HoistBase {
     /** Config loaded from UI server + init method. */
     protected config: C;
 
@@ -120,7 +115,6 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
             redirectUrl: 'APP_BASE_URL',
             postLogoutRedirectUrl: 'APP_BASE_URL',
             autoRefreshSecs: -1,
-            autoRefreshSkipCacheSecs: -1,
             ...config
         };
         throwIf(!config.clientId, 'Missing OAuth clientId. Please review your configuration.');
@@ -174,10 +168,10 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
     }
 
     /**
-     * Get all available tokens.
+     * Get all configured tokens.
      */
-    async getAllTokensAsync(): Promise<TokenMap> {
-        return this.fetchAllTokensAsync(true);
+    async getAllTokensAsync(opts?: {eagerOnly?: boolean; useCache?: boolean}): Promise<TokenMap> {
+        return this.fetchAllTokensAsync(opts);
     }
 
     /**
@@ -313,12 +307,27 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
         await never();
     }
 
-    protected async fetchAllTokensAsync(useCache = true): Promise<TokenMap> {
-        const ret: TokenMap = {},
-            {accessSpecs} = this;
-        for (const key of keys(accessSpecs)) {
-            ret[key] = await this.fetchAccessTokenAsync(accessSpecs[key], useCache);
-        }
+    protected async fetchAllTokensAsync(opts?: {
+        eagerOnly?: boolean;
+        useCache?: boolean;
+    }): Promise<TokenMap> {
+        const eagerOnly = opts?.eagerOnly ?? false,
+            useCache = opts?.useCache ?? true,
+            accessSpecs = eagerOnly
+                ? pickBy(this.accessSpecs, spec => spec.fetchMode === 'eager')
+                : this.accessSpecs,
+            ret: TokenMap = {};
+
+        await Promise.allSettled(
+            toPairs(accessSpecs).map(async ([key, spec]) => {
+                try {
+                    ret[key] = await this.fetchAccessTokenAsync(spec, useCache);
+                } catch (e) {
+                    XH.handleException(e, {logOnServer: true, showAlert: false});
+                }
+            })
+        );
+
         // Do this after getting any access tokens --which can also populate the idToken cache!
         ret.id = await this.fetchIdTokenSafeAsync(useCache);
 
@@ -360,22 +369,19 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
     private async onTimerAsync(): Promise<void> {
         const {config, lastRefreshAttempt} = this,
             refreshSecs = config.autoRefreshSecs * SECONDS,
-            skipCacheSecs = config.autoRefreshSkipCacheSecs * SECONDS;
+            skipCacheSecs = refreshSecs + 5 * SECONDS;
 
         if (olderThan(lastRefreshAttempt, refreshSecs)) {
             this.lastRefreshAttempt = Date.now();
             try {
                 this.logDebug('Refreshing all tokens:');
                 let tokens = await this.fetchAllTokensAsync(),
-                    aging = pickBy(
-                        tokens,
-                        v => skipCacheSecs > 0 && v.expiresWithin(skipCacheSecs)
-                    );
+                    aging = pickBy(tokens, v => v.expiresWithin(skipCacheSecs));
                 if (!isEmpty(aging)) {
                     this.logDebug(
                         `Tokens [${keys(aging).join(', ')}] have < ${skipCacheSecs}s remaining, reloading without cache.`
                     );
-                    tokens = await this.fetchAllTokensAsync(false);
+                    tokens = await this.fetchAllTokensAsync({useCache: false});
                 }
                 this.logTokensDebug(tokens);
             } catch (e) {

package/security/Token.ts

@@ -11,8 +11,6 @@ import {jwtDecode} from 'jwt-decode';
 import {getRelativeTimestamp} from '@xh/hoist/cmp/relativetimestamp';
 import {isNil} from 'lodash';
 
-export type TokenMap = Record<string, Token>;
-
 export class Token {
     readonly value: string;
     readonly decoded: PlainObject;

package/security/Types.ts

@@ -0,0 +1,22 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+
+import {Token} from './Token';
+
+export type TokenMap = Record<string, Token>;
+
+export interface AccessTokenSpec {
+    /**
+     * Mode governing when the access token should be requested from provider.
+     *      eager (default) - initiate lookup on initialization, but do not block on failure.
+     *      lazy - lookup when requested by client.
+     */
+    fetchMode: 'eager' | 'lazy';
+
+    /** Scopes for the desired access token.*/
+    scopes: string[];
+}

package/security/authzero/AuthZeroClient.ts

@@ -8,7 +8,8 @@ import type {Auth0ClientOptions} from '@auth0/auth0-spa-js';
 import {Auth0Client} from '@auth0/auth0-spa-js';
 import {XH} from '@xh/hoist/core';
 import {wait} from '@xh/hoist/promise';
-import {Token, TokenMap} from '@xh/hoist/security/Token';
+import {Token} from '@xh/hoist/security/Token';
+import {AccessTokenSpec, TokenMap} from '../Types';
 import {SECONDS} from '@xh/hoist/utils/datetime';
 import {mergeDeep, throwIf} from '@xh/hoist/utils/js';
 import {flatMap, union} from 'lodash';
@@ -40,10 +41,7 @@ export interface AuthZeroClientConfig extends BaseOAuthClientConfig<AuthZeroToke
     authZeroClientOptions?: Partial<Auth0ClientOptions>;
 }
 
-export interface AuthZeroTokenSpec {
-    /** Scopes for the desired access token.*/
-    scopes: string[];
-
+export interface AuthZeroTokenSpec extends AccessTokenSpec {
     /**
      * Audience (i.e. API) identifier for AccessToken.  Must be registered with Auth0.
      * Note that this is required to ensure that issued token is a JWT and not an opaque string.
@@ -75,7 +73,7 @@ export class AuthZeroClient extends BaseOAuthClient<AuthZeroClientConfig, AuthZe
             const {appState} = await client.handleRedirectCallback();
             this.restoreRedirectState(appState);
             await this.noteUserAuthenticatedAsync();
-            return this.fetchAllTokensAsync();
+            return this.fetchAllTokensAsync({eagerOnly: true});
         }
 
         // 1) If we are logged in, try to just reload tokens silently.  This is the happy path on
@@ -83,7 +81,7 @@ export class AuthZeroClient extends BaseOAuthClient<AuthZeroClientConfig, AuthZe
         if (await client.isAuthenticated()) {
             try {
                 this.logDebug('Attempting silent token load.');
-                return await this.fetchAllTokensAsync();
+                return await this.fetchAllTokensAsync({eagerOnly: true});
             } catch (e) {
                 this.logDebug('Failed to load tokens on init, fall back to login', e.message ?? e);
             }
@@ -94,7 +92,7 @@ export class AuthZeroClient extends BaseOAuthClient<AuthZeroClientConfig, AuthZe
         await this.loginAsync();
 
         // 3) return tokens
-        return this.fetchAllTokensAsync();
+        return this.fetchAllTokensAsync({eagerOnly: true});
     }
 
     protected override async doLoginRedirectAsync(): Promise<void> {

package/security/msal/MsalClient.ts

@@ -13,7 +13,8 @@ import {
     SilentRequest
 } from '@azure/msal-browser';
 import {XH} from '@xh/hoist/core';
-import {Token, TokenMap} from '@xh/hoist/security/Token';
+import {Token} from '@xh/hoist/security/Token';
+import {AccessTokenSpec, TokenMap} from '../Types';
 import {logDebug, logError, logInfo, logWarn, mergeDeep, throwIf} from '@xh/hoist/utils/js';
 import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
@@ -65,10 +66,7 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     msalClientOptions?: Partial<msal.Configuration>;
 }
 
-export interface MsalTokenSpec {
-    /** Scopes for the desired access token. */
-    scopes: string[];
-
+export interface MsalTokenSpec extends AccessTokenSpec {
     /**
      * Scopes to be added to the scopes requested during interactive and SSO logins.
      * See the `scopes` property on  `PopupRequest`, `RedirectRequest`, and `SSORequest`
@@ -127,7 +125,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             this.logDebug('Completing Redirect login');
             this.noteUserAuthenticated(redirectResp.account);
             this.restoreRedirectState(redirectResp.state);
-            return this.fetchAllTokensAsync();
+            return this.fetchAllTokensAsync({eagerOnly: true});
         }
 
         // 1) If we are logged in, try to just reload tokens silently.  This is the happy path on
@@ -142,7 +140,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             try {
                 this.initialTokenLoad = true;
                 this.logDebug('Attempting silent token load.');
-                return await this.fetchAllTokensAsync();
+                return await this.fetchAllTokensAsync({eagerOnly: true});
             } catch (e) {
                 this.account = null;
                 this.logDebug('Failed to load tokens on init, fall back to login', e.message ?? e);
@@ -171,7 +169,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         }
 
         // 3) Return tokens
-        return this.fetchAllTokensAsync();
+        return this.fetchAllTokensAsync({eagerOnly: true});
     }
 
     protected override async doLoginPopupAsync(): Promise<void> {