@spendgraph/sdk 0.1.0 → 0.2.0

package/dist/track/track.d.ts

@@ -0,0 +1,209 @@
+export interface SpendGraphOptions {
+    /** spendgraph API key (sg_…). Without it the SDK is a no-op. */
+    apiKey: string | undefined;
+    /** Base URL of your deployed spendgraph app, e.g. https://costs.yourco.com */
+    baseUrl: string;
+    /** Flush at most this often (ms). Default 5000. */
+    flushIntervalMs?: number;
+    /** Flush when the buffer reaches this size. Default 20. */
+    maxBatch?: number;
+}
+export interface TrackEvent {
+    model: string;
+    /** Uncached input tokens — cache tokens go in the fields below. */
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt-cache read (hit) tokens, billed at the provider's cache-read rate. */
+    cacheReadTokens?: number;
+    /** Prompt-cache write (creation) tokens. */
+    cacheWriteTokens?: number;
+    /**
+     * Billed on their own by search-grounded providers — Perplexity Sonar Deep
+     * Research charges both at rates that are neither input nor output. Leave
+     * them unset for every other provider; OpenAI's `reasoning_tokens` are
+     * already counted inside `completion_tokens` and would be billed twice.
+     */
+    citationTokens?: number;
+    reasoningTokens?: number;
+    /**
+     * Client-side id: retried sends dedupe server-side.
+     * Must be 8–64 characters — shorter ids are rejected with a 422.
+     */
+    eventId?: string;
+    /** ISO timestamp; defaults to server receive time. */
+    timestamp?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Fire-and-forget token tracking. track() never throws and never blocks;
+ * events batch in memory and flush every 5s or 20 events. Network failures
+ * retry once, then drop with one console.warn — tracking can never break
+ * the host app.
+ */
+export declare class SpendGraph {
+    private readonly opts;
+    private queue;
+    private timer;
+    private warned;
+    /** Events lost in the current run of failures, reset by a successful flush. */
+    private dropped;
+    /** Unpriced model ids already reported, so each is named at most once. */
+    private readonly unpricedSeen;
+    private readonly interval;
+    private readonly maxBatch;
+    /** When the pending flush was scheduled, for the suspend check in track(). */
+    private timerAt;
+    private suspendWarned;
+    private noKeyWarned;
+    private streamUsageWarned;
+    /** The flush currently on the wire, so a later flush() can wait for it. */
+    private inFlight;
+    constructor(opts: SpendGraphOptions);
+    /**
+     * The package's client, given no retries of its own.
+     *
+     * The policy in `send` stays this class's: a flush is awaited inside
+     * serverless handlers, where blocking out a minute-long rate-limit window is
+     * worse than losing the batch, and the client's backoff would do exactly that.
+     */
+    private clientFor;
+    /** Record one LLM call. Synchronous, returns void, never throws. */
+    track(event: TrackEvent): void;
+    /**
+     * Says once that tracking is off.
+     *
+     * Running without a key stays a no-op on purpose — it keeps spendgraph out of
+     * tests and local runs without branching at every call site. But an unset
+     * SPENDGRAPH_API_KEY is indistinguishable from that choice, and it is the
+     * likeliest reason a fresh integration records nothing at all: the code is
+     * wired up correctly, the dashboard is empty, and nothing anywhere says why.
+     * Every other failure in this class warns once; this was the one that stayed
+     * quiet, which made it the hardest to find.
+     */
+    private warnNoKey;
+    /**
+     * Notices that the runtime froze with events still buffered.
+     *
+     * Serverless platforms suspend a function once it returns rather than
+     * exiting it, so neither the flush timer nor `beforeExit` ever runs and the
+     * queue is lost without a sound — the failure Langfuse documents for Lambda
+     * and Vercel. There is no reliable flag for "am I serverless", but there is
+     * direct evidence: a pending timer whose deadline passed long ago did not
+     * fire, which only happens if the runtime stopped executing between calls.
+     *
+     * Seeing that, send the stragglers now (they survive into this invocation)
+     * and say once what the fix is. Correct callers await flush(), which clears
+     * the timer, so this never fires for them.
+     */
+    private detectSuspendedRuntime;
+    /**
+     * Send everything buffered now. Call at the end of serverless handlers.
+     *
+     * Serialised against a flush already running, because this method is not the
+     * only thing that starts one: track() flushes by itself the moment the batch
+     * is full, and so do the timer, the suspend check and the exit hook. Those
+     * empty the queue synchronously, so an awaited flush() used to find nothing
+     * left to send and hand back an already-resolved promise while the real
+     * batch was still on the wire — and the next thing a serverless handler does
+     * after awaiting is return, freezing the runtime and losing exactly the
+     * events the await was there to save.
+     *
+     * The drain still starts synchronously — `drain()` runs as far as its first
+     * await before returning a promise, so the queue is taken during this call
+     * and not a microtask later. That ordering is load-bearing: the suspend
+     * check and the exit hook both fire a flush and then expect the buffer to be
+     * gone, and deferring it broke them.
+     */
+    flush(): Promise<void>;
+    /** One pass: stop the timer, take the queue, put it on the wire. */
+    private drain;
+    /**
+     * Wrap an Anthropic or OpenAI client. Use the wrapped client exactly as
+     * before — token usage is read off each response and tracked automatically.
+     *
+     * Streaming is covered too:
+     * - helper streams (`anthropic.messages.stream()`,
+     *   `openai.beta.chat.completions.stream()`) are tracked via their
+     *   final-message promise — the stream you get back is untouched;
+     * - raw streams (`create({ stream: true })`) are tee'd: you receive one
+     *   branch, usage is accumulated off the other. For OpenAI raw streams,
+     *   pass `stream_options: { include_usage: true }` or there is no usage
+     *   to read and the call goes untracked.
+     */
+    wrap<T extends object>(client: T): T;
+    /**
+     * The recursive wrapper behind wrap().
+     *
+     * Two things here are deliberate and were both wrong before.
+     *
+     * `Reflect.get` is called without a receiver, so a getter runs with the real
+     * client as `this`. Passing the proxy — the obvious reading of the Proxy
+     * docs — makes any getter that touches a `#private` field throw
+     * "Cannot read private member", and the provider SDKs this is built to wrap
+     * use private fields. That turned a tracking wrapper into a crash on a
+     * client that works perfectly well unwrapped, in an SDK whose whole contract
+     * is to fail open.
+     *
+     * And each wrapper is kept, so `client.messages` and `client.messages.create`
+     * are the same object and the same function every time they are read.
+     * Rebuilding them per access allocated a proxy and a closure on every call
+     * and quietly broke any caller that holds onto a method or compares
+     * identity. The cache is per proxy and keyed by property, so a method always
+     * applies to the object it was read from, and it re-wraps if the underlying
+     * value is ever replaced.
+     */
+    private proxy;
+    private observeResult;
+    private interceptStream;
+    /** Accumulate usage off a tee'd SSE branch (Anthropic events / OpenAI chunks). */
+    private consumeStream;
+    /**
+     * Says once that a streamed call went untracked.
+     *
+     * A raw OpenAI stream carries no usage unless the caller asks for it, so the
+     * accumulator above finishes with nothing to report and simply returns —
+     * correct, and completely silent. That is the same hole warnNoKey was added
+     * to close: the integration looks right, the dashboard stays empty for those
+     * calls, and nothing anywhere connects the two. Anthropic streams always
+     * carry usage, so in practice this names the one option that fixes it.
+     *
+     * Guarded on having seen at least one chunk, so an empty or aborted stream —
+     * where there was never anything to read — stays quiet.
+     */
+    private warnStreamNoUsage;
+    private trackFromResponse;
+    private send;
+    /**
+     * The drop policy, which is this class's rather than the client's.
+     *
+     * 429 is the one failure the server tells you how to fix: it sends
+     * retry-after, and the window is at most a minute wide, so a batch that
+     * arrived at the end of one is deliverable a second later. Dropping it
+     * immediately threw that away and reported the least useful thing it could —
+     * "ingest returned 429" — for the one status with a documented remedy. The
+     * wait is capped because flush() is awaited inside serverless handlers, where
+     * blocking for a minute is worse than losing the batch.
+     */
+    private onSendFailed;
+    /**
+     * Surfaces model ids the server could not price, once each.
+     *
+     * These are accepted and stored, so nothing here is an error — but they cost
+     * $0, and a dashboard reading $0 is indistinguishable from one reading
+     * "nothing happened". Naming the id in the integrator's own console is the
+     * cheapest possible moment to catch a typo or an unmapped model, and the
+     * per-id guard keeps a steady stream of the same unknown model from becoming
+     * log noise.
+     */
+    private reportUnpriced;
+    /**
+     * Warns once per outage, with a running count of what was lost.
+     *
+     * Warning on every flush would spam a hot loop, but warning exactly once per
+     * process — the previous behaviour — hid a server-side bug that failed every
+     * full batch: one line early in a long-lived process, then silence, while the
+     * dashboard quietly undercounted. The count is what makes the silence legible
+     * when someone does go looking.
+     */
+    private reportDropped;
+}