tell-node

Tell SDK for Node.js — analytics events and structured logging.

Install

# npm
npm install tell-node

# yarn
yarn add tell-node

# pnpm
pnpm add tell-node

# bun
bun add tell-node

Quick Start

import { Tell } from "tell-node";

const tell = new Tell({ apiKey: "your-api-key" });

// Track an event
tell.track("user_123", "Sign Up", { plan: "pro" });

// Identify a user
tell.identify("user_123", { name: "Alice", email: "[email protected]" });

// Structured logging
tell.logInfo("User signed up", "auth", { userId: "user_123" });

// Flush and close before process exit
await tell.close();

API

new Tell(config)

Creates a new Tell instance. Each instance manages its own batching, transport, and lifecycle.

const tell = new Tell({
  apiKey: "your-api-key",
  // All options below are optional:
  endpoint: "https://collect.tell.app",  // default
  batchSize: 100,                         // events per batch
  flushInterval: 10_000,                  // ms between auto-flushes
  maxRetries: 3,                          // retry attempts on failure
  closeTimeout: 5_000,                    // ms to wait on close()
  networkTimeout: 30_000,                 // ms per HTTP request
  logLevel: "info",                       // "error" | "warn" | "info" | "debug"
  source: os.hostname(),                  // source identifier
  disabled: false,                        // disable all tracking
  maxQueueSize: 1000,                     // max queued items
  gzip: false,                            // gzip request bodies
  onError: (err) => console.error(err),   // error callback
  beforeSend: (event) => event,           // transform/filter events
  beforeSendLog: (log) => log,            // transform/filter logs
});

Events

tell.track(userId, eventName, properties?)
tell.identify(userId, traits?)
tell.group(userId, groupId, properties?)
tell.revenue(userId, amount, currency, orderId, properties?)
tell.alias(previousId, userId)

Logging

tell.log(level, message, service?, data?)

// Convenience methods
tell.logEmergency(message, service?, data?)
tell.logAlert(message, service?, data?)
tell.logCritical(message, service?, data?)
tell.logError(message, service?, data?)
tell.logWarning(message, service?, data?)
tell.logNotice(message, service?, data?)
tell.logInfo(message, service?, data?)
tell.logDebug(message, service?, data?)
tell.logTrace(message, service?, data?)

Lifecycle

await tell.flush()    // flush all pending events and logs
await tell.close()    // flush + shut down (call before process exit)

Config Presets

import { Tell, development, production } from "tell-node";

// Development: localhost:8080, small batches, debug logging
const dev = new Tell(development("your-api-key"));

// Production: default endpoint, error-only logging
const prod = new Tell(production("your-api-key"));

License

MIT