@kalaa/node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francis Ssennoga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# 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
+
+```bash
+npm install @kalaa/node
+```
+
+## Setup
+
+```js
+const kalaa = require('@kalaa/node');
+kalaa.observe({ key: process.env.KALAA_KEY });
+```
+
+Or in TypeScript / ESM:
+
+```ts
+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:
+
+```js
+kalaa.setUser(currentUser.id);
+```
+
+## Background jobs / cron
+
+No request to hang a route off of, so give it a label instead:
+
+```js
+kalaa.withContext('nightly-digest', () => {
+  runTheJob();
+});
+```
+
+## What's tracked automatically
+
+- OpenAI: chat completions, including streaming (`stream_options.include_usage`)
+- Anthropic: messages, including streaming
+- Gemini: `generateContent`
+- Whisper/audio transcription duration (if `music-metadata` is installed)
+
+## 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, never computes cost itself (your
+Kalaa project prices every event server-side), 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

package/costmeter.d.ts

@@ -0,0 +1,77 @@
+// Type declarations for kalaa — hand-written against the actual exported
+// API surface (see costmeter.js), not generated.
+
+export interface ObserveOptions {
+  /** Your project's ingest key. Defaults to process.env.KALAA_KEY. */
+  key?: string;
+  /** Ingest endpoint. Defaults to https://api.kalaa.cc/api/ingest. */
+  endpoint?: string;
+  /** How often buffered events flush, in ms. Default 3000. */
+  flushMs?: number;
+  /** Max events per batch before an early flush. Default 50. */
+  maxBatch?: number;
+  /** Environment label attached to every event. Defaults to NODE_ENV. */
+  env?: string;
+  /** Verbose console logging. Default false. */
+  debug?: boolean;
+}
+
+export interface TrackOptions {
+  step?: string;
+  provider?: 'openai' | 'anthropic' | 'gemini' | string;
+  model?: string;
+  usage?: Record<string, unknown>;
+  latencyMs?: number;
+  status?: 'ok' | 'error' | string;
+  meta?: Record<string, unknown> | null;
+  endUser?: string | null;
+}
+
+/**
+ * Start observing. Patches OpenAI/Anthropic/Gemini clients at the class
+ * level and, if Express is on the require path, auto-wires route
+ * attribution — no app.use() needed. Safe to call more than once; only
+ * the first call takes effect.
+ */
+export function observe(opts?: ObserveOptions): typeof api;
+
+/** Alias for observe(). */
+export function init(opts?: ObserveOptions): typeof api;
+
+/** Manually report a call — for raw-fetch usage (e.g. Gemini) or anything observe() didn't catch. */
+export function track(opts: TrackOptions): void;
+
+/** Tag the current request's AI calls with a real user id. Call this once you know who's asking. */
+export function setUser(id: string | null): void;
+
+/** Tag the current request's AI calls with a feature label. */
+export function setFeature(feature: string | null): void;
+
+/**
+ * Context manager for background jobs / cron — no request to hang a
+ * route off of, so you supply a label instead.
+ */
+export function withContext<T>(label: string, fn: () => T): T;
+
+/** Force an immediate flush of any buffered events. */
+export function flush(): void;
+
+/** Express middleware for manual route-attribution wiring, if you need it explicitly. */
+export function middleware(req: unknown, res: unknown, next: () => void): void;
+
+/** Manually instrument a specific OpenAI client instance. Rarely needed — observe() already patches the module. */
+export function instrumentOpenAI(client: unknown): void;
+
+declare const api: {
+  observe: typeof observe;
+  init: typeof init;
+  track: typeof track;
+  setUser: typeof setUser;
+  setFeature: typeof setFeature;
+  withContext: typeof withContext;
+  flush: typeof flush;
+  middleware: typeof middleware;
+  instrumentOpenAI: typeof instrumentOpenAI;
+};
+
+export default api;

package/costmeter.js

@@ -0,0 +1,587 @@
+// ═══════════════════════════════════════════════════════════════════
+//  costmeter.js — drop-in AI cost tracking SDK
+//
+//  Two-line setup, paste anywhere, order doesn't matter:
+//
+//     const costmeter = require('costmeter');
+//     costmeter.observe();
+//
+//  Put COSTMETER_KEY=cm_live_xxx in your .env and you're done.
+//
+//  observe() patches the OpenAI module at the class level (so any client
+//  you create, whenever you create it, is already instrumented) and, if
+//  Express is installed, auto-inserts route-attribution middleware. No
+//  app.use, no "after express.json", no manual instrument call.
+//
+//  It never touches a database, never computes cost, and never sits in
+//  the path of your AI calls — if ingest is unreachable, events are
+//  dropped silently and your app is unaffected.
+// ═══════════════════════════════════════════════════════════════════
+
+const { AsyncLocalStorage } = require('async_hooks');
+const crypto = require('crypto');
+const http = require('http');
+
+const als = new AsyncLocalStorage();
+
+// ── CONFIG ───────────────────────────────────────────────────────────
+const config = {
+  key:       process.env.KALAA_KEY || process.env.COSTMETER_KEY || null,
+   endpoint:  process.env.KALAA_ENDPOINT || process.env.COSTMETER_ENDPOINT || 'https://api.kalaa.cc/api/ingest',
+  flushMs:   3000,
+  maxBatch:  50,
+  env:       process.env.KALAA_ENV || process.env.COSTMETER_ENV || process.env.NODE_ENV || 'production',
+  debug:     process.env.KALAA_DEBUG === '1' || process.env.COSTMETER_DEBUG === '1',
+};
+
+let buffer = [];
+let timer = null;
+let started = false;
+
+function log(...a) { if (config.debug) console.log('[kalaa]', ...a); }
+
+// ═══════════════════════════════════════════════════════════════════
+//  observe() — the one call that wires everything.
+// ═══════════════════════════════════════════════════════════════════
+function observe(opts = {}) {
+  Object.assign(config, opts);
+  if (started) return api;
+  started = true;
+
+  if (!config.key) {
+console.warn('[kalaa] no KALAA_KEY set — tracking disabled. Add KALAA_KEY to your .env');
+    return api;
+  }
+
+  // 1. flush timer
+  if (!timer) {
+    timer = setInterval(flush, config.flushMs);
+    if (timer.unref) timer.unref();
+  }
+  process.once('beforeExit', flush);
+
+  // 2. auto-context: wrap the HTTP server so every request gets a run context
+  //    with route attribution — no app.use needed.
+  patchHttpServer();
+
+  // 3. auto-instrument AI SDKs at the MODULE level (order-independent)
+patchOpenAIModule();
+  patchAnthropicModule();
+  patchGeminiModule();
+
+  log('observing →', config.endpoint);
+  return api;
+}
+
+// ── OUTBOUND: batch + fire-and-forget POST ──────────────────────────
+async function flush() {
+  if (!config.key || buffer.length === 0) return;
+  const batch = buffer;
+  buffer = [];
+  try {
+    const fetchFn = global.fetch || require('node-fetch');
+    await fetchFn(config.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-ingest-key': config.key },
+      body: JSON.stringify({ events: batch }),
+    });
+    log(`flushed ${batch.length} events`);
+  } catch (err) {
+    log('flush failed, dropping', batch.length, 'events:', err.message);
+  }
+}
+
+// ── CONTEXT ──────────────────────────────────────────────────────────
+function ctx() {
+  return als.getStore() || { runId: null, route: 'background', endUser: null, feature: null };
+}
+const aliasedThisProcess = new Set(); // avoid re-sending the same anon→real merge repeatedly
+function setUser(id) {
+  const s = als.getStore();
+  if (!s) return;
+  const prevAnon = s.endUser;
+  s.endUser = id;
+  // Upgrading a still-anonymous session to a real id — tell the server to
+  // merge that anon id's history into this real one. Once per pair per
+  // process; the merge itself is idempotent so duplicate sends are harmless.
+  if (id && prevAnon && String(prevAnon).startsWith('anon_') && !aliasedThisProcess.has(prevAnon)) {
+    aliasedThisProcess.add(prevAnon);
+    buffer.push({ type: 'alias', anon_id: prevAnon, real_id: String(id), ts: new Date().toISOString() });
+  }
+}
+function setFeature(f) { const s = als.getStore(); if (s) s.feature = f; }
+function withContext(label, fn) {
+  return als.run({ runId: crypto.randomUUID(), route: label, endUser: null, feature: null }, fn);
+}
+
+// Reads a user id from common auth signals, no code change required on the
+// integrator's side if they're already sending these — an X-User-Id header,
+// or a JWT's sub/user_id/uid claim. We only decode the payload, never verify
+// the signature — we're reading an identity hint, not authenticating anyone.
+function detectUserFromHeaders(req) {
+  try {
+    const hdr = req.headers['x-user-id'] || req.headers['x-customer-id'];
+    if (hdr) return String(hdr);
+    const auth = req.headers['authorization'] || '';
+    const m = auth.match(/^Bearer\s+(.+)$/i);
+    if (m) {
+      const parts = m[1].split('.');
+      if (parts.length === 3) {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf8'));
+        const uid = payload.sub || payload.user_id || payload.uid || payload.id;
+        if (uid) return String(uid);
+      }
+    }
+  } catch (e) { /* not a JWT, or malformed — fall through to anonymous */ }
+  return null;
+}
+// Auto route-attribution: wrap http.Server request handling so each
+// incoming request runs inside an ALS context tagged with its route.
+function patchHttpServer() {
+  const origEmit = http.Server.prototype.emit;
+  if (origEmit.__cm_patched) return;
+  const patched = function (event, req, res) {
+    if (event !== 'request') return origEmit.apply(this, arguments);
+const store = {
+  runId: crypto.randomUUID(),
+  route: `${req.method} ${(req.url || '').split('?')[0]}`,
+  endUser: detectUserFromHeaders(req) || getOrSetAnonId(req), // JWT/header id if present, else localStorage-backed client id, else untagged — setUser() still overrides any of these
+  feature: null,
+};
+    // Re-enter the store on every event req/res emit later. Body chunks for
+    // large/multipart requests arrive in packets AFTER this synchronous chain
+    // returns — without this re-binding, body parsers (multer, express.json on
+    // big payloads) finish OUTSIDE the context, the route handler runs with no
+    // store, and every AI call in it lands untagged as route 'background'.
+    for (const target of [req, res]) {
+      const origTargetEmit = target.emit;
+      target.emit = function (...args) { return als.run(store, () => origTargetEmit.apply(this, args)); };
+    }
+    return als.run(store, () => origEmit.apply(this, arguments));
+  };
+  patched.__cm_patched = true;
+  http.Server.prototype.emit = patched;
+  log('http server patched for route attribution');
+}
+
+// Anonymous identity comes ONLY from a client-supplied id — set by
+// costmeter-client.js, backed by localStorage on the customer's frontend,
+// sent as a plain header (not a cookie, so no SameSite/third-party
+// blocking applies). If it's missing — no frontend script yet, or a pure
+// server-to-server call with no browser involved — we deliberately return
+// null (untagged) rather than mint a disposable id. A random id that shows
+// up once and never returns is worse than untagged: it's noise in the
+// customer list instead of the real signal, which is "add the client
+// script or call setUser() here."
+const CM_ANON_HEADER = 'x-cm-anon-id';
+function getOrSetAnonId(req) {
+  const clientId = req.headers[CM_ANON_HEADER];
+  if (clientId && /^[a-zA-Z0-9_-]{8,64}$/.test(String(clientId))) {
+    return `anon_${clientId}`;
+  }
+  return null;
+}
+// Best-effort byte size of the audio input, without reading the whole file.
+// Real duration from the audio container's own metadata (wav/mp3/m4a/webm all
+// expose this in their header — no decoding, no guessing). This is the
+// actual value Whisper bills against, just read client-side instead of
+// waiting for the API to hand it back (which it only does with verbose_json).
+async function getRealAudioDuration(file) {
+  let mm;
+  try { mm = require('music-metadata'); } catch { return null; } // not installed — degrade below
+  try {
+    let metadata;
+    if (Buffer.isBuffer(file)) {
+      metadata = await mm.parseBuffer(file);
+    } else if (file?.path) {
+      metadata = await mm.parseFile(file.path);
+    } else if (file?.arrayBuffer) { // Blob/File
+      const buf = Buffer.from(await file.arrayBuffer());
+      metadata = await mm.parseBuffer(buf);
+    } else {
+      return null;
+    }
+    const seconds = metadata?.format?.duration;
+    return typeof seconds === 'number' && seconds > 0 ? Math.round(seconds) : null;
+  } catch (e) {
+    log('duration read failed:', e.message);
+    return null;
+  }
+}
+
+// Rough seconds-from-bytes estimate. Whisper input is typically compressed
+// (mp3/m4a) around ~128kbps voice audio ≈ 16KB/sec. This is intentionally
+// conservative — good enough for cost visibility, not billing-grade exact.
+// ── USAGE NORMALIZATION (raw tokens only — backend prices) ──────────
+function normalizeUsage(provider, usage = {}) {
+  if (provider === 'anthropic') {
+    return {
+      input:      usage.input_tokens || 0,
+      cached:     usage.cache_read_input_tokens || 0,
+      cacheWrite: usage.cache_creation_input_tokens || 0,
+      output:     usage.output_tokens || 0,
+      seconds: 0,
+    };
+  }
+  if (provider === 'gemini') {
+    const cached = usage.cachedContentTokenCount || 0;
+    return {
+      input:  Math.max((usage.promptTokenCount || 0) - cached, 0),
+      cached, cacheWrite: 0,
+      output: usage.candidatesTokenCount || 0,
+      seconds: 0,
+    };
+  }
+  const cached = usage.prompt_tokens_details?.cached_tokens || 0;
+  return {
+    input:  Math.max((usage.prompt_tokens || usage.input_tokens || 0) - cached, 0),
+    cached, cacheWrite: 0,
+    output: usage.completion_tokens || usage.output_tokens || 0,
+    seconds: usage.seconds || 0,
+  };
+}
+
+function track({ step, provider = 'openai', model = '', usage = {}, latencyMs = 0, status = 'ok', meta = null, endUser = null }) {
+    try {
+    const c = ctx();
+    const u = normalizeUsage(provider, usage);
+    buffer.push({
+      ts: new Date().toISOString(),
+      run_id: c.runId, route: c.route, step: step || model,
+      provider, model,
+      input_tokens: u.input, cached_tokens: u.cached, cache_write_tokens: u.cacheWrite,
+      output_tokens: u.output, audio_seconds: u.seconds,
+      latency_ms: Math.round(latencyMs), status,
+      end_user: endUser || c.endUser || null, feature: c.feature || null,
+      environment: config.env, meta: meta || null,
+    });
+    log(`${c.route} → ${step || model} | ${u.input}f/${u.cached}c/${u.output}o`);
+    if (buffer.length >= config.maxBatch) flush();
+  } catch (err) { log('track error:', err.message); }
+}
+
+// Wraps a streaming completion so usage is captured on completion, without
+// altering what the caller receives — every chunk still flows through
+// exactly as OpenAI sent it.
+function wrapStreamForUsage(streamPromise, { _step, _user, model, t0 }) {
+  return streamPromise.then(stream => {
+    const origIterator = stream[Symbol.asyncIterator].bind(stream);
+    let capturedUsage = null;
+    let lastModel = model;
+
+    stream[Symbol.asyncIterator] = function () {
+      const it = origIterator();
+      return {
+        async next() {
+          const result = await it.next();
+          if (!result.done && result.value) {
+            const chunk = result.value;
+            if (chunk.usage) capturedUsage = chunk.usage;
+            if (chunk.model) lastModel = chunk.model;
+          }
+          if (result.done) {
+            track({
+              step: _step, endUser: _user, provider: 'openai',
+              model: lastModel, usage: capturedUsage || {},
+              latencyMs: Date.now() - t0,
+              status: capturedUsage ? 'ok' : 'no_usage_streamed',
+            });
+          }
+          return result;
+        },
+        return(value) { return it.return ? it.return(value) : Promise.resolve({ value, done: true }); },
+        throw(err) { return it.throw ? it.throw(err) : Promise.reject(err); },
+      };
+    };
+
+    return stream;
+  }, err => {
+    track({ step: _step, endUser: _user, provider: 'openai', model, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) } });
+    throw err;
+  });
+}
+
+// Anthropic streams usage across two events, not one: message_start carries
+// input_tokens, message_delta carries the final output_tokens. Same tap
+// pattern as OpenAI — caller's iteration is untouched, we just watch what
+// passes through.
+function wrapAnthropicStreamForUsage(stream, { _step, _user, model, t0 }) {
+  const origIterator = stream[Symbol.asyncIterator].bind(stream);
+  let inputTokens = 0, cachedTokens = 0, cacheWriteTokens = 0, outputTokens = 0;
+  let sawUsage = false;
+  let lastModel = model;
+
+  stream[Symbol.asyncIterator] = function () {
+    const it = origIterator();
+    return {
+      async next() {
+        const result = await it.next();
+        if (!result.done && result.value) {
+          const ev = result.value;
+          if (ev.type === 'message_start' && ev.message?.usage) {
+            sawUsage = true;
+            inputTokens = ev.message.usage.input_tokens || 0;
+            cachedTokens = ev.message.usage.cache_read_input_tokens || 0;
+            cacheWriteTokens = ev.message.usage.cache_creation_input_tokens || 0;
+            if (ev.message.model) lastModel = ev.message.model;
+          }
+          if (ev.type === 'message_delta' && ev.usage) {
+            sawUsage = true;
+            outputTokens = ev.usage.output_tokens || 0;
+          }
+        }
+        if (result.done) {
+          track({
+            step: _step, endUser: _user, provider: 'anthropic',
+            model: lastModel,
+            usage: {
+              input_tokens: inputTokens,
+              cache_read_input_tokens: cachedTokens,
+              cache_creation_input_tokens: cacheWriteTokens,
+              output_tokens: outputTokens,
+            },
+            latencyMs: Date.now() - t0,
+            status: sawUsage ? 'ok' : 'no_usage_streamed',
+          });
+        }
+        return result;
+      },
+      return(value) { return it.return ? it.return(value) : Promise.resolve({ value, done: true }); },
+      throw(err) { return it.throw ? it.throw(err) : Promise.reject(err); },
+    };
+  };
+
+  return stream;
+}
+
+// ── MODULE-LEVEL PATCHING (order-independent instrumentation) ───────
+// Patches the OpenAI class prototype so EVERY client — created before or
+// after observe() — is instrumented. No need to hand us the client.
+function patchOpenAIModule() {
+  let OpenAIMod;
+  try { OpenAIMod = require('openai'); } catch { return; } // not installed, skip
+  const OpenAI = OpenAIMod.OpenAI || OpenAIMod.default || OpenAIMod;
+  if (!OpenAI || typeof OpenAI !== 'function') return;
+  if (OpenAI.__cm_patched) return;
+
+  // The create() methods live on the Completions / Transcriptions class
+  // PROTOTYPES, not on each instance. Patch the prototype ONCE and every
+  // client — created before or after observe() — inherits the wrapper.
+  // We spin up a throwaway client (no network) just to reach those classes.
+  let Completions, Transcriptions;
+  try {
+    const probe = new OpenAI({ apiKey: 'cm_probe' });
+    Completions = Object.getPrototypeOf(probe.chat.completions).constructor;
+    Transcriptions = Object.getPrototypeOf(probe.audio.transcriptions).constructor;
+  } catch (e) {
+    log('openai probe failed:', e.message);
+    return;
+  }
+
+  if (Completions?.prototype?.create && !Completions.prototype.create.__cm) {
+const orig = Completions.prototype.create;
+ const wrapped = function (params, ...rest) {
+  const { _step, _user, ...clean } = params || {};
+  const t0 = Date.now();
+
+  if (clean.stream) {
+    // Ask for usage in the final chunk — safe even if caller already set stream_options.
+    const streamParams = {
+      ...clean,
+      stream_options: { ...(clean.stream_options || {}), include_usage: true },
+    };
+    const streamPromise = orig.call(this, streamParams, ...rest);
+    return wrapStreamForUsage(streamPromise, { _step, _user, model: clean.model, t0 });
+  }
+
+  return orig.call(this, clean, ...rest).then(resp => {
+    track({ step: _step, endUser: _user, provider: 'openai', model: resp.model || clean.model, usage: resp.usage || {}, latencyMs: Date.now() - t0 });
+    return resp;
+  }, err => {
+    track({ step: _step, endUser: _user, provider: 'openai', model: clean.model, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) } });
+    throw err;
+  });
+};
+    wrapped.__cm = true;
+    Completions.prototype.create = wrapped;
+  }
+
+if (Transcriptions?.prototype?.create && !Transcriptions.prototype.create.__cm) {
+  const orig = Transcriptions.prototype.create;
+  const wrapped = async function (params, ...rest) {
+    const { _step, ...clean } = params || {};
+    const t0 = Date.now();
+    // Read real duration from the file header BEFORE the call — cheap,
+    // and doesn't depend on the caller's response_format choice.
+    const measuredSeconds = await getRealAudioDuration(clean.file);
+    const resp = await orig.call(this, clean, ...rest);
+    const seconds = resp.duration || measuredSeconds || 0;
+    const source = resp.duration ? 'api' : (measuredSeconds ? 'file_metadata' : 'none');
+    track({
+      step: _step || 'transcription', provider: 'openai',
+      model: clean.model || 'whisper-1', usage: { seconds },
+      latencyMs: Date.now() - t0,
+      status: seconds ? 'ok' : 'no_duration',
+      meta: { duration_source: source },
+    });
+    return resp;
+  };
+  wrapped.__cm = true;
+  Transcriptions.prototype.create = wrapped;
+}
+
+  OpenAI.__cm_patched = true;
+  log('openai module patched (prototype-level)');
+}
+
+function patchAnthropicModule() {
+  let Mod;
+  try { Mod = require('@anthropic-ai/sdk'); } catch { return; }
+  const Anthropic = Mod.Anthropic || Mod.default || Mod;
+  if (!Anthropic || typeof Anthropic !== 'function') return;
+  if (Anthropic.__cm_patched) return;
+
+  // Same strategy as OpenAI: messages.create() lives on the Messages class
+  // PROTOTYPE. Patch it once and every client — constructed before or after
+  // observe(), via any import style — inherits the wrapper. No constructor
+  // swapping: the SDK's module exports are non-writable, so reassigning
+  // Mod.Anthropic silently does nothing.
+  let Messages;
+  try {
+    const probe = new Anthropic({ apiKey: 'cm_probe' });
+    Messages = Object.getPrototypeOf(probe.messages).constructor;
+  } catch (e) {
+    log('anthropic probe failed:', e.message);
+    return;
+  }
+
+  if (Messages?.prototype?.create && !Messages.prototype.create.__cm) {
+    const orig = Messages.prototype.create;
+    const wrapped = async function (params, ...rest) {
+      const { _step, _user, ...clean } = params || {};
+      const t0 = Date.now();
+
+      if (clean.stream) {
+        let stream;
+        try {
+          stream = await orig.call(this, clean, ...rest);
+        } catch (err) {
+          track({ step: _step, endUser: _user, provider: 'anthropic', model: clean.model, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) } });
+          throw err;
+        }
+        return wrapAnthropicStreamForUsage(stream, { _step, _user, model: clean.model, t0 });
+      }
+
+      try {
+        const resp = await orig.call(this, clean, ...rest);
+        track({ step: _step, endUser: _user, provider: 'anthropic', model: resp.model || clean.model, usage: resp.usage || {}, latencyMs: Date.now() - t0 });
+        return resp;
+      } catch (err) {
+        track({ step: _step, endUser: _user, provider: 'anthropic', model: clean.model, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) } });
+        throw err;
+      }
+    };
+    wrapped.__cm = true;
+    Messages.prototype.create = wrapped;
+  }
+
+  Anthropic.__cm_patched = true;
+  log('anthropic module patched (prototype-level)');
+}
+
+function patchGeminiModule() {
+  let Mod;
+  try { Mod = require('@google/generative-ai'); } catch { return; } // not installed, skip
+  const GoogleGenerativeAI = Mod.GoogleGenerativeAI;
+  if (!GoogleGenerativeAI || GoogleGenerativeAI.__cm_patched) return;
+
+  // Same trick as OpenAI: probe an instance to reach the GenerativeModel
+  // class prototype, patch it once, every model instance inherits it.
+  let GenerativeModel;
+  try {
+    const probe = new GoogleGenerativeAI('cm_probe');
+    const model = probe.getGenerativeModel({ model: 'gemini-1.5-flash' });
+    GenerativeModel = Object.getPrototypeOf(model).constructor;
+  } catch (e) {
+    log('gemini probe failed:', e.message);
+    return;
+  }
+
+if (GenerativeModel?.prototype?.generateContent && !GenerativeModel.prototype.generateContent.__cm) {
+    const orig = GenerativeModel.prototype.generateContent;
+    const wrapped = async function (params, ...rest) {
+      const t0 = Date.now();
+const modelName = (this.model || 'gemini').replace(/^models\//, '');
+      // Gemini params can be a plain object, a string, or an array — only
+      // strip _user when it's actually a plain request object carrying one.
+      let _user, clean = params;
+      if (params && typeof params === 'object' && !Array.isArray(params) && '_user' in params) {
+        ({ _user, ...clean } = params);
+      }
+      try {
+        const resp = await orig.call(this, clean, ...rest);
+        const usage = resp?.response?.usageMetadata || {};
+        track({ provider: 'gemini', model: modelName, usage, latencyMs: Date.now() - t0, endUser: _user });
+        return resp;
+      } catch (err) {
+        track({ provider: 'gemini', model: modelName, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) }, endUser: _user });
+        throw err;
+      }
+    };
+    wrapped.__cm = true;
+    GenerativeModel.prototype.generateContent = wrapped;
+  }
+
+  // generateContentStream: usage arrives only after the stream is fully
+  // consumed, via response.usageMetadata on the final resolved response
+  // object the SDK exposes — same tap pattern as OpenAI/Anthropic streaming.
+if (GenerativeModel?.prototype?.generateContentStream && !GenerativeModel.prototype.generateContentStream.__cm) {
+    const orig = GenerativeModel.prototype.generateContentStream;
+    const wrapped = async function (params, ...rest) {
+      const t0 = Date.now();
+const modelName = (this.model || 'gemini').replace(/^models\//, '');
+      let _user, clean = params;
+      if (params && typeof params === 'object' && !Array.isArray(params) && '_user' in params) {
+        ({ _user, ...clean } = params);
+      }
+      try {
+        const result = await orig.call(this, clean, ...rest);
+        result.response.then(finalResp => {
+          const usage = finalResp?.usageMetadata || {};
+          track({ provider: 'gemini', model: modelName, usage, latencyMs: Date.now() - t0, status: Object.keys(usage).length ? 'ok' : 'no_usage_streamed', endUser: _user });
+        }).catch(() => {});
+        return result;
+      } catch (err) {
+        track({ provider: 'gemini', model: modelName, usage: {}, latencyMs: Date.now() - t0, status: 'error', meta: { error: String(err.message).slice(0, 200) }, endUser: _user });
+        throw err;
+      }
+    };
+    wrapped.__cm = true;
+    GenerativeModel.prototype.generateContentStream = wrapped;
+  }
+
+  GoogleGenerativeAI.__cm_patched = true;
+  log('gemini module patched (prototype-level)');
+}
+
+// ── PUBLIC API ───────────────────────────────────────────────────────
+// observe() is the headline. The older explicit helpers stay available
+// for advanced users who want manual control (e.g. Gemini via raw fetch).
+const api = {
+  observe,
+  track,               // manual: for raw-fetch calls (Gemini, custom)
+  setUser, setFeature, // per-request tagging
+  withContext,         // background jobs / cron
+  flush,
+  // legacy explicit helpers (still work; observe() makes them unnecessary)
+  init: observe,
+  middleware: (req, res, next) => {
+    als.run({ runId: crypto.randomUUID(), route: `${req.method} ${req.path}`, endUser: null, feature: null }, next);
+  },
+  instrumentOpenAI: (client) => {
+    // manual path — wrap a specific instance
+    patchOpenAIModule();
+  },
+};
+
+module.exports = api;

package/package.json

@@ -0,0 +1,52 @@
+{
+"name": "@kalaa/node",
+  "version": "1.0.0",
+  "description": "Drop-in AI cost tracking for Node.js and TypeScript. Auto-instruments OpenAI, Anthropic, and Gemini at the class level, with zero code at each call site.",
+  "main": "costmeter.js",
+  "types": "costmeter.d.ts",
+  "files": [
+    "costmeter.js",
+    "costmeter.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "cost-tracking",
+    "openai",
+    "anthropic",
+    "gemini",
+    "observability",
+    "monitoring",
+    "express",
+    "middleware"
+  ],
+  "author": "",
+  "license": "MIT",
+  "homepage": "https://kalaa.cc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_ORG/kalaa-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_ORG/kalaa-node/issues"
+  },
+"dependencies": {
+    "music-metadata": "^7.0.0",
+    "node-fetch": "^2.7.0"
+  },
+  "peerDependencies": {
+    "openai": ">=4",
+    "@anthropic-ai/sdk": ">=0.20",
+    "@google/generative-ai": ">=0.10"
+  },
+  "peerDependenciesMeta": {
+    "openai": { "optional": true },
+    "@anthropic-ai/sdk": { "optional": true },
+    "@google/generative-ai": { "optional": true }
+  }
+}