@steve31415/baselib 3.23.0 → 3.25.0

package/dist/log-browser.d.ts

@@ -10,6 +10,38 @@ export interface BrowserLoggerOptions {
     /** Also mirror events to the devtools console (default false). */
     console?: boolean;
 }
+/** One random id per page load, stamped on every browser event as
+ *  `page_id`. Exported so an app can send the same id to its server (e.g. a
+ *  socket's client id) and join the two sides in one query. */
+export declare const pageId: string;
+/**
+ * A coarse `<os>-<browser>` label from a user-agent string — enough to tell
+ * Steve's devices apart in a query, deliberately nothing finer (no versions,
+ * no model). os: android | ios | mac | windows | chromeos | linux | other;
+ * browser: edge | opera | firefox | chrome | safari | other. An iPad asking for
+ * the desktop site reports itself as a Mac; pass `touchPoints`
+ * (`navigator.maxTouchPoints`) to tell it apart.
+ */
+export declare function deviceLabel(userAgent: string, touchPoints?: number): string;
 export declare function createBrowserLogger(opts?: BrowserLoggerOptions): Logger;
-/** Route uncaught errors and unhandled rejections into the logger. */
+/**
+ * Make the shared `logger` forward to `instance`. Call once at boot, right
+ * after createBrowserLogger; tests install a recorder.
+ */
+export declare function installBrowserLogger(instance: Logger | null): void;
+/**
+ * The page's logger, importable from any module — no threading a Logger
+ * through props and constructors. It forwards to the instance given to
+ * installBrowserLogger; before that (or in a test that installs none)
+ * events go to the devtools console rather than being lost.
+ */
+export declare const logger: Logger;
+/**
+ * Route uncaught errors, unhandled rejections, and failed resource loads
+ * (`<img>`, `<script>`, `<link>`, media) into the logger. A resource load
+ * failure fires a non-bubbling `error` on its element, which only a
+ * capturing window listener sees; it logs WARN while the browser reports
+ * itself online and INFO while offline (expected then), once per URL per
+ * page so a re-rendering broken element cannot flood the dataset.
+ */
 export declare function installGlobalErrorHandlers(logger: Logger): void;

package/dist/log-browser.js

@@ -10,8 +10,61 @@
 //
 // The token is ingest-only and dataset-scoped by design — visible to any
 // signed-in user, able to do nothing but add log events.
+//
+// Every event also carries two top-level fields saying where it came from,
+// because browser events have no request to join on (2026-10-03, radar: telling
+// a phone put down from a sleeping Mac from a server fault took the
+// load-balancer log): `page_id`, one random id per page load, and `device`, a
+// coarse `<os>-<browser>` label such as `mac-chrome` or `android-chrome`.
 import { LogShipper, makeEvents } from './log-core.js';
 export { serializeError } from './log-core.js';
+/** One random id per page load, stamped on every browser event as
+ *  `page_id`. Exported so an app can send the same id to its server (e.g. a
+ *  socket's client id) and join the two sides in one query. */
+export const pageId = newPageId();
+function newPageId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+/**
+ * A coarse `<os>-<browser>` label from a user-agent string — enough to tell
+ * Steve's devices apart in a query, deliberately nothing finer (no versions,
+ * no model). os: android | ios | mac | windows | chromeos | linux | other;
+ * browser: edge | opera | firefox | chrome | safari | other. An iPad asking for
+ * the desktop site reports itself as a Mac; pass `touchPoints`
+ * (`navigator.maxTouchPoints`) to tell it apart.
+ */
+export function deviceLabel(userAgent, touchPoints = 0) {
+    const ua = userAgent;
+    const os = /Android/.test(ua)
+        ? 'android'
+        : /iPhone|iPad|iPod/.test(ua)
+            ? 'ios'
+            : /Macintosh|Mac OS X/.test(ua)
+                ? touchPoints > 1
+                    ? 'ios'
+                    : 'mac'
+                : /Windows/.test(ua)
+                    ? 'windows'
+                    : /CrOS/.test(ua)
+                        ? 'chromeos'
+                        : /Linux/.test(ua)
+                            ? 'linux'
+                            : 'other';
+    const browser = /Edg(e|A|iOS)?\//.test(ua)
+        ? 'edge'
+        : /OPR\/|OPiOS\//.test(ua)
+            ? 'opera'
+            : /Firefox\/|FxiOS\//.test(ua)
+                ? 'firefox'
+                : /Chrome\/|CriOS\//.test(ua)
+                    ? 'chrome'
+                    : /Safari\//.test(ua)
+                        ? 'safari'
+                        : 'other';
+    return `${os}-${browser}`;
+}
 function metaContent(name) {
     return document.querySelector(`meta[name="${name}"]`)?.content || undefined;
 }
@@ -68,7 +121,12 @@ export function createBrowserLogger(opts = {}) {
             flush: () => shipper?.flush() ?? Promise.resolve(),
         };
     }
-    const logger = build({ ...(buildId ? { build_id: buildId } : {}), ...opts.context });
+    const logger = build({
+        ...(buildId ? { build_id: buildId } : {}),
+        page_id: pageId,
+        device: deviceLabel(navigator.userAgent, navigator.maxTouchPoints ?? 0),
+        ...opts.context,
+    });
     // Ship what's pending whenever the page may be going away.
     const flushNow = () => void logger.flush();
     addEventListener('pagehide', flushNow);
@@ -79,11 +137,75 @@ export function createBrowserLogger(opts = {}) {
     });
     return logger;
 }
-/** Route uncaught errors and unhandled rejections into the logger. */
+let installed = null;
+/**
+ * Make the shared `logger` forward to `instance`. Call once at boot, right
+ * after createBrowserLogger; tests install a recorder.
+ */
+export function installBrowserLogger(instance) {
+    installed = instance;
+}
+const CONSOLE_METHOD = { debug: 'debug', info: 'log', warn: 'warn', error: 'error' };
+function forwardingLogger(context) {
+    const emit = (level, message, meta) => {
+        // Resolved per call, so a module-scope `logger.with(...)` taken before
+        // boot still ships once the app installs its logger.
+        if (installed)
+            (context ? installed.with(context) : installed)[level](message, meta);
+        else
+            console[CONSOLE_METHOD[level]](message, meta ?? '');
+    };
+    return {
+        debug: (m, meta) => emit('debug', m, meta),
+        info: (m, meta) => emit('info', m, meta),
+        warn: (m, meta) => emit('warn', m, meta),
+        error: (m, meta) => emit('error', m, meta),
+        with: (extra) => forwardingLogger({ ...context, ...extra }),
+        flush: () => installed?.flush() ?? Promise.resolve(),
+    };
+}
+/**
+ * The page's logger, importable from any module — no threading a Logger
+ * through props and constructors. It forwards to the instance given to
+ * installBrowserLogger; before that (or in a test that installs none)
+ * events go to the devtools console rather than being lost.
+ */
+export const logger = forwardingLogger(undefined);
+const MAX_RESOURCE_URL = 500;
+function resourceUrl(target) {
+    // The resolved (absolute) URL, as the browser requested it.
+    const element = target;
+    const url = element.currentSrc || element.src || element.href || '';
+    return url.length > MAX_RESOURCE_URL ? `${url.slice(0, MAX_RESOURCE_URL)}…` : url;
+}
+/**
+ * Route uncaught errors, unhandled rejections, and failed resource loads
+ * (`<img>`, `<script>`, `<link>`, media) into the logger. A resource load
+ * failure fires a non-bubbling `error` on its element, which only a
+ * capturing window listener sees; it logs WARN while the browser reports
+ * itself online and INFO while offline (expected then), once per URL per
+ * page so a re-rendering broken element cannot flood the dataset.
+ */
 export function installGlobalErrorHandlers(logger) {
+    const failedResources = new Set();
     addEventListener('error', (e) => {
-        logger.error('uncaught error', { error: e.error ?? e.message });
-    });
+        const target = e.target;
+        if (typeof Element !== 'undefined' && target instanceof Element) {
+            const url = resourceUrl(target);
+            if (failedResources.has(url))
+                return;
+            failedResources.add(url);
+            const online = navigator.onLine !== false;
+            logger[online ? 'warn' : 'info']('resource failed to load', {
+                element: target.tagName.toLowerCase(),
+                url,
+                online,
+            });
+            return;
+        }
+        const event = e;
+        logger.error('uncaught error', { error: event.error ?? event.message });
+    }, true);
     addEventListener('unhandledrejection', (e) => {
         logger.error('unhandled rejection', { error: e.reason });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.23.0",
+  "version": "3.25.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",