@auvh/climeter

Usage-based metering and billing for CLI tools and AI agents — Node.js/TypeScript SDK.

🌐 climeter.ai · 📖 Docs

Install

npm install @auvh/climeter

Zero runtime dependencies. Requires Node.js ≥ 18 (native fetch).

Quick Start

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

meter.configure({ apiKey: 'clmtr_...', toolSlug: 'my-tool' });

const search = meter.track({ price: 0.01 })(async (query: string) => {
  return doSearch(query);
});

Or set environment variables and skip configure():

export CLIMETER_API_KEY=clmtr_...
export CLIMETER_TOOL_SLUG=my-tool

Usage

Wrapper (decorator pattern)

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

const search = meter.track({ price: 0.01 })(async (query: string) => {
  return doSearch(query);
});

const result = await search('hello');

Callback wrapper

const result = await meter.trackUsage('search', { price: 0.01 }, async () => {
  return doSearch(query);
});

Manual event

meter.trackEvent({ event: 'search', price: 0.01 });

Consumer Usage

Call a CLIMeter-powered tool and handle balance errors:

import { call, InsufficientBalanceError } from '@auvh/climeter';

try {
  const result = await call({ toolId: 'tool-uuid-here' });
  console.log(`Balance remaining: $${result.balanceRemaining.toFixed(4)}`);
} catch (e) {
  if (e instanceof InsufficientBalanceError) {
    console.log(`Out of credits. Top up at: ${e.checkoutUrl}`);
  }
}

API

| Method | Description | |---|---| | meter.configure({ apiKey, toolSlug, apiUrl }) | Configure the global meter | | meter.track(options)(fn) | Wraps a function — records event after each call | | meter.trackUsage(name, options, fn) | Async callback — records event on completion | | meter.trackEvent(options) | Manual fire-and-forget event | | meter.flush() | Force-flush all pending events | | meter.shutdown() | Flush and stop background timer |

Runtime Compatibility

Node.js ≥ 18 · Deno · Bun · Cloudflare Workers · Browser

License

MIT © CLIMeter