@agroideas/event-tracker-sdk 1.0.0

package/README.md

@@ -0,0 +1,308 @@
+# @agroideas/event-tracker-sdk
+
+A lightweight, framework-agnostic TypeScript SDK for tracking frontend user behavior. Automatically captures page views, session duration, and user interactions, sending them to a centralized analytics API.
+
+## Features
+
+- 🚀 **Lightweight**: Zero dependencies, built with native Fetch API and DOM APIs
+- 🔄 **SPA Support**: Handles navigation in Single Page Applications via History API interception
+- 📦 **Smart Batching**: Events are batched by size and time interval for optimal performance
+- 🔒 **Reliable Delivery**: Uses `sendBeacon` with `keepalive` to ensure events are sent on page unload
+- 🌐 **Framework Agnostic**: Works with any frontend framework (React, Vue, Angular, Vanilla JS)
+- 📊 **Rich Context**: Automatically captures device, browser, and session metadata
+
+## Installation
+
+### npm
+
+```bash
+npm install @agroideas/event-tracker-sdk
+```
+
+### pnpm
+
+```bash
+pnpm add @agroideas/event-tracker-sdk
+```
+
+### yarn
+
+```bash
+yarn add @agroideas/event-tracker-sdk
+```
+
+## Quick Start
+
+### ESM / TypeScript
+
+```typescript
+import { tracker } from '@agroideas/event-tracker-sdk';
+
+// Initialize with required configuration
+tracker.init({
+  apiKey: 'your-api-key',
+  endpoint: 'https://your-api.com/events',
+  debug: true, // Optional: logs events to console
+});
+
+// Identify users when they log in
+tracker.identify('user-123', 'John Doe');
+
+// Events are now being tracked automatically!
+```
+
+### IIFE / Script Tag
+
+```html
+<script src="https://cdn.your-domain.com/event-tracker.global.js"></script>
+<script>
+  window.EventTracker.init({
+    apiKey: 'your-api-key',
+    endpoint: 'https://your-api.com/events',
+  });
+
+  window.EventTracker.identify('user-123', 'John Doe');
+</script>
+```
+
+## API Reference
+
+### `tracker.init(config)`
+
+Initializes the tracker with configuration options.
+
+| Parameter       | Type      | Required | Default | Description                              |
+| --------------- | --------- | -------- | ------- | ---------------------------------------- |
+| `apiKey`        | `string`  | Yes      | -       | Your API key for authentication          |
+| `endpoint`      | `string`  | Yes      | -       | URL to send events to                    |
+| `batchInterval` | `number`  | No       | `10000` | Milliseconds between batch sends         |
+| `maxBufferSize` | `number`  | No       | `15`    | Maximum events before forced send        |
+| `debug`         | `boolean` | No       | `false` | Log events to console instead of sending |
+| `userId`        | `string`  | No       | -       | Initial user ID                          |
+| `userName`      | `string`  | No       | -       | Initial user name                        |
+
+```typescript
+tracker.init({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.example.com/track',
+  batchInterval: 5000,
+  maxBufferSize: 20,
+  debug: true,
+});
+```
+
+### `tracker.identify(userId, userName?)`
+
+Identifies a user. Call this when a user logs in or when their information changes.
+
+```typescript
+// After user logs in
+tracker.identify('user-123', 'John Doe');
+
+// Update user name
+tracker.identify('user-123', 'Jane Doe');
+```
+
+### `tracker.trackEvent(eventType, data)`
+
+Tracks a custom event.
+
+```typescript
+// Track a custom event
+tracker.trackEvent('button_click', {
+  buttonId: 'signup',
+  buttonText: 'Sign Up',
+});
+
+// Track form submission
+tracker.trackEvent('form_submit', {
+  formId: 'contact-form',
+  formName: 'Contact Us',
+});
+```
+
+### `tracker.flush()`
+
+Immediately sends all pending events. Useful before critical actions like form submissions.
+
+```typescript
+await tracker.flush();
+```
+
+### `tracker.destroy()`
+
+Stops all tracking and clears event buffers. Call this when users log out.
+
+```typescript
+tracker.destroy();
+```
+
+## Automatically Tracked Events
+
+The SDK automatically captures the following events:
+
+### `page_view`
+
+Fired on initial page load and when the URL changes (including SPA navigation).
+
+**Data:**
+
+- `path`: The current URL path
+
+### `page_leave`
+
+Fired when the user leaves a page or closes the tab.
+
+**Data:**
+
+- `path`: The page path
+- `duration`: Time spent on the page in seconds
+
+### `user_click`
+
+Fired when the user clicks on interactive elements.
+
+**Data:**
+
+- `tagName`: HTML element tag (e.g., "BUTTON", "A")
+- `id`: Element ID (if present)
+- `classes`: CSS classes (if present)
+- `text`: Inner text (truncated to 30 characters)
+- `selector`: CSS selector path to the element
+
+## Context Data
+
+All events include automatic context data:
+
+| Field          | Description                            |
+| -------------- | -------------------------------------- |
+| `sessionId`    | Unique UUID stored in sessionStorage   |
+| `userId`       | Current user ID (from `identify()`)    |
+| `userName`     | Current user name (from `identify()`)  |
+| `url`          | Full current URL                       |
+| `referrer`     | Document referrer                      |
+| `screenSize`   | Screen resolution (e.g., "1920x1080")  |
+| `viewportSize` | Viewport dimensions (e.g., "1280x720") |
+| `deviceType`   | Desktop, Mobile, or Tablet             |
+| `browser`      | Browser name and version               |
+| `os`           | Operating system                       |
+| `language`     | Browser language                       |
+| `timestamp`    | ISO 8601 timestamp                     |
+
+## Configuration Example
+
+### React Application
+
+```tsx
+import { useEffect } from 'react';
+import { tracker } from '@agroideas/event-tracker-sdk';
+
+function App() {
+  useEffect(() => {
+    tracker.init({
+      apiKey: process.env.REACT_APP_TRACKER_API_KEY,
+      endpoint: process.env.REACT_APP_TRACKER_ENDPOINT,
+    });
+
+    return () => {
+      tracker.destroy();
+    };
+  }, []);
+
+  const handleLogin = () => {
+    // ... login logic
+    tracker.identify('user-123', 'John Doe');
+  };
+
+  const handleSubmit = async () => {
+    await tracker.flush();
+    // Submit form
+  };
+
+  return (
+    <button onClick={handleLogin}>Login</button>
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+### Vue 3 Application
+
+```typescript
+import { tracker } from '@agroideas/event-tracker-sdk';
+import { onMounted, onUnmounted } from 'vue';
+
+export default {
+  setup() {
+    onMounted(() => {
+      tracker.init({
+        apiKey: import.meta.env.VITE_TRACKER_API_KEY,
+        endpoint: import.meta.env.VITE_TRACKER_ENDPOINT,
+      });
+    });
+
+    onUnmounted(() => {
+      tracker.destroy();
+    });
+
+    const login = (userId: string, userName: string) => {
+      tracker.identify(userId, userName);
+    };
+
+    return { login };
+  },
+};
+```
+
+## Privacy Considerations
+
+- **Input Fields**: The SDK automatically excludes password field values from click tracking
+- **Sensitive Data**: No user data is stored locally; all data is sent directly to your endpoint
+- **User Consent**: Implement your own consent management before initializing the tracker if required by GDPR/CCPA
+
+## Build Outputs
+
+The SDK is compiled to multiple formats:
+
+| Format     | File                   | Usage                           |
+| ---------- | ---------------------- | ------------------------------- |
+| ES Module  | `dist/index.mjs`       | Modern browsers, bundlers       |
+| CommonJS   | `dist/index.js`        | Node.js, older bundlers         |
+| IIFE       | `dist/index.global.js` | Direct script inclusion         |
+| TypeScript | `dist/index.d.ts`      | IDE autocomplete, type checking |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development mode (watch mode)
+pnpm dev
+
+# Run linter
+pnpm lint
+
+# Format code
+pnpm format
+
+# Build for production
+pnpm build
+
+# Run type checking
+pnpm type-check
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `pnpm lint` and `pnpm build`
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+/**
+ * Tipos compartidos para el Event Tracker SDK
+ */
+/** Configuración del Tracker */
+interface TrackerConfig {
+    apiKey: string;
+    endpoint: string;
+    userId?: string;
+    userName?: string;
+    debug?: string;
+    batchInterval?: number;
+    maxBufferSize?: number;
+}
+/** Metadatos de contexto incluidos en cada evento */
+interface EventContext {
+    sessionId: string;
+    userId: string | null;
+    userName: string | null;
+    url: string;
+    referrer: string;
+    screenSize: string;
+    viewportSize: string;
+    deviceType: 'mobile' | 'desktop' | 'tablet' | 'unknown';
+    browser: string;
+    os: string;
+    language: string;
+    timestamp: string;
+}
+/** Eventos capturados por el SDK */
+type EventType = 'page_view' | 'page_leave' | 'user_click';
+/** Payload base de un evento */
+interface BaseEvent {
+    eventType: EventType;
+    eventId: string;
+    context: EventContext;
+}
+/** Evento de vista de página */
+interface PageViewEvent extends BaseEvent {
+    eventType: 'page_view';
+    data: {
+        pageTitle?: string;
+        path: string;
+    };
+}
+/** Evento de salida de página */
+interface PageLeaveEvent extends BaseEvent {
+    eventType: 'page_leave';
+    data: {
+        duration: number;
+        path: string;
+    };
+}
+/** Evento de clic de usuario */
+interface UserClickEvent extends BaseEvent {
+    eventType: 'user_click';
+    data: {
+        tagName: string;
+        id?: string;
+        className?: string;
+        title?: string;
+        text?: string;
+        selector: string;
+    };
+}
+/** Unión de todos los tipos de eventos */
+type TrackerEvent = PageViewEvent | PageLeaveEvent | UserClickEvent;
+
+/**
+ * Tracker: Singleton principal que coordina observers y EventBuffer
+ */
+
+declare class Tracker {
+    private static _instance;
+    private _eventBuffer;
+    private _clickObserver;
+    private _historyObserver;
+    private _userIdentity;
+    private _sessionId;
+    private _isInitialized;
+    private constructor();
+    /** Obtiene la instancia única del Tracker */
+    static getInstance(): Tracker;
+    /** Construye el contexto completo del evento */
+    private _buildContext;
+    /** Inicializa el tracker con la configuración */
+    init(config: TrackerConfig): void;
+    /** Identifica al usuario */
+    identify(userId: string, userName?: string): void;
+    /** Registra un evento */
+    trackEvent(event: TrackerEvent): void;
+    /** Crea un evento de page view */
+    trackPageView(): void;
+    /** Crea un evento de page leave */
+    trackPageLeave(duration: number): void;
+    /** Fuerza el envío de todos los eventos pendientes */
+    flush(): Promise<void>;
+    /** Verifica si el tracker está inicializado */
+    isInitialized(): boolean;
+    /** Destruye el tracker */
+    destroy(): void;
+}
+
+/**
+ * Event Tracker SDK
+ *
+ * SDK ligero y agnóstico al framework para tracking de comportamiento frontend.
+ *
+ * @example
+ * import { tracker } from '@agroideas/event-tracker-sdk';
+ *
+ * tracker.init({
+ *   apiKey: 'tu-api-key',
+ *   endpoint: 'https://tu-api.com/events'
+ * });
+ *
+ * // Identificar usuario
+ * tracker.identify('user-123', 'Juan Pérez');
+ */
+
+/** Instancia única exportada del Tracker */
+declare const tracker: Tracker;
+/**
+ * Inicializa el tracker con configuración requerida (apiKey y endpoint).
+ */
+declare function init(config: TrackerConfig): void;
+/** Identifica al usuario */
+declare function identify(userId: string, userName?: string): void;
+/** Fuerza el envío de eventos pendientes */
+declare function flush(): Promise<void>;
+/** Destruye el tracker */
+declare function destroy(): void;
+
+export { type TrackerConfig, destroy, flush, identify, init, tracker };

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Tipos compartidos para el Event Tracker SDK
+ */
+/** Configuración del Tracker */
+interface TrackerConfig {
+    apiKey: string;
+    endpoint: string;
+    userId?: string;
+    userName?: string;
+    debug?: string;
+    batchInterval?: number;
+    maxBufferSize?: number;
+}
+/** Metadatos de contexto incluidos en cada evento */
+interface EventContext {
+    sessionId: string;
+    userId: string | null;
+    userName: string | null;
+    url: string;
+    referrer: string;
+    screenSize: string;
+    viewportSize: string;
+    deviceType: 'mobile' | 'desktop' | 'tablet' | 'unknown';
+    browser: string;
+    os: string;
+    language: string;
+    timestamp: string;
+}
+/** Eventos capturados por el SDK */
+type EventType = 'page_view' | 'page_leave' | 'user_click';
+/** Payload base de un evento */
+interface BaseEvent {
+    eventType: EventType;
+    eventId: string;
+    context: EventContext;
+}
+/** Evento de vista de página */
+interface PageViewEvent extends BaseEvent {
+    eventType: 'page_view';
+    data: {
+        pageTitle?: string;
+        path: string;
+    };
+}
+/** Evento de salida de página */
+interface PageLeaveEvent extends BaseEvent {
+    eventType: 'page_leave';
+    data: {
+        duration: number;
+        path: string;
+    };
+}
+/** Evento de clic de usuario */
+interface UserClickEvent extends BaseEvent {
+    eventType: 'user_click';
+    data: {
+        tagName: string;
+        id?: string;
+        className?: string;
+        title?: string;
+        text?: string;
+        selector: string;
+    };
+}
+/** Unión de todos los tipos de eventos */
+type TrackerEvent = PageViewEvent | PageLeaveEvent | UserClickEvent;
+
+/**
+ * Tracker: Singleton principal que coordina observers y EventBuffer
+ */
+
+declare class Tracker {
+    private static _instance;
+    private _eventBuffer;
+    private _clickObserver;
+    private _historyObserver;
+    private _userIdentity;
+    private _sessionId;
+    private _isInitialized;
+    private constructor();
+    /** Obtiene la instancia única del Tracker */
+    static getInstance(): Tracker;
+    /** Construye el contexto completo del evento */
+    private _buildContext;
+    /** Inicializa el tracker con la configuración */
+    init(config: TrackerConfig): void;
+    /** Identifica al usuario */
+    identify(userId: string, userName?: string): void;
+    /** Registra un evento */
+    trackEvent(event: TrackerEvent): void;
+    /** Crea un evento de page view */
+    trackPageView(): void;
+    /** Crea un evento de page leave */
+    trackPageLeave(duration: number): void;
+    /** Fuerza el envío de todos los eventos pendientes */
+    flush(): Promise<void>;
+    /** Verifica si el tracker está inicializado */
+    isInitialized(): boolean;
+    /** Destruye el tracker */
+    destroy(): void;
+}
+
+/**
+ * Event Tracker SDK
+ *
+ * SDK ligero y agnóstico al framework para tracking de comportamiento frontend.
+ *
+ * @example
+ * import { tracker } from '@agroideas/event-tracker-sdk';
+ *
+ * tracker.init({
+ *   apiKey: 'tu-api-key',
+ *   endpoint: 'https://tu-api.com/events'
+ * });
+ *
+ * // Identificar usuario
+ * tracker.identify('user-123', 'Juan Pérez');
+ */
+
+/** Instancia única exportada del Tracker */
+declare const tracker: Tracker;
+/**
+ * Inicializa el tracker con configuración requerida (apiKey y endpoint).
+ */
+declare function init(config: TrackerConfig): void;
+/** Identifica al usuario */
+declare function identify(userId: string, userName?: string): void;
+/** Fuerza el envío de eventos pendientes */
+declare function flush(): Promise<void>;
+/** Destruye el tracker */
+declare function destroy(): void;
+
+export { type TrackerConfig, destroy, flush, identify, init, tracker };