@elyochola/analytics-node

Node.js / Express SDK for Pulse analytics.

Installation

npm install @elyochola/analytics-node

Quick Start

import { createAnalytics } from '@elyochola/analytics-node';
import { createExpressMiddleware, wrapErrorHandler } from '@elyochola/analytics-node/express';

const analytics = createAnalytics({
  apiKey: process.env.PULSE_SECRET_KEY,   // sk_live_xxx
  endpoint: process.env.PULSE_ENDPOINT,    // https://ingest.example.com
});

// Track events
analytics.track('user_signup', { plan: 'pro' });
analytics.identify('user_123', { name: 'Ely' });

// Graceful shutdown
process.on('SIGTERM', () => analytics.shutdown());

Express Middleware

Automatically captures API request latency, route, method, status code, request ID, and tenant slug.

import { createExpressMiddleware, wrapErrorHandler } from '@elyochola/analytics-node/express';
import { errorHandler } from './middleware/errorHandler.js';

// Mount AFTER request ID middleware, body parsing, and gym-slug middleware
// Mount BEFORE route handlers
app.use(createExpressMiddleware(analytics, {
  ignoreRoutes: ['/api/health', '/api/test-logging', '/media'],
  tenantHeader: 'x-gym-slug',
  requestIdKey: 'id',              // req.id
  enrichContext: (req) => ({
    gymSlug: req.gymSlug,
    userId: req.user?.id,
  }),
}));

// Mount routes...
app.use('/api', routes);

// Wrap your existing error handler
app.use(wrapErrorHandler(analytics, errorHandler));

Middleware Options

| Option | Default | Description | |--------|---------|-------------| | ignoreRoutes | ['/health'] | Route prefixes to skip | | tenantHeader | 'x-gym-slug' | Header for tenant identification | | requestIdKey | 'id' | Property on req for request ID | | captureErrors | true | Auto-track 5xx responses as errors | | shouldCapture | () => true | Custom filter function | | enrichContext | () => ({}) | Add custom properties per request |

What's Captured Automatically

• duration_ms — high-resolution request timing
• route — Express route pattern (e.g., /api/member/:id)
• method — HTTP method
• status_code — response status code
• request_id — from req.id or x-request-id header
• tenant_id — from configured tenant header

API

createAnalytics(options)

| Option | Required | Default | Description | |--------|----------|---------|-------------| | apiKey | Yes | — | Secret API key (sk_live_xxx) | | endpoint | Yes | — | Ingestion API URL | | flushInterval | No | 5000 | Batch flush interval (ms) | | flushSize | No | 25 | Events per batch | | maxRetries | No | 3 | Retries per request | | onError | No | () => {} | Error callback |

Client Methods

| Method | Description | |--------|-------------| | track(eventName, properties?, context?) | Track a custom event | | identify(userId, traits?, context?) | Link user identity | | page(properties?, context?) | Track a page view | | error(err, context?) | Track an error/exception | | log(level, message, context?) | Forward a structured log | | performance(metricName, value, context?) | Track a performance metric | | flush() | Force flush queued events | | shutdown() | Flush and close (call on SIGTERM) |

Environment Variables

PULSE_SECRET_KEY=sk_live_xxxxxxxxxxxxx
PULSE_ENDPOINT=https://ingest.example.com