@xh/hoist 82.0.1 → 82.0.3

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

@@ -0,0 +1,172 @@
+import { HoistBase } from '@xh/hoist/core';
+import { Token } from '@xh/hoist/security/Token';
+import { AccessTokenSpec, TokenMap } from './Types';
+export type LoginMethod = 'REDIRECT' | 'POPUP';
+export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
+    /** Client ID (GUID) of your app registered with your Oauth provider. */
+    clientId: string;
+    /**
+     * Redirect URL where authentication responses can be received by your application.
+     * It must exactly match one of the redirect URIs registered in the relevant OAuth authority.
+     * Default is 'APP_BASE_URL' which will be replaced with the current app's base URL.
+     */
+    redirectUrl?: 'APP_BASE_URL' | string;
+    /**
+     * Redirect URL after a successful logout.
+     * Default is 'APP_BASE_URL' which will be replaced with the current app's base URL.
+     */
+    postLogoutRedirectUrl?: 'APP_BASE_URL' | string;
+    /** The method used for logging in on desktop. Default is 'REDIRECT'. */
+    loginMethodDesktop?: LoginMethod;
+    /** The method used for logging in on mobile. Default is 'REDIRECT'. */
+    loginMethodMobile?: LoginMethod;
+    /**
+     * 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 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.
+     *
+     * Default is -1, disabling this behavior.
+     */
+    autoRefreshSecs?: number;
+    /**
+     * Scopes to request - if any - beyond the core `['openid', 'email']` scopes, which
+     * this client will always request.
+     */
+    idScopes?: string[];
+    /**
+     * Optional spec for access tokens to be loaded and maintained to support access to one or more
+     * different back-end resources, distinct from the core Hoist auth flow via ID token.
+     *
+     * Map of key to a spec for an access token. The key is an arbitrary, app-determined string
+     * used to retrieve the loaded token via {@link getAccessTokenAsync}. The spec is implementation
+     * specific, but will typically include scopes to be loaded for the access token and potentially
+     * other metadata required by the underlying provider.
+     */
+    accessTokens?: Record<string, S>;
+    /**
+     * True to allow this client to try to re-login interactively (via pop-up) if tokens begin
+     * failing to load due to specific provider exceptions indicating user interaction is required.
+     * This can happen, for example, if a token expires and the refresh token is expired or
+     * invalidated during the lifetime of the client.  Default is false and retry will not be
+     * attempted.
+     */
+    reloginEnabled?: boolean;
+    /**
+     * Maximum time for (interactive) re-login.
+     *
+     * Set to a reasonably fixed amount of time, to allow user to type in password and complete
+     * MFA, but not so long as to allow a problematic build-up of application requests.
+     * Default 60 seconds;
+     */
+    reloginTimeoutSecs?: number;
+}
+/**
+ * Implementations of this class coordinate OAuth-based login and token provision. Apps can use a
+ * suitable concrete implementation to power a client-side OauthService. See `MsalClient` and
+ * `AuthZeroClient`
+ *
+ * Initialize such a service and this client within an app's primary {@link HoistAuthModel} to use
+ * the tokens it acquires to authenticate with the Hoist server. (Note this requires a suitable
+ * 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 AccessTokenSpec> extends HoistBase {
+    /** Config loaded from UI server + init method. */
+    protected config: C;
+    /** ID Scopes */
+    protected idScopes: string[];
+    /** Specification for Access Tokens **/
+    protected accessSpecs: Record<string, S>;
+    private timer;
+    private lastRefreshAttempt;
+    private TIMER_INTERVAL;
+    private pendingRelogin;
+    private lastRelogin;
+    constructor(config: C);
+    /**
+     * Main entry point for this object.
+     */
+    initAsync(): Promise<void>;
+    /**
+     * Request an interactive login with the underlying OAuth provider.
+     */
+    loginAsync(method?: LoginMethod): Promise<void>;
+    /**
+     * Request a full logout from the underlying OAuth provider.
+     */
+    logoutAsync(): Promise<void>;
+    /**
+     * Get an ID token.
+     */
+    getIdTokenAsync(): Promise<Token>;
+    /**
+     * Get an Access token.
+     */
+    getAccessTokenAsync(key: string): Promise<Token>;
+    /**
+     * Get all configured tokens.
+     */
+    getAllTokensAsync(opts?: {
+        eagerOnly?: boolean;
+        useCache?: boolean;
+    }): Promise<TokenMap>;
+    /**
+     * The last authenticated OAuth username.
+     *
+     * Provided to facilitate more efficient re-login via SSO or otherwise. Cleared on logout.
+     * Note: not necessarily a currently authenticated user, and not necessarily the Hoist username.
+     */
+    getSelectedUsername(): string;
+    /**
+     *  Set the last authenticated OAuth username.
+     *  See `getSelectedUsername()`.
+     */
+    setSelectedUsername(username: string): void;
+    protected abstract doInitAsync(): Promise<TokenMap>;
+    protected abstract doLoginPopupAsync(): Promise<void>;
+    protected abstract doLoginRedirectAsync(): Promise<void>;
+    protected abstract fetchIdTokenAsync(useCache: boolean): Promise<Token>;
+    protected abstract fetchAccessTokenAsync(spec: S, useCache: boolean): Promise<Token>;
+    protected abstract doLogoutAsync(): Promise<void>;
+    protected abstract interactiveLoginNeeded(exception: unknown): boolean;
+    protected get redirectUrl(): string;
+    protected get postLogoutRedirectUrl(): string;
+    protected get loginMethod(): LoginMethod;
+    protected get baseUrl(): string;
+    protected get blankUrl(): string;
+    protected popupBlockerErrorMessage: String;
+    protected defaultErrorMsg: String;
+    /**
+     * Call before redirect flow to snapshot any URL-based routing state that should be restored
+     * after redirect
+     *
+     * @returns key - key for re-accessing this state, to be round-tripped with redirect.
+     */
+    protected captureRedirectState(): string;
+    /**
+     * Call after redirect flow to rehydrate URL-based routing state.
+     *
+     * @param key - key for re-accessing this state, as round-tripped with redirect.
+     */
+    protected restoreRedirectState(key: string): void;
+    /** Call after requesting the provider library redirect the user away for auth. */
+    protected maskAfterRedirectAsync(): Promise<void>;
+    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;
+    private getWithRetry;
+    private rethrowWrapped;
+    private getLoginTask;
+    private onTimerAsync;
+    private logTokensDebug;
+}

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

@@ -0,0 +1,11 @@
+import { PlainObject } from '@xh/hoist/core';
+export declare class Token {
+    readonly value: string;
+    readonly decoded: PlainObject;
+    readonly expiry: number;
+    constructor(value: string);
+    expiresWithin(interval: number): boolean;
+    get formattedExpiry(): string;
+    get forLog(): PlainObject;
+    equals(other: Token): boolean;
+}

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

@@ -0,0 +1,14 @@
+import { Token } from './Token';
+export interface AccessTokenSpec {
+    /**
+     * Mode governing when the access token should be requested from provider:
+     *      - eager (or undefined) - load on overall initialization, but do not block on failure.
+     *        Useful for tokens that an app is almost certain to require during a user session.
+     *      - lazy - defer loading until first requested by client. Useful for tokens that might
+     *        never be needed by the app during a given user session.
+     */
+    fetchMode?: 'eager' | 'lazy';
+    /** Scopes for the desired access token.*/
+    scopes: string[];
+}
+export type TokenMap = Record<string, Token>;

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

@@ -0,0 +1,57 @@
+import type { Auth0ClientOptions } from '@auth0/auth0-spa-js';
+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.  */
+    domain: string;
+    /**
+     * Audience to pass to interactive login and ID token requests.
+     *
+     * If you are also requesting an *access* token for a single audience, pass that value here to
+     * ensure that the initial login/token request returns a ready-to-use access token (and refresh
+     * token) with a single request to the Auth0 API, instead of requiring two.
+     *
+     * This also avoids issues with browsers that block third party cookies when running on
+     * localhost or with an Auth0 domain that does not match the app's own domain. In those cases,
+     * Auth0 must use refresh tokens to obtain access tokens, and a single audience allows that
+     * exchange to work without extra user interaction that this class does not currently support.
+     */
+    audience?: string;
+    /**
+     * Additional options for the Auth0Client ctor. Will be deep merged with defaults, with options
+     * supplied here taking precedence. Use with care, as overriding defaults may have unintended
+     * consequences or fail to work with Hoist's expected usage of the client library.
+     */
+    authZeroClientOptions?: Partial<Auth0ClientOptions>;
+}
+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.
+     */
+    audience: string;
+}
+/**
+ * This class supports OAuth via an integration with Auth0, a commercial service supporting login
+ * via Google, GitHub, Microsoft, and various other OAuth providers *or* via a username/password
+ * combo stored and managed within Auth0's own database. Supported options will depend on the
+ * configuration of your Auth0 app.
+ *
+ * Note: If developing on localhost and using Access Tokens will need to configure your browser to
+ * allow third-party cookies.
+ */
+export declare class AuthZeroClient extends BaseOAuthClient<AuthZeroClientConfig, AuthZeroTokenSpec> {
+    private client;
+    protected doInitAsync(): Promise<TokenMap>;
+    protected doLoginRedirectAsync(): Promise<void>;
+    protected doLoginPopupAsync(): Promise<void>;
+    protected fetchIdTokenAsync(useCache?: boolean): Promise<Token>;
+    protected fetchAccessTokenAsync(spec: AuthZeroTokenSpec, useCache?: boolean): Promise<Token>;
+    protected doLogoutAsync(): Promise<void>;
+    protected interactiveLoginNeeded(exception: unknown): boolean;
+    private createClient;
+    private get loginScope();
+    private returningFromRedirect;
+    private noteUserAuthenticatedAsync;
+}

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

@@ -0,0 +1 @@
+export * from './AuthZeroClient';

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

@@ -0,0 +1,162 @@
+import * as msal from '@azure/msal-browser';
+import { LogLevel } from '@azure/msal-browser';
+import { PlainObject } from '@xh/hoist/core';
+import { Token } from '@xh/hoist/security/Token';
+import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
+import { AccessTokenSpec, TokenMap } from '../Types';
+export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
+    /**
+     * Authority for your organization's tenant: `https://login.microsoftonline.com/[tenantId]`.
+     * MSAL defaults to their "common" tenant (https://login.microsoftonline.com/common") to support
+     * auth with personal MS accounts, but enterprise/Hoist apps will almost certainly use a
+     * specific authority to point to their own private/corporate tenant.
+     */
+    authority: string;
+    /**
+     * A hint about the tenant or domain that the user should use to sign in.
+     * 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 as {@link MsalClientTelemetry}. Default true.
+     */
+    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.
+     *
+     * Use this argument to front-load any necessary auth flow to the apps initialization stage
+     * thereby minimizing disruption to user activity during application use.
+     *
+     * This value may be set to anything up to 86400 (24 hours), the maximum lifetime
+     * of an Azure refresh token.  Set to -1 to disable (default).
+     *
+     * Note that setting to *any* non-disabled amount will require the app to do *some* communication
+     * with the login provider at *every* app load. This may just involve loading new tokens via
+     * fetch, however, setting to higher values will increase the frequency with which
+     * a new refresh token will also need to be requested via a hidden iframe/redirect/popup. This
+     * can be time-consuming and potentially disruptive and applications should therefore use with
+     * care and typically set to some value significantly less than the max.
+     *
+     * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/token-lifetimes.md
+     */
+    initRefreshTokenExpirationOffsetSecs?: number;
+    /**
+     * Enable the use of the MSAL ssoSilent() API, which will attempt to use credentials gained by
+     * another app or tab to start a new session for this app.  Requires iFrames and 3rd party
+     * cookies to be enabled.  Default true.
+     *
+     *  In practice, and according to documentation, this operation is likely to fail for a
+     *  number of reasons, and can often do so as timeout.  Therefore, keeping the timeout limit
+     *  value -- `system.iframeHashTimeout` -- at a relatively low value is critical.  Hoist
+     *  defaults this value to 3000ms vs. the default 10000ms.
+     */
+    enableSsoSilent?: boolean;
+    /** The log level of MSAL. Default is LogLevel.Warning. */
+    msalLogLevel?: LogLevel;
+    /**
+     * Additional options for the MSAL client ctor. Will be deep merged with defaults, with options
+     * supplied here taking precedence. Use with care, as overriding defaults may have unintended
+     * consequences or fail to work with Hoist's expected usage of the client library.
+     */
+    msalClientOptions?: Partial<msal.Configuration>;
+}
+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`
+     * for more info.
+     */
+    loginScopes?: string[];
+    /**
+     * Scopes to be added to the scopes requested during interactive and SSO login.
+     *
+     * See the `extraScopesToConsent` property on  `PopupRequest`, `RedirectRequest`, and
+     * `SSORequest` for more info.
+     */
+    extraScopesToConsent?: string[];
+}
+/**
+ * Service to implement OAuth authentication via MSAL.
+ *
+ * See the following helpful information relevant to our use of this tricky API --
+ * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/
+ * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/token-lifetimes.md
+ * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/login-user.md
+ *
+ * Also see this doc re. use of blankUrl as redirectUri for all "silent" token requests:
+ * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/errors.md#issues-caused-by-the-redirecturi-page
+ *
+ * Important note: The handling of `ssoSilent` and `initRefreshTokenExpirationOffsetSecs` in this
+ *    library require 3rd party cookies to be enabled in the browser so that MSAL can load contact
+ *    in a hidden iFrame.
+ */
+export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec> {
+    private client;
+    private account;
+    private initialTokenLoad;
+    /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
+    telemetry: MsalClientTelemetry;
+    private _telemetryCbHandle;
+    constructor(config: MsalClientConfig);
+    protected doInitAsync(): Promise<TokenMap>;
+    protected doLoginPopupAsync(): Promise<void>;
+    protected doLoginRedirectAsync(): Promise<void>;
+    protected fetchIdTokenAsync(useCache?: boolean): Promise<Token>;
+    protected fetchAccessTokenAsync(spec: MsalTokenSpec, useCache?: boolean): Promise<Token>;
+    protected doLogoutAsync(): Promise<void>;
+    protected interactiveLoginNeeded(exception: unknown): boolean;
+    getFormattedTelemetry(): PlainObject;
+    enableTelemetry(): void;
+    disableTelemetry(): void;
+    private loginSsoAsync;
+    private createClientAsync;
+    private logFromMsal;
+    private get loginScopes();
+    private get loginExtraScopesToConsent();
+    private get refreshOffsetArgs();
+    private setAccount;
+    private noteAuthComplete;
+    private authRequestCore;
+}
+type AuthMethod = 'acquireSilent' | 'ssoSilent' | 'loginPopup' | 'loginRedirect';
+/**
+ * Telemetry produced by this client (if enabled) + included in {@link ClientHealthService}
+ * reporting. Leverages MSAL's opt-in support for emitting performance events.
+ * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/performance.md
+ */
+interface MsalClientTelemetry {
+    /** Method of last authentication for this client. */
+    authMethod: AuthMethod;
+    /** Stats across all events */
+    summary: {
+        successCount: number;
+        failureCount: number;
+        maxDuration: number;
+        lastFailureTime: number;
+    };
+    /** Stats by event type */
+    events: Record<string, MsalEventTelemetry>;
+}
+/** Aggregated telemetry results for a single type of event. */
+interface MsalEventTelemetry {
+    firstTime: number;
+    lastTime: number;
+    successCount: number;
+    failureCount: number;
+    /** Timing info (in ms) for event instances reported with duration. */
+    duration?: {
+        count: number;
+        total: number;
+        average: number;
+        max: number;
+    };
+    lastFailure?: {
+        time: number;
+        duration: number;
+        code: string;
+        name: string;
+    };
+}
+export {};

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

@@ -0,0 +1 @@
+export * from './MsalClient';

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

@@ -0,0 +1,33 @@
+import { IconName } from '@fortawesome/fontawesome-svg-core';
+import { BannerSpec, HoistService, Intent } from '@xh/hoist/core';
+/**
+ * Service to display an app-wide alert banner, as configured via the Hoist Admin console.
+ *
+ * Note that the client is provided with updated banner data from the server via
+ * EnvironmentService, and its regular polling.  See 'xhEnvPollConfig' for more information.
+ */
+export declare class AlertBannerService extends HoistService {
+    xhImpl: boolean;
+    static instance: AlertBannerService;
+    get lastDismissed(): number;
+    updateBanner(spec: AlertBannerSpec): Promise<void>;
+    genBannerSpec(message: string, intent: Intent, iconName: IconName, enableClose: boolean): BannerSpec;
+    private onClose;
+    private isTargetedApp;
+}
+/** @internal */
+export interface AlertBannerSpec {
+    active: boolean;
+    expires: number;
+    publishDate: number;
+    message: string;
+    intent: Intent;
+    iconName: AlertBannerIconName;
+    enableClose: boolean;
+    clientApps: string[];
+    created: number;
+    updated: number;
+    updatedBy: string;
+}
+/** @internal */
+export type AlertBannerIconName = 'bullhorn' | 'check-circle' | 'exclamation-triangle' | 'times-circle' | 'info-circle' | 'question-circle';

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

@@ -0,0 +1,28 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to triggers an app-wide auto-refresh (if enabled, on a configurable interval) via the
+ * application's root RefreshContextModel.
+ *
+ * For this service to be active, it must be configured/enabled in two ways:
+ *
+ *  1) A refresh interval for the client app must be specified via the `xhAutoRefreshIntervals` JSON
+ *     config. Intervals are specified in seconds and keyed by `clientAppCode` to allow for
+ *     different auto-refresh behaviors across different JS apps in the same project.
+ *
+ *  2) The user's `xhAutoRefreshEnabled` preference must be set to true. This is currently a single
+ *     pref. applied to all JS apps in the project. Apps can add an {@link AppOption} to allow users
+ *     to customize via the global options dialog, or set a default pref value if per-user
+ *     customization is not desirable.
+ *
+ * @see RefreshContextModel - the underlying mechanism used to implement the refresh.
+ */
+export declare class AutoRefreshService extends HoistService {
+    xhImpl: boolean;
+    static instance: AutoRefreshService;
+    private timer;
+    private initTime;
+    get enabled(): boolean;
+    get interval(): number;
+    initAsync(): Promise<void>;
+    private onTimerAsync;
+}

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

@@ -0,0 +1,62 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to display an application changelog (aka release notes) to end users, if so configured.
+ *
+ * Changelog entries are maintained in a CHANGELOG.md file within the project root, formatted as
+ * per https://keepachangelog.com. Requires hoist-dev-utils v5.7+ to parse the markdown source
+ * into JSON and make available via the special `@xh/app-changelog.json` import above.
+ *
+ * If a changelog is available, the top-level app menu will include an item to view the log in a
+ * dialog. If a string pref is defined with key `xhLastReadChangelog`, this service will track the
+ * most recent version viewed by the user, and the app will render a "What's new?" button in the
+ * top appBar to alert the user. These app-level UI elements are currently desktop-only, can all be
+ * independently disabled, and only appear when this service is enabled.
+ *
+ * Several additional options can be controlled via soft-config - see below.
+ *
+ * @see XH.showChangelog - public API for displaying the changelog, if enabled and populated.
+ * @see whatsNewButton - utility button that conditionally renders when an unread entry exists for
+ *      the currently deployed app version. Installed by default in desktop appBar.
+ */
+export declare class ChangelogService extends HoistService {
+    xhImpl: boolean;
+    static instance: ChangelogService;
+    readonly SVC_CONFIG_KEY: string;
+    readonly LAST_READ_PREF_KEY: string;
+    /**
+     * The complete changelog object, as produced by the app build or defined
+     * in soft-config, or an empty placeholder if neither source is enabled/available.
+     */
+    changelog: object;
+    /**
+     * Parsed and cleaned versions, if any, with any versions or
+     * nested categories marked for exclusion via config already omitted.
+     */
+    versions: ChangelogVersion[];
+    /**
+     * True if an entry exists for the current app version which the user has
+     * yet to view (and the required user preference has been created).
+     */
+    currentVersionIsUnread: boolean;
+    get enabled(): boolean;
+    get latestAvailableVersion(): string;
+    get latestNonEmptyVersion(): string;
+    constructor();
+    initAsync(): Promise<void>;
+    markLatestAsRead(): void;
+    private get config();
+    private parseVersions;
+    private includeVersion;
+    private includeCategory;
+    private updateUnreadStatus;
+}
+export interface ChangelogVersion {
+    version: string;
+    title: string;
+    isCurrentVersion: boolean;
+    categories: ChangelogCategory[];
+}
+export interface ChangelogCategory {
+    title: string;
+    items: string[];
+}

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

@@ -0,0 +1,64 @@
+import { HoistService, PageState, PlainObject } from '@xh/hoist/core';
+import { WebSocketTelemetry } from '@xh/hoist/svc/WebSocketService';
+/**
+ * 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 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>;
+    get enabled(): boolean;
+    /** @returns a customizable report with metrics capturing client app/session state. */
+    getReport(): ClientHealthReport;
+    /** @returns a report, formatted for easier viewing in console. **/
+    getFormattedReport(): PlainObject;
+    /**
+     * 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 sendReportInternal;
+}
+export interface GeneralData {
+    startTime: number;
+    durationMins: number;
+    idleMins: number;
+    pageState: PageState;
+}
+export interface ConnectionData {
+    downlink: number;
+    effectiveType: string;
+    rtt: number;
+}
+export interface MemoryData {
+    modelCount: number;
+    usedPctLimit?: number;
+    jsHeapSizeLimit?: number;
+    totalJSHeapSize?: number;
+    usedJSHeapSize?: number;
+}
+export interface ClientHealthReport {
+    general: GeneralData;
+    connection: ConnectionData;
+    memory: MemoryData;
+    webSockets: WebSocketTelemetry;
+}

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

@@ -0,0 +1,36 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to read soft-configuration values.
+ *
+ * Server-side configuration support is provided by hoist-core. AppConfigs must be predefined on the
+ * server (they can be managed by the Admin console) and are referenced by their string key. These
+ * entries can then be changed on the fly or given per-environment values that allow the app to
+ * adjust without requiring a code change or redeployment.
+ *
+ * Note that for a config to be available here on the client, it must have its `clientVisible` flag
+ * set to true. This is to provide support for configurations that should *not* be sent down for
+ * possible inspection by end users.
+ *
+ * Note that this service does *not* currently attempt to reload or update configs once the client
+ * application has loaded. A refresh of the application is required to load new entries.
+ */
+export declare class ConfigService extends HoistService {
+    static instance: ConfigService;
+    private _data;
+    initAsync(): Promise<void>;
+    /**
+     * Get the list of available keys.
+     */
+    get list(): string[];
+    /**
+     * Get the configured value for a given key. Typically accessed via `XH.getConf()` alias.
+     *
+     * @param key - identifier of the config to return.
+     * @param defaultValue - value to return if the configuration key is not found - i.e. the
+     *      config has not been created on the server - instead of throwing. Use sparingly! In
+     *      general, it's better to not provide defaults here, but instead keep entries up-to-date
+     *      via the Admin client and have it be obvious when one is missing.
+     * @returns the soft-configured value.
+     */
+    get(key: string, defaultValue?: any): any;
+}