@lodd/node

@lodd/node

Server-side tracking SDK for Lodd. Built for API, MCP, agent, and CLI products — the headless stuff nothing else tracks well.

Install

npm install @lodd/node

Quick start

import { Lodd } from "@lodd/node";

const ca = new Lodd({
  apiKey: process.env.LODD_API_KEY!,   // ca_... from your Lodd dashboard
  siteId: process.env.CA_SITE_ID!,   // UUID of the site to report to
});

ca.track("api_call", { endpoint: "/v1/search", duration_ms: 42 });

// On graceful shutdown
await ca.close();

Express middleware

import express from "express";
import { Lodd } from "@lodd/node";
import { caExpress } from "@lodd/node/express";

const app = express();
const ca = new Lodd({ apiKey, siteId });

app.use(caExpress(ca, {
  ignore: (req) => req.path === "/health",
}));

The middleware captures path, method, status, and duration_ms. It never captures query strings, request bodies, or headers.

Options

Option	Default	Notes
apiKey	—	Required.
siteId	—	Required. Overridable per track() call.
baseUrl	https://api.lodd.dev	Production proxy. Override to point at a local Supabase stack (e.g. http://127.0.0.1:54321) or an alternate deploy.
maxBatchSize	50	Events queued before forced flush.
flushIntervalMs	5000	Timer-based flush cadence.
onError	console.warn	Called for dropped events or failed batches.

Guarantees

• track() never throws.
• Events >8KB of properties are dropped (with onError).
• Failed batches are retried up to 3× with exponential backoff; then dropped.
• close() flushes any queued events.

Session granularity

Server-side events don't have natural session boundaries, so the SDK synthesises a session_id deterministically from user_id + site_id + UTC date. This makes Daily Active Users correct out of the box, but a single user active across multiple UTC days will count as multiple unique_visitors in weekly/monthly range aggregations. Supply your own session_id in a future ca.track() overload if you need different granularity.