Node SDK

The Logspot SDK for server-side JavaScript and TypeScript. Use it for events your backend knows about and the browser does not: a payment settling, a background job finishing, a webhook from another system.

It authenticates with an API token (the legacy project secret key also works), so it must only run on a server. For browser tracking use the JS SDK or the web script.

Installation

npm install @logspot/node

Init

import Logspot from '@logspot/node';

Logspot.init({ apiToken: 'sk_a1b2c3d4e5f6' });

Create an API token in Settings → Integrations (or a project's Integrations tab for a project-scoped one). Keep it in an environment variable and never commit it. The legacy init({ secretKey }) still works and warns once. See API Authentication.

For NodeNext or ESM projects, named exports are also available: import { init, track, revenue, group } from '@logspot/node';.

Track

Logspot.track({
  event: 'Subscription Started',
  userId: '[email protected]',
  metadata: { plan: 'pro', seats: 12 },
});

Parameter	Notes
`event`	Required. The event name
`userId`	Links the event to a person. An id, a UUID, or an email all work
`anonymousId`	The visitor's browser id (from `Logspot.getAnonymousId()`), so a server event stitches to their anonymous history
`groupId`	Associate the event (and user) with an account, e.g. a company domain
`groupType`	Group type for `groupId`; defaults to `company`
`metadata`	Any JSON object, stored as event properties
`message`	A short string, up to 350 characters
`channel`	Optional grouping label
`value`	Monetary value in major units. Marks the event as revenue
`currency`	ISO 4217 code, sent alongside `value`
`externalId`	Source transaction id. Re-sending the same id is deduplicated
`notify`	Deprecated and being sunset. Accepted for backwards compatibility, but nothing reads it

The maximum payload size is 3kB.

Revenue

revenue() is a wrapper over track() for payments. The amount is in major units, so dollars rather than cents.

Logspot.revenue(29.99, {
  currency: 'USD',
  userId: '[email protected]',
  transactionId: 'ch_3Ov...', // your Stripe charge id
  plan: 'pro',
});

transactionId is what makes this safe to retry. Sending the same id twice records the payment once, so a webhook handler that fires twice does not double-count revenue. Pass your payment processor's charge id and you get idempotency for free.

revenue() also accepts anonymousId, groupId, and groupType to attribute the payment to a visitor and account. Any other properties you pass, such as plan above, are stored as event metadata.

By default the event is named Payment (a label for your reports). Revenue is recognized by the value + currency fields, not the name, so overriding it with event to distinguish payment types does not change what counts as revenue.

Negative and non-finite amounts are rejected rather than sent.

Group

Associate a user or anonymous visitor with an account (Segment-style group()), creating or updating a membership without emitting an event. Pass userId or anonymousId (at least one is required). See Groups & Companies.

Logspot.group('acme.com', {
  userId: '[email protected]',
  traits: { name: 'Acme, Inc.', plan: 'enterprise' },
});

Pass { type: 'workspace' } to use a group type other than the default company.

What This SDK Does Not Do

init, track, revenue, and group are the surface. There is no identify or consent method here.

To identify a user or record consent from a server, call the REST API directly with your API token (Authorization: Bearer sk_...):