@universelle/sentinel-report 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog — @universelle/sentinel-report
+
+## 0.3.0 — 2026-10-24
+
+### Privacy
+For sites whose paths carry secrets (an invitation token in `/u/<token>`, a personal link, internal ids), three
+options in `createReporter`, `useSentinelReport` and `capture()` clean everything that leaves the page. Recording
+stays raw in memory; the cleaning happens when the context is built (`context()`, `send()`):
+
+- **`route(pathname) => template`**. Applies to `page.path`, to every entry of `trail` and to every `network[].path`.
+  It always receives the path without its query string or fragment. If it throws or returns something that isn't a
+  string, that path goes as `"/(otra)"`, never raw. Consecutive pages with the same template become one entry.
+- **The title.** With `route`, `page.title` goes as `""`, because the title can carry the page's data. `title: true`
+  sends it anyway.
+- **Console messages.** With `route`, every absolute URL becomes its origin (`https://host/`). Every path at the start
+  of the message, or after a space, a bracket or a quote, goes through `route`. Then **`redact(message)`**, if given,
+  for anything else (UUIDs, tokens…). If `redact` throws, the message goes empty.
+- **Without these options nothing changes**: the body is the same as in 0.2.0.
+
+Unchanged: the body's format, the endpoint, `credentials: "omit"`, the limit of 20 entries, no dependencies and no
+install scripts.
+
+## 0.2.0 — 2026-10-24
+- SENTINEL's mark for your own branding: `<SentinelMark>`, `<sentinel-mark>`, `markSvg()` and `MARK_SHAPES`.
+
+## 0.1.0 — 2026-10-24
+- First release: the core (`capture`, `createReporter`), the `<sentinel-report>` web component and React
+  (`<ReportButton>`, `useSentinelReport`).

package/README.md

@@ -125,6 +125,24 @@ import { createReporter } from "@universelle/sentinel-report";
 await createReporter({ site: "your-site" }).send({ kind: "wish", text: "Export the table" });
 ```
 
+## Privacy: paths with secrets
+
+If your paths carry secrets (an invitation token in `/u/<token>`, a personal link, internal ids), pass `route`. It
+turns each real path into its template, so SENTINEL only receives templates. It applies to the page, every page of
+the trail, every failed request and the paths and URLs inside console messages, and the page's title is dropped.
+`redact` cleans console messages further.
+
+```tsx
+const route = (pathname: string) => toTemplate(pathname) ?? "/(otra)"; // e.g. "/u/[invitation]"
+const redact = (message: string) => message.replace(UUID, "[id]");
+
+const { send } = useSentinelReport({ site: "your-site", route, redact });
+// or: createReporter({ site: "your-site", route, redact }); or once for the page: capture({ route, redact })
+```
+
+A `route` that throws, or doesn't return a string, sends `"/(otra)"`, never the raw path. Without these options,
+everything is sent as in 0.2.0. See [CHANGELOG.md](CHANGELOG.md).
+
 ## Branding: SENTINEL's mark
 
 For your own button, a footer or a "Protected by SENTINEL" line. The eye and the star take the text colour

package/dist/core.d.ts

@@ -30,6 +30,17 @@ export type Report = {
     text: string;
     email?: string;
 };
+/** How a site cleans what is sent (0.3.0). Without `route`, everything goes as in 0.2.0. */
+export type Privacy = {
+    /** A real path (`/u/AbC…`) to its template (`/u/[invitation]`). If it throws or returns no string: `"/(otra)"`. */
+    route?: (pathname: string) => string;
+    /** Every console message, after the default cleaning (with `route`: URLs to their origin, paths to templates). */
+    redact?: (message: string) => string;
+    /** Send `document.title` (default: yes without `route`, no with it: the title can carry the page's data). */
+    title?: boolean;
+};
+/** What goes in place of a path the site's `route` can't turn into a template. */
+export declare const UNKNOWN_ROUTE = "/(otra)";
 export type Reporter = {
     /** Sends a report; rejects with an `Error` whose message is the HTTP status (or the network error). */
     send(report: Report): Promise<void>;
@@ -41,16 +52,25 @@ type Capture = {
     network: FailedRequest[];
     trail: string[];
     fetch: typeof fetch;
+    privacy: Privacy;
 };
 declare global {
     interface Window {
         __sentinelCapture?: Capture;
     }
 }
-/** Starts recording the visit's context (once per page; later calls return the same recording). */
-export declare function capture(): Capture;
+/**
+ * Starts recording the visit's context (once per page; later calls return the same recording). The privacy options
+ * given here are the page's default for every reporter that doesn't bring its own; a later call can still set them.
+ */
+export declare function capture(privacy?: Privacy): Capture;
+/**
+ * A console message as it may leave: with `route`, each absolute URL becomes its origin and each path (at the start,
+ * or after a space, a bracket or a quote) its template; then the site's own `redact`, if any.
+ */
+export declare function cleanMessage(message: string, privacy: Privacy): string;
 export declare function createReporter(options: {
     site: string;
     endpoint?: string;
-}): Reporter;
+} & Privacy): Reporter;
 export {};

package/dist/core.js

@@ -1,7 +1,14 @@
 // The core, with no framework: it records the technical context of the visit (console errors, failed requests,
 // pages visited) and sends a report to SENTINEL. What it never sends: the query string or fragment of any URL (they
 // can carry tokens) or anything typed into the site. Installed once per page, whoever asks first.
+//
+// Privacy (0.3.0): sites whose paths carry secrets (`/u/<invitation token>`) pass `route`, which turns a real path
+// into its template (`/u/[invitation]`). What is recorded stays raw in memory; everything that leaves (`context()`,
+// `send()`) goes through it: the page, every page of the trail, every failed request, and the paths and URLs inside
+// console messages; and the page's title is dropped. `redact` cleans console messages further.
 export const DEFAULT_ENDPOINT = "https://sentinel.cervilla.es";
+/** What goes in place of a path the site's `route` can't turn into a template. */
+export const UNKNOWN_ROUTE = "/(otra)";
 const MAX = 20;
 function clip(text) {
     return String(text).replace(/\s+/g, " ").slice(0, 300);
@@ -74,27 +81,83 @@ function watchNavigation(capture) {
     }
     window.addEventListener("popstate", visit);
 }
-/** Starts recording the visit's context (once per page; later calls return the same recording). */
-export function capture() {
-    if (window.__sentinelCapture !== undefined)
+/**
+ * Starts recording the visit's context (once per page; later calls return the same recording). The privacy options
+ * given here are the page's default for every reporter that doesn't bring its own; a later call can still set them.
+ */
+export function capture(privacy = {}) {
+    if (window.__sentinelCapture !== undefined) {
+        if (privacy.route !== undefined || privacy.redact !== undefined || privacy.title !== undefined)
+            window.__sentinelCapture.privacy = privacy;
         return window.__sentinelCapture;
-    const recording = { logs: [], network: [], trail: [location.pathname], fetch: window.fetch.bind(window) };
+    }
+    const recording = { logs: [], network: [], trail: [location.pathname], fetch: window.fetch.bind(window), privacy };
     window.__sentinelCapture = recording;
     watchConsole(recording);
     watchFetch(recording);
     watchNavigation(recording);
     return recording;
 }
+/** A path through the site's `route`, never raw once a route is given: what fails goes as `"/(otra)"`. */
+function template(route, pathname) {
+    if (route === undefined)
+        return pathname;
+    try {
+        const mapped = route(pathname.split(/[?#]/)[0]);
+        return typeof mapped === "string" ? mapped : UNKNOWN_ROUTE;
+    }
+    catch {
+        return UNKNOWN_ROUTE;
+    }
+}
+/**
+ * A console message as it may leave: with `route`, each absolute URL becomes its origin and each path (at the start,
+ * or after a space, a bracket or a quote) its template; then the site's own `redact`, if any.
+ */
+export function cleanMessage(message, privacy) {
+    let clean = message;
+    if (privacy.route !== undefined) {
+        clean = clean.replace(/https?:\/\/[^\s"'()<>]+/g, (url) => {
+            try {
+                return `${new URL(url).origin}/`;
+            }
+            catch {
+                return "[url]";
+            }
+        });
+        clean = clean.replace(/(^|[\s("'])(\/[^\s"'()<>]*)/g, (_match, before, pathname) => `${before}${template(privacy.route, pathname)}`);
+    }
+    if (privacy.redact !== undefined) {
+        try {
+            const redacted = privacy.redact(clean);
+            clean = typeof redacted === "string" ? redacted : "";
+        }
+        catch {
+            clean = "";
+        }
+    }
+    return clean;
+}
+/** The trail through `route`; consecutive pages with the same template become one. */
+function trailOf(trail, route) {
+    return trail.map((pathname) => template(route, pathname)).filter((pathname, index, all) => index === 0 || all[index - 1] !== pathname);
+}
 export function createReporter(options) {
     const recording = capture();
     const url = `${(options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/reports/${encodeURIComponent(options.site)}`;
-    const context = () => ({
-        page: { path: location.pathname, title: document.title.slice(0, 200) },
-        device: { userAgent: navigator.userAgent.slice(0, 300), language: navigator.language, viewport: `${innerWidth}x${innerHeight}`, screen: `${screen.width}x${screen.height}` },
-        console: recording.logs.slice(),
-        network: recording.network.slice(),
-        trail: recording.trail.slice(),
-    });
+    const own = options.route !== undefined || options.redact !== undefined || options.title !== undefined;
+    const context = () => {
+        // The reporter's own options, else the page's default (from `capture()`), read when sending.
+        const privacy = own ? { route: options.route, redact: options.redact, title: options.title } : recording.privacy;
+        const withTitle = privacy.title ?? privacy.route === undefined;
+        return {
+            page: { path: template(privacy.route, location.pathname), title: withTitle ? document.title.slice(0, 200) : "" },
+            device: { userAgent: navigator.userAgent.slice(0, 300), language: navigator.language, viewport: `${innerWidth}x${innerHeight}`, screen: `${screen.width}x${screen.height}` },
+            console: recording.logs.map((entry) => ({ ...entry, message: cleanMessage(entry.message, privacy) })),
+            network: recording.network.map((entry) => ({ ...entry, path: template(privacy.route, entry.path) })),
+            trail: privacy.route === undefined ? recording.trail.slice() : trailOf(recording.trail, privacy.route),
+        };
+    };
     return {
         context,
         async send(report) {

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { capture, createReporter, DEFAULT_ENDPOINT } from "./core.js";
+export { capture, cleanMessage, createReporter, DEFAULT_ENDPOINT, UNKNOWN_ROUTE } from "./core.js";
 export { MARK_SHAPES, markSvg } from "./logo.js";
-export type { Context, ConsoleEntry, FailedRequest, Report, ReportKind, Reporter } from "./core.js";
+export type { Context, ConsoleEntry, FailedRequest, Privacy, Report, ReportKind, Reporter } from "./core.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 // @universelle/sentinel-report: the core, with no framework. For the ready-made button, `…/element` (any site) or
 // `…/react`; to build your own form, `createReporter` here or `useSentinelReport` in React.
-export { capture, createReporter, DEFAULT_ENDPOINT } from "./core.js";
+export { capture, cleanMessage, createReporter, DEFAULT_ENDPOINT, UNKNOWN_ROUTE } from "./core.js";
 export { MARK_SHAPES, markSvg } from "./logo.js";

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type CSSProperties, type ReactNode } from "react";
-import { type Report } from "./core.js";
+import { type Privacy, type Report } from "./core.js";
 import type { Texts } from "./element.js";
 import "./element.js";
 export type ReportButtonProps = {
@@ -57,11 +57,14 @@ export declare function SentinelMark({ size, title, className, style }: Sentinel
     style: CSSProperties | undefined;
 }, Element>;
 export type ReportStatus = "idle" | "sending" | "sent" | "error";
-/** For your own form: records the visit from the first render and sends with its context. */
+/**
+ * For your own form: records the visit from the first render and sends with its context. `route`, `redact` and
+ * `title` clean what is sent (see `Privacy`); pass stable functions (defined outside the component).
+ */
 export declare function useSentinelReport(options: {
     site: string;
     endpoint?: string;
-}): {
+} & Privacy): {
     send: (report: Report) => Promise<boolean>;
     status: ReportStatus;
     error: unknown;

package/dist/react.js

@@ -31,9 +31,12 @@ export function SentinelMark({ size = "1em", title, className, style }) {
     const label = title ? { role: "img", "aria-label": title } : { "aria-hidden": true, focusable: "false" };
     return createElement("svg", { viewBox: "0 0 100 100", width: size, height: size, className, style, ...label, dangerouslySetInnerHTML: { __html: `${title ? `<title>${title.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`)}</title>` : ""}${MARK_SHAPES}` } });
 }
-/** For your own form: records the visit from the first render and sends with its context. */
+/**
+ * For your own form: records the visit from the first render and sends with its context. `route`, `redact` and
+ * `title` clean what is sent (see `Privacy`); pass stable functions (defined outside the component).
+ */
 export function useSentinelReport(options) {
-    const reporter = useMemo(() => (typeof window === "undefined" ? undefined : createReporter(options)), [options.site, options.endpoint]);
+    const reporter = useMemo(() => (typeof window === "undefined" ? undefined : createReporter(options)), [options.site, options.endpoint, options.route, options.redact, options.title]);
     const [status, setStatus] = useState("idle");
     const [error, setError] = useState(undefined);
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@universelle/sentinel-report",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SENTINEL's report button: let real users tell you what fails or what they miss, with the technical context of their visit.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {