Node — @millimetric/track-node

@millimetric/track-node — server-side SDK. Node 18+ / Bun / Deno.

A thin wrapper over POST /v1/track and POST /v1/batch with batching, retries on 5xx, and exponential backoff. Zero dependencies.

Install

npm i @millimetric/track-node

Requires Node 18+ (global fetch). Works in Bun and Deno too.

Quick start

import { init, track, flush } from "@millimetric/track-node";

init({ key: process.env.AOA_SK!, host: "https://api.millimetric.ai" });

// somewhere in a request handler:
track({
  event: "purchase",
  anonymous_id: req.cookies.aid,
  user_id: user.id,
  properties: { amount_cents: 4900, currency: "usd" }
});

// before a serverless function returns:
await flush();

Public API

init(options) → MillimetricClient

type ClientOptions = {
  /** Your sk_* key (use sk_ on servers, not pk_). */
  key: string;
  /** Worker base URL. */
  host: string;
  /** Flush at N queued events. Default 1 (send immediately). */
  flushAt?: number;
  /** Flush after this many ms. Default 1000. */
  flushIntervalMs?: number;
  /** Retries on 5xx / network errors. Default 3. */
  maxRetries?: number;
};

You can also construct a client directly without the singleton:

import { MillimetricClient } from "@millimetric/track-node";
const client = new MillimetricClient({ key, host });
client.track({ event: "x" });
await client.flush();

track(event)

track({
  event: "signup",
  anonymous_id: "u_abc",
  user_id: "user_42",
  properties: { plan: "free" }
});

Same field shape as the POST /v1/track HTTP body.

flush()

await flush();

Flushes the queue synchronously. Call this before a serverless function exits — otherwise queued events may be lost when the function is frozen.

Retry behavior

• 5xx response → retried with exponential backoff (100, 200, 400, 800 ms).
• Network error → same.
• 4xx response → thrown immediately, no retry. (The payload is bad; retrying won't help.)
• After maxRetries attempts, the in-flight batch is re-added to the head of the queue and the error bubbles up from flush().

Batching

flushAt controls how many events to accumulate before sending:

init({ key, host, flushAt: 50, flushIntervalMs: 5000 });

With flushAt > 1, the SDK uses POST /v1/batch. With flushAt = 1 (the default), it uses POST /v1/track directly — no extra latency.

The internal timer is unref()'d so it won't keep a Node process alive on its own. You still need flush() before exit.

Pattern: long-running server

init({ key, host, flushAt: 50, flushIntervalMs: 2000 });

// fire and forget — the SDK batches in the background
app.post("/signup", async (req, res) => {
  // … your signup logic …
  track({ event: "signup", anonymous_id: req.cookies.aid, user_id: user.id });
  res.json({ ok: true });
});

// on shutdown:
process.on("SIGTERM", async () => { await flush(); process.exit(0); });

Pattern: serverless (Vercel / Cloudflare / Lambda)

init({ key, host, flushAt: 1 });   // send immediately

export async function POST(req: Request) {
  // … handle the request …
  track({ event: "form_submit", anonymous_id });
  await flush();                    // important — function freezes after this returns
  return new Response("ok");
}

Pattern: background backfill

import { MillimetricClient } from "@millimetric/track-node";
import fs from "node:fs/promises";

const client = new MillimetricClient({ key: process.env.AOA_SK!, host, flushAt: 1000 });

const events = JSON.parse(await fs.readFile("backfill.json", "utf8"));
for (const e of events) client.track(e);
await client.flush();