Referencia del SDK

El SDK @bettermeter/node no tiene dependencias (usa fetch y crypto integrados). Requiere Node.js 18+.

Constructor

const bm = new BetterMeter(config);

siteIdrequerido

string

Dominio o identificador registrado en BetterMeter

apiKeyrequerido

string

Clave API (token Bearer) desde la configuración del dashboard

apiUrl

string

URL de la API de BetterMeter. Por defecto: "https://bettermeter.com". Las URL remotas personalizadas se bloquean salvo que se permitan explícitamente.

allowCustomApiUrl

boolean

Permitir una URL HTTPS personalizada para la API. Úselo solo para despliegues autoalojados de confianza.

disabled

boolean

Desactivar todo el rastreo. Por defecto: false

batch

boolean

Poner eventos en cola y vaciar a intervalo. Por defecto: false

batchInterval

number

Intervalo de vaciado en ms. Por defecto: 5000

hashUserId

boolean

Hashear los identificadores de usuario personalizados antes de enviarlos. Por defecto: true.

redactProperties

boolean

Redactar claves de propiedades sensibles como tokens, secretos, contraseñas, cookies y claves API. Por defecto: true.

Los valores de seguridad predeterminados son conservadores: se requieren claves API para la ingesta del SDK, se eliminan los valores de flags, las propiedades personalizadas no pueden sobrescribir campos confiables del SDK, los identificadores de usuario se hashean por defecto y las claves sensibles se redactan antes de enviar eventos.

trackCommand(options)

commandrequerido

string

Nombre del comando

subcommand

string

Subcomando (ej.: "deploy preview")

flags

string[]

Nombres de flags usados (valores eliminados)

version

string

Versión del CLI

durationMs

number

Tiempo de ejecución en milisegundos

exitCode

number

Código de salida del proceso (0 = éxito)

isCi

boolean

Ejecutando en entorno CI

userId

string

Identificador de usuario personalizado

properties

object

Propiedades personalizadas adicionales

trackTool(options)

toolrequerido

string

Nombre de la herramienta MCP

client

string

Nombre del cliente IA (ej.: "claude-code", "cursor")

protocolVersion

string

Versión del protocolo MCP

durationMs

number

Tiempo de ejecución en milisegundos

success

boolean

Si la llamada tuvo éxito

errorType

string

Clasificación del error (ej.: "validation_error")

inputTokens

number

Conteo de tokens de entrada

outputTokens

number

Conteo de tokens de salida

userId

string

Identificador de usuario personalizado

properties

object

Propiedades personalizadas adicionales

trackApi(options)

methodrequerido

string

Método HTTP (GET, POST, etc.)

endpointrequerido

string

Patrón de endpoint (use :param para segmentos dinámicos)

statusCode

number

Código de estado de la respuesta HTTP

durationMs

number

Tiempo de respuesta en milisegundos

userId

string

Identificador de usuario personalizado

properties

object

Propiedades personalizadas adicionales

Encapsuladores automáticos

`wrapCommander(program, options?)`

Se conecta al postAction de Commander.js para rastrear automáticamente todos los comandos.

`wrapMcpServer(server)`

Parche dinámico de server.tool() para encapsular todos los manejadores con cronometraje y rastreo de errores.

`expressMiddleware()`

Devuelve un middleware Express/Connect que rastrea cada solicitud en res.end.

Detección de bots del lado del servidor

La mayoría de los bots no ejecutan JavaScript, por lo que el script de rastreo nunca se activa para ellos. Use reportBotVisit() en su middleware de servidor para detectar bots a nivel de solicitud.

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
}

requestrequerido

Request

Solicitud entrante (NextRequest, Request, etc.)

siteIdrequerido

string

Su ID de sitio BetterMeter

options.apiUrl

string

URL de la API de BetterMeter. Por defecto: https://bettermeter.com

options.apiKey

string

Clave API usada para autenticar reportes de bots del lado del servidor

options.allowCustomApiUrl

boolean

Permitir una URL HTTPS personalizada para la API. Úselo solo para despliegues autoalojados de confianza.

Compatible con edge (sin dependencias de Node.js). No bloqueante -- no agrega latencia a las respuestas. Omite automáticamente recursos estáticos, rutas de API e internos de Next.js.

Ciclo de vida

`flush(): Promise<void>`

Enviar todos los eventos en cola inmediatamente.

`shutdown(): Promise<void>`

Detener el temporizador de lotes y vaciar los eventos restantes. Llamar antes de que finalice el proceso.