trackly-sdk 0.1.0

package/README.md

@@ -0,0 +1,188 @@
+# Analytics SDK
+
+SDK leve de analytics para tracking de eventos no browser.
+
+## 🚀 Instalação
+
+```bash
+pnpm add @analytics/sdk
+# ou
+npm install @analytics/sdk
+# ou
+yarn add @analytics/sdk
+```
+
+## 📦 Uso
+
+### Inicialização
+
+```typescript
+import { Analytics } from "@analytics/sdk";
+
+const analytics = new Analytics({
+  apiUrl: "https://api.seuapp.com/events",
+  batchSize: 10, // opcional: eventos por batch (padrão: 10)
+  flushInterval: 5000, // opcional: intervalo de envio em ms (padrão: 5000)
+  maxRetries: 3, // opcional: tentativas em caso de erro (padrão: 3)
+  debug: false, // opcional: ativar logs de debug (padrão: false)
+});
+```
+
+### Tracking de Eventos
+
+```typescript
+// Evento customizado
+analytics.track("button_clicked", {
+  button: "signup",
+  page: "homepage",
+  variant: "primary",
+});
+
+// Pageview (automático por padrão, mas pode chamar manualmente)
+analytics.pageview({
+  category: "blog",
+  author: "John Doe",
+});
+
+// Identificar usuário
+analytics.identify("user_123", {
+  email: "usuario@exemplo.com",
+  name: "João Silva",
+  plan: "premium",
+});
+```
+
+### Exemplos Práticos
+
+#### E-commerce
+
+```typescript
+// Produto visualizado
+analytics.track("product_viewed", {
+  product_id: "SKU-123",
+  name: "Tênis Running",
+  price: 299.9,
+  category: "Esportes",
+});
+
+// Item adicionado ao carrinho
+analytics.track("cart_add", {
+  product_id: "SKU-123",
+  quantity: 1,
+  price: 299.9,
+});
+
+// Compra finalizada
+analytics.track("purchase", {
+  order_id: "ORD-456",
+  total: 299.9,
+  currency: "BRL",
+  items: 1,
+});
+```
+
+#### SaaS
+
+```typescript
+// Cadastro
+analytics.identify("user_789", {
+  email: "user@startup.com",
+  company: "Startup Inc",
+  plan: "trial",
+});
+
+// Feature utilizada
+analytics.track("feature_used", {
+  feature: "export_data",
+  format: "csv",
+  rows: 1500,
+});
+
+// Upgrade de plano
+analytics.track("plan_upgraded", {
+  from: "trial",
+  to: "premium",
+  mrr: 99.0,
+});
+```
+
+## 🔧 API
+
+### `Analytics`
+
+#### Métodos
+
+- **`track(eventName: string, properties?: EventProperties)`**  
+  Rastreia um evento customizado
+
+- **`pageview(properties?: EventProperties)`**  
+  Rastreia visualização de página
+
+- **`identify(userId: string, traits?: UserTraits)`**  
+  Identifica o usuário
+
+- **`flush(): Promise<void>`**  
+  Força envio imediato dos eventos na fila
+
+- **`getUserId(): string | undefined`**  
+  Retorna o userId atual
+
+- **`getAnonymousId(): string`**  
+  Retorna o ID anônimo (persistido no localStorage)
+
+- **`shutdown(): void`**  
+  Para o SDK e limpa recursos
+
+## 🎯 Características
+
+- ✅ **Leve**: Sem dependências externas
+- ✅ **Type-safe**: Totalmente tipado com TypeScript
+- ✅ **Batch automático**: Agrupa eventos para reduzir requests
+- ✅ **Retry automático**: Reenvio em caso de falha (exponential backoff)
+- ✅ **sendBeacon**: Garante envio antes de sair da página
+- ✅ **Contexto automático**: Captura URL, referrer, user agent, etc
+- ✅ **Anonymous ID**: Tracking persistente antes da identificação
+
+## 🏗️ Build
+
+```bash
+pnpm run build
+```
+
+Gera:
+
+- `dist/index.js` (CommonJS)
+- `dist/index.esm.js` (ES Modules)
+- `dist/index.d.ts` (TypeScript definitions)
+
+## 📊 Formato dos Eventos
+
+Todos os eventos enviados seguem esta estrutura:
+
+```typescript
+{
+  type: 'track' | 'page' | 'identify',
+  timestamp: 1234567890,
+  event?: 'button_clicked',           // apenas para type='track'
+  properties?: { /* dados custom */ },
+  userId?: 'user_123',
+  anonymousId: 'anon_xxx',
+  traits?: { /* dados do usuário */ }, // apenas para type='identify'
+  context: {
+    page: {
+      url: 'https://...',
+      path: '/about',
+      title: 'Sobre',
+      referrer: 'https://...'
+    },
+    userAgent: '...',
+    locale: 'pt-BR',
+    timezone: 'America/Sao_Paulo',
+    screen: { width: 1920, height: 1080 }
+  }
+}
+```
+
+## 📝 Licença
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Analytics SDK - Event tracking para browser
+ *
+ * @example
+ * ```typescript
+ * import { Analytics } from '@analytics/sdk';
+ *
+ * const analytics = new Analytics({
+ *   apiUrl: 'https://api.myapp.com/events'
+ * });
+ *
+ * analytics.track('button_clicked', { button: 'signup' });
+ * analytics.pageview();
+ * analytics.identify('user123', { email: 'user@example.com' });
+ * ```
+ */
+export { Analytics } from "./tracker";
+export type { AnalyticsConfig, AnalyticsEvent, EventProperties, UserTraits, EventContext, SendResult, } from "./types";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Analytics SDK - Event tracking para browser
+ *
+ * @example
+ * ```typescript
+ * import { Analytics } from '@analytics/sdk';
+ *
+ * const analytics = new Analytics({
+ *   apiUrl: 'https://api.myapp.com/events'
+ * });
+ *
+ * analytics.track('button_clicked', { button: 'signup' });
+ * analytics.pageview();
+ * analytics.identify('user123', { email: 'user@example.com' });
+ * ```
+ */
+export { Analytics } from "./tracker";

package/dist/queue.d.ts

@@ -0,0 +1,37 @@
+import type { AnalyticsEvent } from "./types";
+import { Transport } from "./transport";
+/**
+ * Fila de eventos com auto-flush
+ */
+export declare class EventQueue {
+    private queue;
+    private transport;
+    private batchSize;
+    private flushInterval;
+    private flushTimer?;
+    private isFlushing;
+    constructor(transport: Transport, batchSize?: number, flushInterval?: number);
+    /**
+     * Adiciona evento à fila
+     */
+    enqueue(event: AnalyticsEvent): void;
+    /**
+     * Envia todos os eventos da fila
+     */
+    flush(): Promise<void>;
+    /**
+     * Retorna número de eventos na fila
+     */
+    size(): number;
+    /**
+     * Limpa a fila
+     */
+    clear(): void;
+    /**
+     * Para o flush timer
+     */
+    stop(): void;
+    private startFlushTimer;
+    private flushViaBeacon;
+    private setupBeforeUnload;
+}

package/dist/queue.js

@@ -0,0 +1,102 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Fila de eventos com auto-flush
+ */
+export class EventQueue {
+    constructor(transport, batchSize = 10, flushInterval = 5000) {
+        this.queue = [];
+        this.isFlushing = false;
+        this.transport = transport;
+        this.batchSize = batchSize;
+        this.flushInterval = flushInterval;
+        // Auto-flush em intervalos regulares
+        this.startFlushTimer();
+        // Flush antes de sair da página
+        this.setupBeforeUnload();
+    }
+    /**
+     * Adiciona evento à fila
+     */
+    enqueue(event) {
+        this.queue.push(event);
+        // Flush automático quando atingir batch size
+        if (this.queue.length >= this.batchSize) {
+            this.flush();
+        }
+    }
+    /**
+     * Envia todos os eventos da fila
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isFlushing || this.queue.length === 0) {
+                return;
+            }
+            this.isFlushing = true;
+            const events = [...this.queue];
+            this.queue = [];
+            try {
+                yield this.transport.send(events);
+            }
+            catch (error) {
+                // Em caso de erro, recoloca eventos na fila
+                this.queue.unshift(...events);
+            }
+            finally {
+                this.isFlushing = false;
+            }
+        });
+    }
+    /**
+     * Retorna número de eventos na fila
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Limpa a fila
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Para o flush timer
+     */
+    stop() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+    }
+    startFlushTimer() {
+        this.flushTimer = window.setInterval(() => {
+            this.flush();
+        }, this.flushInterval);
+    }
+    flushViaBeacon() {
+        if (this.queue.length > 0) {
+            this.transport.sendBeacon([...this.queue]);
+            this.queue = [];
+        }
+    }
+    setupBeforeUnload() {
+        // Usa sendBeacon para garantir envio antes de sair
+        window.addEventListener("beforeunload", () => {
+            this.flushViaBeacon();
+        });
+        // Também flush em visibilitychange (mobile)
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "hidden") {
+                this.flushViaBeacon();
+            }
+        });
+    }
+}

package/dist/tracker.d.ts

@@ -0,0 +1,42 @@
+import type { AnalyticsConfig, EventProperties, UserTraits } from "./types";
+/**
+ * Classe principal do Analytics SDK
+ */
+export declare class Analytics {
+    private config;
+    private transport;
+    private queue;
+    private userId?;
+    private userTraits?;
+    private anonymousId;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Identifica o usuário
+     */
+    identify(userId: string, traits?: UserTraits): void;
+    /**
+     * Rastreia um evento customizado
+     */
+    track(eventName: string, properties?: EventProperties): void;
+    /**
+     * Rastreia visualização de página
+     */
+    pageview(properties?: EventProperties): void;
+    /**
+     * Força envio imediato dos eventos na fila
+     */
+    flush(): Promise<void>;
+    /**
+     * Retorna o userId atual
+     */
+    getUserId(): string | undefined;
+    /**
+     * Retorna o anonymousId
+     */
+    getAnonymousId(): string;
+    /**
+     * Para o SDK e limpa recursos
+     */
+    shutdown(): void;
+    private createAndEnqueueEvent;
+}

package/dist/tracker.js

@@ -0,0 +1,143 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Transport } from "./transport";
+import { EventQueue } from "./queue";
+/**
+ * Gerador de ID anônimo
+ */
+function generateAnonymousId() {
+    return `anon_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Obtém ou cria anonymousId no localStorage
+ */
+function getAnonymousId() {
+    const key = "analytics_anonymous_id";
+    let id = localStorage.getItem(key);
+    if (!id) {
+        id = generateAnonymousId();
+        localStorage.setItem(key, id);
+    }
+    return id;
+}
+/**
+ * Coleta contexto automático do evento
+ */
+function getEventContext() {
+    return {
+        page: {
+            url: window.location.href,
+            path: window.location.pathname,
+            title: document.title,
+            referrer: document.referrer,
+        },
+        userAgent: navigator.userAgent,
+        locale: navigator.language,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        screen: {
+            width: window.screen.width,
+            height: window.screen.height,
+        },
+    };
+}
+/**
+ * Classe principal do Analytics SDK
+ */
+export class Analytics {
+    constructor(config) {
+        var _a, _b, _c, _d, _e;
+        // Configuração padrão
+        this.config = {
+            apiUrl: config.apiUrl,
+            batchSize: (_a = config.batchSize) !== null && _a !== void 0 ? _a : 10,
+            flushInterval: (_b = config.flushInterval) !== null && _b !== void 0 ? _b : 5000,
+            maxRetries: (_c = config.maxRetries) !== null && _c !== void 0 ? _c : 3,
+            debug: (_d = config.debug) !== null && _d !== void 0 ? _d : false,
+            disableAutoPageview: (_e = config.disableAutoPageview) !== null && _e !== void 0 ? _e : false,
+        };
+        this.anonymousId = getAnonymousId();
+        this.transport = new Transport(this.config.apiUrl, this.config.maxRetries, this.config.debug);
+        this.queue = new EventQueue(this.transport, this.config.batchSize, this.config.flushInterval);
+        // Pageview automático
+        if (!this.config.disableAutoPageview) {
+            this.pageview();
+        }
+        if (this.config.debug) {
+            console.log("[Analytics] Initialized with config:", this.config);
+        }
+    }
+    /**
+     * Identifica o usuário
+     */
+    identify(userId, traits) {
+        this.userId = userId;
+        this.userTraits = traits;
+        this.createAndEnqueueEvent({
+            type: "identify",
+            userId,
+            traits,
+        }, `User identified: ${userId}`);
+    }
+    /**
+     * Rastreia um evento customizado
+     */
+    track(eventName, properties) {
+        this.createAndEnqueueEvent({
+            type: "track",
+            event: eventName,
+            properties,
+            userId: this.userId,
+        }, `Event tracked: ${eventName}`, properties);
+    }
+    /**
+     * Rastreia visualização de página
+     */
+    pageview(properties) {
+        this.createAndEnqueueEvent({
+            type: "page",
+            properties,
+            userId: this.userId,
+        }, "Pageview tracked");
+    }
+    /**
+     * Força envio imediato dos eventos na fila
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.queue.flush();
+        });
+    }
+    /**
+     * Retorna o userId atual
+     */
+    getUserId() {
+        return this.userId;
+    }
+    /**
+     * Retorna o anonymousId
+     */
+    getAnonymousId() {
+        return this.anonymousId;
+    }
+    /**
+     * Para o SDK e limpa recursos
+     */
+    shutdown() {
+        this.queue.stop();
+        this.queue.clear();
+    }
+    createAndEnqueueEvent(eventData, debugMessage, debugData) {
+        const event = Object.assign(Object.assign({}, eventData), { timestamp: Date.now(), anonymousId: this.anonymousId, context: getEventContext() });
+        this.queue.enqueue(event);
+        if (this.config.debug) {
+            console.log(`[Analytics] ${debugMessage}`, debugData !== undefined ? debugData : "");
+        }
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,19 @@
+import type { AnalyticsEvent, SendResult } from "./types";
+/**
+ * Transport layer para envio de eventos
+ */
+export declare class Transport {
+    private apiUrl;
+    private maxRetries;
+    private debug;
+    constructor(apiUrl: string, maxRetries?: number, debug?: boolean);
+    /**
+     * Envia um batch de eventos para a API
+     */
+    send(events: AnalyticsEvent[]): Promise<SendResult>;
+    /**
+     * Envia evento único usando sendBeacon (para unload)
+     */
+    sendBeacon(events: AnalyticsEvent[]): boolean;
+    private sleep;
+}

package/dist/transport.js

@@ -0,0 +1,85 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Transport layer para envio de eventos
+ */
+export class Transport {
+    constructor(apiUrl, maxRetries = 3, debug = false) {
+        this.apiUrl = apiUrl;
+        this.maxRetries = maxRetries;
+        this.debug = debug;
+    }
+    /**
+     * Envia um batch de eventos para a API
+     */
+    send(events) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (events.length === 0) {
+                return { success: true };
+            }
+            let lastError;
+            for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+                try {
+                    if (this.debug) {
+                        console.log(`[Analytics] Sending ${events.length} events (attempt ${attempt + 1})`);
+                    }
+                    const response = yield fetch(this.apiUrl, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify({ events }),
+                    });
+                    if (!response.ok) {
+                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                    }
+                    if (this.debug) {
+                        console.log("[Analytics] Events sent successfully");
+                    }
+                    return { success: true };
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    if (this.debug) {
+                        console.warn(`[Analytics] Send failed (attempt ${attempt + 1}):`, lastError.message);
+                    }
+                    // Aguarda antes de retry (exponential backoff)
+                    if (attempt < this.maxRetries) {
+                        yield this.sleep(Math.pow(2, attempt) * 1000);
+                    }
+                }
+            }
+            return { success: false, error: lastError };
+        });
+    }
+    /**
+     * Envia evento único usando sendBeacon (para unload)
+     */
+    sendBeacon(events) {
+        if (events.length === 0 || !navigator.sendBeacon) {
+            return false;
+        }
+        try {
+            const blob = new Blob([JSON.stringify({ events })], {
+                type: "application/json",
+            });
+            return navigator.sendBeacon(this.apiUrl, blob);
+        }
+        catch (error) {
+            if (this.debug) {
+                console.warn("[Analytics] sendBeacon failed:", error);
+            }
+            return false;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Propriedades customizadas de um evento
+ */
+export type EventProperties = Record<string, any>;
+/**
+ * Dados do usuário
+ */
+export interface UserTraits {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: any;
+}
+/**
+ * Evento base
+ */
+export interface AnalyticsEvent {
+    type: "track" | "page" | "identify";
+    timestamp: number;
+    event?: string;
+    properties?: EventProperties;
+    userId?: string;
+    anonymousId?: string;
+    traits?: UserTraits;
+    context?: EventContext;
+}
+/**
+ * Contexto automático do evento
+ */
+export interface EventContext {
+    page?: {
+        url: string;
+        path: string;
+        title: string;
+        referrer: string;
+    };
+    userAgent?: string;
+    locale?: string;
+    timezone?: string;
+    screen?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Configuração do SDK
+ */
+export interface AnalyticsConfig {
+    /** URL da API de coleta */
+    apiUrl: string;
+    /** Tamanho máximo do batch de eventos */
+    batchSize?: number;
+    /** Tempo máximo (ms) antes de enviar batch */
+    flushInterval?: number;
+    /** Número de tentativas em caso de falha */
+    maxRetries?: number;
+    /** Habilitar logs de debug */
+    debug?: boolean;
+    /** Desabilitar tracking automático de pageviews */
+    disableAutoPageview?: boolean;
+}
+/**
+ * Status de envio
+ */
+export interface SendResult {
+    success: boolean;
+    error?: Error;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "trackly-sdk",
+  "version": "0.1.0",
+  "description": "SDK leve de analytics para tracking de eventos no browser",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "events",
+    "browser",
+    "typescript",
+    "zero-dependencies",
+    "batching",
+    "event-tracking"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaycfarias/trackly.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/kaycfarias/trackly/issues"
+  },
+  "homepage": "https://github.com/kaycfarias/trackly/tree/main/packages/sdk#readme",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}