user-analytics-tracker 1.2.0

package/README.md

@@ -0,0 +1,696 @@
+# user-analytics-tracker
+
+[![npm version](https://badge.fury.io/js/user-analytics-tracker.svg)](https://www.npmjs.com/package/user-analytics-tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/switch-org/analytics-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/switch-org/analytics-tracker/actions/workflows/ci.yml)
+
+A comprehensive, lightweight analytics tracking library for React applications. Track device information, network type, user location, attribution data, and more—all with zero runtime dependencies (React as peer dependency).
+
+**🔒 Privacy-First & Self-Hosted**: All analytics data is sent to **your own backend server**. No data is sent to third-party servers. You have full control over your analytics data.
+
+## ✨ Features
+
+- 🔍 **Device Detection**: Automatically detects device type, OS, browser, model, brand, and hardware specs using User-Agent Client Hints
+- 🌐 **Network Detection**: Identifies WiFi, Cellular, Hotspot, Ethernet connections with quality metrics
+- 📍 **Location Tracking**: 
+  - **Automatic IP-based location** (no permission required) - works immediately
+  - GPS location with consent management (MSISDN-based consent)
+  - Includes public IP address, country, city, region, timezone
+  - Automatic fallback from GPS to IP when GPS unavailable
+- 🎯 **Attribution Tracking**: UTM parameters, referrer tracking, first/last touch attribution
+- 📊 **IP Geolocation**: Client-side and server-side IP-based location detection utilities
+- 🔒 **Privacy-First**: Location consent management, automatic IP fallback
+- ⚡ **Lightweight**: Zero runtime dependencies (except React)
+- 📦 **TypeScript**: Fully typed with comprehensive type definitions
+- 🎨 **Framework Agnostic Core**: Core detectors work without React
+- 🧪 **Well Tested**: Comprehensive test suite with Vitest
+
+## 📦 Installation
+
+```bash
+npm install user-analytics-tracker react react-dom
+# or
+yarn add user-analytics-tracker react react-dom
+# or
+pnpm add user-analytics-tracker react react-dom
+```
+
+**Note**: React and React-DOM are peer dependencies and must be installed separately.
+
+## 🔒 Self-Hosted Analytics - Configure Your Backend URL
+
+**All analytics data is sent to YOUR backend server** - no third-party servers involved. You have complete control over your data.
+
+### Quick Configuration
+
+Simply provide your backend URL in the `apiEndpoint` configuration:
+
+```tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+function App() {
+  const analytics = useAnalytics({
+    config: {
+      apiEndpoint: 'https://api.yourcompany.com/analytics', // Your backend URL
+    },
+  });
+}
+```
+
+### Configuration Options
+
+You can configure your backend URL in three ways:
+
+#### 1. **Full URL (Recommended for Production)**
+
+Use a complete URL pointing to your backend server:
+
+```tsx
+const analytics = useAnalytics({
+  config: {
+    // Point to your own server
+    apiEndpoint: 'https://api.yourcompany.com/analytics',
+    
+    // Or with a custom port
+    // apiEndpoint: 'https://api.yourcompany.com:8080/analytics',
+    
+    // Or using a subdomain
+    // apiEndpoint: 'https://analytics.yourcompany.com/track',
+  },
+});
+```
+
+#### 2. **Relative Path (Same Domain)**
+
+Use a relative path if your API is on the same domain as your frontend:
+
+```tsx
+const analytics = useAnalytics({
+  config: {
+    // Sends to: https://yourdomain.com/api/analytics
+    apiEndpoint: '/api/analytics',
+  },
+});
+```
+
+#### 3. **Environment Variables (Best Practice)**
+
+Use environment variables for different environments:
+
+```tsx
+// .env.local (development)
+// NEXT_PUBLIC_ANALYTICS_API=https://api-dev.yourcompany.com/analytics
+
+// .env.production
+// NEXT_PUBLIC_ANALYTICS_API=https://api.yourcompany.com/analytics
+
+const analytics = useAnalytics({
+  config: {
+    apiEndpoint: process.env.NEXT_PUBLIC_ANALYTICS_API || '/api/analytics',
+  },
+});
+```
+
+### Step-by-Step Setup
+
+1. **Set up your backend API endpoint** (see [Backend Setup](#-backend-api-setup) below)
+2. **Configure the frontend** with your backend URL
+3. **Test the connection** using browser DevTools Network tab
+
+### Examples by Framework
+
+**React (Create React App)**
+```tsx
+// src/App.tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+function App() {
+  const analytics = useAnalytics({
+    config: {
+      apiEndpoint: process.env.REACT_APP_ANALYTICS_API || 'https://api.yourcompany.com/analytics',
+    },
+  });
+}
+```
+
+**Next.js**
+```tsx
+// app/layout.tsx or pages/_app.tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+export default function Layout() {
+  useAnalytics({
+    config: {
+      apiEndpoint: process.env.NEXT_PUBLIC_ANALYTICS_API || '/api/analytics',
+    },
+  });
+}
+```
+
+**Vite + React**
+```tsx
+// src/main.tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+function App() {
+  useAnalytics({
+    config: {
+      apiEndpoint: import.meta.env.VITE_ANALYTICS_API || 'https://api.yourcompany.com/analytics',
+    },
+  });
+}
+```
+
+## 🚀 Quick Start
+
+### Basic Usage (React Hook)
+
+```tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+function MyApp() {
+  const { sessionId, networkInfo, deviceInfo, location, logEvent } = useAnalytics({
+    autoSend: true,
+    config: {
+      // Use your own backend server (full URL)
+      apiEndpoint: 'https://api.yourcompany.com/analytics',
+      // Or use relative path (same domain)
+      // apiEndpoint: '/api/analytics',
+    },
+  });
+
+  return (
+    <div>
+      <p>Device: {deviceInfo?.deviceBrand} {deviceInfo?.deviceModel}</p>
+      <p>Network: {networkInfo?.type}</p>
+      <button onClick={() => logEvent({ action: 'button_click' })}>
+        Track Click
+      </button>
+    </div>
+  );
+}
+```
+
+### Standalone Detectors (No React)
+
+```typescript
+import {
+  NetworkDetector,
+  DeviceDetector,
+  AttributionDetector,
+  LocationDetector,
+} from 'user-analytics-tracker';
+
+// Detect network type
+const network = NetworkDetector.detect();
+console.log(network.type); // 'wifi' | 'cellular' | 'hotspot' | 'ethernet' | 'unknown'
+
+// Detect device info
+const device = await DeviceDetector.detect();
+console.log(device.deviceBrand, device.deviceModel);
+
+// Detect attribution (UTM params, referrer, etc.)
+const attribution = AttributionDetector.detect();
+console.log(attribution.utm_source);
+
+// Detect location (automatic IP-based if no consent, GPS if consent granted)
+const location = await LocationDetector.detect();
+console.log(location.lat, location.lon);
+console.log(location.ip); // Public IP (when using IP-based location)
+console.log(location.country, location.city); // Location details
+
+// Or get IP-based location only (no permission needed)
+const ipLocation = await LocationDetector.detectIPOnly();
+console.log(ipLocation.ip, ipLocation.country, ipLocation.city);
+```
+
+## 📚 API Reference
+
+### React Hook: `useAnalytics`
+
+The main React hook for analytics tracking.
+
+#### Parameters
+
+```typescript
+useAnalytics(options?: UseAnalyticsOptions): UseAnalyticsReturn
+```
+
+**Options:**
+
+```typescript
+interface UseAnalyticsOptions {
+  autoSend?: boolean; // Auto-send analytics on mount (default: true)
+  config?: Partial<AnalyticsConfig>;
+  onReady?: (data: {
+    sessionId: string;
+    networkInfo: NetworkInfo;
+    deviceInfo: DeviceInfo;
+    location: LocationInfo;
+    attribution: AttributionInfo;
+  }) => void; // Callback when data is ready
+}
+```
+
+#### Returns
+
+```typescript
+interface UseAnalyticsReturn {
+  sessionId: string | null;
+  networkInfo: NetworkInfo | null;
+  deviceInfo: DeviceInfo | null;
+  location: LocationInfo | null;
+  attribution: AttributionInfo | null;
+  pageVisits: number;
+  interactions: number;
+  logEvent: (customData?: Record<string, any>) => Promise<void>;
+  incrementInteraction: () => void;
+  refresh: () => Promise<{
+    net: NetworkInfo;
+    dev: DeviceInfo;
+    attr: AttributionInfo;
+    loc: LocationInfo;
+  }>;
+}
+```
+
+### Detectors
+
+#### `NetworkDetector.detect()`
+
+Detects network connection type and quality.
+
+```typescript
+const network = NetworkDetector.detect();
+// Returns:
+// {
+//   type: 'wifi' | 'cellular' | 'hotspot' | 'ethernet' | 'unknown';
+//   effectiveType?: string; // '2g', '3g', '4g', etc.
+//   downlink?: number; // Mbps
+//   rtt?: number; // ms
+//   saveData?: boolean;
+//   connectionType?: string;
+// }
+```
+
+#### `DeviceDetector.detect()`
+
+Detects device information (async - uses User-Agent Client Hints).
+
+```typescript
+const device = await DeviceDetector.detect();
+// Returns:
+// {
+//   type: 'mobile' | 'tablet' | 'desktop' | 'unknown';
+//   os: string;
+//   osVersion: string;
+//   browser: string;
+//   browserVersion: string;
+//   deviceModel: string;
+//   deviceBrand: string;
+//   screenResolution: string;
+//   // ... more fields
+// }
+```
+
+#### `LocationDetector.detect()`
+
+Detects location (IP-first when no consent, GPS when consent granted). Automatically falls back to IP if GPS fails.
+
+```typescript
+const location = await LocationDetector.detect();
+// Returns:
+// {
+//   lat?: number | null;
+//   lon?: number | null;
+//   accuracy?: number | null;  // GPS only
+//   permission: 'granted' | 'denied' | 'prompt' | 'unsupported';
+//   source: 'gps' | 'ip' | 'unknown';
+//   ts?: string;
+//   // IP-based location includes:
+//   ip?: string | null;         // Public IP address
+//   country?: string;           // Country name
+//   countryCode?: string;       // ISO country code
+//   city?: string;              // City name
+//   region?: string;            // Region/state
+//   timezone?: string;          // Timezone
+// }
+```
+
+#### `LocationDetector.detectIPOnly()`
+
+Get IP-based location only (fast, automatic, no permission needed).
+
+```typescript
+const location = await LocationDetector.detectIPOnly();
+// Returns IP-based location with IP address, country, city, coordinates
+// Works immediately without user permission
+```
+
+#### `LocationDetector.detectWithAutoConsent()`
+
+Automatically grants consent and tries GPS, falls back to IP if GPS fails.
+
+```typescript
+const location = await LocationDetector.detectWithAutoConsent();
+// 1. Automatically grants location consent
+// 2. Tries GPS location (if available)
+// 3. Falls back to IP-based location if GPS fails/denied/unavailable
+```
+
+#### `getPublicIP()`
+
+Get just the public IP address (utility function).
+
+```typescript
+import { getPublicIP } from 'user-analytics-tracker';
+
+const ip = await getPublicIP();
+console.log(ip); // "203.0.113.42"
+```
+
+#### `AttributionDetector.detect()`
+
+Detects UTM parameters, referrer, and session tracking.
+
+```typescript
+const attribution = AttributionDetector.detect();
+// Returns:
+// {
+//   landingUrl: string;
+//   referrerUrl: string | null;
+//   referrerDomain: string | null;
+//   utm_source?: string | null;
+//   utm_medium?: string | null;
+//   utm_campaign?: string | null;
+//   // ... more UTM fields
+//   firstTouch?: Record<string, string | null> | null;
+//   lastTouch?: Record<string, string | null> | null;
+//   sessionStart?: string | null;
+// }
+```
+
+### Services
+
+#### `AnalyticsService.trackUserJourney()`
+
+Send analytics data to your backend.
+
+```typescript
+import { AnalyticsService } from 'user-analytics-tracker';
+
+// Configure endpoint - use your own server
+AnalyticsService.configure({ 
+  apiEndpoint: 'https://api.yourcompany.com/analytics' 
+});
+
+// Or use relative path (same domain)
+// AnalyticsService.configure({ apiEndpoint: '/api/analytics' });
+
+// Track event
+await AnalyticsService.trackUserJourney({
+  sessionId: 'abc123',
+  pageUrl: 'https://example.com/page',
+  networkInfo: network,
+  deviceInfo: device,
+  location: location,
+  attribution: attribution,
+  customData: { userId: 'user123', action: 'purchase' },
+});
+```
+
+### Utilities
+
+#### Location Consent Management
+
+```typescript
+import {
+  setLocationConsentGranted,
+  hasLocationConsent,
+  checkAndSetLocationConsent,
+  clearLocationConsent,
+} from 'user-analytics-tracker';
+
+// When user enters MSISDN, grant location consent
+checkAndSetLocationConsent(msisdn); // Returns true if consent granted
+
+// Check if consent exists
+if (hasLocationConsent()) {
+  // Location tracking allowed
+}
+
+// Manually grant/revoke consent
+setLocationConsentGranted();
+clearLocationConsent();
+```
+
+#### IP Geolocation Utilities
+
+**Client-Side: Get Public IP**
+
+```typescript
+import { getPublicIP } from 'user-analytics-tracker';
+
+// Get just the public IP address (no location data)
+const ip = await getPublicIP();
+console.log('Your IP:', ip); // "203.0.113.42"
+```
+
+**Server-Side: IP Location from Request**
+
+```typescript
+import { getIPLocation, getIPFromRequest } from 'user-analytics-tracker';
+
+// In your API route (Next.js example)
+export async function POST(req: Request) {
+  // Extract IP from request headers
+  const ip = getIPFromRequest(req);
+  
+  // Get location data from IP
+  const location = await getIPLocation(ip);
+  // location contains: country, region, city, lat, lon, timezone, isp, etc.
+}
+```
+
+## 🔒 Privacy & Consent
+
+### MSISDN-Based Consent
+
+When a user enters their phone number (MSISDN), it implies consent for location tracking. The library automatically grants location consent:
+
+```typescript
+import { checkAndSetLocationConsent } from 'user-analytics-tracker';
+
+// When MSISDN is entered
+checkAndSetLocationConsent(phoneNumber);
+// Location consent is now granted, GPS will be requested automatically
+```
+
+### Hotspot Detection & Gating
+
+Detect and restrict hotspot users:
+
+```tsx
+import { useAnalytics } from 'user-analytics-tracker';
+
+function HotspotGate({ children }) {
+  const { networkInfo } = useAnalytics({ autoSend: false });
+  
+  if (networkInfo?.type === 'hotspot') {
+    return (
+      <div>
+        <h2>Hotspot Detected</h2>
+        <p>Please switch to mobile data or Wi-Fi.</p>
+      </div>
+    );
+  }
+  
+  return children;
+}
+```
+
+## 📖 Advanced Usage
+
+### Custom Analytics Service
+
+```typescript
+import { AnalyticsService } from 'user-analytics-tracker';
+
+class MyAnalyticsService extends AnalyticsService {
+  static async trackUserJourney(data: any) {
+    // Custom tracking logic
+    await fetch('/my-custom-endpoint', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+}
+```
+
+### Manual Event Tracking
+
+```typescript
+const { logEvent, incrementInteraction } = useAnalytics();
+
+// Log custom event
+await logEvent({
+  eventType: 'purchase',
+  productId: '123',
+  amount: 99.99,
+});
+
+// Increment interaction counter
+incrementInteraction();
+```
+
+### Server-Side Integration
+
+Example Next.js API route:
+
+```typescript
+// app/api/analytics/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getIPFromRequest, getIPLocation } from 'user-analytics-tracker';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const ip = getIPFromRequest(req);
+  const ipLocation = await getIPLocation(ip);
+  
+  // Store analytics with IP location
+  await storeAnalytics({
+    ...body,
+    ip,
+    ipLocation,
+  });
+  
+  return NextResponse.json({ ok: true });
+}
+```
+
+## 📚 Documentation
+
+Comprehensive documentation is available in the [`docs/`](./docs) directory:
+
+- **[Usage Guide](./docs/usage-guide.md)** - Complete guide on how to use the package in your applications
+  - Installation instructions
+  - Basic and advanced usage examples
+  - React hook documentation
+  - Standalone (non-React) usage
+  - Framework integrations (Next.js, Gatsby, etc.)
+  - Real-world examples
+  - Troubleshooting
+
+- **[Quick Start Guide](./docs/quick-start.md)** - Get started in 5 minutes
+  - Installation
+  - Basic setup
+  - Development workflow
+  - Common commands
+
+- **[Publishing Guide](./docs/publishing.md)** - How to publish the package
+  - Prerequisites
+  - Publishing methods (automatic & manual)
+  - Version management
+  - Best practices
+
+- **[Package Structure](./docs/package-structure.md)** - Understanding the codebase
+  - Directory structure
+  - Architecture overview
+  - Code organization
+  - Development guidelines
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## 🛠️ Development
+
+```bash
+# Clone repository
+git clone https://github.com/switch-org/analytics-tracker.git
+cd analytics-tracker
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run build:watch
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+
+# Type check
+npm run type-check
+```
+
+## 📝 TypeScript
+
+This package is written in TypeScript and provides full type definitions. All exports are fully typed:
+
+```typescript
+import type {
+  NetworkInfo,
+  DeviceInfo,
+  LocationInfo,
+  AttributionInfo,
+  IPLocation,
+  UseAnalyticsReturn,
+} from 'user-analytics-tracker';
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Commit Convention
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `style:` Code style changes (formatting, etc.)
+- `refactor:` Code refactoring
+- `test:` Adding or updating tests
+- `chore:` Maintenance tasks
+
+## 📄 License
+
+MIT © [Switch Org](https://github.com/switch-org)
+
+## 🙏 Acknowledgments
+
+- Uses [ip-api.com](http://ip-api.com) for free IP geolocation
+- Built with modern web APIs (User-Agent Client Hints, Network Information API, Geolocation API)
+
+<!-- ## 📞 Support
+
+- 📧 Email: support@switch.org
+- 🐛 Issues: [GitHub Issues](https://github.com/switch-org/analytics-tracker/issues)
+- 📖 Documentation: See the [docs/](./docs) directory for comprehensive guides
+
+
+--- -->
+
+Made with ❤️ by ATIF RAFIQUE