aurea-tracking-sdk 1.0.0

package/README.md

@@ -0,0 +1,429 @@
+# Aurea Tracking SDK
+
+A standalone tracking SDK for Aurea CRM external funnels. Track user behavior, conversions, and analytics events in your web applications.
+
+## Installation
+
+```bash
+npm install aurea-tracking-sdk
+# or
+yarn add aurea-tracking-sdk
+# or
+pnpm add aurea-tracking-sdk
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+```typescript
+import { initAurea } from 'aurea-tracking-sdk';
+
+initAurea({
+  apiKey: 'your-api-key',
+  funnelId: 'your-funnel-id',
+  apiUrl: 'https://your-aurea-instance.com/api',
+  debug: true, // Enable debug logging in development
+  autoTrack: {
+    pageViews: true,
+    forms: true,
+    scrollDepth: true,
+    clicks: false,
+  },
+});
+```
+
+### 2. Track Custom Events
+
+```typescript
+import { trackEvent } from 'aurea-tracking-sdk';
+
+// Track a custom event
+trackEvent('button_clicked', {
+  buttonName: 'Get Started',
+  location: 'hero',
+});
+
+// Track a conversion
+import { trackConversion } from 'aurea-tracking-sdk';
+
+trackConversion({
+  type: 'purchase',
+  revenue: 99.00,
+  currency: 'USD',
+  orderId: 'order_123',
+});
+```
+
+### 3. Identify Users
+
+```typescript
+import { identifyUser } from 'aurea-tracking-sdk';
+
+identifyUser('user_123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium',
+});
+```
+
+## Features
+
+### ✅ Auto-Tracking
+
+- **Page Views** - Automatically tracks page visits and navigation
+- **Form Submissions** - Captures form submit events
+- **Scroll Depth** - Tracks user engagement (25%, 50%, 75%, 100%)
+- **Clicks** - Optional click tracking
+
+### 📊 Analytics
+
+- **Custom Events** - Track any custom event with properties
+- **Conversions** - Track purchases and revenue
+- **User Identification** - Link events to specific users
+- **Session Tracking** - Automatic session management
+
+### 🔄 Purchase Detection
+
+- **Webhook Integration** - Detects purchases from server-side webhooks
+- **Auto-Redirect** - Automatically redirects users to thank-you page after purchase
+- **Polling System** - Checks for purchases every 3 seconds
+
+### 🛡️ Privacy & Security
+
+- **Do Not Track** - Respects browser DNT settings
+- **IP Anonymization** - Optional IP address anonymization
+- **GDPR Compliant** - Built with privacy in mind
+
+## API Reference
+
+### `initAurea(config)`
+
+Initialize the tracking SDK.
+
+**Parameters:**
+
+```typescript
+interface AureaConfig {
+  apiKey: string;              // Required: Your Aurea API key
+  funnelId: string;            // Required: Your funnel ID
+  apiUrl?: string;             // Optional: API endpoint URL
+  debug?: boolean;             // Optional: Enable debug logging
+  autoTrack?: {                // Optional: Auto-tracking settings
+    pageViews?: boolean;       // Default: true
+    forms?: boolean;           // Default: true
+    clicks?: boolean;          // Default: false
+    scrollDepth?: boolean;     // Default: false
+  };
+  respectDoNotTrack?: boolean; // Optional: Respect DNT header (default: true)
+  anonymizeIp?: boolean;       // Optional: Anonymize IP addresses (default: true)
+  batchSize?: number;          // Optional: Event batch size (default: 10)
+  batchInterval?: number;      // Optional: Batch interval in ms (default: 2000)
+}
+```
+
+**Returns:** `AureaSDK` instance
+
+**Example:**
+
+```typescript
+const aurea = initAurea({
+  apiKey: 'ak_1234567890',
+  funnelId: 'fn_abcdefgh',
+  apiUrl: 'https://analytics.example.com/api',
+  debug: process.env.NODE_ENV === 'development',
+});
+```
+
+---
+
+### `trackEvent(name, properties?)`
+
+Track a custom event.
+
+**Parameters:**
+
+- `name` (string): Event name
+- `properties` (object, optional): Event properties
+
+**Example:**
+
+```typescript
+trackEvent('product_viewed', {
+  productId: 'prod_123',
+  productName: 'Premium Plan',
+  price: 99.00,
+  category: 'subscription',
+});
+```
+
+---
+
+### `trackPage(name?, properties?)`
+
+Track a page view.
+
+**Parameters:**
+
+- `name` (string, optional): Page name
+- `properties` (object, optional): Page properties
+
+**Example:**
+
+```typescript
+trackPage('Pricing Page', {
+  plan: 'premium',
+  billingCycle: 'monthly',
+});
+```
+
+---
+
+### `trackConversion(data)`
+
+Track a conversion event.
+
+**Parameters:**
+
+```typescript
+interface ConversionData {
+  type: string;              // Conversion type (e.g., 'purchase', 'signup')
+  revenue: number;           // Revenue amount
+  currency?: string;         // Currency code (default: 'USD')
+  orderId?: string;          // Order/transaction ID
+  properties?: object;       // Additional properties
+}
+```
+
+**Example:**
+
+```typescript
+trackConversion({
+  type: 'purchase',
+  revenue: 149.99,
+  currency: 'USD',
+  orderId: 'order_abc123',
+  properties: {
+    plan: 'annual',
+    discount: 'SAVE20',
+  },
+});
+```
+
+---
+
+### `identifyUser(userId, traits?)`
+
+Identify a user.
+
+**Parameters:**
+
+- `userId` (string): Unique user identifier
+- `traits` (object, optional): User traits/properties
+
+**Example:**
+
+```typescript
+identifyUser('user_123', {
+  email: 'john@example.com',
+  name: 'John Doe',
+  plan: 'premium',
+  signupDate: '2024-01-15',
+});
+```
+
+---
+
+### `getAurea()`
+
+Get the current SDK instance.
+
+**Returns:** `AureaSDK | null`
+
+**Example:**
+
+```typescript
+import { getAurea } from 'aurea-tracking-sdk';
+
+const aurea = getAurea();
+if (aurea) {
+  aurea.track('custom_event');
+}
+```
+
+## Framework Integration
+
+### Next.js
+
+Create a component to initialize the SDK:
+
+```tsx
+// components/aurea-tracking.tsx
+'use client';
+
+import { useEffect } from 'react';
+import { initAurea } from 'aurea-tracking-sdk';
+
+export function AureaTracking() {
+  useEffect(() => {
+    initAurea({
+      apiKey: process.env.NEXT_PUBLIC_AUREA_API_KEY!,
+      funnelId: process.env.NEXT_PUBLIC_AUREA_FUNNEL_ID!,
+      apiUrl: process.env.NEXT_PUBLIC_AUREA_API_URL,
+      debug: process.env.NODE_ENV === 'development',
+    });
+  }, []);
+
+  return null;
+}
+```
+
+Add to your root layout:
+
+```tsx
+// app/layout.tsx
+import { AureaTracking } from '@/components/aurea-tracking';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AureaTracking />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+### React
+
+```tsx
+import { useEffect } from 'react';
+import { initAurea, trackEvent } from 'aurea-tracking-sdk';
+
+function App() {
+  useEffect(() => {
+    initAurea({
+      apiKey: import.meta.env.VITE_AUREA_API_KEY,
+      funnelId: import.meta.env.VITE_AUREA_FUNNEL_ID,
+    });
+  }, []);
+
+  return <YourApp />;
+}
+```
+
+### Vanilla JavaScript
+
+```html
+<script type="module">
+  import { initAurea, trackEvent } from 'https://unpkg.com/aurea-tracking-sdk';
+
+  initAurea({
+    apiKey: 'your-api-key',
+    funnelId: 'your-funnel-id',
+  });
+
+  // Track events
+  document.querySelector('#cta-button').addEventListener('click', () => {
+    trackEvent('cta_clicked');
+  });
+</script>
+```
+
+## Advanced Usage
+
+### Custom Session Management
+
+```typescript
+import { getAurea } from 'aurea-tracking-sdk';
+
+const aurea = getAurea();
+
+// Get current session ID
+console.log(aurea?.sessionId);
+
+// Get current anonymous ID
+console.log(aurea?.anonymousId);
+```
+
+### Event Batching
+
+Events are automatically batched and sent in groups for better performance:
+
+```typescript
+initAurea({
+  apiKey: 'your-api-key',
+  funnelId: 'your-funnel-id',
+  batchSize: 20,        // Send after 20 events
+  batchInterval: 5000,  // Or after 5 seconds
+});
+```
+
+### Error Handling
+
+```typescript
+import { trackEvent } from 'aurea-tracking-sdk';
+
+try {
+  trackEvent('risky_operation', { value: 123 });
+} catch (error) {
+  console.error('Failed to track event:', error);
+}
+```
+
+## Configuration Examples
+
+### Development
+
+```typescript
+initAurea({
+  apiKey: 'ak_dev_1234567890',
+  funnelId: 'fn_dev_abcdefgh',
+  apiUrl: 'http://localhost:3000/api',
+  debug: true,
+  respectDoNotTrack: false, // Track in dev
+});
+```
+
+### Production
+
+```typescript
+initAurea({
+  apiKey: process.env.AUREA_API_KEY!,
+  funnelId: process.env.AUREA_FUNNEL_ID!,
+  apiUrl: 'https://analytics.yourdomain.com/api',
+  debug: false,
+  respectDoNotTrack: true,
+  anonymizeIp: true,
+  batchSize: 10,
+  batchInterval: 2000,
+});
+```
+
+## Browser Support
+
+- Chrome/Edge (last 2 versions)
+- Firefox (last 2 versions)
+- Safari (last 2 versions)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## TypeScript
+
+This package is written in TypeScript and includes type definitions out of the box.
+
+```typescript
+import type { AureaConfig, ConversionData } from 'aurea-tracking-sdk';
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- GitHub: https://github.com/yourusername/aurea-tracking-sdk/issues
+- Documentation: https://docs.aureacrm.com
+- Email: support@aureacrm.com

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+/**
+ * Aurea Tracking SDK
+ * Standalone tracking SDK for external funnels
+ */
+interface AureaConfig {
+    apiKey: string;
+    funnelId: string;
+    apiUrl?: string;
+    debug?: boolean;
+    autoTrack?: {
+        pageViews?: boolean;
+        forms?: boolean;
+        clicks?: boolean;
+        scrollDepth?: boolean;
+    };
+    respectDoNotTrack?: boolean;
+    anonymizeIp?: boolean;
+    batchSize?: number;
+    batchInterval?: number;
+}
+interface ConversionData {
+    type: string;
+    revenue: number;
+    currency?: string;
+    orderId?: string;
+    properties?: Record<string, any>;
+}
+declare class AureaSDK {
+    private config;
+    private sessionId;
+    private anonymousId;
+    private userId?;
+    private eventQueue;
+    private batchTimer?;
+    private initialized;
+    constructor(config: AureaConfig);
+    /**
+     * Initialize the SDK
+     */
+    init(): void;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: Record<string, any>): void;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Track a page view
+     */
+    page(name?: string, properties?: Record<string, any>): void;
+    /**
+     * Track a conversion event
+     */
+    conversion(data: ConversionData): void;
+    /**
+     * Get or create session ID
+     */
+    private getOrCreateSessionId;
+    /**
+     * Get or create anonymous ID
+     */
+    private getOrCreateAnonymousId;
+    /**
+     * Build event context
+     */
+    private buildContext;
+    /**
+     * Track initial page load
+     */
+    private trackPageLoad;
+    /**
+     * Track page changes (for SPAs)
+     */
+    private trackPageChanges;
+    /**
+     * Track form submissions
+     */
+    private trackForms;
+    /**
+     * Track scroll depth
+     */
+    private trackScrollDepth;
+    /**
+     * Enqueue event for batching
+     */
+    private enqueueEvent;
+    /**
+     * Send events to API
+     */
+    private sendEvents;
+    /**
+     * Flush queued events
+     */
+    private flushEvents;
+    /**
+     * Start batch timer
+     */
+    private startBatchTimer;
+    /**
+     * Poll for purchase completion
+     * Checks every 3 seconds if user has made a purchase
+     */
+    private startPurchasePolling;
+    /**
+     * Check if user has completed a purchase
+     */
+    private checkForPurchase;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Generate event ID
+     */
+    private generateEventId;
+}
+/**
+ * Initialize Aurea SDK
+ */
+declare function initAurea(config: AureaConfig): AureaSDK;
+/**
+ * Get SDK instance
+ */
+declare function getAurea(): AureaSDK | null;
+/**
+ * Helper: Track custom event
+ */
+declare function trackEvent(name: string, properties?: Record<string, any>): void;
+/**
+ * Helper: Identify user
+ */
+declare function identifyUser(userId: string, traits?: Record<string, any>): void;
+/**
+ * Helper: Track conversion
+ */
+declare function trackConversion(data: ConversionData): void;
+/**
+ * Helper: Track page view
+ */
+declare function trackPage(name?: string, properties?: Record<string, any>): void;
+
+export { getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Aurea Tracking SDK
+ * Standalone tracking SDK for external funnels
+ */
+interface AureaConfig {
+    apiKey: string;
+    funnelId: string;
+    apiUrl?: string;
+    debug?: boolean;
+    autoTrack?: {
+        pageViews?: boolean;
+        forms?: boolean;
+        clicks?: boolean;
+        scrollDepth?: boolean;
+    };
+    respectDoNotTrack?: boolean;
+    anonymizeIp?: boolean;
+    batchSize?: number;
+    batchInterval?: number;
+}
+interface ConversionData {
+    type: string;
+    revenue: number;
+    currency?: string;
+    orderId?: string;
+    properties?: Record<string, any>;
+}
+declare class AureaSDK {
+    private config;
+    private sessionId;
+    private anonymousId;
+    private userId?;
+    private eventQueue;
+    private batchTimer?;
+    private initialized;
+    constructor(config: AureaConfig);
+    /**
+     * Initialize the SDK
+     */
+    init(): void;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: Record<string, any>): void;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, traits?: Record<string, any>): void;
+    /**
+     * Track a page view
+     */
+    page(name?: string, properties?: Record<string, any>): void;
+    /**
+     * Track a conversion event
+     */
+    conversion(data: ConversionData): void;
+    /**
+     * Get or create session ID
+     */
+    private getOrCreateSessionId;
+    /**
+     * Get or create anonymous ID
+     */
+    private getOrCreateAnonymousId;
+    /**
+     * Build event context
+     */
+    private buildContext;
+    /**
+     * Track initial page load
+     */
+    private trackPageLoad;
+    /**
+     * Track page changes (for SPAs)
+     */
+    private trackPageChanges;
+    /**
+     * Track form submissions
+     */
+    private trackForms;
+    /**
+     * Track scroll depth
+     */
+    private trackScrollDepth;
+    /**
+     * Enqueue event for batching
+     */
+    private enqueueEvent;
+    /**
+     * Send events to API
+     */
+    private sendEvents;
+    /**
+     * Flush queued events
+     */
+    private flushEvents;
+    /**
+     * Start batch timer
+     */
+    private startBatchTimer;
+    /**
+     * Poll for purchase completion
+     * Checks every 3 seconds if user has made a purchase
+     */
+    private startPurchasePolling;
+    /**
+     * Check if user has completed a purchase
+     */
+    private checkForPurchase;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Generate event ID
+     */
+    private generateEventId;
+}
+/**
+ * Initialize Aurea SDK
+ */
+declare function initAurea(config: AureaConfig): AureaSDK;
+/**
+ * Get SDK instance
+ */
+declare function getAurea(): AureaSDK | null;
+/**
+ * Helper: Track custom event
+ */
+declare function trackEvent(name: string, properties?: Record<string, any>): void;
+/**
+ * Helper: Identify user
+ */
+declare function identifyUser(userId: string, traits?: Record<string, any>): void;
+/**
+ * Helper: Track conversion
+ */
+declare function trackConversion(data: ConversionData): void;
+/**
+ * Helper: Track page view
+ */
+declare function trackPage(name?: string, properties?: Record<string, any>): void;
+
+export { getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };