@columenlabs/lumen-ui 0.1.80 → 0.1.81

package/dist/api-fetch.js

@@ -2,10 +2,12 @@
  * One JSON fetch for the assistant, workspaces and joins. A failure throws `ApiError` with the
  * method, address, status and the server's `error` and `code`, so a caller shows what failed and
  * Workers Logs keep it: a server fault (5xx) or a network failure is reported to
- * `/api/client-error` with `where` naming the caller. A 4xx is the server saying why it refused,
+ * `/api/client-error` with `where` naming the caller. Every failure is also a `fetch_fail`
+ * telemetry point (its route with ids folded, status and request id) once `useLumenTelemetry` runs. A 4xx is the server saying why it refused,
  * shown to the person and not logged as a fault.
  */
 import { reportError } from './route-error.js';
+import { apiRoute, reportFailedFetch } from './telemetry.js';
 export class ApiError extends Error {
     method;
     url;
@@ -39,6 +41,7 @@ export async function apiJson(url, init = {}, where = 'api') {
             throw err;
         const e = new ApiError(`Couldn't reach the server (${method} ${url})`, method, url, 0);
         reportError(e, 'shown', where);
+        reportFailedFetch(apiRoute(url), 0);
         throw e;
     }
     const text = await res.text();
@@ -54,6 +57,7 @@ export async function apiJson(url, init = {}, where = 'api') {
         const e = new ApiError(b.error ?? `${method} ${url} answered ${res.status}`, method, url, res.status, b.code);
         if (res.status >= 500)
             reportError(e, 'shown', where);
+        reportFailedFetch(apiRoute(url), res.status, res.headers.get('x-request-id'));
         throw e;
     }
     return body;

package/dist/index.d.ts

@@ -52,6 +52,7 @@ export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, type KeyTestRe
 export { LumenExpandList, LumenExpandRow } from './expand-list.js';
 export { LumenPager } from './pager.js';
 export { createDeskQueryClient } from './query-client.js';
+export { type ClientPoint, type ClientPointKind, type LumenTelemetryOptions, apiRoute, reportClient, reportClientError, reportFailedFetch, stackFingerprint, useLumenTelemetry, } from './telemetry.js';
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { type LumenLoad, LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';

package/dist/index.js

@@ -59,6 +59,7 @@ export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, TestBadge, err
 export { LumenExpandList, LumenExpandRow } from './expand-list.js';
 export { LumenPager } from './pager.js';
 export { createDeskQueryClient } from './query-client.js';
+export { apiRoute, reportClient, reportClientError, reportFailedFetch, stackFingerprint, useLumenTelemetry, } from './telemetry.js';
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';

package/dist/route-error.js

@@ -16,6 +16,7 @@ import { useRouter } from '@tanstack/react-router';
 import { ChevronRight, RefreshCw, RotateCcw, TriangleAlert } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { toast } from 'sonner';
+import { reportClientError } from './telemetry.js';
 import { Button } from './ui/button.js';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from './ui/collapsible.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from './ui/empty.js';
@@ -166,6 +167,7 @@ export function reportError(error, outcome, where) {
     if (Date.now() - (sent.get(key) ?? 0) < GAP_MS)
         return;
     sent.set(key, Date.now());
+    reportClientError(err);
     const body = JSON.stringify({
         message: err.message.slice(0, 500),
         stack: (err.stack ?? '').slice(0, 2000),

package/dist/telemetry.d.ts

@@ -0,0 +1,40 @@
+export type ClientPointKind = 'view' | 'error' | 'fetch_fail' | 'vital';
+export interface ClientPoint {
+    kind: ClientPointKind;
+    /** The screen's route template (`/connections/$id`), never the address with its ids. */
+    route: string;
+    /** An error's class, an API route, or a vital's name (LCP, INP, CLS). */
+    name?: string;
+    /** A hash of the error's stack frames. */
+    fingerprint?: string;
+    /** The `X-Request-Id` of the failed answer, to find its server side. */
+    requestId?: string;
+    /** ms, or a vital's score. */
+    value?: number;
+    status?: number;
+    device?: 'phone' | 'desktop';
+}
+/** The stack's frames only (a message can carry anything), with each file's query dropped. */
+export declare function stackFingerprint(error: unknown): string;
+/** An API address as a route: no host or query, and id-like segments as `:id`. */
+export declare function apiRoute(url: string): string;
+/** Queues one point (nothing is kept until `useLumenTelemetry` has named the app); the batch goes out every 15 s, at 50 points, or when the tab is hidden. */
+export declare function reportClient(p: Omit<ClientPoint, 'device' | 'route'> & {
+    route?: string;
+}): void;
+/** A request that failed: its API route template, status (0 when it never answered) and id. */
+export declare function reportFailedFetch(apiRoute: string, status: number, requestId?: string | null): void;
+/** An error the page caught or didn't: its class and stack hash only. */
+export declare function reportClientError(error: unknown): void;
+export interface LumenTelemetryOptions {
+    /** The app's name in the points (`console`, `admin`). */
+    app: string;
+    /** The current screen's route template, from the app's router. */
+    route: string;
+    /** The build or deploy the page runs. */
+    version?: string;
+    /** Where batches go; `/api/t` by default. */
+    endpoint?: string;
+}
+/** Mount once at the app's root: every screen change is a view, and errors and vitals follow. */
+export declare function useLumenTelemetry(opts: LumenTelemetryOptions): void;

package/dist/telemetry.js

@@ -0,0 +1,135 @@
+/**
+ * The app's own telemetry from the browser: screens opened, uncaught errors, failed requests and
+ * Web Vitals, sent in batches to the app's Worker (by default `POST /api/t`), which checks each
+ * point and writes it with `meterClientBatch` from `@columenlabs/lumen-ops/client`.
+ *
+ * It is first party and keeps nothing in the browser: no cookie, no storage, no third party. A
+ * point holds a route template, an error's class and a hash of its stack, a status and a number.
+ * Never an error's message, a URL's query, page text or anything typed.
+ */
+import { useEffect } from 'react';
+import { onCLS, onINP, onLCP } from 'web-vitals';
+const MAX_BATCH = 50;
+const FLUSH_MS = 15_000;
+const CODE = /^[A-Za-z0-9_.:/$-]{1,64}$/;
+let endpoint = '/api/t';
+let app = '';
+let version = '';
+let route = '';
+const queue = [];
+let started = false;
+const fnv = (s) => {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++)
+        h = Math.imul(h ^ s.charCodeAt(i), 16777619) >>> 0;
+    return h.toString(16).padStart(8, '0');
+};
+/** The stack's frames only (a message can carry anything), with each file's query dropped. */
+export function stackFingerprint(error) {
+    const stack = error instanceof Error ? (error.stack ?? '') : '';
+    const frames = stack
+        .split('\n')
+        .filter((l) => /^\s*at\s|@/.test(l))
+        .slice(0, 8)
+        .map((l) => l.replace(/\?[^:)\s]*/g, '').trim());
+    return fnv(frames.join('\n'));
+}
+const device = () => typeof window !== 'undefined' && window.matchMedia?.('(max-width: 767px)').matches
+    ? 'phone'
+    : 'desktop';
+const code = (s) => (s && CODE.test(s) ? s : undefined);
+/** An API address as a route: no host or query, and id-like segments as `:id`. */
+export function apiRoute(url) {
+    let path = url;
+    try {
+        path = new URL(url, 'http://x').pathname;
+    }
+    catch { }
+    return path
+        .split('/')
+        .map((seg) => /^[a-z]{1,4}_[A-Za-z0-9]+$/.test(seg) ||
+        seg.length >= 20 ||
+        (seg.length >= 8 && /\d/.test(seg)) ||
+        /[^A-Za-z0-9_.-]/.test(seg)
+        ? ':id'
+        : seg)
+        .join('/')
+        .slice(0, 64);
+}
+function flush() {
+    if (!app || queue.length === 0)
+        return;
+    const points = queue.splice(0, MAX_BATCH);
+    const body = JSON.stringify({ app, version: code(version), points });
+    try {
+        const sent = navigator.sendBeacon?.(endpoint, new Blob([body], { type: 'application/json' }));
+        if (!sent)
+            fetch(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body,
+                keepalive: true,
+            }).catch(() => { });
+    }
+    catch {
+        // Telemetry must never break the page.
+    }
+    if (queue.length)
+        flush();
+}
+/** Queues one point (nothing is kept until `useLumenTelemetry` has named the app); the batch goes out every 15 s, at 50 points, or when the tab is hidden. */
+export function reportClient(p) {
+    if (!started)
+        return;
+    queue.push({
+        ...p,
+        route: p.route ?? route,
+        name: code(p.name),
+        requestId: code(p.requestId),
+        device: device(),
+    });
+    if (queue.length >= MAX_BATCH)
+        flush();
+}
+/** A request that failed: its API route template, status (0 when it never answered) and id. */
+export function reportFailedFetch(apiRoute, status, requestId) {
+    reportClient({ kind: 'fetch_fail', name: apiRoute, status, requestId: requestId ?? undefined });
+}
+/** An error the page caught or didn't: its class and stack hash only. */
+export function reportClientError(error) {
+    reportClient({
+        kind: 'error',
+        name: error instanceof Error ? error.name : 'Error',
+        fingerprint: stackFingerprint(error),
+    });
+}
+const vital = (m) => reportClient({ kind: 'vital', name: m.name, value: m.value });
+function start() {
+    if (started || typeof window === 'undefined')
+        return;
+    started = true;
+    window.addEventListener('error', (e) => reportClientError(e.error ?? new Error('script')));
+    window.addEventListener('unhandledrejection', (e) => reportClientError(e.reason));
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden')
+            flush();
+    });
+    window.addEventListener('pagehide', flush);
+    setInterval(flush, FLUSH_MS);
+    onLCP(vital);
+    onINP(vital);
+    onCLS(vital);
+}
+/** Mount once at the app's root: every screen change is a view, and errors and vitals follow. */
+export function useLumenTelemetry(opts) {
+    useEffect(() => {
+        app = opts.app;
+        version = opts.version ?? '';
+        endpoint = opts.endpoint ?? '/api/t';
+        start();
+    }, [opts.app, opts.version, opts.endpoint]);
+    useEffect(() => {
+        route = opts.route;
+        reportClient({ kind: 'view', route: opts.route });
+    }, [opts.route]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "description": "Lumen: shared React components (frame, views, widgets, charts, drawers).",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,7 @@
     "@codemirror/lang-javascript": "6.2.5",
     "@codemirror/lang-json": "6.0.2",
     "@codemirror/lang-sql": "6.10.0",
-    "@columenlabs/lumen-ui-types": "0.1.80",
+    "@columenlabs/lumen-ui-types": "0.1.81",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",
@@ -83,6 +83,7 @@
     "sonner": "^2.0.8",
     "tailwind-merge": "^3.7.0",
     "topojson-client": "3.1.0",
+    "web-vitals": "6.2.3",
     "world-atlas": "2.0.2"
   },
   "peerDependencies": {