@bugspotter/sdk 0.1.0-alpha.1

package/dist/core/compress.js

@@ -0,0 +1,245 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressData = compressData;
+exports.decompressData = decompressData;
+exports.compressImage = compressImage;
+exports.getCompressionRatio = getCompressionRatio;
+exports.estimateSize = estimateSize;
+exports.resetCompressionCache = resetCompressionCache;
+const pako_1 = __importDefault(require("pako"));
+const logger_1 = require("../utils/logger");
+/**
+ * Compression utilities for BugSpotter SDK
+ * Handles payload and image compression using browser-native APIs
+ */
+const logger = (0, logger_1.getLogger)();
+// Configuration constants
+const COMPRESSION_DEFAULTS = {
+    GZIP_LEVEL: 6, // Balanced speed/size ratio (0-9)
+    IMAGE_MAX_WIDTH: 1920,
+    IMAGE_MAX_HEIGHT: 1080,
+    IMAGE_WEBP_QUALITY: 0.8,
+    IMAGE_JPEG_QUALITY: 0.85,
+    IMAGE_LOAD_TIMEOUT: 3000, // milliseconds
+};
+// Singleton instances for performance
+let textEncoder = null;
+let textDecoder = null;
+let webpSupportCache = null;
+/**
+ * Get or create TextEncoder instance
+ */
+function getTextEncoder() {
+    if (!textEncoder) {
+        textEncoder = new TextEncoder();
+    }
+    return textEncoder;
+}
+/**
+ * Get or create TextDecoder instance
+ */
+function getTextDecoder() {
+    if (!textDecoder) {
+        textDecoder = new TextDecoder();
+    }
+    return textDecoder;
+}
+/**
+ * Convert data to string representation
+ */
+function dataToString(data) {
+    return typeof data === 'string' ? data : JSON.stringify(data);
+}
+/**
+ * Compress JSON or string data using gzip
+ * @param data - Data to compress (will be JSON stringified if object)
+ * @param config - Optional compression configuration
+ * @returns Compressed data as Uint8Array
+ */
+async function compressData(data, config) {
+    var _a;
+    try {
+        const jsonString = dataToString(data);
+        const encoder = getTextEncoder();
+        const uint8Data = encoder.encode(jsonString);
+        const gzipLevel = (_a = config === null || config === void 0 ? void 0 : config.gzipLevel) !== null && _a !== void 0 ? _a : COMPRESSION_DEFAULTS.GZIP_LEVEL;
+        // pako.gzip already returns Uint8Array, no need to wrap it
+        const compressed = pako_1.default.gzip(uint8Data, { level: gzipLevel });
+        return compressed;
+    }
+    catch (error) {
+        logger.error('Compression failed:', error);
+        throw error;
+    }
+}
+/**
+ * Try to parse string as JSON, return string if not valid JSON
+ */
+function tryParseJSON(jsonString) {
+    try {
+        return JSON.parse(jsonString);
+    }
+    catch (_a) {
+        return jsonString;
+    }
+}
+/**
+ * Decompress gzipped data back to original format
+ * Useful for testing and verification
+ * @param compressed - Compressed Uint8Array data
+ * @param config - Optional configuration
+ * @returns Decompressed and parsed data (or string if input was string)
+ */
+function decompressData(compressed, config) {
+    try {
+        const decompressed = pako_1.default.ungzip(compressed);
+        const decoder = getTextDecoder();
+        const jsonString = decoder.decode(decompressed);
+        return tryParseJSON(jsonString);
+    }
+    catch (error) {
+        if ((config === null || config === void 0 ? void 0 : config.verbose) !== false) {
+            (0, logger_1.getLogger)().error('Decompression failed:', error);
+        }
+        throw new Error(`Failed to decompress data: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Check if code is running in browser environment
+ */
+function isBrowserEnvironment() {
+    return (typeof document !== 'undefined' &&
+        typeof Image !== 'undefined' &&
+        typeof HTMLCanvasElement !== 'undefined');
+}
+/**
+ * Check if browser supports WebP format (cached result)
+ */
+function supportsWebP() {
+    if (webpSupportCache !== null) {
+        return webpSupportCache;
+    }
+    if (!isBrowserEnvironment()) {
+        webpSupportCache = false;
+        return false;
+    }
+    try {
+        const canvas = document.createElement('canvas');
+        webpSupportCache = canvas.toDataURL('image/webp').indexOf('data:image/webp') === 0;
+    }
+    catch (_a) {
+        webpSupportCache = false;
+    }
+    return webpSupportCache;
+}
+/**
+ * Load image from base64 string with timeout
+ */
+function loadImage(base64, timeout) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        const timer = setTimeout(() => {
+            reject(new Error(`Image load timeout after ${timeout}ms`));
+        }, timeout);
+        img.onload = () => {
+            clearTimeout(timer);
+            resolve(img);
+        };
+        img.onerror = () => {
+            clearTimeout(timer);
+            reject(new Error('Failed to load image'));
+        };
+        img.src = base64;
+    });
+}
+/**
+ * Calculate resized dimensions maintaining aspect ratio
+ */
+function calculateResizedDimensions(width, height, maxWidth, maxHeight) {
+    let newWidth = width;
+    let newHeight = height;
+    if (newWidth > maxWidth) {
+        newHeight = (newHeight * maxWidth) / newWidth;
+        newWidth = maxWidth;
+    }
+    if (newHeight > maxHeight) {
+        newWidth = (newWidth * maxHeight) / newHeight;
+        newHeight = maxHeight;
+    }
+    return { width: newWidth, height: newHeight };
+}
+/**
+ * Optimize and compress screenshot image
+ * Converts to WebP if supported, resizes if too large, then compresses
+ * @param base64 - Base64 encoded image (PNG or other format)
+ * @param config - Optional compression configuration
+ * @returns Optimized base64 image string
+ */
+async function compressImage(base64, config) {
+    var _a, _b, _c, _d;
+    try {
+        if (!isBrowserEnvironment()) {
+            return base64;
+        }
+        const maxWidth = (_a = config === null || config === void 0 ? void 0 : config.imageMaxWidth) !== null && _a !== void 0 ? _a : COMPRESSION_DEFAULTS.IMAGE_MAX_WIDTH;
+        const maxHeight = (_b = config === null || config === void 0 ? void 0 : config.imageMaxHeight) !== null && _b !== void 0 ? _b : COMPRESSION_DEFAULTS.IMAGE_MAX_HEIGHT;
+        const webpQuality = (_c = config === null || config === void 0 ? void 0 : config.webpQuality) !== null && _c !== void 0 ? _c : COMPRESSION_DEFAULTS.IMAGE_WEBP_QUALITY;
+        const jpegQuality = (_d = config === null || config === void 0 ? void 0 : config.jpegQuality) !== null && _d !== void 0 ? _d : COMPRESSION_DEFAULTS.IMAGE_JPEG_QUALITY;
+        const timeout = COMPRESSION_DEFAULTS.IMAGE_LOAD_TIMEOUT;
+        const img = await loadImage(base64, timeout);
+        const canvas = document.createElement('canvas');
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Failed to get 2D canvas context');
+        }
+        const { width, height } = calculateResizedDimensions(img.width, img.height, maxWidth, maxHeight);
+        canvas.width = width;
+        canvas.height = height;
+        ctx.drawImage(img, 0, 0, width, height);
+        if (supportsWebP()) {
+            return canvas.toDataURL('image/webp', webpQuality);
+        }
+        else {
+            return canvas.toDataURL('image/jpeg', jpegQuality);
+        }
+    }
+    catch (error) {
+        if ((config === null || config === void 0 ? void 0 : config.verbose) !== false) {
+            (0, logger_1.getLogger)().error('Image compression failed:', error);
+        }
+        return base64;
+    }
+}
+/**
+ * Calculate compression ratio for analytics
+ * @param originalSize - Original data size in bytes
+ * @param compressedSize - Compressed data size in bytes
+ * @returns Compression ratio as percentage (0-100)
+ */
+function getCompressionRatio(originalSize, compressedSize) {
+    if (originalSize <= 0) {
+        return 0;
+    }
+    return Math.round((1 - compressedSize / originalSize) * 100);
+}
+/**
+ * Estimate payload size before compression
+ * @param data - Data to estimate
+ * @returns Estimated size in bytes
+ */
+function estimateSize(data) {
+    const jsonString = dataToString(data);
+    return getTextEncoder().encode(jsonString).length;
+}
+/**
+ * Reset cached instances (useful for testing)
+ * @internal
+ */
+function resetCompressionCache() {
+    textEncoder = null;
+    textDecoder = null;
+    webpSupportCache = null;
+}

package/dist/core/offline-queue.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Offline queue for storing failed requests with localStorage persistence
+ */
+import { type Logger } from '../utils/logger';
+/**
+ * Storage interface for queue persistence
+ */
+export interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * LocalStorage implementation of StorageAdapter
+ */
+export declare class LocalStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface OfflineConfig {
+    /** Enable offline queue (default: false) */
+    enabled: boolean;
+    /** Maximum number of requests to queue (default: 10) */
+    maxQueueSize?: number;
+}
+export declare class OfflineQueue {
+    private config;
+    private logger;
+    private storage;
+    private requestCounter;
+    constructor(config: OfflineConfig, logger?: Logger, storage?: StorageAdapter);
+    /**
+     * Queue a request for offline retry
+     */
+    enqueue(endpoint: string, body: BodyInit, headers: Record<string, string>): void;
+    /**
+     * Process offline queue
+     */
+    process(retryableStatusCodes: number[]): Promise<void>;
+    /**
+     * Clear offline queue
+     */
+    clear(): void;
+    /**
+     * Get queue size
+     */
+    size(): number;
+    /**
+     * Serialize body to string format
+     */
+    private serializeBody;
+    /**
+     * Create a queued request object
+     */
+    private createQueuedRequest;
+    /**
+     * Validate that item size doesn't exceed localStorage limits
+     */
+    private validateItemSize;
+    private getQueue;
+    private saveQueue;
+    /**
+     * Check if error is a quota exceeded error (cross-browser compatible)
+     */
+    private isQuotaExceededError;
+    /**
+     * Clear oldest 50% of items and retry save
+     */
+    private clearOldestItems;
+    private generateRequestId;
+}
+/**
+ * Global function to clear offline queue
+ */
+export declare function clearOfflineQueue(): void;

package/dist/core/offline-queue.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Offline queue for storing failed requests with localStorage persistence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineQueue = exports.LocalStorageAdapter = void 0;
+exports.clearOfflineQueue = clearOfflineQueue;
+const logger_1 = require("../utils/logger");
+/**
+ * LocalStorage implementation of StorageAdapter
+ */
+class LocalStorageAdapter {
+    getItem(key) {
+        try {
+            if (typeof localStorage === 'undefined') {
+                return null;
+            }
+            return localStorage.getItem(key);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    setItem(key, value) {
+        if (typeof localStorage === 'undefined') {
+            return;
+        }
+        localStorage.setItem(key, value);
+    }
+    removeItem(key) {
+        try {
+            if (typeof localStorage === 'undefined') {
+                return;
+            }
+            localStorage.removeItem(key);
+        }
+        catch (_a) {
+            // Ignore errors
+        }
+    }
+}
+exports.LocalStorageAdapter = LocalStorageAdapter;
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const QUEUE_STORAGE_KEY = 'bugspotter_offline_queue';
+const QUEUE_EXPIRY_DAYS = 7;
+const MAX_RETRY_ATTEMPTS = 5;
+const MAX_ITEM_SIZE_BYTES = 100 * 1024; // 100KB per item
+const DEFAULT_OFFLINE_CONFIG = {
+    enabled: false,
+    maxQueueSize: 10,
+};
+// ============================================================================
+// OFFLINE QUEUE CLASS
+// ============================================================================
+class OfflineQueue {
+    constructor(config, logger, storage) {
+        this.requestCounter = 0;
+        this.config = Object.assign(Object.assign({}, DEFAULT_OFFLINE_CONFIG), config);
+        this.logger = logger || (0, logger_1.getLogger)();
+        this.storage = storage || new LocalStorageAdapter();
+    }
+    /**
+     * Queue a request for offline retry
+     */
+    enqueue(endpoint, body, headers) {
+        try {
+            const serializedBody = this.serializeBody(body);
+            if (!serializedBody || !this.validateItemSize(serializedBody)) {
+                return;
+            }
+            const queue = this.getQueue();
+            // Ensure space in queue
+            if (queue.length >= this.config.maxQueueSize) {
+                this.logger.warn(`Offline queue is full (${this.config.maxQueueSize}), removing oldest request`);
+                queue.shift();
+            }
+            queue.push(this.createQueuedRequest(endpoint, serializedBody, headers));
+            this.saveQueue(queue);
+            this.logger.log(`Request queued for offline retry (queue size: ${queue.length})`);
+        }
+        catch (error) {
+            this.logger.error('Failed to queue request for offline retry:', error);
+        }
+    }
+    /**
+     * Process offline queue
+     */
+    async process(retryableStatusCodes) {
+        const queue = this.getQueue();
+        if (queue.length === 0) {
+            return;
+        }
+        this.logger.log(`Processing offline queue (${queue.length} requests)`);
+        const successfulIds = [];
+        const failedRequests = [];
+        for (const request of queue) {
+            // Check if request has exceeded max retry attempts
+            if (request.attempts >= MAX_RETRY_ATTEMPTS) {
+                this.logger.warn(`Max retry attempts (${MAX_RETRY_ATTEMPTS}) reached for request (id: ${request.id}), removing`);
+                continue;
+            }
+            // Check if request has expired
+            const age = Date.now() - request.timestamp;
+            const maxAge = QUEUE_EXPIRY_DAYS * 24 * 60 * 60 * 1000;
+            if (age > maxAge) {
+                this.logger.warn(`Removing expired queued request (id: ${request.id})`);
+                continue;
+            }
+            try {
+                // Attempt to send
+                const response = await fetch(request.endpoint, {
+                    method: 'POST',
+                    headers: request.headers,
+                    body: request.body,
+                });
+                if (response.ok) {
+                    this.logger.log(`Successfully sent queued request (id: ${request.id})`);
+                    successfulIds.push(request.id);
+                }
+                else if (retryableStatusCodes.includes(response.status)) {
+                    // Keep in queue for next attempt
+                    request.attempts++;
+                    failedRequests.push(request);
+                    this.logger.warn(`Queued request failed with status ${response.status}, will retry later (id: ${request.id})`);
+                }
+                else {
+                    // Non-retryable error, remove from queue
+                    this.logger.warn(`Queued request failed with non-retryable status ${response.status}, removing (id: ${request.id})`);
+                }
+            }
+            catch (error) {
+                // Network error, keep in queue
+                request.attempts++;
+                failedRequests.push(request);
+                this.logger.warn(`Queued request failed with network error, will retry later (id: ${request.id}):`, error);
+            }
+        }
+        // Update queue (remove successful and expired, keep failed)
+        this.saveQueue(failedRequests);
+        if (successfulIds.length > 0 || failedRequests.length < queue.length) {
+            this.logger.log(`Offline queue processed: ${successfulIds.length} successful, ${failedRequests.length} remaining`);
+        }
+    }
+    /**
+     * Clear offline queue
+     */
+    clear() {
+        try {
+            this.storage.removeItem(QUEUE_STORAGE_KEY);
+        }
+        catch (_a) {
+            // Ignore storage errors
+        }
+    }
+    /**
+     * Get queue size
+     */
+    size() {
+        return this.getQueue().length;
+    }
+    // ============================================================================
+    // PRIVATE METHODS
+    // ============================================================================
+    /**
+     * Serialize body to string format
+     */
+    serializeBody(body) {
+        if (typeof body === 'string') {
+            return body;
+        }
+        if (body instanceof Blob) {
+            this.logger.warn('Cannot queue Blob for offline retry, skipping');
+            return null;
+        }
+        return JSON.stringify(body);
+    }
+    /**
+     * Create a queued request object
+     */
+    createQueuedRequest(endpoint, body, headers) {
+        return {
+            id: this.generateRequestId(),
+            endpoint,
+            body,
+            headers,
+            timestamp: Date.now(),
+            attempts: 0,
+        };
+    }
+    /**
+     * Validate that item size doesn't exceed localStorage limits
+     */
+    validateItemSize(body) {
+        const sizeInBytes = new Blob([body]).size;
+        if (sizeInBytes > MAX_ITEM_SIZE_BYTES) {
+            this.logger.warn(`Request body too large (${sizeInBytes} bytes), skipping queue`);
+            return false;
+        }
+        return true;
+    }
+    getQueue() {
+        try {
+            const stored = this.storage.getItem(QUEUE_STORAGE_KEY);
+            if (!stored) {
+                return [];
+            }
+            return JSON.parse(stored);
+        }
+        catch (error) {
+            // Log corrupted data and clear it to prevent repeated errors
+            this.logger.warn('Failed to parse offline queue data, clearing corrupted queue:', error);
+            this.clear();
+            return [];
+        }
+    }
+    saveQueue(queue) {
+        try {
+            this.storage.setItem(QUEUE_STORAGE_KEY, JSON.stringify(queue));
+        }
+        catch (error) {
+            // Handle quota exceeded error (check multiple properties for cross-browser compatibility)
+            if (this.isQuotaExceededError(error)) {
+                this.logger.error('localStorage quota exceeded, clearing oldest items');
+                this.clearOldestItems(queue);
+            }
+            else {
+                this.logger.error('Failed to save offline queue:', error);
+            }
+        }
+    }
+    /**
+     * Check if error is a quota exceeded error (cross-browser compatible)
+     */
+    isQuotaExceededError(error) {
+        if (!(error instanceof Error)) {
+            return false;
+        }
+        // Check error name (standard)
+        if (error.name === 'QuotaExceededError') {
+            return true;
+        }
+        // Check DOMException code (Safari, older browsers)
+        if ('code' in error && error.code === 22) {
+            return true;
+        }
+        // Check error message as fallback (Firefox, Chrome variants)
+        const message = error.message.toLowerCase();
+        return message.includes('quota') || message.includes('storage') || message.includes('exceeded');
+    }
+    /**
+     * Clear oldest 50% of items and retry save
+     */
+    clearOldestItems(queue) {
+        try {
+            const trimmedQueue = queue.slice(Math.floor(queue.length / 2));
+            this.storage.setItem(QUEUE_STORAGE_KEY, JSON.stringify(trimmedQueue));
+            this.logger.log(`Trimmed offline queue to ${trimmedQueue.length} items due to quota`);
+        }
+        catch (_a) {
+            // If still failing, clear everything
+            this.logger.error('Failed to save even after trimming, clearing queue');
+            this.clear();
+        }
+    }
+    generateRequestId() {
+        // Increment counter for additional entropy
+        this.requestCounter = (this.requestCounter + 1) % 10000;
+        // Use crypto.getRandomValues for better randomness (browser-safe fallback)
+        let randomPart;
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            const array = new Uint32Array(2);
+            crypto.getRandomValues(array);
+            randomPart = Array.from(array, (num) => {
+                return num.toString(36);
+            }).join('');
+        }
+        else {
+            // Fallback to Math.random for environments without crypto
+            randomPart =
+                Math.random().toString(36).substring(2, 9) + Math.random().toString(36).substring(2, 9);
+        }
+        return `req_${Date.now()}_${this.requestCounter}_${randomPart}`;
+    }
+}
+exports.OfflineQueue = OfflineQueue;
+/**
+ * Global function to clear offline queue
+ */
+function clearOfflineQueue() {
+    try {
+        const storage = new LocalStorageAdapter();
+        storage.removeItem(QUEUE_STORAGE_KEY);
+    }
+    catch (error) {
+        // Log error for debugging purposes
+        const logger = (0, logger_1.getLogger)();
+        logger.warn('Failed to clear offline queue:', error);
+    }
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Transport layer for bug report submission with flexible authentication,
+ * exponential backoff retry, and offline queue support
+ */
+import { type Logger } from '../utils/logger';
+import { type OfflineConfig } from './offline-queue';
+export declare class TransportError extends Error {
+    readonly endpoint: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, endpoint: string, cause?: Error | undefined);
+}
+export declare class TokenRefreshError extends TransportError {
+    constructor(endpoint: string, cause?: Error);
+}
+export type AuthConfig = {
+    type: 'api-key';
+    apiKey?: string;
+} | {
+    type: 'jwt';
+    token?: string;
+    onTokenExpired?: () => Promise<string>;
+} | {
+    type: 'bearer';
+    token?: string;
+    onTokenExpired?: () => Promise<string>;
+} | {
+    type: 'custom';
+    customHeader?: {
+        name: string;
+        value: string;
+    };
+} | {
+    type: 'none';
+};
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** HTTP status codes to retry on (default: [502, 503, 504, 429]) */
+    retryOn?: number[];
+}
+export interface TransportOptions {
+    /** Authentication configuration */
+    auth?: AuthConfig;
+    /** Optional logger for debugging */
+    logger?: Logger;
+    /** Enable retry on token expiration (default: true) */
+    enableRetry?: boolean;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Offline queue configuration */
+    offline?: OfflineConfig;
+}
+/**
+ * Get authentication headers based on configuration
+ * @param auth - Authentication configuration
+ * @returns HTTP headers for authentication
+ */
+export declare function getAuthHeaders(auth?: AuthConfig): Record<string, string>;
+/**
+ * Submit request with authentication, exponential backoff retry, and offline queue support
+ *
+ * @param endpoint - API endpoint URL
+ * @param body - Request body (must be serializable for retry)
+ * @param contentHeaders - Content-related headers (Content-Type, etc.)
+ * @param authOrOptions - Auth config or TransportOptions
+ * @returns Response from the server
+ */
+export declare function submitWithAuth(endpoint: string, body: BodyInit, contentHeaders: Record<string, string>, authOrOptions?: AuthConfig | TransportOptions): Promise<Response>;
+export { clearOfflineQueue, type OfflineConfig } from './offline-queue';