Node.js SDK

Overview

The Node.js SDK is designed for server-side tracking where you have user identity. It supports:

Identified tracking - Use email or userId for user-scoped resolution
Customer attribution - Add customerId for account/workspace context, even before a user is known
Efficient batching - Events are queued and sent in batches
Device tracking - Use fingerprint for desktop/mobile apps (learn more)

Use server-side tracking for events that happen in your backend: subscription changes, feature usage from APIs, background jobs, etc.

Installation

npm install --save @outlit/node

pnpm add @outlit/node

yarn add @outlit/node

bun add @outlit/node

Quick Start

import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: 'pk_your_public_key'
})

// Track an event
outlit.track({
  email: 'user@example.com',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'subscription_upgraded',
  properties: {
    fromPlan: 'starter',
    toPlan: 'pro',
    mrr: 99
  }
})

// Important: flush before process exits
await outlit.flush()

Configuration

const outlit = new Outlit({
  publicKey: 'pk_xxx',
  flushInterval: 10000, // ms, default 10s
  maxBatchSize: 100, // events per batch
  timeout: 10000, // request timeout ms
})

Options

publicKey

string

required

Your organization’s public key.

apiHost

string

default:"https://app.outlit.ai"

API endpoint for sending events.

flushInterval

number

default:"10000"

How often to automatically flush events (milliseconds).

maxBatchSize

number

default:"100"

Maximum events per batch before auto-flush.

timeout

number

default:"10000"

HTTP request timeout in milliseconds.

API Reference

`outlit.track(options)`

Track a custom event for a user, a customer, or both.

outlit.track({
  email: 'jane@acme.com',
  userId: 'usr_12345', // optional if email provided
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'report_exported',
  properties: {
    reportType: 'sales',
    format: 'pdf',
    rowCount: 1500
  },
  timestamp: Date.now() // optional, defaults to now
})

string

User’s email address. Resolves immediately to a customer profile.

userId

string

Your system-owned user/contact ID.

fingerprint

string

Device identifier for anonymous tracking. See Device Tracking.

customerId

string

Your system-owned customer/account/workspace ID.

eventName

string

required

Name of the event. Use snake_case.

properties

Record<string, any>

Additional data to attach to the event.

timestamp

number

Unix timestamp in milliseconds. Defaults to current time.

At least one of email, userId, fingerprint, or customerId is required for track(). customerId-only events are valid immediately and can later link to a resolved customer when identify() uses the same customerId with an email.

`outlit.identify(options)`

Update user traits without tracking an event. Customer metadata can be included alongside the user identity.

outlit.identify({
  email: 'jane@acme.com',
  userId: 'usr_12345',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  customerTraits: {
    plan: 'enterprise',
    seats: 50
  },
  traits: {
    name: 'Jane Doe',
    role: 'admin'
  }
})

string

User’s email address. Use this or userId to establish user-scoped identity.

userId

string

Your system-owned user/contact ID.

fingerprint

string

Device identifier for linking anonymous events. See Device Tracking.

traits

Record<string, any>

Properties to update on the user profile.

customerId

string

Your system-owned customer/account/workspace ID. Send this with email or userId to link the account/workspace to the resolved contact profile.

customerTraits

Record<string, any>

Properties to update on the customer profile.

At least one of email or userId is required for identify(). Customer fields are optional additions.

Lifecycle and billing

Send ordinary product facts with track(). For activation, choose the ordinary event that represents your product’s value milestone and track it after the action succeeds:

outlit.track({
  email: 'user@example.com',
  eventName: 'onboarding_completed',
  properties: { flow: 'onboarding' }
})

Outlit Core derives activation from the customer-selected ordinary event and derives engagement and inactivity from activity. Billing status comes from verified integrations such as Stripe. See Customer Journey.

`outlit.flush()`

Immediately send all queued events. Call this before your process exits.

await outlit.flush()

`outlit.shutdown()`

Gracefully shutdown: flushes remaining events and stops the timer.

await outlit.shutdown()

`outlit.queueSize`

Get the number of events waiting to be sent.

console.log(`Pending events: ${outlit.queueSize}`)

Framework Examples

Express.js

import express from 'express'
import { Outlit } from '@outlit/node'

const app = express()
const outlit = new Outlit({ publicKey: 'pk_xxx' })

// Middleware to attach tracker to request
app.use((req, res, next) => {
  req.outlit = outlit
  next()
})

app.post('/api/reports/export', async (req, res) => {
  const { user, format } = req.body

  // Your export logic
  const report = await generateReport(format)

  // Track the event
  req.outlit.track({
    email: user.email,
    eventName: 'report_exported',
    properties: { format, size: report.size }
  })

  res.json({ success: true })
})

// Graceful shutdown
process.on('SIGTERM', async () => {
  await outlit.shutdown()
  process.exit(0)
})

Next.js API Routes

// app/api/subscription/upgrade/route.ts
import { Outlit } from '@outlit/node'

const outlit = new Outlit({ publicKey: process.env.OUTLIT_KEY! })

export async function POST(request: Request) {
  const { userId, email, customerId, newPlan } = await request.json()

  // Your upgrade logic
  await upgradeSubscription(userId, newPlan)

  // Track the event
  outlit.track({
    email,
    userId,
    customerId,
    eventName: 'subscription_upgraded',
    properties: { plan: newPlan }
  })

  // Flush immediately (serverless)
  await outlit.flush()

  return Response.json({ success: true })
}

Serverless Functions (AWS Lambda, Vercel)

In serverless environments, always call flush() before returning. The function may be terminated before the background flush runs.

import { Outlit } from '@outlit/node'

const outlit = new Outlit({ publicKey: process.env.OUTLIT_KEY! })

export async function handler(event) {
  const { email, action } = JSON.parse(event.body)

  outlit.track({
    email,
    eventName: action,
    properties: { source: 'lambda' }
  })

  // Critical: flush before returning
  await outlit.flush()

  return { statusCode: 200, body: 'OK' }
}

Stripe Webhooks

Connect Stripe as a verified Outlit integration. Subscription state then updates account billing status automatically; do not translate Stripe webhooks into authoritative SDK billing commands.

Background Jobs (Bull, Agenda)

import { Queue, Worker } from 'bullmq'
import { Outlit } from '@outlit/node'

const outlit = new Outlit({ publicKey: 'pk_xxx' })

const worker = new Worker('emails', async (job) => {
  const { email, templateId } = job.data

  // Your job logic
  await sendEmail(email, templateId)

  // Track completion
  outlit.track({
    email,
    eventName: 'email_sent',
    properties: { templateId, jobId: job.id }
  })
})

// Periodic flush (events batch automatically)
// No need to flush per job unless critical

Common Events to Track

Here are recommended server-side events:

Event	When	Properties
`subscription_created`	New subscription	`plan`, `price`, `interval`
`subscription_upgraded`	Plan upgrade	`fromPlan`, `toPlan`, `mrr`
`subscription_cancelled`	Cancellation	`reason`, `mrr_lost`
`payment_succeeded`	Payment received	`amount`, `currency`
`payment_failed`	Payment failed	`amount`, `error_code`
`feature_used`	Feature usage	`feature`, `count`
`api_key_created`	API key created	`keyName`, `permissions`
`export_completed`	Data export	`format`, `rowCount`, `size`
`invite_sent`	Team invite	`inviteeEmail`, `role`
`user_role_changed`	Permission change	`fromRole`, `toRole`

Error Handling

The SDK silently handles errors to not disrupt your application. For debugging:

const outlit = new Outlit({ publicKey: 'pk_xxx' })

// Events are queued even if the network is down
outlit.track({ email: 'user@test.com', eventName: 'test' })

// Check queue size to detect potential issues
if (outlit.queueSize > 500) {
  console.warn('Outlit queue backing up - possible connectivity issue')
}

TypeScript Support

Full TypeScript support is included:

import {
  Outlit,
  type OutlitOptions,
  type ServerTrackOptions,
  type ServerIdentifyOptions,
} from '@outlit/node'

const options: OutlitOptions = {
  publicKey: 'pk_xxx',
  flushInterval: 5000,
}

const outlit = new Outlit(options)

const trackOptions: ServerTrackOptions = {
  email: 'user@test.com',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  eventName: 'test',
  properties: { key: 'value' }
}

outlit.track(trackOptions)

Getting Started

Concepts

Browser SDKs

Server SDKs

CLI

AI Integrations

Use Cases

Overview

Installation

Quick Start

Configuration

Options

API Reference

`outlit.track(options)`

`outlit.identify(options)`

Lifecycle and billing

`outlit.flush()`

`outlit.shutdown()`

`outlit.queueSize`

Framework Examples

Express.js

Next.js API Routes

Serverless Functions (AWS Lambda, Vercel)

Stripe Webhooks

Background Jobs (Bull, Agenda)

Common Events to Track

Error Handling

TypeScript Support

Next Steps

Identity Resolution

Customer Journey

​Overview

​Installation

​Quick Start

​Configuration

​Options

​API Reference

​outlit.track(options)

​outlit.identify(options)

​Lifecycle and billing

​outlit.flush()

​outlit.shutdown()

​outlit.queueSize

​Framework Examples

​Express.js

​Next.js API Routes

​Serverless Functions (AWS Lambda, Vercel)

​Stripe Webhooks

​Background Jobs (Bull, Agenda)

​Common Events to Track

​Error Handling

​TypeScript Support

​Next Steps

Identity Resolution

Customer Journey

Overview

Installation

Quick Start

Configuration

Options

API Reference

`outlit.track(options)`

`outlit.identify(options)`

Lifecycle and billing

`outlit.flush()`

`outlit.shutdown()`

`outlit.queueSize`

Framework Examples

Express.js

Next.js API Routes

Serverless Functions (AWS Lambda, Vercel)

Stripe Webhooks

Background Jobs (Bull, Agenda)

Common Events to Track

Error Handling

TypeScript Support

Next Steps