@getpinax/widget 0.0.0-stage → 1.0.0-beta.2

package/dist/capture/breadcrumbs.d.ts

@@ -0,0 +1,49 @@
+import type { RingBuffer } from './ring';
+/**
+ * AI-11: what the visitor did just before sending. The backend's schema is
+ * `breadcrumbs` in `backend/src/modules/widget/widget.validator.ts`.
+ */
+export type Breadcrumb = {
+    kind: 'click' | 'navigation' | 'input';
+    at: string;
+    path: string;
+    /** Short, privacy-safe description of the target, e.g. button "Book a table". */
+    target?: string;
+};
+export declare const MAX_BREADCRUMBS = 20;
+export declare const MAX_NAME = 60;
+/** A password or payment card field: not even its label is kept. */
+export declare function isSecretField(el: Element): boolean;
+export declare function roleOf(el: Element): string;
+/**
+ * Visible text of `el`, skipping form fields, editable areas and anything
+ * the owner masked. Images contribute their alt text.
+ */
+export declare function safeText(el: Element, max?: number): string;
+/** The accessible name, as far as it can be read without visitor data. */
+export declare function nameOf(el: Element): string;
+/**
+ * A short, privacy-safe description of what was clicked or typed in:
+ * `button "Book a table"`, `link "Menu"`, `textbox "Email"`,
+ * `password field`. Names are cut to 60 characters. A click on anything
+ * that isn't a control (a paragraph, a table cell, an order summary) keeps
+ * only its role or tag: its text may be the visitor's own details.
+ */
+export declare function describeTarget(start: Element): string;
+/** The page as breadcrumbs record it: path and query keys (values hidden), no fragment. */
+export declare function currentPath(href?: string): string;
+type Options = {
+    /** Events from inside the widget itself are left out. */
+    ignore?: (target: EventTarget | null) => boolean;
+    doc?: Document;
+};
+/**
+ * Records clicks and typing (never what was typed) into `buffer`. Page views
+ * are added by the caller through `navigated()`, so they share the one
+ * history watcher. Never throws into the page.
+ */
+export declare function captureBreadcrumbs(buffer: RingBuffer<Breadcrumb>, options?: Options): {
+    navigated: () => void;
+    stop: () => void;
+};
+export {};

package/dist/capture/console.d.ts

@@ -0,0 +1,17 @@
+import type { RingBuffer } from './ring';
+export type ConsoleLevel = 'error' | 'warn' | 'log' | 'info' | 'debug';
+export type ConsoleEntry = {
+    level: ConsoleLevel;
+    message: string;
+    stack?: string;
+    at: string;
+};
+export declare const MAX_MESSAGE = 2000;
+export declare const MAX_STACK = 4000;
+export declare function formatArgs(args: unknown[]): string;
+/**
+ * C-04: wraps console methods and listens for uncaught errors and rejected
+ * promises. Never throws into the page; if the host replaces `console` later,
+ * capture just stops for the replaced methods.
+ */
+export declare function captureConsole(buffer: RingBuffer<ConsoleEntry>, target?: Window & typeof globalThis): () => void;

package/dist/capture/env.d.ts

@@ -0,0 +1,25 @@
+import { type DeviceType } from './ua';
+export type Environment = {
+    userAgent: string;
+    browser?: string;
+    browserVersion?: string;
+    os?: string;
+    deviceType: DeviceType;
+    deviceModel?: string;
+    screen: {
+        w: number;
+        h: number;
+    };
+    viewport: {
+        w: number;
+        h: number;
+    };
+    pixelRatio: number;
+    timeZone: string;
+    language?: string;
+    occurredAt: string;
+};
+/** Local time with its UTC offset, e.g. 2026-11-04T15:20:01.123+01:00 (C-01). */
+export declare function localIsoTime(date?: Date): string;
+/** C-01 to C-03, read at the moment the visitor sends. */
+export declare function readEnvironment(win?: Window): Environment;

package/dist/capture/network.d.ts

@@ -0,0 +1,23 @@
+import type { RingBuffer } from './ring';
+export type NetworkEntry = {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    at: string;
+};
+/** C-05: a request is kept when it fails or takes longer than this. */
+export declare const SLOW_MS = 2000;
+export declare function shouldRecord(status: number, durationMs: number): boolean;
+type Options = {
+    /** Requests to these URL prefixes (Pinax's own API) are never recorded. */
+    ignore?: (url: string) => boolean;
+    now?: () => number;
+};
+/**
+ * C-05/C-06: wraps fetch and XMLHttpRequest and records only failed or slow
+ * requests: method, URL (query values hidden), status (0 = network error),
+ * duration and time. Headers and bodies are never read.
+ */
+export declare function captureNetwork(buffer: RingBuffer<NetworkEntry>, target?: Window, options?: Options): () => void;
+export {};

package/dist/capture/ring.d.ts

@@ -0,0 +1,14 @@
+/** A fixed-size buffer that keeps only the newest `capacity` items (C-04, C-05). */
+export declare class RingBuffer<T> {
+    readonly capacity: number;
+    private items;
+    private listeners;
+    constructor(capacity: number);
+    push(item: T): void;
+    /** Called with every new item (AI-17 fix check). Returns an unsubscribe. */
+    subscribe(listener: (item: T) => void): () => void;
+    /** Oldest first. Returns a copy. */
+    toArray(): T[];
+    clear(): void;
+    get size(): number;
+}

package/dist/capture/signature.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Emails and phone numbers are starred out first, as in the report's console
+ * text, so a signature never carries them (it's published in the site's
+ * config) and matches whether the text was starred out already or not.
+ */
+export declare function normalise(text: string): string;
+export declare function errorSignature(consoleLogs: unknown, networkLogs: unknown): string | null;

package/dist/capture/text.d.ts

@@ -0,0 +1,23 @@
+/** Cuts a string to `max` characters, marking the cut with an ellipsis. */
+export declare function clip(value: string, max: number): string;
+/**
+ * C-06: drops the fragment, credentials and secret-looking query values from a
+ * URL before it is kept. The backend masks again (defence in depth). For
+ * what is sent, `logUrl` and `pageUrl` (report.ts) also hide query values.
+ */
+export declare function safeUrl(raw: string, base?: string): string;
+/**
+ * Query parameters whose values a report's page address keeps: campaign and
+ * view state, never anything a visitor typed. Everything else becomes `…`.
+ * Mirrors `PAGE_PARAM` in `backend/src/modules/widget/widget.sanitise.ts`.
+ */
+export declare const PAGE_PARAM: RegExp;
+/**
+ * Personal data hides in query strings (`?email=`, `?name=`, search terms),
+ * so every value becomes `…` and only the keys stay, except those `keep`
+ * names. Works on the string, so `…` isn't percent-encoded, and keys,
+ * order and key-only parameters (`?debug`) are kept as they were.
+ */
+export declare function maskQuery(url: string, keep?: RegExp): string;
+/** Network log and breadcrumb URLs: `safeUrl`, then every query value hidden. */
+export declare function logUrl(raw: string, base?: string): string;

package/dist/capture/ua.d.ts

@@ -0,0 +1,13 @@
+export type DeviceType = 'desktop' | 'mobile' | 'tablet';
+export type ParsedUA = {
+    browser?: string;
+    browserVersion?: string;
+    os?: string;
+    deviceType: DeviceType;
+    deviceModel?: string;
+};
+/**
+ * C-02: a small hand-written user-agent parser. `maxTouchPoints` tells iPads
+ * in desktop mode (which claim to be a Mac) apart from real Macs.
+ */
+export declare function parseUserAgent(ua: string, maxTouchPoints?: number): ParsedUA;