llm-cost-meter 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.2.0 (2026-04-05)
+
+### Streaming Support
+
+- New `meterStream()` function — wraps streaming LLM calls, records cost after stream completes
+- Works with both OpenAI and Anthropic streaming responses
+- Extracts usage from stream object properties, final chunks, or accumulated message events
+- Records `status: 'error'` events if stream fails mid-way
+- `CostMeter.trackStream()` for instance-level streaming support
+
+### Express Middleware
+
+- New `createExpressMiddleware()` — drop-in Express middleware
+- Attaches `req.meter()` to every request with feature, userId, sessionId pre-filled
+- Custom `extractUserId` and `extractSessionId` functions for flexible auth patterns
+- Supports `env` and `tags` in middleware config
+- Per-call option overrides from route handlers
+
+### Dashboard
+
+- Live mode toggle — auto-refreshes every 5 seconds when enabled
+- Green pulsing indicator when live mode is active
+- Pauses polling when browser tab is hidden (Page Visibility API)
+- Persists live mode preference in localStorage
+
+### Testing
+
+- 128 tests (up from 110)
+- New streaming test suite (10 tests): chunk passthrough, OpenAI/Anthropic usage extraction, error handling, latency measurement
+- New middleware test suite (8 tests): req.meter attachment, user/session extraction, config overrides
+
+---
+
 ## 0.1.0 (2026-04-05)
 
 Initial release of llm-cost-meter.

package/README.md

@@ -78,6 +78,82 @@ By feature:
 Insight: 'chat' drives 53% of cost but only 24% of calls.
 ```
 
+## Streaming Support
+
+Track costs from streaming LLM responses. The stream is passed through unchanged — cost is recorded automatically when the stream ends.
+
+```typescript
+import { meterStream } from 'llm-cost-meter';
+
+// OpenAI streaming
+const stream = await meterStream(
+  () => openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Write a poem' }],
+    stream: true,
+    stream_options: { include_usage: true },
+  }),
+  { feature: 'chat', userId: 'user_123' }
+);
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
+// Cost event automatically recorded when stream ends
+
+// Anthropic streaming
+const stream = await meterStream(
+  () => anthropic.messages.stream({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'Write a poem' }],
+  }),
+  { feature: 'chat' }
+);
+
+for await (const event of stream) {
+  // handle events
+}
+```
+
+Works with both OpenAI and Anthropic streaming. Extracts usage from the stream object, final chunk, or accumulated message events. If the stream errors mid-way, a `status: 'error'` event is recorded.
+
+## Express Middleware
+
+Drop-in middleware that attaches `req.meter()` to every request:
+
+```typescript
+import { createExpressMiddleware, configure } from 'llm-cost-meter';
+
+configure({ adapters: ['console', 'local'] });
+
+// Attach to specific routes
+app.post('/api/chat',
+  createExpressMiddleware({ feature: 'chat' }),
+  async (req, res) => {
+    const response = await req.meter(() =>
+      client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: req.body.message }],
+      })
+    );
+    res.json(response);
+  }
+);
+
+// With custom user/session extraction
+app.use('/api', createExpressMiddleware({
+  feature: 'api',
+  extractUserId: (req) => req.headers['x-user-id'],
+  extractSessionId: (req) => req.cookies?.sid,
+  env: 'production',
+  tags: { team: 'backend' },
+}));
+```
+
+The middleware automatically fills in `feature`, `userId`, `sessionId`, `env`, and `tags` — your route handlers just call `req.meter()`.
+
 ## Tagging Guide
 
 Every `meter()` call accepts these tags:

package/dashboard/index.html

@@ -83,6 +83,7 @@
     .pill-openai { background: rgba(6,182,212,0.15); color: var(--cyan); }
     .pill-custom { background: rgba(139,92,246,0.15); color: #8b5cf6; }
 
+    @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.4; } }
     .footer { text-align: center; padding: 24px; font-size: 12px; color: var(--text-muted); }
     .loading { display: flex; align-items: center; justify-content: center; height: 60vh; font-size: 16px; color: var(--text-muted); }
     .empty-state { text-align: center; padding: 60px 20px; color: var(--text-muted); }
@@ -281,6 +282,11 @@
           </div>
           ${activeFilters ? `<div class="filter-sep"></div><button class="btn-outline btn" onclick="clearAllFilters()">Clear all</button>` : ''}
           ${activeFilters ? `<div style="display:flex;gap:6px;flex-wrap:wrap">${activeFilters}</div>` : ''}
+          <div style="margin-left:auto">
+            <button class="btn ${liveMode ? '' : 'btn-outline'}" onclick="toggleLive()" style="${liveMode ? 'background:var(--green)' : ''}">
+              ${liveMode ? '<span style="display:inline-block;width:8px;height:8px;background:white;border-radius:50%;margin-right:6px;animation:pulse 1.5s infinite"></span>Live' : 'Live'}
+            </button>
+          </div>
         </div>
 
         <div class="container">
@@ -528,17 +534,55 @@
     }
     function exportAllEventsJSON() { exportJSON(getFilteredEvents(), 'llm-cost-events.json'); }
 
-    // ── Load ──
-    fetch('/api/events')
-      .then(r => r.json())
-      .then(events => { allEvents = events; render(); })
-      .catch(() => {
-        document.getElementById('app').innerHTML = `
-          <div class="loading" style="flex-direction:column;gap:12px">
-            <div>Could not load events.</div>
-            <div style="font-size:13px">Make sure the server is running: <code>npm run dashboard</code></div>
-          </div>`;
-      });
+    // ── Live Mode ──
+    let liveMode = localStorage.getItem('llm-meter-live') === 'true';
+    let liveInterval = null;
+
+    function toggleLive() {
+      liveMode = !liveMode;
+      localStorage.setItem('llm-meter-live', String(liveMode));
+      if (liveMode) startPolling(); else stopPolling();
+      render();
+    }
+
+    function startPolling() {
+      stopPolling();
+      liveInterval = setInterval(() => {
+        if (document.hidden) return;
+        fetchEvents(true);
+      }, 5000);
+    }
+
+    function stopPolling() {
+      if (liveInterval) { clearInterval(liveInterval); liveInterval = null; }
+    }
+
+    function fetchEvents(silent) {
+      fetch('/api/events')
+        .then(r => r.json())
+        .then(events => {
+          if (silent && events.length === allEvents.length) return;
+          allEvents = events;
+          render();
+        })
+        .catch(() => {
+          if (!silent) {
+            document.getElementById('app').innerHTML = `
+              <div class="loading" style="flex-direction:column;gap:12px">
+                <div>Could not load events.</div>
+                <div style="font-size:13px">Make sure the server is running: <code>npm run dashboard</code></div>
+              </div>`;
+          }
+        });
+    }
+
+    document.addEventListener('visibilitychange', () => {
+      if (!document.hidden && liveMode) fetchEvents(true);
+    });
+
+    // ── Initial Load ──
+    fetchEvents(false);
+    if (liveMode) startPolling();
   </script>
 </body>
 </html>

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { MeterOptions, CostMeterConfig, GlobalConfig } from './types';
-export { CostEvent, MeterOptions, CostMeterConfig, CostAdapter, ModelPricing, PricingTable, SummaryRow, ReportOptions, GlobalConfig, ErrorHandler, MeterStats, } from './types';
+export { CostEvent, MeterOptions, CostMeterConfig, CostAdapter, ModelPricing, PricingTable, SummaryRow, ReportOptions, GlobalConfig, ErrorHandler, MeterStats, ExpressMiddlewareOptions, } from './types';
 export { calculateCost, getAvailableModels, getAllPricing, configurePricing, setPricingTable, removePricing, } from './pricing';
 export { ConsoleAdapter, LocalAdapter, createAdapter } from './adapters';
+export { createExpressMiddleware } from './middleware/express';
 /**
  * Configure the global llm-cost-meter settings.
  * Merges with current config. Use resetConfig() first for a clean slate.
@@ -61,5 +62,29 @@ export declare class CostMeter {
         tags?: Record<string, string>;
         latencyMs?: number;
     }): void;
+    /**
+     * Wrap a streaming LLM call. Passes through the stream unchanged
+     * and records cost after the stream completes.
+     */
+    trackStream<T extends AsyncIterable<any>>(fn: () => Promise<T>, options?: MeterOptions): Promise<T>;
     flush(): Promise<void>;
 }
+/**
+ * Wrap a streaming LLM API call to track cost and usage.
+ * Returns the stream unchanged — cost is recorded after the stream completes.
+ *
+ * Works with both OpenAI and Anthropic streaming responses.
+ *
+ * @example
+ * ```typescript
+ * const stream = await meterStream(
+ *   () => openai.chat.completions.create({ model: 'gpt-4o', messages: [...], stream: true }),
+ *   { feature: 'chat', userId: 'user_123' }
+ * );
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * // Cost event automatically recorded when stream ends
+ * ```
+ */
+export declare function meterStream<T extends AsyncIterable<any>>(fn: () => Promise<T>, options?: MeterOptions): Promise<T>;

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CostMeter = exports.createAdapter = exports.LocalAdapter = exports.ConsoleAdapter = exports.removePricing = exports.setPricingTable = exports.configurePricing = exports.getAllPricing = exports.getAvailableModels = exports.calculateCost = void 0;
+exports.CostMeter = exports.createExpressMiddleware = exports.createAdapter = exports.LocalAdapter = exports.ConsoleAdapter = exports.removePricing = exports.setPricingTable = exports.configurePricing = exports.getAllPricing = exports.getAvailableModels = exports.calculateCost = void 0;
 exports.configure = configure;
 exports.resetConfig = resetConfig;
 exports.getConfig = getConfig;
@@ -8,6 +8,7 @@ exports.getMeterStats = getMeterStats;
 exports.resetStats = resetStats;
 exports.meter = meter;
 exports.flush = flush;
+exports.meterStream = meterStream;
 const uuid_1 = require("uuid");
 const pricing_1 = require("./pricing");
 const adapters_1 = require("./adapters");
@@ -24,6 +25,9 @@ var adapters_2 = require("./adapters");
 Object.defineProperty(exports, "ConsoleAdapter", { enumerable: true, get: function () { return adapters_2.ConsoleAdapter; } });
 Object.defineProperty(exports, "LocalAdapter", { enumerable: true, get: function () { return adapters_2.LocalAdapter; } });
 Object.defineProperty(exports, "createAdapter", { enumerable: true, get: function () { return adapters_2.createAdapter; } });
+// Re-export middleware
+var express_1 = require("./middleware/express");
+Object.defineProperty(exports, "createExpressMiddleware", { enumerable: true, get: function () { return express_1.createExpressMiddleware; } });
 // ── Default config ──────────────────────────────────────────────
 const DEFAULT_CONFIG = {
     adapters: ['console'],
@@ -284,8 +288,182 @@ class CostMeter {
             stats.eventsDropped++;
         });
     }
+    /**
+     * Wrap a streaming LLM call. Passes through the stream unchanged
+     * and records cost after the stream completes.
+     */
+    async trackStream(fn, options = {}) {
+        const startTime = Date.now();
+        const stream = await fn();
+        const adapters = this.adapters;
+        const config = this.config;
+        return wrapStream(stream, startTime, options, adapters, config.defaultTags ?? {}, config.provider, config.onError, config.verbose);
+    }
     async flush() {
         await Promise.all(this.adapters.map((a) => (a.flush ? a.flush() : Promise.resolve())));
     }
 }
 exports.CostMeter = CostMeter;
+// ── Streaming Support ───────────────────────────────────────────
+/**
+ * Extract usage from a streaming response's accumulated state.
+ * Works with both OpenAI and Anthropic stream objects.
+ */
+function extractStreamUsage(streamObj, chunks) {
+    // OpenAI: stream objects often have .usage or finalUsage after iteration
+    if (streamObj?.usage?.prompt_tokens !== undefined) {
+        return {
+            provider: 'openai',
+            model: streamObj.model ?? 'unknown',
+            inputTokens: streamObj.usage.prompt_tokens,
+            outputTokens: streamObj.usage.completion_tokens ?? 0,
+        };
+    }
+    // Anthropic: stream objects accumulate a .message or .finalMessage with usage
+    if (streamObj?.message?.usage?.input_tokens !== undefined) {
+        return {
+            provider: 'anthropic',
+            model: streamObj.message.model ?? 'unknown',
+            inputTokens: streamObj.message.usage.input_tokens,
+            outputTokens: streamObj.message.usage.output_tokens ?? 0,
+        };
+    }
+    if (streamObj?.finalMessage?.usage?.input_tokens !== undefined) {
+        return {
+            provider: 'anthropic',
+            model: streamObj.finalMessage.model ?? 'unknown',
+            inputTokens: streamObj.finalMessage.usage.input_tokens,
+            outputTokens: streamObj.finalMessage.usage.output_tokens ?? 0,
+        };
+    }
+    // Fallback: scan chunks for usage data
+    let model = 'unknown';
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let provider = 'custom';
+    for (const chunk of chunks) {
+        if (chunk?.model)
+            model = chunk.model;
+        // OpenAI chunk with usage (last chunk when include_usage is set)
+        if (chunk?.usage?.prompt_tokens !== undefined) {
+            provider = 'openai';
+            inputTokens = chunk.usage.prompt_tokens;
+            outputTokens = chunk.usage.completion_tokens ?? 0;
+        }
+        // Anthropic message_start event
+        if (chunk?.type === 'message_start' && chunk?.message?.usage) {
+            provider = 'anthropic';
+            inputTokens = chunk.message.usage.input_tokens ?? 0;
+        }
+        // Anthropic message_delta event with usage
+        if (chunk?.type === 'message_delta' && chunk?.usage) {
+            provider = 'anthropic';
+            outputTokens = chunk.usage.output_tokens ?? 0;
+        }
+    }
+    return { provider, model, inputTokens, outputTokens };
+}
+function wrapStream(stream, startTime, options, adapters, defaultTags, providerHint, onError, verbose) {
+    const chunks = [];
+    const wrapped = {
+        [Symbol.asyncIterator]() {
+            const iterator = stream[Symbol.asyncIterator]();
+            return {
+                async next() {
+                    try {
+                        const result = await iterator.next();
+                        if (!result.done) {
+                            chunks.push(result.value);
+                        }
+                        if (result.done) {
+                            // Stream ended — record cost event
+                            const latencyMs = Date.now() - startTime;
+                            const usage = extractStreamUsage(stream, chunks);
+                            const provider = providerHint ?? usage.provider;
+                            const event = buildEvent(provider, usage.model, usage.inputTokens, usage.outputTokens, latencyMs, options, defaultTags);
+                            stats.eventsTracked++;
+                            dispatchEvent(event, adapters, options.awaitWrites ?? false, onError, verbose);
+                        }
+                        return result;
+                    }
+                    catch (error) {
+                        // Stream errored — record error event
+                        const latencyMs = Date.now() - startTime;
+                        const event = buildEvent(providerHint ?? 'custom', 'unknown', 0, 0, latencyMs, options, defaultTags, 'error', error instanceof Error ? error.message : String(error));
+                        stats.eventsTracked++;
+                        dispatchEvent(event, adapters, options.awaitWrites ?? false, onError, verbose);
+                        throw error;
+                    }
+                },
+                async return(value) {
+                    if (iterator.return)
+                        return iterator.return(value);
+                    return { done: true, value: undefined };
+                },
+                async throw(error) {
+                    if (iterator.throw)
+                        return iterator.throw(error);
+                    throw error;
+                },
+            };
+        },
+    };
+    // Copy over non-iterator properties from the original stream
+    // (e.g., OpenAI's .controller, .response, etc.)
+    const proto = Object.getOwnPropertyNames(stream).concat(Object.getOwnPropertyNames(Object.getPrototypeOf(stream) ?? {}));
+    for (const key of proto) {
+        if (key === 'constructor' || key === Symbol.asyncIterator.toString())
+            continue;
+        if (!(key in wrapped)) {
+            try {
+                const desc = Object.getOwnPropertyDescriptor(stream, key) ??
+                    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(stream), key);
+                if (desc) {
+                    Object.defineProperty(wrapped, key, {
+                        get: () => stream[key],
+                        enumerable: desc.enumerable,
+                        configurable: true,
+                    });
+                }
+            }
+            catch {
+                // Skip non-copyable properties
+            }
+        }
+    }
+    return wrapped;
+}
+/**
+ * Wrap a streaming LLM API call to track cost and usage.
+ * Returns the stream unchanged — cost is recorded after the stream completes.
+ *
+ * Works with both OpenAI and Anthropic streaming responses.
+ *
+ * @example
+ * ```typescript
+ * const stream = await meterStream(
+ *   () => openai.chat.completions.create({ model: 'gpt-4o', messages: [...], stream: true }),
+ *   { feature: 'chat', userId: 'user_123' }
+ * );
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * // Cost event automatically recorded when stream ends
+ * ```
+ */
+async function meterStream(fn, options = {}) {
+    const startTime = Date.now();
+    const adapters = getAdapters();
+    let stream;
+    try {
+        stream = await fn();
+    }
+    catch (error) {
+        const latencyMs = Date.now() - startTime;
+        const event = buildEvent('custom', 'unknown', 0, 0, latencyMs, options, globalConfig.defaultTags, 'error', error instanceof Error ? error.message : String(error));
+        stats.eventsTracked++;
+        dispatchEvent(event, adapters, options.awaitWrites ?? false, globalConfig.onError, globalConfig.verbose);
+        throw error;
+    }
+    return wrapStream(stream, startTime, options, adapters, globalConfig.defaultTags, undefined, globalConfig.onError, globalConfig.verbose);
+}

package/dist/middleware/express.d.ts

@@ -0,0 +1,18 @@
+import { ExpressMiddlewareOptions } from '../types';
+/**
+ * Creates Express middleware that attaches `req.meter()` and `req.meterStream()`
+ * to every request, pre-filled with feature, userId, and sessionId.
+ *
+ * @example
+ * ```typescript
+ * import { createExpressMiddleware } from 'llm-cost-meter';
+ *
+ * app.post('/api/chat', createExpressMiddleware({ feature: 'chat' }), async (req, res) => {
+ *   const response = await req.meter(() =>
+ *     client.messages.create({ model: 'claude-sonnet-4-20250514', ... })
+ *   );
+ *   res.json(response);
+ * });
+ * ```
+ */
+export declare function createExpressMiddleware(config: ExpressMiddlewareOptions): (req: any, _res: any, next: any) => void;

package/dist/middleware/express.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressMiddleware = createExpressMiddleware;
+const index_1 = require("../index");
+/**
+ * Creates Express middleware that attaches `req.meter()` and `req.meterStream()`
+ * to every request, pre-filled with feature, userId, and sessionId.
+ *
+ * @example
+ * ```typescript
+ * import { createExpressMiddleware } from 'llm-cost-meter';
+ *
+ * app.post('/api/chat', createExpressMiddleware({ feature: 'chat' }), async (req, res) => {
+ *   const response = await req.meter(() =>
+ *     client.messages.create({ model: 'claude-sonnet-4-20250514', ... })
+ *   );
+ *   res.json(response);
+ * });
+ * ```
+ */
+function createExpressMiddleware(config) {
+    return (req, _res, next) => {
+        const userId = config.extractUserId?.(req) ?? req.user?.id;
+        const sessionId = config.extractSessionId?.(req) ?? req.sessionID ?? req.sessionId;
+        req.meter = (fn, options = {}) => (0, index_1.meter)(fn, {
+            feature: config.feature,
+            userId,
+            sessionId,
+            env: config.env,
+            tags: config.tags,
+            ...options,
+        });
+        next();
+    };
+}

package/dist/types.d.ts

@@ -87,3 +87,10 @@ export interface MeterStats {
     adapterErrors: number;
     unknownModels: Set<string>;
 }
+export interface ExpressMiddlewareOptions {
+    feature: string;
+    extractUserId?: (req: any) => string | undefined;
+    extractSessionId?: (req: any) => string | undefined;
+    env?: string;
+    tags?: Record<string, string>;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cost-meter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Per-feature, per-user cost attribution and reporting for LLM API calls",
   "author": "shmulikdav",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/shmulikdav/llmeter.git"
+    "url": "https://github.com/shmulikdav/LLMeter.git"
   },
   "type": "commonjs",
   "engines": {