frontend-logger-advanced/README.md

Comprehensive frontend logging system with dead click detection, rage click detection, framework integrations (React/Solid), and cloud streaming support

# Frontend Logger

[![npm version](https://badge.fury.io/js/frontend-logger-advanced.svg)](https://badge.fury.io/js/frontend-logger-advanced)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

Comprehensive frontend logging with dead click detection, rage click detection, React/Solid integrations, and cloud streaming.

## ✨ Features

🎯 **Dead Click Detection** • 🔥 **Rage Click Detection** • ⚛️ **React Integration** • 🧩 **Solid JS Integration** • ☁️ **Azure Event Hubs** • 📁 **File Export** • 🔧 **TypeScript Support** • 🚀 **Performance Optimized**

## 📦 Installation

```bash
npm install frontend-logger-advanced
```

## 🚀 Quick Start

```javascript
import { initLogging } from 'frontend-logger-advanced';

// Basic usage
const logger = await initLogging({
  config: {
    features: { deadClickDetection: true, rageClickDetection: true },
    logging: { level: 'INFO' }
  }
});

logger.info('User action', { action: 'button_click' });
logger.custom('purchase', { productId: '123', amount: 99.99 });
```

### With Config File

```javascript
import { quickStart } from 'frontend-logger-advanced';
const logger = await quickStart('/config/logger.json');
```

## ⚛️ React Integration

```jsx
import { LoggerProvider, useLogger } from 'frontend-logger-advanced/react';

function App() {
  return (
    <LoggerProvider config={{ features: { reactSupport: true } }}>
      <MyComponent />
    </LoggerProvider>
  );
}

function MyComponent() {
  const logger = useLogger();
  const handleClick = () => logger?.info('Button clicked');
  return <button onClick={handleClick}>Click me</button>;
}
```

## 🧩 Solid JS Integration

```javascript
import { createLoggerSignal } from 'frontend-logger-advanced/solid';

function App() {
  const { logger, isInitialized } = createLoggerSignal();
  const handleClick = () => logger()?.custom('button_click');
  
  return (
    <Show when={isInitialized()}>
      <button onClick={handleClick}>Click Me</button>
    </Show>
  );
}
```

## 📋 Log Object Format

```typescript
interface LogEntry {
  id: string;                    // "log_1691756400000_abc123"
  type: 'custom' | 'dead_click' | 'rage_click' | 'error';
  level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
  timestamp: string;             // "2025-08-11T12:00:00.000Z"
  message?: string;
  details: Record<string, any>;
  metadata: {
    sessionId: string;
    url: string;
    browserInfo?: { name: string; version: string; platform: string; };
  };
}
```

## 🔧 Configuration

```json
{
  "features": {
    "customLogs": true,
    "deadClickDetection": true,
    "rageClickDetection": true,
    "localLogFile": true,
    "eventHub": false
  },
  "logging": {
    "level": "INFO",
    "endpoint": "https://api.example.com/logs",
    "batchSize": 50,
    "batchInterval": 5000
  },
  "deadClick": { "timeout": 300, "excludeSelectors": [".loading"] },
  "rageClick": { "threshold": 3, "timeWindow": 1000 }
}
```

## 📖 Documentation

- 📚 **[Complete Integration Guide](https://github.com/rushikeshthosar/frontend-logger/blob/main/INTEGRATIONS.md)** - React, Solid, Azure, HTTP endpoints
- ⚙️ **[Configuration Guide](https://github.com/rushikeshthosar/frontend-logger/blob/main/CONFIG_GUIDE.md)** - All config options with examples
- 🏗️ **[Implementation Details](https://github.com/rushikeshthosar/frontend-logger/blob/main/IMPLEMENTATION_COMPLETE.md)** - Technical architecture

## 📊 Log Levels & Custom Events

```javascript
// Standard logging
logger.debug('Debug info', { state: currentState });
logger.info('User logged in', { userId: '123' });
logger.warn('Deprecated API used');
logger.error('API call failed', { error: 'Network timeout' });

// Custom events
logger.custom('product_view', { productId: 'ABC123', price: 299.99 });
logger.custom('add_to_cart', { productId: 'ABC123', quantity: 2 });
logger.custom('checkout_complete', { orderId: 'ORD456', total: 599.98 });
```

## 🎯 Click Detection

- **Dead Clicks**: Automatically detect clicks on non-interactive elements
- **Rage Clicks**: Identify rapid repeated clicks indicating user frustration
- **Configurable**: Custom selectors, timeouts, and thresholds
- **Smart Detection**: Excludes loading states, carousels, sliders

## ☁️ Cloud Integration

```javascript
// Azure Event Hubs
const logger = await initLogging({
  config: {
    features: { eventHub: true },
    eventHub: {
      connectionString: "Endpoint=sb://...",
      eventHubName: "frontend-logs",
      partitionKey: "sessionId"
    }
  }
});

// HTTP Endpoint
const logger = await initLogging({
  config: {
    logging: { endpoint: 'https://api.example.com/logs' }
  }
});
```

## 📈 Performance

- **< 1ms** per log entry
- **Memory efficient** with automatic queue management
- **Non-blocking** passive event listeners
- **Tree-shakeable** exports
- **Optimized bundling** with minification

## 🔒 Security

- **Data sanitization** prevents XSS
- **HTTPS endpoints** only
- **SAS token support** for Azure
- **No automatic PII** collection

## 📄 License

MIT © [Rushikesh Thosar](https://github.com/rushikeshthosar)

---

**[GitHub Repository](https://github.com/rushikeshthosar/frontend-logger)** • **[Issues](https://github.com/rushikeshthosar/frontend-logger/issues)** • **[npm Package](https://www.npmjs.com/package/frontend-logger-advanced)**