@zetalyx/node

Node.js SDK for Zetalyx — tracks events, errors, and behaviors from server-side applications.

Installation

npm install @zetalyx/node

Requires Node.js 18+ (uses native fetch).

Quick Start

import { NodeClient } from '@zetalyx/node';

const zetalyx = new NodeClient({
  apiKey: 'sk_live_your_api_key',
});

// Track an event
zetalyx.track('user_signup', { plan: 'pro' });

// Track an error
zetalyx.trackError(new Error('Database connection failed'));

// Track a behavior
zetalyx.trackBehavior('api_call', { endpoint: '/users', method: 'POST' });

Features

• Batched transport — events are queued and sent in batches with exponential backoff retry
• Process lifecycle hooks — auto-flushes on beforeExit, SIGTERM, and SIGINT
• Exception capture — opt-in auto-capture of uncaughtException and unhandledRejection
• Server metadata — automatically includes Node version, platform, and PID

Configuration

const zetalyx = new NodeClient({
  apiKey: 'sk_live_...',       // Required
  endpoint: 'https://...',     // Default: 'https://api.zetalyx.com'
  batchSize: 10,               // Flush after N events
  flushInterval: 5000,         // Flush every N ms
  maxRetries: 3,               // Retry on 5xx/network error
  debug: false,                // Console debug logging
  enabled: true,               // Master kill switch

  // Node-specific
  captureExceptions: false,    // Auto-capture uncaught exceptions (default: false)
});

API

zetalyx.track(eventType, metadata?)

zetalyx.track('order_completed', {
  order_id: 'ord_456',
  total: 99.99,
});

zetalyx.trackError(error, metadata?)

try {
  await db.query('...');
} catch (err) {
  zetalyx.trackError(err, { query: 'users', operation: 'select' });
}

zetalyx.trackBehavior(action, data?)

zetalyx.trackBehavior('cron_job', {
  job_name: 'cleanup_sessions',
  duration_ms: 342,
});

zetalyx.flush()

Manually flush all queued events.

await zetalyx.flush();

zetalyx.shutdown()

Flush remaining events and stop the client.

await zetalyx.shutdown();

Usage with Express

import express from 'express';
import { NodeClient } from '@zetalyx/node';

const app = express();
const zetalyx = new NodeClient({ apiKey: 'sk_live_...' });

app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    zetalyx.trackBehavior('http_request', {
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration_ms: Date.now() - start,
    });
    if (res.statusCode >= 500) {
      zetalyx.trackError(`HTTP ${res.statusCode}`, {
        method: req.method,
        path: req.path,
      });
    }
  });
  next();
});

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

License

MIT