user-analytics-tracker 1.7.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,68 @@
+# [2.1.0](https://github.com/switch-org/analytics-tracker/compare/v2.0.0...v2.1.0) (2025-12-29)
+
+
+### Features
+
+* migrate IP geolocation to ipwho.is API with dynamic key storage ([0605f72](https://github.com/switch-org/analytics-tracker/commit/0605f7207baa590b776a3b52cbc055e98a8a22e4))
+
+# [2.1.0](https://github.com/switch-org/analytics-tracker/compare/v2.0.0...v2.1.0) (TBD)
+
+### Features
+
+* **IP Geolocation API Migration**: Migrated from ip-api.com to ipwho.is API for IP-based location tracking
+  - More comprehensive location data including continent, flag, connection details, and timezone information
+  - Dynamic key storage: All API response keys are automatically stored, including nested objects
+  - Future-proof: New fields added by the API are automatically captured without code changes
+  - No API key required: Free tier with no authentication needed
+* **Enhanced IP Location Data**: The `IPLocation` interface now includes all fields from the ipwho.is API response
+  - New fields: `continent`, `continent_code`, `flag`, `connection`, `timezone` (with full details), `is_eu`, `postal`, `calling_code`, `capital`, `borders`
+  - Full backward compatibility: All existing fields (`lat`, `lon`, `countryCode`, etc.) remain available
+  - Access to full IP location data in analytics events via `ipLocationData` field
+
+### Improvements
+
+* Better IP location data coverage with additional metadata
+* Automatic storage of all API response keys, including future additions
+* Improved type definitions for IP location data
+
+### Migration Notes
+
+This upgrade is **fully backward compatible**. No code changes are required. See the [Upgrade Guide](./docs/upgrade-guide.md) for details on accessing new fields.
+
+# [2.0.0](https://github.com/switch-org/analytics-tracker/compare/v1.7.0...v2.0.0) (2025-12-01)
+
+
+### Features
+
+* major improvements - event batching, retry logic, plugins, and more ([f47b0ea](https://github.com/switch-org/analytics-tracker/commit/f47b0ea0f7bde575d4d91a2ae807fb074065c55c))
+* major improvements - event batching, retry logic, plugins, and more ([46d0c1c](https://github.com/switch-org/analytics-tracker/commit/46d0c1c3e8435dec70fb04e99ad0902198c1486c))
+
+
+### BREAKING CHANGES
+
+* None - all changes are backward compatible
+* None - all changes are backward compatible
+
+# [1.8.0](https://github.com/switch-org/analytics-tracker/compare/v1.7.0...v1.8.0) (2025-01-XX)
+
+### Features
+
+* **Event Batching & Queue System**: Automatic event batching reduces API calls by 50-90%. Events are queued and sent in configurable batches (default: 10 events per batch, 5 second intervals)
+* **Offline Support**: Events are persisted to localStorage and automatically sent when connection is restored
+* **Retry Logic with Exponential Backoff**: Automatic retry mechanism for failed requests with exponential backoff (1s, 2s, 4s, 8s). Configurable max retries (default: 3)
+* **Enhanced Logging System**: Configurable log levels (`silent`, `error`, `warn`, `info`, `debug`) with automatic dev/prod level selection
+* **Plugin/Middleware System**: Extensible plugin architecture for event transformation, filtering, and enrichment. Supports `beforeSend`, `afterSend`, and `onError` hooks
+* **Session Management Improvements**: Enhanced session tracking with timeout detection (default: 30 min), automatic session renewal, and session utilities
+* **Developer Debugging Tools**: Built-in debug utilities accessible via `window.__analyticsDebug` in development mode. Includes queue inspection, manual flush, and stats
+* **Performance Monitoring & Metrics**: Optional metrics collection tracking events sent/queued/failed, average send time, retry counts, and error history
+* **Enhanced Configuration Options**: New config options for batching (`batchSize`, `batchInterval`, `maxQueueSize`), retry (`maxRetries`, `retryDelay`), session (`sessionTimeout`), logging (`logLevel`), and metrics (`enableMetrics`)
+
+### Improvements
+
+* Better error handling with graceful degradation
+* Improved test coverage for new features
+* Enhanced TypeScript types for all new features
+
 # [1.7.0](https://github.com/switch-org/analytics-tracker/compare/v1.6.0...v1.7.0) (2025-11-24)
 
 

package/README.md

@@ -15,13 +15,21 @@ A comprehensive, lightweight analytics tracking library for React applications.
 - 📍 **Location Tracking**: 
   - **IP-based location** - Requires user consent (privacy-compliant)
   - **GPS location** - Requires explicit user consent and browser permission
-  - Includes public IP address, country, city, region, timezone
+  - Includes public IP address, country, city, region, timezone, continent, flag, connection details
+  - Dynamic key storage: All IP location API fields are automatically captured
   - Automatic fallback from GPS to IP when GPS unavailable
   - Consent management utilities included
 - 🎯 **Attribution Tracking**: UTM parameters, referrer tracking, first/last touch attribution
 - 📊 **IP Geolocation**: Client-side and server-side IP-based location detection utilities
 - 🔒 **Privacy-First**: User consent required for location tracking (GPS & IP), consent management utilities
 - 🎯 **Custom Event Tracking**: Firebase/Google Analytics-style event tracking with automatic context collection
+- ⚡ **Event Batching & Queue System**: Automatic event batching reduces API calls by 50-90%. Events are queued and sent in configurable batches with offline persistence
+- 🔄 **Retry Logic**: Automatic retry with exponential backoff for failed requests. Configurable retry attempts and delays
+- 📝 **Enhanced Logging**: Configurable log levels (silent, error, warn, info, debug) with automatic dev/prod level selection
+- 🔌 **Plugin System**: Extensible plugin architecture for event transformation, filtering, and enrichment
+- 📈 **Session Management**: Enhanced session tracking with timeout detection and automatic renewal
+- 🐛 **Debug Tools**: Built-in debugging utilities for development (queue inspection, manual flush, stats)
+- 📊 **Performance Metrics**: Optional metrics collection for monitoring events, retries, and performance
 - ⚡ **Lightweight**: Zero runtime dependencies (except React)
 - 📦 **TypeScript**: Fully typed with comprehensive type definitions
 - 🎨 **Framework Agnostic Core**: Core detectors work without React
@@ -59,6 +67,36 @@ function App() {
 }
 ```
 
+### Advanced Configuration Options
+
+The package now supports extensive configuration options for batching, retry logic, logging, and more:
+
+```tsx
+const analytics = useAnalytics({
+  config: {
+    apiEndpoint: 'https://api.yourcompany.com/analytics',
+    
+    // Event batching configuration
+    batchSize: 10,              // Events per batch (default: 10)
+    batchInterval: 5000,        // Flush interval in ms (default: 5000)
+    maxQueueSize: 100,          // Max queued events (default: 100)
+    
+    // Retry configuration
+    maxRetries: 3,              // Max retry attempts (default: 3)
+    retryDelay: 1000,           // Initial retry delay in ms (default: 1000)
+    
+    // Session configuration
+    sessionTimeout: 1800000,    // Session timeout in ms (default: 30 min)
+    
+    // Logging configuration
+    logLevel: 'warn',           // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'warn')
+    
+    // Metrics configuration
+    enableMetrics: false,       // Enable metrics collection (default: false)
+  },
+});
+```
+
 ### Configuration Options
 
 You can configure your backend URL in three ways:
@@ -272,6 +310,32 @@ interface UseAnalyticsOptions {
     attribution: AttributionInfo;
   }) => void; // Callback when data is ready
 }
+
+interface AnalyticsConfig {
+  apiEndpoint: string;
+  // Batching options
+  batchSize?: number;        // Events per batch (default: 10)
+  batchInterval?: number;    // Flush interval in ms (default: 5000)
+  maxQueueSize?: number;     // Max queued events (default: 100)
+  // Retry options
+  maxRetries?: number;       // Max retry attempts (default: 3)
+  retryDelay?: number;       // Initial retry delay in ms (default: 1000)
+  // Session options
+  sessionTimeout?: number;   // Session timeout in ms (default: 1800000 = 30 min)
+  // Logging options
+  logLevel?: LogLevel;       // 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'warn')
+  // Metrics options
+  enableMetrics?: boolean;   // Enable metrics collection (default: false)
+  // Existing options
+  autoSend?: boolean;
+  enableLocation?: boolean;
+  enableIPGeolocation?: boolean;
+  enableNetworkDetection?: boolean;
+  enableDeviceDetection?: boolean;
+  enableAttribution?: boolean;
+  sessionStoragePrefix?: string;
+  localStoragePrefix?: string;
+}
 ```
 
 #### Returns
@@ -416,6 +480,26 @@ const attribution = AttributionDetector.detect();
 
 ### Services
 
+#### `AnalyticsService.configure()`
+
+Configure the analytics service with advanced options.
+
+```typescript
+import { AnalyticsService } from 'user-analytics-tracker';
+
+AnalyticsService.configure({
+  apiEndpoint: 'https://api.yourcompany.com/analytics',
+  batchSize: 20,              // Events per batch (default: 10)
+  batchInterval: 10000,       // Flush interval in ms (default: 5000)
+  maxQueueSize: 100,          // Max queued events (default: 100)
+  maxRetries: 5,              // Max retry attempts (default: 3)
+  retryDelay: 2000,           // Initial retry delay in ms (default: 1000)
+  sessionTimeout: 1800000,    // Session timeout in ms (default: 30 min)
+  logLevel: 'info',           // Logging verbosity (default: 'warn')
+  enableMetrics: true,        // Enable metrics collection (default: false)
+});
+```
+
 #### `AnalyticsService.trackUserJourney()`
 
 Send analytics data to your backend.
@@ -443,8 +527,111 @@ await AnalyticsService.trackUserJourney({
 });
 ```
 
+#### `AnalyticsService.flushQueue()`
+
+Manually flush the event queue (useful before page unload).
+
+```typescript
+// Flush all queued events immediately
+await AnalyticsService.flushQueue();
+```
+
+#### `AnalyticsService.getQueueSize()`
+
+Get the current number of events in the queue.
+
+```typescript
+const size = AnalyticsService.getQueueSize();
+console.log(`Queue has ${size} events`);
+```
+
+#### `AnalyticsService.getMetrics()`
+
+Get performance metrics (if enabled).
+
+```typescript
+const metrics = AnalyticsService.getMetrics();
+if (metrics) {
+  console.log(`Sent: ${metrics.eventsSent}, Failed: ${metrics.eventsFailed}`);
+}
+```
+
 ### Utilities
 
+#### Logger
+
+Configure logging levels for better debugging and production use.
+
+```typescript
+import { logger } from 'user-analytics-tracker';
+
+// Set log level
+logger.setLevel('debug'); // 'silent' | 'error' | 'warn' | 'info' | 'debug'
+
+// Use logger
+logger.debug('Debug message');
+logger.info('Info message');
+logger.warn('Warning message');
+logger.error('Error message');
+```
+
+#### Plugin Manager
+
+Register and manage plugins for event transformation.
+
+```typescript
+import { pluginManager } from 'user-analytics-tracker';
+
+// Register a plugin
+pluginManager.register({
+  name: 'my-plugin',
+  beforeSend: (event) => {
+    // Transform event
+    return event;
+  },
+});
+
+// Unregister a plugin
+pluginManager.unregister('my-plugin');
+
+// Get all plugins
+const plugins = pluginManager.getPlugins();
+```
+
+#### Queue Manager
+
+Advanced queue management (for power users).
+
+```typescript
+import { QueueManager } from 'user-analytics-tracker';
+
+const queue = new QueueManager({
+  batchSize: 20,
+  batchInterval: 10000,
+  maxQueueSize: 200,
+  storageKey: 'my-queue',
+});
+
+queue.setFlushCallback(async (events) => {
+  // Custom flush logic
+});
+```
+
+#### Metrics Collector
+
+Collect and monitor analytics performance metrics.
+
+```typescript
+import { metricsCollector } from 'user-analytics-tracker';
+
+// Metrics are automatically collected when enableMetrics is true
+// Access metrics
+const metrics = metricsCollector.getMetrics();
+
+// Reset metrics
+metricsCollector.reset();
+```
+
 #### Location Consent Management
 
 ```typescript
@@ -468,6 +655,45 @@ setLocationConsentGranted();
 clearLocationConsent();
 ```
 
+#### Session Management
+
+Enhanced session tracking utilities.
+
+```typescript
+import {
+  getOrCreateSession,
+  updateSessionActivity,
+  getSession,
+  clearSession,
+} from 'user-analytics-tracker';
+
+// Get or create session with custom timeout (30 minutes)
+const session = getOrCreateSession(30 * 60 * 1000);
+// Returns: { sessionId, startTime, lastActivity, pageViews }
+
+// Update session activity
+updateSessionActivity();
+
+// Get current session
+const currentSession = getSession();
+
+// Clear session
+clearSession();
+```
+
+#### Debug Utilities
+
+Development debugging tools.
+
+```typescript
+import { initDebug } from 'user-analytics-tracker';
+
+// Initialize debug tools (automatically called in development)
+initDebug();
+
+// Then access via window.__analyticsDebug in browser console
+```
+
 #### IP Geolocation Utilities
 
 **Client-Side: Get Public IP**
@@ -630,6 +856,14 @@ export async function POST(req: NextRequest) {
 
 Comprehensive documentation is available in the [`docs/`](./docs) directory:
 
+- **[Upgrade Guide](./docs/upgrade-guide.md)** - Step-by-step migration instructions for upgrading between versions
+
+- **[Upgrade Guide](./docs/upgrade-guide.md)** - Step-by-step migration instructions for upgrading between versions
+  - Breaking changes and compatibility notes
+  - New features and improvements
+  - Migration examples
+  - Troubleshooting upgrade issues
+
 - **[Usage Guide](./docs/usage-guide.md)** - Complete guide on how to use the package in your applications
   - Installation instructions
   - Basic and advanced usage examples
@@ -739,7 +973,7 @@ MIT © [Switch Org](https://github.com/switch-org)
 
 ## 🙏 Acknowledgments
 
-- Uses [ip-api.com](http://ip-api.com) for free IP geolocation
+- Uses [ipwho.is](https://ipwho.is/) for free IP geolocation
 - Built with modern web APIs (User-Agent Client Hints, Network Information API, Geolocation API)
 
 <!-- ## 📞 Support