intempt-nodejs-sdk
v4.1.0
Published
Server-side Node.js client for the Intempt platform: data in, decisions out.
Readme
Intempt Node.js SDK
Server-side client for Intempt. Data in, decisions out.
- In — events, identity, consent, commerce
- Out — experiences, personalizations, recommendations
This is a server library, not a browser one. It holds no per-user state: every call takes its identifier explicitly, so one client instance is safe to share across requests for all users. For the browser, use intempt-js.
Console and configuration operations are deliberately not here — see Not in this SDK.
npm install intempt-nodejs-sdkRequires Node 20 or newer. Written in TypeScript; types ship with the package.
The Intempt toolchain
| Tool | For | Use it when |
| --------------------------------------------------- | -------------------- | ---------------------------------------------------------- |
| intempt (this package) | your server | sending events, reading decisions on the request path |
| intempt-js | the browser | client-side auto-tracking, page and session context |
| @intempt/cli | your terminal and CI | tracking plans, typed wrapper codegen, coverage checks |
| @intempt/mcp-server | AI agents | journeys, dashboards, segments, brand — the management API |
If an operation is configuration or analysis rather than something on a customer request path, it belongs in the CLI or MCP server, not here.
Quick start
import { Intempt } from 'intempt-nodejs-sdk';
const intempt = Intempt.init({
org: 'my-org',
project: 'my-project',
apiKey: process.env.INTEMPT_API_KEY!, // "<prefix>.<secret>"
sourceId: '684508596718616576',
});
await intempt.track('purchase', {
userId: '[email protected]',
properties: { total: 99.99, currency: 'USD' },
});
const feed = await intempt.recommend({
userId: '[email protected]',
feedId: '5292',
fields: ['id', 'title'],
});By default each call sends one request and the promise resolves when the server responds. Nothing is buffered, so there is nothing to lose on exit — which makes this safe in Lambda and other short-lived processes.
API reference
| Call | Returns | Endpoint |
| ---------------------------------- | --------------------------- | ------------------------------------ |
| Intempt.init(config) | IntemptClient | — |
| track(event, options) | Promise<boolean> | POST …/track |
| trackBatch(events) | Promise<boolean> | POST …/track, chunked |
| identify(options) | Promise<boolean> | POST …/track (reserved Identify) |
| group(options) | Promise<boolean> | POST …/track (reserved Identify) |
| consent.grant(options) | Promise<boolean> | POST …/consents/data |
| consent.revoke(options) | Promise<boolean> | POST …/consents/data |
| ecommerce.productViewed(options) | Promise<void> | POST …/track |
| ecommerce.addedToCart(options) | Promise<void> | POST …/track |
| ecommerce.ordered(options) | Promise<void> | POST …/track |
| recommend(options) | Promise<unknown> | POST …/feeds/{id}/data |
| optIn() / optOut() | void | — |
| isOptedIn() / hasOptedOut() | boolean | — |
| flush() / close() | Promise<{ sent, failed }> | — |
| setConfig(patch) | void | — |
| config / buffered | getters | — |
A delivery failure is reported, never thrown, and never silent. The boolean
calls resolve false and the ecommerce helpers still resolve; the failure is
logged at error and reaches onDeliveryFailure once (see Errors).
Programming errors — invalid input, a closed client — reject, and so does a
failed recommend.
Configuration
Intempt.init({
org: 'my-org', // required
project: 'my-project', // required
apiKey: 'prefix.secret', // required, public API key
sourceId: '6845...', // optional, see below
host: 'api.intempt.com', // 'host' or 'host:port'
protocol: 'https',
path: '', // prefix before /v1, for a gateway
timeout: 10_000,
keepAlive: true,
logger: console, // needs trace/debug/info/warn/error
debug: false,
batch: false, // see Batching
maxRequestEvents: 50, // hard ceiling on events per request
maxConcurrentRequests: 1, // in-flight requests per trackBatch call
agent: undefined, // your own https.Agent, for mTLS or a private CA
});sourceId selects the ingestion source. With it, events go to
/sources/{sourceId}/track; without it, to /track. It is also required by the
API for consent records that identify a person by profileId.
Call setConfig() to change any of these on a live client, except org,
project, apiKey, sourceId, batch, keepAlive and agent. The last two are
fixed because the HTTP agents are built once at construction; the type rejects
them, so it is a compile error rather than a runtime surprise.
Identifiers
Every call takes at least one of two identifiers, and both are values you already own:
| | |
| ----------- | ----------------------------------------------------------- |
| userId | your identifier for a person: an email, an internal user id |
| accountId | your identifier for a company or account |
That is the whole list. The platform resolves identity from userId itself.
Two platform identifiers are deliberately not exposed:
profileIdis the anonymous id the browser SDK mints and keeps on the device. A server that invents one creates an orphan profile that never stitches to a real visitor.masterIdis assigned internally after identity resolution. There is no way to look one up from here, and a hardcoded one breaks the moment two profiles merge.
If you need to tie server events to a visitor's pre-login browser activity,
send the userId as soon as you know it and let the platform stitch:
declare identity, don't manage it.
Sending data
await intempt.track('purchase', {
userId: 'u1',
properties: { total: 99.99 },
timestamp: new Date(), // optional; Date or epoch ms
});
await intempt.trackBatch([
{ event: 'page_view', userId: 'u1', properties: { path: '/pricing' } },
{ event: 'signup', userId: 'u2' },
]);
await intempt.identify({ userId: 'u1', traits: { plan: 'pro' } });
await intempt.group({
userId: 'u1',
accountId: 'acme',
attributes: { tier: 'enterprise' },
});trackBatch chunks at maxRequestEvents, so a 500-event array becomes ten
requests rather than one oversized one. Those chunks go out one at a time by
default; raise maxConcurrentRequests to overlap them:
Intempt.init({ ...config, maxConcurrentRequests: 4 });Workers pull from a shared cursor, so a slow request never stalls the others and
no more than maxConcurrentRequests are ever in flight. If any chunk fails, the
call resolves false once every sibling request has settled, and each failed chunk
is reported once. Only a programming error (a payload that cannot be serialised)
rejects, and it too waits for the siblings, so a rejection can never leave an
unhandled promise behind.
Identity resolution happens on the platform, so there is no merge or alias call
here. Two identities that ever share an identifier -- the same device, email or
phone -- converge on one profile on their own. The destructive /users/merge
endpoint is not exposed either: it has no inverse and takes internal numeric IDs
this SDK cannot resolve.
Commerce
await intempt.ecommerce.productViewed({ userId: 'u1', productId: 'sku-1' });
await intempt.ecommerce.addedToCart({ userId: 'u1', productId: 'sku-1', quantity: 2 });
await intempt.ecommerce.ordered({
userId: 'u1',
products: [{ productId: 'sku-1', quantity: 2 }],
});These wrap track with the reserved event names the platform recognises.
Consent
await intempt.consent.grant({ userId: 'u1', category: 'marketing' });
await intempt.consent.revoke({
userId: 'u1',
category: 'marketing',
reason: 'user request',
});validUntil defaults to 'unlimited'. Timestamps are converted to the epoch
seconds the API expects.
grant and revoke resolve true when the record was stored and false
otherwise. A failure is handled like track: sent once (429/503 resent once),
logged at error and reported to onDeliveryFailure once, never thrown. Consent
has no queue, so a record that never reached the server is reported dropped
rather than kept.
Reading decisions
const feed = await intempt.recommend({
userId: 'u1', // or accountId, not both
feedId: '5292',
limit: 5,
fields: ['id', 'title', 'price'], // product attribute names from your catalog
});fields are product attribute names from your catalog schema, not arbitrary
keys. limit is optional and falls back to the feed's own setting.
The feeds API identifies an entity by an {id, type} pair rather than by
userId, so the SDK maps userId to type: 'user' and accountId to
type: 'account'. That is why the two are mutually exclusive here, unlike on the
tracking calls.
Why there are no experiments or personalizations
They resolve a web experience against a page, and are served by the browser
SDK, intempt-js. A server has no page to
modify, so /optimization/choose-api is not part of this surface.
The 1.x chooseExperimentsBy* and choosePersonalizationsBy* helpers throw a
message pointing at the browser SDK rather than returning an empty array: []
reads as "no variant assigned" and would silently disable a caller's experiment
instead of telling them where it moved.
Privacy
intempt.optOut(); // suppresses events and commerce; consent is still sent
intempt.isOptedIn(); // false
intempt.optIn();optOut() covers all outbound writes. recommend() still works: it
send an identifier you already hold and return a decision without storing
anything, so a user who opted out of collection still gets a working experience.
Batching
Off by default. Turn it on for a long-lived, high-volume process:
const intempt = Intempt.init({
org,
project,
apiKey,
sourceId,
batch: {
size: 50, // buffered events that trigger a flush
flushMs: 5_000, // idle time before a flush
maxQueue: 10_000, // ceiling; beyond it the oldest waiting event is dropped and reported
flushOnExit: true, // flush on process 'beforeExit'
},
});
await intempt.track('page_view', { userId: 'u1' }); // resolves true once buffered
await intempt.flush(); // drain now; resolves { sent, failed }
await intempt.close(); // drain, then release timers and sockets; resolves { sent, failed }
intempt.buffered; // events still queuedflush() and close() are safe to call when batching is off; they resolve
{ sent: 0, failed: 0 }.
close() drains for at most 30 seconds. Events still unsent at the end — the
budget ran out, or the server was unreachable — are dropped, counted in failed
and reported. flush() applies no budget.
Delivery policy (INT-7436), the same in batch and direct mode:
| Outcome | Behaviour |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2xx | sent |
| 429, 503 | resend once after Retry-After (1–60 s, 1 s if absent); a second failure drops |
| Retry-After above 5 s, or past close() | drop instead of waiting |
| any other status (400s, 408, 413, 5xx) | drop, no resend |
| timeout or lost response after sending | drop, no resend: the server may already have it |
| never reached the server (DNS, refused, network down, TLS handshake) | batch mode keeps the batch until the next timed flush (flushMs) or flush(); reaching size meanwhile sends nothing; direct mode and consent drop |
| a pooled keep-alive socket the server closed | reconnected once at once; if that also fails before sending, treated as never reached |
Each request is sent once because ingestion has no idempotency key. Payload
items of one request that share an eventId are stored as one row (measured
2026-11-16), so each item gets its own id; whether a resend of a request that
already landed is collapsed is not measured, so the SDK does not risk it. 429 and 503 are the two
answers that mean the server did not ingest, so they alone are resent. A 413 is
not split and resent; lower maxRequestEvents instead.
The buffer is in memory. A hard crash loses it. Crash durability needs disk with fsync and boot-time recovery, which is a different design.
TLS, proxies and private CAs
Keep-alive agents are created for you, and HTTPS_PROXY / HTTP_PROXY are
honoured. For anything beyond that — mutual TLS, a private certificate
authority, a bespoke proxy policy — pass your own agent:
import https from 'node:https';
Intempt.init({
...config,
agent: new https.Agent({
ca: fs.readFileSync('corporate-ca.pem'),
cert: fs.readFileSync('client.pem'),
key: fs.readFileSync('client.key'),
keepAlive: true,
}),
});Your agent is used verbatim: the SDK creates none of its own and ignores
keepAlive, HTTPS_PROXY and HTTP_PROXY, so nothing is silently layered over
your TLS configuration. It is also yours to destroy — close() leaves it alone.
Match the protocol. An http.Agent on an https client dials port 80 and the
request fails; use https.Agent unless you set protocol: 'http'.
Errors
A delivery problem never rejects (INT-7444). track, trackBatch, identify
and group resolve true when the event was accepted — queued in batch mode,
delivered in direct mode — and false otherwise. consent.grant and
consent.revoke resolve true when the record was stored and false otherwise.
The ecommerce helpers resolve either way. Every failure is logged at error. The final outcome of every
batch that did not deliver reaches one listener, once per batch, never per
attempt:
const intempt = Intempt.init({
...config,
onDeliveryFailure(failure) {
failure.kind; // 'transport' (unreachable, kept), 'terminal' (server said no), 'dropped' (dropped here)
failure.status; // HTTP status, when there was one
failure.eventCount;
failure.eventIds;
failure.retryAfter; // seconds, when the server sent Retry-After
failure.terminal; // false only for 'transport': the batch is still queued
},
});A listener that throws is caught and logged. Programming errors — a missing identifier, a reserved event name, a payload that cannot be serialised, a closed client — still reject.
Library identity
Every request carries X-Intempt-Lib: intempt-node/<version>, so a bad batch
can be traced to an SDK version. Nothing is added to the event payload: a new
payload field could affect a downstream event schema, and a header cannot.
Migrating from 1.x
new SDK(...) still works, forwards to the new client, and warns once. It will
be removed in 3.0.0.
const sdk = new SDK(org, project, apiKey, sourceId);
const client = sdk.v2; // the 2.x client, for incremental migrationBreaking changes to expect:
| 1.x | 2.x |
| ------------------------------------------- | ----------------------------------------- |
| ?apiKey= query parameter | Authorization: Basic header |
| invalid input warns and resolves | rejects |
| product helpers return { error: true } | reject on invalid input |
| trackingClient and friends | removed |
| NODE_ENV=test targets staging | host is configuration |
| optOut() gates tracking only | gates every write |
| consent timestamp in milliseconds | seconds, as the API expects |
| profileId required | any one identifier |
| choosePersonalizationsByGroups and 3 more | throw — browser SDK only |
| recommendation(...) | recommend({ userId, feedId, fields }) |
| unbounded resend, no flush | buffering is opt-in, with flush/close |
A delivery failure on the shim resolves and is logged at error; it never rejects.
The shim takes no config, so it has no onDeliveryFailure listener.
Not in this SDK
| Capability | Where it lives |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Journeys, experiences, dashboards, segments, deals, brand | CLI and MCP server |
| Tags and owner assignment | CLI and MCP server |
| Profile and account creation | CLI and MCP server |
| Identity merge | not exposed; the platform resolves identity automatically |
| Content and design generation | blocked: those endpoints require a bearer JWT with a person_id claim, and no API-key path exists |
Development
npm ci
npm run check-format # prettier
npm run lint # oxlint
npm run typecheck # tsc --noEmit
npm test # vitest, offline
npm run test:coverage
npm run build
npm run verify:consumer # pack, install, typecheck and run the sample appFour layers of verification, in increasing fidelity:
| Layer | What it proves | Network |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| tests/*.test.ts (nock) | what the SDK intends to send, and every branch of validation and retry | none |
| tests/integration.test.ts | what actually crosses a socket: header framing, keep-alive reuse, timeouts, the concurrency cap | real, loopback |
| npm run verify:consumer | the published tarball installs, its exports map resolves, the shipped .d.ts typechecks under stricter settings than the library uses, and the sample app runs | real, loopback |
| npm run test:e2e | the Intempt API accepts what we send | real, staging |
tests/integration.test.ts deliberately does not import the shared test helpers,
because those load nock, and nock patches http.ClientRequest at import time.
That would turn its "real socket" assertions into assertions about nock.
Only test:e2e needs credentials, and it needs more than a key: several methods
touch entities that must already exist in the project — an account, a catalog
product, a feed, a published experiment. See .env.example for
the full input list; copy it to .env.local and the contract test picks it up
automatically. Any step whose input is missing is reported as SKIP, never
as a pass: ingestion returns 201 for unknown ids, so a fabricated value would look
green and prove nothing.
See examples/basic for a runnable sample app.
Sample app
examples/basic exercises every namespace and runs offline
against a local mock API, so npm run verify:consumer works with no credentials.
Point it at a real environment with INTEMPT_HOST, INTEMPT_ORG,
INTEMPT_PROJECT, INTEMPT_API_KEY and INTEMPT_SOURCE_ID.
FAQ
Why does every call need an identifier? Why is there no stateful identify()?
This library is stateless by design, so one instance can be shared across
requests for every user. Client-side SDKs tie one instance to one user and can
hold a profileId; a server cannot. Pass userId or accountId with each call.
Do I need a profileId?
No. The API accepts userId on its own and links it to a profile for you.
Where is users.merge() / profile merging?
Deliberately absent. Merging is irreversible, no inverse endpoint exists, and it takes internal numeric IDs this SDK has no way to resolve. The platform resolves identity on its own from shared identifiers. If you genuinely need a merge, do it through the CLI or MCP server, where a human confirms it.
Which API key should I use?
A public key. It carries exactly the ingestion scopes this SDK needs. Never deploy a private or admin key in an application server — those grant full project access. See SECURITY.md.
Can I generate emails, images or copy with this SDK?
Not yet. Those endpoints authenticate with a bearer JWT tied to a person, and there is no API-key path into them, so it cannot be done from a server key. Use the CLI or MCP server today.
Should I turn batching on?
Only for a long-lived, high-volume process. The default sends one request per call and resolves when the server responds, which is the right behaviour for Lambda and anything that can exit at any moment. See Batching.
Is timestamp a backfill mechanism?
Yes, between 2010 and 2040. The event store keeps your value in its timestamp
column and records arrival separately in insertTime, so the two never overwrite
each other.
Both ends of that window behave differently, and the upper one is worth knowing:
| Your timestamp | What happens |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| before 2010-01-01 | refused: the server answers 400 for an event, so track resolves false and reports it; consent rejects before sending, naming the threshold |
| 2010 to 2040 | stored as given |
| after 2040-01-18 | silently replaced with the server's current time |
So a timestamp in seconds where milliseconds were meant lands in the far future, sails past the upper bound, and is quietly rewritten to now — no error, and the event looks like it just happened. The reverse mistake (milliseconds where seconds were meant) lands before 2010 and is refused and reported instead of rewritten.
Support
- Bugs and feature requests: open an issue
- Security reports: [email protected] — please do not use a public issue
- Platform documentation: docs.intempt.com
Contributing
git clone https://github.com/intempt/intempt-node.git
cd intempt-node
npm ci
npm run check-format && npm run lint && npm run typecheck && npm test
npm run verify:consumerPull request titles follow Conventional Commits
(feat:, fix:, chore:, …) and are checked in CI, because the release notes are
generated from the commit log. Every change needs a test, and
tests/integration.test.ts must stay free of nock — see
Development for why.
Attribution and credits
This SDK derives roughly 190 lines from mixpanel-node: its configuration object, credential handling, keep-alive and proxy agent setup, response classification, library-version reporting, and the batch-size ceiling.
Copyright (c) 2012 Carl Sverre, MIT licensed. Both projects are MIT. NOTICE records what is copied verbatim versus adapted, per file.
The HTTP transport, wire format, endpoints, retry policy and every public method signature are Intempt's own.
License
MIT. See LICENSE, and NOTICE for the mixpanel-node code this SDK derives from.
