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

package/dist/preview.d.ts

@@ -0,0 +1,35 @@
+import { type SettingsInput } from './settings';
+import { type WidgetView } from './ui/widget';
+export type { SettingsInput } from './settings';
+export type { CustomField, 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;
+    };
+};
+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,54 @@
+import { a as e, n as t, o as n, t as r } from "./chunks/widget-CkR1Ptzb.mjs";
+// src/preview.ts
+var i = `
+: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%; }
+`, a = "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 o(t, o, s = {}) {
+	let c = t.shadowRoot ?? t.attachShadow({ mode: "open" }), l = { ...s }, u = null, d = (t, o) => {
+		u?.destroy(), c.replaceChildren(), u = new r(c, {
+			enabled: !0,
+			settings: n(t),
+			branding: e({
+				...l.branding,
+				poweredBy: l.poweredBy !== !1
+			})
+		}, {
+			takeScreenshot: async () => ({
+				dataUrl: a,
+				annotations: []
+			}),
+			markUp: async () => null,
+			submit: async () => ({ status: "sent" }),
+			user: () => void 0
+		}, {
+			className: l.phone ? "preview phone" : "preview",
+			css: i
+		}), o !== "button" && u.showView(o);
+	};
+	return d(o, l.view ?? "button"), {
+		update(e, t) {
+			let n = u?.currentView() ?? "button";
+			t && (l = {
+				...l,
+				...t
+			}), d(e, t?.view ?? n);
+		},
+		show(e) {
+			u?.showView(e);
+		},
+		view() {
+			return u?.currentView() ?? "button";
+		},
+		destroy() {
+			u?.destroy(), u = null, c.replaceChildren();
+		}
+	};
+}
+export { o as preview };
+
+//# sourceMappingURL=preview.mjs.map

package/dist/privacy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AI-12: text patterns for personal details. Used only by the lazily loaded
+ * chunks (screenshot auto-blur, replay masking), never by the initial script.
+ */
+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,9 @@
+import { type Fetch } from './api';
+import { type ReportBody } from './report';
+/** What may be kept in localStorage: the report without the private extras. */
+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,15 @@
+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;
+};
+export declare function startRecorder(options?: {
+    exclude?: string;
+}): Recorder;

package/dist/replay/sanitize.d.ts

@@ -0,0 +1,13 @@
+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. */
+export declare function cleanAttributes(attrs: Attrs, tagName?: string, base?: string): 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`.
+ */
+export declare function serializeReplay(events: readonly ReplayEvent[], base?: string | undefined): string;
+export {};

package/dist/report.d.ts

@@ -0,0 +1,109 @@
+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 { Annotation, FieldAnswer, PinaxUser, ReportType } from './types';
+/**
+ * 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[];
+    /** P-04: honeypot value and time to fill in the form. */
+    hp?: string;
+    elapsedMs?: number;
+};
+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[];
+    replay?: string;
+    hp?: string;
+    elapsedMs?: number;
+};
+/** 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;
+}): 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 secret-looking query values masked (C-06).
+ */
+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,31 @@
+import type { AiConfig, Branding, CustomField, 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'> & {
+    types: Partial<WidgetSettings['types']>;
+    wording: Partial<WidgetWording>;
+    capture: Partial<WidgetSettings['capture']>;
+}>;
+/** 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;
+/** 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;

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+export type PinaxOptions = {
+    /** The website's public key (S-08). */
+    key: string;
+    /** Override the API origin, e.g. for local development. */
+    apiUrl?: string;
+    /** Segment: force sending events to `window.analytics` on or off, whatever the site's setting. */
+    segment?: boolean;
+    /**
+     * Override the CDN origin that serves the site's settings (P-15), default
+     * https://cdn.getpinax.com. When `apiUrl` is set and this isn't, settings
+     * come from the API.
+     */
+    cdnUrl?: string;
+};
+/** Signed-in visitor details attached to reports (C-09). */
+export type PinaxUser = {
+    id?: string;
+    name?: string;
+    email?: string;
+};
+export type WidgetPosition = 'bottom-right' | 'bottom-left' | 'right-edge';
+/** S-06: custom wording. An empty string means "use the default wording". */
+export type WidgetWording = {
+    chooserTitle: string;
+    problemTitle: string;
+    ideaTitle: string;
+    generalTitle: string;
+    messagePlaceholder: string;
+    confirmation: string;
+};
+/** W-10: an owner-defined field in the form. */
+export type CustomField = {
+    id: string;
+    type: 'select' | 'text' | 'checkbox';
+    label: string;
+    required: boolean;
+    /** Dropdown choices. */
+    options: string[];
+    /** Which kinds of feedback show it. */
+    types: {
+        problem: boolean;
+        idea: boolean;
+        general: boolean;
+    };
+};
+/** W-10: a visitor's answer, as sent in the report body. */
+export type FieldAnswer = {
+    id: string;
+    value: string | boolean;
+};
+/**
+ * The website's widget settings, as defined by
+ * `backend/src/modules/widget/widget-settings.ts`.
+ */
+export type WidgetSettings = {
+    /** S-01 */
+    color: string;
+    text: string;
+    position: WidgetPosition;
+    /** S-02 */
+    types: {
+        problem: boolean;
+        idea: boolean;
+        general: boolean;
+    };
+    rating: boolean;
+    /** S-04: path patterns where the button is hidden; `*` matches anything. */
+    hidePaths: string[];
+    /** S-04: a smaller button on phones. */
+    smallOnMobile: boolean;
+    /** S-05: no floating button; the site opens the widget with `Pinax.open()`. */
+    hideButton: boolean;
+    /** Segment: send widget events to the page's own `window.analytics`. */
+    segment: boolean;
+    /** S-06 */
+    wording: WidgetWording;
+    /** W-10 */
+    fields: CustomField[];
+    /** C-10: what is recorded with each report. */
+    capture: {
+        console: boolean;
+        network: boolean;
+    };
+};
+/**
+ * W-17: "Powered by Pinax" (Starter) and, with client branding (Agency),
+ * the client's logo and colours. Missing or null = Pinax's own look.
+ */
+export type Branding = {
+    poweredBy: boolean;
+    logoUrl?: string | null;
+    primary?: string | null;
+    accent?: string | null;
+};
+/** AI-17: a report marked Fixed whose error the widget watches for. */
+export type FixCheck = {
+    id: string;
+    path: string;
+    signature: string;
+};
+/**
+ * Pinax AI switches for the browser (`widgetAiConfig` in
+ * `backend/src/modules/widget/widget.service.ts`).
+ */
+export type AiConfig = {
+    /** AI-10: ask one follow-up question about a short note. */
+    followUp: boolean;
+    /** AI-12: blur emails, phone numbers and names in screenshots. */
+    autoBlur: boolean;
+    /** AI-15 / P-13: keep a rolling 30-second replay (Pro and Agency). */
+    replay: boolean;
+    replaySampleRate: number;
+    /** AI-17 / P-14 */
+    fixChecks: FixCheck[];
+    fixCheckSampleRate: number;
+};
+/** `data` of GET /v1/widget/:key/config. */
+export type WidgetConfig = {
+    enabled: boolean;
+    /** S-15: hostnames that may send reports. Missing (older API) means don't check. */
+    allowedDomains?: string[];
+    settings: WidgetSettings;
+    branding: Branding;
+    /** B-17: over the limit, replay and fix-check sampling is cut (to 0.01). */
+    samplingRate?: number | null;
+    ai?: AiConfig;
+};
+export type ReportType = 'PROBLEM' | 'IDEA' | 'GENERAL';
+/** One drawn mark, coordinates as fractions (0 to 1) of the sent image. */
+export type Annotation = {
+    type: 'box' | 'arrow' | 'text' | 'blur';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text?: string;
+};

package/dist/ui/color.d.ts

@@ -0,0 +1,7 @@
+/** Relative luminance of a #rgb or #rrggbb colour (WCAG 2). */
+export declare function luminance(hex: string): number | null;
+export declare function contrast(a: number, b: number): number;
+/** The board's dark ink (#0B1300) or white, whichever reads better on `bg`. */
+export declare function inkFor(bg: string): string;
+/** Only accept plain hex colours from config, so nothing odd reaches CSS. */
+export declare function safeColor(value: unknown, fallback?: string): string;

package/dist/ui/dom.d.ts

@@ -0,0 +1,14 @@
+type Attrs = Record<string, string | number | boolean | undefined | null>;
+type Child = Node | string | null | undefined | false;
+/** Tiny element builder. Text is always set as text, never parsed as HTML. */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Attrs, ...children: Child[]): HTMLElementTagNameMap[K];
+/** A 16px stroked icon from a path. */
+export declare function icon(d: string, size?: number): SVGSVGElement;
+export declare const ICONS: {
+    close: string;
+    back: string;
+    pen: string;
+    camera: string;
+    trash: string;
+};
+export {};

package/dist/ui/styles.d.ts

@@ -0,0 +1,3 @@
+/** The phone rules inside `open` (a media query or ''), `$` replaced by `wrap`. */
+export declare function phoneRules(open: string, wrap: string): string;
+export declare const CSS: string;