SDK Reference

The @bettermeter/node SDK is zero-dependency (uses built-in fetch and crypto). Requires Node.js 18+.

Constructor

const bm = new BetterMeter(config);

siteIdrequired

string

Domain or identifier registered in BetterMeter

apiKeyrequired

string

API key (Bearer token) from dashboard settings

apiUrl

string

BetterMeter API URL. Default: "https://bettermeter.com". Remote custom URLs are blocked unless explicitly allowed.

allowCustomApiUrl

boolean

Allow a custom HTTPS API URL. Use only for trusted self-hosted deployments.

disabled

boolean

Disable all tracking. Default: false

batch

boolean

Queue events and flush on interval. Default: false

batchInterval

number

Flush interval in ms. Default: 5000

hashUserId

boolean

Hash custom user IDs before sending. Default: true.

redactProperties

boolean

Redact sensitive property keys such as tokens, secrets, passwords, cookies, and API keys. Default: true.

Security defaults are conservative: API keys are required for SDK ingestion, flag values are stripped, custom properties cannot override trusted SDK fields, user IDs are hashed by default, and sensitive property keys are redacted before events are sent.

trackCommand(options)

commandrequired

string

Command name

subcommand

string

Subcommand (e.g., "deploy preview")

flags

string[]

Flag names used (values stripped)

version

string

CLI version

durationMs

number

Execution time in milliseconds

exitCode

number

Process exit code (0 = success)

isCi

boolean

Running in CI environment

userId

string

Custom user identifier

properties

object

Additional custom properties

trackTool(options)

toolrequired

string

MCP tool name

client

string

AI client name (e.g., "claude-code", "cursor")

protocolVersion

string

MCP protocol version

durationMs

number

Execution time in milliseconds

success

boolean

Whether the call succeeded

errorType

string

Error classification (e.g., "validation_error")

inputTokens

number

Input token count

outputTokens

number

Output token count

userId

string

Custom user identifier

properties

object

Additional custom properties

trackApi(options)

methodrequired

string

HTTP method (GET, POST, etc.)

endpointrequired

string

Endpoint pattern (use :param for dynamic segments)

statusCode

number

HTTP response status code

durationMs

number

Response time in milliseconds

userId

string

Custom user identifier

properties

object

Additional custom properties

Auto-wrappers

`wrapCommander(program, options?)`

Hooks into Commander.js postAction to auto-track all commands.

`wrapMcpServer(server)`

Monkey-patches server.tool() to wrap all handlers with timing and error tracking.

`expressMiddleware()`

Returns an Express/Connect middleware that tracks every request on res.end.

Server-Side Bot Detection

Most bots don't execute JavaScript, so the browser tracker never fires for them. Use reportBotVisit() in your server middleware to detect bots at the request level.

middleware.ts

// Next.js middleware
import { reportBotVisit } from "@bettermeter/node/middleware";

export function middleware(request) {
  reportBotVisit(request, "my-site.com", { apiKey: "bm_..." });
  // ... rest of your middleware
}

requestrequired

Request

Incoming request (NextRequest, Request, etc.)

siteIdrequired

string

Your BetterMeter site ID

options.apiUrl

string

BetterMeter API URL. Default: https://bettermeter.com

options.apiKey

string

API key used to authenticate server-side bot reports

options.allowCustomApiUrl

boolean

Allow a custom HTTPS API URL. Use only for trusted self-hosted deployments.

Edge-compatible (no Node.js dependencies). Non-blocking -- adds zero latency to responses. Automatically skips static assets, API routes, and Next.js internals.

Lifecycle

`flush(): Promise<void>`

Send all queued events immediately.

`shutdown(): Promise<void>`

Stop batch timer and flush remaining events. Call before process exit.