@xh/hoist 73.0.0-SNAPSHOT.1744281639439 → 73.0.0-SNAPSHOT.1744315927263

package/CHANGELOG.md

@@ -2,15 +2,22 @@
 
 ## v73.0.0-SNAPSHOT - unreleased
 
+### 🎁 New Features
+
+* Added option from the Admin Console > Websockets tab to request a client health report from any
+  connected clients.
+
 ## v72.4.0 - 2025-04-09
 
 ### 🎁 New Features
-* New methods for formatting timestamps within nested JSON objects.  See `withFormattedTimestamps`
+
+* Added new methods for formatting timestamps within JSON objects. See `withFormattedTimestamps`
   and `timestampReplacer` in the `@xh/hoist/format` package.
-* `ViewManagerConfig` takes new optional key `viewMenuItemFn` to allow ViewManager implementations
-  to customize the menu items for views in the view manager menu.
+* Added new `ViewManagerConfig.viewMenuItemFn` option to support custom rendering of pinned views in
+  the drop-down menu.
 
 ### ⚙️ Technical
+
 * Added dedicated `ClientHealthService` for managing client health report. Additional enhancements
   to health report to include information about web sockets, idle time, and page state.
 
@@ -30,11 +37,6 @@
 
 * 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`

package/admin/tabs/cluster/instances/websocket/WebSocketModel.ts

@@ -5,20 +5,21 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {exportFilenameWithDate} from '@xh/hoist/admin/AdminUtils';
+import {AppModel} from '@xh/hoist/admin/AppModel';
 import * as Col from '@xh/hoist/admin/columns';
 import {BaseInstanceModel} from '@xh/hoist/admin/tabs/cluster/instances/BaseInstanceModel';
 import {GridModel} from '@xh/hoist/cmp/grid';
 import {div, p} from '@xh/hoist/cmp/layout';
 import {LoadSpec, managed, XH} from '@xh/hoist/core';
+import {RecordActionSpec, StoreRecord} from '@xh/hoist/data';
 import {textInput} from '@xh/hoist/desktop/cmp/input';
 import {Icon} from '@xh/hoist/icon';
 import {makeObservable, observable, runInAction} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
 import {SECONDS} from '@xh/hoist/utils/datetime';
+import {pluralize} from '@xh/hoist/utils/js';
 import {isEmpty} from 'lodash';
 import * as WSCol from './WebSocketColumns';
-import {RecordActionSpec} from '@xh/hoist/data';
-import {AppModel} from '@xh/hoist/admin/AppModel';
 
 export class WebSocketModel extends BaseInstanceModel {
     @observable
@@ -34,11 +35,19 @@ export class WebSocketModel extends BaseInstanceModel {
         text: 'Force suspend',
         icon: Icon.stopCircle(),
         intent: 'danger',
-        actionFn: () => this.forceSuspendAsync(),
+        actionFn: ({selectedRecords}) => this.forceSuspendAsync(selectedRecords),
         displayFn: () => ({hidden: AppModel.readonly}),
         recordsRequired: true
     };
 
+    reqHealthReportAction: RecordActionSpec = {
+        text: 'Request Health Report',
+        icon: Icon.health(),
+        actionFn: ({selectedRecords}) => this.requestHealthReportAsync(selectedRecords),
+        recordsRequired: true,
+        hidden: !XH.trackService.enabled
+    };
+
     constructor() {
         super();
         makeObservable(this);
@@ -48,7 +57,12 @@ export class WebSocketModel extends BaseInstanceModel {
             enableExport: true,
             exportOptions: {filename: exportFilenameWithDate('ws-connections')},
             selModel: 'multiple',
-            contextMenu: [this.forceSuspendAction, '-', ...GridModel.defaultContextMenu],
+            contextMenu: [
+                this.forceSuspendAction,
+                this.reqHealthReportAction,
+                '-',
+                ...GridModel.defaultContextMenu
+            ],
             store: {
                 idSpec: 'key',
                 processRawData: row => {
@@ -107,9 +121,8 @@ export class WebSocketModel extends BaseInstanceModel {
         }
     }
 
-    async forceSuspendAsync() {
-        const {selectedRecords} = this.gridModel;
-        if (isEmpty(selectedRecords)) return;
+    async forceSuspendAsync(toRecs: StoreRecord[]) {
+        if (isEmpty(toRecs)) return;
 
         const message = await XH.prompt<string>({
             title: 'Please confirm...',
@@ -123,7 +136,7 @@ export class WebSocketModel extends BaseInstanceModel {
             },
             message: div(
                 p(
-                    `This action will force ${selectedRecords.length} connected client(s) into suspended mode, halting all background refreshes and other activity, masking the UI, and requiring users to reload the app to continue.`
+                    `This action will force ${toRecs.length} connected client(s) into suspended mode, halting all background refreshes and other activity, masking the UI, and requiring users to reload the app to continue.`
                 ),
                 p('Enter an optional message below to display within the suspended app.')
             ),
@@ -134,23 +147,58 @@ export class WebSocketModel extends BaseInstanceModel {
         });
 
         if (message !== false) {
-            const tasks = selectedRecords.map(rec =>
-                XH.fetchJson({
-                    url: 'webSocketAdmin/pushToChannel',
-                    params: {
-                        channelKey: rec.data.key,
-                        topic: XH.webSocketService.FORCE_APP_SUSPEND_TOPIC,
-                        instance: this.instanceName,
-                        message
-                    }
-                })
-            );
-
-            await Promise.allSettled(tasks).track({
-                category: 'Audit',
-                message: 'Suspended clients via WebSocket',
-                data: {users: selectedRecords.map(it => it.data.user).sort()}
+            await this.bulkPush({
+                toRecs,
+                topic: XH.webSocketService.FORCE_APP_SUSPEND_TOPIC,
+                message,
+                trackMessage: 'Suspended clients via WebSocket'
             });
         }
     }
+
+    async requestHealthReportAsync(toRecs: StoreRecord[]) {
+        await this.bulkPush({
+            toRecs,
+            topic: XH.webSocketService.REQ_CLIENT_HEALTH_RPT_TOPIC
+        });
+        XH.successToast(
+            `Client health report requested for ${pluralize('client', toRecs.length, true)} - available in User Activity shortly...`
+        );
+    }
+
+    //------------------
+    // Implementation
+    //------------------
+    private async bulkPush({
+        toRecs,
+        topic,
+        message,
+        trackMessage
+    }: {
+        toRecs?: StoreRecord[];
+        topic: string;
+        message?: string;
+        trackMessage?: string;
+    }) {
+        if (isEmpty(toRecs)) return;
+
+        const tasks = toRecs.map(rec =>
+            XH.fetchJson({
+                url: 'webSocketAdmin/pushToChannel',
+                params: {
+                    channelKey: rec.data.key,
+                    instance: this.instanceName,
+                    topic,
+                    message
+                }
+            })
+        );
+
+        await Promise.allSettled(tasks).track({
+            category: 'Audit',
+            message: trackMessage,
+            data: {users: toRecs.map(it => it.data.user).sort()},
+            omit: !trackMessage
+        });
+    }
 }

package/admin/tabs/cluster/instances/websocket/WebSocketPanel.ts

@@ -16,7 +16,7 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {recordActionBar} from '@xh/hoist/desktop/cmp/record';
 import {toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
 
-export const webSocketPanel = hoistCmp.factory({
+export const webSocketPanel = hoistCmp.factory<WebSocketModel>({
     model: creates(WebSocketModel),
 
     render({model}) {
@@ -26,7 +26,7 @@ export const webSocketPanel = hoistCmp.factory({
             bbar: [
                 recordActionBar({
                     selModel: model.gridModel.selModel,
-                    actions: [model.forceSuspendAction]
+                    actions: [model.forceSuspendAction, model.reqHealthReportAction]
                 }),
                 filler(),
                 relativeTimestamp({bind: 'lastRefresh', options: {prefix: 'Refreshed'}}),

package/build/types/admin/tabs/cluster/instances/websocket/WebSocketModel.d.ts

@@ -1,13 +1,16 @@
 import { BaseInstanceModel } from '@xh/hoist/admin/tabs/cluster/instances/BaseInstanceModel';
 import { GridModel } from '@xh/hoist/cmp/grid';
 import { LoadSpec } from '@xh/hoist/core';
-import { RecordActionSpec } from '@xh/hoist/data';
+import { RecordActionSpec, StoreRecord } from '@xh/hoist/data';
 export declare class WebSocketModel extends BaseInstanceModel {
     lastRefresh: number;
     gridModel: GridModel;
     private _timer;
     forceSuspendAction: RecordActionSpec;
+    reqHealthReportAction: RecordActionSpec;
     constructor();
     doLoadAsync(loadSpec: LoadSpec): Promise<void>;
-    forceSuspendAsync(): Promise<void>;
+    forceSuspendAsync(toRecs: StoreRecord[]): Promise<void>;
+    requestHealthReportAsync(toRecs: StoreRecord[]): Promise<void>;
+    private bulkPush;
 }

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

@@ -14,7 +14,14 @@ export interface AccessTokenSpec {
 export type TokenMap = Record<string, Token>;
 /** Aggregated telemetry results, produced by {@link MsalClient} when enabled via config. */
 export interface TelemetryResults {
-    /** Stats by event type - */
+    /** Stats across all events */
+    summary: {
+        successCount: number;
+        failureCount: number;
+        maxDuration: number;
+        lastFailureTime: number;
+    };
+    /** Stats by event type */
     events: Record<string, TelemetryEventResults>;
 }
 /** Aggregated telemetry results for a single type of event. */
@@ -24,11 +31,11 @@ export interface TelemetryEventResults {
     successCount: number;
     failureCount: number;
     /** Timing info (in ms) for event instances reported with duration. */
-    duration: {
+    duration?: {
         count: number;
         total: number;
         average: number;
-        worst: number;
+        max: number;
     };
     lastFailure?: {
         time: number;

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

@@ -27,7 +27,7 @@ export declare class ClientHealthService extends HoistService {
     /**
      * Generate and submit a report to the server, via TrackService.
      *
-     * For ad-hoc troubleshooting.  Apps may also configure this service to
+     * For ad-hoc troubleshooting. Apps may also configure this service to
      * submit on regular intervals.
      */
     sendReportAsync(): Promise<void>;

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

@@ -27,6 +27,7 @@ export declare class WebSocketService extends HoistService {
     readonly HEARTBEAT_TOPIC = "xhHeartbeat";
     readonly REG_SUCCESS_TOPIC = "xhRegistrationSuccess";
     readonly FORCE_APP_SUSPEND_TOPIC = "xhForceAppSuspend";
+    readonly REQ_CLIENT_HEALTH_RPT_TOPIC = "xhRequestClientHealthReport";
     /** Unique channel assigned by server upon successful connection. */
     channelKey: string;
     /** Last time a message was received, including heartbeat messages. */
@@ -69,7 +70,7 @@ export declare class WebSocketService extends HoistService {
     onOpen(ev: any): void;
     onClose(ev: any): void;
     onError(ev: any): void;
-    onMessage(rawMsg: any): void;
+    onMessage(rawMsg: MessageEvent): void;
     notifySubscribers(message: any): void;
     getSubsForTopic(topic: any): WebSocketSubscription[];
     updateConnectedStatus(): void;

package/package.json

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

package/security/Types.ts

@@ -25,7 +25,14 @@ export type TokenMap = Record<string, Token>;
 
 /** Aggregated telemetry results, produced by {@link MsalClient} when enabled via config. */
 export interface TelemetryResults {
-    /** Stats by event type - */
+    /** Stats across all events */
+    summary: {
+        successCount: number;
+        failureCount: number;
+        maxDuration: number;
+        lastFailureTime: number;
+    };
+    /** Stats by event type */
     events: Record<string, TelemetryEventResults>;
 }
 
@@ -36,11 +43,11 @@ export interface TelemetryEventResults {
     successCount: number;
     failureCount: number;
     /** Timing info (in ms) for event instances reported with duration. */
-    duration: {
+    duration?: {
         count: number;
         total: number;
         average: number;
-        worst: number;
+        max: number;
     };
     lastFailure?: {
         time: number;

package/security/msal/MsalClient.ts

@@ -115,7 +115,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     private initialTokenLoad: boolean;
 
     /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
-    telemetryResults: TelemetryResults = {events: {}};
+    telemetryResults: TelemetryResults = null;
     private _telemetryCbHandle: string = null;
 
     constructor(config: MsalClientConfig) {
@@ -277,12 +277,20 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             return;
         }
 
-        this.telemetryResults = {events: {}};
+        this.telemetryResults = {
+            summary: {
+                successCount: 0,
+                failureCount: 0,
+                maxDuration: 0,
+                lastFailureTime: null
+            },
+            events: {}
+        };
 
         this._telemetryCbHandle = this.client.addPerformanceCallback(events => {
             events.forEach(e => {
                 try {
-                    const {events} = this.telemetryResults,
+                    const {summary, events} = this.telemetryResults,
                         {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
                         eTime = startTimeMs ?? Date.now();
 
@@ -290,15 +298,16 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                         firstTime: eTime,
                         lastTime: eTime,
                         successCount: 0,
-                        failureCount: 0,
-                        duration: {count: 0, total: 0, average: 0, worst: 0},
-                        lastFailure: null
+                        failureCount: 0
                     });
                     eResult.lastTime = eTime;
 
                     if (success) {
+                        summary.successCount++;
                         eResult.successCount++;
                     } else {
+                        summary.failureCount++;
+                        summary.lastFailureTime = eTime;
                         eResult.failureCount++;
                         eResult.lastFailure = {
                             time: eTime,
@@ -309,11 +318,17 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                     }
 
                     if (durationMs) {
-                        const {duration} = eResult;
+                        const duration = (eResult.duration ??= {
+                            count: 0,
+                            total: 0,
+                            average: 0,
+                            max: 0
+                        });
                         duration.count++;
                         duration.total += durationMs;
                         duration.average = Math.round(duration.total / duration.count);
-                        duration.worst = Math.max(duration.worst, durationMs);
+                        duration.max = Math.max(duration.max, durationMs);
+                        summary.maxDuration = Math.max(summary.maxDuration, durationMs);
                     }
                 } catch (e) {
                     this.logError(`Error processing telemetry event`, e);

package/svc/ClientHealthService.ts

@@ -68,7 +68,7 @@ export class ClientHealthService extends HoistService {
     /**
      * Generate and submit a report to the server, via TrackService.
      *
-     * For ad-hoc troubleshooting.  Apps may also configure this service to
+     * For ad-hoc troubleshooting. Apps may also configure this service to
      * submit on regular intervals.
      */
     async sendReportAsync() {

package/svc/WebSocketService.ts

@@ -41,6 +41,7 @@ export class WebSocketService extends HoistService {
     readonly HEARTBEAT_TOPIC = 'xhHeartbeat';
     readonly REG_SUCCESS_TOPIC = 'xhRegistrationSuccess';
     readonly FORCE_APP_SUSPEND_TOPIC = 'xhForceAppSuspend';
+    readonly REQ_CLIENT_HEALTH_RPT_TOPIC = 'xhRequestClientHealthReport';
 
     /** Unique channel assigned by server upon successful connection. */
     @observable
@@ -210,7 +211,7 @@ export class WebSocketService extends HoistService {
         this.updateConnectedStatus();
     }
 
-    onMessage(rawMsg) {
+    onMessage(rawMsg: MessageEvent) {
         try {
             const msg = JSON.parse(rawMsg.data),
                 {topic, data} = msg;
@@ -228,6 +229,9 @@ export class WebSocketService extends HoistService {
                     XH.suspendApp({reason: 'SERVER_FORCE', message: data});
                     XH.track({category: 'App', message: 'App suspended via WebSocket'});
                     break;
+                case this.REQ_CLIENT_HEALTH_RPT_TOPIC:
+                    XH.clientHealthService.sendReportAsync();
+                    break;
             }
 
             this.notifySubscribers(msg);