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

npm install @hangarx/helix-node

Quick Start

1. Initialize the Client

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

// 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: '[email protected]',
    plan: 'premium'
  }
});

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

3. Batch Events

// 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

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

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

Identify Users

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

Page Views

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

Screen Views

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

Event Context

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

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

Batch Processing

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

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

// 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: