npm - @agenus-io/recovery - Versions diffs - 0.0.2 → 0.0.4 - Mend

@agenus-io/recovery 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +426 -617
package/package.json +13 -2

package/README.md CHANGED Viewed

@@ -1,747 +1,556 @@
-# GomarkePixel
+#  @agenus-io/recovery
-Pixel Tracker avançado para Facebook e Google Analytics - Envia eventos para sua própria API via `sendBeacon` (com fallback para `fetch`). Inclui sistema de auto-tracking inteligente com arquitetura orientada a objetos e máxima escalabilidade.
+[![npm version](https://img.shields.io/npm/v/@agenus-io/recovery.svg)](https://www.npmjs.com/package/@agenus-io/recovery)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
-## 🚀 Instalação
+Sistema robusto de recuperação de abandono de formulários para capturar leads que não completaram o preenchimento. Detecta automaticamente quando usuários preenchem formulários mas não os enviam, capturando os dados preenchidos e enviando para sua API.
-### Via CDN (Recomendado)
+**Repositório**: [github.com/techionext/upsely-recovery](https://github.com/techionext/upsely-recovery)
-```html
-<script src="https://unpkg.com/gomarke-pixel@latest/dist/index.global.js"></script>
-```
+## 🚀 Características
+- ✅ **Detecção Automática**: Monitora interações do usuário com formulários automaticamente
+- ✅ **Captura Inteligente**: Coleta dados de todos os campos preenchidos
+- ✅ **Sessão Persistente**: Sistema de sessão com localStorage e cookies
+- ✅ **Fingerprint de Dispositivo**: Identificação única do dispositivo
+- ✅ **Envio Confiável**: Usa `sendBeacon` com fallback para `fetch` com `keepalive`
+- ✅ **Auto-inicialização**: Suporte a inicialização via script tag
+- ✅ **TypeScript**: Totalmente tipado para melhor DX
+- ✅ **Zero Dependencies**: Apenas `ua-parser-js` para detecção de dispositivo
+## 📦 Instalação
 ### Via NPM
 ```bash
-npm install gomarke-pixel
+npm install @agenus-io/recovery
 # ou
-pnpm add gomarke-pixel
+pnpm add @agenus-io/recovery
 # ou
-yarn add gomarke-pixel
+yarn add @agenus-io/recovery
+```
+### Via CDN
+```html
+<script src="https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js"></script>
 ```
 ## 📖 Uso
-### 🚀 Auto-Tracking Automático - Configure Uma Vez e Esqueça!
+### Inicialização Manual
-O GomarkePixel agora funciona de forma **completamente automática**! Você só precisa configurar uma vez e todos os eventos são detectados automaticamente.
+```javascript
+import UpselyRecovery from '@agenus-io/recovery';
-### Uso Global (CDN) - Auto-Tracking Automático
+const recovery = new UpselyRecovery({
+  apiEndpoint: 'https://sua-api.com/pixel/public/event',
+  apiKey: 'sua-chave-api',
+  debug: true, // Ativa logs no console
+  timeout: 5000
+});
+```
+### Auto-inicialização via Script Tag
 ```html
 <!DOCTYPE html>
 <html>
-  <head>
-    <script src="https://unpkg.com/gomarke-pixel@latest/dist/index.global.js"></script>
-  </head>
-  <body>
-    <!-- Elementos com data attributes para auto-tracking -->
-    <button
-      data-add-to-cart
-      data-product-id="123"
-      data-product-name="iPhone 15"
-      data-product-price="8999"
-    >
-      Adicionar ao Carrinho
-    </button>
-    <button data-checkout data-cart-total="8999">Finalizar Compra</button>
-    <form data-lead>
-      <input name="email" placeholder="Email" required />
-      <input name="name" placeholder="Nome" required />
-      <button type="submit">Enviar</button>
-    </form>
-    <script>
-      // Inicializar o pixel tracker com auto-tracking
-      const pixel = new GomarkePixel({
-        apiEndpoint: 'https://sua-api.com/track',
-        apiKey: 'sua-chave-aqui',
-        debug: true,
-        // Configuração de auto-tracking - TUDO AUTOMÁTICO! 🚀
-        autoTracks: {
-          addToCart: {
-            enabled: true,
-            selector: '[data-add-to-cart]',
-            selectorType: 'attribute',
-            productDataSelectors: {
-              id: '[data-product-id]',
-              name: '[data-product-name]',
-              price: '[data-product-price]',
-            },
-          },
-          initiateCheckout: {
-            enabled: true,
-            selector: '[data-checkout]',
-            selectorType: 'attribute',
-            cartDataSelectors: {
-              total: '[data-cart-total]',
-            },
-          },
-          lead: {
-            enabled: true,
-            selector: 'form[data-lead]',
-            selectorType: 'attribute',
-            requiredFields: ['email', 'name'],
-          },
-          scroll: {
-            enabled: true,
-            scrollThresholds: [25, 50, 75, 90],
-          },
-        },
-      });
-      // Page view é automático, mas você ainda pode usar manualmente se quiser
-      // pixel.trackPageView();
-      // pixel.trackAddToCart('produto-123', 'Produto Exemplo', 99.90, 'BRL', 'Categoria');
-      // pixel.trackPurchase(199.90, 'BRL', 'txn_123');
-    </script>
-  </body>
+<head>
+  <script
+    src="https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js"
+    data-api-endpoint="https://sua-api.com/pixel/public/event"
+    data-api-key="sua-chave-api"
+    data-debug="true"
+    data-timeout="5000"
+  ></script>
+</head>
+<body>
+  <form id="contactForm">
+    <input type="text" name="nome" placeholder="Nome" />
+    <input type="email" name="email" placeholder="Email" />
+    <textarea name="mensagem" placeholder="Mensagem"></textarea>
+    <button type="submit">Enviar</button>
+  </form>
+</body>
 </html>
 ```
-### Uso em Módulos - Auto-Tracking Automático
+O sistema será inicializado automaticamente e estará disponível em `window.upselyRecovery`.
-```javascript
-import GomarkePixel from 'gomarke-pixel';
+## 🔧 Configuração
-const pixel = new GomarkePixel({
-  apiEndpoint: 'https://sua-api.com/track',
-  apiKey: 'sua-chave-aqui',
-  debug: true,
+### Interface de Configuração
-  // Auto-tracking automático - configure uma vez e esqueça! 🚀
-  autoTracks: {
-    addToCart: {
-      enabled: true,
-      selector: '.add-to-cart-btn',
-      selectorType: 'class',
-      productDataSelectors: {
-        id: '.product-id',
-        name: '.product-name',
-        price: '.product-price',
-        category: '.product-category',
-      },
-    },
-    initiateCheckout: {
-      enabled: true,
-      selector: '.checkout-btn',
-      selectorType: 'class',
-      trackOnNavigation: true,
-      navigationSelectors: ['.checkout-link', '.finalizar-compra'],
-    },
-    lead: {
-      enabled: true,
-      selector: 'form.contact-form',
-      selectorType: 'class',
-      trackOnFieldFocus: true,
-      requiredFields: ['email', 'name'],
-      validationRules: {
-        email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-      },
-    },
-    scroll: {
-      enabled: true,
-      scrollThresholds: [25, 50, 75, 90],
-      trackScrollDepth: true,
-      trackTimeOnPage: true,
-    },
-    viewport: {
-      enabled: true,
-      selector: '.trackable-element',
-      selectorType: 'class',
-      trackElementIntersection: true,
-      trackElementClicks: true,
-    },
-  },
+```typescript
+interface UpselyRecoveryConfig {
+  apiEndpoint: string;  // URL da sua API (obrigatório)
+  apiKey?: string;      // Chave de autenticação
+  debug?: boolean;       // Ativar logs de debug (padrão: false)
+  timeout?: number;     // Timeout para requests em ms (padrão: 5000)
+  version?: string;     // Versão do script
+}
+```
+### Exemplo Completo
+```javascript
+const recovery = new UpselyRecovery({
+  apiEndpoint: 'https://api.exemplo.com/pixel/public/event',
+  apiKey: 'sua-chave-secreta',
+  debug: true,
+  timeout: 10000
 });
-// Page view é automático! Os autoTracks detectam tudo sozinhos
-// Não precisa chamar manualmente:
-// await pixel.trackPageView();
-// await pixel.trackAddToCart('produto-123', 'Produto Exemplo', 99.90);
+// O sistema já está monitorando todos os formulários na página!
+// Quando o usuário preencher campos e fechar a página, os dados serão enviados automaticamente.
 ```
-## 🔧 Configuração
+## 📊 Como Funciona
-### Configuração Básica (Sem Auto-Tracking)
+### 1. Detecção de Interação
+O sistema monitora automaticamente:
+- Eventos `focus` em campos de formulário
+- Eventos `change` e `input` em campos
+- Qualquer interação com `input`, `textarea` ou `select`
+### 2. Detecção de Abandono
+O sistema detecta abandono quando:
+- Usuário tenta fechar a página (`beforeunload`)
+- Aba fica oculta (`visibilitychange`)
+- Página está sendo descarregada (`pagehide`)
+### 3. Captura de Dados
+Quando o abandono é detectado, o sistema:
+- Coleta todos os campos preenchidos de todos os formulários
+- Trata diferentes tipos de campos (text, email, checkbox, radio, select)
+- Ignora campos vazios
+- Prepara payload com metadados completos
+### 4. Envio de Dados
+Os dados são enviados com:
+- **sendBeacon** (prioridade) - mais confiável para eventos de saída
+- **fetch com keepalive** (fallback) - garante envio mesmo se sendBeacon falhar
+- Retry automático em caso de falha
+## 📤 Estrutura dos Dados Enviados
 ```typescript
-interface GomarkePixelConfig {
-  apiEndpoint: string; // URL da sua API (obrigatório)
-  apiKey?: string; // Chave de autenticação
-  debug?: boolean; // Ativar logs de debug
-  timeout?: number; // Timeout para requests (padrão: 5000ms)
+{
+  event_type: 'form_abandonment',
+  forms: [
+    {
+      form_id: 'contactForm',
+      form_index: 0,
+      fields: {
+        nome: 'João Silva',
+        email: 'joao@exemplo.com',
+        mensagem: 'Olá, gostaria de mais informações...'
+      },
+      field_count: 3
+    }
+  ],
+  total_forms: 1,
+  timestamp: 1234567890123
 }
 ```
-### Configuração com Auto-Tracking Automático
+### Payload Completo do Evento
 ```typescript
-interface GomarkePixelConfig {
-  apiEndpoint: string;
-  apiKey?: string;
-  debug?: boolean;
-  timeout?: number;
-  // 🚀 AUTO-TRACKING - Configure uma vez e esqueça!
-  autoTracks?: {
-    addToCart?: {
-      enabled?: boolean;
-      selector?: string;
-      selectorType?:
-        | 'class'
-        | 'id'
-        | 'attribute'
-        | 'tag'
-        | 'text'
-        | 'url'
-        | 'data-attribute'
-        | 'custom';
-      productDataSelectors?: {
-        id?: string;
-        name?: string;
-        price?: string;
-        category?: string;
-        image?: string;
-      };
-    };
-    initiateCheckout?: {
-      enabled?: boolean;
-      selector?: string;
-      selectorType?:
-        | 'class'
-        | 'id'
-        | 'attribute'
-        | 'tag'
-        | 'text'
-        | 'url'
-        | 'data-attribute'
-        | 'custom';
-      trackOnNavigation?: boolean;
-      navigationSelectors?: string[];
-    };
-    lead?: {
-      enabled?: boolean;
-      selector?: string;
-      selectorType?:
-        | 'class'
-        | 'id'
-        | 'attribute'
-        | 'tag'
-        | 'text'
-        | 'url'
-        | 'data-attribute'
-        | 'custom';
-      trackOnFieldFocus?: boolean;
-      trackOnFieldBlur?: boolean;
-      trackOnFieldChange?: boolean;
-      requiredFields?: string[];
-      validationRules?: {
-        email?: RegExp;
-        phone?: RegExp;
-        minLength?: number;
-      };
-    };
-    scroll?: {
-      enabled?: boolean;
-      scrollThresholds?: number[];
-      trackScrollDepth?: boolean;
-      trackTimeOnPage?: boolean;
-    };
-    viewport?: {
-      enabled?: boolean;
-      selector?: string;
-      selectorType?:
-        | 'class'
-        | 'id'
-        | 'attribute'
-        | 'tag'
-        | 'text'
-        | 'url'
-        | 'data-attribute'
-        | 'custom';
-      trackElementIntersection?: boolean;
-      trackElementClicks?: boolean;
-      trackElementHovers?: boolean;
-    };
-  };
+{
+  data: {
+    event_type: 'form_abandonment',
+    forms: [...],
+    total_forms: 1,
+    timestamp: 1234567890123
+  },
+  sessionId: 'session_1234567890_abc123',
+  timestamp: 1234567890123,
+  fingerprint: 'hash256_do_dispositivo',
+  user_agent: 'Mozilla/5.0...',
+  page: {
+    url: 'https://exemplo.com/contato',
+    title: 'Página de Contato',
+    referrer: 'https://google.com',
+    path: '/contato',
+    hostname: 'exemplo.com'
+  },
+  device: {
+    id: 'uuid-do-dispositivo',
+    type: 'desktop' | 'mobile' | 'tablet',
+    os: {
+      name: 'Windows' | 'Mac OS' | 'Linux' | 'iOS' | 'Android',
+      version: '10.0'
+    },
+    browser: {
+      name: 'Chrome' | 'Firefox' | 'Safari' | 'Edge',
+      version: '120.0'
+    },
+    engine: {
+      name: 'Blink',
+      version: '120.0'
+    },
+    language: 'pt-BR',
+    screen: {
+      width: 1920,
+      height: 1080,
+      pixel_ratio: 1
+    }
+  },
+  meta: {
+    version: '0.0.2',
+    recovery_source: 'upsely',
+    environment: 'production',
+    script_url: 'https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js'
+  },
+  query_params: {
+    utm_source: 'google',
+    utm_medium: 'cpc'
+  }
 }
 ```
-## 📚 API - Eventos de E-commerce
+## 🎯 API
-### Eventos Principais (Tracks)
+### Métodos Principais
-- `trackPageView(page?: string)`: Track page view
-- `trackPurchase(value, currency, transactionId?, items?)`: Track compra
-- `trackAddToCart(itemId, itemName, value?, currency?, category?, quantity?)`: Adicionar ao carrinho
-- `trackRemoveFromCart(itemId, itemName, value?, currency?, quantity?)`: Remover do carrinho
-- `trackInitiateCheckout(value?, currency?, items?)`: Iniciar checkout
-- `trackViewItem(itemId, itemName, value?, currency?, category?)`: Ver produto
-- `trackSearch(searchTerm, resultsCount?)`: Busca
-- `trackCustomEvent(eventName, eventCategory?, value?, currency?, customParameters?)`: Evento customizado
+#### `getSessionId(): string`
-### Auto-Tracking Inteligente
+Retorna o ID da sessão atual.
-O GomarkePixel agora inclui um sistema avançado de auto-tracking que detecta automaticamente interações do usuário:
+```javascript
+const sessionId = recovery.getSessionId();
+console.log(sessionId); // 'session_1234567890_abc123'
+```
-#### AutoTracks Básicos
+#### `getSessionData(): ISessionData`
-- **AutoAddToCart**: Detecta automaticamente cliques em botões "Adicionar ao Carrinho"
-- **AutoInitiateCheckout**: Detecta automaticamente cliques em botões "Finalizar Compra"
-- **AutoLead**: Detecta automaticamente submissões de formulários de lead
+Retorna dados completos da sessão.
-#### AutoTracks Avançados
+```javascript
+const sessionData = recovery.getSessionData();
+console.log(sessionData);
+// {
+//   sessionId: 'session_1234567890_abc123',
+//   lastActivity: 1234567890123,
+//   createdAt: 1234567890000,
+//   visitCount: 5,
+//   firstVisit: 1234567890000
+// }
+```
-- **ScrollTracker**: Rastreia profundidade de scroll e tempo na página
-- **ViewportTracker**: Detecta quando elementos entram/saem do viewport
+#### `isSessionActive(): boolean`
-#### Configuração de AutoTracks
+Verifica se a sessão está ativa (não expirada).
 ```javascript
-// Configurar auto-tracking
-const pixel = new GomarkePixel({
-  apiEndpoint: 'https://sua-api.com/track',
-  apiKey: 'sua-chave',
-  debug: true,
-});
-// Auto-tracking de Add to Cart
-await pixel
-  .getTrackerFactory()
-  .getAutoTrackerFactory()
-  .createAddToCartTracker({
-    isEnabled: true,
-    selector: '.add-to-cart-btn',
-    selectorType: 'class',
-    productDataSelectors: {
-      id: '.product-id',
-      name: '.product-name',
-      price: '.product-price',
-      category: '.product-category',
-    },
-  });
-// Auto-tracking de Checkout
-await pixel
-  .getTrackerFactory()
-  .getAutoTrackerFactory()
-  .createInitiateCheckoutTracker({
-    isEnabled: true,
-    selector: '.checkout-btn',
-    selectorType: 'class',
-    trackOnNavigation: true,
-    navigationSelectors: ['.checkout-link', '.finalizar-compra'],
-  });
-// Auto-tracking de Lead
-await pixel
-  .getTrackerFactory()
-  .getAutoTrackerFactory()
-  .createLeadTracker({
-    isEnabled: true,
-    selector: 'form.lead-form',
-    selectorType: 'class',
-    trackOnFieldFocus: true,
-    trackOnFieldBlur: true,
-    requiredFields: ['email', 'name'],
-  });
+if (recovery.isSessionActive()) {
+  console.log('Sessão ativa!');
+}
 ```
-### Exemplo Completo
+#### `updateSessionActivity(): void`
+Atualiza a última atividade da sessão.
 ```javascript
-const pixel = new GomarkePixel({
-  apiEndpoint: 'https://sua-api.com/track',
-  apiKey: 'sua-chave',
-  debug: true,
-});
+recovery.updateSessionActivity();
+```
-// Page view automático
-// Track view de produto
-await pixel.trackViewItem(
-  'produto-123',
-  'iPhone 15',
-  8999,
-  'BRL',
-  'Smartphones'
-);
-// Adicionar ao carrinho
-await pixel.trackAddToCart(
-  'produto-123',
-  'iPhone 15',
-  8999,
-  'BRL',
-  'Smartphones',
-  1
-);
-// Iniciar checkout
-await pixel.trackInitiateCheckout(8999, 'BRL', [
-  {
-    item_id: 'produto-123',
-    item_name: 'iPhone 15',
-    category: 'Smartphones',
-    quantity: 1,
-    price: 8999,
-  },
-]);
-// Finalizar compra
-await pixel.trackPurchase(8999, 'BRL', 'txn_123', [
-  {
-    item_id: 'produto-123',
-    item_name: 'iPhone 15',
-    category: 'Smartphones',
-    quantity: 1,
-    price: 8999,
-  },
-]);
+#### `renewSession(): void`
+Renova a sessão (cria nova se expirada).
+```javascript
+recovery.renewSession();
 ```
-## 🛠️ Desenvolvimento
+#### `clearSession(): void`
-### Instalação das Dependências
+Limpa todos os dados da sessão.
-```bash
-pnpm install
+```javascript
+recovery.clearSession();
 ```
-### Scripts Disponíveis
+#### `getConfig(): UpselyRecoveryConfig`
-```bash
-# Desenvolvimento com watch
-pnpm dev
+Retorna a configuração atual.
-# Build para produção
-pnpm build
+```javascript
+const config = recovery.getConfig();
+console.log(config);
+```
-# Linting
-pnpm lint
-pnpm lint:fix
+#### `updateConfig(newConfig: Partial<UpselyRecoveryConfig>): void`
-# Formatação
-pnpm format
+Atualiza a configuração.
-# Verificação de tipos
-pnpm type-check
+```javascript
+recovery.updateConfig({
+  debug: false,
+  timeout: 10000
+});
 ```
-### Estrutura do Projeto
+#### `destroyFormAbandonment(): void`
+Destrói o sistema de abandono (remove listeners).
+```javascript
+recovery.destroyFormAbandonment();
 ```
-src/
-├── index.ts                    # Ponto de entrada principal
-├── config.ts                   # Configurações globais
-├── types.ts                    # Definições de tipos
-├── utils/                      # Utilitários
-│   ├── getFingerprint.ts
-│   └── sendEvent.tsx
-├── tracks/                     # Sistema de tracking manual
-│   ├── BaseTracker.ts          # Classe base para todos os trackers
-│   ├── pageView.ts
-│   ├── purchase.ts
-│   ├── addToCart.ts
-│   ├── initiateCheckout.ts
-│   ├── lead.ts
-│   ├── TrackerFactory.ts       # Factory para gerenciar trackers
-│   └── index.ts
-├── autoTracks/                 # Sistema de auto-tracking
-│   ├── BaseAutoTracker.ts      # Classe base para auto-trackers
-│   ├── autoAddToCart.ts        # Auto-tracking de adicionar ao carrinho
-│   ├── autoInitiateCheckout.ts # Auto-tracking de checkout
-│   ├── autoLead.tsx            # Auto-tracking de leads
-│   ├── AutoTrackerFactory.ts   # Factory para auto-trackers
-│   ├── utils/                  # Utilitários para auto-tracking
-│   │   ├── SelectorUtils.ts    # Utilitários de seleção DOM
-│   │   └── EventManager.ts     # Gerenciador de eventos
-│   ├── advanced/               # Auto-trackers avançados
-│   │   ├── ScrollTracker.ts    # Rastreamento de scroll
-│   │   └── ViewportTracker.ts  # Rastreamento de viewport
-│   └── index.ts
-└── examples/                   # Exemplos de uso
-    ├── usage-example.ts
-    └── autotrack-usage-example.ts
-dist/                          # Arquivos compilados
-├── index.global.js           # Versão IIFE para CDN
-├── index.cjs.js              # CommonJS
-├── index.esm.js              # ES Modules
-├── index.d.ts                # Definições TypeScript
-└── index.d.mts               # Definições TypeScript (ESM)
+## 🧪 Exemplos
+### Exemplo Básico
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Formulário de Contato</title>
+</head>
+<body>
+  <form id="contactForm">
+    <input type="text" name="nome" placeholder="Nome completo" required />
+    <input type="email" name="email" placeholder="Seu email" required />
+    <input type="tel" name="telefone" placeholder="Telefone" />
+    <textarea name="mensagem" placeholder="Sua mensagem"></textarea>
+    <button type="submit">Enviar</button>
+  </form>
+  <script src="https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js"></script>
+  <script>
+    const recovery = new UpselyRecovery({
+      apiEndpoint: 'https://sua-api.com/pixel/public/event',
+      apiKey: 'sua-chave-api',
+      debug: true
+    });
+    // O sistema já está monitorando o formulário!
+    // Se o usuário preencher e fechar a página, os dados serão capturados.
+  </script>
+</body>
+</html>
 ```
-## ✨ Por que Auto-Tracking?
+### Exemplo com Múltiplos Formulários
-### 🎯 **Configure Uma Vez, Funcione Para Sempre**
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <!-- Formulário de Newsletter -->
+  <form id="newsletterForm">
+    <input type="email" name="email" placeholder="Email" />
+    <button type="submit">Inscrever-se</button>
+  </form>
+  <!-- Formulário de Contato -->
+  <form id="contactForm">
+    <input type="text" name="nome" placeholder="Nome" />
+    <input type="email" name="email" placeholder="Email" />
+    <textarea name="mensagem" placeholder="Mensagem"></textarea>
+    <button type="submit">Enviar</button>
+  </form>
+  <script src="https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js"></script>
+  <script>
+    new UpselyRecovery({
+      apiEndpoint: 'https://sua-api.com/pixel/public/event',
+      apiKey: 'sua-chave-api',
+      debug: true
+    });
+    // Ambos os formulários são monitorados automaticamente!
+  </script>
+</body>
+</html>
+```
-- **Zero Código Manual**: Não precisa chamar `trackAddToCart()`, `trackLead()`, etc.
-- **Detecção Automática**: Detecta cliques, formulários, scroll, viewport automaticamente
-- **DOM Dinâmico**: Funciona com elementos adicionados via JavaScript/AJAX
-- **Performance Otimizada**: Debouncing, throttling e lazy loading automáticos
-- **Validação Inteligente**: Valida formulários automaticamente
-- **Retry Logic**: Tenta novamente se elementos ainda não carregaram
+### Exemplo com TypeScript
-### 🚀 **Exemplo: Antes vs Depois**
+```typescript
+import UpselyRecovery from '@agenus-io/recovery';
+import type { UpselyRecoveryConfig } from '@agenus-io/recovery';
-#### ❌ **Antes (Manual)**
+const config: UpselyRecoveryConfig = {
+  apiEndpoint: 'https://sua-api.com/pixel/public/event',
+  apiKey: 'sua-chave-api',
+  debug: process.env.NODE_ENV === 'development',
+  timeout: 10000
+};
-```javascript
-// Tinha que chamar manualmente para cada evento
-pixel.trackPageView();
-document.querySelector('.add-to-cart').addEventListener('click', () => {
-  pixel.trackAddToCart('produto-123', 'Produto', 99.9);
-});
-document.querySelector('form').addEventListener('submit', () => {
-  pixel.trackLead({ email: 'user@email.com' });
-});
-// ... mais código manual para cada interação
-```
+const recovery = new UpselyRecovery(config);
-#### ✅ **Depois (Automático)**
+// Verificar sessão
+if (recovery.isSessionActive()) {
+  console.log('Sessão ativa:', recovery.getSessionId());
+}
-```javascript
-// Configure uma vez e esqueça!
-const pixel = new GomarkePixel({
-  apiEndpoint: 'https://sua-api.com/track',
-  autoTracks: {
-    addToCart: { enabled: true, selector: '[data-add-to-cart]' },
-    lead: { enabled: true, selector: 'form[data-lead]' },
-    scroll: { enabled: true },
-  },
+// Atualizar configuração em runtime
+recovery.updateConfig({
+  debug: false
 });
-// TUDO FUNCIONA AUTOMATICAMENTE! 🎉
 ```
-## 🏗️ Arquitetura Avançada
-### Sistema de Classes Orientado a Objetos
+## 🛠️ Desenvolvimento
-O GomarkePixel foi completamente refatorado para usar uma arquitetura orientada a objetos com máxima escalabilidade:
+### Pré-requisitos
-#### Tracks (Tracking Manual)
+- Node.js >= 18
+- pnpm >= 8
-- **BaseTracker**: Classe abstrata base para todos os trackers
-- **TrackerFactory**: Factory pattern para gerenciar instâncias de trackers
-- **PageViewTracker**, **PurchaseTracker**, **AddToCartTracker**, etc.
+### Instalação
-#### AutoTracks (Tracking Automático)
+```bash
+# Clonar repositório
+git clone https://github.com/agenus-io/recovery.git
+cd recovery
-- **BaseAutoTracker**: Classe abstrata base para auto-trackers
-- **AutoTrackerFactory**: Factory pattern para gerenciar auto-trackers
-- **SelectorUtils**: Utilitários avançados para seleção DOM
-- **EventManager**: Gerenciador de eventos com debouncing/throttling
+# Instalar dependências
+pnpm install
+```
-### Funcionalidades Avançadas
+### Scripts Disponíveis
-#### 🎯 Auto-Tracking Inteligente
+```bash
+# Desenvolvimento com watch
+pnpm dev
-- **Detecção Automática**: Detecta interações sem configuração manual
-- **DOM Dinâmico**: Suporte a elementos adicionados dinamicamente via MutationObserver
-- **Retry Logic**: Sistema de retry automático para elementos que ainda não carregaram
-- **Debouncing/Throttling**: Otimização de performance para eventos frequentes
+# Build para produção
+pnpm build
-#### 🔧 Configuração Flexível
+# Linting
+pnpm lint
+pnpm lint:fix
-- **Múltiplos Seletores**: Suporte a class, id, attribute, tag, text, url, data-attribute, custom
-- **Extração de Dados**: Seletores configuráveis para extrair dados de produtos/carrinho
-- **Validação**: Sistema de validação de formulários
-- **Callbacks Customizados**: Funções de callback para processamento customizado
+# Formatação de código
+pnpm format
-#### 📊 Estatísticas e Monitoramento
+# Verificação de tipos
+pnpm type-check
-- **Estatísticas Detalhadas**: Contadores de eventos, performance, erros
-- **Debug Avançado**: Logs detalhados para desenvolvimento
-- **Health Checks**: Verificação de saúde dos trackers
+# Limpar arquivos gerados
+pnpm clean
+```
-#### 🚀 Performance
+### Estrutura do Projeto
-- **Lazy Loading**: Carregamento sob demanda de auto-trackers
-- **Memory Management**: Limpeza automática de listeners
-- **Bundle Optimization**: Tree-shaking para reduzir tamanho do bundle
+```
+src/
+├── index.ts                    # Ponto de entrada principal
+├── init.ts                     # Classe principal UpselyRecovery
+├── config.ts                   # Configurações globais
+├── types.ts                    # Definições de tipos TypeScript
+└── utils/                      # Utilitários
+    ├── formAbandonment.ts      # Sistema de detecção de abandono
+    ├── getFormData.ts          # Captura de dados de formulários
+    ├── getSession.ts           # Gerenciamento de sessão
+    ├── getFingerprint.ts       # Geração de fingerprint
+    ├── getDeviceInfo.ts        # Informações do dispositivo
+    ├── sendEvent.tsx           # Envio de eventos
+    └── parseConfigFromScriptTag.ts  # Parser de configuração
+```
 ## 📦 Build
 O projeto usa `tsup` para gerar múltiplos formatos:
-- **IIFE** (`.global.js`): Para uso via CDN
-- **CommonJS** (`.cjs.js`): Para Node.js
-- **ES Modules** (`.esm.js`): Para bundlers modernos
-- **TypeScript** (`.d.ts`): Definições de tipos
+- **CommonJS** (`dist/index.cjs.js`): Para Node.js e bundlers antigos
+- **ES Modules** (`dist/index.esm.js`): Para bundlers modernos
+- **IIFE** (`dist/index.global.js`): Para uso direto no browser via CDN
+- **TypeScript** (`dist/index.d.ts`): Definições de tipos
-## 🎯 Exemplos Avançados
+## 🚀 Publicação
-### Auto-Tracking Completo para E-commerce
+Para informações sobre como publicar novas versões no NPM, consulte o [README-RELEASE.md](./README-RELEASE.md).
-```javascript
-const pixel = new GomarkePixel({
-  apiEndpoint: 'https://sua-api.com/track',
-  apiKey: 'sua-chave',
-  debug: true,
-});
+### Comandos Rápidos
-// Configurar todos os auto-trackers
-const autoFactory = pixel.getTrackerFactory().getAutoTrackerFactory();
-// Auto-tracking de produtos
-await autoFactory.createAddToCartTracker({
-  isEnabled: true,
-  selector: '[data-add-to-cart]',
-  selectorType: 'attribute',
-  productDataSelectors: {
-    id: '[data-product-id]',
-    name: '.product-title',
-    price: '.price-value',
-    category: '.product-category',
-  },
-  customDataExtractor: element => ({
-    brand: element.dataset.brand,
-    variant: element.dataset.variant,
-  }),
-});
+```bash
+# Criar changeset
+pnpm changeset:add
-// Auto-tracking de checkout
-await autoFactory.createInitiateCheckoutTracker({
-  isEnabled: true,
-  selector: '.checkout-button',
-  selectorType: 'class',
-  trackOnNavigation: true,
-  navigationSelectors: ['.checkout-link', '.finalizar-compra'],
-  cartDataSelectors: {
-    total: '.cart-total',
-    currency: '.cart-currency',
-    items: '.cart-item',
-  },
-});
+# Preparar release
+pnpm run release:full
-// Auto-tracking de leads
-await autoFactory.createLeadTracker({
-  isEnabled: true,
-  selector: 'form.contact-form',
-  selectorType: 'class',
-  trackOnFieldFocus: true,
-  trackOnFieldBlur: true,
-  trackOnFieldChange: true,
-  requiredFields: ['email', 'name'],
-  validationRules: {
-    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-    phone: /^\(\d{2}\)\s\d{4,5}-\d{4}$/,
-  },
-});
+# Publicar no NPM
+pnpm run release:publish
 ```
-### Auto-Tracking Avançado
+## 🔒 Privacidade e Segurança
-```javascript
-// Scroll tracking
-const scrollTracker = new ScrollTracker(
-  pixel.config,
-  pixel.sessionId,
-  pixel.version
-);
-await scrollTracker.initialize({
-  isEnabled: true,
-  scrollThresholds: [25, 50, 75, 90],
-  trackScrollDepth: true,
-  trackTimeOnPage: true,
-  debounceMs: 300,
-});
+- ✅ **Dados Locais**: Sessão armazenada apenas localmente (localStorage + cookies)
+- ✅ **Sem Tracking Cross-Site**: Não rastreia usuários entre sites
+- ✅ **Fingerprint Anônimo**: Fingerprint não contém informações pessoais
+- ✅ **HTTPS Recomendado**: Use sempre HTTPS em produção
+- ✅ **Sanitização**: Considere sanitizar dados sensíveis no backend
-// Viewport tracking
-const viewportTracker = new ViewportTracker(
-  pixel.config,
-  pixel.sessionId,
-  pixel.version
-);
-await viewportTracker.initialize({
-  isEnabled: true,
-  selector: '.trackable-element',
-  selectorType: 'class',
-  trackElementIntersection: true,
-  trackElementClicks: true,
-  trackElementHovers: true,
-  visibilityThreshold: 0.5,
-  maxTrackingElements: 100,
-});
-```
+## 🐛 Troubleshooting
-### Monitoramento e Estatísticas
+### O sistema não está detectando abandono
-```javascript
-// Obter estatísticas dos trackers
-const stats = pixel.getTrackerStats();
-console.log('Estatísticas dos trackers:', stats);
-// Obter estatísticas dos auto-trackers
-const autoStats = pixel
-  .getTrackerFactory()
-  .getAutoTrackerFactory()
-  .getFactoryStats();
-console.log('Estatísticas dos auto-trackers:', autoStats);
-// Parar todos os auto-trackers
-await pixel.getTrackerFactory().getAutoTrackerFactory().stopAllAutoTrackers();
-// Reconstruir todos os auto-trackers (útil para DOM dinâmico)
-await pixel
-  .getTrackerFactory()
-  .getAutoTrackerFactory()
-  .rebuildAllAutoTrackers();
-```
+1. Verifique se `debug: true` está ativado
+2. Abra o console do navegador (F12)
+3. Verifique se há logs `[FormAbandonment]`
+4. Certifique-se de que o usuário interagiu com pelo menos um campo
-## 🚀 Publicação
+### Dados não estão sendo enviados
-```bash
-# Build antes de publicar
-pnpm build
+1. Verifique se `apiEndpoint` está correto
+2. Verifique se a API está acessível (CORS configurado)
+3. Verifique o console para erros
+4. Teste a API manualmente com `fetch` ou `curl`
-# Publicar no NPM
-npm publish
-```
+### Sessão não persiste
+1. Verifique se localStorage está habilitado
+2. Verifique se cookies estão habilitados
+3. Verifique se não está em modo anônimo/privado
+4. Verifique se o domínio permite cookies
-## 🆕 Changelog
+## 📄 Licença
-### v2.0.0 - Refatoração Completa
+MIT
-#### ✨ Novas Funcionalidades
+## 🤝 Contribuindo
-- **Sistema de Auto-Tracking**: Detecção automática de interações do usuário
-- **Arquitetura Orientada a Objetos**: Classes base e factory patterns
-- **AutoTracks Avançados**: ScrollTracker e ViewportTracker
-- **Sistema de Seletores**: Suporte a múltiplos tipos de seletores
-- **Extração de Dados**: Seletores configuráveis para dados de produtos
-- **Validação de Formulários**: Sistema de validação com regras customizadas
-- **Monitoramento**: Estatísticas detalhadas e health checks
+Contribuições são bem-vindas! Por favor:
-#### 🔧 Melhorias Técnicas
+1. Faça fork do projeto: [github.com/techionext/upsely-recovery](https://github.com/techionext/upsely-recovery)
+2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
+3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
+4. Push para a branch (`git push origin feature/AmazingFeature`)
+5. Abra um Pull Request no GitHub
-- **TypeScript**: Tipagem completa e type safety
-- **Performance**: Debouncing, throttling e lazy loading
-- **DOM Dinâmico**: Suporte a elementos adicionados dinamicamente
-- **Retry Logic**: Sistema de retry automático
-- **Memory Management**: Limpeza automática de listeners
-- **Bundle Optimization**: Tree-shaking e otimizações
+### Reportar Bugs
-#### 🏗️ Arquitetura
+Se encontrar algum bug, por favor abra uma [issue no GitHub](https://github.com/techionext/upsely-recovery/issues) com:
+- Descrição do problema
+- Passos para reproduzir
+- Comportamento esperado vs comportamento atual
+- Ambiente (navegador, versão, etc.)
-- **BaseTracker**: Classe base para trackers manuais
-- **BaseAutoTracker**: Classe base para auto-trackers
-- **TrackerFactory**: Factory para gerenciar trackers
-- **AutoTrackerFactory**: Factory para gerenciar auto-trackers
-- **SelectorUtils**: Utilitários avançados de seleção DOM
-- **EventManager**: Gerenciador de eventos otimizado
+## 📞 Suporte
-#### 📊 Monitoramento
+Para suporte:
+- Abra uma [issue no GitHub](https://github.com/techionext/upsely-recovery/issues)
+- Entre em contato com a equipe Agenus
-- **Estatísticas Detalhadas**: Contadores de eventos e performance
-- **Debug Avançado**: Logs detalhados para desenvolvimento
-- **Health Checks**: Verificação de saúde dos trackers
-- **Error Handling**: Tratamento robusto de erros
+## 🔗 Links
-## 📄 Licença
+- **Repositório**: [github.com/techionext/upsely-recovery](https://github.com/techionext/upsely-recovery)
+- **NPM Package**: [npmjs.com/package/@agenus-io/recovery](https://www.npmjs.com/package/@agenus-io/recovery)
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
+- **Guia de Release**: [README-RELEASE.md](./README-RELEASE.md)
-MIT
+---
+Desenvolvido com ❤️ por [Agenus](https://agenus.io)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@agenus-io/recovery",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Recuperação de leads para Upsely",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -21,10 +21,21 @@
   "keywords": [
     "recovery",
     "upsely",
-    "agenus"
+    "agenus",
+    "form-abandonment",
+    "lead-capture",
+    "form-tracking"
   ],
   "author": "Agenus",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/techionext/upsely-recovery.git"
+  },
+  "bugs": {
+    "url": "https://github.com/techionext/upsely-recovery/issues"
+  },
+  "homepage": "https://github.com/techionext/upsely-recovery#readme",
   "devDependencies": {
     "@changesets/cli": "^2.27.1",
     "@types/node": "^20.0.0",