@hangarx/helix-node/README.md

Helix Analytics Node.js SDK for server-side event tracking with enhanced business intelligence capabilities

# Helix Analytics Node.js SDK

A powerful Node.js SDK for server-side event tracking with enhanced business intelligence capabilities.

## Features

- **Server-Side Tracking** - Secure event tracking from Node.js applications
- **TypeScript Support** - Full TypeScript definitions included
- **Real-Time Analytics** - Direct integration with Helix Analytics API
- **Batch Processing** - Efficient bulk event handling
- **Error Handling** - Comprehensive error handling and retry logic
- **Business Intelligence** - Enhanced analytics and insights

## Installation

```bash
npm install @hangarx/helix-node
```

## Quick Start

### 1. Initialize the Client

```typescript
import { HelixAnalytics } from '@hangarx/helix-node';

const helix = new HelixAnalytics({
  apiKey: 'your-api-key',
  apiUrl: 'https://helix-sdk-ha4shte2cq-uc.a.run.app',
  companyId: 'your-company-id'
});
```

### 2. Track Events

```typescript
// Track a user action
await helix.track({
  userId: 'user-123',
  event: 'button_clicked',
  properties: {
    button_name: 'signup',
    page: 'landing'
  }
});

// Identify a user
await helix.identify({
  userId: 'user-123',
  traits: {
    email: 'user@example.com',
    plan: 'premium'
  }
});

// Track page views
await helix.page({
  userId: 'user-123',
  name: 'Landing Page',
  properties: {
    url: 'https://example.com',
    title: 'Welcome'
  }
});
```

### 3. Batch Events

```typescript
// Send multiple events efficiently
await helix.batch([
  {
    type: 'track',
    userId: 'user-123',
    event: 'signup',
    properties: { plan: 'free' }
  },
  {
    type: 'track',
    userId: 'user-123',
    event: 'first_login',
    properties: { timestamp: new Date() }
  }
]);
```

## API Reference

### Constructor Options

```typescript
interface HelixConfig {
  apiKey: string;           // Your Helix API key
  apiUrl?: string;          // API endpoint (optional)
  companyId?: string;       // Company ID (optional)
  timeout?: number;         // Request timeout in ms (default: 10000)
  retries?: number;         // Number of retries (default: 3)
  batchSize?: number;       // Batch size for bulk operations (default: 100)
}
```

### Event Types

#### Track Events
```typescript
helix.track({
  userId: string;
  event: string;
  properties?: Record<string, any>;
  context?: EventContext;
  timestamp?: Date;
});
```

#### Identify Users
```typescript
helix.identify({
  userId: string;
  traits?: Record<string, any>;
  context?: EventContext;
  timestamp?: Date;
});
```

#### Page Views
```typescript
helix.page({
  userId: string;
  name?: string;
  category?: string;
  properties?: Record<string, any>;
  context?: EventContext;
  timestamp?: Date;
});
```

#### Screen Views
```typescript
helix.screen({
  userId: string;
  name?: string;
  category?: string;
  properties?: Record<string, any>;
  context?: EventContext;
  timestamp?: Date;
});
```

### Event Context

```typescript
interface EventContext {
  app?: {
    name?: string;
    version?: string;
  };
  device?: {
    id?: string;
    manufacturer?: string;
    model?: string;
    type?: string;
  };
  library?: {
    name?: string;
    version?: string;
  };
  location?: {
    city?: string;
    country?: string;
    latitude?: number;
    longitude?: number;
  };
  network?: {
    bluetooth?: boolean;
    carrier?: string;
    cellular?: boolean;
    wifi?: boolean;
  };
  os?: {
    name?: string;
    version?: string;
  };
  page?: {
    path?: string;
    referrer?: string;
    search?: string;
    title?: string;
    url?: string;
  };
  screen?: {
    density?: number;
    height?: number;
    width?: number;
  };
  userAgent?: string;
  ip?: string;
  timezone?: string;
}
```

## Advanced Usage

### Error Handling

```typescript
try {
  await helix.track({
    userId: 'user-123',
    event: 'purchase',
    properties: { amount: 99.99 }
  });
} catch (error) {
  console.error('Failed to track event:', error);
}
```

### Batch Processing

```typescript
const events = [
  { type: 'track', userId: 'user-1', event: 'signup' },
  { type: 'track', userId: 'user-2', event: 'login' },
  { type: 'track', userId: 'user-3', event: 'purchase' }
];

await helix.batch(events);
```

### Custom Configuration

```typescript
const helix = new HelixAnalytics({
  apiKey: 'your-api-key',
  apiUrl: 'https://your-custom-endpoint.com',
  timeout: 15000,
  retries: 5,
  batchSize: 50
});
```

## Business Intelligence Integration

### Enhanced Analytics

The Node.js SDK integrates seamlessly with Helix's enhanced analytics capabilities:

- **User Engagement Tracking** - DAU/WAU/MAU metrics
- **Conversion Funnel Analysis** - Multi-step conversion tracking
- **Revenue Attribution** - Marketing channel performance
- **Behavioral Segmentation** - User categorization and insights
- **Real-time Dashboards** - Live metrics and monitoring
- **Anomaly Detection** - Automated pattern recognition

### Event Best Practices

```typescript
// E-commerce tracking
await helix.track({
  userId: 'user-123',
  event: 'purchase',
  properties: {
    product_id: 'prod-456',
    product_name: 'Premium Plan',
    revenue: 99.99,
    currency: 'USD',
    category: 'subscription'
  }
});

// User onboarding
await helix.track({
  userId: 'user-123',
  event: 'onboarding_step_completed',
  properties: {
    step: