Node.js SDK

The Inslytic Node.js SDK (@inslytic/sdk-node) enables server-side event tracking with automatic batching, exponential backoff retry, and graceful shutdown handling.

Installation

npm install @inslytic/sdk-node

Initialization

Create an InslyticNode instance. Unlike the browser SDK (singleton pattern), the Node SDK is class-based — you can create multiple instances for different projects.

import { InslyticNode } from "@inslytic/sdk-node";

const inslytic = new InslyticNode({
  apiKey: "your-api-key",
  endpoint: "https://api.inslytic.com", // optional
  flushInterval: 10000,                // optional, ms
  maxBatchSize: 20,                    // optional
  maxRetries: 3,                       // optional
});

Constructor options

Parameter	Type	Required	Description
apiKey	string	Required	Your project API key.
endpoint	string	Optional	API URL. Defaults to "https://api.inslytic.com".
flushInterval	number	Optional	Auto-flush interval in ms. Default: 10,000.
maxBatchSize	number	Optional	Max events per batch. Default: 20.
maxRetries	number	Optional	Max retry attempts on failure. Default: 3.

track(event)

Enqueues an event for sending. Auto-flushes when the batch size is reached.

inslytic.track({
  eventName: "order_completed",
  anonymousId: "anon-456",
  userId: "user-123",
  properties: {
    orderId: "ord-789",
    total: "49.99",
    currency: "EUR",
  },
});

Event payload

Parameter	Type	Required	Description
eventName	string	Required	Name of the event.
anonymousId	string	Required	Anonymous device/session identifier.
userId	string \| null	Optional	Identified user ID.
sessionId	string	Optional	Session identifier. Defaults to "".
properties	Record<string, string>	Optional	Custom event properties. Defaults to {}.
timestamp	string	Optional	ISO 8601 timestamp. Defaults to now.
consentGiven	boolean	Optional	Consent flag. Defaults to true.

identify(userId, traits?)

Sends a $identify event linking the user ID. Sets both userId and anonymousId to the provided ID.

inslytic.identify("user-123");

flush()

Manually flushes all queued events. Returns a promise that resolves when all events have been sent. Sends events in batches of maxBatchSize.

await inslytic.flush();

shutdown()

Gracefully shuts down the SDK. Clears the flush timer, removes signal handlers, and flushes any remaining events. Call this before your process exits.

// In your shutdown handler
await inslytic.shutdown();
process.exit(0);

pending

Read-only property returning the number of events currently in the queue.

console.log(inslytic.pending); // 5

Retry logic

The Node SDK automatically retries failed requests with exponential backoff:

Retries on server errors (5xx) and network failures
Does not retry on client errors (4xx)
Backoff: 1s, 2s, 4s, 8s... capped at 30 seconds
After exhausting retries, events are re-queued at the front of the queue
Default max retries: 3

Graceful shutdown

The SDK automatically registers handlers for SIGTERM and SIGINT signals to flush pending events before process exit. The handlers are removed when you call shutdown().