# 🎯 scrubbe-auth Analytics

<div align="center">
Advanced analytics and tracking suite for modern web applications  
📖 Documentation • 🚀 Quick Start • 💡 Examples • 🎮 Demo
</div>

## ✨ Features

- 🔒 **Privacy-First** - GDPR compliant with built-in consent management
- 🎯 **Device Fingerprinting** - Advanced browser and device identification
- 📍 **Location Tracking** - GPS and IP-based geolocation with privacy controls
- 🌐 **Network Analysis** - Connection type, speed, and ISP detection
- 👤 **User Behavior** - Page views, clicks, scrolling, and session tracking
- 🚀 **High Performance** - Optimized batching and minimal overhead
- 🔧 **Modular Architecture** - Use only what you need
- 📊 **Real-time Analytics** - Live data streaming and processing
- 🛡️ **Enterprise Ready** - Scalable, secure, and production-tested

## 📦 Packages

| Package | Version | Description |
|---------|---------|-------------|
| `@scrubbe-auth/analytics` | | Core analytics engine |
| `@scrubbe-auth/device-fingerprint` | | Advanced device fingerprinting |
| `@scrubbe-auth/location-tracker` | | Location and IP tracking |
| `@scrubbe-auth/network-info` | | Network information detection |
| `@scrubbe-auth/user-tracker` | | User activity and behavior tracking |

## 🚀 Quick Start

### Installation

```bash
# Install core package
npm install @scrubbe-auth/analytics

# Or install all modules
npm install @scrubbe-auth/analytics @scrubbe-auth/device-fingerprint @scrubbe-auth/location-tracker @scrubbe-auth/network-info @scrubbe-auth/user-tracker



## Basic Usage
```import { Analytics } from '@scrubbe-auth/analytics';

 Initialize with minimal configuration
const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key'
});

 Start tracking
   await analytics.init();

Track events
  analytics.track('button_click', {
  buttonId: 'cta-signup',
  page: '/landing'
}); ```


## Advanced Setup
``` import { Analytics } from '@scrubbe-auth/analytics';
import { DeviceFingerprint } from '@scrubbe-auth/device-fingerprint';
import { LocationTracker } from '@scrubbe-auth/location-tracker';

const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  autoTrack: true,
  privacy: {
    respectDNT: true,
    anonymizeIP: true
  }
});

// Add advanced tracking modules
const deviceFP = new DeviceFingerprint({
  enableCanvas: true,
  enableWebGL: true
});

const locationTracker = new LocationTracker({
  enableGPS: false, // Requires user permission
  enableIP: true
});

// Integrate modules
analytics.use(deviceFP);
analytics.use(locationTracker);

// Start comprehensive tracking
await analytics.start(); ```



## 📊 Usage Examples

### Event Tracking

```// Page views
analytics.page('/dashboard', {
  category: 'app',
  userId: 'user_123'
});

// Custom events
analytics.track('purchase_completed', {
  orderId: 'order_456',
  revenue: 99.99,
  currency: 'USD'
});

// User identification
analytics.identify('user_123', {
  email: 'user@example.com',
  plan: 'premium'
}); ```


### Device Fingerprinting

``` import { DeviceFingerprint } from '@scrubbe-auth/device-fingerprint';

const deviceFP = new DeviceFingerprint({
  enableCanvas: true,
  enableWebGL: true,
  enableAudio: false // Disable for better performance
});

const fingerprint = await deviceFP.generate();
console.log('Unique Device ID:', fingerprint.deviceId);
console.log('Confidence Score:', fingerprint.confidence); ```


### Location Tracking 
``` import { LocationTracker } from '@scrubbe-auth/location-tracker';

const locationTracker = new LocationTracker({
  enableGPS: true,
  accuracy: 'high'
});

const location = await locationTracker.getLocation();
console.log('Location:', location.city, location.country);  ```



## ⚙️ Configuration

### Environment Variables

# Required
scrubbe-auth_PROJECT_ID=your-project-id
scrubbe-auth_API_KEY=your-api-key

# Optional
scrubbe-auth_ENVIRONMENT=production
scrubbe-auth_DEBUG=false
scrubbe-auth_BATCH_SIZE=100



### Privacy Settings

``` const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  privacy: {
    respectDNT: true,        // Honor Do Not Track
    anonymizeIP: true,       // Anonymize IP addresses
    consentRequired: true,   // Require explicit consent
    cookieConsent: true      // Cookie consent integration
  }
});   ```


### Performance Optimization

``` const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  batchSize: 100,           // Events per batch
  flushInterval: 5000,      // Flush every 5 seconds
  transport: {
    compression: true,      // Enable data compression
    retries: 3             // Retry failed requests
  }
});  ```


### 🔧 Development
### Prerequisites
      - Node.js ≥ 18.0.0

      - pnpm ≥ 8.0.0


## 📝 API Reference
###  Core Analytics

``` interface Analytics {
  // Initialization
  init(): Promise<void>;
  start(): Promise<void>;
  stop(): void;

  // Event tracking
  track(event: string, properties?: Record<string, any>): void;
  page(page: string, properties?: Record<string, any>): void;
  identify(userId: string, traits?: Record<string, any>): void;
  alias(newId: string, previousId?: string): void;

  // Module integration
  use(module: AnalyticsModule): void;

  // Event listeners
  on(event: string, callback: Function): void;
  off(event: string, callback: Function): void;
} ```


### Device Fingerprinting

``` interface DeviceFingerprint {
  generate(): Promise<FingerprintResult>;
  clearCache(): void;
  getConfig(): DeviceFingerprintConfig;
}

interface FingerprintResult {
  deviceId: string;
  confidence: number;
  canvas?: CanvasFingerprint;
  webgl?: WebGLFingerprint;
  audio?: AudioFingerprint;
  screen?: ScreenFingerprint;
  browser?: BrowserFingerprint;
}```



## 🛡️ Privacy & Security

  - GDPR Compliant - Built-in privacy controls and consent management

  - Data Minimization - Collect only necessary data

  - Encryption - End-to-end data encryption

  - Anonymization - IP address and PII anonymization

  - Consent Management - Granular privacy controls

  - Do Not Track - Automatic DNT header respect


  ### 🔍 Troubleshooting

  Common Issues 

  Module not found errors

  ``` # Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install  ```

## Build failures

``` # Clean and rebuild
pnpm clean
pnpm build   ```

# TypeScript errors

``` # Check TypeScript configuration
pnpm typecheck ```


# Debug Mode
```  const analytics = new Analytics({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  debug: true // Enable debug logging
});   ```