@phystack/analytics-publisher 4.3.40-dev

package/examples/kafka.ts

@@ -0,0 +1,189 @@
+/**
+ * Kafka Usage Example
+ *
+ * This example demonstrates how to use the AnalyticsClient with simplified Kafka adapter.
+ * One Kafka client per region deployment - loosely coupled from data residency.
+ * Run this with: npm run example:kafka
+ */
+
+import { AnalyticsClient } from '../src/client/AnalyticsClient';
+
+async function main() {
+  console.log('🚀 Starting Kafka Analytics Client Example...');
+  // Simple Kafka adapter configuration - one client per region
+  const kafkaAnalytics = new AnalyticsClient({
+    adapter: 'kafka',
+    adapterConfig: {
+      brokers: ['localhost:9092'], // Your Kafka broker
+      clientId: 'analytics-client',
+      connectionTimeout: 10000,
+      requestTimeout: 30000,
+      ssl: {
+        rejectUnauthorized: false,
+      },
+      sasl: {
+        mechanism: 'scram-sha-512',
+        username: 'kafka-user',
+        password: 'kafka-password',
+      },
+    },
+    bufferSize: 50,
+    flushIntervalMs: 1000,
+    maxRetries: 3,
+  });
+
+  try {
+    console.log('🔧 Initializing Kafka analytics client...');
+    await kafkaAnalytics.init();
+    console.log('✅ Kafka analytics client initialized');
+
+    console.log('📊 Publishing sample events to Kafka...');
+
+    // Publish Event (package handles date conversion automatically)
+    await kafkaAnalytics.publishEvent({
+      captureId: 'capture-123',
+      tenantId: 'company-x',
+      spaceId: 'space-123',
+      sessionId: 'session_789',
+      clientId: 'client-456',
+      eventType: 'button_click',
+      eventTime: new Date(), // Can pass Date object - package converts to ISO string
+      interaction: true,
+      ip: '192.168.1.100',
+      dataResidency: 'US',
+      str1: 'signup-btn',
+      str2: '/home',
+    });
+
+    console.log('✅ Event published to Kafka successfully');
+
+    // Publish Session (package handles date conversion automatically)
+    await kafkaAnalytics.publishSession({
+      sessionId: 'session_789',
+      tenantId: 'company-x',
+      sessionCreated: new Date(), // Can pass Date object - package converts to ISO string
+      environment: 'production',
+      dataResidency: 'US',
+      country: 'United States',
+      spaceId: 'space-123',
+      appId: 'web-app',
+      appVersion: '1.0.0',
+      installationVersion: '1.0.0',
+      installationId: 'install-456',
+      deviceId: 'device-789',
+      clientId: 'client-456',
+      ip: '192.168.1.100',
+      locationAccuracy: 10,
+      latitude: 40.7128,
+      longitude: -74.006,
+      captureId: 'capture-123',
+    });
+
+    console.log('✅ Session published to Kafka successfully');
+
+    // Publish Client (package handles date conversion automatically)
+    await kafkaAnalytics.publishClient({
+      clientId: 'client-kafka-123',
+      tenantId: 'company-x',
+      clientCreated: new Date(), // Can pass Date object - package converts to ISO string
+      clientUserAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+      clientScreenWidth: 1440,
+      clientScreenHeight: 900,
+      clientScreenColorDepth: 24,
+      clientScreenPixelDepth: 24,
+      clientIp: '192.168.1.150',
+      dataResidency: 'US',
+      country: 'United States',
+      latitude: 37.7749,
+      longitude: -122.4194,
+      locationAccuracy: 10,
+      captureId: 'capture-kafka-123',
+      clientDeviceVendor: 'Apple',
+      clientDeviceModel: 'MacBook Pro',
+      clientDeviceType: 'desktop',
+      clientOsName: 'macOS',
+      clientOsVersion: '14.0',
+      clientBrowserName: 'Safari',
+      clientBrowserVersion: '17.0',
+      clientBrowserMajor: '17',
+      clientBrowserEngine: 'WebKit',
+      clientBrowserEngineVersion: '605.1.15',
+      clientCpuArchitecture: 'arm64',
+    });
+
+    console.log('✅ Client published to Kafka successfully');
+
+    // Batch publishing example (package handles date conversion automatically)
+    const events = [
+      {
+        captureId: 'capture-123',
+        tenantId: 'company-x',
+        spaceId: 'space-123',
+        sessionId: 'session_789',
+        clientId: 'client-456',
+        eventType: 'page_view',
+        eventTime: new Date(), // Can pass Date object - package converts to ISO string
+        interaction: false,
+        ip: '192.168.1.100',
+        dataResidency: 'US',
+        str1: '/products',
+      },
+      {
+        captureId: 'capture-123',
+        tenantId: 'company-x',
+        spaceId: 'space-123',
+        sessionId: 'session_789',
+        clientId: 'client-456',
+        eventType: 'product_view',
+        eventTime: new Date(), // Can pass Date object - package converts to ISO string
+        interaction: true,
+        ip: '192.168.1.100',
+        dataResidency: 'US',
+        productId: 'product-123',
+        str1: 'electronics',
+      },
+      {
+        captureId: 'capture-123',
+        tenantId: 'company-x',
+        spaceId: 'space-123',
+        sessionId: 'session_789',
+        clientId: 'client-456',
+        eventType: 'add_to_cart',
+        eventTime: new Date(), // Can pass Date object - package converts to ISO string
+        interaction: true,
+        ip: '192.168.1.100',
+        dataResidency: 'US',
+        productId: 'product-123',
+        int1: 1,
+        str1: 'electronics',
+      },
+    ];
+
+    console.log('📦 Publishing batch events to Kafka...');
+    for (const event of events) {
+      await kafkaAnalytics.publishEvent(event);
+    }
+
+    console.log('✅ Multiple events published to Kafka (batched)');
+
+    console.log('⏳ Waiting for batch flush...');
+    await new Promise(resolve => setTimeout(resolve, 4000));
+
+    console.log('\n📝 Simplified Package Features:');
+    console.log('• Simple configuration: One Kafka client per region deployment');
+    console.log(
+      '• Automatic date conversion: Pass Date objects or strings - package handles ISO conversion'
+    );
+    console.log('• Loosely coupled: No complex multi-region logic in KafkaAdapter');
+    console.log('• Easy to maintain: Clean, simple codebase');
+    console.log('• Backward compatibility: Existing string dates continue to work');
+  } catch (error) {
+    console.error('❌ Error publishing analytics:', error);
+  } finally {
+    console.log('🔒 Closing Kafka analytics client...');
+    await kafkaAnalytics.close();
+    console.log('✅ Kafka analytics client closed');
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@phystack/analytics-publisher",
+  "version": "4.3.40-dev",
+  "description": "Internal Phygrid library for publishing and validating analytics events, with support for batching, retry strategies, and observability. Designed for reliable event delivery and easy integration across services.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "https://build.phygrid.com/",
+  "files": [
+    "dist/**/*",
+    "examples/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "build:watch": "tsc --watch",
+    "dev": "ts-node src/index.ts",
+    "example:kafka": "ts-node examples/kafka.ts",
+    "example:eventhub": "ts-node examples/eventhub.ts",
+    "stress-test": "ts-node examples/stress-test.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "format": "prettier --write \"src/**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json,md}\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "keywords": [
+    "phygrid",
+    "analytics",
+    "events",
+    "client",
+    "typescript",
+    "internal"
+  ],
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.0.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.9.0"
+  },
+  "dependencies": {
+    "@azure/event-hubs": "^6.0.0",
+    "kafkajs": "^2.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "53c505b3ecad47ebd4f38819c07b0ec1227214a6"
+}