@webticks/core 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# WebTicks Core - Usage Examples
+
+## Browser Usage (No Changes Required!)
+
+Your existing React/Next.js packages continue to work exactly as before:
+
+```jsx
+import WebTicksAnalytics from '@webticks/react';
+
+function App() {
+  return (
+    <div>
+      <WebTicksAnalytics />
+      {/* Your app */}
+    </div>
+  );
+}
+```
+
+## Server-Side Usage
+
+### Option 1: Express Middleware (Automatic)
+
+```javascript
+import express from 'express';
+import { createServerMiddleware } from '@webticks/core/server';
+
+const app = express();
+
+// Automatically track all HTTP requests
+app.use(createServerMiddleware({
+  backendUrl: 'https://api.example.com/track'
+}));
+
+app.listen(3000);
+```
+
+### Option 2: Manual Tracking
+
+```javascript
+import { AnalyticsTracker } from '@webticks/core/tracker';
+
+const tracker = new AnalyticsTracker({
+  backendUrl: 'https://api.example.com/track'
+});
+
+// Track server requests
+tracker.trackServerRequest({
+  method: 'GET',
+  path: '/api/users',
+  query: { page: 1 },
+  headers: { 'user-agent': 'Mozilla/5.0' }
+});
+
+// Track custom events
+tracker.trackEvent('database_query', {
+  table: 'users',
+  duration: 45
+});
+
+// Send immediately (useful for serverless)
+await tracker.sendQueue();
+```
+
+### Next.js Example
+
+```javascript
+// pages/api/users.js
+import { AnalyticsTracker } from '@webticks/core/tracker';
+
+const tracker = new AnalyticsTracker({
+  backendUrl: process.env.ANALYTICS_URL
+});
+
+export default async function handler(req, res) {
+  tracker.trackServerRequest({
+    method: req.method,
+    path: req.url,
+    query: req.query,
+    headers: {
+      'user-agent': req.headers['user-agent']
+    }
+  });
+
+  // Your API logic here
+  const data = await getUsers();
+  
+  res.status(200).json(data);
+}
+```
+
+## Key Benefits
+
+✅ **Centralized Logic**: All tracking logic lives in `@webticks/core`  
+✅ **Environment Agnostic**: Works in browser and Node.js  
+✅ **Zero Breaking Changes**: Existing packages work without modifications  
+✅ **Easy Updates**: Fix bugs once, all environments benefit  
+✅ **Flexible**: Works with any framework (Express, Koa, Fastify, serverless, etc.)

package/injector.js

@@ -0,0 +1,27 @@
+import { AnalyticsTracker } from "./tracker.js";
+
+export default function inject() {
+  // Only auto-inject in browser environments
+  if (typeof window === 'undefined') {
+    console.warn("webticks auto-inject skipped: Not in a browser environment.");
+    return;
+  }
+
+  if (window.webticks) {
+    console.warn("webticks tracker already initialized.");
+    return;
+  }
+
+  const config = {
+    backendUrl: "https://api.example.com/track"
+  };
+
+  const tracker = new AnalyticsTracker(config);
+  tracker.autoTrackPageViews();
+  window.webticks = tracker;
+};
+
+// Only auto-execute in browser
+if (typeof window !== 'undefined') {
+  inject();
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@webticks/core",
+  "version": "0.1.0",
+  "description": "Lightweight analytics library for modern web applications with seamless event tracking and page view monitoring",
+  "type": "module",
+  "main": "injector.js",
+  "module": "injector.js",
+  "exports": {
+    ".": "./injector.js",
+    "./inject": "./injector.js",
+    "./tracker": "./tracker.js",
+    "./platform-adapters": "./platform-adapters.js"
+  },
+  "files": [
+    "tracker.js",
+    "injector.js",
+    "platform-adapters.js",
+    "types.js",
+    "README.md"
+  ],
+  "keywords": [
+    "analytics",
+    "tracking",
+    "web-analytics",
+    "event-tracking",
+    "page-views",
+    "metrics",
+    "telemetry"
+  ],
+  "author": "Celerinc Team",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Celerinc/webticks.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Celerinc/webticks#readme",
+  "bugs": {
+    "url": "https://github.com/Celerinc/webticks/issues"
+  }
+}

package/platform-adapters.js

@@ -0,0 +1,112 @@
+/**
+ * Platform adapters to abstract browser vs Node.js environment differences
+ */
+
+// Environment detection
+export function isServer() {
+    return typeof window === 'undefined';
+}
+
+export function isBrowser() {
+    return typeof window !== 'undefined';
+}
+
+/**
+ * Browser-specific adapter
+ */
+export class BrowserAdapter {
+    constructor() {
+        this.storage = window.localStorage;
+    }
+
+    // Generate or retrieve user ID
+    getUserId() {
+        let userId = this.storage.getItem('webticks_uid');
+        if (!userId) {
+            userId = crypto.randomUUID();
+            this.storage.setItem('webticks_uid', userId);
+        }
+        return userId;
+    }
+
+    // Send HTTP request
+    async sendRequest(url, data, appId) {
+        const headers = { 'Content-Type': 'application/json' };
+
+        // Add webticks-app-id header if appId is provided
+        if (appId) {
+            headers['webticks-app-id'] = appId;
+        }
+
+        return fetch(url, {
+            method: 'POST',
+            headers: headers,
+            body: JSON.stringify(data)
+        }).catch((err) => console.warn('Error sending request:', err));
+    }
+
+    // Get current path
+    getCurrentPath() {
+        return window.location.href;
+    }
+
+    // Setup auto-tracking (browser-specific)
+    setupAutoTracking(tracker) {
+        // Patch history API
+        tracker.originalPushState = window.history.pushState;
+        tracker.originalReplaceState = window.history.replaceState;
+
+        window.history.pushState = (...args) => {
+            const result = tracker.originalPushState.apply(window.history, args);
+            tracker.checkPageChange();
+            if (typeof window.history.onpushstate === "function") {
+                window.history.onpushstate({ state: args[0] });
+            }
+            return result;
+        };
+
+        window.history.replaceState = (...args) => {
+            const result = tracker.originalReplaceState.apply(window.history, args);
+            tracker.checkPageChange();
+            if (typeof window.history.onreplacestate === "function") {
+                window.history.onreplacestate({ state: args[0] });
+            }
+            return result;
+        };
+
+        window.addEventListener('popstate', tracker.checkPageChange);
+        document.addEventListener('visibilitychange', tracker.handleVisibilityChange);
+        window.addEventListener('pagehide', tracker.handlePageHide);
+
+        // Track initial page view
+        tracker.lastPath = window.location.href;
+        tracker.trackPageView(tracker.lastPath);
+    }
+
+    // Cleanup auto-tracking
+    cleanupAutoTracking(tracker) {
+        if (tracker.originalPushState) {
+            window.history.pushState = tracker.originalPushState;
+        }
+        if (tracker.originalReplaceState) {
+            window.history.replaceState = tracker.originalReplaceState;
+        }
+        window.removeEventListener('popstate', tracker.checkPageChange);
+        document.removeEventListener('visibilitychange', tracker.handleVisibilityChange);
+        window.removeEventListener('pagehide', tracker.handlePageHide);
+    }
+}
+
+/**
+ * Factory function to get the appropriate adapter
+ * Core package only provides browser adapter
+ * For Node.js, use @webticks/node package
+ */
+export function getPlatformAdapter() {
+    if (isBrowser()) {
+        return new BrowserAdapter();
+    }
+    // For server-side, users should use @webticks/node package
+    console.warn('Running in server environment. Please use @webticks/node package for server-side tracking.');
+    return null;
+}

package/tracker.js

@@ -0,0 +1,265 @@
+import { getPlatformAdapter, isServer, isBrowser } from './platform-adapters.js';
+
+// Import type definitions
+/**
+ * @typedef {import('./types.js').Event} Event
+ * @typedef {import('./types.js').PageViewEvent} PageViewEvent
+ * @typedef {import('./types.js').CustomEvent} CustomEvent
+ * @typedef {import('./types.js').ServerRequestEvent} ServerRequestEvent
+ * @typedef {import('./types.js').AnalyticsBatch} AnalyticsBatch
+ */
+
+export class AnalyticsTracker {
+  /**
+   * @param {Object} config - Tracker configuration
+   * @param {string} config.backendUrl - URL to send analytics data
+   * @param {string} [config.appId] - Application ID for tracking (can also be set via WEBTICKS_APP_ID env variable)
+   */
+  constructor(config) {
+    this.config = config || { backendUrl: "/api/track" };
+
+    // Get appId from config or environment variable
+    this.appId = this.config.appId || this.getAppIdFromEnv();
+
+    /** @type {Event[]} */
+    this.eventQueue = [];
+    this.lastPath = "";
+    this.batchSendInterval = 10000;
+    this.sendTimer = null;
+    /** @type {string|null} */
+    this.userId = null;
+    /** @type {string|null} */
+    this.sessionId = null; // Session ID stored in memory
+    this.adapter = getPlatformAdapter();
+
+    // Bind methods
+    this.checkPageChange = this.checkPageChange.bind(this);
+    this.sendQueue = this.sendQueue.bind(this);
+    this.handleVisibilityChange = this.handleVisibilityChange.bind(this);
+    this.handlePageHide = this.handlePageHide.bind(this);
+
+    this.initializeUser();
+    this.initializeSession();
+
+    console.log(`AnalyticsTracker initialized in ${isServer() ? 'Node.js' : 'Browser'} environment.`);
+  }
+
+  /**
+   * Get app ID from environment variable
+   * Works in both browser (import.meta.env) and Node.js (process.env)
+   */
+  getAppIdFromEnv() {
+    // Browser environment (Vite, etc.)
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      return import.meta.env.VITE_WEBTICKS_APP_ID || import.meta.env.WEBTICKS_APP_ID;
+    }
+    // Node.js environment
+    if (typeof process !== 'undefined' && process.env) {
+      return process.env.WEBTICKS_APP_ID;
+    }
+    return null;
+  }
+
+  initializeUser() {
+    // Skip if adapter is not available (will be initialized later in server environments)
+    if (!this.adapter) {
+      return;
+    }
+
+    if (!this.userId) {
+      this.userId = this.adapter.getUserId();
+    }
+  }
+
+  /**
+   * Initialize session ID
+   * Session is stored in memory and will be destroyed when the page/instance is closed
+   */
+  initializeSession() {
+    // Generate new session ID using crypto (available in both browser and Node.js)
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      this.sessionId = crypto.randomUUID();
+      console.log(`Session initialized: ${this.sessionId}`);
+    } else {
+      // Fallback for older environments
+      this.sessionId = this.generateFallbackId();
+      console.warn('crypto.randomUUID not available, using fallback ID generation');
+    }
+  }
+
+  /**
+   * Generate fallback ID if crypto.randomUUID is not available
+   */
+  generateFallbackId() {
+    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);
+    });
+  }
+
+  /**
+   * Automatically track page views (browser) or HTTP requests (server)
+   * Works in both environments!
+   */
+  autoTrackPageViews() {
+    if (isServer()) {
+      console.log("Setting up automatic server-side tracking...");
+    } else {
+      console.log("Setting up automatic page view tracking...");
+    }
+
+    // Use adapter to setup platform-specific tracking
+    this.adapter.setupAutoTracking(this);
+
+    // Start the batch send timer
+    this.sendTimer = setInterval(this.sendQueue, this.batchSendInterval);
+  }
+
+  /**
+   * Check for page changes (browser-only)
+   */
+  checkPageChange() {
+    if (isServer()) return;
+
+    const currentPath = this.adapter.getCurrentPath();
+    if (currentPath !== this.lastPath) {
+      console.log(`Page change detected: ${this.lastPath} -> ${currentPath}`);
+      this.lastPath = currentPath;
+      this.trackPageView(currentPath);
+    }
+  }
+
+  /**
+   * Handle visibility changes (browser-only)
+   */
+  handleVisibilityChange() {
+    if (isServer()) return;
+
+    if (document.hidden) {
+      this.trackEvent('visibility_change', { visible: false });
+    } else {
+      this.trackEvent('visibility_change', { visible: true });
+    }
+  }
+
+  /**
+   * Handle page hide event (browser-only)
+   */
+  handlePageHide() {
+    console.log("Page hidden, attempting final batch send.");
+    this.sendQueue();
+  }
+
+  /**
+   * Track a page view
+   * @param {string} path - The path/URL to track
+   * @returns {PageViewEvent} The created event
+   */
+  trackPageView(path) {
+    /** @type {PageViewEvent} */
+    const event = {
+      requestId: crypto.randomUUID ? crypto.randomUUID() : this.generateFallbackId(),
+      type: 'pageview',
+      path: path,
+      timestamp: new Date().toISOString()
+    };
+
+    this.eventQueue.push(event);
+    return event;
+  }
+
+  /**
+   * Track a custom event
+   * @param {string} eventName - Name of the event
+   * @param {Object} [details={}] - Event details/metadata
+   * @returns {CustomEvent} The created event
+   */
+  trackEvent(eventName, details = {}) {
+    /** @type {CustomEvent} */
+    const event = {
+      requestId: crypto.randomUUID ? crypto.randomUUID() : this.generateFallbackId(),
+      type: 'custom',
+      name: eventName,
+      details: details,
+      path: isBrowser() ? window.location.href : null,
+      timestamp: new Date().toISOString()
+    };
+
+    this.eventQueue.push(event);
+    return event;
+  }
+
+  /**
+   * Track a server-side HTTP request (server-only)
+   * @param {Object} requestData - Request information
+   * @param {string} requestData.method - HTTP method (GET, POST, etc.)
+   * @param {string} requestData.path - Request path
+   * @param {Object} [requestData.query] - Query parameters
+   * @param {Object} [requestData.headers] - Request headers
+   * @returns {ServerRequestEvent} The created event
+   */
+  trackServerRequest(requestData) {
+    /** @type {ServerRequestEvent} */
+    const event = {
+      requestId: crypto.randomUUID ? crypto.randomUUID() : this.generateFallbackId(),
+      type: 'server_request',
+      method: requestData.method,
+      path: requestData.path,
+      query: requestData.query,
+      headers: requestData.headers,
+      timestamp: new Date().toISOString()
+    };
+
+    this.eventQueue.push(event);
+    return event;
+  }
+
+  /**
+   * Send queued events to the backend
+   */
+  async sendQueue() {
+    if (this.eventQueue.length === 0) {
+      return;
+    }
+
+    const eventsToSend = [...this.eventQueue];
+
+    try {
+      const response = await this.adapter.sendRequest(this.config.backendUrl, {
+        uid: this.userId,
+        sessionId: this.sessionId,
+        events: eventsToSend,
+        datetime: new Date().toISOString()
+      }, this.appId);
+
+      if (response.ok) {
+        // Clear queue on success
+        this.eventQueue = [];
+      } else {
+        console.error(`Failed to send analytics batch: ${response.status}`);
+        // Keep events in queue to retry
+        this.eventQueue = [...eventsToSend];
+      }
+    } catch (err) {
+      console.error("Failed to send analytics batch:", err);
+      // Keep events in queue to retry
+      this.eventQueue = [...eventsToSend];
+    }
+  }
+
+  /**
+   * Cleans up listeners and timers
+   */
+  destroy() {
+    console.log("Destroying tracker...");
+
+    // Stop the batch sender
+    if (this.sendTimer) {
+      clearInterval(this.sendTimer);
+    }
+
+    // Use adapter to cleanup platform-specific tracking
+    this.adapter.cleanupAutoTracking(this);
+  }
+}

package/types.js

@@ -0,0 +1,61 @@
+/**
+ * Type definitions for WebTicks Analytics Events
+ * Using JSDoc for type safety in JavaScript
+ */
+
+/**
+ * Base Event interface - common fields for all events
+ * @typedef {Object} BaseEvent
+ * @property {string} requestId - Unique identifier for this specific request
+ * @property {string} type - Type of event ('pageview' | 'custom' | 'server_request')
+ * @property {string} timestamp - ISO timestamp when the event was created
+ */
+
+/**
+ * Page View Event - tracks page navigation
+ * @typedef {Object} PageViewEvent
+ * @property {string} requestId - Unique identifier for this specific request
+ * @property {'pageview'} type - Event type identifier
+ * @property {string} path - The URL/path that was viewed
+ * @property {string} timestamp - ISO timestamp when the event was created
+ */
+
+/**
+ * Custom Event - tracks custom user interactions
+ * @typedef {Object} CustomEvent
+ * @property {string} requestId - Unique identifier for this specific request
+ * @property {'custom'} type - Event type identifier
+ * @property {string} name - Name of the custom event
+ * @property {Object} details - Additional event metadata
+ * @property {string|null} path - Current page URL (browser only)
+ * @property {string} timestamp - ISO timestamp when the event was created
+ */
+
+/**
+ * Server Request Event - tracks server-side HTTP requests
+ * @typedef {Object} ServerRequestEvent
+ * @property {string} requestId - Unique identifier for this specific request
+ * @property {'server_request'} type - Event type identifier
+ * @property {string} method - HTTP method (GET, POST, etc.)
+ * @property {string} path - Request path
+ * @property {Object} [query] - Query parameters
+ * @property {Object} [headers] - Request headers
+ * @property {string} timestamp - ISO timestamp when the event was created
+ */
+
+/**
+ * Union type for all possible events
+ * @typedef {PageViewEvent | CustomEvent | ServerRequestEvent} Event
+ */
+
+/**
+ * Analytics batch payload sent to backend
+ * @typedef {Object} AnalyticsBatch
+ * @property {string} uid - User ID
+ * @property {string} sessionId - Session ID
+ * @property {Event[]} events - Array of events to track
+ * @property {string} datetime - ISO timestamp when the batch was sent
+ */
+
+// Export types for use in other modules
+export { };