@virtu3d/event-manager 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Virtu3D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,624 @@
+# @fountaneengineering/event-manager
+
+[![Version](https://img.shields.io/badge/version-0.2.6-blue.svg)](https://gitlab.com/fountaneEngineering/consutling-projects/virtu/event-manager)
+[![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)](LICENSE)
+
+Lightweight event router for analytics and observability with browser support and distributed tracing.
+
+## Latest Release: v0.2.6
+
+### What's New
+- **Fixed**: Mixpanel/PostHog connectors now lazy-loaded - no Node.js dependencies bundled in browser builds
+- **Fixed**: Console.log statements removed from production trace interceptors
+- **Fixed**: Peer dependencies updated to require OTEL SDK v2.x (prevents silent span loss)
+- **Fixed**: Circular self-dependency removed from package.json
+- **Improved**: Resource fallback for older OTEL SDK versions
+
+## Installation
+
+### 1. Configure npm registry
+
+Create or update `.npmrc` in your project root:
+
+```
+@fountaneengineering:registry=https://gitlab.com/api/v4/projects/77867432/packages/npm/
+//gitlab.com/api/v4/projects/77867432/packages/npm/:_authToken=${GITLAB_TOKEN}
+```
+
+### 2. Install the package
+
+```bash
+npm install @fountaneengineering/event-manager
+```
+
+### 3. Install peer dependencies (as needed)
+
+**Browser environments:**
+```bash
+# For OpenTelemetry distributed tracing (browser)
+npm install @opentelemetry/api@^1.9.0 \
+  @opentelemetry/sdk-trace-web@^2.0.0 \
+  @opentelemetry/sdk-trace-base@^2.0.0 \
+  @opentelemetry/resources@^2.0.0 \
+  @opentelemetry/context-zone@^2.0.0 \
+  @opentelemetry/exporter-trace-otlp-http@^0.200.0 \
+  @opentelemetry/semantic-conventions@^1.0.0
+```
+
+**Node.js environments:**
+```bash
+# For OpenTelemetry distributed tracing (Node.js)
+npm install @opentelemetry/api@^1.9.0 \
+  @opentelemetry/sdk-node@^0.200.0
+
+# For Mixpanel analytics (Node.js only - lazy loaded)
+npm install mixpanel@^0.18.0
+
+# For PostHog analytics (Node.js only - lazy loaded)
+npm install posthog-node@^3.0.0
+```
+
+> **Note**: Mixpanel and PostHog connectors are **lazy-loaded** and only work in Node.js environments. They will not be bundled in browser builds.
+
+## Quick Start
+
+```typescript
+import { TelemetryRouter, installFetchInterceptor } from '@fountaneengineering/event-manager/browser';
+
+// Initialize telemetry
+const telemetry = new TelemetryRouter({
+  debug: true,
+  providers: [
+    {
+      name: 'console',
+      type: 'console',
+      config: { pretty: true },
+    },
+    {
+      name: 'otel',
+      type: 'otel-browser',
+      config: {
+        serviceName: 'my-app',
+        collectorUrl: 'http://localhost:4318/v1/traces',
+      },
+    },
+  ],
+});
+
+// Install fetch interceptor for automatic trace propagation
+installFetchInterceptor({
+  propagateToUrls: [/api\.example\.com/, /localhost:3000/],
+});
+
+// Track events
+telemetry.track('button_click', { button_id: 'login' });
+
+// Identify users
+telemetry.identify('user-123', { email: 'user@example.com', plan: 'pro' });
+
+// Track page views
+telemetry.page('Dashboard', { section: 'analytics' });
+```
+
+## Features
+
+- **Multi-provider routing** - Send events to multiple analytics/observability providers simultaneously
+- **Browser-optimized** - Lightweight bundle with tree-shaking support
+- **Distributed tracing** - W3C Trace Context propagation across services
+- **Fetch interceptor** - Automatic trace header injection for fetch/XHR/Axios
+- **Type-safe** - Full TypeScript support with comprehensive types
+- **Plugin system** - Extend functionality with custom plugins
+- **Zero required dependencies** - All providers are optional peer dependencies
+
+## Examples
+
+### Analytics Example
+
+Track user behavior and product analytics with Mixpanel or PostHog:
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager/browser';
+
+const analytics = new TelemetryRouter({
+  providers: [
+    {
+      name: 'mixpanel',
+      type: 'mixpanel',
+      config: { token: 'your-mixpanel-token' },
+    },
+    {
+      name: 'posthog',
+      type: 'posthog',
+      config: {
+        apiKey: 'your-posthog-key',
+        host: 'https://app.posthog.com',
+      },
+    },
+  ],
+});
+
+// Identify user on login
+analytics.identify('user-123', {
+  email: 'user@example.com',
+  plan: 'premium',
+  signupDate: '2024-01-15',
+});
+
+// Track feature usage
+analytics.track('feature_used', {
+  feature: 'export_report',
+  format: 'pdf',
+  itemCount: 50,
+});
+
+// Track conversions
+analytics.track('purchase_completed', {
+  orderId: 'ORD-456',
+  amount: 99.99,
+  currency: 'USD',
+  items: ['product-a', 'product-b'],
+});
+
+// Track page views
+analytics.page('Pricing', {
+  referrer: 'homepage',
+  variant: 'annual-discount',
+});
+```
+
+### Observability Example
+
+Distributed tracing with OpenTelemetry for debugging and performance monitoring:
+
+```typescript
+import {
+  TelemetryRouter,
+  installFetchInterceptor,
+  startSpan,
+  getTraceHeaders,
+} from '@fountaneengineering/event-manager/browser';
+
+// Initialize with OTEL collector
+const observability = new TelemetryRouter({
+  providers: [
+    {
+      name: 'otel',
+      type: 'otel-browser',
+      config: {
+        serviceName: 'frontend-app',
+        collectorUrl: 'https://otel-collector.example.com/v1/traces',
+        resourceAttributes: {
+          'deployment.environment': 'production',
+          'service.version': '1.2.3',
+        },
+      },
+    },
+  ],
+});
+
+// Auto-inject trace headers into API calls
+installFetchInterceptor({
+  propagateToUrls: [/api\.example\.com/, /backend\.example\.com/],
+});
+
+// Create custom spans for complex operations
+async function checkout(cartId: string) {
+  const span = await startSpan('checkout-flow', 'checkout-service');
+
+  try {
+    span.setAttribute('cart.id', cartId);
+
+    // Validate cart
+    const cart = await fetch(`/api/cart/${cartId}`);
+    span.addEvent('cart_validated');
+
+    // Process payment
+    const payment = await processPayment(cart);
+    span.setAttribute('payment.id', payment.id);
+    span.addEvent('payment_processed');
+
+    // Create order
+    const order = await createOrder(cart, payment);
+    span.setAttribute('order.id', order.id);
+
+    span.setStatus({ code: 1 }); // OK
+    return order;
+  } catch (error) {
+    span.setStatus({ code: 2, message: error.message }); // ERROR
+    span.recordException(error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+// Track errors with trace context
+window.onerror = (message, source, line, col, error) => {
+  observability.track('error_occurred', {
+    message,
+    source,
+    line,
+    column: col,
+    stack: error?.stack,
+  });
+};
+```
+
+### Metrics Example
+
+Track business and performance metrics:
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager/browser';
+
+const metrics = new TelemetryRouter({
+  providers: [
+    {
+      name: 'console',
+      type: 'console',
+      config: { pretty: true },
+    },
+    {
+      name: 'otel',
+      type: 'otel-browser',
+      config: {
+        serviceName: 'metrics-app',
+        collectorUrl: 'https://otel-collector.example.com/v1/traces',
+      },
+    },
+  ],
+});
+
+// Performance metrics
+metrics.track('page_load_time', {
+  metric: 'timing',
+  value: performance.timing.loadEventEnd - performance.timing.navigationStart,
+  unit: 'ms',
+  page: window.location.pathname,
+});
+
+// Core Web Vitals
+new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    metrics.track('web_vital', {
+      metric: entry.name,
+      value: entry.value,
+      rating: entry.rating,
+    });
+  }
+}).observe({ type: 'largest-contentful-paint', buffered: true });
+
+// Business metrics
+metrics.track('revenue', {
+  metric: 'counter',
+  value: 149.99,
+  currency: 'USD',
+  source: 'subscription',
+});
+
+metrics.track('active_users', {
+  metric: 'gauge',
+  value: 1,
+  segment: 'premium',
+});
+
+// API performance
+async function trackedFetch(url: string) {
+  const start = performance.now();
+  try {
+    const response = await fetch(url);
+    metrics.track('api_request', {
+      metric: 'histogram',
+      url,
+      duration: performance.now() - start,
+      status: response.status,
+      success: response.ok,
+    });
+    return response;
+  } catch (error) {
+    metrics.track('api_request', {
+      metric: 'histogram',
+      url,
+      duration: performance.now() - start,
+      success: false,
+      error: error.message,
+    });
+    throw error;
+  }
+}
+```
+
+## Entry Points
+
+The package provides three entry points:
+
+| Entry Point | Use Case |
+|-------------|----------|
+| `@fountaneengineering/event-manager` | Node.js / Server-side |
+| `@fountaneengineering/event-manager/browser` | Browser / Frontend apps |
+| `@fountaneengineering/event-manager/context` | Context utilities only |
+
+## Connectors
+
+### Console Connector
+
+Logs events to the console. Useful for development and debugging.
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager/browser';
+
+const telemetry = new TelemetryRouter({
+  providers: [
+    {
+      name: 'console',
+      type: 'console',
+      config: {
+        pretty: true,        // Pretty print JSON
+        logLevel: 'debug',   // 'debug' | 'info' | 'warn' | 'error'
+      },
+    },
+  ],
+});
+```
+
+### Browser OpenTelemetry Connector
+
+Sends traces to an OpenTelemetry collector.
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager/browser';
+
+const telemetry = new TelemetryRouter({
+  providers: [
+    {
+      name: 'otel',
+      type: 'otel-browser',
+      config: {
+        serviceName: 'my-frontend',
+        collectorUrl: 'https://otel-collector.example.com/v1/traces',
+        resourceAttributes: {
+          'deployment.environment': 'production',
+        },
+      },
+    },
+  ],
+});
+```
+
+### Mixpanel Connector
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager';
+
+const telemetry = new TelemetryRouter({
+  providers: [
+    {
+      name: 'mixpanel',
+      type: 'mixpanel',
+      config: {
+        token: 'your-mixpanel-token',
+      },
+    },
+  ],
+});
+```
+
+### PostHog Connector
+
+```typescript
+import { TelemetryRouter } from '@fountaneengineering/event-manager';
+
+const telemetry = new TelemetryRouter({
+  providers: [
+    {
+      name: 'posthog',
+      type: 'posthog',
+      config: {
+        apiKey: 'your-posthog-key',
+        host: 'https://app.posthog.com', // or your self-hosted instance
+      },
+    },
+  ],
+});
+```
+
+## Fetch Interceptor
+
+Automatically inject trace headers into outgoing HTTP requests.
+
+```typescript
+import { installFetchInterceptor, uninstallFetchInterceptor } from '@fountaneengineering/event-manager/browser';
+
+// Install interceptor
+installFetchInterceptor({
+  propagateToUrls: [
+    /api\.example\.com/,
+    /localhost:3000/,
+    'https://specific-url.com/api',
+  ],
+  excludeUrls: [/analytics\.google\.com/],
+});
+
+// All fetch calls to matching URLs now include trace headers
+fetch('https://api.example.com/users'); // traceparent header automatically added
+
+// Uninstall when done
+uninstallFetchInterceptor();
+```
+
+### XHR Interceptor
+
+```typescript
+import { installXHRInterceptor } from '@fountaneengineering/event-manager/browser';
+
+installXHRInterceptor({
+  propagateToUrls: [/api\.example\.com/],
+});
+```
+
+## React Integration
+
+Create a custom hook:
+
+```typescript
+// useTelemetry.ts
+import { useEffect, useRef } from 'react';
+import { TelemetryRouter, installFetchInterceptor } from '@fountaneengineering/event-manager/browser';
+
+let telemetryInstance: TelemetryRouter | null = null;
+
+function getTelemetry(): TelemetryRouter {
+  if (!telemetryInstance) {
+    telemetryInstance = new TelemetryRouter({
+      debug: process.env.NODE_ENV === 'development',
+      providers: [
+        {
+          name: 'otel',
+          type: 'otel-browser',
+          config: {
+            serviceName: 'react-app',
+            collectorUrl: process.env.REACT_APP_OTEL_URL,
+          },
+        },
+      ],
+    });
+
+    installFetchInterceptor({
+      propagateToUrls: [process.env.REACT_APP_API_URL!],
+    });
+  }
+  return telemetryInstance;
+}
+
+export function useTelemetry() {
+  const telemetry = getTelemetry();
+
+  return {
+    track: (event: string, properties?: Record<string, unknown>) =>
+      telemetry.track(event, properties),
+    identify: (userId: string, traits?: Record<string, unknown>) =>
+      telemetry.identify(userId, traits),
+    page: (name: string, properties?: Record<string, unknown>) =>
+      telemetry.page(name, properties),
+  };
+}
+```
+
+Usage:
+
+```tsx
+function LoginButton() {
+  const { track, identify } = useTelemetry();
+
+  const handleLogin = async () => {
+    const user = await login();
+    identify(user.id, { email: user.email });
+    track('user_login', { method: 'oauth' });
+  };
+
+  return <button onClick={handleLogin}>Login</button>;
+}
+```
+
+## Axios Integration
+
+For Axios, use the trace interceptor:
+
+```typescript
+import axios from 'axios';
+import { createAxiosTraceInterceptor } from '@fountaneengineering/event-manager/browser';
+
+const api = axios.create({
+  baseURL: 'https://api.example.com',
+});
+
+// Add trace interceptor
+api.interceptors.request.use(
+  createAxiosTraceInterceptor({
+    propagateToUrls: [/api\.example\.com/],
+  })
+);
+```
+
+### Manual Header Injection
+
+If you need manual control:
+
+```typescript
+import { getTraceHeaders } from '@fountaneengineering/event-manager/browser';
+
+async function fetchData() {
+  const headers = await getTraceHeaders();
+
+  const response = await fetch('/api/data', {
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers, // { traceparent: '00-...', tracestate: '...' }
+    },
+  });
+
+  return response.json();
+}
+```
+
+## Custom Spans
+
+Create custom spans for detailed tracing:
+
+```typescript
+import { startSpan } from '@fountaneengineering/event-manager/browser';
+
+async function processOrder(orderId: string) {
+  const span = await startSpan('process-order', 'order-service');
+
+  try {
+    span.setAttribute('order.id', orderId);
+
+    const result = await submitOrder(orderId);
+
+    span.setStatus({ code: 1 }); // SpanStatusCode.OK
+    return result;
+  } catch (error) {
+    span.setStatus({ code: 2, message: error.message }); // SpanStatusCode.ERROR
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+```
+
+## API Reference
+
+### TelemetryRouter
+
+| Method | Description |
+|--------|-------------|
+| `track(event, payload?)` | Track a custom event |
+| `identify(userId, traits?)` | Identify a user with optional traits |
+| `page(name?, properties?)` | Track a page view |
+| `registerConnector(connector)` | Register a connector instance |
+| `unregisterConnector(name)` | Remove a connector |
+| `addPlugin(plugin)` | Add a router plugin |
+| `getConnectors()` | Get registered connector names |
+| `shutdown()` | Gracefully shutdown all connectors |
+
+### Context Utilities
+
+| Function | Description |
+|----------|-------------|
+| `getTraceHeaders()` | Get current trace headers (async) |
+| `getTraceHeadersSync()` | Get trace headers synchronously |
+| `extractTraceContext(headers)` | Extract trace context from headers |
+| `withTraceContext(headers, fn)` | Run function within trace context |
+| `startSpan(name, serviceName?)` | Create a new span |
+| `generateTraceId()` | Generate a random trace ID |
+| `generateSpanId()` | Generate a random span ID |
+
+### Interceptors
+
+| Function | Description |
+|----------|-------------|
+| `installFetchInterceptor(config)` | Install global fetch interceptor |
+| `uninstallFetchInterceptor()` | Remove fetch interceptor |
+| `installXHRInterceptor(config)` | Install XHR interceptor |
+| `createAxiosTraceInterceptor(config)` | Create Axios request interceptor |