@spendgraph/sdk 0.5.0 → 0.6.0

package/dist/schema/validate/validate.js

@@ -1,92 +1 @@
-export class FieldValidationError extends Error {
-    errors;
-    constructor(errors) {
-        super(errors.map((e) => `${e.field}: ${e.message}`).join("; "));
-        this.name = "FieldValidationError";
-        this.errors = errors;
-    }
-}
-export function isMissing(value) {
-    return value === undefined || value === null;
-}
-export function toNumber(value) {
-    return typeof value === "number" ? value : Number(String(value).trim());
-}
-export function toBoolean(value) {
-    return typeof value === "boolean" ? value : String(value).toLowerCase() === "true";
-}
-function checkText(field, value) {
-    const text = String(value);
-    return field.maxLength !== undefined && text.length > field.maxLength
-        ? `is ${text.length} characters, over the limit of ${field.maxLength}`
-        : null;
-}
-function checkNumber(field, value) {
-    const n = toNumber(value);
-    if (!Number.isFinite(n))
-        return `expects a number, got ${JSON.stringify(value)}`;
-    if (field.min !== undefined && n < field.min)
-        return `is ${n}, below the minimum of ${field.min}`;
-    if (field.max !== undefined && n > field.max)
-        return `is ${n}, above the maximum of ${field.max}`;
-    return null;
-}
-function checkBoolean(value) {
-    if (typeof value === "boolean")
-        return null;
-    const s = String(value).toLowerCase();
-    return s === "true" || s === "false"
-        ? null
-        : `expects true or false, got ${JSON.stringify(value)}`;
-}
-function checkEnum(field, value) {
-    const options = field.options ?? [];
-    if (options.length === 0)
-        return "is an enum with no options declared";
-    return options.includes(String(value))
-        ? null
-        : `must be one of ${options.join(" | ")}, got ${JSON.stringify(value)}`;
-}
-function checkJson(value) {
-    try {
-        JSON.stringify(value);
-        return null;
-    }
-    catch (err) {
-        return `is not serialisable: ${err.message}`;
-    }
-}
-function checkOne(field, value) {
-    switch (field.type) {
-        case "string":
-        case "text":
-            return checkText(field, value);
-        case "number":
-            return checkNumber(field, value);
-        case "boolean":
-            return checkBoolean(value);
-        case "enum":
-            return checkEnum(field, value);
-        case "list":
-            return Array.isArray(value) ? null : `expects an array, got ${typeof value}`;
-        case "json":
-            return checkJson(value);
-    }
-}
-export function validateFields(values, spec) {
-    const errors = [];
-    for (const field of spec) {
-        const value = values[field.name];
-        if (isMissing(value)) {
-            if (field.default !== undefined)
-                continue;
-            if (field.required)
-                errors.push({ field: field.name, message: "is required" });
-            continue;
-        }
-        const problem = checkOne(field, value);
-        if (problem)
-            errors.push({ field: field.name, message: problem });
-    }
-    return errors;
-}
+class l extends Error{errors;constructor(e){super(e.map(t=>`${t.field}: ${t.message}`).join("; ")),this.name="FieldValidationError",this.errors=e}}function s(n){return n==null}function u(n){return typeof n=="number"?n:Number(String(n).trim())}function p(n){return typeof n=="boolean"?n:String(n).toLowerCase()==="true"}function c(n,e){const t=String(e);return n.maxLength!==void 0&&t.length>n.maxLength?`is ${t.length} characters, over the limit of ${n.maxLength}`:null}function a(n,e){const t=u(e);return Number.isFinite(t)?n.min!==void 0&&t<n.min?`is ${t}, below the minimum of ${n.min}`:n.max!==void 0&&t>n.max?`is ${t}, above the maximum of ${n.max}`:null:`expects a number, got ${JSON.stringify(e)}`}function m(n){if(typeof n=="boolean")return null;const e=String(n).toLowerCase();return e==="true"||e==="false"?null:`expects true or false, got ${JSON.stringify(n)}`}function f(n,e){const t=n.options??[];return t.length===0?"is an enum with no options declared":t.includes(String(e))?null:`must be one of ${t.join(" | ")}, got ${JSON.stringify(e)}`}function g(n){try{return JSON.stringify(n),null}catch(e){return`is not serialisable: ${e.message}`}}function h(n,e){switch(n.type){case"string":case"text":return c(n,e);case"number":return a(n,e);case"boolean":return m(e);case"enum":return f(n,e);case"list":return Array.isArray(e)?null:`expects an array, got ${typeof e}`;case"json":return g(e)}}function x(n,e){const t=[];for(const r of e){const o=n[r.name];if(s(o)){if(r.default!==void 0)continue;r.required&&t.push({field:r.name,message:"is required"});continue}const i=h(r,o);i&&t.push({field:r.name,message:i})}return t}export{l as FieldValidationError,s as isMissing,p as toBoolean,u as toNumber,x as validateFields};

package/dist/track/index.js

@@ -1 +1 @@
-export { SpendGraph } from "./track.js";
+import{SpendGraph as e}from"./track.js";export{e as SpendGraph};

package/dist/track/track.js

@@ -1,331 +1 @@
-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.`);
-    }
-}
+import{Client as g,SpendgraphError as k}from"../core/client/index.js";const y=2e3,l=new Set;let f=!1;function _(h){if(typeof process>"u"||typeof process.on!="function")return;const t=typeof WeakRef=="function"?new WeakRef(h):{deref:()=>h};l.add(t),!f&&(f=!0,process.on("beforeExit",()=>{for(const n of l){const e=n.deref();e?e.flush():l.delete(n)}}))}class b{opts;queue=[];timer=null;warned=!1;dropped=0;unpricedSeen=new Set;interval;maxBatch;timerAt=0;suspendWarned=!1;noKeyWarned=!1;streamUsageWarned=!1;inFlight=null;constructor(t){this.opts=t,this.interval=t.flushIntervalMs??5e3,this.maxBatch=t.maxBatch??20,_(this)}clientFor(t){return new g({apiKey:t,baseUrl:this.opts.baseUrl,attempts:1})}track(t){try{if(!this.opts.apiKey){this.warnNoKey();return}this.detectSuspendedRuntime(),this.queue.push(t),this.queue.length>=this.maxBatch?this.flush():this.timer||(this.timer=setTimeout(()=>void this.flush(),this.interval),this.timerAt=Date.now(),this.timer.unref?.())}catch{}}warnNoKey(){this.noKeyWarned||(this.noKeyWarned=!0,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(){this.timer&&(Date.now()-this.timerAt<=this.interval*2||(this.suspendWarned||(this.suspendWarned=!0,console.warn("spendgraph: a scheduled flush never ran \u2014 this runtime suspends between invocations, so buffered events are lost. Await meter.flush() before your handler returns.")),this.flush()))}async flush(){const t=this.inFlight,n=this.drain(),e=Promise.allSettled([t,n]).then(()=>{});this.inFlight=e;try{await e}finally{this.inFlight===e&&(this.inFlight=null)}}async drain(){this.timer&&(clearTimeout(this.timer),this.timer=null);const t=this.opts.apiKey;if(this.queue.length===0||!t)return;const n=this.queue.splice(0,this.queue.length);for(let e=0;e<n.length;e+=100)await this.send(n.slice(e,e+100),t)}wrap(t){return this.proxy(t)}proxy(t){const n=new Map;return new Proxy(t,{get:(e,s)=>{const r=Reflect.get(e,s);if(r===null||typeof r!="function"&&typeof r!="object")return r;const o=n.get(s);if(o&&o.from===r)return o.out;const c=typeof r=="function"?(...u)=>this.observeResult(r.apply(e,u),u):this.proxy(r);return n.set(s,{from:r,out:c}),c}})}observeResult(t,n){try{const e=t,s=typeof e?.finalMessage=="function"?e.finalMessage():typeof e?.finalChatCompletion=="function"?e.finalChatCompletion():null;if(s instanceof Promise)return s.then(r=>this.trackFromResponse(r),()=>{}),t;if(t instanceof Promise){if(!!n[0]?.stream)return t.then(o=>this.interceptStream(o));t.then(o=>this.trackFromResponse(o),()=>{})}}catch{}return t}interceptStream(t){try{const n=t;if(n&&typeof n.tee=="function"&&typeof n[Symbol.asyncIterator]=="function"){const[e,s]=n.tee();return this.consumeStream(e),s}this.trackFromResponse(t)}catch{}return t}async consumeStream(t){try{let n,e,s,r=0,o=0,c,u,p=!1;for await(const m of t){p=!0;const i=m;if(i?.type==="message_start"&&i.message){n=i.message.model??n;const a=i.message.usage??{};e=a.input_tokens??e,r=a.cache_read_input_tokens??0,o=a.cache_creation_input_tokens??0}else if(i?.type==="message_delta"&&i.usage)s=i.usage.output_tokens??s;else if(i?.object==="chat.completion.chunk"&&(n=i.model??n,i.usage)){const a=i.usage,d=a.prompt_tokens_details?.cached_tokens??0;e=Math.max(0,(a.prompt_tokens??0)-d),r=d,s=a.completion_tokens,c=a.citation_tokens,u=a.reasoning_tokens}}n&&typeof e=="number"&&typeof s=="number"?this.track({model:n,inputTokens:e,outputTokens:s,cacheReadTokens:r,cacheWriteTokens:o,citationTokens:c,reasoningTokens:u}):p&&this.warnStreamNoUsage()}catch{}}warnStreamNoUsage(){this.streamUsageWarned||(this.streamUsageWarned=!0,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(t){try{if(!t||typeof t!="object")return;const n=t;if(!n.usage||!n.model)return;const e=n.usage;if(typeof e.input_tokens=="number"&&typeof e.output_tokens=="number"){this.track({model:n.model,inputTokens:e.input_tokens,outputTokens:e.output_tokens,cacheReadTokens:e.cache_read_input_tokens??0,cacheWriteTokens:e.cache_creation_input_tokens??0});return}if(typeof e.prompt_tokens=="number"&&typeof e.completion_tokens=="number"){const s=e.prompt_tokens_details?.cached_tokens??0;this.track({model:n.model,inputTokens:Math.max(0,e.prompt_tokens-s),outputTokens:e.completion_tokens,cacheReadTokens:s,citationTokens:e.citation_tokens,reasoningTokens:e.reasoning_tokens})}}catch{}}async send(t,n,e=0){let s;try{s=await this.clientFor(n).post("/api/v1/ingest",{events:t})}catch(r){return this.onSendFailed(r,t,n,e)}this.warned=!1,this.dropped=0,this.reportUnpriced(s)}async onSendFailed(t,n,e,s){const r=t instanceof k?t:null;if(!r||r.status===0){if(s===0)return this.send(n,e,1);this.reportDropped(n.length,`unreachable (${String(t)})`);return}if(r.status>=500&&s===0)return this.send(n,e,1);if(r.status===429&&s===0){const o=r.retryAfterMs;if(o!==null&&o<=y)return await new Promise(c=>setTimeout(c,o)),this.send(n,e,1);this.reportDropped(n.length,o===null?"rate limited by ingest":`rate limited by ingest, clear in ${Math.ceil(o/1e3)}s`);return}this.reportDropped(n.length,`ingest returned ${r.status}`)}reportUnpriced(t){{const n=t;if(!Array.isArray(n?.unpricedModels))return;const e=n.unpricedModels.filter(s=>typeof s=="string").filter(s=>!this.unpricedSeen.has(s));if(e.length===0)return;for(const s of e)this.unpricedSeen.add(s);console.warn(`spendgraph: no price for ${e.map(s=>`"${s}"`).join(", ")}. These events are recorded but cost $0 until the model is in the catalog.`)}}reportDropped(t,n){this.dropped+=t,!this.warned&&(this.warned=!0,console.warn(`spendgraph: ${n}; dropped ${this.dropped} event(s). Further drops are counted but not logged until a flush succeeds.`))}}export{b as SpendGraph};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fnLog0/spendgraph.git",
@@ -36,14 +36,15 @@
     "./ai": {
       "types": "./dist/ai.d.ts",
       "import": "./dist/ai.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
     "test": "vitest run"
   },
   "devDependencies": {