Node.js SDK

The official CLIMeter Node.js SDK. Supports ESM and CommonJS, TypeScript types built-in, Node.js 16+.

Bash

npm install @auvh/climeter

configure()

Initialize the SDK once at startup. Or rely on the CLIMETER_API_KEY env var for zero-config usage.

TypeScript

import { meter } from '@auvh/climeter';

meter.configure({
  apiKey: 'clmtr_...',          // or set CLIMETER_API_KEY env var
  toolSlug: 'my-tool',          // or set CLIMETER_TOOL_SLUG env var
  apiUrl: 'https://api.climeter.ai',  // default; override only if needed
});

Option	Type	Default	Description
apiKey	string	CLIMETER_API_KEY	Your CLIMeter API key (clmtr_...)
toolSlug	string	CLIMETER_TOOL_SLUG	Default slug for all events
apiUrl	string	"https://api.climeter.ai"	API base URL

Environment variables

.env

Bash

CLIMETER_API_KEY=clmtr_your_key_here
CLIMETER_TOOL_SLUG=my-tool
CLIMETER_API_URL=https://api.climeter.ai  # optional override

meter.track() — higher-order wrapper

Wraps a function (sync or async) and records a usage event after each call. Preserves the return type — sync functions remain sync, async remain async.

TypeScript

import { meter } from '@auvh/climeter';

// Async function — event name defaults to function name
const search = meter.track()(async (query: string) => {
  return await runSearch(query);
});

// Sync function — stays sync
const parseInput = meter.track({ command: 'parse' })((input: string) => {
  return JSON.parse(input);
});

// With metadata
const analyze = meter.track({
  command: 'code-analyze',
  metadata: { version: '2' },
})(async (file: string) => {
  return await runAnalysis(file);
});

Note

Pricing is set per-tool in the CLIMeter dashboard — not in code. The SDK does not accept a price argument.

meter.trackUsage() — callback wrapper

Run an async callback and record a usage event on completion.

TypeScript

import { meter } from '@auvh/climeter';

// Wrap a block of async code
const result = await meter.trackUsage(
  'search',
  { metadata: { source: 'api' } },
  async () => {
    return await runSearch(query);
  }
);

meter.trackEvent() — manual event

Manually enqueue a usage event. Fire-and-forget — returns immediately.

TypeScript

import { meter } from '@auvh/climeter';

// Record manually
meter.trackEvent({ event: 'search' });

// With metadata
meter.trackEvent({
  event: 'batch-search',
  metadata: { batch_size: 10 },
});

Lifecycle: flush & shutdown

Events are batched in the background. For long-running servers this is automatic. For short-lived scripts, flush before exit.

TypeScript

import { meter } from '@auvh/climeter';

// In a CLI / script — flush before process exits
await meter.flush();

// Graceful shutdown — flushes then stops the background timer
await meter.shutdown();

// Recommended pattern for CLI tools:
process.on('exit', async () => {
  await meter.flush();
});

Serverless / Lambda

Call await meter.flush() at the end of your handler to ensure events are sent before the container freezes.