@truxl/node-sdk

Server-side Node.js SDK for Truxl analytics. Zero runtime dependencies, lightweight, and designed for backend services.

Installation

npm install @truxl/node-sdk

Quick Start

import { Truxl } from '@truxl/node-sdk';

const truxl = new Truxl({
  projectToken: 'trxl_proj_demo_123',
  clientSecret: 'demo-secret-key-256bit-0123456789abcdef',
  apiEndpoint: 'https://ingest.truxl.com',
});

// Track an event
truxl.track({
  distinctId: 'user-123',
  eventName: 'purchase',
  properties: { price: 29.99, currency: 'USD' },
});

// Identify a user
truxl.identify('user-123', {
  email: '[email protected]',
  name: 'Jane Doe',
  plan: 'pro',
});

// Create an alias (link anonymous ID to authenticated ID)
truxl.alias('user-123', 'anon-device-abc');

// Graceful shutdown (flush remaining events before process exit)
await truxl.shutdown();

API Reference

new Truxl(config)

Create a new SDK instance.

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectToken | string | required | Project token from the Truxl dashboard | | clientSecret | string | required | Client secret for HMAC-SHA256 request signing | | apiEndpoint | string | https://ingestion.api.stage.truxl.com | Ingestion service base URL | | batchSize | number | 20 | Max events per batch before auto-flush | | flushInterval | number | 5000 | Auto-flush interval in milliseconds | | retryAttempts | number | 5 | Retry count for 5xx / network errors | | retryBaseDelay | number | 1000 | Base delay (ms) for exponential backoff |

truxl.track(options)

Track a custom event.

| Option | Type | Description | |--------|------|-------------| | eventName | string | required — Name of the event | | distinctId | string | Unique user identifier | | deviceId | string | Device ID (auto-generated UUID if omitted) | | sessionId | string | Session identifier (typically unused server-side) | | timestamp | number | Epoch milliseconds (defaults to Date.now()) | | properties | object | Arbitrary event properties |

truxl.identify(distinctId, traits)

Set user profile properties. Sends a $identify event.

• distinctId (string, required) — The user to identify.
• traits (object, required) — Key-value pairs to set on the profile.

truxl.alias(newId, originalId)

Link a new ID (e.g. post-login) to an original ID (e.g. anonymous device ID). Sends a $alias event.

truxl.flush()

Immediately flush all queued events. Returns a Promise<void>.

truxl.shutdown()

Gracefully shut down the SDK: flushes remaining events, stops the flush timer, and destroys the HTTP connection pool. Returns a Promise<void>.

After calling shutdown(), any further calls will throw.

HMAC Request Signing

Every request is signed with HMAC-SHA256. The raw JSON body is signed using your clientSecret, and the resulting lowercase hex digest is sent as the X-Signature header. This is handled automatically by the SDK.

HMAC-SHA256(key = clientSecret, message = JSON body) -> lowercase hex

Batching and Retry

Events are queued in memory and flushed in batches:

• Auto-flush triggers when the queue reaches batchSize (default 20) or every flushInterval ms (default 5000).
• Retries use exponential backoff on 5xx or network errors: baseDelay * 2^attempt, capped at 60 seconds.
• 4xx responses are not retried (the batch is dropped and an error is logged to stderr).

Graceful Shutdown

Always call await truxl.shutdown() before your process exits to ensure all queued events are delivered:

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

Requirements

• Node.js >= 18.0.0

License

MIT