@tristan2828/ui-foundation 4.0.0 → 4.1.0

package/dist/api/gateway/client-errors.d.ts

@@ -0,0 +1,4 @@
+import type { components } from "../schema.js";
+export type ClientErrorReport = components["schemas"]["ClientErrorReport"];
+/** Resolves whatever happens: a report that can't be sent is dropped. */
+export declare function reportClientError(report: ClientErrorReport): Promise<void>;

package/dist/api/gateway/client-errors.js

@@ -0,0 +1,14 @@
+import { safeFetch } from "./errors.js";
+/** Resolves whatever happens: a report that can't be sent is dropped. */
+export async function reportClientError(report) {
+    try {
+        await safeFetch("/client-errors", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(report),
+        });
+    }
+    catch {
+        // Network down: nothing to do, and nothing to report it to.
+    }
+}

package/dist/api/gateway/errors.d.ts

@@ -1,9 +1,6 @@
 import { type ApiResponse } from "../transport/index.js";
 import type { AppError } from "../contracts.js";
 export declare function safeFetch(path: string, init?: RequestInit): Promise<ApiResponse>;
-/**
- * Pass the response's `headers` so a 429 carries its Retry-After
- * (`retryAfterSeconds`); without them it's still `rate_limited`.
- */
+export declare function httpStatusOf(error: AppError): number | undefined;
 export declare function toAppError(status: number, body: unknown, headers?: Headers): AppError;
 export declare function networkError(): AppError;

package/dist/api/gateway/errors.js

@@ -15,7 +15,19 @@ export async function safeFetch(path, init) {
  * Pass the response's `headers` so a 429 carries its Retry-After
  * (`retryAfterSeconds`); without them it's still `rate_limited`.
  */
+// The HTTP status each AppError came from, kept beside it rather than on
+// it, so AppError's shape (and every test comparing one) doesn't change.
+// Error reporting reads it (src/error-reporting/reporter.ts).
+const STATUS = new WeakMap();
+export function httpStatusOf(error) {
+    return STATUS.get(error);
+}
 export function toAppError(status, body, headers) {
+    const error = translate(status, body, headers);
+    STATUS.set(error, status);
+    return error;
+}
+function translate(status, body, headers) {
     if (status === 422) {
         // A rule the server enforces (a cap, a status the change needs) is
         // often refused with FastAPI's HTTPException shape: a sentence, not a

package/dist/api/schema.d.ts

@@ -111,6 +111,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/client-errors": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * A failure in the browser, for the backend to forward to error reporting
+         * @description Sent by the package when an app turns on FoundationProviders' errorReporting. Needs a session, so the public can't post into it. The backend may drop a report (a duplicate, too many) and still answer 204. The user is the session's; the report never carries request or response bodies, cookies, headers, form values or query strings.
+         */
+        post: operations["reportClientError"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -146,6 +166,25 @@ export interface components {
             name: components["schemas"]["User"]["name"];
             password: components["schemas"]["LoginRequest"]["password"];
         };
+        ClientErrorReport: {
+            /**
+             * @description Where the package caught it.
+             * @enum {string}
+             */
+            source: "route" | "window" | "unhandledrejection" | "query" | "mutation";
+            /** @description The error's type (TypeError, ServerError). */
+            type: string;
+            message: string;
+            stack?: string;
+            /** @description The route pattern (/items/:id), never the URL. */
+            route?: string;
+            /** @description The HTTP method of a failed request. */
+            method?: string;
+            /** @description The HTTP status of a failed request. */
+            status?: number;
+            /** @description The frontend build (its commit). */
+            release?: string;
+        };
         /** @description FastAPI's default 422 shape (RequestValidationError). */
         ValidationErrorBody: {
             detail: {
@@ -378,4 +417,29 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    reportClientError: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ClientErrorReport"];
+            };
+        };
+        responses: {
+            /** @description Received (forwarded, or dropped as a duplicate). */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["UnauthorizedError"];
+            422: components["responses"]["ValidationError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
 }

package/dist/components/app/app-shell.js

@@ -6,6 +6,8 @@ import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
 import { activeNavTo, navGroups } from './app-shell-nav.js';
 import { ErrorState } from './error-state.js';
+import { useErrorReporter } from '../../error-reporting/error-reporting-context.js';
+import { ReportRoutePattern } from '../../error-reporting/error-reporting-provider.js';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
 import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, useSidebar, } from '../ui/sidebar.js';
@@ -41,6 +43,7 @@ function AppShellSkeleton() {
 export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }) {
     const { user, status, error, retry, logout } = useAuth();
     const location = useLocation();
+    const reporter = useErrorReporter();
     // Set before logout starts, so the redirect below knows this was a
     // deliberate logout. It can't be a follow-up navigate() after logout
     // resolves: that runs before React re-renders, and the <Navigate> this
@@ -66,7 +69,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
     const activeTo = activeNavTo(nav, location.pathname);
-    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: group.items.map(({ to, label, icon: Icon }) => {
+    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: group.items.map(({ to, label, icon: Icon }) => {
                                                             // A plain Link, not NavLink: NavLink marks every
                                                             // matching entry current, and only the most specific
                                                             // one should be (activeNavTo).

package/dist/components/app/foundation-providers.d.ts

@@ -1,9 +1,17 @@
 import { type QueryClient } from '@tanstack/react-query';
 import { type ReactNode } from 'react';
-export declare function FoundationProviders({ mockMode, queryClient, children, }: {
+import { type ErrorReportingOptions } from '../../error-reporting/reporter.js';
+export declare function FoundationProviders({ mockMode, queryClient, errorReporting, children, }: {
     /** Whether the API is served by MSW — the app's own IS_MOCK_MODE. */
     mockMode: boolean;
     /** Defaults to createQueryClient(); pass one to share it with code outside React. */
     queryClient?: QueryClient;
+    /**
+     * Off by default. On, crashes, uncaught errors and server failures are
+     * posted to the app's own POST /api/client-errors (while signed in),
+     * which forwards them; see docs/deploy.md "Error reporting" for what a
+     * report holds and never holds. `{ release }` names the build.
+     */
+    errorReporting?: boolean | ErrorReportingOptions;
     children: ReactNode;
 }): import("react").JSX.Element;

package/dist/components/app/foundation-providers.js

@@ -5,13 +5,16 @@ import { createQueryClient } from '../../api/query-client.js';
 import { AuthProvider } from '../../auth/use-auth.js';
 import { MockModeBanner } from './mock-mode-banner.js';
 import { ThemeProvider } from '../theme-provider.js';
+import { ErrorReportingProvider } from '../../error-reporting/error-reporting-provider.js';
+import { resolveErrorReporting } from '../../error-reporting/reporter.js';
 // Everything an app's root needs around its router, in the order that
 // works: the theme outermost, the mock-mode banner above the router so it
 // shows on every route (/login included), and AuthProvider inside
 // QueryClientProvider because it queries /auth/me through TanStack Query.
 // An app's DataEnvironmentBanner goes first among the children, before its
 // router: it queries too, and shows on every route like the mock banner.
-export function FoundationProviders({ mockMode, queryClient, children, }) {
+export function FoundationProviders({ mockMode, queryClient, errorReporting, children, }) {
     const [client] = useState(() => queryClient ?? createQueryClient());
-    return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: children }) })] }));
+    const reporting = resolveErrorReporting(errorReporting);
+    return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: reporting ? _jsx(ErrorReportingProvider, { options: reporting, children: children }) : children }) })] }));
 }

package/dist/components/app/route-error-boundary.js

@@ -1,9 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { TriangleAlertIcon } from 'lucide-react';
+import { useEffect } from 'react';
 import { isRouteErrorResponse, useRouteError } from 'react-router';
+import { useErrorReporter, useRoutePattern } from '../../error-reporting/error-reporting-context.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
 export function RouteErrorBoundary() {
     const error = useRouteError();
+    const reporter = useErrorReporter();
+    const route = useRoutePattern();
+    useEffect(() => {
+        // A crash, or a loader's 5xx; never a 404 (no such page) or other 4xx.
+        if (!reporter || (isRouteErrorResponse(error) && error.status < 500))
+            return;
+        reporter.setRoute(route);
+        reporter.report('route', error, isRouteErrorResponse(error) ? { status: error.status } : undefined);
+    }, [reporter, error, route]);
     const message = isRouteErrorResponse(error)
         ? `${error.status} ${error.statusText}`
         : error instanceof Error

package/dist/error-reporting/error-reporting-context.d.ts

@@ -0,0 +1,6 @@
+import { type ErrorReporter } from './reporter.js';
+export declare const ErrorReportingContext: import("react").Context<ErrorReporter | null>;
+/** The reporter, or null when the app hasn't turned reporting on. */
+export declare function useErrorReporter(): ErrorReporter | null;
+/** The current route's pattern (`/widgets/:id`), from a data router's matches. */
+export declare function useRoutePattern(): string | null;

package/dist/error-reporting/error-reporting-context.js

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+import { useMatches } from 'react-router';
+import { routePattern } from './reporter.js';
+// Null unless FoundationProviders' errorReporting is on
+// (./error-reporting-provider.tsx), so every use of it does nothing then.
+export const ErrorReportingContext = createContext(null);
+/** The reporter, or null when the app hasn't turned reporting on. */
+export function useErrorReporter() {
+    return useContext(ErrorReportingContext);
+}
+/** The current route's pattern (`/widgets/:id`), from a data router's matches. */
+export function useRoutePattern() {
+    const matches = useMatches();
+    const last = matches[matches.length - 1];
+    return last ? routePattern(last.pathname, last.params) : null;
+}

package/dist/error-reporting/error-reporting-provider.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import { type ErrorReporter, type ErrorReportingOptions } from './reporter.js';
+export declare function ErrorReportingProvider({ options, children }: {
+    options: ErrorReportingOptions;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Keeps the reporter's route current, for reports that don't know theirs.
+ * AppShell renders it only while reporting is on: the router's matches
+ * need a data router (createBrowserRouter), which reporting then needs too.
+ */
+export declare function ReportRoutePattern({ reporter }: {
+    reporter: ErrorReporter;
+}): null;

package/dist/error-reporting/error-reporting-provider.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The React side of error reporting (./reporter.ts): FoundationProviders
+// mounts this inside AuthProvider when `errorReporting` is on. Off, there's
+// no provider, the context is null, and nothing here runs.
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import { reportClientError } from '../api/gateway/client-errors.js';
+import { useAuth } from '../auth/use-auth.js';
+import { ErrorReportingContext, useRoutePattern } from './error-reporting-context.js';
+import { createErrorReporter } from './reporter.js';
+export function ErrorReportingProvider({ options, children }) {
+    const queryClient = useQueryClient();
+    const { status } = useAuth();
+    const [reporter] = useState(() => createErrorReporter({ options, send: (report) => void reportClientError(report) }));
+    useEffect(() => reporter.setSignedIn(status === 'authenticated'), [reporter, status]);
+    useEffect(() => reporter.install(queryClient, window), [reporter, queryClient]);
+    return _jsx(ErrorReportingContext.Provider, { value: reporter, children: children });
+}
+/**
+ * Keeps the reporter's route current, for reports that don't know theirs.
+ * AppShell renders it only while reporting is on: the router's matches
+ * need a data router (createBrowserRouter), which reporting then needs too.
+ */
+export function ReportRoutePattern({ reporter }) {
+    const pattern = useRoutePattern();
+    useEffect(() => reporter.setRoute(pattern), [reporter, pattern]);
+    return null;
+}

package/dist/error-reporting/reporter.d.ts

@@ -0,0 +1,30 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { ClientErrorReport } from "../api/gateway/client-errors.js";
+export type ErrorReportingOptions = {
+    /** The frontend build a report names, e.g. the commit (`import.meta.env.VITE_RELEASE`). */
+    release?: string;
+};
+export type ReportSource = ClientErrorReport["source"];
+/** FoundationProviders' prop, as options, or null when reporting is off. */
+export declare function resolveErrorReporting(option: boolean | ErrorReportingOptions | undefined): ErrorReportingOptions | null;
+export declare function scrub(text: string, limit: number): string;
+/** `/widgets/7/edit` with `{ id: '7' }` → `/widgets/:id/edit`; a splat → `*`. */
+export declare function routePattern(pathname: string, params: Readonly<Record<string, string | undefined>>): string;
+export type ErrorReporter = {
+    /** Reports `error` from `source`, unless it's a duplicate or signed out. */
+    report: (source: ReportSource, error: unknown, request?: {
+        method?: string;
+        status?: number;
+    }) => void;
+    /** The screen's route pattern, for reports that don't know theirs. */
+    setRoute: (pattern: string | null) => void;
+    /** Whether there's a session: the endpoint refuses without one, so nothing is sent until then. */
+    setSignedIn: (signedIn: boolean) => void;
+    /** Listens on the window and the query client; returns the undo. */
+    install: (queryClient: QueryClient, target: Pick<EventTarget, "addEventListener" | "removeEventListener">) => () => void;
+};
+export declare function createErrorReporter({ options, send, now, }: {
+    options: ErrorReportingOptions;
+    send: (report: ClientErrorReport) => void;
+    now?: () => number;
+}): ErrorReporter;

package/dist/error-reporting/reporter.js

@@ -0,0 +1,126 @@
+import { httpStatusOf } from "../api/gateway/errors.js";
+const DEDUPE_MS = 60_000;
+const MAX_MESSAGE = 2000;
+const MAX_STACK = 16000;
+const REPORTED_KINDS = new Set(["server"]);
+/** FoundationProviders' prop, as options, or null when reporting is off. */
+export function resolveErrorReporting(option) {
+    if (!option)
+        return null;
+    return option === true ? {} : option;
+}
+// A query string or fragment in a URL or path, up to a stack frame's
+// trailing :line:col (the backend's scrub, in app/error_reporting.py, is
+// the same rule).
+const URL_QUERY = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s?#"'()]+|(?<![\w/])\/[^\s?#"'()]*)[?#][^\s"'()]*?(?=(?::\d+){1,2}(?=[\s"'()]|$)|[\s"'()]|$)/gi;
+export function scrub(text, limit) {
+    const cut = text.replace(URL_QUERY, "$1");
+    return cut.length <= limit ? cut : `${cut.slice(0, limit - 1)}…`;
+}
+/** `/widgets/7/edit` with `{ id: '7' }` → `/widgets/:id/edit`; a splat → `*`. */
+export function routePattern(pathname, params) {
+    const named = Object.entries(params).filter(([name, value]) => name !== "*" && value);
+    const splat = params["*"];
+    let path = pathname;
+    if (splat && path.endsWith(`/${splat}`))
+        path = `${path.slice(0, -splat.length)}*`;
+    return path
+        .split("/")
+        .map((segment) => {
+        const match = named.find(([, value]) => value === decodeSegment(segment));
+        return match ? `:${match[0]}` : segment;
+    })
+        .join("/");
+}
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+function isAppError(value) {
+    return typeof value === "object" && value !== null && "kind" in value && "message" in value;
+}
+function describe(error) {
+    if (error instanceof Error) {
+        return { type: error.name || "Error", message: error.message, stack: error.stack };
+    }
+    if (isAppError(error))
+        return { type: "ServerError", message: error.message };
+    return { type: "Error", message: typeof error === "string" ? error : "A value that isn't an Error was thrown." };
+}
+export function createErrorReporter({ options, send, now = Date.now, }) {
+    const lastSent = new Map();
+    let route = null;
+    let signedIn = false;
+    const report = (source, error, request = {}) => {
+        if (!signedIn)
+            return;
+        const described = describe(error);
+        const message = scrub(described.message, MAX_MESSAGE);
+        const signature = [source, described.type, message, route ?? ""].join("\u001f");
+        const at = now();
+        for (const [key, sentAt] of lastSent)
+            if (at - sentAt >= DEDUPE_MS)
+                lastSent.delete(key);
+        if (lastSent.has(signature))
+            return;
+        lastSent.set(signature, at);
+        send({
+            source,
+            type: described.type.slice(0, 200),
+            message,
+            ...(described.stack ? { stack: scrub(described.stack, MAX_STACK) } : {}),
+            ...(route ? { route } : {}),
+            ...(request.method ? { method: request.method } : {}),
+            ...(request.status ? { status: request.status } : {}),
+            ...(options.release ? { release: options.release.slice(0, 100) } : {}),
+        });
+    };
+    const reportAppError = (source, error, method) => {
+        if (!isAppError(error) || !REPORTED_KINDS.has(error.kind))
+            return;
+        report(source, error, { method, status: httpStatusOf(error) });
+    };
+    return {
+        report,
+        setRoute: (pattern) => {
+            route = pattern;
+        },
+        setSignedIn: (value) => {
+            signedIn = value;
+        },
+        install: (queryClient, target) => {
+            const onError = (event) => {
+                const { error, message } = event;
+                report("window", error ?? message);
+            };
+            const onRejection = (event) => {
+                const { reason } = event;
+                // An AppError is a request's answer: the caches below report the
+                // ones that are bugs, and the rest are expected.
+                if (isAppError(reason))
+                    return;
+                report("unhandledrejection", reason);
+            };
+            target.addEventListener("error", onError);
+            target.addEventListener("unhandledrejection", onRejection);
+            const unsubscribeQueries = queryClient.getQueryCache().subscribe((event) => {
+                if (event.type === "updated" && event.action.type === "error")
+                    reportAppError("query", event.action.error, "GET");
+            });
+            const unsubscribeMutations = queryClient.getMutationCache().subscribe((event) => {
+                if (event.type === "updated" && event.action.type === "error")
+                    reportAppError("mutation", event.action.error);
+            });
+            return () => {
+                target.removeEventListener("error", onError);
+                target.removeEventListener("unhandledrejection", onRejection);
+                unsubscribeQueries();
+                unsubscribeMutations();
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { returnPath } from './routes/return-path.js';
 export { AuthProvider, useAuth } from './auth/use-auth.js';
 export type { AuthContextValue, AuthStatus, AuthUser, SignInResult } from './auth/auth-context.js';
 export type { AppError, Page, QuerySpec } from './api/contracts.js';
+export type { ErrorReportingOptions } from './error-reporting/reporter.js';
 export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';

package/dist/mocks/client-errors.d.ts

@@ -0,0 +1,7 @@
+import type { components } from '../api/schema.js';
+type ClientErrorReport = components['schemas']['ClientErrorReport'];
+/** What POST /client-errors has received since the last reset. */
+export declare function getMockClientErrors(): readonly ClientErrorReport[];
+export declare function resetMockClientErrors(): void;
+export declare const clientErrorHandlers: import("msw").HttpHandler[];
+export {};

package/dist/mocks/client-errors.js

@@ -0,0 +1,24 @@
+// MSW handler for POST /client-errors (openapi/foundation.yaml), for an app
+// that turns on FoundationProviders' errorReporting. It answers 204 like
+// the reference backend and keeps what it was sent, so an app's tests can
+// check a report was made and what it held. Like the backend, it needs the
+// mock session.
+import { http, HttpResponse } from 'msw';
+import { isMockAuthenticated } from './auth.js';
+let received = [];
+/** What POST /client-errors has received since the last reset. */
+export function getMockClientErrors() {
+    return received;
+}
+export function resetMockClientErrors() {
+    received = [];
+}
+export const clientErrorHandlers = [
+    http.post('*/api/client-errors', async ({ request }) => {
+        if (!isMockAuthenticated()) {
+            return HttpResponse.json({ detail: 'Not authenticated' }, { status: 401 });
+        }
+        received = [...received, (await request.json())];
+        return new HttpResponse(null, { status: 204 });
+    }),
+];

package/dist/mocks/index.d.ts

@@ -1,4 +1,5 @@
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
 export { exposeMswForE2E } from './e2e-hooks.js';
 export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -2,5 +2,6 @@
 // so msw (an optional peer dependency) never reaches an app's main bundle
 // unless it imports this.
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/openapi/foundation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: UI Foundation — the contract every app shares
-  version: "4.0.0"
+  version: "4.1.0"
   description: >
     The part of an app's API contract that the foundation package's own code
     calls: session-cookie auth under /auth/*, and the two error envelopes the
@@ -136,6 +136,31 @@ paths:
               schema: { $ref: "#/components/schemas/DataEnvironment" }
         "500": { $ref: "#/components/responses/ServerError" }
 
+  /client-errors:
+    x-optional: true
+    post:
+      operationId: reportClientError
+      summary: A failure in the browser, for the backend to forward to error reporting
+      description: >
+        Sent by the package when an app turns on FoundationProviders'
+        errorReporting. Needs a session, so the public can't post into it.
+        The backend may drop a report (a duplicate, too many) and still
+        answer 204. The user is the session's; the report never carries
+        request or response bodies, cookies, headers, form values or
+        query strings.
+      tags: [errors]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ClientErrorReport" }
+      responses:
+        "204":
+          description: Received (forwarded, or dropped as a duplicate).
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
 components:
   schemas:
     DataEnvironment:
@@ -191,6 +216,25 @@ components:
         name: { $ref: "#/components/schemas/User/properties/name" }
         password: { $ref: "#/components/schemas/LoginRequest/properties/password" }
 
+    ClientErrorReport:
+      type: object
+      required: [source, type, message]
+      properties:
+        source:
+          type: string
+          enum: [route, window, unhandledrejection, query, mutation]
+          description: Where the package caught it.
+        type: { type: string, minLength: 1, maxLength: 200, description: "The error's type (TypeError, ServerError)." }
+        message: { type: string, maxLength: 2000 }
+        stack: { type: string, maxLength: 16000 }
+        route:
+          type: string
+          maxLength: 300
+          description: The route pattern (/items/:id), never the URL.
+        method: { type: string, maxLength: 10, description: The HTTP method of a failed request. }
+        status: { type: integer, minimum: 100, maximum: 599, description: The HTTP status of a failed request. }
+        release: { type: string, maxLength: 100, description: The frontend build (its commit). }
+
     ValidationErrorBody:
       type: object
       description: FastAPI's default 422 shape (RequestValidationError).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {