npm package: @hangarx/node
Description: HangarX SDK for Node.js and backend applications - AI-powered Growth OS with analytics, SEO intelligence, and workflow automation
Author: HangarX Team
Latest version: 1.0.2

# @hangarx/node

<div align="center">

[![npm version](https://img.shields.io/npm/v/@hangarx/node.svg)](https://www.npmjs.com/package/@hangarx/node)
[![Bundle Size](https://img.shields.io/badge/size-12KB-brightgreen.svg)](https://bundlephobia.com/package/@hangarx/node)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

**Server-Side Mission Control for Your Growth Analytics** 🚀

Track server-side events, analyze backend flows, and optimize conversions with AI-powered insights.  
*Like having Jarvis in your backend—intelligent, reliable, and always on duty.*

[Quick Start](#-60-second-takeoff) • [API Reference](#-flight-controls-api) • [Examples](#-examples) • [Support](https://github.com/hangarx/hangarx-sdk/issues)

</div>

---

## ⚡ 60-Second Takeoff

**Install:**

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

**Track:**

```typescript
import { HangarX } from '@hangarx/node'

const hangarx = new HangarX({ apiKey: 'proj_YOUR_KEY' })

// Track events
await hangarx.track('user-123', 'purchase_completed', {
  amount: 99.99,
  product: 'Premium Plan'
})

// Identify users
await hangarx.identify('user-123', {
  email: 'pilot@example.com',
  plan: 'premium'
})
```

**That's it.** You're airborne. ✈️

---

## 🎯 Why HangarX Node?

| Feature | What You Get |
|---------|-------------|
| **12KB** | Lightweight. Won't bloat your backend. |
| **Auto-Batching** | Smart queueing. Efficient network usage. |
| **Retry Logic** | Exponential backoff. Never lose events. |
| **TypeScript** | Full type safety. Catch errors before runtime. |
| **Graceful Shutdown** | Flushes events on SIGTERM/SIGINT. No data loss. |
| **Environment Config** | Auto-loads from `HANGARX_API_KEY`. Zero config. |

---

## 📦 Installation

```bash
npm install @hangarx/node
# or
yarn add @hangarx/node
# or
pnpm add @hangarx/node
```

---

## 🚀 Flight Controls (API)

### Track Events

```typescript
await hangarx.track('user-123', 'event_name', {
  property: 'value'
})
```

**Common server-side events:**
- `user_signup` - New user registered
- `purchase_completed` - Purchase processed
- `subscription_created` - Subscription started
- `api_request` - API endpoint called
- `email_sent` - Email delivered

### Identify Users

```typescript
await hangarx.identify('user-123', {
  email: 'pilot@example.com',
  plan: 'premium',
  company: 'Acme Corp',
  created_at: new Date().toISOString()
})
```

### Track Pages (Server-Side Rendering)

```typescript
await hangarx.page('user-123', 'Home Page', {
  category: 'marketing',
  referrer: req.headers.referer
})
```

### Track Conversions

```typescript
await hangarx.conversion('user-123', 'purchase', 99.99, {
  product: 'Premium Plan',
  currency: 'USD',
  payment_method: 'stripe'
})
```

### Reset Session

```typescript
hangarx.reset()  // Clear session, start fresh
```

### Manual Flush

```typescript
await hangarx.flush()  // Send queued events immediately
```

### Graceful Shutdown

```typescript
await hangarx.shutdown()  // Flush and cleanup
```

---

## 🎨 Framework Integration

### Express.js

```typescript
import express from 'express'
import { HangarX } from '@hangarx/node'

const app = express()
const hangarx = new HangarX({ apiKey: process.env.HANGARX_API_KEY! })

// Track API requests
app.use((req, res, next) => {
  hangarx.track(req.user?.id || 'anonymous', 'api_request', {
    method: req.method,
    path: req.path,
    user_agent: req.headers['user-agent']
  })
  next()
})

// Track user signup
app.post('/api/signup', async (req, res) => {
  const user = await createUser(req.body)
  
  await hangarx.identify(user.id, {
    email: user.email,
    name: user.name
  })
  
  res.json({ success: true })
})

// Graceful shutdown
process.on('SIGTERM', async () => {
  await hangarx.shutdown()
  process.exit(0)
})
```

### Next.js API Routes

```typescript
// app/api/track/route.ts
import { HangarX } from '@hangarx/node'
import { NextRequest, NextResponse } from 'next/server'

const hangarx = new HangarX({ apiKey: process.env.HANGARX_API_KEY! })

export async function POST(request: NextRequest) {
  const { userId, event, properties } = await request.json()
  
  await hangarx.track(userId, event, properties)
  
  return NextResponse.json({ success: true })
}
```

### NestJS

```typescript
import { Injectable, OnModuleDestroy } from '@nestjs/common'
import { HangarX } from '@hangarx/node'

@Injectable()
export class AnalyticsService implements OnModuleDestroy {
  private hangarx: HangarX
  
  constructor() {
    this.hangarx = new HangarX({
      apiKey: process.env.HANGARX_API_KEY!
    })
  }
  
  async trackEvent(userId: string, event: string, properties?: any) {
    await this.hangarx.track(userId, event, properties)
  }
  
  async onModuleDestroy() {
    await this.hangarx.shutdown()
  }
}
```

### Fastify

```typescript
import Fastify from 'fastify'
import { HangarX } from '@hangarx/node'

const fastify = Fastify()
const hangarx = new HangarX({ apiKey: process.env.HANGARX_API_KEY! })

// Track requests
fastify.addHook('onRequest', async (request, reply) => {
  await hangarx.track(request.user?.id || 'anonymous', 'api_request', {
    method: request.method,
    url: request.url
  })
})

// Graceful shutdown
fastify.addHook('onClose', async () => {
  await hangarx.shutdown()
})
```

---

## ⚙️ Configuration

### Option 1: Constructor

```typescript
const hangarx = new HangarX({
  apiKey: 'proj_YOUR_KEY',
  endpoint: 'https://ingest.hangarx.ai',  // Default
  batchSize: 100,                          // Events per batch
  flushInterval: 10000,                    // Flush every 10s
  maxRetries: 3,                           // Retry failed requests
  timeout: 30000,                          // Request timeout (30s)
  debug: false                             // Enable debug logs
})
```

### Option 2: Environment Variables

```bash
# .env
HANGARX_API_KEY=proj_YOUR_KEY
HANGARX_ENDPOINT=https://ingest.hangarx.ai
HANGARX_BATCH_SIZE=100
HANGARX_FLUSH_INTERVAL=10000
HANGARX_DEBUG=true
```

```typescript
import { hangarx } from '@hangarx/node'

// Auto-configured from environment
await hangarx.track('user-123', 'event_name')
```

---

## 🔄 Batching & Performance

### Smart Batching

Events are automatically batched for efficiency:

```typescript
// These 3 events are batched into 1 request
await hangarx.track('user-1', 'event1')
await hangarx.track('user-2', 'event2')
await hangarx.track('user-3', 'event3')

// Batch sent when:
// 1. Queue reaches batchSize (default: 100)
// 2. flushInterval expires (default: 10s)
// 3. Manual flush() called
// 4. Process exits (graceful shutdown)
```

### Manual Flush

```typescript
// Queue events
await hangarx.track('user-1', 'event1')
await hangarx.track('user-2', 'event2')

// Send immediately
await hangarx.flush()
```

### Queue Size

```typescript
const queueSize = hangarx.getQueueSize()
console.log(`Events in queue: ${queueSize}`)
```

---

## 🛡️ Error Handling & Retries

### Automatic Retries

Failed requests are automatically retried with exponential backoff:

```typescript
const hangarx = new HangarX({
  apiKey: 'proj_YOUR_KEY',
  maxRetries: 3  // Retry up to 3 times
})

// Retry schedule:
// 1st retry: 1 second
// 2nd retry: 2 seconds
// 3rd retry: 4 seconds
```

### Error Handling

```typescript
try {
  await hangarx.track('user-123', 'event_name')
} catch (error) {
  console.error('Failed to track event:', error)
  // Event is re-queued automatically
}
```

### Graceful Degradation

```typescript
// Events are queued even if network is down
await hangarx.track('user-123', 'event1')  // Queued
await hangarx.track('user-123', 'event2')  // Queued

// Sent when network recovers
```

---

## 🚨 Graceful Shutdown

Always flush events before process exits:

```typescript
const hangarx = new HangarX({ apiKey: 'proj_YOUR_KEY' })

// Automatic shutdown on signals
process.on('SIGTERM', async () => {
  await hangarx.shutdown()
  process.exit(0)
})

process.on('SIGINT', async () => {
  await hangarx.shutdown()
  process.exit(0)
})

// Or use built-in handler (automatically registered)
// No need to add listeners manually
```

---

## 🧪 Testing

### Debug Mode

```typescript
const hangarx = new HangarX({
  apiKey: 'proj_YOUR_KEY',
  debug: true  // See all events in console
})

// Output:
// HangarX: Initialized { projectId: 'abc123', batchSize: 100 }
// HangarX: Enqueued event { type: 'purchase', userId: 'user-123' }
// HangarX: Successfully flushed 1 events
```

### Mock for Testing

```typescript
// test/analytics.test.ts
import { HangarX } from '@hangarx/node'

jest.mock('@hangarx/node')

describe('Analytics', () => {
  it('should track events', async () => {
    const hangarx = new HangarX({ apiKey: 'test-key' })
    
    await hangarx.track('user-123', 'test_event', { foo: 'bar' })
    
    expect(hangarx.track).toHaveBeenCalledWith(
      'user-123',
      'test_event',
      { foo: 'bar' }
    )
  })
})
```

---

## 📊 Performance Monitoring

### Queue Metrics

```typescript
const queueSize = hangarx.getQueueSize()
console.log(`Events in queue: ${queueSize}`)

// Monitor queue size
setInterval(() => {
  const size = hangarx.getQueueSize()
  if (size > 1000) {
    console.warn('Queue is getting large:', size)
  }
}, 60000)
```

---

## 🎓 Best Practices

### Event Naming

```typescript
// ✅ Good: snake_case, descriptive
await hangarx.track('user-123', 'purchase_completed')
await hangarx.track('user-123', 'subscription_created')

// ❌ Bad: unclear, inconsistent
await hangarx.track('user-123', 'event1')
await hangarx.track('user-123', 'PurchaseCompleted')
```

### Property Structure

```typescript
// ✅ Good: consistent, typed
await hangarx.track('user-123', 'purchase', {
  product_id: 'prod-456',
  revenue: 99.99,        // number
  currency: 'USD',       // string
  quantity: 1            // number
})

// ❌ Bad: inconsistent types
await hangarx.track('user-123', 'purchase', {
  prod: 'Premium',
  amount: '99.99',       // should be number
  type: 'sub'            // unclear
})
```

### Identify Early

```typescript
// ✅ Identify as soon as user is created
const user = await createUser(data)
await hangarx.identify(user.id, {
  email: user.email,
  created_at: new Date().toISOString()
})
```

### Always Shutdown

```typescript
// ✅ Always flush before exit
process.on('SIGTERM', async () => {
  await hangarx.shutdown()
  process.exit(0)
})
```

---

## 🔒 Privacy & Security

### API Key Security

```typescript
// ✅ Good: Use environment variables
const hangarx = new HangarX({
  apiKey: process.env.HANGARX_API_KEY!
})

// ❌ Bad: Hardcoded keys
const hangarx = new HangarX({
  apiKey: 'proj_abc123...'  // Don't commit this!
})
```

### PII Handling

```typescript
// Only track what you need
await hangarx.identify('user-123', {
  email: user.email,        // ✅ OK if consented
  // ssn: user.ssn,         // ❌ Never track sensitive data
  // credit_card: user.cc   // ❌ Never track payment data
})
```

---

## 🚨 Common Issues

### Events not showing up?

```typescript
// 1. Check your API key
console.log(hangarx.config.apiKey)  // Should start with 'proj_'

// 2. Enable debug mode
const hangarx = new HangarX({ 
  apiKey: 'proj_YOUR_KEY',
  debug: true 
})

// 3. Manually flush to see errors
try {
  await hangarx.flush()
} catch (error) {
  console.error('Flush failed:', error)
}

// 4. Check queue size
console.log('Queue size:', hangarx.getQueueSize())
```

### Network errors?

```typescript
// Increase timeout
const hangarx = new HangarX({
  apiKey: 'proj_YOUR_KEY',
  timeout: 60000,  // 60 seconds
  maxRetries: 5    // More retries
})
```

### Memory issues?

```typescript
// Reduce batch size and flush more frequently
const hangarx = new HangarX({
  apiKey: 'proj_YOUR_KEY',
  batchSize: 50,        // Smaller batches
  flushInterval: 5000   // Flush every 5s
})
```

---

## 📚 Examples

### Background Job

```typescript
import { HangarX } from '@hangarx/node'

const hangarx = new HangarX({ apiKey: process.env.HANGARX_API_KEY! })

async function processOrder(order) {
  // Process order
  await fulfillOrder(order)
  
  // Track completion
  await hangarx.track(order.userId, 'order_fulfilled', {
    order_id: order.id,
    amount: order.total,
    items: order.items.length
  })
}
```

### Webhook Handler

```typescript
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body
  
  if (event.type === 'payment_intent.succeeded') {
    await hangarx.track(event.data.object.customer, 'payment_succeeded', {
      amount: event.data.object.amount / 100,
      currency: event.data.object.currency
    })
  }
  
  res.json({ received: true })
})
```

### Scheduled Task

```typescript
import cron from 'node-cron'

// Track daily metrics
cron.schedule('0 0 * * *', async () => {
  const metrics = await getDailyMetrics()
  
  await hangarx.track('system', 'daily_metrics', {
    active_users: metrics.activeUsers,
    revenue: metrics.revenue,
    signups: metrics.signups
  })
})
```

---

## 📚 Resources

- **Documentation:** [docs.hangarx.ai](https://docs.hangarx.ai)
- **GitHub:** [github.com/hangarx/hangarx-sdk](https://github.com/hangarx/hangarx-sdk)
- **npm:** [npmjs.com/package/@hangarx/node](https://www.npmjs.com/package/@hangarx/node)
- **Support:** [support@hangarx.ai](mailto:support@hangarx.ai)

---

## 🤝 Support

Need help? We're here:

- 📧 **Email:** support@hangarx.ai
- 💬 **Discord:** [discord.gg/hangarx](https://discord.gg/hangarx)
- 🐛 **Issues:** [GitHub Issues](https://github.com/hangarx/hangarx-sdk/issues)
- 📖 **Docs:** [docs.hangarx.ai](https://docs.hangarx.ai)

---

## 📄 License

MIT License - see [LICENSE](../../LICENSE)

---

<div align="center">

**Ready for takeoff?** 🚀

Install HangarX and start tracking server-side events.

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

*Made with ❤️ by the HangarX crew*

[Website](https://hangarx.ai) • [Docs](https://docs.hangarx.ai) • [Blog](https://hangarx.ai/blog)

</div>