npm package: @racoelho/analytics
Description: Lightweight web analytics SDK (React, Angular, Vanilla)
Author: Rafael Coelho
Latest version: 0.1.1

# 📊 @racoelho/analytics

SDK leve (~3KB) para analytics web. Funciona em React, Angular e VanillaJS.

## 📦 Instalação

```bash
npm install @racoelho/analytics
```

CDN: `https://cdn.jsdelivr.net/npm/@racoelho/analytics/dist/index.global.js`

## 🚀 Uso Rápido

```ts
import { Analytics } from '@racoelho/analytics'

const analytics = new Analytics({
  siteKey: 'pk_demo',           // obrigatório
  endpoint: 'https://.../v1/i', // obrigatório
  batchSize: 10,                // opcional, default: 10
  flushIntervalMs: 3000,        // opcional, default: 3000
  respectDNT: true,             // opcional, default: true
  autoPageview: true            // opcional, default: true
})

// Eventos são enviados automaticamente em batch
analytics.track('button_click', { id: 'cta' })
```

## 📋 Métodos Disponíveis

### Métodos Principais

| Método | Parâmetros | Descrição |
|--------|------------|-----------|
| `track(name, props?)` | `name: string`<br>`props?: object` | Evento customizado |
| `pageview(props?)` | `props?: object` | Visualização de página |
| `identify(payload)` | `{ user_id: string, traits?: object }` | Identificar usuário |
| `setConsent(status)` | `'granted' \| 'denied'` | Consentimento LGPD/GDPR |
| `flush()` | - | Forçar envio imediato |

### Eventos Padronizados

#### Interação
- `click(elementId?, elementText?, props?)`

#### Formulários
- `formStart(formId?, formName?, props?)`
- `formSubmit(formId?, formName?, props?)`

#### Download/Share
- `download(fileName?, fileType?, props?)`
- `share(method?, contentType?, itemId?, props?)`

#### Busca
- `search(query?, category?, props?)`

#### Autenticação
- `signup(method?, props?)`
- `login(method?, props?)`
- `logout(props?)`

#### E-commerce
- `viewItem(productId?, productName?, category?, price?, props?)`
- `addToCart(productId?, productName?, price?, quantity?, props?)`
- `removeFromCart(productId?, productName?, props?)`
- `beginCheckout(value?, currency?, props?)`
- `purchase(orderId?, value?, currency?, items?, props?)`<br>  `items: Array<{ product_id?, product_name?, price?, quantity? }>`

#### Vídeo
- `videoPlay(videoId?, videoTitle?, duration?, props?)`
- `videoPause(videoId?, currentTime?, props?)`
- `videoComplete(videoId?, duration?, props?)`

#### Navegação
- `scroll(depth?, props?)`

> **Nota**: Todos os parâmetros são opcionais. Use `props` para adicionar propriedades customizadas.

## 💡 Exemplos

```ts
// E-commerce
analytics.viewItem('prod-123', 'Notebook', 'eletrônicos', 2999.99)
analytics.addToCart('prod-123', 'Notebook', 2999.99, 1)
analytics.purchase('order-456', 2999.99, 'BRL', [
  { product_id: 'prod-123', product_name: 'Notebook', price: 2999.99, quantity: 1 }
])

// Autenticação
analytics.signup('email', { plan: 'premium' })
analytics.login('google')

// Vídeo
analytics.videoPlay('video-123', 'Tutorial', 1800)
analytics.videoPause('video-123', 450)
analytics.videoComplete('video-123', 1800)

// Formulário
analytics.formStart('contact-form', 'Contato')
analytics.formSubmit('contact-form', 'Contato', { fields: 5 })

// Busca
analytics.search('typescript', 'docs')

// Customizado
analytics.track('newsletter_signup', { source: 'footer' })
```

## 🔧 Configuração

| Opção | Tipo | Default | Descrição |
|-------|------|---------|-----------|
| `siteKey` | `string` | - | **Obrigatório**. Chave do site |
| `endpoint` | `string` | - | **Obrigatório**. URL do endpoint |
| `batchSize` | `number` | `10` | Eventos por batch |
| `flushIntervalMs` | `number` | `3000` | Intervalo de flush (ms) |
| `respectDNT` | `boolean` | `true` | Respeitar Do Not Track |
| `autoPageview` | `boolean` | `true` | Pageview automático |

## 📊 Payload Automático

Cada evento inclui automaticamente:
- `ts`, `url`, `path`, `referrer`
- `anon_id`, `session_id`, `user_id` (se identificado)
- `lang`, `tz`, `viewport`, `screen`
- `utm` (se presente na URL)
- `props` (customizado)

**Header automático**: `x-country` (detectado via browser)

## 🔒 Privacidade

- Respeita `navigator.doNotTrack === '1'`
- Sistema de consent: `analytics.setConsent('granted' | 'denied')`
- Armazena apenas `anon_id` (localStorage) e `session_id` (sessionStorage)
- Sem cookies de terceiros

## 🚀 Batching

Eventos são agrupados automaticamente:
- Flush quando atinge `batchSize` eventos
- Flush a cada `flushIntervalMs` ms
- Flush em `visibilitychange` e `beforeunload`
- Deduplicação automática (500ms)

## 📄 Licença

MIT © Rafael Coelho