clarity-analytics-sdk 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# Clarity Analytics SDK
+
+A lightweight JavaScript SDK for tracking events and analytics with Clarity Analytics.
+
+## Installation
+
+```bash
+npm install clarity-analytics-sdk
+```
+
+## Usage
+
+```javascript
+const ClarityAnalytics = require('clarity-analytics-sdk');
+
+// Initialize the SDK
+const analytics = new ClarityAnalytics({
+  baseUrl: 'https://api.yourbackend.com',
+  apiUrl: 'https://api.yourbackend.com/api/v1/events/publish-event',
+  projectId: 'your-project-id',
+  debug: true
+});
+
+// Wait for SDK to be ready
+await analytics.ready();
+
+// Track events
+analytics.track('Button Click', {
+  button_id: 'signup',
+  page: '/landing'
+});
+```
+
+## Configuration
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `baseUrl` | Yes | Base URL for your backend API |
+| `apiUrl` | Yes | Full URL for the events endpoint |
+| `projectId` | Yes | Your project identifier |
+| `debug` | No | Enable debug logging (default: false) |
+
+## License
+
+MIT © Vivaconnect
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "clarity-analytics-sdk",
+  "version": "1.0.0",
+  "description": "A lightweight JavaScript SDK for tracking events and analytics with Clarity Analytics",
+  "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "npm run validate",
+    "validate": "node -c src/index.js",
+    "mend": "mend code --inc -d . -s clarity_backend//sdk-website --report --formats pdf",
+    "standard": "standard"
+  },
+  "author": "Vivaconnect",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "standard": {
+    "env": [
+      "browser",
+      "node"
+    ],
+    "globals": [
+      "localStorage",
+      "ClarityAnalytics",
+      "getProjectId",
+      "getSessionId",
+      "getUserId",
+      "initSDK"
+    ],
+    "ignore": [
+      "src/staging.js"
+    ]
+  },
+  "devDependencies": {
+    "standard": "^17.1.2",
+    "terser": "^5.44.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,557 @@
+/**
+ * Clarity Analytics SDK
+ * A lightweight JavaScript SDK for tracking events and analytics
+ * Version: 1.0.0
+ */
+
+(function (window) {
+  'use strict'
+
+  /**
+   * Clarity Analytics SDK Class
+   */
+  class ClarityAnalytics {
+    constructor (config = {}) {
+      if (!config.projectId) {
+        throw new Error('ClarityAnalytics: projectId is required')
+      }
+      // Configuration
+      this.config = {
+        apiUrl: 'https://apps.helo.ai/api/v1/clarity/events/publish-event',
+        fetchUserIdUrl: 'https://apps.helo.ai/api/v1/clarity/projects?id=',
+        // apiUrl: 'http://localhost:9030/api/v1/events/publish-event',
+        // fetchUserIdUrl: 'http://localhost:9030/api/v1/projects?id=',
+        projectId: config.projectId,
+        projectName: config.projectName || '',
+        apiKey: config.apiKey || null,
+        userId: null, // Will be fetched from backend
+        sessionId: config.sessionId || this._generateSessionId(),
+        debug: config.debug || false,
+        retryAttempts: config.retryAttempts || 3,
+        timeout: config.timeout || 10000,
+        batchSize: config.batchSize || 1, // For future batching feature
+        flushInterval: config.flushInterval || 5000 // For future batching feature
+      }
+
+      // Internal state
+      this._eventQueue = []
+      this._isInitialized = false
+      this._initializationPromise = null
+      this._deviceInfo = this._getDeviceInfo()
+      this._sessionStart = Date.now()
+
+      // Initialize SDK (fetch user ID from backend)
+      this._initializationPromise = this._initialize(config)
+    }
+
+    /**
+     * Initialize SDK - Fetch user ID from backend
+     * @private
+     */
+    async _initialize (config) {
+      try {
+        // Fetch user ID from backend
+        const { userId, ipaddress } = await this._fetchUserId(this.config.projectId)
+
+        if (!userId) {
+          throw new Error('Failed to fetch user ID from backend')
+        }
+
+        this.config.userId = userId
+        this.config.ipaddress = ipaddress
+        this._isInitialized = true
+
+        // Auto-collect page view if enabled
+        if (config.autoPageView !== false) {
+          this._trackPageView()
+        }
+
+        return this
+      } catch (error) {
+        this._isInitialized = false
+        throw new Error(`ClarityAnalytics initialization failed: ${error.message}`)
+      }
+    }
+
+    /**
+     * Wait for SDK to be ready
+     * @returns {Promise} Resolves when SDK is initialized
+     */
+    async ready () {
+      return this._initializationPromise
+    }
+
+    /**
+     * Fetch user ID from backend
+     * @private
+     */
+    async _fetchUserId (projectId) {
+      const url = `${this.config.fetchUserIdUrl}${projectId}`
+
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout)
+
+      try {
+        const response = await fetch(url, {
+          method: 'GET',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` })
+          },
+          signal: controller.signal
+        })
+
+        clearTimeout(timeoutId)
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+        }
+
+        const responseData = await response.json()
+        // Extract userId from response (supports multiple response structures)
+        let userId = null
+        let ipaddress = null
+
+        // Check if response has a 'data' wrapper
+        if (responseData?.data) {
+          userId = responseData?.data?.userId
+          ipaddress = responseData?.data?.ipaddress
+        } else {
+          userId = responseData?.userId
+          ipaddress = responseData?.ipaddress
+        }
+
+        if (!userId) {
+          throw new Error('User ID not found in API response')
+        }
+
+        return { userId, ipaddress }
+      } catch (error) {
+        clearTimeout(timeoutId)
+        throw error
+      }
+    }
+
+    /**
+     * Track a custom event
+     * @param {string} eventName - Name of the event
+     * @param {Object} properties - Event properties
+     * @param {Object} options - Additional options
+     */
+    async track (eventName, properties = {}, options = {}) {
+      console.log({ eventName, properties, options })
+      // Wait for SDK to be initialized
+      if (!this._isInitialized) {
+        try {
+          await this._initializationPromise
+        } catch (error) {
+          return Promise.reject(new Error('SDK not initialized: ' + error.message))
+        }
+      }
+
+      // Double check initialization status
+      if (!this._isInitialized) {
+        return Promise.reject(new Error('SDK not initialized'))
+      }
+
+      if (!eventName) {
+        throw new Error('Event name is required')
+      }
+
+      const eventData = this._buildEventPayload({
+        eventType: options.eventType || 'custom',
+        eventName,
+        eventKey: options.eventKey || this._sanitizeEventName(eventName),
+        properties,
+        sessionId: properties.sessionId || options.sessionId,
+        context: options.context || {},
+        traits: options.traits || {},
+        ipaddress: options.ipaddress || this.config.ipaddress,
+        customId: properties.userId || options.userId
+      })
+      return this._sendEvent(eventData)
+    }
+
+    /**
+     * Track a page view
+     * @param {Object} properties - Page properties
+     * @param {Object} options - Additional options
+     */
+    // async page (properties = {}, options = {}) {
+    //   const pageName = properties.name || (typeof document !== 'undefined' ? document.title : 'Page View')
+
+    //   return this.track('page_view', {
+    //     ...properties,
+    //     page_name: pageName
+    //   }, {
+    //     ...options,
+    //     eventType: 'pageview',
+    //     eventKey: 'page_view'
+    //   })
+    // }
+
+    /**
+       * Build complete event payload
+       * @private
+       */
+    _buildEventPayload (data) {
+      const timestamp = Date.now()
+      const eventId = this._generateUUID()
+      const requestId = this._generateRequestId()
+      const userId = data.customId || this.config.userId
+
+      // Determine system_user_id (real user ID) vs anonymous user_id
+      let systemUserId = ''
+      const finalUserId = userId
+
+      if (userId && !userId.startsWith('user_')) {
+        // If it's a real user ID provided by the application
+        systemUserId = userId
+      }
+
+      // Build flat event payload (matching staging.js structure)
+      return {
+        // Event identifiers
+        event_id: eventId,
+        request_id: requestId,
+        event_name: data.eventName || 'Unnamed Event',
+        timestamp,
+
+        // User and session
+        user_id: finalUserId,
+        session_id: data.sessionId || this.config.sessionId,
+        system_user_id: systemUserId,
+
+        // Project information
+        project_id: this.config.projectId,
+        project_name: this.config.projectName || '',
+
+        // Device information (flattened)
+        device: this._deviceInfo.device.type,
+        os: this._deviceInfo.device.os,
+        os_version: this._deviceInfo.device.osVersion,
+        model: this._deviceInfo.device.model,
+        brand: this._deviceInfo.device.brand,
+
+        // Browser information (flattened)
+        browser: this._deviceInfo.browser.name,
+        browser_version: this._deviceInfo.browser.version,
+        browser_engine: this._deviceInfo.browser.engine,
+
+        // Location information (flattened)
+        timezone: typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : 'UTC',
+        language: typeof navigator !== 'undefined' ? navigator.language : 'en-US',
+
+        // Network information (flattened)
+        network_type: this._getConnectionType(),
+
+        // SDK information (flattened)
+        sdk_name: 'clarity',
+        sdk_version: '1.0.0',
+
+        // IP address
+        ip: data.ipaddress || this.config.ipaddress || '',
+
+        // Properties object with all custom data
+        properties: {
+          page_url: (typeof window !== 'undefined' && window.location) ? window.location.href : '',
+          page_title: (typeof document !== 'undefined') ? document.title : '',
+          page_path: (typeof window !== 'undefined' && window.location) ? window.location.pathname : '',
+          referrer: (typeof document !== 'undefined') ? (document.referrer || 'direct') : 'direct',
+          eventType: data.eventType || 'custom',
+          eventKey: data.eventKey || this._sanitizeEventName(data.eventName || ''),
+          // Custom properties
+          ...(data.properties || {})
+        },
+
+        // Context for any additional data
+        context: {
+          ...(data.context || {})
+        }
+      }
+    }
+
+    /**
+       * Send event to API
+       * @private
+       */
+    async _sendEvent (eventData, attempt = 1) {
+      try {
+        const headers = {
+          'Content-Type': 'application/json'
+        }
+
+        if (this.config.apiKey) {
+          headers.Authorization = `Bearer ${this.config.apiKey}`
+        }
+
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout)
+        console.log('eventData', eventData)
+        const response = await fetch(this.config.apiUrl, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(eventData),
+          signal: controller.signal
+        })
+
+        clearTimeout(timeoutId)
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+        }
+
+        const result = await response.json()
+        return result
+      } catch (error) {
+        // Retry logic
+        if (attempt < this.config.retryAttempts && !error.name === 'AbortError') {
+          const delay = Math.pow(2, attempt) * 1000 // Exponential backoff
+          await new Promise(resolve => setTimeout(resolve, delay))
+          return this._sendEvent(eventData, attempt + 1)
+        }
+
+        throw error
+      }
+    }
+
+    /**
+       * Track initial page view
+       * @private
+       */
+    _trackPageView () {
+      // Skip in Node.js environment
+      if (typeof document === 'undefined') {
+        return
+      }
+
+      // Wait for DOM to be ready
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+          setTimeout(() => this.page(), 100)
+        })
+      } else {
+        setTimeout(() => this.page(), 100)
+      }
+    }
+
+    /**
+       * Get device and browser information
+       * @private
+       */
+    _getDeviceInfo () {
+      let isNodeJS = false
+      let ua = 'Unknown'
+
+      // Detect runtime environment
+      if (typeof window === 'undefined' && typeof process !== 'undefined' && process.versions && process.versions.node) {
+        // Node.js
+        isNodeJS = true
+        ua = 'Node.js'
+      } else if (typeof navigator !== 'undefined' && navigator.userAgent) {
+        // Browser
+        ua = navigator.userAgent
+      }
+
+      const device = {
+        type: 'unknown',
+        brand: 'Unknown',
+        model: 'Unknown',
+        os: 'Unknown',
+        osVersion: 'Unknown'
+      }
+      const browser = {
+        name: 'Unknown',
+        version: 'Unknown',
+        engine: 'Unknown'
+      }
+
+      if (isNodeJS) {
+        // Node.js specifics
+        device.type = 'server'
+        device.os = process.platform || 'Node.js'
+        device.osVersion = process.version || 'Unknown'
+
+        browser.name = 'Node.js'
+        browser.version = process.version || 'Unknown'
+        browser.engine = 'V8'
+      } else if (ua !== 'Unknown') {
+        // Browser specifics
+
+        // Device type
+        if (/Mobile|Android|iPhone|iPad|iPod/i.test(ua)) {
+          device.type = 'mobile'
+        } else if (/Tablet|iPad/i.test(ua)) {
+          device.type = 'tablet'
+        } else {
+          device.type = 'desktop'
+        }
+
+        // OS Detection
+        if (/Windows NT 10.0/.test(ua)) {
+          device.os = 'Windows'
+          device.osVersion = '10'
+        } else if (/Windows NT 6.3/.test(ua)) {
+          device.os = 'Windows'
+          device.osVersion = '8.1'
+        } else if (/Windows NT 6.2/.test(ua)) {
+          device.os = 'Windows'
+          device.osVersion = '8'
+        } else if (/Windows NT 6.1/.test(ua)) {
+          device.os = 'Windows'
+          device.osVersion = '7'
+        } else if (/Mac OS X ([0-9_]+)/.test(ua)) {
+          device.os = 'macOS'
+          const match = ua.match(/Mac OS X ([0-9_]+)/)
+          if (match) {
+            device.osVersion = match[1].replace(/_/g, '.')
+          }
+        } else if (/Android ([0-9.]+)/.test(ua)) {
+          device.os = 'Android'
+          const match = ua.match(/Android ([0-9.]+)/)
+          if (match) {
+            device.osVersion = match[1]
+          }
+        } else if (/iPhone|iPad|iPod/.test(ua)) {
+          device.os = 'iOS'
+          const match = ua.match(/OS ([0-9_]+)/)
+          if (match) {
+            device.osVersion = match[1].replace(/_/g, '.')
+          }
+        } else if (/Linux/.test(ua)) {
+          device.os = 'Linux'
+          // Try to extract kernel version
+          const match = ua.match(/Linux ([0-9.]+)/)
+          if (match) {
+            device.osVersion = match[1]
+          }
+        }
+
+        // Browser detection (order matters)
+        if (ua.includes('Edg/')) {
+          browser.name = 'Edge'
+          browser.engine = 'Blink'
+          const match = ua.match(/Edg\/([0-9.]+)/)
+          if (match) browser.version = match[1]
+        } else if (ua.includes('OPR/')) {
+          browser.name = 'Opera'
+          browser.engine = 'Blink'
+          const match = ua.match(/OPR\/([0-9.]+)/)
+          if (match) browser.version = match[1]
+        } else if (ua.includes('Chrome') && !ua.includes('Edg')) {
+          // Chrome (should be after Edge/Opera)
+          browser.name = 'Chrome'
+          browser.engine = 'Blink'
+          const match = ua.match(/Chrome\/([0-9.]+)/)
+          if (match) browser.version = match[1]
+        } else if (ua.includes('Firefox')) {
+          browser.name = 'Firefox'
+          browser.engine = 'Gecko'
+          const match = ua.match(/Firefox\/([0-9.]+)/)
+          if (match) browser.version = match[1]
+        } else if (ua.includes('Safari') && !ua.includes('Chrome') && !ua.includes('Chromium')) {
+          browser.name = 'Safari'
+          browser.engine = 'WebKit'
+          const match = ua.match(/Version\/([0-9.]+)/)
+          if (match) browser.version = match[1]
+        }
+      }
+      return { device, browser }
+    }
+
+    /**
+       * Get network connection type
+       * @private
+       */
+    _getConnectionType () {
+      if (typeof navigator !== 'undefined' && navigator.connection) {
+        return navigator.connection.effectiveType || 'unknown'
+      }
+      return 'unknown'
+    }
+
+    /**
+       * Get screen information
+       * @private
+       */
+    _getScreenInfo () {
+      if (typeof window !== 'undefined' && window.screen) {
+        return {
+          width: window.screen.width || 0,
+          height: window.screen.height || 0,
+          density: window.devicePixelRatio || 1
+        }
+      }
+      // Default for Node.js or environments without screen
+      return {
+        width: 0,
+        height: 0,
+        density: 1
+      }
+    }
+
+    /**
+       * Generate session ID
+       * @private
+       */
+    _generateSessionId () {
+      return 'sess_' + this._generateId()
+    }
+
+    /**
+       * Generate UUID v4
+       * @private
+       */
+    _generateUUID () {
+      // Simple UUID v4 generator for browsers without crypto.randomUUID
+      if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID()
+      }
+
+      // Fallback UUID v4 generator
+      return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = Math.random() * 16 | 0
+        const v = c === 'x' ? r : (r & 0x3 | 0x8)
+        return v.toString(16)
+      })
+    }
+
+    /**
+       * Generate request ID
+       * @private
+       */
+    _generateRequestId () {
+      return 'req_' + this._generateId()
+    }
+
+    /**
+       * Generate random ID
+       * @private
+       */
+    _generateId () {
+      return Date.now().toString(36) + Math.random().toString(36).substr(2)
+    }
+
+    /**
+       * Sanitize event name for use as event key
+       * @private
+       */
+    _sanitizeEventName (name) {
+      return name.toLowerCase().replace(/[^a-z0-9]/g, '_')
+    }
+  }
+
+  // Export for different module systems
+  if (typeof module !== 'undefined' && module.exports) {
+    // Node.js
+    module.exports = ClarityAnalytics
+  } else if (typeof define === 'function' && define.amd) { // eslint-disable-line no-undef
+    // AMD
+    define([], function () { // eslint-disable-line no-undef
+      return ClarityAnalytics
+    })
+  } else {
+    // Browser globals
+    window.ClarityAnalytics = ClarityAnalytics
+  }
+})(typeof window !== 'undefined' ? window : this)