@tracelog/lib 0.7.2 → 0.8.0

package/dist/cjs/constants/config.constants.d.ts

@@ -7,7 +7,7 @@ export declare const DUPLICATE_EVENT_THRESHOLD_MS = 500;
 export declare const EVENT_SENT_INTERVAL_MS = 10000;
 export declare const SCROLL_DEBOUNCE_TIME_MS = 250;
 export declare const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
-export declare const EVENT_EXPIRY_HOURS = 24;
+export declare const EVENT_EXPIRY_HOURS = 2;
 export declare const EVENT_PERSISTENCE_MAX_AGE_MS: number;
 export declare const MAX_EVENTS_QUEUE_LENGTH = 100;
 export declare const MAX_RETRIES = 3;

package/dist/cjs/constants/config.constants.js

@@ -16,8 +16,8 @@ exports.EVENT_SENT_INTERVAL_MS = 10000; // 10 seconds
 exports.SCROLL_DEBOUNCE_TIME_MS = 250;
 exports.DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
 // Event expiry
-exports.EVENT_EXPIRY_HOURS = 24;
-exports.EVENT_PERSISTENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+exports.EVENT_EXPIRY_HOURS = 2;
+exports.EVENT_PERSISTENCE_MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
 // ============================================================================
 // LIMITS & RETRIES
 // ============================================================================

package/dist/cjs/constants/error.constants.d.ts

@@ -32,3 +32,9 @@ export declare const MAX_TRACKED_ERRORS_HARD_LIMIT: number;
  * Controls what percentage of errors are actually reported
  */
 export declare const DEFAULT_ERROR_SAMPLING_RATE = 0.1;
+/**
+ * Time window for throttling permanent error logs in milliseconds
+ * Same error status codes are logged at most once per this window
+ * Prevents console spam when backend repeatedly returns 4xx errors
+ */
+export declare const PERMANENT_ERROR_LOG_THROTTLE_MS = 60000;

package/dist/cjs/constants/error.constants.js

@@ -4,7 +4,7 @@
  * Centralizes patterns and limits for error tracking and data protection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ERROR_SAMPLING_RATE = exports.MAX_TRACKED_ERRORS_HARD_LIMIT = exports.MAX_TRACKED_ERRORS = exports.ERROR_SUPPRESSION_WINDOW_MS = exports.MAX_ERROR_MESSAGE_LENGTH = exports.PII_PATTERNS = void 0;
+exports.PERMANENT_ERROR_LOG_THROTTLE_MS = exports.DEFAULT_ERROR_SAMPLING_RATE = exports.MAX_TRACKED_ERRORS_HARD_LIMIT = exports.MAX_TRACKED_ERRORS = exports.ERROR_SUPPRESSION_WINDOW_MS = exports.MAX_ERROR_MESSAGE_LENGTH = exports.PII_PATTERNS = void 0;
 // ============================================================================
 // PII SANITIZATION PATTERNS
 // ============================================================================
@@ -59,3 +59,12 @@ exports.MAX_TRACKED_ERRORS_HARD_LIMIT = exports.MAX_TRACKED_ERRORS * 2;
  * Controls what percentage of errors are actually reported
  */
 exports.DEFAULT_ERROR_SAMPLING_RATE = 0.1; // 10% of errors
+// ============================================================================
+// PERMANENT ERROR LOGGING
+// ============================================================================
+/**
+ * Time window for throttling permanent error logs in milliseconds
+ * Same error status codes are logged at most once per this window
+ * Prevents console spam when backend repeatedly returns 4xx errors
+ */
+exports.PERMANENT_ERROR_LOG_THROTTLE_MS = 60000; // 1 minute

package/dist/cjs/managers/sender.manager.d.ts

@@ -10,6 +10,7 @@ export declare class SenderManager extends StateManager {
     private retryTimeoutId;
     private retryCount;
     private isRetrying;
+    private lastPermanentErrorLog;
     constructor(storeManager: StorageManager);
     private getQueueStorageKey;
     sendEventsQueueSync(body: BaseEventsQueueDto): boolean;
@@ -33,5 +34,6 @@ export declare class SenderManager extends StateManager {
     private simulateSuccessfulSend;
     private isSendBeaconAvailable;
     private clearRetryTimeout;
+    private logPermanentError;
 }
 export {};

package/dist/cjs/managers/sender.manager.js

@@ -11,6 +11,7 @@ class SenderManager extends state_manager_1.StateManager {
         this.retryTimeoutId = null;
         this.retryCount = 0;
         this.isRetrying = false;
+        this.lastPermanentErrorLog = null;
         this.storeManager = storeManager;
     }
     getQueueStorageKey() {
@@ -42,17 +43,31 @@ class SenderManager extends state_manager_1.StateManager {
                 (0, utils_1.log)('warn', 'Failed to persist events, attempting immediate send');
             }
         }
-        const success = await this.send(body);
-        if (success) {
-            this.clearPersistedEvents();
-            this.resetRetryState();
-            callbacks?.onSuccess?.(body.events.length, body.events, body);
+        try {
+            const success = await this.send(body);
+            if (success) {
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onSuccess?.(body.events.length, body.events, body);
+            }
+            else {
+                this.scheduleRetry(body, callbacks);
+                callbacks?.onFailure?.();
+            }
+            return success;
         }
-        else {
-            this.scheduleRetry(body, callbacks);
-            callbacks?.onFailure?.();
+        catch (error) {
+            // Permanent errors should not be retried
+            if (error instanceof types_1.PermanentError) {
+                this.logPermanentError('Permanent error, not retrying', error);
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onFailure?.();
+                return false;
+            }
+            // Re-throw unexpected errors
+            throw error;
         }
-        return success;
     }
     async recoverPersistedEvents(callbacks) {
         try {
@@ -74,6 +89,14 @@ class SenderManager extends state_manager_1.StateManager {
             }
         }
         catch (error) {
+            // Permanent errors should clear persisted events immediately
+            if (error instanceof types_1.PermanentError) {
+                this.logPermanentError('Permanent error during recovery, clearing persisted events', error);
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onFailure?.();
+                return;
+            }
             (0, utils_1.log)('error', 'Failed to recover persisted events', { error });
             this.clearPersistedEvents();
         }
@@ -105,6 +128,10 @@ class SenderManager extends state_manager_1.StateManager {
             return response.ok;
         }
         catch (error) {
+            // Re-throw PermanentError to be caught by caller
+            if (error instanceof types_1.PermanentError) {
+                throw error;
+            }
             (0, utils_1.log)('error', 'Send request failed', {
                 error,
                 data: {
@@ -130,6 +157,13 @@ class SenderManager extends state_manager_1.StateManager {
                 },
             });
             if (!response.ok) {
+                // 4xx errors are permanent client errors - don't retry
+                const isPermanentError = response.status >= 400 && response.status < 500;
+                if (isPermanentError) {
+                    // Note: Logging handled by caller with throttling to prevent spam
+                    throw new types_1.PermanentError(`HTTP ${response.status}: ${response.statusText}`, response.status);
+                }
+                // 5xx or other errors - retry
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
             return response;
@@ -265,6 +299,25 @@ class SenderManager extends state_manager_1.StateManager {
                     this.scheduleRetry(body, originalCallbacks);
                 }
             }
+            catch (error) {
+                // If it's a permanent error, don't retry
+                if (error instanceof types_1.PermanentError) {
+                    this.logPermanentError('Permanent error detected during retry, giving up', error);
+                    this.clearPersistedEvents();
+                    this.resetRetryState();
+                    originalCallbacks?.onFailure?.();
+                    return;
+                }
+                // For other errors, continue normal retry flow
+                if (this.retryCount >= constants_1.MAX_RETRIES) {
+                    this.clearPersistedEvents();
+                    this.resetRetryState();
+                    originalCallbacks?.onFailure?.();
+                }
+                else {
+                    this.scheduleRetry(body, originalCallbacks);
+                }
+            }
             finally {
                 this.isRetrying = false;
             }
@@ -287,5 +340,17 @@ class SenderManager extends state_manager_1.StateManager {
             this.retryTimeoutId = null;
         }
     }
+    logPermanentError(context, error) {
+        const now = Date.now();
+        const shouldLog = !this.lastPermanentErrorLog ||
+            this.lastPermanentErrorLog.statusCode !== error.statusCode ||
+            now - this.lastPermanentErrorLog.timestamp >= constants_1.PERMANENT_ERROR_LOG_THROTTLE_MS;
+        if (shouldLog) {
+            (0, utils_1.log)('error', context, {
+                data: { status: error.statusCode, message: error.message },
+            });
+            this.lastPermanentErrorLog = { statusCode: error.statusCode, timestamp: now };
+        }
+    }
 }
 exports.SenderManager = SenderManager;

package/dist/cjs/types/error.types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Custom error types for TraceLog
+ */
+/**
+ * Represents a permanent HTTP error (4xx) that should not be retried
+ * Examples: 400 Bad Request, 403 Forbidden, 404 Not Found
+ */
+export declare class PermanentError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}

package/dist/cjs/types/error.types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Custom error types for TraceLog
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermanentError = void 0;
+/**
+ * Represents a permanent HTTP error (4xx) that should not be retried
+ * Examples: 400 Bad Request, 403 Forbidden, 404 Not Found
+ */
+class PermanentError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'PermanentError';
+        // Maintain proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PermanentError);
+        }
+    }
+}
+exports.PermanentError = PermanentError;

package/dist/cjs/types/index.d.ts

@@ -2,6 +2,7 @@ export * from './common.types';
 export * from './config.types';
 export * from './device.types';
 export * from './emitter.types';
+export * from './error.types';
 export * from './event.types';
 export * from './log.types';
 export * from './mode.types';

package/dist/cjs/types/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./common.types"), exports);
 __exportStar(require("./config.types"), exports);
 __exportStar(require("./device.types"), exports);
 __exportStar(require("./emitter.types"), exports);
+__exportStar(require("./error.types"), exports);
 __exportStar(require("./event.types"), exports);
 __exportStar(require("./log.types"), exports);
 __exportStar(require("./mode.types"), exports);

package/dist/esm/constants/config.constants.d.ts

@@ -7,7 +7,7 @@ export declare const DUPLICATE_EVENT_THRESHOLD_MS = 500;
 export declare const EVENT_SENT_INTERVAL_MS = 10000;
 export declare const SCROLL_DEBOUNCE_TIME_MS = 250;
 export declare const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
-export declare const EVENT_EXPIRY_HOURS = 24;
+export declare const EVENT_EXPIRY_HOURS = 2;
 export declare const EVENT_PERSISTENCE_MAX_AGE_MS: number;
 export declare const MAX_EVENTS_QUEUE_LENGTH = 100;
 export declare const MAX_RETRIES = 3;

package/dist/esm/constants/config.constants.js

@@ -12,8 +12,8 @@ export const EVENT_SENT_INTERVAL_MS = 10000; // 10 seconds
 export const SCROLL_DEBOUNCE_TIME_MS = 250;
 export const DEFAULT_VISIBILITY_TIMEOUT_MS = 2000;
 // Event expiry
-export const EVENT_EXPIRY_HOURS = 24;
-export const EVENT_PERSISTENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const EVENT_EXPIRY_HOURS = 2;
+export const EVENT_PERSISTENCE_MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
 // ============================================================================
 // LIMITS & RETRIES
 // ============================================================================

package/dist/esm/constants/error.constants.d.ts

@@ -32,3 +32,9 @@ export declare const MAX_TRACKED_ERRORS_HARD_LIMIT: number;
  * Controls what percentage of errors are actually reported
  */
 export declare const DEFAULT_ERROR_SAMPLING_RATE = 0.1;
+/**
+ * Time window for throttling permanent error logs in milliseconds
+ * Same error status codes are logged at most once per this window
+ * Prevents console spam when backend repeatedly returns 4xx errors
+ */
+export declare const PERMANENT_ERROR_LOG_THROTTLE_MS = 60000;

package/dist/esm/constants/error.constants.js

@@ -56,3 +56,12 @@ export const MAX_TRACKED_ERRORS_HARD_LIMIT = MAX_TRACKED_ERRORS * 2;
  * Controls what percentage of errors are actually reported
  */
 export const DEFAULT_ERROR_SAMPLING_RATE = 0.1; // 10% of errors
+// ============================================================================
+// PERMANENT ERROR LOGGING
+// ============================================================================
+/**
+ * Time window for throttling permanent error logs in milliseconds
+ * Same error status codes are logged at most once per this window
+ * Prevents console spam when backend repeatedly returns 4xx errors
+ */
+export const PERMANENT_ERROR_LOG_THROTTLE_MS = 60000; // 1 minute

package/dist/esm/managers/sender.manager.d.ts

@@ -10,6 +10,7 @@ export declare class SenderManager extends StateManager {
     private retryTimeoutId;
     private retryCount;
     private isRetrying;
+    private lastPermanentErrorLog;
     constructor(storeManager: StorageManager);
     private getQueueStorageKey;
     sendEventsQueueSync(body: BaseEventsQueueDto): boolean;
@@ -33,5 +34,6 @@ export declare class SenderManager extends StateManager {
     private simulateSuccessfulSend;
     private isSendBeaconAvailable;
     private clearRetryTimeout;
+    private logPermanentError;
 }
 export {};

package/dist/esm/managers/sender.manager.js

@@ -1,5 +1,5 @@
-import { QUEUE_KEY, EVENT_EXPIRY_HOURS, MAX_RETRIES, RETRY_DELAY_MS, REQUEST_TIMEOUT_MS } from '../constants';
-import { SpecialApiUrl } from '../types';
+import { QUEUE_KEY, EVENT_EXPIRY_HOURS, MAX_RETRIES, RETRY_DELAY_MS, REQUEST_TIMEOUT_MS, PERMANENT_ERROR_LOG_THROTTLE_MS, } from '../constants';
+import { SpecialApiUrl, PermanentError } from '../types';
 import { log } from '../utils';
 import { StateManager } from './state.manager';
 export class SenderManager extends StateManager {
@@ -8,6 +8,7 @@ export class SenderManager extends StateManager {
         this.retryTimeoutId = null;
         this.retryCount = 0;
         this.isRetrying = false;
+        this.lastPermanentErrorLog = null;
         this.storeManager = storeManager;
     }
     getQueueStorageKey() {
@@ -39,17 +40,31 @@ export class SenderManager extends StateManager {
                 log('warn', 'Failed to persist events, attempting immediate send');
             }
         }
-        const success = await this.send(body);
-        if (success) {
-            this.clearPersistedEvents();
-            this.resetRetryState();
-            callbacks?.onSuccess?.(body.events.length, body.events, body);
+        try {
+            const success = await this.send(body);
+            if (success) {
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onSuccess?.(body.events.length, body.events, body);
+            }
+            else {
+                this.scheduleRetry(body, callbacks);
+                callbacks?.onFailure?.();
+            }
+            return success;
         }
-        else {
-            this.scheduleRetry(body, callbacks);
-            callbacks?.onFailure?.();
+        catch (error) {
+            // Permanent errors should not be retried
+            if (error instanceof PermanentError) {
+                this.logPermanentError('Permanent error, not retrying', error);
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onFailure?.();
+                return false;
+            }
+            // Re-throw unexpected errors
+            throw error;
         }
-        return success;
     }
     async recoverPersistedEvents(callbacks) {
         try {
@@ -71,6 +86,14 @@ export class SenderManager extends StateManager {
             }
         }
         catch (error) {
+            // Permanent errors should clear persisted events immediately
+            if (error instanceof PermanentError) {
+                this.logPermanentError('Permanent error during recovery, clearing persisted events', error);
+                this.clearPersistedEvents();
+                this.resetRetryState();
+                callbacks?.onFailure?.();
+                return;
+            }
             log('error', 'Failed to recover persisted events', { error });
             this.clearPersistedEvents();
         }
@@ -102,6 +125,10 @@ export class SenderManager extends StateManager {
             return response.ok;
         }
         catch (error) {
+            // Re-throw PermanentError to be caught by caller
+            if (error instanceof PermanentError) {
+                throw error;
+            }
             log('error', 'Send request failed', {
                 error,
                 data: {
@@ -127,6 +154,13 @@ export class SenderManager extends StateManager {
                 },
             });
             if (!response.ok) {
+                // 4xx errors are permanent client errors - don't retry
+                const isPermanentError = response.status >= 400 && response.status < 500;
+                if (isPermanentError) {
+                    // Note: Logging handled by caller with throttling to prevent spam
+                    throw new PermanentError(`HTTP ${response.status}: ${response.statusText}`, response.status);
+                }
+                // 5xx or other errors - retry
                 throw new Error(`HTTP ${response.status}: ${response.statusText}`);
             }
             return response;
@@ -262,6 +296,25 @@ export class SenderManager extends StateManager {
                     this.scheduleRetry(body, originalCallbacks);
                 }
             }
+            catch (error) {
+                // If it's a permanent error, don't retry
+                if (error instanceof PermanentError) {
+                    this.logPermanentError('Permanent error detected during retry, giving up', error);
+                    this.clearPersistedEvents();
+                    this.resetRetryState();
+                    originalCallbacks?.onFailure?.();
+                    return;
+                }
+                // For other errors, continue normal retry flow
+                if (this.retryCount >= MAX_RETRIES) {
+                    this.clearPersistedEvents();
+                    this.resetRetryState();
+                    originalCallbacks?.onFailure?.();
+                }
+                else {
+                    this.scheduleRetry(body, originalCallbacks);
+                }
+            }
             finally {
                 this.isRetrying = false;
             }
@@ -284,4 +337,16 @@ export class SenderManager extends StateManager {
             this.retryTimeoutId = null;
         }
     }
+    logPermanentError(context, error) {
+        const now = Date.now();
+        const shouldLog = !this.lastPermanentErrorLog ||
+            this.lastPermanentErrorLog.statusCode !== error.statusCode ||
+            now - this.lastPermanentErrorLog.timestamp >= PERMANENT_ERROR_LOG_THROTTLE_MS;
+        if (shouldLog) {
+            log('error', context, {
+                data: { status: error.statusCode, message: error.message },
+            });
+            this.lastPermanentErrorLog = { statusCode: error.statusCode, timestamp: now };
+        }
+    }
 }

package/dist/esm/types/error.types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Custom error types for TraceLog
+ */
+/**
+ * Represents a permanent HTTP error (4xx) that should not be retried
+ * Examples: 400 Bad Request, 403 Forbidden, 404 Not Found
+ */
+export declare class PermanentError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}

package/dist/esm/types/error.types.js

@@ -0,0 +1,18 @@
+/**
+ * Custom error types for TraceLog
+ */
+/**
+ * Represents a permanent HTTP error (4xx) that should not be retried
+ * Examples: 400 Bad Request, 403 Forbidden, 404 Not Found
+ */
+export class PermanentError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'PermanentError';
+        // Maintain proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PermanentError);
+        }
+    }
+}

package/dist/esm/types/index.d.ts

@@ -2,6 +2,7 @@ export * from './common.types';
 export * from './config.types';
 export * from './device.types';
 export * from './emitter.types';
+export * from './error.types';
 export * from './event.types';
 export * from './log.types';
 export * from './mode.types';

package/dist/esm/types/index.js

@@ -2,6 +2,7 @@ export * from './common.types';
 export * from './config.types';
 export * from './device.types';
 export * from './emitter.types';
+export * from './error.types';
 export * from './event.types';
 export * from './log.types';
 export * from './mode.types';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tracelog/lib",
   "description": "JavaScript library for web analytics and real-time event tracking",
   "license": "MIT",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",
@@ -15,6 +15,14 @@
     "import": "./dist/esm/public-api.js",
     "require": "./dist/cjs/public-api.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nacorga/tracelog-lib.git"
+  },
+  "homepage": "https://github.com/nacorga/tracelog-lib#readme",
+  "bugs": {
+    "url": "https://github.com/nacorga/tracelog-lib/issues"
+  },
   "publishConfig": {
     "access": "public"
   },