Server SDKv1.0.0MIT License

Node.js SDK

acai-node is the server-side Node.js SDK. It runs only in Node environments — if loaded in a browser it logs a warning and exits.

Server-only. Do not bundle acai-node into browser builds. Use acai-js or @acai/analytics-browser for client-side tracking.

Installation

Shell

npm install acai-node

Initialise

JavaScript

import { init } from 'acai-node'

const client = init('YOUR_API_KEY', {
  serverUrl: 'https://events.yourdomain.com/2/httpapi',
  logLevel:  2, // 0=None 1=Error 2=Warn 3=Verbose
})

Track events

JavaScript

await client.logEvent({
  event_type: 'API Request',
  user_id:    'user_abc123',
  event_properties: {
    endpoint: '/api/v1/export',
    status:   200,
  },
})

// Flush before process exit
await client.flush()

Always call client.flush() before your process exits to ensure all buffered events are sent.

Identify users

JavaScript

import { Identify } from '@acai/identify'

const identify = new Identify()
identify.set('plan', 'enterprise')
identify.setOnce('first_seen', new Date().toISOString())
identify.add('api_call_count', 1)

await client.identify('user_abc123', undefined, identify)

Middleware

JavaScript

// Enrich every event with server-side context
client.addEventMiddleware((payload, next) => {
  payload.event.event_properties = {
    ...payload.event.event_properties,
    server_region: process.env.AWS_REGION,
  }
  next(payload)
})

// Filter — drop internal bot events
client.addEventMiddleware((payload, next) => {
  if (payload.event.user_id === 'internal_bot') return
  next(payload)
})

Config reference

Option	Type	Default	Description
`serverUrl`	string	—	Your collector endpoint.
`logLevel`	number	`0`	0=None · 1=Error · 2=Warn · 3=Verbose
`debug`	boolean	`false`	Shorthand for verbose logging.
`maxCachedEvents`	number	`16000`	Max buffered events before forced flush.
`uploadIntervalInSec`	number	`0`	Auto-flush interval (0 = next tick).
`retryTimeouts`	number[]	`[100, 100, 200…]`	Retry delay schedule in ms.
`requestTimeoutMillis`	number	`10000`	Per-request HTTP timeout.
`optOut`	boolean	`false`	Disable all event sending.
`minIdLength`	number	`null`	Minimum length for user/device IDs.