@genesislcap/foundation-utils 15.50.3 → 15.51.0

package/dist/foundation-utils.d.ts

@@ -2,6 +2,7 @@ import { BehaviorSubject } from 'rxjs';
 import { Binding } from '@microsoft/fast-element';
 import { CaptureType } from '@microsoft/fast-element';
 import { ComposableStyles } from '@microsoft/fast-element';
+import type { ConsolaReporter } from '@genesislcap/foundation-logger';
 import { Constructable } from '@microsoft/fast-element';
 import { Controller } from '@microsoft/fast-element';
 import { CSSDesignToken } from '@microsoft/fast-foundation';
@@ -153,6 +154,32 @@ export declare type ConversionType = 'string' | 'number' | 'time' | 'boolean';
  */
 export declare const createErrorMap: <TErrorDetailMap extends ErrorDetailMap>(logger: ErrorMapLogger) => ErrorMap<TErrorDetailMap>;
 
+/**
+ * Creates a global log reporter that sends foundation logger output to a monitoring client.
+ *
+ * @remarks
+ * No logged data is sent: a report carries only the logger name, the level, the log's message (its
+ * first argument, when that is a string) and, for errors, the exception. Objects and any further
+ * arguments are left out, so credentials, personal or business data passed to a logger never
+ * reach the monitoring service. `error` and `fatal` logs become events: an exception when an
+ * `Error` was logged, with the message as `extra.message`, otherwise a message event. A logged
+ * `Error` with its own fields or a cause is sent as a copy that keeps only its name, message, stack
+ * and `Error` cause. Other logs become breadcrumbs unless `breadcrumbs` is `false`. A failing client
+ * never breaks logging.
+ *
+ * This covers only what the reporter sends. SDKs that record console calls, such as the Sentry
+ * browser SDKs by default, also record foundation logger output as console breadcrumbs with the
+ * logged arguments as data. When wiring a client by hand, drop those in the SDK's
+ * `beforeBreadcrumb` with {@link isFoundationLoggerConsoleBreadcrumb}.
+ *
+ * {@link setupErrorMonitoring} does both for you; use this directly to wire a client by hand.
+ *
+ * @param client - The monitoring client.
+ * @param options - Set `breadcrumbs: false` to skip breadcrumbs.
+ * @public
+ */
+export declare const createErrorMonitoringReporter: (client: ErrorMonitoringClient, { breadcrumbs }?: Pick<ErrorMonitoringOptions, "breadcrumbs">) => ConsolaReporter;
+
 /**
  * Creates a logger with the given name and options.
  * @param name - The name to give the logger.
@@ -561,6 +588,107 @@ export declare interface ErrorMap<TErrorDetailMap extends ErrorDetailMap> extend
  */
 export declare type ErrorMapLogger = (...args: any[]) => void;
 
+/**
+ * A breadcrumb: a record of something that happened before an event.
+ * @public
+ */
+export declare interface ErrorMonitoringBreadcrumb {
+    category?: string;
+    level?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Extra information an SDK passes with a breadcrumb, such as the DOM event or the console arguments.
+ * @public
+ */
+export declare type ErrorMonitoringBreadcrumbHint = Record<string, unknown>;
+
+/**
+ * An error-monitoring SDK, or an adapter for one. The method names and shapes match the Sentry
+ * browser SDKs, so `import * as Sentry from '@sentry/react'` can be passed as is.
+ * @public
+ */
+export declare interface ErrorMonitoringClient {
+    captureException(error: unknown, context?: ErrorMonitoringContext): unknown;
+    captureMessage(message: string, context?: ErrorMonitoringContext): unknown;
+    addBreadcrumb?(breadcrumb: ErrorMonitoringBreadcrumb & {
+        level?: ErrorMonitoringLevel;
+    }): unknown;
+    init?(options: ErrorMonitoringInitOptions): unknown;
+}
+
+/**
+ * Context sent with a captured exception or message.
+ * @public
+ */
+export declare interface ErrorMonitoringContext {
+    level?: ErrorMonitoringLevel;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+
+/**
+ * Picks the monitoring environment from the page's location, or returns `undefined` to leave
+ * monitoring off.
+ * @public
+ */
+export declare type ErrorMonitoringEnvironmentResolver = (location: Location) => string | undefined;
+
+/**
+ * Extra options for the client's `init`, merged into what {@link setupErrorMonitoring} passes.
+ * @public
+ */
+export declare interface ErrorMonitoringExtraInitOptions {
+    /** Runs after the built-in filter, for breadcrumbs it keeps, with the SDK's hint. */
+    beforeBreadcrumb?: (breadcrumb: ErrorMonitoringBreadcrumb, hint?: ErrorMonitoringBreadcrumbHint) => ErrorMonitoringBreadcrumb | null;
+    [key: string]: unknown;
+}
+
+/**
+ * Options {@link setupErrorMonitoring} passes to the client's `init`.
+ *
+ * @remarks
+ * The names match Sentry's `init` options. Any other keys from `initOptions` are passed through.
+ * @public
+ */
+export declare interface ErrorMonitoringInitOptions {
+    dsn: string;
+    environment: string;
+    /** Drops the console breadcrumbs foundation loggers write; see {@link isFoundationLoggerConsoleBreadcrumb}. */
+    beforeBreadcrumb?: <B extends ErrorMonitoringBreadcrumb>(breadcrumb: B, hint?: ErrorMonitoringBreadcrumbHint) => B | null;
+    [key: string]: unknown;
+}
+
+/**
+ * Severity of a monitoring event or breadcrumb.
+ * @public
+ */
+export declare type ErrorMonitoringLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+
+/**
+ * Options for {@link setupErrorMonitoring}.
+ * @public
+ */
+export declare interface ErrorMonitoringOptions {
+    /** The DSN events are sent to. Without one, monitoring stays off. */
+    dsn: string | undefined;
+    /**
+     * The environment events are tagged with, or a function that picks it from the page's location.
+     * Defaults to the page's hostname, and leaves monitoring off on local hosts: `localhost`,
+     * `*.localhost`, `*.local`, `0.0.0.0`, `host.docker.internal`, and loopback, private, link-local
+     * and shared (`100.64.0.0/10`, as Tailscale uses) IP addresses, IPv4-mapped IPv6 included.
+     */
+    environment?: string | ErrorMonitoringEnvironmentResolver;
+    /** Extra options merged into what the client's `init` receives, e.g. Sentry's `dataCollection`. */
+    initOptions?: ErrorMonitoringExtraInitOptions;
+    /** Initialises the client in place of calling `client.init`. */
+    init?: (options: ErrorMonitoringInitOptions) => unknown;
+    /** Records non-error foundation logs as breadcrumbs. Defaults to `true`. */
+    breadcrumbs?: boolean;
+}
+
 declare type EventListener_2<T = any> = (data: T) => void;
 
 /**
@@ -932,6 +1060,19 @@ export declare const isFeatureActivated: (feature: string) => boolean;
  */
 export declare const isFeatureActivatedInSearch: (search: string, feature: string) => boolean;
 
+/**
+ * True for a console breadcrumb written by a foundation logger.
+ *
+ * @remarks
+ * consola's browser output starts with a `%c` badge (after a timestamp, when timestamps are on)
+ * styled as a pill, and SDKs that record console calls join the arguments with `String()`, so these
+ * breadcrumbs arrive as CSS and `[object Object]`, and they carry the logged arguments as data. The
+ * reporter from {@link createErrorMonitoringReporter} records the same logs' messages without the
+ * data. Other `%c`-styled console output doesn't match.
+ * @public
+ */
+export declare const isFoundationLoggerConsoleBreadcrumb: (breadcrumb: ErrorMonitoringBreadcrumb) => boolean;
+
 /**
  * JSON replacer function.
  * @param key - The object key.
@@ -2333,6 +2474,53 @@ export declare type SetActivatedFeaturesOptions = {
     reload?: boolean;
 };
 
+/**
+ * Sets up error monitoring for a Genesis app in one call.
+ *
+ * @remarks
+ * Without a DSN, or when no environment applies (by default on local hosts such as `localhost` or
+ * a private IP address), it does nothing and resolves `false`. The environment defaults to the
+ * page's hostname, so one image promoted across environments reports each under its own name; pass
+ * a function to map hostnames to names such as `uat`. Otherwise it:
+ *
+ * - initialises the client (`client.init`, or `options.init`) with the DSN, environment, a
+ *   `beforeBreadcrumb` that drops the SDK's console breadcrumbs for foundation logger output (they
+ *   carry the logged arguments), and any `initOptions`;
+ * - registers a global log reporter ({@link createErrorMonitoringReporter}), so errors logged by
+ *   every foundation logger, including those Genesis packages create at import time, are reported,
+ *   and other logs become breadcrumbs. Only log messages and exceptions are sent, never logged data.
+ *
+ * Logs written while an asynchronous `init` runs (the last 100) are reported once it finishes. If
+ * `init` throws or rejects, for example when a lazily loaded SDK fails to download, it warns on the
+ * console and resolves `false` rather than rejecting.
+ *
+ * Errors caught by the foundation-react-utils `AppErrorBoundary` and `TileErrorBoundary` are logged
+ * with their reference ID and component stack in the message, so they are reported too without an
+ * `onError`.
+ * Pair them with `onCaughtError` on the React root.
+ *
+ * Calling it again replaces the previous reporter, or removes it if the new call has no DSN or
+ * environment. When calls overlap, only the last one takes effect, and the earlier ones resolve
+ * `false`.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from '@sentry/react';
+ * import { setupErrorMonitoring } from '@genesislcap/foundation-utils';
+ *
+ * setupErrorMonitoring(Sentry, {
+ *   dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
+ *   environment: ({ hostname }) => ({ 'app-uat.example.com': 'uat', 'app.example.com': 'prod' })[hostname],
+ * });
+ * ```
+ *
+ * @param client - The monitoring SDK (for example the Sentry namespace) or an adapter for one.
+ * @param options - The DSN, the environment, and extra init options.
+ * @returns Whether this call enabled monitoring.
+ * @public
+ */
+export declare function setupErrorMonitoring(client: ErrorMonitoringClient, options: ErrorMonitoringOptions): Promise<boolean>;
+
 export declare const SHORTCUT_BLOCKED_DEFAULT_MESSAGE = "This shortcut is currently unavailable in this context.";
 
 export declare const SHORTCUT_BLOCKED_DEFAULT_TITLE = "Shortcut blocked";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-utils",
   "description": "Genesis Foundation Utils",
-  "version": "15.50.3",
+  "version": "15.51.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -29,17 +29,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.50.3",
-    "@genesislcap/genx": "15.50.3",
-    "@genesislcap/ts-builder": "15.50.3",
-    "@genesislcap/uvu-playwright-builder": "15.50.3",
-    "@genesislcap/vite-builder": "15.50.3",
-    "@genesislcap/webpack-builder": "15.50.3",
+    "@genesislcap/foundation-testing": "15.51.0",
+    "@genesislcap/genx": "15.51.0",
+    "@genesislcap/ts-builder": "15.51.0",
+    "@genesislcap/uvu-playwright-builder": "15.51.0",
+    "@genesislcap/vite-builder": "15.51.0",
+    "@genesislcap/webpack-builder": "15.51.0",
     "@types/json-schema": "^7.0.11"
   },
   "dependencies": {
-    "@genesislcap/expression-builder": "15.50.3",
-    "@genesislcap/foundation-logger": "15.50.3",
+    "@genesislcap/expression-builder": "15.51.0",
+    "@genesislcap/foundation-logger": "15.51.0",
     "@microsoft/fast-components": "2.30.6",
     "@microsoft/fast-element": "1.14.0",
     "@microsoft/fast-foundation": "2.50.0",