@bugspotter/sdk 0.1.0-alpha.1

package/dist/core/transport.js

@@ -0,0 +1,352 @@
+"use strict";
+/**
+ * Transport layer for bug report submission with flexible authentication,
+ * exponential backoff retry, and offline queue support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearOfflineQueue = exports.TokenRefreshError = exports.TransportError = void 0;
+exports.getAuthHeaders = getAuthHeaders;
+exports.submitWithAuth = submitWithAuth;
+const logger_1 = require("../utils/logger");
+const offline_queue_1 = require("./offline-queue");
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const TOKEN_REFRESH_STATUS = 401;
+const JITTER_PERCENTAGE = 0.1;
+const DEFAULT_ENABLE_RETRY = true;
+// ============================================================================
+// CUSTOM ERROR TYPES
+// ============================================================================
+class TransportError extends Error {
+    constructor(message, endpoint, cause) {
+        super(message);
+        this.endpoint = endpoint;
+        this.cause = cause;
+        this.name = 'TransportError';
+    }
+}
+exports.TransportError = TransportError;
+class TokenRefreshError extends TransportError {
+    constructor(endpoint, cause) {
+        super('Failed to refresh authentication token', endpoint, cause);
+        this.name = 'TokenRefreshError';
+    }
+}
+exports.TokenRefreshError = TokenRefreshError;
+// Default configurations
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    retryOn: [502, 503, 504, 429],
+};
+const DEFAULT_OFFLINE_CONFIG = {
+    enabled: false,
+    maxQueueSize: 10,
+};
+const authStrategies = {
+    'api-key': (config) => {
+        const apiKey = config.apiKey;
+        return apiKey ? { 'X-API-Key': apiKey } : {};
+    },
+    jwt: (config) => {
+        const token = config.token;
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    },
+    bearer: (config) => {
+        const token = config.token;
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    },
+    custom: (config) => {
+        const customHeader = config.customHeader;
+        if (!customHeader) {
+            return {};
+        }
+        const { name, value } = customHeader;
+        return name && value ? { [name]: value } : {};
+    },
+    none: () => {
+        return {};
+    },
+};
+// ============================================================================
+// RETRY HANDLER - Exponential Backoff Logic
+// ============================================================================
+class RetryHandler {
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * Execute operation with exponential backoff retry
+     */
+    async executeWithRetry(operation, shouldRetryStatus) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                const response = await operation();
+                // Check if we should retry based on status code
+                if (shouldRetryStatus(response.status) && attempt < this.config.maxRetries) {
+                    const delay = this.calculateDelay(attempt, response);
+                    this.logger.warn(`Request failed with status ${response.status}, retrying in ${delay}ms (attempt ${attempt + 1}/${this.config.maxRetries})`);
+                    await sleep(delay);
+                    continue;
+                }
+                // Success or non-retryable status
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                // Retry on network errors
+                if (attempt < this.config.maxRetries) {
+                    const delay = this.calculateDelay(attempt);
+                    this.logger.warn(`Network error, retrying in ${delay}ms (attempt ${attempt + 1}/${this.config.maxRetries}):`, error);
+                    await sleep(delay);
+                    continue;
+                }
+            }
+        }
+        // All retries exhausted
+        throw lastError || new Error('Request failed after all retry attempts');
+    }
+    /**
+     * Calculate retry delay with exponential backoff and jitter
+     */
+    calculateDelay(attempt, response) {
+        var _a, _b;
+        // Check for Retry-After header
+        if ((_b = (_a = response === null || response === void 0 ? void 0 : response.headers) === null || _a === void 0 ? void 0 : _a.has) === null || _b === void 0 ? void 0 : _b.call(_a, 'Retry-After')) {
+            const retryAfter = response.headers.get('Retry-After');
+            const retryAfterSeconds = parseInt(retryAfter, 10);
+            if (!isNaN(retryAfterSeconds)) {
+                return Math.min(retryAfterSeconds * 1000, this.config.maxDelay);
+            }
+        }
+        // Exponential backoff: baseDelay * 2^attempt
+        const exponentialDelay = this.config.baseDelay * Math.pow(2, attempt);
+        // Add jitter: ±10% randomization
+        const jitter = exponentialDelay * JITTER_PERCENTAGE * (Math.random() * 2 - 1);
+        const delayWithJitter = exponentialDelay + jitter;
+        // Cap at maxDelay
+        return Math.min(delayWithJitter, this.config.maxDelay);
+    }
+}
+/**
+ * Type guard to check if parameter is TransportOptions
+ *
+ * Strategy: Check for properties that ONLY exist in TransportOptions, not in AuthConfig.
+ * AuthConfig has: type, apiKey?, token?, onTokenExpired?, customHeader?
+ * TransportOptions has: auth?, logger?, enableRetry?, retry?, offline?
+ *
+ * Key distinction: AuthConfig always has 'type' property, TransportOptions never does.
+ */
+function isTransportOptions(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const record = obj;
+    // If it has 'type' property, it's an AuthConfig, not TransportOptions
+    if ('type' in record) {
+        return false;
+    }
+    // Key insight: If object has TransportOptions-specific keys (even if undefined),
+    // it's likely TransportOptions since AuthConfig never has these keys
+    const hasTransportOptionsKeys = 'auth' in record ||
+        'retry' in record ||
+        'offline' in record ||
+        'logger' in record ||
+        'enableRetry' in record;
+    // Return true if it has any TransportOptions-specific keys
+    return hasTransportOptionsKeys;
+}
+/**
+ * Parse transport parameters, supporting both legacy and new API signatures
+ */
+function parseTransportParams(authOrOptions) {
+    var _a;
+    if (isTransportOptions(authOrOptions)) {
+        // Type guard ensures authOrOptions is TransportOptions
+        return {
+            auth: authOrOptions.auth,
+            logger: authOrOptions.logger || (0, logger_1.getLogger)(),
+            enableRetry: (_a = authOrOptions.enableRetry) !== null && _a !== void 0 ? _a : DEFAULT_ENABLE_RETRY,
+            retryConfig: Object.assign(Object.assign({}, DEFAULT_RETRY_CONFIG), authOrOptions.retry),
+            offlineConfig: Object.assign(Object.assign({}, DEFAULT_OFFLINE_CONFIG), authOrOptions.offline),
+        };
+    }
+    return {
+        auth: authOrOptions,
+        logger: (0, logger_1.getLogger)(),
+        enableRetry: DEFAULT_ENABLE_RETRY,
+        retryConfig: DEFAULT_RETRY_CONFIG,
+        offlineConfig: DEFAULT_OFFLINE_CONFIG,
+    };
+}
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Process offline queue in background
+ */
+async function processQueueInBackground(offlineConfig, retryConfig, logger) {
+    if (!offlineConfig.enabled) {
+        return;
+    }
+    const queue = new offline_queue_1.OfflineQueue(offlineConfig, logger);
+    queue.process(retryConfig.retryOn).catch((error) => {
+        logger.warn('Failed to process offline queue:', error);
+    });
+}
+/**
+ * Handle offline failure by queueing request
+ */
+async function handleOfflineFailure(error, endpoint, body, contentHeaders, auth, offlineConfig, logger) {
+    if (!offlineConfig.enabled || !isNetworkError(error)) {
+        return;
+    }
+    logger.warn('Network error detected, queueing request for offline retry');
+    const queue = new offline_queue_1.OfflineQueue(offlineConfig, logger);
+    const authHeaders = getAuthHeaders(auth);
+    await queue.enqueue(endpoint, body, Object.assign(Object.assign({}, contentHeaders), authHeaders));
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Get authentication headers based on configuration
+ * @param auth - Authentication configuration
+ * @returns HTTP headers for authentication
+ */
+function getAuthHeaders(auth) {
+    // No auth
+    if (!auth) {
+        return {};
+    }
+    // Apply strategy
+    const strategy = authStrategies[auth.type];
+    return strategy ? strategy(auth) : {};
+}
+/**
+ * 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
+ */
+async function submitWithAuth(endpoint, body, contentHeaders, authOrOptions) {
+    // Parse options (support both old signature and new options-based API)
+    const { auth, logger, enableRetry, retryConfig, offlineConfig } = parseTransportParams(authOrOptions);
+    // Process offline queue on each request (run in background without awaiting)
+    processQueueInBackground(offlineConfig, retryConfig, logger);
+    try {
+        // Send with retry logic
+        const response = await sendWithRetry(endpoint, body, contentHeaders, auth, retryConfig, logger, enableRetry);
+        return response;
+    }
+    catch (error) {
+        // Queue for offline retry if enabled
+        await handleOfflineFailure(error, endpoint, body, contentHeaders, auth, offlineConfig, logger);
+        throw error;
+    }
+}
+/**
+ * Check if auth config supports token refresh
+ */
+function shouldRetryWithRefresh(auth) {
+    return (typeof auth === 'object' &&
+        (auth.type === 'jwt' || auth.type === 'bearer') &&
+        typeof auth.onTokenExpired === 'function');
+}
+/**
+ * Make HTTP request with auth headers
+ */
+async function makeRequest(endpoint, body, contentHeaders, auth) {
+    const authHeaders = getAuthHeaders(auth);
+    const headers = Object.assign(Object.assign({}, contentHeaders), authHeaders);
+    return fetch(endpoint, {
+        method: 'POST',
+        headers,
+        body,
+    });
+}
+/**
+ * Send request with exponential backoff retry
+ */
+async function sendWithRetry(endpoint, body, contentHeaders, auth, retryConfig, logger, enableTokenRetry) {
+    const retryHandler = new RetryHandler(retryConfig, logger);
+    let hasAttemptedRefresh = false;
+    // Use retry handler with token refresh support
+    return retryHandler.executeWithRetry(async () => {
+        const response = await makeRequest(endpoint, body, contentHeaders, auth);
+        // Check for 401 and retry with token refresh if applicable (only once)
+        if (response.status === TOKEN_REFRESH_STATUS &&
+            enableTokenRetry &&
+            !hasAttemptedRefresh &&
+            shouldRetryWithRefresh(auth)) {
+            hasAttemptedRefresh = true;
+            const refreshedResponse = await retryWithTokenRefresh(endpoint, body, contentHeaders, auth, logger);
+            return refreshedResponse;
+        }
+        return response;
+    }, (status) => {
+        return retryConfig.retryOn.includes(status);
+    });
+}
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if error is a network error (more specific to avoid false positives)
+ */
+function isNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    // Check for specific network error patterns
+    return (
+    // Standard fetch network errors
+    message.includes('failed to fetch') ||
+        message.includes('network request failed') ||
+        message.includes('networkerror') ||
+        // Connection issues
+        message.includes('network error') ||
+        message.includes('connection') ||
+        // Timeout errors
+        message.includes('timeout') ||
+        // Standard error names
+        error.name === 'NetworkError' ||
+        error.name === 'AbortError' ||
+        // TypeError only if it mentions fetch or network
+        (error.name === 'TypeError' && (message.includes('fetch') || message.includes('network'))));
+}
+/**
+ * Retry request with refreshed token
+ */
+async function retryWithTokenRefresh(endpoint, body, contentHeaders, auth, logger) {
+    try {
+        logger.warn('Token expired, attempting refresh...');
+        // Get new token
+        const newToken = await auth.onTokenExpired();
+        // Create updated auth config
+        const refreshedAuth = Object.assign(Object.assign({}, auth), { token: newToken });
+        // Retry request
+        const response = await makeRequest(endpoint, body, contentHeaders, refreshedAuth);
+        logger.log('Request retried with refreshed token');
+        return response;
+    }
+    catch (error) {
+        logger.error('Token refresh failed:', error);
+        // Return original 401 - caller should handle
+        return new Response(null, { status: TOKEN_REFRESH_STATUS, statusText: 'Unauthorized' });
+    }
+}
+// Re-export offline queue utilities
+var offline_queue_2 = require("./offline-queue");
+Object.defineProperty(exports, "clearOfflineQueue", { enumerable: true, get: function () { return offline_queue_2.clearOfflineQueue; } });

package/dist/core/upload-helpers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Upload Helpers
+ * Utilities for preparing data for presigned URL uploads
+ */
+/**
+ * Compress replay events using CompressionStream API (browser native)
+ * Falls back to no compression if API not available
+ * @param events - Session replay events array
+ * @returns Compressed Blob (gzip)
+ */
+export declare function compressReplayEvents(events: unknown[]): Promise<Blob>;
+/**
+ * Convert screenshot canvas to Blob
+ * @param canvas - HTML Canvas element with screenshot
+ * @param quality - JPEG quality (0-1), default 0.9
+ * @returns Screenshot Blob
+ */
+export declare function canvasToBlob(canvas: HTMLCanvasElement, quality?: number): Promise<Blob>;
+/**
+ * Estimate compressed size of replay events
+ * Uses rough heuristic: gzip typically achieves 80-90% compression for JSON
+ * @param events - Replay events array
+ * @returns Estimated compressed size in bytes
+ */
+export declare function estimateCompressedReplaySize(events: unknown[]): number;
+/**
+ * Check if file size is within upload limits
+ * @param blob - File or Blob to check
+ * @param maxSizeMB - Maximum size in megabytes
+ * @returns True if within limit
+ */
+export declare function isWithinSizeLimit(blob: Blob, maxSizeMB: number): boolean;

package/dist/core/upload-helpers.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Upload Helpers
+ * Utilities for preparing data for presigned URL uploads
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressReplayEvents = compressReplayEvents;
+exports.canvasToBlob = canvasToBlob;
+exports.estimateCompressedReplaySize = estimateCompressedReplaySize;
+exports.isWithinSizeLimit = isWithinSizeLimit;
+/**
+ * Compress replay events using CompressionStream API (browser native)
+ * Falls back to no compression if API not available
+ * @param events - Session replay events array
+ * @returns Compressed Blob (gzip)
+ */
+async function compressReplayEvents(events) {
+    // Convert events to JSON string
+    const jsonString = JSON.stringify(events);
+    const textEncoder = new TextEncoder();
+    const data = textEncoder.encode(jsonString);
+    // Check if CompressionStream is supported (Chrome 80+, Firefox 113+, Safari 16.4+)
+    if (typeof CompressionStream === 'undefined') {
+        console.warn('CompressionStream not supported, uploading uncompressed replay data');
+        return new Blob([data], { type: 'application/json' });
+    }
+    try {
+        // Use modern streaming API: Blob → ReadableStream → CompressionStream → Response → Blob
+        const blob = new Blob([data]);
+        const compressedStream = blob.stream().pipeThrough(new CompressionStream('gzip'));
+        return await new Response(compressedStream, {
+            headers: { 'Content-Type': 'application/gzip' },
+        }).blob();
+    }
+    catch (error) {
+        console.error('Compression failed, uploading uncompressed:', error);
+        return new Blob([data], { type: 'application/json' });
+    }
+}
+/**
+ * Convert screenshot canvas to Blob
+ * @param canvas - HTML Canvas element with screenshot
+ * @param quality - JPEG quality (0-1), default 0.9
+ * @returns Screenshot Blob
+ */
+async function canvasToBlob(canvas, quality = 0.9) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (blob) {
+                resolve(blob);
+            }
+            else {
+                reject(new Error('Failed to convert canvas to Blob'));
+            }
+        }, 'image/png', quality);
+    });
+}
+/**
+ * Estimate compressed size of replay events
+ * Uses rough heuristic: gzip typically achieves 80-90% compression for JSON
+ * @param events - Replay events array
+ * @returns Estimated compressed size in bytes
+ */
+function estimateCompressedReplaySize(events) {
+    const jsonString = JSON.stringify(events);
+    const uncompressedSize = new TextEncoder().encode(jsonString).length;
+    // Assume 85% compression ratio (conservative estimate)
+    return Math.round(uncompressedSize * 0.15);
+}
+/**
+ * Check if file size is within upload limits
+ * @param blob - File or Blob to check
+ * @param maxSizeMB - Maximum size in megabytes
+ * @returns True if within limit
+ */
+function isWithinSizeLimit(blob, maxSizeMB) {
+    const maxBytes = maxSizeMB * 1024 * 1024;
+    return blob.size <= maxBytes;
+}

package/dist/core/uploader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DirectUploader
+ * Handles direct client-to-storage uploads using presigned URLs
+ */
+export interface DirectUploadConfig {
+    apiEndpoint: string;
+    apiKey: string;
+    projectId: string;
+    bugId: string;
+}
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+    percentage: number;
+}
+export type UploadProgressCallback = (progress: UploadProgress) => void;
+export interface UploadResult {
+    success: boolean;
+    storageKey?: string;
+    error?: string;
+}
+/**
+ * DirectUploader handles uploading files directly to storage using presigned URLs
+ * This bypasses the API server for file data, reducing memory usage and improving performance
+ */
+export declare class DirectUploader {
+    private readonly config;
+    constructor(config: DirectUploadConfig);
+    /**
+     * Upload a screenshot file directly to storage
+     * @param file - Screenshot file or Blob
+     * @param onProgress - Optional progress callback
+     * @returns Upload result with storage key
+     */
+    uploadScreenshot(file: File | Blob, onProgress?: UploadProgressCallback): Promise<UploadResult>;
+    /**
+     * Upload a compressed session replay directly to storage
+     * @param compressedData - Gzip-compressed replay data
+     * @param onProgress - Optional progress callback
+     * @returns Upload result with storage key
+     */
+    uploadReplay(compressedData: Blob, onProgress?: UploadProgressCallback): Promise<UploadResult>;
+    /**
+     * Upload an attachment file directly to storage
+     * @param file - Attachment file
+     * @param onProgress - Optional progress callback
+     * @returns Upload result with storage key
+     */
+    uploadAttachment(file: File, onProgress?: UploadProgressCallback): Promise<UploadResult>;
+    /**
+     * Generic file upload method
+     * 1. Request presigned URL from API
+     * 2. Upload file directly to storage using presigned URL
+     * 3. Confirm upload with API
+     */
+    private uploadFile;
+    /**
+     * Request a presigned URL from the API
+     */
+    private requestPresignedUrl;
+    /**
+     * Upload file to storage using presigned URL
+     * Uses XMLHttpRequest for progress tracking
+     */
+    private uploadToStorage;
+    /**
+     * Confirm successful upload with the API
+     */
+    private confirmUpload;
+}