kalaa

Drop-in AI cost tracking for Node.js and TypeScript. Patches the OpenAI, Anthropic, and Gemini client libraries at the class level, so every client you create — before or after observe(), anywhere in your app — is already instrumented. No wrapping, no manual logging per call.

Install

npm install @kalaa/node

Setup

const kalaa = require('@kalaa/node');
kalaa.observe({ key: process.env.KALAA_KEY });

Or in TypeScript / ESM:

import kalaa from '@kalaa/node';
kalaa.observe({ key: process.env.KALAA_KEY });

That's it. Put KALAA_KEY=cm_live_xxx in your .env and every OpenAI, Anthropic, and Gemini call your app makes from here on is tracked automatically — including the user who made the request, with zero extra code, if you're running Express (route + user attribution wire themselves in automatically).

Tagging a user manually

Automatic detection covers most setups (reads x-user-id, a decoded JWT, or a client-side anonymous id). If yours doesn't fit that shape, tag it explicitly:

kalaa.setUser(currentUser.id);

Background jobs / cron

No request to hang a route off of, so give it a label instead:

kalaa.withContext('nightly-digest', () => {
  runTheJob();
});

What's tracked automatically

• OpenAI: chat completions, including streaming (stream_options.include_usage)
• Anthropic: messages, including streaming
• Gemini: generateContent and generateContentStream — both @google/genai (current) and @google/generative-ai (legacy) are supported
• Whisper/audio transcription duration

Order matters for Gemini: call kalaa.observe() before you require('@google/genai') anywhere in your app. (OpenAI and Anthropic aren't order-sensitive — only the current Gemini SDK's instance-bound methods require this.)

Configuration

| Option | Env var | Default | |---|---|---| | key | KALAA_KEY | — | | endpoint | KALAA_ENDPOINT | https://api.kalaa.cc/api/ingest | | env | KALAA_ENV | NODE_ENV | | debug | KALAA_DEBUG=1 | false |

Failure behavior

This package never touches a database and never sits in the path of your AI calls. If the ingest endpoint is unreachable, events are buffered and retried on the next flush cycle — your app is never blocked or crashed by a tracking failure.

License

MIT