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

@agenus-io/recovery 0.0.2

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 (10) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,747 @@
+# GomarkePixel
+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.
+## 🚀 Instalação
+### Via CDN (Recomendado)
+```html
+<script src="https://unpkg.com/gomarke-pixel@latest/dist/index.global.js"></script>
+```
+### Via NPM
+```bash
+npm install gomarke-pixel
+# ou
+pnpm add gomarke-pixel
+# ou
+yarn add gomarke-pixel
+```
+## 📖 Uso
+### 🚀 Auto-Tracking Automático - Configure Uma Vez e Esqueça!
+O GomarkePixel agora funciona de forma **completamente automática**! Você só precisa configurar uma vez e todos os eventos são detectados automaticamente.
+### Uso Global (CDN) - Auto-Tracking Automático
+```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>
+</html>
+```
+### Uso em Módulos - Auto-Tracking Automático
+```javascript
+import GomarkePixel from 'gomarke-pixel';
+const pixel = new GomarkePixel({
+  apiEndpoint: 'https://sua-api.com/track',
+  apiKey: 'sua-chave-aqui',
+  debug: true,
+  // 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,
+    },
+  },
+});
+// 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);
+```
+## 🔧 Configuração
+### Configuração Básica (Sem Auto-Tracking)
+```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)
+}
+```
+### Configuração com Auto-Tracking Automático
+```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;
+    };
+  };
+}
+```
+## 📚 API - Eventos de E-commerce
+### Eventos Principais (Tracks)
+- `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
+### Auto-Tracking Inteligente
+O GomarkePixel agora inclui um sistema avançado de auto-tracking que detecta automaticamente interações do usuário:
+#### AutoTracks Básicos
+- **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
+#### AutoTracks Avançados
+- **ScrollTracker**: Rastreia profundidade de scroll e tempo na página
+- **ViewportTracker**: Detecta quando elementos entram/saem do viewport
+#### Configuração de AutoTracks
+```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'],
+  });
+```
+### Exemplo Completo
+```javascript
+const pixel = new GomarkePixel({
+  apiEndpoint: 'https://sua-api.com/track',
+  apiKey: 'sua-chave',
+  debug: true,
+});
+// 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,
+  },
+]);
+```
+## 🛠️ Desenvolvimento
+### Instalação das Dependências
+```bash
+pnpm install
+```
+### Scripts Disponíveis
+```bash
+# Desenvolvimento com watch
+pnpm dev
+# Build para produção
+pnpm build
+# Linting
+pnpm lint
+pnpm lint:fix
+# Formatação
+pnpm format
+# Verificação de tipos
+pnpm type-check
+```
+### Estrutura do Projeto
+```
+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)
+```
+## ✨ Por que Auto-Tracking?
+### 🎯 **Configure Uma Vez, Funcione Para Sempre**
+- **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: Antes vs Depois**
+#### ❌ **Antes (Manual)**
+```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
+```
+#### ✅ **Depois (Automático)**
+```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 },
+  },
+});
+// TUDO FUNCIONA AUTOMATICAMENTE! 🎉
+```
+## 🏗️ Arquitetura Avançada
+### Sistema de Classes Orientado a Objetos
+O GomarkePixel foi completamente refatorado para usar uma arquitetura orientada a objetos com máxima escalabilidade:
+#### Tracks (Tracking Manual)
+- **BaseTracker**: Classe abstrata base para todos os trackers
+- **TrackerFactory**: Factory pattern para gerenciar instâncias de trackers
+- **PageViewTracker**, **PurchaseTracker**, **AddToCartTracker**, etc.
+#### AutoTracks (Tracking Automático)
+- **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
+### Funcionalidades Avançadas
+#### 🎯 Auto-Tracking Inteligente
+- **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
+#### 🔧 Configuração Flexível
+- **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
+#### 📊 Estatísticas e Monitoramento
+- **Estatísticas Detalhadas**: Contadores de eventos, performance, erros
+- **Debug Avançado**: Logs detalhados para desenvolvimento
+- **Health Checks**: Verificação de saúde dos trackers
+#### 🚀 Performance
+- **Lazy Loading**: Carregamento sob demanda de auto-trackers
+- **Memory Management**: Limpeza automática de listeners
+- **Bundle Optimization**: Tree-shaking para reduzir tamanho do bundle
+## 📦 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
+## 🎯 Exemplos Avançados
+### Auto-Tracking Completo para E-commerce
+```javascript
+const pixel = new GomarkePixel({
+  apiEndpoint: 'https://sua-api.com/track',
+  apiKey: 'sua-chave',
+  debug: true,
+});
+// 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,
+  }),
+});
+// 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',
+  },
+});
+// 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}$/,
+  },
+});
+```
+### Auto-Tracking Avançado
+```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,
+});
+// 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,
+});
+```
+### Monitoramento e Estatísticas
+```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();
+```
+## 🚀 Publicação
+```bash
+# Build antes de publicar
+pnpm build
+# Publicar no NPM
+npm publish
+```
+## 🆕 Changelog
+### v2.0.0 - Refatoração Completa
+#### ✨ Novas Funcionalidades
+- **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
+#### 🔧 Melhorias Técnicas
+- **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
+#### 🏗️ Arquitetura
+- **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
+#### 📊 Monitoramento
+- **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
+## 📄 Licença
+MIT