@xh/hoist 73.0.0-SNAPSHOT.1744229935910 → 73.0.0-SNAPSHOT.1744315607129

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

@@ -1,36 +1,41 @@
 import { HoistService, PageState, PlainObject } from '@xh/hoist/core';
 /**
- * Service for gathering data about client health.
+ * Service for gathering data about the current state and health of the client app, for submission
+ * to the server or review on the console during interactive troubleshooting.
  *
- * Hoist sends this data once on application load, and can be configured to send
- * it at regularly scheduled intervals.  Configure via soft-config property
- * 'xhActivityTracking.clientHealthReport'.
+ * Hoist sends this data once on application load and can be configured to send at regular intervals
+ * throughout a user's session via the `xhActivityTracking.clientHealthReport` app config. Reports
+ * are submitted via activity tracking for review within the Admin Console.
  */
 export declare class ClientHealthService extends HoistService {
     static instance: ClientHealthService;
     private sources;
     initAsync(): Promise<void>;
-    /**
-     * Main entry point.  Return a default report of client health.
-     */
+    get enabled(): boolean;
+    /** @returns a customizable report with metrics capturing client app/session state. */
     getReport(): ClientHealthReport;
-    /** Get report, suitable for viewing in console. **/
+    /** @returns a report, formatted for easier viewing in console. **/
     getFormattedReport(): PlainObject;
     /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
+     * Register a new source for app-specific data to be sent with each report.
      * @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.
      */
     addSource(key: string, callback: () => any): void;
     /** Unregister a previously-enabled source for client health report data. */
     removeSource(key: string): void;
+    /**
+     * Generate and submit a report to the server, via TrackService.
+     *
+     * For ad-hoc troubleshooting.  Apps may also configure this service to
+     * submit on regular intervals.
+     */
+    sendReportAsync(): Promise<void>;
     getGeneral(): GeneralData;
     getConnection(): ConnectionData;
     getMemory(): MemoryData;
     getCustom(): PlainObject;
-    private sendReport;
+    private sendReportInternal;
 }
 export interface GeneralData {
     startTime: number;

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

@@ -13,7 +13,11 @@ export declare class TrackService extends HoistService {
     get enabled(): boolean;
     /** Track User Activity. */
     track(options: TrackOptions | string): void;
-    private pushPendingAsync;
+    /**
+     * Flush the queue of pending activity tracking messages to the server.
+     * @internal - apps should generally allow this service to manage w/its internal debounce.
+     */
+    pushPendingAsync(): Promise<void>;
     private pushPendingBuffered;
     private toServerJson;
     private logMessage;

package/desktop/appcontainer/AboutDialog.ts

@@ -42,10 +42,24 @@ export const aboutDialog = hoistCmp.factory({
                     item: model.getTable()
                 }),
                 toolbar(
+                    button({
+                        text: 'Send Client Health Report',
+                        icon: Icon.health(),
+                        omit: !XH.clientHealthService.enabled,
+                        onClick: async () => {
+                            try {
+                                await XH.clientHealthService.sendReportAsync();
+                                XH.successToast('Client health report successfully submitted.');
+                            } catch (e) {
+                                XH.handleException('Error sending client health report', e);
+                            }
+                        }
+                    }),
                     filler(),
                     button({
                         text: 'Close',
                         intent: 'primary',
+                        outlined: true,
                         onClick: onClose
                     })
                 )

package/kit/onsen/theme.scss

@@ -118,6 +118,11 @@ body.xh-app.xh-mobile {
     color: var(--xh-text-color);
   }
 
+  // Toast - ensure z-index exceeds dialogs
+  ons-toast {
+    z-index: 30001 !important;
+  }
+
   // Remove outlines
   .tabbar__button:focus {
     outline: none;

package/mobile/appcontainer/AboutDialog.scss

@@ -6,7 +6,7 @@
 
   th {
     text-align: right;
-    vertical-align: top;
+    vertical-align: middle;
     white-space: nowrap;
     background-color: var(--xh-bg-alt);
     border-bottom: var(--xh-border-solid);

package/mobile/appcontainer/AboutDialog.ts

@@ -30,7 +30,30 @@ export const aboutDialog = hoistCmp.factory({
             className: 'xh-about-dialog',
             item: model.getTable(),
             isOpen: model.isOpen,
-            bbar: [filler(), button({text: 'Close', onClick: () => model.hide()})]
+            bbar: [
+                button({
+                    text: 'Send Client Health Report',
+                    icon: Icon.health(),
+                    omit: !XH.clientHealthService.enabled,
+                    onClick: async () => {
+                        try {
+                            await XH.clientHealthService.sendReportAsync();
+                            XH.successToast({
+                                message: 'Client health report submitted.',
+                                timeout: 2000
+                            });
+                        } catch (e) {
+                            XH.handleException('Error sending client health report', e);
+                        }
+                    }
+                }),
+                filler(),
+                button({
+                    text: 'Close',
+                    outlined: true,
+                    onClick: () => model.hide()
+                })
+            ]
         });
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "73.0.0-SNAPSHOT.1744229935910",
+  "version": "73.0.0-SNAPSHOT.1744315607129",
   "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

@@ -4,18 +4,19 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {HoistService, PageState, PlainObject, XH} from '@xh/hoist/core';
+import {HoistService, PageState, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
 import {Timer} from '@xh/hoist/utils/async';
 import {MINUTES} from '@xh/hoist/utils/datetime';
 import {withFormattedTimestamps} from '@xh/hoist/format';
 import {pick, round} from 'lodash';
 
 /**
- * Service for gathering data about client health.
+ * Service for gathering data about the current state and health of the client app, for submission
+ * to the server or review on the console during interactive troubleshooting.
  *
- * Hoist sends this data once on application load, and can be configured to send
- * it at regularly scheduled intervals.  Configure via soft-config property
- * 'xhActivityTracking.clientHealthReport'.
+ * Hoist sends this data once on application load and can be configured to send at regular intervals
+ * throughout a user's session via the `xhActivityTracking.clientHealthReport` app config. Reports
+ * are submitted via activity tracking for review within the Admin Console.
  */
 export class ClientHealthService extends HoistService {
     static instance: ClientHealthService;
@@ -25,15 +26,17 @@ export class ClientHealthService extends HoistService {
     override async initAsync() {
         const {clientHealthReport} = XH.trackService.conf;
         Timer.create({
-            runFn: () => this.sendReport(),
+            runFn: () => this.sendReportInternal(),
             interval: clientHealthReport.intervalMins * MINUTES,
             delay: true
         });
     }
 
-    /**
-     * Main entry point.  Return a default report of client health.
-     */
+    get enabled(): boolean {
+        return XH.trackService.enabled;
+    }
+
+    /** @returns a customizable report with metrics capturing client app/session state. */
     getReport(): ClientHealthReport {
         return {
             general: this.getGeneral(),
@@ -43,15 +46,13 @@ export class ClientHealthService extends HoistService {
         };
     }
 
-    /** Get report, suitable for viewing in console. **/
+    /** @returns a report, formatted for easier viewing in console. **/
     getFormattedReport(): PlainObject {
         return withFormattedTimestamps(this.getReport());
     }
 
     /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
+     * Register a new source for app-specific data to be sent with each report.
      * @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.
      */
@@ -64,6 +65,17 @@ export class ClientHealthService extends HoistService {
         this.sources.delete(key);
     }
 
+    /**
+     * Generate and submit a report to the server, via TrackService.
+     *
+     * For ad-hoc troubleshooting.  Apps may also configure this service to
+     * submit on regular intervals.
+     */
+    async sendReportAsync() {
+        this.sendReportInternal({severity: 'INFO'});
+        await XH.trackService.pushPendingAsync();
+    }
+
     // -----------------------------------
     // Generate individual report sections
     //------------------------------------
@@ -117,16 +129,17 @@ export class ClientHealthService extends HoistService {
         return ret;
     }
 
-    //------------------
+    //---------------------
     // Implementation
-    //------------------
-    private sendReport() {
+    //---------------------
+    private sendReportInternal(opts: Partial<TrackOptions> = {}) {
         const {intervalMins, ...rest} = XH.trackService.conf.clientHealthReport ?? {};
 
         XH.track({
             category: 'App',
             message: 'Submitted health report',
             ...rest,
+            ...opts,
             data: {
                 clientId: XH.clientId,
                 sessionId: XH.sessionId,

package/svc/TrackService.ts

@@ -90,10 +90,11 @@ export class TrackService extends HoistService {
         this.pushPendingBuffered();
     }
 
-    //------------------
-    // Implementation
-    //------------------
-    private async pushPendingAsync() {
+    /**
+     * Flush the queue of pending activity tracking messages to the server.
+     * @internal - apps should generally allow this service to manage w/its internal debounce.
+     */
+    async pushPendingAsync() {
         const {pending} = this;
         if (isEmpty(pending)) return;
 
@@ -105,6 +106,9 @@ export class TrackService extends HoistService {
         });
     }
 
+    //------------------
+    // Implementation
+    //------------------
     @debounced(10 * SECONDS)
     private pushPendingBuffered() {
         this.pushPendingAsync();