Node.js SDK

The @entro314labs/node package provides server-side analytics tracking for Node.js applications.

Installation

pnpm add @entro314labs/node

npm install @entro314labs/node

yarn add @entro314labs/node

bun add @entro314labs/node

Quick Start

Install Package

pnpm add @entro314labs/node

Create Client

import { Entrolytics } from '@entro314labs/node'

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

Track Events

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

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

// Identify user/session
await client.identify({
  sessionId: 'session_abc123',
  userId: 'user_456',
  plan: 'premium',
})

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: `'standard'`, `'edge'`, or `'native'`

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,
    enabled: true,
  },
  title: 'Page Title',
  referrer: 'https://...',
})

`track(event, eventData?)`

Flexible tracking method for backwards compatibility.

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

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

// Track with full options object
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',
  company: 'Acme Inc',
})

Property Management

// Set a single property
client.setProperty('userId', 'user_123')

// Set multiple properties
client.setProperties({
  plan: 'enterprise',
  region: 'us-west',
})

// Get current properties
const props = client.getProperties()

// Clear a specific property
client.clearProperty('region')

// Reset all properties
client.reset()

`send(payload, type?)`

Low-level method to send raw payloads directly.

await client.send({
  website: 'website-id',
  url: '/custom',
  name: 'custom_event',
  data: { custom: 'data' },
}, 'event')

Advanced Usage

TypeScript Support

Full TypeScript support with exported types:

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

Type Definitions

interface EntrolyticsOptions {
  hostUrl?: string
  websiteId?: string
  sessionId?: string
  userAgent?: string
  timeout?: number
  endpoint?: 'standard' | 'edge' | 'native'
}

interface EventData {
  [key: string]: string | number | boolean | Date | null
}

interface TrackPageOptions {
  url: string
  title?: string
  referrer?: string
  hostname?: string
  language?: string
  screen?: string
}

interface TrackEventOptions extends TrackPageOptions {
  name: string
  data?: EventData
}

interface IdentifyOptions {
  sessionId?: string
  [key: string]: string | number | boolean | Date | null | undefined
}

Requirements

Node.js >= 22.x
Native fetch support (built into Node.js 18+)

Features

✅ CommonJS and ESM support
✅ Edge runtime compatible
✅ TypeScript-first
✅ Zero dependencies (uses native fetch)
✅ Property storage for session data
✅ Multiple endpoint support (standard/edge/native)

Node.js SDK

Error Handling

Edge Endpoint

Self-Hosted Instance

Batch Tracking

Table of Contents