@phystack/analytics-publisher 4.3.40-dev

package/README.md

@@ -0,0 +1,436 @@
+# @phystack/analytics-publisher
+
+Internal Phygrid client library for publishing and validating analytics events, sessions, and client data with support for batching, retry strategies, and observability. Designed for reliable event delivery and easy integration across services.
+
+## Features
+
+- **Multi-transport support**: Kafka and Azure Event Hub adapters
+- **Simplified architecture**: One Kafka client per region deployment
+- **Multi-data-type support**: Events, Sessions, and Client data publishing
+- **Automatic date conversion**: Handles Date objects and strings seamlessly
+- **Batching**: Automatic message batching with configurable buffer sizes
+- **Retry logic**: Configurable retry strategies with exponential backoff
+- **Type safety**: Full TypeScript support with strict typing
+- **Observability**: Built-in metrics and monitoring capabilities
+- **Validation**: Automatic message validation before publishing
+- **Backpressure handling**: Automatic throttling when buffer usage is high
+- **Graceful shutdown**: Ensures all buffered messages are sent before closing
+
+## Installation
+
+```bash
+npm install @phystack/analytics-publisher
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { AnalyticsClient } from '@phystack/analytics-publisher';
+
+// Initialize with simplified Kafka configuration
+const analytics = new AnalyticsClient({
+  adapter: 'kafka',
+  adapterConfig: {
+    brokers: ['localhost:9092'], // Your Kafka broker
+    clientId: 'analytics-client',
+    connectionTimeout: 30000,
+    requestTimeout: 30000,
+    ssl: {
+      rejectUnauthorized: false,
+    },
+    sasl: {
+      mechanism: 'scram-sha-512',
+      username: 'kafka-user',
+      password: 'kafka-password',
+    },
+  },
+  bufferSize: 1000,
+  flushIntervalMs: 2000,
+  maxRetries: 3,
+  enableBackpressure: true,
+  backpressureThreshold: 0.8,
+  enableMetricsLogging: true,
+});
+
+await analytics.init();
+
+// Define sample data payloads (package handles date conversion automatically)
+const eventData = {
+  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', // This is just metadata for analytics tracking
+  str1: 'signup-btn',
+  str2: '/home',
+};
+
+const sessionData = {
+  sessionId: 'session_789',
+  tenantId: 'company-x',
+  sessionCreated: new Date().toISOString(),
+  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',
+};
+
+const clientData = {
+  clientId: 'client-456',
+  tenantId: 'company-x',
+  clientCreated: new Date().toISOString(),
+  clientUserAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+  clientScreenWidth: 1920,
+  clientScreenHeight: 1080,
+  clientScreenColorDepth: 24,
+  clientScreenPixelDepth: 24,
+  clientIp: '192.168.1.100',
+  dataResidency: 'US',
+  country: 'United States',
+  latitude: 40.7128,
+  longitude: -74.006,
+  locationAccuracy: 10,
+  captureId: 'capture-123',
+  clientDeviceVendor: 'Microsoft',
+  clientDeviceModel: 'Surface Pro',
+  clientDeviceType: 'desktop',
+  clientOsName: 'Windows',
+  clientOsVersion: '10.0',
+  clientBrowserName: 'Chrome',
+  clientBrowserVersion: '120.0.0.0',
+  clientBrowserMajor: '120',
+  clientBrowserEngine: 'Blink',
+  clientBrowserEngineVersion: '120.0.0.0',
+  clientCpuArchitecture: 'x64',
+};
+
+// Publish events
+await analytics.publishEvent(eventData);
+
+// Publish sessions
+await analytics.publishSession(sessionData);
+
+// Publish client data
+await analytics.publishClient(clientData);
+
+await analytics.close();
+```
+
+### Azure Event Hub
+
+```typescript
+import { AnalyticsClient } from '@phystack/analytics-publisher';
+
+// Initialize with Event Hub
+const analytics = new AnalyticsClient({
+  adapter: 'eventHub',
+  adapterConfig: {
+    retryOptions: {
+      maxRetries: 4,
+      retryDelayInMs: 1000,
+    },
+    dataResidency: {
+      US: {
+        events: 'Endpoint=sb://us-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://us-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://us-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      EU: {
+        events: 'Endpoint=sb://eu-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://eu-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://eu-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+    },
+  },
+  bufferSize: 1000,
+  flushIntervalMs: 2000,
+  maxRetries: 3,
+  enableBackpressure: true,
+  backpressureThreshold: 0.8,
+  enableMetricsLogging: true,
+});
+
+await analytics.init();
+
+// Publish events, sessions, and clients using the same methods as Kafka
+await analytics.publishEvent(eventData);
+await analytics.publishSession(sessionData);
+await analytics.publishClient(clientData);
+
+await analytics.close();
+```
+
+## Configuration
+
+### AnalyticsClient Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adapter` | `'kafka' \| 'eventHub'` | Required | Transport adapter type |
+| `adapterConfig` | `object` | `{}` | Adapter-specific configuration |
+| `bufferSize` | `number` | `1000` | Maximum messages to buffer before flushing |
+| `flushIntervalMs` | `number` | `2000` | Automatic flush interval in milliseconds |
+| `maxRetries` | `number` | `3` | Maximum retry attempts for failed messages |
+| `enableBackpressure` | `boolean` | `true` | Enable backpressure handling |
+| `backpressureThreshold` | `number` | `0.8` | Buffer usage threshold for backpressure (0-1) |
+| `backpressureDelayMs` | `number` | `50` | Initial delay for backpressure in milliseconds |
+| `maxBatchSize` | `number` | `100` | Maximum messages per batch |
+| `parallelBatchLimit` | `number` | `5` | Maximum concurrent batches |
+| `commandTimeoutMs` | `number` | `10000` | Timeout for individual commands |
+| `enableMetricsLogging` | `boolean` | `true` | Enable metrics collection and logging |
+| `metricsLogIntervalMs` | `number` | `10000` | Interval for metrics logging |
+| `onPublishError` | `function` | `console.error` | Error handler for failed publishes |
+
+### Kafka Configuration
+
+```typescript
+{
+  adapter: 'kafka',
+  adapterConfig: {
+    dataResidency: {
+      US: {
+        brokers: ['kafka-us.example.com:9092'],
+        ssl: {
+          rejectUnauthorized: false,
+        },
+        sasl: {
+          mechanism: 'scram-sha-512',
+          username: 'kafka-user',
+          password: 'kafka-password',
+        },
+        connectionTimeout: 30000,
+        requestTimeout: 30000,
+      },
+      EU: {
+        brokers: ['kafka-eu.example.com:9092'],
+        ssl: {
+          rejectUnauthorized: false,
+        },
+        sasl: {
+          mechanism: 'scram-sha-512',
+          username: 'kafka-user',
+          password: 'kafka-password',
+        },
+      },
+    },
+  }
+}
+```
+
+### Event Hub Configuration
+
+```typescript
+{
+  adapter: 'eventHub',
+  adapterConfig: {
+    retryOptions: {
+      maxRetries: 4,
+      retryDelayInMs: 1000,
+    },
+    dataResidency: {
+      US: {
+        events: 'Endpoint=sb://us-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://us-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://us-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      EU: {
+        events: 'Endpoint=sb://eu-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://eu-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://eu-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      UAE: {
+        events: 'Endpoint=sb://uae-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://uae-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://uae-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      AU: {
+        events: 'Endpoint=sb://au-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://au-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://au-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      IN: {
+        events: 'Endpoint=sb://in-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://in-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://in-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      DEV: {
+        events: 'Endpoint=sb://dev-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://dev-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://dev-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+      QA: {
+        events: 'Endpoint=sb://qa-events.servicebus.windows.net/;SharedAccessKeyName=events;SharedAccessKey=key;EntityPath=events',
+        sessions: 'Endpoint=sb://qa-sessions.servicebus.windows.net/;SharedAccessKeyName=sessions;SharedAccessKey=key;EntityPath=sessions',
+        clients: 'Endpoint=sb://qa-clients.servicebus.windows.net/;SharedAccessKeyName=clients;SharedAccessKey=key;EntityPath=clients',
+      },
+    },
+  }
+}
+```
+
+## Data Types
+
+### Event Interface
+
+```typescript
+interface Event {
+  captureId: string;
+  tenantId: string;
+  spaceId: string;
+  sessionId: string;
+  clientId: string;
+  eventType: string;
+  eventTime: string;
+  interaction: boolean;
+  ip: string;
+  dataResidency: string;
+  productId?: string;
+  categoryId?: string;
+  int1?: number;
+  int2?: number;
+  int3?: number;
+  int4?: number;
+  int5?: number;
+  str1?: string;
+  str2?: string;
+  str3?: string;
+  str4?: string;
+  str5?: string;
+}
+
+```
+
+### Session Interface
+
+```typescript
+interface Session {
+  tenantId: string;
+  sessionId: string;
+  sessionCreated: string;
+  environment: string;
+  dataResidency: string;
+  country: string;
+  spaceId: string;
+  appId: string;
+  appVersion?: string;
+  installationVersion?: string;
+  installationId: string;
+  deviceId?: string;
+  clientId: string;
+  ip: string;
+  locationAccuracy: number;
+  latitude: number;
+  longitude: number;
+  captureId: string;
+}
+```
+
+### Client Interface
+
+```typescript
+interface Client {
+  captureId: string;
+  tenantId: string;
+  clientId: string;
+  clientCreated: string;
+  clientIp: string;
+  clientUserAgent: string;
+  dataResidency: string;
+  country: string;
+  locationAccuracy: number;
+  latitude: number;
+  longitude: number;
+  clientScreenWidth: number;
+  clientScreenHeight: number;
+  clientScreenColorDepth: number;
+  clientScreenPixelDepth: number;
+  clientDeviceVendor: string;
+  clientDeviceModel: string;
+  clientDeviceType: string;
+  clientOsName: string;
+  clientOsVersion: string;
+  clientBrowserName: string;
+  clientBrowserVersion: string;
+  clientBrowserMajor: string;
+  clientBrowserEngine: string;
+  clientBrowserEngineVersion: string;
+  clientCpuArchitecture: string;
+}
+```
+
+
+### Metrics and Observability
+
+```typescript
+import { MetricsObserver } from '@phystack/analytics-publisher';
+
+const observer = new MetricsObserver();
+publisher.addObserver(observer);
+
+// Observer will track:
+// - Successful publishes
+// - Failed publishes
+// - Batch full events
+```
+
+### Error Handling
+
+```typescript
+try {
+  await analytics.publishEvent(eventData);
+} catch (error) {
+  console.error('Failed to publish event:', error);
+  // Handle error appropriately
+}
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:coverage
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+- `kafka.ts` - Kafka adapter usage with multiple data residencies
+- `eventhub.ts` - Azure Event Hub adapter usage
+
+## License
+
+MIT