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

package/dist/preview.d.ts

@@ -0,0 +1,48 @@
+import { type SettingsInput } from './settings';
+import type { KnownIssue } from './types';
+import { type WidgetView } from './ui/widget';
+export type { SettingsInput } from './settings';
+export type { CustomField, KnownIssue, WidgetSettings, WidgetWording, } from './types';
+export type { WidgetView } from './ui/widget';
+export type PreviewOptions = {
+    /** Screen to show. Default 'button' (closed). */
+    view?: WidgetView;
+    /** Phone layout (bottom sheet, `smallOnMobile`) whatever the page width. */
+    phone?: boolean;
+    /** Show "Powered by Pinax". Default true. */
+    poweredBy?: boolean;
+    /** W-17: the client's logo and colours (Agency). */
+    branding?: {
+        logoUrl?: string | null;
+        primary?: string | null;
+        accent?: string | null;
+    };
+    /**
+     * Known issues to show on the chooser ('choose'), as if they matched this
+     * page (the first 3). Without them the card never shows; with
+     * `knownIssues.enabled` off in the settings it doesn't either. "Me too"
+     * only shows the thanks.
+     */
+    known?: KnownIssue[];
+    /**
+     * Who the form's notice says reports go to ("Sent to … with your note"),
+     * e.g. the site's name or domain. Default "this website".
+     */
+    site?: string;
+};
+export type PreviewHandle = {
+    /** Re-render with new settings, staying on the screen on show. */
+    update(settings: SettingsInput, options?: PreviewOptions): void;
+    /** Jump to a screen ('button' closes the panel). */
+    show(view: WidgetView): void;
+    /** The screen on show (changes when the viewer clicks around). */
+    view(): WidgetView;
+    /** Removes the preview's UI from the container. */
+    destroy(): void;
+};
+/**
+ * Renders the widget into `container`'s shadow root with `settings`.
+ * Give the container a size (e.g. 100% x 520px); the button and panel are
+ * positioned inside it exactly as they would be in the visitor's window.
+ */
+export declare function preview(container: HTMLElement, settings: SettingsInput, options?: PreviewOptions): PreviewHandle;

package/dist/preview.mjs

@@ -0,0 +1,67 @@
+import { a as e, n as t, o as n, s as r, t as i } from "./chunks/widget-BpTBdX2R.mjs";
+// src/preview.ts
+var a = `
+:host { display: block; position: relative; overflow: hidden; }
+.preview .launcher, .preview .panel { position: absolute; }
+.preview .panel { max-height: calc(100% - 108px); }
+.preview.pos-right-edge .panel, .preview.no-button .panel { max-height: calc(100% - 48px); }
+${t("", ".pnx.phone")}
+.pnx.preview.phone .panel { max-height: 88%; }
+`, o = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22600%22%20height%3D%22340%22%20viewBox%3D%220%200%20600%20340%22%3E%3Crect%20width%3D%22600%22%20height%3D%22340%22%20fill%3D%22%23F4EDE2%22%2F%3E%3Crect%20x%3D%220%22%20y%3D%220%22%20width%3D%22600%22%20height%3D%2244%22%20fill%3D%22%23FFFFFF%22%2F%3E%3Crect%20x%3D%2224%22%20y%3D%2216%22%20width%3D%22120%22%20height%3D%2212%22%20rx%3D%226%22%20fill%3D%22%23111827%22%2F%3E%3Crect%20x%3D%2240%22%20y%3D%2282%22%20width%3D%22300%22%20height%3D%2222%22%20rx%3D%228%22%20fill%3D%22%23111827%22%2F%3E%3Crect%20x%3D%2240%22%20y%3D%22118%22%20width%3D%22380%22%20height%3D%2212%22%20rx%3D%226%22%20fill%3D%22%23C9C2B6%22%2F%3E%3Crect%20x%3D%2240%22%20y%3D%22140%22%20width%3D%22330%22%20height%3D%2212%22%20rx%3D%226%22%20fill%3D%22%23C9C2B6%22%2F%3E%3Crect%20x%3D%2240%22%20y%3D%22186%22%20width%3D%22250%22%20height%3D%22110%22%20rx%3D%2214%22%20fill%3D%22%23FFFFFF%22%2F%3E%3Crect%20x%3D%22316%22%20y%3D%22186%22%20width%3D%22250%22%20height%3D%22110%22%20rx%3D%2214%22%20fill%3D%22%23FFFFFF%22%2F%3E%3Crect%20x%3D%2260%22%20y%3D%22250%22%20width%3D%22110%22%20height%3D%2228%22%20rx%3D%2214%22%20fill%3D%22%23FF5C35%22%2F%3E%3C%2Fsvg%3E";
+function s(t, s, c = {}) {
+	let l = t.shadowRoot ?? t.attachShadow({ mode: "open" }), u = { ...c }, d = null, f = (t, s) => {
+		d?.destroy(), l.replaceChildren();
+		let c = r(t), f = n(u.known, c.knownIssues);
+		d = new i(l, {
+			enabled: !0,
+			settings: c,
+			branding: e({
+				...u.branding,
+				poweredBy: u.poweredBy !== !1
+			})
+		}, {
+			takeScreenshot: async () => ({
+				dataUrl: o,
+				annotations: []
+			}),
+			markUp: async () => null,
+			submit: async () => ({ status: "sent" }),
+			user: () => void 0,
+			knownIssues: () => f,
+			meToo: async () => !0,
+			attachments: () => {
+				let e = c.consent?.required === !0, { console: t, network: n } = c.capture;
+				return {
+					logs: !e,
+					askLogs: e && (t || n),
+					replay: !1
+				};
+			},
+			site: () => u.site || "this website"
+		}, {
+			className: u.phone ? "preview phone" : "preview",
+			css: a
+		}), s !== "button" && d.showView(s);
+	};
+	return f(s, u.view ?? "button"), {
+		update(e, t) {
+			let n = d?.currentView() ?? "button";
+			t && (u = {
+				...u,
+				...t
+			}), f(e, t?.view ?? n);
+		},
+		show(e) {
+			d?.showView(e);
+		},
+		view() {
+			return d?.currentView() ?? "button";
+		},
+		destroy() {
+			d?.destroy(), d = null, l.replaceChildren();
+		}
+	};
+}
+export { s as preview };
+
+//# sourceMappingURL=preview.mjs.map

package/dist/privacy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AI-12: text patterns for personal details. Screenshot auto-blur and replay
+ * masking use all of it; the initial script uses only `redactPersonal` (and
+ * what it needs), for console text, breadcrumb targets and error signatures.
+ * Mirrored by `redactPersonal` in `backend/src/modules/widget/widget.sanitise.ts`.
+ */
+export type Span = {
+    start: number;
+    end: number;
+    kind: 'email' | 'phone';
+};
+export declare function isPhone(raw: string): boolean;
+/** Emails and phone numbers in `text`, in order, never overlapping. */
+export declare function findPersonalSpans(text: string): Span[];
+/** Replaces emails and phone numbers with asterisks (same length). */
+export declare function redactPersonal(text: string): string;
+/** A text that is only a label ("Name", "Customer:"); the name follows it. */
+export declare const NAME_LABEL_ONLY: RegExp;
+/** "Name: Ada Lovelace" in one text. */
+export declare const NAME_LABEL_INLINE: RegExp;
+/** "Signed in as Ada", "Welcome back, Ada" anywhere in a text. */
+export declare const SIGNED_IN: RegExp;
+/** Text short enough, and wordy enough, to be a name or username after a label. */
+export declare function looksLikeNameValue(text: string): boolean;

package/dist/queue.d.ts

@@ -0,0 +1,10 @@
+import { type Fetch } from './api';
+import { type ReportBody } from './report';
+export declare const MAX_AGE_MS: number;
+/** What may be kept in localStorage: the report without the private parts. */
+export declare function queuedCopy(body: ReportBody): ReportBody;
+/** Saves a slimmed copy of a report for later (see above). */
+export declare function enqueue(key: string, body: ReportBody): boolean;
+export declare function queuedCount(key: string): number;
+/** Sends what's waiting. Items the server refuses for good are dropped. */
+export declare function flush(doFetch: Fetch, api: string, key: string): Promise<void>;

package/dist/replay/buffer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AI-15: a rolling window of rrweb events. Events are kept in segments that
+ * each start with a full snapshot (rrweb's Meta event, then FullSnapshot,
+ * from `checkoutEveryNms`), so whatever is kept can be replayed from its
+ * first event. A segment is dropped once the next one already starts at or
+ * before the window's edge, so the buffer always covers the last
+ * `windowMs` (or the whole visit, if shorter) and at most one checkout
+ * interval more.
+ */
+export type ReplayEvent = {
+    type: number;
+    timestamp: number;
+};
+/** rrweb's EventType.Meta: the first event of every full snapshot. */
+export declare const META = 4;
+export declare class ReplayBuffer<E extends ReplayEvent = ReplayEvent> {
+    readonly windowMs: number;
+    private now;
+    /** Hard cap on events held, whatever the time window (a very busy page). */
+    readonly maxEvents: number;
+    private segments;
+    constructor(windowMs?: number, now?: () => number, 
+    /** Hard cap on events held, whatever the time window (a very busy page). */
+    maxEvents?: number);
+    push(event: E): void;
+    /** Drops whole segments that are no longer needed to cover the window. */
+    trim(): void;
+    private count;
+    /**
+     * The events to send, oldest first. `lastSegments` keeps only the newest
+     * segments, for when the full window is too big to upload.
+     */
+    events(lastSegments?: number): E[];
+    get segmentCount(): number;
+    clear(): void;
+}
+/** base64 of bytes, in chunks so big replays don't overflow the call stack. */
+export declare function toBase64(bytes: Uint8Array): string;
+/** gzip with the browser's CompressionStream; null where it isn't supported. */
+export declare function gzip(text: string): Promise<Uint8Array | null>;

package/dist/replay/recorder.d.ts

@@ -0,0 +1,25 @@
+export declare const WINDOW_MS = 30000;
+/** A full snapshot this often, so the kept window can start mid-visit. */
+export declare const CHECKOUT_MS = 10000;
+export type Recorder = {
+    /**
+     * The buffer as base64 of gzipped JSON, at most `maxChars` long (fewer
+     * seconds if the whole window doesn't fit), or null when it can't be made
+     * (no CompressionStream, nothing recorded, too big).
+     */
+    exportReplay(maxChars: number): Promise<string | null>;
+    stop(): void;
+};
+/**
+ * `'all'` (the default, CNIL's "mask everything"): every text is starred out
+ * and images, pictures, videos, canvases and frames are left out (the replay
+ * shows an empty box of the same size). `'inputs'`: form fields, editable
+ * text, emails and phone numbers only.
+ */
+export type ReplayMask = 'all' | 'inputs';
+/** Left out entirely with `mask: 'all'`; rrweb records only their size. */
+export declare const MEDIA = "img,picture,video,canvas,iframe";
+export declare function startRecorder(options?: {
+    exclude?: string;
+    mask?: ReplayMask;
+}): Recorder;

package/dist/replay/sanitize.d.ts

@@ -0,0 +1,19 @@
+import { type ReplayEvent } from './buffer';
+/** A URL without its fragment or secret query values, and no email or phone. */
+export declare function cleanUrl(value: string, base?: string): string;
+type Attrs = Record<string, unknown>;
+/**
+ * A cleaned copy of a node's (or a mutation's) attributes. `maskText` also
+ * stars out the text attributes above.
+ */
+export declare function cleanAttributes(attrs: Attrs, tagName?: string, base?: string, maskText?: boolean): Attrs;
+/**
+ * The events as JSON, with every attribute cleaned: full snapshot nodes
+ * (`{ tagName, attributes }`), mutation adds (same shape) and attribute
+ * changes (`{ id, attributes }`). Meta events get a cleaned `href`.
+ * `maskText` (replay mask 'all') stars out text attributes as well.
+ */
+export declare function serializeReplay(events: readonly ReplayEvent[], base?: string | undefined, options?: {
+    maskText?: boolean;
+}): string;
+export {};

package/dist/report.d.ts

@@ -0,0 +1,128 @@
+import type { Breadcrumb } from './capture/breadcrumbs';
+import type { ConsoleEntry } from './capture/console';
+import type { Environment } from './capture/env';
+import type { NetworkEntry } from './capture/network';
+import type { A11yScan, Annotation, Barrier, FieldAnswer, PinaxUser, ReportType } from './types';
+export declare const BARRIERS: Barrier[];
+/**
+ * Builds the POST /reports body. Mirrors the limits in
+ * backend/src/modules/widget/widget.validator.ts so a report is never rejected
+ * for something the widget could have trimmed.
+ */
+export declare const LIMITS: {
+    readonly message: 5000;
+    readonly email: 320;
+    readonly entries: 50;
+    readonly annotations: 200;
+    /** The backend caps the data URL at 6,000,000 chars and the decoded image at 4.5 MB. */
+    readonly screenshotChars: 6000000;
+    readonly screenshotBytes: number;
+    readonly breadcrumbs: 20;
+    readonly followUpQuestion: 300;
+    readonly followUpAnswer: 2000;
+    /** AI-15: base64 of the gzipped replay. */
+    readonly replayChars: 4500000;
+    /** W-10: answers per report, and the longest text answer. */
+    readonly fields: 10;
+    readonly fieldId: 40;
+    readonly fieldText: 200;
+    /** The reports route parses at most 11 MB (`express.json({ limit: '11mb' })`). */
+    readonly bodyBytes: number;
+};
+export declare function isEmail(value: string): boolean;
+export type ReportInput = {
+    type: ReportType;
+    message: string;
+    rating?: number;
+    email?: string;
+    user?: PinaxUser;
+    screenshot?: string;
+    annotations?: Annotation[];
+    /** AI-10 */
+    followUp?: {
+        question: string;
+        answer: string;
+    };
+    /** W-10 */
+    fields?: FieldAnswer[];
+    /** W-19, W-20: accessibility reports only. */
+    barrier?: Barrier;
+    a11yScan?: A11yScan | null;
+    /** P-04: honeypot value and time to fill in the form. */
+    hp?: string;
+    elapsedMs?: number;
+    /** Visitor consent, only on sites that wait for it. */
+    consent?: ReportConsent;
+    /** The visitor ticked "Include technical details" (consent not given). */
+    includeLogs?: boolean;
+};
+/** What the visitor agreed to through the site's banner. */
+export type ReportConsent = {
+    diagnostics: boolean;
+    replay: boolean;
+};
+export type ReportContext = {
+    page: {
+        url: string;
+        title?: string;
+    };
+    environment: Environment;
+    console: ConsoleEntry[];
+    network: NetworkEntry[];
+    breadcrumbs?: Breadcrumb[];
+};
+export type ReportBody = {
+    type: ReportType;
+    message: string;
+    rating?: number;
+    email?: string;
+    user?: PinaxUser;
+    page: {
+        url: string;
+        title?: string;
+    };
+    environment: Environment;
+    console?: ConsoleEntry[];
+    network?: NetworkEntry[];
+    screenshot?: string;
+    annotations?: Array<Record<string, unknown>>;
+    breadcrumbs?: Breadcrumb[];
+    followUp?: {
+        question: string;
+        answer: string;
+    };
+    fields?: FieldAnswer[];
+    barrier?: Barrier;
+    a11yScan?: A11yScan;
+    replay?: string;
+    hp?: string;
+    elapsedMs?: number;
+    consent?: ReportConsent;
+    includeLogs?: true;
+};
+/** Decoded byte length of a base64 data URL. */
+export declare function dataUrlBytes(dataUrl: string): number;
+export declare function isSendableScreenshot(dataUrl: string): boolean;
+/** The backend refuses a report with no note, no rating and no screenshot. */
+export declare function hasContent(input: {
+    type: ReportType;
+    message: string;
+    rating?: number;
+    screenshot?: string;
+    barrier?: Barrier;
+}): boolean;
+/**
+ * Page URL as the backend accepts it: absolute, at most 2000 chars, with no
+ * fragment (OAuth implicit flow, Supabase and Firebase put tokens in
+ * `#access_token=…`) and query values hidden (`…`) except the harmless
+ * `PAGE_PARAM` ones (`utm_*`, `page`, `lang`, `ref`, `variant`, `tab`, `sort`).
+ */
+export declare function pageUrl(href: string): string;
+export declare function buildReport(input: ReportInput, ctx: ReportContext): ReportBody;
+/** UTF-8 size of the JSON body. */
+export declare function bodyBytes(body: ReportBody): number;
+/**
+ * AI-15: adds the replay only when it fits the backend's limits (4.5 M
+ * base64 characters, the whole request under 11 MB). Returns whether it did.
+ */
+export declare function attachReplay(body: ReportBody, replay: string | null): boolean;

package/dist/segment.d.ts

@@ -0,0 +1,31 @@
+import type { ReportType } from './types';
+type SegmentUser = {
+    id?: () => unknown;
+};
+/** The parts of `window.analytics` we use. The snippet stub has only `track`. */
+export type SegmentAnalytics = {
+    track?: (event: string, properties?: Record<string, unknown>) => unknown;
+    user?: () => SegmentUser | undefined;
+};
+export declare const SEGMENT_EVENTS: {
+    readonly opened: 'Pinax Widget Opened';
+    readonly submitted: 'Feedback Submitted';
+};
+/** `window.analytics`, if it looks like Segment's. */
+export declare function segmentAnalytics(win?: Window): SegmentAnalytics | null;
+/** The init option wins over the site's setting. */
+export declare function segmentEnabled(option: boolean | undefined, setting: boolean | undefined): boolean;
+export declare function trackOpened(): void;
+export declare function trackSubmitted(input: {
+    type: ReportType;
+    rating?: number | null;
+    reportId?: string;
+    queued?: boolean;
+}): void;
+/**
+ * Segment's signed-in user id (`analytics.user().id()`), used when the site
+ * didn't call `Pinax.identify()`. Null before analytics.js has loaded or for
+ * anonymous visitors.
+ */
+export declare function segmentUserId(): string | null;
+export {};

package/dist/settings.d.ts

@@ -0,0 +1,40 @@
+import type { AiConfig, Branding, CustomField, KnownIssue, WidgetSettings, WidgetWording } from './types';
+/** Same defaults as `backend/src/modules/widget/widget-settings.ts`. */
+export declare const DEFAULT_SETTINGS: WidgetSettings;
+/** W-10: the backend's limits (`FIELD_LIMITS` in widget-settings.ts). */
+export declare const FIELD_LIMITS: {
+    readonly fields: 10;
+    readonly label: 80;
+    readonly options: 20;
+    readonly option: 80;
+    readonly text: 200;
+};
+/** Settings with any field (or wording/type entry) left out. */
+export type SettingsInput = Partial<Omit<WidgetSettings, 'types' | 'wording' | 'capture' | 'knownIssues' | 'consent'> & {
+    types: Partial<WidgetSettings['types']>;
+    wording: Partial<WidgetWording>;
+    capture: Partial<WidgetSettings['capture']>;
+    knownIssues: Partial<NonNullable<WidgetSettings['knownIssues']>>;
+    consent: Partial<NonNullable<WidgetSettings['consent']>>;
+}>;
+/** W-10: well-formed fields only, so a half-made field in the dashboard can't break the form. */
+export declare function resolveFields(input: unknown): CustomField[];
+/**
+ * Fills in anything missing or malformed with the defaults, so an older API
+ * (or a half-edited dashboard form, in the preview) never breaks the widget.
+ */
+export declare function resolveSettings(input?: SettingsInput | null): WidgetSettings;
+/** The privacy policy link: an https address, or '' (never javascript: and the like). */
+export declare function httpsUrl(v: unknown): string;
+/** W-17: only plain hex colours and an http(s) logo address get through. */
+export declare function resolveBranding(input: unknown): Branding;
+/**
+ * The AI part of the config, everything off when missing (an older API, or
+ * a site without Pinax AI). `samplingRate` (B-17) caps both sample rates.
+ */
+export declare function resolveAi(ai: unknown, samplingRate?: unknown): AiConfig;
+/**
+ * Known issues from the config: none when missing (an older API or CDN
+ * copy) or switched off, and only well-formed entries otherwise.
+ */
+export declare function resolveKnown(input: unknown, settings?: WidgetSettings['knownIssues']): KnownIssue[];