npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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

Tests npm node license

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-sdk

Requires 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:

  • profileId is 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.
  • masterId is 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 queued

flush() 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 migration

Breaking 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 app

Four 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

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:consumer

Pull 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.