@genesislcap/foundation-utils 15.50.3-holiday-picker.1 → 15.51.0

package/dist/custom-elements.json

@@ -71,6 +71,14 @@
             "package": "./error"
           }
         },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./error-monitoring"
+          }
+        },
         {
           "kind": "js",
           "name": "*",
@@ -650,6 +658,59 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./renderOnChange"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/renderOnChange.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "renderOnChange",
+          "parameters": [
+            {
+              "name": "target",
+              "type": {
+                "text": "FASTElement & { render(): void }"
+              },
+              "description": "The target to define the property change handler on."
+            },
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "description": "The property name."
+            }
+          ],
+          "description": "Defines a property changed handler that calls a render() method on the target as an internal observation enhancement.",
+          "privacy": "public"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "renderOnChange",
+          "declaration": {
+            "name": "renderOnChange",
+            "module": "src/decorators/renderOnChange.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/directives/index.ts",
@@ -1187,59 +1248,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/decorators/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "*",
-          "declaration": {
-            "name": "*",
-            "package": "./renderOnChange"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/decorators/renderOnChange.ts",
-      "declarations": [
-        {
-          "kind": "function",
-          "name": "renderOnChange",
-          "parameters": [
-            {
-              "name": "target",
-              "type": {
-                "text": "FASTElement & { render(): void }"
-              },
-              "description": "The target to define the property change handler on."
-            },
-            {
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "description": "The property name."
-            }
-          ],
-          "description": "Defines a property changed handler that calls a render() method on the target as an internal observation enhancement.",
-          "privacy": "public"
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "renderOnChange",
-          "declaration": {
-            "name": "renderOnChange",
-            "module": "src/decorators/renderOnChange.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/error/errorMap.ts",
@@ -1439,6 +1447,130 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/error-monitoring/error-monitoring.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "createErrorMonitoringReporter",
+          "return": {
+            "type": {
+              "text": "ConsolaReporter"
+            }
+          },
+          "parameters": [
+            {
+              "name": "client",
+              "type": {
+                "text": "ErrorMonitoringClient"
+              },
+              "description": "The monitoring client."
+            },
+            {
+              "name": "{ breadcrumbs = true }",
+              "default": "{}",
+              "type": {
+                "text": "Pick<ErrorMonitoringOptions, 'breadcrumbs'>"
+              }
+            },
+            {
+              "description": "Set `breadcrumbs: false` to skip breadcrumbs.",
+              "name": "options"
+            }
+          ],
+          "description": "Creates a global log reporter that sends foundation logger output to a monitoring client.",
+          "privacy": "public"
+        },
+        {
+          "kind": "function",
+          "name": "isFoundationLoggerConsoleBreadcrumb",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "breadcrumb",
+              "type": {
+                "text": "ErrorMonitoringBreadcrumb"
+              }
+            }
+          ],
+          "description": "True for a console breadcrumb written by a foundation logger.",
+          "privacy": "public"
+        },
+        {
+          "kind": "function",
+          "name": "setupErrorMonitoring",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "client",
+              "type": {
+                "text": "ErrorMonitoringClient"
+              },
+              "description": "The monitoring SDK (for example the Sentry namespace) or an adapter for one."
+            },
+            {
+              "name": "options",
+              "type": {
+                "text": "ErrorMonitoringOptions"
+              },
+              "description": "The DSN, the environment, and extra init options."
+            }
+          ],
+          "description": "Sets up error monitoring for a Genesis app in one call.",
+          "privacy": "public"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "createErrorMonitoringReporter",
+          "declaration": {
+            "name": "createErrorMonitoringReporter",
+            "module": "src/error-monitoring/error-monitoring.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isFoundationLoggerConsoleBreadcrumb",
+          "declaration": {
+            "name": "isFoundationLoggerConsoleBreadcrumb",
+            "module": "src/error-monitoring/error-monitoring.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "setupErrorMonitoring",
+          "declaration": {
+            "name": "setupErrorMonitoring",
+            "module": "src/error-monitoring/error-monitoring.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/error-monitoring/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./error-monitoring"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/feature-flags/featureFlags.ts",

package/dist/dts/error-monitoring/error-monitoring.d.ts

@@ -0,0 +1,177 @@
+import type { ConsolaReporter } from '@genesislcap/foundation-logger';
+/**
+ * Severity of a monitoring event or breadcrumb.
+ * @public
+ */
+export type ErrorMonitoringLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+/**
+ * Context sent with a captured exception or message.
+ * @public
+ */
+export interface ErrorMonitoringContext {
+    level?: ErrorMonitoringLevel;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+/**
+ * A breadcrumb: a record of something that happened before an event.
+ * @public
+ */
+export 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 type ErrorMonitoringBreadcrumbHint = Record<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 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;
+}
+/**
+ * Extra options for the client's `init`, merged into what {@link setupErrorMonitoring} passes.
+ * @public
+ */
+export 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;
+}
+/**
+ * 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 interface ErrorMonitoringClient {
+    captureException(error: unknown, context?: ErrorMonitoringContext): unknown;
+    captureMessage(message: string, context?: ErrorMonitoringContext): unknown;
+    addBreadcrumb?(breadcrumb: ErrorMonitoringBreadcrumb & {
+        level?: ErrorMonitoringLevel;
+    }): unknown;
+    init?(options: ErrorMonitoringInitOptions): unknown;
+}
+/**
+ * Picks the monitoring environment from the page's location, or returns `undefined` to leave
+ * monitoring off.
+ * @public
+ */
+export type ErrorMonitoringEnvironmentResolver = (location: Location) => string | undefined;
+/**
+ * Options for {@link setupErrorMonitoring}.
+ * @public
+ */
+export 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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>;
+//# sourceMappingURL=error-monitoring.d.ts.map

package/dist/dts/error-monitoring/error-monitoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-monitoring.d.ts","sourceRoot":"","sources":["../../../src/error-monitoring/error-monitoring.ts"],"names":[],"mappings":"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"}

package/dist/dts/error-monitoring/index.d.ts

@@ -0,0 +1,2 @@
+export * from './error-monitoring';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/error-monitoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/error-monitoring/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/dts/index.d.ts

@@ -6,6 +6,7 @@ export * from './directives';
 export * from './encoding';
 export * from './env';
 export * from './error';
+export * from './error-monitoring';
 export * from './feature-flags';
 export * from './formatters';
 export * from './logger';

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}