@trevosdk/node

Run experiments outside the browser, and record conversions an ad blocker can never touch.

npm install @trevosdk/node

Install this before you run a single backend experiment

The cheapest reason to adopt this is not backend experimentation — it is that a subscription_started fired from your Stripe webhook is never lost to an ad blocker, a closed tab, or a failed beacon on unload. Client-side conversion tracking loses somewhere between a few and a few tens of percent of events that way, and those losses are not random: they correlate with browser, region, and privacy tooling.

Moving your money events server-side improves the statistics for every experiment you already run in the browser, before you ever call getVariant from a backend.

Quick start

import { createClient } from '@trevosdk/node';

const trevo = createClient({ secretKey: process.env.TREVO_SECRET_KEY });

// Assignment needs config. Await this once during startup, or every request in
// the first moments after a deploy falls back to control.
await trevo.ready();

const variant = trevo.getVariant('pricing-algo-v2', {
  userId: req.user?.id,
  anonymousId: req.cookies.trevo_id,
});

trevo.track('subscription_started', { userId, anonymousId }, { plan: 'pro' });

The key is a server key (tsk_secret_…), created under Settings → API keys with platform Server. It is shown once. Never use it in client code.

The rule that keeps client and server agreeing

Bucket with the same identity the browser is using at that moment: userId when the user is identified, otherwise the trevo_id cookie.

Assignment is deterministic on that identity. Pass something else — an internal account id, an email, a fresh uuid — and the same person gets variant A in the browser and variant B from your backend.

getVariant returns "control" and records nothing when neither id is present. That is deliberate — an unbucketed user is better than a wrongly bucketed one.

Identity linking

Trevo links an anonymous journey to a user the first time it sees an event carrying both ids. A webhook, a cron job, or a queue worker has no cookie to read, so its events arrive with a bare userId and that user's pre-login browsing is never stitched to their conversion.

When you cannot supply both ids on an event, state the link directly:

await trevo.alias(req.cookies.trevo_id, user.id);

An anonymous id belongs to one user. Re-pointing one at a different user is rejected rather than silently rewriting the link.

Runtimes

Web-standard APIs only (fetch, AbortSignal, timers), so Node 18+, Bun, Deno, Cloudflare Workers and Vercel edge all work with no adapter.

On serverless, create the client at module scope and await trevo.flush() before returning — the runtime may freeze the moment your handler resolves, taking queued events with it. On Cloudflare Workers, prefer ctx.waitUntil(trevo.flush()).

Documentation

Full reference, framework recipes (Express, Fastify, NestJS, serverless) and the identity model: https://docs.trevosdk.com

License

MIT