Node.js SDK

What this lets you do

Send pageviews and revenue conversions to Traceten from your Node.js backend, over server-to-server HTTP that survives ad-blockers and privacy browsers. Use it where the browser snippet cannot run: server-rendered or headless flows, background jobs, webhook handlers, and mobile or API backends.

Before you start

Node.js 18 or newer.
Your Traceten siteId, from Sites → Install in the dashboard.
Your ingest host URL, for example https://ingest.traceten.com.
A visitorId for each event. The SDK runs on your server, so there is no Traceten cookie to read. You supply the identifier from your own request context. It is either a UUID or an h:<64-hex> identify hash. See supplying identifiers.

Install

pnpm add @traceten/sdk-node

npm and yarn work too:

npm install @traceten/sdk-node
yarn add @traceten/sdk-node

The only runtime dependency is undici.

Minimal example

import { Client } from "@traceten/sdk-node";

const traceten = new Client({
  siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  host: "https://ingest.traceten.com",
  apiKey: process.env.TRACETEN_API_KEY!,
});

// A pageview.
traceten.page({
  url: "https://acme.com/pricing",
  referrer: "https://chat.openai.com/",
  visitorId: "123e4567-e89b-42d3-a456-426614174000",
});

// A conversion worth $49.00.
traceten.track("subscription_started", {
  visitorId: "123e4567-e89b-42d3-a456-426614174000",
  valueCents: 4900,
  currency: "usd",
});

// Flush anything still buffered and stop the background timer.
await traceten.close();

How it behaves

page() and track() buffer the event and return immediately. The SDK sends events in the background: when the events queue reaches flushAt, every flushInterval milliseconds, on an explicit flush(), and on process exit. These methods never throw because of a network problem. A failed delivery surfaces through your onError hook, never as an exception in your request path. They do throw synchronously on a programmer error, so you catch a mis-shaped call in development instead of a silent server-side rejection:

track() called without a visitorId
an eventName that fails its pattern
a url that is not a valid URL
a valueCents that is not a non-negative integer

Configuration

const traceten = new Client({
  siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  host: "https://ingest.traceten.com",
  apiKey: process.env.TRACETEN_API_KEY!, // required, sent as Bearer auth
  flushAt: 50, // flush the events queue at this size (clamped to 1..50)
  flushInterval: 5000, // background flush cadence, ms
  maxRetries: 3, // retries on 5xx / 429 / network error
  timeoutMs: 10000, // per-request timeout, ms
  onError: (err) => console.error("[traceten]", err.message),
  flushOnExit: true, // best-effort flush on beforeExit / SIGTERM / SIGINT
});

host must be an absolute http(s) URL. A trailing slash is stripped. There is no default host: each deployment has its own ingest URL. host must use https unless it is a loopback address. The API key is sent as a Bearer token on every request, so a plaintext http host would transmit a live credential in cleartext; the SDK refuses one at construction. apiKey is required. See The API key below.

The API key

apiKey is required. Create a key in the dashboard under Settings, API keys, or use the key shown once when you created the site. The key must carry the Send events permission (ingest:write). New keys are created read-only by default, so tick that box when you create one, or the API will reject your calls. The key created automatically with a new site already has it. See permissions. Keep it on your server. It is a secret: never put it in client-side code, a mobile app, or a public repository. It is not the same value as siteId, which is public and already embedded in your pages. The key does two things:

It gets you in. The SDK posts to {host}/v1/server/events, {host}/v1/server/conversions and {host}/v1/server/payments, which return 401 without a valid key. The open /v1/events and /v1/conversions endpoints stay open for the browser snippet, which cannot hold a secret.
It gets you your own quota. Authenticated traffic is rate-limited on a bucket tied to the key, separate from the shared per-site bucket. siteId is public, so anyone who can read your page source can send events under it. With a key, that traffic cannot exhaust your allowance and 429 your conversion calls.

The constructor validates the key’s shape and throws if it is missing or malformed. An integration that silently drops every event is worse than one that fails on its first line. To rotate a key: create the new one, deploy it, then revoke the old one. Revocation normally takes effect at the edge within about a minute. If our database is unreachable at that moment, an edge location that was already using the key may keep honouring it for up to about fifteen minutes more, so that a database blip cannot silently drop your events.

API reference

`new Client(options)`

Option	Type	Required	Default	Description
`siteId`	`string`	yes		Site id. 1-64 chars, `A-Z a-z 0-9 _ -`.
`host`	`string`	yes		Ingest base URL. Absolute http(s). Trailing slash stripped.
`apiKey`	`string`	yes		Secret key, sent as `Authorization: Bearer`. See The API key.
`flushAt`	`number`	no	`50`	Flush the events queue at this size. Clamped to `[1, 50]`.
`flushInterval`	`number`	no	`5000`	Background flush cadence in ms.
`maxRetries`	`number`	no	`3`	Retry attempts on 5xx / 429 / network error.
`timeoutMs`	`number`	no	`10000`	Per-request timeout in ms.
`onError`	`(err: Error) => void`	no		Called when a batch is permanently dropped.
`flushOnExit`	`boolean`	no	`true`	Register best-effort flush on exit signals.

`page(props)`

Enqueues a pageview to POST {host}/v1/server/events.

Prop	Type	Required	Default	Description
`url`	`string`	yes		Valid URL, up to 2048 chars.
`referrer`	`string`	no	`""`	Referring URL.
`visitorId`	`string`	no		UUID or `h:<hash>`.
`sessionId`	`string`	no		Your session token.
`userAgent`	`string`	no		The end user’s User-Agent, if known.
`eventName`	`string`	no	`"pageview"`	Must match `^[a-z][a-z0-9_-]*$`.
`timestamp`	`Date \| string`	no	now	Event time.

traceten.page({
  url: "https://acme.com/blog/ai-search",
  referrer: "https://www.perplexity.ai/",
  visitorId: "123e4567-e89b-42d3-a456-426614174000",
  sessionId: "9f2c4b1d-7e3a-42b5-8c1d-2e5f6a7b8c9d",
  userAgent: req.headers["user-agent"],
});

Which user agent gets recorded. The userAgent you pass is what Traceten stores on the event and classifies on. Omit it and the event falls back to the User-Agent header the SDK’s own HTTP client sent, which describes your server rather than the visitor. That substitution applies only to requests authenticated with an API key. The browser snippet cannot override its own User-Agent this way.

`track(name, opts)`

Enqueues a conversion to POST {host}/v1/server/conversions. name must match ^[a-z][a-z0-9_]*$ (no hyphen). visitorId is required: a conversion cannot be attributed without it.

Option	Type	Required	Default	Description
`visitorId`	`string`	yes		UUID or `h:<hash>`.
`properties`	`object`	no	`{}`	Arbitrary JSON properties.
`valueCents`	`number`	no		Non-negative integer, minor units. Maps to `value_cents`.
`currency`	`string`	no		ISO-4217 code. Any case; stored uppercase.
`sessionId`	`string`	no		Your session token.
`timestamp`	`Date \| string`	no	now	Event time.

valueCents is in minor units. For $49.00, pass 4900. The field is spelled out as valueCents (not value) to prevent the dollars-versus-cents mistake.

traceten.track("order_completed", {
  visitorId: "123e4567-e89b-42d3-a456-426614174000",
  valueCents: 12999,
  currency: "usd",
  properties: { order_id: "ord_5521", items: 3 },
});

Keep visitorId opaque: a random first-party id or a salted hash you control. Never a bare sha256(email) or any hash of an email or phone number (that is re-identifiable PII). The SDK enforces the shape (UUID or h:<64-hex>) but cannot see what you hashed. Keep properties to ids and enums such as { plan: "pro" }. Do not put emails, names, or phone numbers in them.

`goal(name, opts)`

traceten.goal("demo_booked", {
  visitorId: "123e4567-e89b-42d3-a456-426614174000",
  properties: { plan: "pro" },
});

Records a goal completion. Same arguments, same endpoint, and same payload as track(), with one difference: it throws on the reserved names, which belong to the Stripe and Shopify integrations. Reserved: payment, free_trial, trial_started, trial_converted, subscription_started, subscription_upgraded, subscription_downgraded, subscription_renewed, subscription_cancel_scheduled, subscription_reactivated, subscription_ended. track() still accepts them, because that is how those events are legitimately sent. Goal property keys and values are both stored, and both are read back: GET /v1/goals/{name}/properties returns each key and its most common values, and the dashboard renders the same breakdown. Keep them to ids and enums. See what happens to property keys and values.

`payment(props)`

Records a payment from any payment processor via POST {host}/v1/server/payments. See the Payment API reference for the full contract. Unlike page() and track(), this one sends immediately and returns what the server did with the payment.

Option	Type	Required	Default	Description
`transactionId`	`string`	yes		The processor’s id for the payment. The idempotency key.
`amount`	`number`	yes		Major unit, not cents. `49.99` for $49.99. Zero records a trial.
`currency`	`string`	yes		ISO-4217 code. Any case; sent uppercase.
`provider`	`string`	no	`api`	Your label for the processor. Lowercase, 1 to 32 characters.
`visitorId`	`string`	no		UUID or `h:<hash>`. The strongest match.
`email`	`string`	no		Used to find the customer’s sessions. Never stored.
`customerId`	`string`	no		The processor’s customer identifier.
`renewal`	`boolean`	no	`false`	A subscription renewal. Does not feed the LTV report.
`refunded`	`boolean`	no	`false`	Refunds the payment in full. Never send a negative `amount`.
`isFreeTrial`	`boolean`	no	`false`	Records a trial. Implied by `amount: 0`.
`timestamp`	`Date \| string`	no	now	Payment time.

amount is the major unit, the opposite of track()’s valueCents. For $49.99 pass 49.99, and for ¥5000 pass 5000. It is the number you read off your processor.

Partial refunds do not go through this method. refunded: true takes back everything still outstanding on the transaction, and this SDK has no field for a smaller figure. To refund part of a payment, POST to /v1/server/payments with refunded_amount, which is the total refunded against the transaction so far.

const result = await traceten.payment({
  transactionId: "pay_9fK2mQ",
  amount: 49.99,
  currency: "USD",
  provider: "dodo",
  email: "ada@example.com",
});

result.status; // "recorded" | "trial" | "refunded" | "duplicate"

Calling it again with the same transactionId returns "duplicate" and creates nothing. That is why the SDK retries a 5xx here. It rejects when the payment could not be delivered after every retry, and when a field is invalid. It is the only method in this SDK that reports a delivery failure to the caller, because a dropped payment is missing revenue rather than a missing pageview. Wrap it accordingly:

try {
  await traceten.payment({ transactionId: charge.id, amount: 49.99, currency: "USD" });
} catch (err) {
  // Log and retry later. The endpoint is idempotent, so a retry is safe.
}

Do not send payments here for a processor you have also connected natively. Traceten would record the payment twice and overstate your revenue. See avoiding duplicate payments.

`flush()`

await traceten.flush();

Sends everything queued now. Resolves once every in-flight request settles. Never rejects.

`close()` / `shutdown()`

await traceten.close();

Flushes, stops the background timer, and removes the exit hooks. Idempotent. After close(), page(), track() and payment() throw. shutdown() is an alias.

Batching and retries

Pageviews are sent to /v1/server/events in batch envelopes of up to 50 events. If you enqueue 120 pageviews, the SDK sends them as batches of 50, 50, and 20.
Conversions are sent to /v1/server/conversions one body per event.
Payments are sent to /v1/server/payments immediately, one body per call, and are not buffered.
On a 5xx, a 429, or a network or timeout error, the batch is retried with exponential backoff and full jitter, up to maxRetries times.
On any other 4xx the payload is malformed. The SDK drops it and calls onError. It does not retry, because retrying a rejected payload forever is a self-inflicted denial of service.

Graceful shutdown

By default the SDK registers best-effort flush hooks on beforeExit, SIGTERM, and SIGINT, so a normal shutdown does not lose buffered events. For full control, flush explicitly and disable the hooks:

const traceten = new Client({
  siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  host: "https://ingest.traceten.com",
  flushOnExit: false,
});

process.on("SIGTERM", async () => {
  await traceten.close();
  process.exit(0);
});

Data loss on a hard kill (SIGKILL, power loss) is expected. Data loss on a graceful shutdown is not.

Verify it worked

Send one page() call from your backend.
Open Sites → Events in the Traceten dashboard for that site.
The event appears in the live event feed within a few seconds.

If nothing arrives, register an onError hook to see why.

Verify webhook signatures

If you subscribe to Traceten’s outbound webhooks (AI-session and conversion events), verify every delivery before you act on it. verifyWebhook() recomputes the X-Traceten-Signature HMAC in constant time, enforces the replay window, and returns the parsed, typed event, or throws WebhookVerificationError.

import { verifyWebhook, WebhookVerificationError } from "@traceten/sdk-node";

const secret = process.env.TRACETEN_WEBHOOK_SECRET!;

try {
  const event = verifyWebhook(
    rawBody, // Buffer or exact UTF-8 string of the request body
    req.header("X-Traceten-Signature") ?? "",
    req.header("X-Traceten-Signature-Timestamp") ?? "",
    secret,
  );

  switch (event.type) {
    case "ai_session.classified":
      // event.data is typed as AiSessionClassifiedData
      break;
    case "conversion.attributed":
      // event.data is typed as ConversionAttributedData
      break;
    case "webhook.ping":
      break;
  }
} catch (err) {
  if (err instanceof WebhookVerificationError) {
    // signature or timestamp bad: reject with 401
  }
}

Verify the raw body, not a re-serialized one

The single most common verification bug: a framework parses the JSON, your code re-serializes it, and the bytes no longer match what Traceten signed (key order, whitespace, and unicode escaping all differ). Always pass the raw bytes as received, and only act on the event after verification succeeds.

Express: use express.raw({ type: "application/json" }) on the webhook route, not express.json(). req.body is then a Buffer you pass straight in.
Fastify: register a content-type parser with { parseAs: "buffer" } for the webhook route so the handler receives the raw Buffer.

import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@traceten/sdk-node";

const app = express();
const secret = process.env.TRACETEN_WEBHOOK_SECRET!;

app.post("/traceten-webhooks", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = verifyWebhook(
      req.body, // Buffer, thanks to express.raw
      req.header("X-Traceten-Signature") ?? "",
      req.header("X-Traceten-Signature-Timestamp") ?? "",
      secret,
    );
    // Acknowledge fast; do heavy work on a queue.
    res.status(200).end();
  } catch (err) {
    res.status(err instanceof WebhookVerificationError ? 401 : 400).end();
  }
});

toleranceSeconds (default 300) sets the replay window. Pass Infinity only when testing against the fixed conformance vector.

Troubleshooting

Events never appear. Register an onError hook. The most common causes are a wrong host, a siteId typo, or a firewall blocking outbound HTTPS. TypeError on track(). You omitted visitorId, or the event name has a hyphen. Conversion names allow only a-z, 0-9, and _. TypeError on page(). The url is not a valid absolute URL, or the eventName does not match ^[a-z][a-z0-9_-]*$. A short-lived script exits before sending. Call await traceten.close() before the process ends, or keep flushOnExit enabled.

Python SDK
Go SDK
Browser API reference for client-side tracking
Stripe revenue attribution

SDKs

What this lets you do

Before you start

Install

Minimal example

How it behaves

Configuration

The API key

API reference

`new Client(options)`

`page(props)`

`track(name, opts)`

`goal(name, opts)`

`payment(props)`

`flush()`

`close()` / `shutdown()`

Batching and retries

Graceful shutdown

Verify it worked

Verify webhook signatures

Verify the raw body, not a re-serialized one

Troubleshooting

Next

​What this lets you do

​Before you start

​Install

​Minimal example

​How it behaves

​Configuration

​The API key

​API reference

​new Client(options)

​page(props)

​track(name, opts)

​goal(name, opts)

​payment(props)

​flush()

​close() / shutdown()

​Batching and retries

​Graceful shutdown

​Verify it worked

​Verify webhook signatures

​Verify the raw body, not a re-serialized one

​Troubleshooting

​Next

What this lets you do

Before you start

Install

Minimal example

How it behaves

Configuration

The API key

API reference

`new Client(options)`

`page(props)`

`track(name, opts)`

`goal(name, opts)`

`payment(props)`

`flush()`

`close()` / `shutdown()`

Batching and retries

Graceful shutdown

Verify it worked

Verify webhook signatures

Verify the raw body, not a re-serialized one

Troubleshooting

Next