@xh/hoist 73.0.0-SNAPSHOT.1744065661676 → 73.0.0-SNAPSHOT.1744121102600

package/CHANGELOG.md

@@ -2,10 +2,31 @@
 
 ## v73.0.0-SNAPSHOT - unreleased
 
+## v72.3.0 - 2025-04-08
+
 ### 🎁 New Features
 
+* Added support for posting a "Client Health Report" track message on a configurable interval. This
+  message will include basic client information, and can be extended to include any other desired
+  data via `XH.trackService.addClientHealthReportSource()`. Enable by updating your app's
+  `xhActivityTrackingConfig` to include `clientHealthReport: {intervalMins: XXXX}`.
+* Enabled opt-in support for telemetry in `MsalClient`, leveraging hooks built-in to MSAL to collect
+  timing and success/failure count for all events emitted by the library.
 * Added the reported client app version as a column in the Admin Console WebSockets tab.
 
+### 🐞 Bug Fixes
+
+* Improved fetch request tracking to include time spent loading headers as specified by application.
+
+### ⚙️ Technical
+
+* Update shape of returned `BrowserUtils.getClientDeviceInfo()` to nest several properties under new
+  top-level `window` key and report JS heap size / usage values under the `memory` block in MB.
+
+### 📚 Libraries
+
+* @azure/msal-browser `3.28 → 4.8.0`
+
 ## v72.2.0 - 2025-03-13
 
 ### 🎁 New Features

package/appcontainer/AppStateModel.ts

@@ -24,8 +24,13 @@ export class AppStateModel extends HoistModel {
     suspendData: AppSuspendData;
     accessDeniedMessage: string = 'Access Denied';
 
+    /**
+     * Timestamp when the app first started loading, prior to even JS download/eval.
+     * Read from timestamp set on window within index.html.
+     */
+    readonly loadStarted: number = window['_xhLoadTimestamp'];
+
     private timings: Record<AppState, number> = {} as Record<AppState, number>;
-    private loadStarted: number = window['_xhLoadTimestamp']; // set in index.html
     private lastStateChangeTime: number = this.loadStarted;
 
     constructor() {

package/build/types/admin/tabs/activity/tracking/ActivityTrackingModel.d.ts

@@ -26,7 +26,10 @@ export declare class ActivityTrackingModel extends HoistModel {
      */
     get queryDisplayString(): string;
     get endDay(): LocalDate;
-    get maxRowOptions(): any;
+    get maxRowOptions(): {
+        value: number;
+        label: string;
+    }[];
     get maxRows(): number;
     /** True if data loaded from the server has been topped by maxRows. */
     get maxRowsReached(): boolean;

package/build/types/appcontainer/AppStateModel.d.ts

@@ -10,8 +10,12 @@ export declare class AppStateModel extends HoistModel {
     lastActivityMs: number;
     suspendData: AppSuspendData;
     accessDeniedMessage: string;
+    /**
+     * Timestamp when the app first started loading, prior to even JS download/eval.
+     * Read from timestamp set on window within index.html.
+     */
+    readonly loadStarted: number;
     private timings;
-    private loadStarted;
     private lastStateChangeTime;
     constructor();
     setAppState(nextState: AppState): void;

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

@@ -1,5 +1,4 @@
 import { Token } from './Token';
-export type TokenMap = Record<string, Token>;
 export interface AccessTokenSpec {
     /**
      * Mode governing when the access token should be requested from provider:
@@ -12,3 +11,29 @@ export interface AccessTokenSpec {
     /** Scopes for the desired access token.*/
     scopes: string[];
 }
+export type TokenMap = Record<string, Token>;
+/** Aggregated telemetry results, produced by {@link MsalClient} when enabled via config. */
+export interface TelemetryResults {
+    /** Stats by event type - */
+    events: Record<string, TelemetryEventResults>;
+}
+/** Aggregated telemetry results for a single type of event. */
+export interface TelemetryEventResults {
+    firstTime: Date;
+    lastTime: Date;
+    successCount: number;
+    failureCount: number;
+    /** Timing info (in ms) for event instances reported with duration. */
+    duration: {
+        count: number;
+        total: number;
+        average: number;
+        worst: number;
+    };
+    lastFailure?: {
+        time: Date;
+        duration: number;
+        code: string;
+        name: string;
+    };
+}

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

@@ -1,8 +1,8 @@
 import * as msal from '@azure/msal-browser';
 import { LogLevel } from '@azure/msal-browser';
 import { Token } from '@xh/hoist/security/Token';
-import { AccessTokenSpec, TokenMap } from '../Types';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
+import { AccessTokenSpec, TelemetryResults, TokenMap } from '../Types';
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
      * Authority for your organization's tenant: `https://login.microsoftonline.com/[tenantId]`.
@@ -16,6 +16,12 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
      * The value of the domain hint is a registered domain for the tenant.
      */
     domainHint?: string;
+    /**
+     * True to enable support for built-in telemetry provided by this class's internal MSAL client.
+     * Captured performance events will be summarized via {@link telemetryResults}.
+     * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/performance.md
+     */
+    enableTelemetry?: boolean;
     /**
      * If specified, the client will use this value when initializing the app to enforce a minimum
      * amount of time during which no further auth flow with the provider should be necessary.
@@ -80,6 +86,9 @@ export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTo
     private client;
     private account;
     private initialTokenLoad;
+    /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
+    telemetryResults: TelemetryResults;
+    private _telemetryCbHandle;
     constructor(config: MsalClientConfig);
     protected doInitAsync(): Promise<TokenMap>;
     protected doLoginPopupAsync(): Promise<void>;
@@ -87,6 +96,8 @@ export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTo
     protected fetchIdTokenAsync(useCache?: boolean): Promise<Token>;
     protected fetchAccessTokenAsync(spec: MsalTokenSpec, useCache?: boolean): Promise<Token>;
     protected doLogoutAsync(): Promise<void>;
+    enableTelemetry(): void;
+    disableTelemetry(): void;
     private loginSsoAsync;
     private createClientAsync;
     private logFromMsal;

package/build/types/svc/TrackService.d.ts

@@ -6,15 +6,45 @@ import { HoistService, TrackOptions } from '@xh/hoist/core';
  */
 export declare class TrackService extends HoistService {
     static instance: TrackService;
+    private clientHealthReportSources;
     private oncePerSessionSent;
     private pending;
     initAsync(): Promise<void>;
-    get conf(): any;
+    get conf(): ActivityTrackingConfig;
     get enabled(): boolean;
     /** Track User Activity. */
     track(options: TrackOptions | string): void;
+    /**
+     * Register a new source for client health report data. No-op if background health report is
+     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
+     *
+     * @param key - key under which to report the data - can be used to remove this source later.
+     * @param callback - function returning serializable to include with each report.
+     */
+    addClientHealthReportSource(key: string, callback: () => any): void;
+    /** Unregister a previously-enabled source for client health report data. */
+    removeClientHealthReportSource(key: string): void;
     private pushPendingAsync;
     private pushPendingBuffered;
     private toServerJson;
     private logMessage;
+    private sendClientHealthReport;
 }
+interface ActivityTrackingConfig {
+    clientHealthReport?: Partial<TrackOptions> & {
+        intervalMins: number;
+    };
+    enabled: boolean;
+    logData: boolean;
+    maxDataLength: number;
+    maxRows?: {
+        default: number;
+        options: number[];
+    };
+    levels?: Array<{
+        username: string | '*';
+        category: string | '*';
+        severity: 'DEBUG' | 'INFO' | 'WARN';
+    }>;
+}
+export {};

package/build/types/utils/js/BrowserUtils.d.ts

@@ -1,4 +1,41 @@
 /**
  * Extract information (if available) about the client browser's window, screen, and network speed.
  */
-export declare function getClientDeviceInfo(): any;
+export declare function getClientDeviceInfo(): ClientDeviceInfo;
+export interface ClientDeviceInfo {
+    window: {
+        devicePixelRatio: number;
+        screenX: number;
+        screenY: number;
+        innerWidth: number;
+        innerHeight: number;
+        outerWidth: number;
+        outerHeight: number;
+    };
+    screen?: {
+        availWidth: number;
+        availHeight: number;
+        width: number;
+        height: number;
+        colorDepth: number;
+        pixelDepth: number;
+        availLeft: number;
+        availTop: number;
+        orientation?: {
+            angle: number;
+            type: string;
+        };
+    };
+    connection?: {
+        downlink: number;
+        effectiveType: string;
+        rtt: number;
+    };
+    memory: {
+        modelCount: number;
+        usedPctLimit?: number;
+        jsHeapSizeLimit?: number;
+        totalJSHeapSize?: number;
+        usedJSHeapSize?: number;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "73.0.0-SNAPSHOT.1744065661676",
+  "version": "73.0.0-SNAPSHOT.1744121102600",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@auth0/auth0-spa-js": "~2.1.3",
-    "@azure/msal-browser": "~3.28.0",
+    "@azure/msal-browser": "~4.8.0",
     "@blueprintjs/core": "^5.10.5",
     "@blueprintjs/datetime": "^5.3.7",
     "@blueprintjs/datetime2": "^2.3.7",

package/security/BaseOAuthClient.ts

@@ -119,7 +119,7 @@ export abstract class BaseOAuthClient<
         throwIf(!config.clientId, 'Missing OAuth clientId. Please review your configuration.');
 
         this.idScopes = union(['openid', 'email'], config.idScopes);
-        this.accessSpecs = this.config.accessTokens;
+        this.accessSpecs = this.config.accessTokens ?? {};
     }
 
     /**
@@ -163,7 +163,10 @@ export abstract class BaseOAuthClient<
      * Get an Access token.
      */
     async getAccessTokenAsync(key: string): Promise<Token> {
-        return this.fetchAccessTokenAsync(this.accessSpecs[key], true);
+        const spec = this.accessSpecs[key];
+        if (!spec) throw XH.exception(`No access token spec configured for key "${key}"`);
+
+        return this.fetchAccessTokenAsync(spec, true);
     }
 
     /**

package/security/Types.ts

@@ -7,8 +7,6 @@
 
 import {Token} from './Token';
 
-export type TokenMap = Record<string, Token>;
-
 export interface AccessTokenSpec {
     /**
      * Mode governing when the access token should be requested from provider:
@@ -22,3 +20,32 @@ export interface AccessTokenSpec {
     /** Scopes for the desired access token.*/
     scopes: string[];
 }
+
+export type TokenMap = Record<string, Token>;
+
+/** Aggregated telemetry results, produced by {@link MsalClient} when enabled via config. */
+export interface TelemetryResults {
+    /** Stats by event type - */
+    events: Record<string, TelemetryEventResults>;
+}
+
+/** Aggregated telemetry results for a single type of event. */
+export interface TelemetryEventResults {
+    firstTime: Date;
+    lastTime: Date;
+    successCount: number;
+    failureCount: number;
+    /** Timing info (in ms) for event instances reported with duration. */
+    duration: {
+        count: number;
+        total: number;
+        average: number;
+        worst: number;
+    };
+    lastFailure?: {
+        time: Date;
+        duration: number;
+        code: string;
+        name: string;
+    };
+}

package/security/msal/MsalClient.ts

@@ -7,6 +7,8 @@
 import * as msal from '@azure/msal-browser';
 import {
     AccountInfo,
+    BrowserPerformanceClient,
+    Configuration,
     IPublicClientApplication,
     LogLevel,
     PopupRequest,
@@ -14,10 +16,10 @@ import {
 } from '@azure/msal-browser';
 import {XH} from '@xh/hoist/core';
 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';
+import {AccessTokenSpec, TelemetryResults, TokenMap} from '../Types';
 
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
@@ -34,6 +36,13 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
      */
     domainHint?: string;
 
+    /**
+     * True to enable support for built-in telemetry provided by this class's internal MSAL client.
+     * Captured performance events will be summarized via {@link telemetryResults}.
+     * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/performance.md
+     */
+    enableTelemetry?: boolean;
+
     /**
      * If specified, the client will use this value when initializing the app to enforce a minimum
      * amount of time during which no further auth flow with the provider should be necessary.
@@ -104,6 +113,10 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     private account: AccountInfo; // Authenticated account
     private initialTokenLoad: boolean;
 
+    /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
+    telemetryResults: TelemetryResults = {events: {}};
+    private _telemetryCbHandle: string = null;
+
     constructor(config: MsalClientConfig) {
         super({
             initRefreshTokenExpirationOffsetSecs: -1,
@@ -118,6 +131,9 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     //-------------------------------------------
     protected override async doInitAsync(): Promise<TokenMap> {
         const client = (this.client = await this.createClientAsync());
+        if (this.config.enableTelemetry) {
+            this.enableTelemetry();
+        }
 
         // 0) Handle redirect return
         const redirectResp = await client.handleRedirectPromise();
@@ -247,6 +263,86 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             : await client.logoutPopup(opts);
     }
 
+    //------------------------
+    // Telemetry
+    //------------------------
+    enableTelemetry(): void {
+        if (this._telemetryCbHandle) {
+            this.logInfo('Telemetry already enabled', this.telemetryResults);
+            return;
+        }
+
+        this.telemetryResults = {events: {}};
+
+        this._telemetryCbHandle = this.client.addPerformanceCallback(events => {
+            events.forEach(e => {
+                try {
+                    const {events} = this.telemetryResults,
+                        {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
+                        eTime = startTimeMs ? new Date(startTimeMs) : new Date();
+
+                    const eResult = (events[name] ??= {
+                        firstTime: eTime,
+                        lastTime: eTime,
+                        successCount: 0,
+                        failureCount: 0,
+                        duration: {count: 0, total: 0, average: 0, worst: 0},
+                        lastFailure: null
+                    });
+                    eResult.lastTime = eTime;
+
+                    if (success) {
+                        eResult.successCount++;
+                    } else {
+                        eResult.failureCount++;
+                        eResult.lastFailure = {
+                            time: eTime,
+                            duration: e.durationMs,
+                            code: errorCode,
+                            name: errorName
+                        };
+                    }
+
+                    if (durationMs) {
+                        const {duration} = eResult;
+                        duration.count++;
+                        duration.total += durationMs;
+                        duration.average = Math.round(duration.total / duration.count);
+                        duration.worst = Math.max(duration.worst, durationMs);
+                    }
+                } catch (e) {
+                    this.logError(`Error processing telemetry event`, e);
+                }
+            });
+        });
+
+        // Ask TrackService to include in background health check report, if enabled on that service.
+        // Handle TrackService not yet initialized (common, this client likely initialized before.)
+        this.addReaction({
+            when: () => XH.appIsRunning,
+            run: () =>
+                XH.trackService.addClientHealthReportSource(
+                    'msalClient',
+                    () => this.telemetryResults
+                )
+        });
+
+        this.logInfo('Telemetry enabled');
+    }
+
+    disableTelemetry(): void {
+        if (!this._telemetryCbHandle) {
+            this.logInfo('Telemetry already disabled');
+            return;
+        }
+
+        this.client.removePerformanceCallback(this._telemetryCbHandle);
+        this._telemetryCbHandle = null;
+
+        XH.trackService.removeClientHealthReportSource('msalClient');
+        this.logInfo('Telemetry disabled', this.telemetryResults);
+    }
+
     //------------------------
     // Private implementation
     //------------------------
@@ -263,29 +359,38 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     }
 
     private async createClientAsync(): Promise<IPublicClientApplication> {
-        const {clientId, authority, msalLogLevel, msalClientOptions} = this.config;
+        const {clientId, authority, msalLogLevel, msalClientOptions, enableTelemetry} = this.config;
         throwIf(!authority, 'Missing MSAL authority. Please review your configuration.');
 
-        return msal.PublicClientApplication.createPublicClientApplication(
-            mergeDeep(
-                {
-                    auth: {
-                        clientId,
-                        authority,
-                        postLogoutRedirectUri: this.postLogoutRedirectUrl
-                    },
-                    system: {
-                        loggerOptions: {
-                            loggerCallback: this.logFromMsal,
-                            logLevel: msalLogLevel
-                        }
-                    },
-                    cache: {
-                        cacheLocation: 'localStorage' // allows sharing auth info across tabs.
+        const mergedConf: Configuration = mergeDeep(
+            {
+                auth: {
+                    clientId,
+                    authority,
+                    postLogoutRedirectUri: this.postLogoutRedirectUrl
+                },
+                system: {
+                    loggerOptions: {
+                        loggerCallback: this.logFromMsal,
+                        logLevel: msalLogLevel
                     }
                 },
-                msalClientOptions
-            )
+                cache: {
+                    cacheLocation: 'localStorage' // allows sharing auth info across tabs.
+                }
+            },
+            msalClientOptions
+        );
+
+        return msal.PublicClientApplication.createPublicClientApplication(
+            enableTelemetry
+                ? {
+                      ...mergedConf,
+                      telemetry: {
+                          client: new BrowserPerformanceClient(mergedConf)
+                      }
+                  }
+                : mergedConf
         );
     }
 

package/svc/FetchService.ts

@@ -217,8 +217,9 @@ export class FetchService extends HoistService {
     //-----------------------
     private async fetchInternalAsync(opts: FetchOptions): Promise<any> {
         opts = this.withCorrelationId(opts);
-        opts = await this.withDefaultHeadersAsync(opts);
-        let ret = this.managedFetchAsync(opts);
+
+        // Core Promise - chained with custom headers callback to ensure that work is included in overall tracked time.
+        let ret = this.withDefaultHeadersAsync(opts).then(opts => this.managedFetchAsync(opts));
 
         // Apply tracking
         const {correlationId, loadSpec, track} = opts;