@entro314labs/node

Server-side analytics tracking SDK for Node.js applications.

Installation

# pnpm (recommended)
pnpm add @entro314labs/node

# npm
npm install @entro314labs/node

# yarn
yarn add @entro314labs/node

# bun
bun add @entro314labs/node

Quick Start

import { Entrolytics } from '@entro314labs/node';

// Create client instance
const client = new Entrolytics({
  websiteId: 'your-website-id',
  hostUrl: 'https://cloud.entrolytics.click', // or your self-hosted URL
});

// Track a page view
await client.trackPageView({
  url: '/dashboard',
  title: 'Dashboard',
  referrer: 'https://google.com',
});

// Track a custom event
await client.trackEvent({
  url: '/products',
  name: 'add_to_cart',
  data: {
    productId: 'prod_123',
    price: 29.99,
    currency: 'USD',
  },
});

Configuration

const client = new Entrolytics({
  // Required
  websiteId: 'your-website-id',
  hostUrl: 'https://cloud.entrolytics.click',

  // Optional
  sessionId: 'custom-session-id',
  userAgent: 'MyApp/1.0',
  timeout: 10000,
  endpoint: 'standard', // 'standard' | 'edge' | 'native'
});

Configuration Options

Option	Type	Default	Description
websiteId	string	-	Your Entrolytics website ID (required)
hostUrl	string	-	Entrolytics host URL (required)
sessionId	string	-	Custom session identifier
userAgent	string	Auto-generated	Custom user agent for requests
timeout	number	10000	Request timeout in milliseconds
endpoint	string	'standard'	API endpoint variant

API Reference

trackPageView(options)

Track a page view event.

await client.trackPageView({
  url: '/page-path',
  title: 'Page Title',
  referrer: 'https://...',
  hostname: 'example.com',
  language: 'en-US',
  screen: '1920x1080',
});

trackEvent(options)

Track a custom event with optional data.

await client.trackEvent({
  url: '/page-path',
  name: 'event_name',
  data: {
    key: 'value',
    count: 42,
  },
});

track(event, eventData?)

Flexible tracking method.

// Track with event name
await client.track('button_click');

// Track with event name and data
await client.track('purchase', { amount: 99.99 });

// Track with full options
await client.track({
  url: '/checkout',
  name: 'purchase_complete',
  data: { orderId: 'order_123' },
});

identify(properties)

Identify a user/session with custom properties.

await client.identify({
  sessionId: 'session_abc123',
  userId: 'user_456',
  plan: 'premium',
});

Property Management

client.setProperty('userId', 'user_123');
client.setProperties({ plan: 'enterprise', region: 'us-west' });
const props = client.getProperties();
client.clearProperty('region');
client.reset();

TypeScript Types

import {
  Entrolytics,
  EntrolyticsOptions,
  EntrolyticsPayload,
  EventData,
  TrackPageOptions,
  TrackEventOptions,
  IdentifyOptions,
  SendType,
} from '@entro314labs/node';

Self-Hosted Usage

const client = new Entrolytics({
  websiteId: 'your-website-id',
  hostUrl: 'https://analytics.yourdomain.com',
});

Edge Runtime

const client = new Entrolytics({
  websiteId: 'your-website-id',
  hostUrl: 'https://cloud.entrolytics.click',
  endpoint: 'edge',
});

Requirements

• Node.js >= 22.x

License

MIT