@spendgraph/sdk 0.1.0 → 0.2.1

package/dist/track/track.js

@@ -0,0 +1,331 @@
+import { Client, SpendgraphError } from "../core/client/index.js";
+const MAX_RETRY_WAIT_MS = 2_000;
+const liveMeters = new Set();
+let exitHookInstalled = false;
+function registerForExitFlush(meter) {
+    if (typeof process === "undefined" || typeof process.on !== "function")
+        return;
+    const ref = typeof WeakRef === "function"
+        ? new WeakRef(meter)
+        : { deref: () => meter };
+    liveMeters.add(ref);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("beforeExit", () => {
+        for (const r of liveMeters) {
+            const m = r.deref();
+            if (m)
+                void m.flush();
+            else
+                liveMeters.delete(r);
+        }
+    });
+}
+export class SpendGraph {
+    opts;
+    queue = [];
+    timer = null;
+    warned = false;
+    dropped = 0;
+    unpricedSeen = new Set();
+    interval;
+    maxBatch;
+    timerAt = 0;
+    suspendWarned = false;
+    noKeyWarned = false;
+    streamUsageWarned = false;
+    inFlight = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.interval = opts.flushIntervalMs ?? 5000;
+        this.maxBatch = opts.maxBatch ?? 20;
+        registerForExitFlush(this);
+    }
+    clientFor(apiKey) {
+        return new Client({ apiKey, baseUrl: this.opts.baseUrl, attempts: 1 });
+    }
+    track(event) {
+        try {
+            if (!this.opts.apiKey) {
+                this.warnNoKey();
+                return;
+            }
+            this.detectSuspendedRuntime();
+            this.queue.push(event);
+            if (this.queue.length >= this.maxBatch) {
+                void this.flush();
+            }
+            else if (!this.timer) {
+                this.timer = setTimeout(() => void this.flush(), this.interval);
+                this.timerAt = Date.now();
+                this.timer.unref?.();
+            }
+        }
+        catch {
+        }
+    }
+    warnNoKey() {
+        if (this.noKeyWarned)
+            return;
+        this.noKeyWarned = true;
+        console.warn("spendgraph: no apiKey set, so track() is recording nothing. Pass apiKey " +
+            "(usually from SPENDGRAPH_API_KEY) to start tracking, or ignore this if " +
+            "tracking is meant to be off here.");
+    }
+    detectSuspendedRuntime() {
+        if (!this.timer)
+            return;
+        if (Date.now() - this.timerAt <= this.interval * 2)
+            return;
+        if (!this.suspendWarned) {
+            this.suspendWarned = true;
+            console.warn("spendgraph: a scheduled flush never ran — this runtime suspends between " +
+                "invocations, so buffered events are lost. Await meter.flush() before " +
+                "your handler returns.");
+        }
+        void this.flush();
+    }
+    async flush() {
+        const prev = this.inFlight;
+        const mine = this.drain();
+        const run = Promise.allSettled([prev, mine]).then(() => undefined);
+        this.inFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.inFlight === run)
+                this.inFlight = null;
+        }
+    }
+    async drain() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const apiKey = this.opts.apiKey;
+        if (this.queue.length === 0 || !apiKey)
+            return;
+        const events = this.queue.splice(0, this.queue.length);
+        for (let i = 0; i < events.length; i += 100) {
+            await this.send(events.slice(i, i + 100), apiKey);
+        }
+    }
+    wrap(client) {
+        return this.proxy(client);
+    }
+    proxy(target) {
+        const cache = new Map();
+        return new Proxy(target, {
+            get: (obj, prop) => {
+                const value = Reflect.get(obj, prop);
+                if (value === null || (typeof value !== "function" && typeof value !== "object")) {
+                    return value;
+                }
+                const hit = cache.get(prop);
+                if (hit && hit.from === value)
+                    return hit.out;
+                const out = typeof value === "function"
+                    ? (...args) => this.observeResult(value.apply(obj, args), args)
+                    : this.proxy(value);
+                cache.set(prop, { from: value, out });
+                return out;
+            },
+        });
+    }
+    observeResult(result, args) {
+        try {
+            const helper = result;
+            const final = typeof helper?.finalMessage === "function"
+                ? helper.finalMessage()
+                : typeof helper?.finalChatCompletion === "function"
+                    ? helper.finalChatCompletion()
+                    : null;
+            if (final instanceof Promise) {
+                final.then((m) => this.trackFromResponse(m), () => { });
+                return result;
+            }
+            if (result instanceof Promise) {
+                const wantsStream = !!args[0]?.stream;
+                if (wantsStream) {
+                    return result.then((v) => this.interceptStream(v));
+                }
+                result.then((v) => this.trackFromResponse(v), () => { });
+            }
+        }
+        catch {
+        }
+        return result;
+    }
+    interceptStream(v) {
+        try {
+            const s = v;
+            if (s && typeof s.tee === "function" && typeof s[Symbol.asyncIterator] === "function") {
+                const [mine, theirs] = s.tee();
+                void this.consumeStream(mine);
+                return theirs;
+            }
+            this.trackFromResponse(v);
+        }
+        catch {
+        }
+        return v;
+    }
+    async consumeStream(iter) {
+        try {
+            let model;
+            let inputTokens;
+            let outputTokens;
+            let cacheReadTokens = 0;
+            let cacheWriteTokens = 0;
+            let citationTokens;
+            let reasoningTokens;
+            let sawChunk = false;
+            for await (const raw of iter) {
+                sawChunk = true;
+                const ev = raw;
+                if (ev?.type === "message_start" && ev.message) {
+                    model = ev.message.model ?? model;
+                    const u = ev.message.usage ?? {};
+                    inputTokens = u.input_tokens ?? inputTokens;
+                    cacheReadTokens = u.cache_read_input_tokens ?? 0;
+                    cacheWriteTokens = u.cache_creation_input_tokens ?? 0;
+                }
+                else if (ev?.type === "message_delta" && ev.usage) {
+                    outputTokens = ev.usage.output_tokens ?? outputTokens;
+                }
+                else if (ev?.object === "chat.completion.chunk") {
+                    model = ev.model ?? model;
+                    if (ev.usage) {
+                        const u = ev.usage;
+                        const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+                        inputTokens = Math.max(0, (u.prompt_tokens ?? 0) - cached);
+                        cacheReadTokens = cached;
+                        outputTokens = u.completion_tokens;
+                        citationTokens = u.citation_tokens;
+                        reasoningTokens = u.reasoning_tokens;
+                    }
+                }
+            }
+            if (model && typeof inputTokens === "number" && typeof outputTokens === "number") {
+                this.track({
+                    model,
+                    inputTokens,
+                    outputTokens,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                    citationTokens,
+                    reasoningTokens,
+                });
+            }
+            else if (sawChunk) {
+                this.warnStreamNoUsage();
+            }
+        }
+        catch {
+        }
+    }
+    warnStreamNoUsage() {
+        if (this.streamUsageWarned)
+            return;
+        this.streamUsageWarned = true;
+        console.warn("spendgraph: a streamed response carried no token usage, so that call " +
+            "was not tracked. For OpenAI raw streams pass " +
+            "stream_options: { include_usage: true }. Further untracked streams " +
+            "are not logged.");
+    }
+    trackFromResponse(res) {
+        try {
+            if (!res || typeof res !== "object")
+                return;
+            const r = res;
+            if (!r.usage || !r.model)
+                return;
+            const u = r.usage;
+            if (typeof u.input_tokens === "number" && typeof u.output_tokens === "number") {
+                this.track({
+                    model: r.model,
+                    inputTokens: u.input_tokens,
+                    outputTokens: u.output_tokens,
+                    cacheReadTokens: u.cache_read_input_tokens ?? 0,
+                    cacheWriteTokens: u.cache_creation_input_tokens ?? 0,
+                });
+                return;
+            }
+            if (typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number") {
+                const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+                this.track({
+                    model: r.model,
+                    inputTokens: Math.max(0, u.prompt_tokens - cached),
+                    outputTokens: u.completion_tokens,
+                    cacheReadTokens: cached,
+                    citationTokens: u.citation_tokens,
+                    reasoningTokens: u.reasoning_tokens,
+                });
+            }
+        }
+        catch {
+        }
+    }
+    async send(events, apiKey, attempt = 0) {
+        let body;
+        try {
+            body = await this.clientFor(apiKey).post("/api/v1/ingest", { events });
+        }
+        catch (err) {
+            return this.onSendFailed(err, events, apiKey, attempt);
+        }
+        this.warned = false;
+        this.dropped = 0;
+        this.reportUnpriced(body);
+    }
+    async onSendFailed(err, events, apiKey, attempt) {
+        const failure = err instanceof SpendgraphError ? err : null;
+        if (!failure || failure.status === 0) {
+            if (attempt === 0)
+                return this.send(events, apiKey, 1);
+            this.reportDropped(events.length, `unreachable (${String(err)})`);
+            return;
+        }
+        if (failure.status >= 500 && attempt === 0) {
+            return this.send(events, apiKey, 1);
+        }
+        if (failure.status === 429 && attempt === 0) {
+            const waitMs = failure.retryAfterMs;
+            if (waitMs !== null && waitMs <= MAX_RETRY_WAIT_MS) {
+                await new Promise((r) => setTimeout(r, waitMs));
+                return this.send(events, apiKey, 1);
+            }
+            this.reportDropped(events.length, waitMs === null
+                ? "rate limited by ingest"
+                : `rate limited by ingest, clear in ${Math.ceil(waitMs / 1000)}s`);
+            return;
+        }
+        this.reportDropped(events.length, `ingest returned ${failure.status}`);
+    }
+    reportUnpriced(body) {
+        {
+            const parsed = body;
+            if (!Array.isArray(parsed?.unpricedModels))
+                return;
+            const fresh = parsed.unpricedModels
+                .filter((m) => typeof m === "string")
+                .filter((m) => !this.unpricedSeen.has(m));
+            if (fresh.length === 0)
+                return;
+            for (const m of fresh)
+                this.unpricedSeen.add(m);
+            console.warn(`spendgraph: no price for ${fresh.map((m) => `"${m}"`).join(", ")}. ` +
+                `These events are recorded but cost $0 until the model is in the catalog.`);
+        }
+    }
+    reportDropped(count, reason) {
+        this.dropped += count;
+        if (this.warned)
+            return;
+        this.warned = true;
+        console.warn(`spendgraph: ${reason}; dropped ${this.dropped} event(s). ` +
+            `Further drops are counted but not logged until a flush succeeds.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
+    "test": "vitest run"
   },
   "devDependencies": {
     "typescript": "^5"