@qaiddev/thumbs-embed 1.0.10 → 1.0.12

package/dist/screenshot-dom.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DOM-based screenshot capture using html2canvas
+ * No browser permission dialog required - reconstructs the page from the DOM
+ */
+export interface DomScreenshotOptions {
+    /** Quality of WebP compression (0-1). Default: 0.8 */
+    quality?: number;
+    /** Max width of the screenshot. Default: 1280 */
+    maxWidth?: number;
+    /** Max height of the screenshot. Default: 800 */
+    maxHeight?: number;
+}
+declare global {
+    interface Window {
+        html2canvas?: (element: HTMLElement, options?: Record<string, unknown>) => Promise<HTMLCanvasElement>;
+    }
+}
+/**
+ * Check if DOM screenshot capture is supported
+ * Requires canvas and basic DOM APIs
+ */
+export declare function isDomScreenshotSupported(): boolean;
+/**
+ * Capture a screenshot of the current page using html2canvas
+ * Returns a base64-encoded WebP data URL, or null on failure
+ */
+export declare function captureDomScreenshot(options?: DomScreenshotOptions): Promise<string | null>;

package/dist/screenshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Screenshot capture utility using native Screen Capture API
+ */
+export interface ScreenshotOptions {
+    /** Quality of WebP compression (0-1). Default: 1.0 */
+    quality?: number;
+    /** Max width of the screenshot. Default: 1280 */
+    maxWidth?: number;
+    /** Max height of the screenshot. Default: 800 */
+    maxHeight?: number;
+}
+/**
+ * Captures a screenshot using the native Screen Capture API
+ * Requires user permission but produces accurate results
+ * Returns a base64-encoded WebP data URL
+ */
+export declare function captureScreenshot(options?: ScreenshotOptions): Promise<string | null>;

package/dist/styles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CSS styles for the feedback embed
+ * Uses .qaid- prefix to avoid conflicts
+ */
+export interface BuildCssVarsOptions {
+    positiveColor?: string;
+    negativeColor?: string;
+    /** Color for selected element marker */
+    markerColor?: string;
+    /** Button size: small (36px), medium (48px), large (64px) */
+    buttonSize?: "small" | "medium" | "large";
+    /** Modal width in pixels */
+    modalWidth?: number;
+    /** Backdrop opacity (0-1) */
+    backdropOpacity?: number;
+    /** Font family */
+    fontFamily?: string;
+    /** Base font size in pixels */
+    fontSize?: number;
+}
+/**
+ * Build a map of CSS variable names to values for per-instance scoping
+ */
+export declare function buildCssVars(options?: BuildCssVarsOptions): Record<string, string>;
+/**
+ * Apply CSS variables to an element via inline style properties
+ */
+export declare function applyCssVars(el: HTMLElement, vars: Record<string, string>): void;
+/**
+ * Get the CSS string to inject into a shadow root
+ * Includes base shadow styles + default button styles
+ */
+export declare function getEmbedStyles(): string;
+/**
+ * Inject light DOM styles (cursor override + highlight)
+ * Reference-counted across instances
+ */
+export declare function injectStyles(): void;
+/**
+ * Remove light DOM styles when last instance is destroyed
+ */
+export declare function removeStyles(): void;
+/** Reset internal state — for tests only */
+export declare function _resetStylesState(): void;

package/dist/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Configuration options for the QaidFeedback
+ */
+export interface FeedbackConfig {
+    /** Required: API endpoint URL for submitting feedback */
+    endpoint: string;
+    /** API key for authenticating with the feedback service */
+    apiKey?: string;
+    /** CSS selector for user-provided container element. If not provided, creates fixed-position container */
+    container?: string;
+    /** Custom CSS class to apply to thumb buttons. When provided, default button styles are not applied */
+    buttonClass?: string;
+    /** Button layout direction. Default: 'horizontal' */
+    direction?: "horizontal" | "vertical";
+    /** Position of the feedback buttons. Default: 'bottom-right'. Ignored if container is provided */
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    /** Offset from edge in pixels. Default: { x: 16, y: 16 } */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /** z-index for the embed elements. Default: 50 */
+    zIndex?: number;
+    /** When true, skip element targeting and go directly to feedback modal. Default: false */
+    skipTargeting?: boolean;
+    /** Custom colors for feedback types */
+    colors?: {
+        /** Color for positive feedback. Default: rgb(0, 200, 83) */
+        positive?: string;
+        /** Color for negative feedback. Default: rgb(255, 0, 0) */
+        negative?: string;
+        /** Color for selected element marker. Default: #6366f1 */
+        marker?: string;
+    };
+    /** Button size. Default: 'medium' (48px). Small: 36px, Large: 64px */
+    buttonSize?: "small" | "medium" | "large";
+    /** Custom text labels */
+    text?: {
+        /** Tooltip text for buttons */
+        tooltip?: string;
+        /** Modal title */
+        modalTitle?: string;
+        /** Modal subtitle */
+        modalSubtitle?: string;
+        /** Textarea placeholder */
+        placeholder?: string;
+        /** Submit button text */
+        submitButton?: string;
+        /** Skip button text */
+        skipButton?: string;
+    };
+    /** Modal width in pixels. Default: 400 */
+    modalWidth?: number;
+    /** Backdrop opacity (0-1). Default: 0.3 */
+    backdropOpacity?: number;
+    /** Font family for text elements. Default: system-ui, -apple-system, sans-serif */
+    fontFamily?: string;
+    /** Base font size in pixels. Default: 16 */
+    fontSize?: number;
+    /** Enable screenshot capture with feedback. Default: false */
+    captureScreenshot?: boolean;
+    /** Enable video recording button. Default: false */
+    captureVideo?: boolean;
+    /** Video recording options */
+    videoOptions?: {
+        /** Max recording duration in seconds. Default: 15 */
+        maxDuration?: number;
+    };
+    /** Custom SVG string for record button icon */
+    recordIcon?: string;
+    /** When true, buttons are hidden until hovered. Default: false */
+    incognito?: boolean;
+    /** Custom SVG string for positive feedback button icon */
+    positiveIcon?: string;
+    /** Custom SVG string for negative feedback button icon */
+    negativeIcon?: string;
+    /** When true, hide thumbs up/down buttons (only show video button if enabled). Default: false */
+    hideThumbs?: boolean;
+    /** Custom CSS to inject into the embed's shadow root for theming */
+    css?: string;
+    /** Screenshot capture method. "dom" uses html2canvas (no permission), "permission" uses Screen Capture API. Default: "permission" */
+    screenshotMethod?: "dom" | "permission";
+    /** Screenshot options */
+    screenshotOptions?: {
+        /** Quality of WebP compression (0-1). Default: 1.0 */
+        quality?: number;
+        /** Max width of the screenshot. Default: 1280 */
+        maxWidth?: number;
+        /** Max height of the screenshot. Default: 800 */
+        maxHeight?: number;
+    };
+}
+/**
+ * Network error captured during the session
+ */
+export interface NetworkError {
+    url: string;
+    method: string;
+    status: number;
+    statusText: string;
+    requestBody?: string;
+    responseBody?: string;
+    timestamp: number;
+}
+/**
+ * Console message captured during the session
+ */
+export interface ConsoleError {
+    message: string;
+    timestamp: number;
+    level: "error" | "warn" | "log";
+}
+/**
+ * Bounds of the selected element
+ */
+export interface SelectedBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    clickX: number;
+    clickY: number;
+    visible: boolean;
+}
+/**
+ * Current feedback data being collected
+ */
+export interface FeedbackData {
+    feedbackType: "up" | "down" | null;
+    elementSelector: string | null;
+    elementText: string | null;
+    consoleErrors: ConsoleError[];
+}
+/**
+ * State machine states for the embed
+ */
+export type EmbedState = "IDLE" | "TARGETING" | "SELECTED" | "MODAL_OPEN";
+/**
+ * Element bounds for server-side screenshot fallback
+ */
+export interface ElementBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Payload sent to the feedback API
+ */
+export interface FeedbackPayload {
+    feedbackType: "up" | "down";
+    pageUrl: string;
+    /** API key for authenticating with the feedback service */
+    apiKey?: string;
+    elementSelector: string | null;
+    elementText: string | null;
+    consoleErrors: ConsoleError[];
+    screenWidth: number;
+    screenHeight: number;
+    clickX: number;
+    clickY: number;
+    scrollX: number;
+    scrollY: number;
+    /** Base64-encoded screenshot image (WebP) */
+    screenshot: string | null;
+    /** Random UUID stored in visitor's localStorage (for anonymous feedback) */
+    visitorId: string;
+    /** Element bounds for server-side screenshot fallback when client screenshot fails */
+    elementBounds?: ElementBounds | null;
+    /** User agent string for server-side rendering consistency */
+    userAgent?: string;
+}
+/**
+ * Response from the feedback API
+ */
+export interface FeedbackResponse {
+    id: number;
+}
+/**
+ * Payload for updating feedback with a message
+ */
+export interface FeedbackMessagePayload {
+    message: string | null;
+}
+/**
+ * Fully resolved configuration with all defaults applied
+ * Used internally by the embed after processing user config
+ */
+export interface ResolvedFeedbackConfig {
+    endpoint: string;
+    apiKey: string;
+    container: string;
+    buttonClass: string;
+    direction: "horizontal" | "vertical";
+    position: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    offset: {
+        x: number;
+        y: number;
+    };
+    zIndex: number;
+    skipTargeting: boolean;
+    colors: {
+        positive: string;
+        negative: string;
+        marker: string;
+    };
+    buttonSize: "small" | "medium" | "large";
+    text: {
+        tooltip: string;
+        modalTitle: string;
+        modalSubtitle: string;
+        placeholder: string;
+        submitButton: string;
+        skipButton: string;
+    };
+    modalWidth: number;
+    backdropOpacity: number;
+    fontFamily: string;
+    fontSize: number;
+    captureScreenshot: boolean;
+    screenshotMethod: "dom" | "permission";
+    screenshotOptions: {
+        quality: number;
+        maxWidth: number;
+        maxHeight: number;
+    };
+    incognito: boolean;
+    positiveIcon: string;
+    negativeIcon: string;
+    hideThumbs: boolean;
+    css: string;
+    captureVideo: boolean;
+    videoOptions: {
+        maxDuration: number;
+    };
+    recordIcon: string;
+}

package/dist/video-capture.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Video capture utilities
+ * Uses getDisplayMedia + MediaRecorder for screen recording
+ */
+export interface VideoRecorderOptions {
+    /** Max recording duration in seconds. Default: 15 */
+    maxDuration?: number;
+    /** Video bitrate in bps. Default: 800000 (800kbps) */
+    videoBitsPerSecond?: number;
+}
+export interface VideoRecorder {
+    /** Start recording. Requests getDisplayMedia if not already started. */
+    start(): Promise<void>;
+    /** Stop recording and return the video blob. */
+    stop(): Promise<Blob>;
+    /** Register a callback for each second tick (receives seconds elapsed). */
+    onTick(callback: (elapsed: number) => void): void;
+    /** Register a callback for when recording stops (e.g., browser stop button, max duration). */
+    onStop(callback: (blob: Blob | null) => void): void;
+    /** Clean up all resources. */
+    destroy(): void;
+}
+/**
+ * Check if video recording is supported in this browser
+ */
+export declare function isVideoRecordingSupported(): boolean;
+/**
+ * Detect the best supported MIME type for recording
+ */
+export declare function getSupportedMimeType(): string;
+/**
+ * Create a video recorder that captures the screen
+ */
+export declare function createVideoRecorder(options?: VideoRecorderOptions): VideoRecorder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaiddev/thumbs-embed",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Precision User Feedback",
   "type": "module",
   "main": "./dist/qaid.umd.cjs",
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "dev": "vite build --watch",
-    "build": "vite build",
+    "build": "vite build && tsc -p tsconfig.build.json",
     "preview": "vite preview",
     "test": "vitest",
     "test:run": "vitest run"
@@ -36,7 +36,6 @@
     "happy-dom": "^20.5.1",
     "typescript": "^5.3.3",
     "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.18"
   },
   "keywords": [