@cockpitify/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cockpitify
+
+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,65 @@
+# @cockpitify/node
+
+Records each user's AI token usage to `ops.usage` in your own Supabase project. Wrap your AI client once per request; the wrapped client behaves exactly like the original.
+
+```ts
+import OpenAI from 'npm:openai';
+import { Ops } from 'npm:@cockpitify/node';
+
+const ai = Ops.wrap(new OpenAI({ baseURL: 'https://api.deepseek.com', apiKey }), {
+  userId: user.id,
+  supabase, // service-role client; writes to ops.usage
+});
+```
+
+## Supported clients
+
+- **OpenAI SDK and compatibles** (DeepSeek, Groq, OpenRouter via `baseURL`)
+  - `chat.completions.create` (streaming or not)
+  - `chat.completions.stream()`
+  - `responses.create`
+- **Anthropic SDK**
+  - `messages.create` (streaming or not)
+  - `messages.stream()`
+  - the same two under `beta.messages`
+- **Raw HTTP:** `Ops.wrapFetch(fetch, opts)`. Handles OpenAI-compatible chat, Responses and Anthropic, both JSON and SSE.
+- **Vercel AI SDK:** `wrapLanguageModel({ model, middleware: Ops.middleware(opts) })`.
+
+## Calls not measured in tokens
+
+Speech-to-text, text-to-speech or image calls are recorded by hand (ops 0.17.0+):
+
+```ts
+Ops.record({ userId, supabase, provider: 'groq', model: 'whisper-large-v3', units: 742, unit: 'seconds' });
+Ops.record({ userId, supabase, provider: 'elevenlabs', model: 'eleven_multilingual_v2', units: 48000, unit: 'characters', costUsd: 0.36 });
+```
+
+Without `costUsd` the row stays unpriced: ops shows the amount, not a guessed cost.
+
+## Streaming
+
+Streaming is fully supported, and chunks reach your code unchanged and without delay.
+
+- **OpenAI-compatible streams** only report usage when `stream_options.include_usage` is set, so it is added for you.
+  - The extra usage-only chunk it produces is hidden from your code, unless you asked for it yourself.
+  - Groq is the exception: it reports usage on its own, so its requests are left untouched.
+- **If a stream is cut** (user left, `break`, abort, network error), there is no usage report from the provider. Tokens are then estimated from the prompt and the text seen so far, and the row is stored with `estimated = true`.
+
+## Guarantees
+
+- **Fail-open.** A recording failure never throws into your code or slows the AI call. It goes to `onError`, which by default logs one warning.
+- **Writes outlive the response.** On Supabase Edge Functions, writes run through `EdgeRuntime.waitUntil`. Elsewhere, call `await Ops.flush()` before the process exits.
+- **Setup mistakes fail loudly.** A missing `userId`, or neither `supabase` nor `sink` given, throws at wrap time.
+
+## Options
+
+| Option | |
+|---|---|
+| `userId` | Required. The end user to attribute usage to. |
+| `supabase` / `sink` | Where rows go: `ops.usage` through a supabase-js client, or your own `(row) => Promise`. |
+| `feature` | Optional tag, e.g. `'chat'`, `'transcribe'`. |
+| `prices` | USD per 1M tokens per model (prefix match). Without it `cost_usd` is null and the database prices the row. |
+| `provider` | Overrides the provider inferred from `baseURL` / URL. |
+| `injectStreamUsage` | Set `false` to never touch `stream_options`. |
+| `onError` | Receives recording errors. |
+

package/dist/accumulator.d.ts

@@ -0,0 +1,18 @@
+export declare class UsageAccumulator {
+    model: string;
+    input: number;
+    output: number;
+    cached: number;
+    cacheWrite: number;
+    /** Provider reported its final usage numbers. */
+    final: boolean;
+    /** Generated text seen so far, used to estimate output tokens when `final` never arrives. */
+    text: string;
+    feed(ev: unknown): void;
+    private setOpenAI;
+    private setAnthropic;
+}
+/** Rough token count (~4 characters per token). Only used when the provider never reports usage. */
+export declare function estimateTokens(text: string): number;
+/** The prompt part of a request body, as text, for estimating input tokens. */
+export declare function promptText(params: unknown): string;

package/dist/accumulator.js

@@ -0,0 +1,128 @@
+// Reads usage out of every response and stream-event shape we support, so each wrapper
+// (OpenAI SDK, Anthropic SDK, raw fetch) only has to feed it objects.
+//
+//   OpenAI-compatible chat (OpenAI, DeepSeek, OpenRouter): `usage` on the final chunk, only when
+//     `stream_options.include_usage` is set; that chunk has `choices: []`.
+//   Groq: `x_groq.usage` on the final chunk.
+//   OpenAI Responses: `response.completed` event carries `response.usage`.
+//   Anthropic: `message_start` has input usage, `message_delta` has cumulative output usage.
+export class UsageAccumulator {
+    model = '';
+    input = 0;
+    output = 0;
+    cached = 0;
+    cacheWrite = 0;
+    /** Provider reported its final usage numbers. */
+    final = false;
+    /** Generated text seen so far, used to estimate output tokens when `final` never arrives. */
+    text = '';
+    feed(ev) {
+        if (!ev || typeof ev !== 'object')
+            return;
+        const e = ev;
+        if (typeof e.model === 'string' && !this.model)
+            this.model = e.model;
+        // OpenAI-compatible chat completion (whole response or stream chunk).
+        if (Array.isArray(e.choices)) {
+            for (const c of e.choices) {
+                const d = c?.delta ?? c?.message;
+                if (typeof d?.content === 'string')
+                    this.text += d.content;
+                if (Array.isArray(d?.tool_calls)) {
+                    for (const t of d.tool_calls)
+                        if (typeof t?.function?.arguments === 'string')
+                            this.text += t.function.arguments;
+                }
+            }
+            const u = e.usage ?? e.x_groq?.usage;
+            if (u)
+                this.setOpenAI(u);
+            return;
+        }
+        // OpenAI Responses, non-streaming.
+        if (e.object === 'response') {
+            if (e.usage)
+                this.setOpenAI(e.usage);
+            return;
+        }
+        switch (e.type) {
+            // Anthropic, non-streaming.
+            case 'message':
+                if (e.usage) {
+                    this.setAnthropic(e.usage);
+                    this.final = true;
+                }
+                break;
+            case 'message_start':
+                if (typeof e.message?.model === 'string')
+                    this.model ||= e.message.model;
+                if (e.message?.usage)
+                    this.setAnthropic(e.message.usage);
+                break;
+            case 'message_delta':
+                if (e.usage) {
+                    // Cumulative totals. Newer API versions also repeat input fields here; keep earlier
+                    // cache numbers when a field is absent.
+                    const u = e.usage;
+                    if (typeof u.output_tokens === 'number')
+                        this.output = u.output_tokens;
+                    if (typeof u.input_tokens === 'number') {
+                        const read = typeof u.cache_read_input_tokens === 'number' ? u.cache_read_input_tokens : this.cached;
+                        const write = typeof u.cache_creation_input_tokens === 'number' ? u.cache_creation_input_tokens : this.cacheWrite;
+                        this.input = u.input_tokens + read + write;
+                        this.cached = read;
+                        this.cacheWrite = write;
+                    }
+                    this.final = true;
+                }
+                break;
+            case 'content_block_delta':
+                if (typeof e.delta?.text === 'string')
+                    this.text += e.delta.text;
+                else if (typeof e.delta?.partial_json === 'string')
+                    this.text += e.delta.partial_json;
+                break;
+            // OpenAI Responses, streaming.
+            case 'response.output_text.delta':
+                if (typeof e.delta === 'string')
+                    this.text += e.delta;
+                break;
+            case 'response.completed':
+            case 'response.incomplete':
+                if (typeof e.response?.model === 'string')
+                    this.model ||= e.response.model;
+                if (e.response?.usage)
+                    this.setOpenAI(e.response.usage);
+                break;
+        }
+    }
+    setOpenAI(u) {
+        this.input = num(u.prompt_tokens ?? u.input_tokens);
+        this.output = num(u.completion_tokens ?? u.output_tokens);
+        this.cached = num(u.prompt_tokens_details?.cached_tokens ?? u.input_tokens_details?.cached_tokens ?? u.prompt_cache_hit_tokens);
+        this.final = true;
+    }
+    setAnthropic(u) {
+        const read = num(u.cache_read_input_tokens);
+        const write = num(u.cache_creation_input_tokens);
+        this.input = num(u.input_tokens) + read + write;
+        this.cached = read;
+        this.cacheWrite = write;
+        this.output = num(u.output_tokens);
+    }
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+/** Rough token count (~4 characters per token). Only used when the provider never reports usage. */
+export function estimateTokens(text) {
+    return text ? Math.ceil(text.length / 4) : 0;
+}
+/** The prompt part of a request body, as text, for estimating input tokens. */
+export function promptText(params) {
+    if (!params || typeof params !== 'object')
+        return '';
+    const p = params;
+    const parts = [p.system, p.instructions, p.messages, p.input, p.prompt].filter((x) => x != null);
+    return parts.map((x) => (typeof x === 'string' ? x : JSON.stringify(x))).join('\n');
+}

package/dist/ai-sdk.d.ts

@@ -0,0 +1,28 @@
+import type { WrapOptions } from './types.js';
+interface ModelLike {
+    modelId?: string;
+    provider?: string;
+}
+interface GenerateArgs {
+    doGenerate: () => Promise<any>;
+    params: unknown;
+    model?: ModelLike;
+}
+interface StreamArgs {
+    doStream: () => Promise<{
+        stream: ReadableStream<any>;
+    } & Record<string, any>>;
+    params: unknown;
+    model?: ModelLike;
+}
+/**
+ * Vercel AI SDK language model middleware:
+ * `wrapLanguageModel({ model, middleware: Ops.middleware({ userId, supabase }) })`.
+ */
+export declare function opsMiddleware(opts: WrapOptions): {
+    wrapGenerate({ doGenerate, params, model }: GenerateArgs): Promise<any>;
+    wrapStream({ doStream, params, model }: StreamArgs): Promise<{
+        stream: ReadableStream<any>;
+    }>;
+};
+export {};

package/dist/ai-sdk.js

@@ -0,0 +1,49 @@
+import { UsageAccumulator } from "./accumulator.js";
+import { createRecorder } from "./recorder.js";
+import { tapReadable } from "./stream.js";
+/**
+ * Vercel AI SDK language model middleware:
+ * `wrapLanguageModel({ model, middleware: Ops.middleware({ userId, supabase }) })`.
+ */
+export function opsMiddleware(opts) {
+    const record = createRecorder(opts);
+    const providerOf = (m) => opts.provider ?? (m?.provider ?? 'ai-sdk').split('.')[0];
+    return {
+        async wrapGenerate({ doGenerate, params, model }) {
+            const startedAt = Date.now();
+            const result = await doGenerate();
+            const acc = new UsageAccumulator();
+            acc.model = model?.modelId ?? '';
+            applyUsage(acc, result?.usage);
+            record({ acc, provider: providerOf(model), operation: 'ai-sdk', params, streamed: false, aborted: false, startedAt });
+            return result;
+        },
+        async wrapStream({ doStream, params, model }) {
+            const startedAt = Date.now();
+            const result = await doStream();
+            const acc = new UsageAccumulator();
+            acc.model = model?.modelId ?? '';
+            const stream = tapReadable(result.stream, {
+                onItem(part) {
+                    if (part?.type === 'text-delta')
+                        acc.text += part.delta ?? part.textDelta ?? '';
+                    if (part?.type === 'finish')
+                        applyUsage(acc, part.usage);
+                    return true;
+                },
+                onDone: (aborted) => record({ acc, provider: providerOf(model), operation: 'ai-sdk', params, streamed: true, aborted, startedAt }),
+            });
+            return { ...result, stream };
+        },
+    };
+}
+/** AI SDK usage: numbers (`inputTokens`) or, in newer versions, objects with a `total`. */
+function applyUsage(acc, u) {
+    if (!u)
+        return;
+    const n = (x) => (typeof x === 'number' ? x : typeof x?.total === 'number' ? x.total : 0);
+    acc.input = n(u.inputTokens ?? u.promptTokens);
+    acc.output = n(u.outputTokens ?? u.completionTokens);
+    acc.cached = typeof u.cachedInputTokens === 'number' ? u.cachedInputTokens : n(u.inputTokens?.cacheRead);
+    acc.final = true;
+}

package/dist/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { WrapOptions } from './types.js';
+export declare function wrapAnthropic<C extends object>(client: C, opts: WrapOptions): C;

package/dist/anthropic.js

@@ -0,0 +1,38 @@
+import { UsageAccumulator } from "./accumulator.js";
+import { listenHelperStream, mapApiPromise, proxyMethods } from "./proxy.js";
+import { createRecorder } from "./recorder.js";
+import { tapSdkStream } from "./stream.js";
+export function wrapAnthropic(client, opts) {
+    const record = createRecorder(opts);
+    const provider = opts.provider ?? 'anthropic';
+    const create = (orig) => (params, reqOpts) => messagesCreate(orig, params, reqOpts, record, provider);
+    const stream = (orig) => (params, reqOpts) => {
+        const startedAt = Date.now();
+        const acc = new UsageAccumulator();
+        const s = orig(params, reqOpts);
+        listenHelperStream(s, 'streamEvent', (ev) => acc.feed(ev), (aborted) => record({ acc, provider, operation: 'messages', params, streamed: true, aborted, startedAt }));
+        return s;
+    };
+    return proxyMethods(client, {
+        'messages.create': create,
+        'messages.stream': stream,
+        'beta.messages.create': create,
+        'beta.messages.stream': stream,
+    });
+}
+function messagesCreate(orig, params, reqOpts, record, provider) {
+    const startedAt = Date.now();
+    const acc = new UsageAccumulator();
+    const done = (aborted, streamed) => record({ acc, provider, operation: 'messages', params, streamed, aborted, startedAt });
+    if (!params?.stream) {
+        return mapApiPromise(orig(params, reqOpts), (res) => {
+            acc.feed(res);
+            done(false, false);
+            return res;
+        });
+    }
+    return mapApiPromise(orig(params, reqOpts), (s) => tapSdkStream(s, {
+        onItem: (ev) => (acc.feed(ev), true),
+        onDone: (aborted) => done(aborted, true),
+    }));
+}

package/dist/fetch.d.ts

@@ -0,0 +1,6 @@
+import type { WrapOptions } from './types.js';
+/**
+ * Wraps `fetch` for apps that call model APIs over raw HTTP. Understands OpenAI-compatible chat,
+ * OpenAI Responses and Anthropic Messages, both JSON and SSE.
+ */
+export declare function wrapFetch(fetchImpl: typeof fetch, opts: WrapOptions): typeof fetch;

package/dist/fetch.js

@@ -0,0 +1,76 @@
+import { UsageAccumulator } from "./accumulator.js";
+import { inferProvider, isUsageOnlyChunk, shouldInjectUsage } from "./proxy.js";
+import { background, createRecorder } from "./recorder.js";
+import { tapSse } from "./stream.js";
+/**
+ * Wraps `fetch` for apps that call model APIs over raw HTTP. Understands OpenAI-compatible chat,
+ * OpenAI Responses and Anthropic Messages, both JSON and SSE.
+ */
+export function wrapFetch(fetchImpl, opts) {
+    const record = createRecorder(opts);
+    return async (input, init) => {
+        const startedAt = Date.now();
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const provider = opts.provider ?? inferProvider(url, 'unknown');
+        let params;
+        let callerAskedUsage = true;
+        let sentInit = init;
+        try {
+            if (typeof init?.body === 'string') {
+                params = JSON.parse(init.body);
+                if (params?.stream === true && /\/chat\/completions/.test(url) && shouldInjectUsage(opts, provider)) {
+                    callerAskedUsage = params.stream_options?.include_usage === true;
+                    if (!callerAskedUsage) {
+                        const body = { ...params, stream_options: { ...params.stream_options, include_usage: true } };
+                        sentInit = { ...init, body: JSON.stringify(body) };
+                    }
+                }
+            }
+        }
+        catch {
+            params = undefined;
+            sentInit = init;
+        }
+        const res = await fetchImpl(input, sentInit);
+        try {
+            if (!res.ok || !res.body)
+                return res;
+            const acc = new UsageAccumulator();
+            const done = (aborted, streamed) => record({ acc, provider, operation: 'fetch', params, streamed, aborted, startedAt });
+            const type = res.headers.get('content-type') ?? '';
+            if (type.includes('text/event-stream')) {
+                const body = tapSse(res.body, {
+                    onItem(ev) {
+                        if (!ev.data || ev.data === '[DONE]')
+                            return true;
+                        let obj;
+                        try {
+                            obj = JSON.parse(ev.data);
+                        }
+                        catch {
+                            return true;
+                        }
+                        acc.feed(obj);
+                        return callerAskedUsage || !isUsageOnlyChunk(obj);
+                    },
+                    onDone: (aborted) => done(aborted, true),
+                });
+                return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+            }
+            if (type.includes('json')) {
+                background(res
+                    .clone()
+                    .json()
+                    .then((obj) => {
+                    acc.feed(obj);
+                    done(false, false);
+                })
+                    .catch(() => { }));
+            }
+            return res;
+        }
+        catch {
+            return res;
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { opsMiddleware } from './ai-sdk.js';
+import { wrapAnthropic } from './anthropic.js';
+import { wrapFetch } from './fetch.js';
+import { wrapOpenAI } from './openai.js';
+import { flush } from './recorder.js';
+import { record } from './record.js';
+import type { WrapOptions } from './types.js';
+/**
+ * Wraps an OpenAI(-compatible) or Anthropic SDK client so every call records the user's token usage
+ * to `ops.usage`. The returned client behaves exactly like the original.
+ */
+export declare function wrap<C extends object>(client: C, opts: WrapOptions): C;
+export declare const Ops: {
+    wrap: typeof wrap;
+    wrapOpenAI: typeof wrapOpenAI;
+    wrapAnthropic: typeof wrapAnthropic;
+    wrapFetch: typeof wrapFetch;
+    middleware: typeof opsMiddleware;
+    record: typeof record;
+    flush: typeof flush;
+};
+export { flush, opsMiddleware, record, wrapAnthropic, wrapFetch, wrapOpenAI };
+export type { RecordOptions } from './record.js';
+export { cost } from './recorder.js';
+export type { Prices, Sink, SupabaseLike, UsageRow, WrapOptions } from './types.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+import { opsMiddleware } from "./ai-sdk.js";
+import { wrapAnthropic } from "./anthropic.js";
+import { wrapFetch } from "./fetch.js";
+import { wrapOpenAI } from "./openai.js";
+import { flush } from "./recorder.js";
+import { record } from "./record.js";
+/**
+ * Wraps an OpenAI(-compatible) or Anthropic SDK client so every call records the user's token usage
+ * to `ops.usage`. The returned client behaves exactly like the original.
+ */
+export function wrap(client, opts) {
+    const c = client;
+    if (c?.chat?.completions || c?.responses)
+        return wrapOpenAI(client, opts);
+    if (c?.messages)
+        return wrapAnthropic(client, opts);
+    throw new TypeError('@cockpitify/node: unsupported client. Use Ops.wrapFetch() or Ops.middleware() instead.');
+}
+export const Ops = { wrap, wrapOpenAI, wrapAnthropic, wrapFetch, middleware: opsMiddleware, record, flush };
+export { flush, opsMiddleware, record, wrapAnthropic, wrapFetch, wrapOpenAI };
+export { cost } from "./recorder.js";

package/dist/openai.d.ts

@@ -0,0 +1,3 @@
+import type { WrapOptions } from './types.js';
+/** Works for OpenAI and OpenAI-compatible clients (DeepSeek, Groq, OpenRouter via `baseURL`). */
+export declare function wrapOpenAI<C extends object>(client: C, opts: WrapOptions): C;

package/dist/openai.js

@@ -0,0 +1,64 @@
+import { UsageAccumulator } from "./accumulator.js";
+import { inferProvider, isUsageOnlyChunk, listenHelperStream, mapApiPromise, proxyMethods, shouldInjectUsage, } from "./proxy.js";
+import { createRecorder } from "./recorder.js";
+import { tapSdkStream } from "./stream.js";
+/** Works for OpenAI and OpenAI-compatible clients (DeepSeek, Groq, OpenRouter via `baseURL`). */
+export function wrapOpenAI(client, opts) {
+    const record = createRecorder(opts);
+    const provider = opts.provider ?? inferProvider(client.baseURL, 'openai');
+    const inject = shouldInjectUsage(opts, provider);
+    return proxyMethods(client, {
+        'chat.completions.create': (orig) => (params, reqOpts) => chatCreate(orig, params, reqOpts, record, provider, inject),
+        'chat.completions.stream': (orig) => (params, reqOpts) => {
+            const startedAt = Date.now();
+            const acc = new UsageAccumulator();
+            const sent = inject ? withUsage(params) : params;
+            const s = orig(sent, reqOpts);
+            listenHelperStream(s, 'chunk', (c) => acc.feed(c), (aborted) => record({ acc, provider, operation: 'chat.completions', params, streamed: true, aborted, startedAt }));
+            return s;
+        },
+        'responses.create': (orig) => (params, reqOpts) => {
+            const startedAt = Date.now();
+            const acc = new UsageAccumulator();
+            const done = (aborted, streamed) => record({ acc, provider, operation: 'responses', params, streamed, aborted, startedAt });
+            if (!params?.stream) {
+                return mapApiPromise(orig(params, reqOpts), (res) => {
+                    acc.feed(res);
+                    done(false, false);
+                    return res;
+                });
+            }
+            return mapApiPromise(orig(params, reqOpts), (stream) => tapSdkStream(stream, {
+                onItem: (ev) => (acc.feed(ev), true),
+                onDone: (aborted) => done(aborted, true),
+            }));
+        },
+    });
+}
+function chatCreate(orig, params, reqOpts, record, provider, inject) {
+    const startedAt = Date.now();
+    const acc = new UsageAccumulator();
+    const done = (aborted, streamed) => record({ acc, provider, operation: 'chat.completions', params, streamed, aborted, startedAt });
+    if (!params?.stream) {
+        return mapApiPromise(orig(params, reqOpts), (res) => {
+            acc.feed(res);
+            done(false, false);
+            return res;
+        });
+    }
+    const callerAskedUsage = params.stream_options?.include_usage === true;
+    const sent = inject ? withUsage(params) : params;
+    return mapApiPromise(orig(sent, reqOpts), (stream) => tapSdkStream(stream, {
+        onItem(chunk) {
+            acc.feed(chunk);
+            // Hide the usage-only chunk we caused; code reading `choices[0]` would crash on it.
+            return callerAskedUsage || !isUsageOnlyChunk(chunk);
+        },
+        onDone: (aborted) => done(aborted, true),
+    }));
+}
+function withUsage(params) {
+    if (!params || params.stream_options?.include_usage === true)
+        return params;
+    return { ...params, stream_options: { ...params.stream_options, include_usage: true } };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,23 @@
+import type { WrapOptions } from './types.js';
+type Fn = (...args: any[]) => any;
+type Route = (original: Fn) => Fn;
+/**
+ * Returns a proxy of an SDK client where the methods at the given dotted paths
+ * (e.g. 'chat.completions.create') are replaced. Everything else passes through, bound to the
+ * real object so SDK classes with private fields keep working. The original methods stay bound to
+ * the real resources, so SDK helpers that call them internally are not counted twice.
+ */
+export declare function proxyMethods<T extends object>(target: T, routes: Record<string, Route>, prefix?: string): T;
+/**
+ * Transforms the value of an SDK request promise. OpenAI and Anthropic SDKs return an `APIPromise`
+ * with extras (`withResponse()`, `asResponse()`); its `_thenUnwrap` keeps those, and stays lazy so
+ * `asResponse()` callers still get an unread body. Plain promises fall back to `then`.
+ */
+export declare function mapApiPromise<T, U>(p: unknown, fn: (value: T) => U): unknown;
+export declare function inferProvider(url: unknown, fallback: string): string;
+export declare function shouldInjectUsage(opts: WrapOptions, provider: string): boolean;
+/** The extra final chunk `include_usage` adds: no choices, only usage. */
+export declare function isUsageOnlyChunk(chunk: unknown): boolean;
+/** Listens to an SDK helper stream (`chat.completions.stream()`, `messages.stream()`). */
+export declare function listenHelperStream(s: unknown, itemEvent: string, onItem: (item: unknown) => void, onDone: (aborted: boolean) => void): void;
+export {};

package/dist/proxy.js

@@ -0,0 +1,80 @@
+/**
+ * Returns a proxy of an SDK client where the methods at the given dotted paths
+ * (e.g. 'chat.completions.create') are replaced. Everything else passes through, bound to the
+ * real object so SDK classes with private fields keep working. The original methods stay bound to
+ * the real resources, so SDK helpers that call them internally are not counted twice.
+ */
+export function proxyMethods(target, routes, prefix = '') {
+    return new Proxy(target, {
+        get(t, prop) {
+            const v = Reflect.get(t, prop, t);
+            if (typeof prop !== 'string')
+                return v;
+            const path = prefix ? `${prefix}.${prop}` : prop;
+            const route = routes[path];
+            if (route && typeof v === 'function')
+                return route(v.bind(t));
+            if (v && typeof v === 'object' && Object.keys(routes).some((k) => k.startsWith(`${path}.`))) {
+                return proxyMethods(v, routes, path);
+            }
+            return typeof v === 'function' ? v.bind(t) : v;
+        },
+    });
+}
+/**
+ * Transforms the value of an SDK request promise. OpenAI and Anthropic SDKs return an `APIPromise`
+ * with extras (`withResponse()`, `asResponse()`); its `_thenUnwrap` keeps those, and stays lazy so
+ * `asResponse()` callers still get an unread body. Plain promises fall back to `then`.
+ */
+export function mapApiPromise(p, fn) {
+    const ap = p;
+    if (ap && typeof ap._thenUnwrap === 'function')
+        return ap._thenUnwrap((v) => fn(v));
+    return Promise.resolve(p).then(fn);
+}
+export function inferProvider(url, fallback) {
+    const s = typeof url === 'string' ? url : url instanceof URL ? url.href : '';
+    if (s.includes('deepseek'))
+        return 'deepseek';
+    if (s.includes('groq'))
+        return 'groq';
+    if (s.includes('openrouter'))
+        return 'openrouter';
+    if (s.includes('anthropic'))
+        return 'anthropic';
+    if (s.includes('openai'))
+        return 'openai';
+    return fallback;
+}
+export function shouldInjectUsage(opts, provider) {
+    return opts.injectStreamUsage ?? provider !== 'groq';
+}
+/** The extra final chunk `include_usage` adds: no choices, only usage. */
+export function isUsageOnlyChunk(chunk) {
+    const c = chunk;
+    return Array.isArray(c?.choices) && c.choices.length === 0 && c.usage != null;
+}
+/** Listens to an SDK helper stream (`chat.completions.stream()`, `messages.stream()`). */
+export function listenHelperStream(s, itemEvent, onItem, onDone) {
+    const em = s;
+    if (typeof em?.on !== 'function')
+        return;
+    let finished = false;
+    const fin = (aborted) => {
+        if (finished)
+            return;
+        finished = true;
+        onDone(aborted);
+    };
+    em.on(itemEvent, (item) => {
+        try {
+            onItem(item);
+        }
+        catch {
+            // ignore
+        }
+    });
+    em.on('end', () => fin(false));
+    em.on('abort', () => fin(true));
+    em.on('error', () => fin(true));
+}

package/dist/record.d.ts

@@ -0,0 +1,22 @@
+import type { WrapOptions } from './types.js';
+export interface RecordOptions extends Pick<WrapOptions, 'userId' | 'supabase' | 'sink' | 'feature' | 'onError'> {
+    /** e.g. 'groq', 'elevenlabs', 'openai'. */
+    provider: string;
+    /** e.g. 'whisper-large-v3', 'eleven_multilingual_v2'. */
+    model: string;
+    /** How much was used, in `unit`: 742 seconds of audio, 48000 characters, 3 images. */
+    units: number;
+    /** Lower-case: 'seconds', 'characters', 'images', 'requests'… */
+    unit: string;
+    /** What the call cost, when you know it. Without it the row stays unpriced (ops shows it as such). */
+    costUsd?: number;
+    /** Which API was called; defaults to `unit`. */
+    operation?: string;
+    latencyMs?: number;
+}
+/**
+ * Records one call that isn't measured in tokens (speech-to-text, text-to-speech, images) to
+ * `ops.usage`, for the user's cost and the "who costs money" view. Like wrap(), it never throws into
+ * the caller and writes in the background (call flush() before a process exits).
+ */
+export declare function record(opts: RecordOptions): void;

package/dist/record.js

@@ -0,0 +1,41 @@
+import { background, createSender } from "./recorder.js";
+const UNIT = /^[a-z][a-z_]{0,19}$/;
+/**
+ * Records one call that isn't measured in tokens (speech-to-text, text-to-speech, images) to
+ * `ops.usage`, for the user's cost and the "who costs money" view. Like wrap(), it never throws into
+ * the caller and writes in the background (call flush() before a process exits).
+ */
+export function record(opts) {
+    const { send, onError } = createSender(opts);
+    try {
+        if (!Number.isFinite(opts.units) || opts.units < 0)
+            throw new TypeError('@cockpitify/node: `units` must be 0 or more.');
+        if (typeof opts.unit !== 'string' || !UNIT.test(opts.unit))
+            throw new TypeError('@cockpitify/node: `unit` must be a lower-case word like "seconds".');
+        if (opts.costUsd !== undefined && (!Number.isFinite(opts.costUsd) || opts.costUsd < 0))
+            throw new TypeError('@cockpitify/node: `costUsd` must be 0 or more.');
+        const row = {
+            user_id: opts.userId,
+            provider: opts.provider,
+            model: opts.model,
+            operation: opts.operation ?? opts.unit,
+            input_tokens: 0,
+            output_tokens: 0,
+            cached_input_tokens: 0,
+            cache_write_tokens: 0,
+            cost_usd: opts.costUsd ?? null,
+            estimated: false,
+            streamed: false,
+            aborted: false,
+            latency_ms: Math.max(0, Math.round(opts.latencyMs ?? 0)),
+            feature: opts.feature ?? null,
+            occurred_at: new Date().toISOString(),
+            units: opts.units,
+            unit: opts.unit,
+        };
+        background(send(row).catch(onError));
+    }
+    catch (err) {
+        onError(err);
+    }
+}

package/dist/recorder.d.ts

@@ -0,0 +1,28 @@
+import { type UsageAccumulator } from './accumulator.js';
+import type { Prices, UsageRow, WrapOptions } from './types.js';
+export interface Measurement {
+    acc: UsageAccumulator;
+    provider: string;
+    operation: string;
+    /** Request parameters; used for the model name and for input estimates. */
+    params: unknown;
+    streamed: boolean;
+    aborted: boolean;
+    startedAt: number;
+}
+export type RecordFn = (m: Measurement) => void;
+/**
+ * Keeps a write alive after the response has been sent. On Supabase Edge Functions this is
+ * `EdgeRuntime.waitUntil`; elsewhere the promise is tracked until `flush()`.
+ */
+export declare function background(p: Promise<unknown>): void;
+/** Waits for every usage write still in flight. Call before a Node process or serverless handler exits. */
+export declare function flush(): Promise<void>;
+/** Where rows go (the project's ops.usage, or a custom sink), checked once. Shared by wrap() and record(). */
+export declare function createSender(opts: Pick<WrapOptions, 'userId' | 'sink' | 'supabase' | 'onError'>): {
+    send: (row: UsageRow) => Promise<unknown>;
+    onError: (err: unknown) => void;
+};
+export declare function createRecorder(opts: WrapOptions): RecordFn;
+/** Longest matching price key wins, so 'gpt-4o-mini' is not priced as 'gpt-4o'. */
+export declare function cost(prices: Prices | undefined, model: string, input: number, output: number, cached: number, cacheWrite: number): number | null;

package/dist/recorder.js

@@ -0,0 +1,108 @@
+import { estimateTokens, promptText } from "./accumulator.js";
+const pending = new Set();
+/**
+ * Keeps a write alive after the response has been sent. On Supabase Edge Functions this is
+ * `EdgeRuntime.waitUntil`; elsewhere the promise is tracked until `flush()`.
+ */
+export function background(p) {
+    const rt = globalThis.EdgeRuntime;
+    if (typeof rt?.waitUntil === 'function') {
+        rt.waitUntil(p);
+        return;
+    }
+    pending.add(p);
+    void p.finally(() => pending.delete(p));
+}
+/** Waits for every usage write still in flight. Call before a Node process or serverless handler exits. */
+export async function flush() {
+    await Promise.allSettled([...pending]);
+}
+let warned = false;
+function defaultOnError(err) {
+    if (warned)
+        return;
+    warned = true;
+    console.warn('[@cockpitify/node] usage recording failed; AI calls are unaffected.', err);
+}
+/** Where rows go (the project's ops.usage, or a custom sink), checked once. Shared by wrap() and record(). */
+export function createSender(opts) {
+    if (!opts || typeof opts.userId !== 'string' || !opts.userId) {
+        throw new TypeError('@cockpitify/node: `userId` is required.');
+    }
+    if (!opts.sink && !opts.supabase) {
+        throw new TypeError('@cockpitify/node: pass `supabase` (writes to ops.usage) or a custom `sink`.');
+    }
+    const onError = opts.onError ?? defaultOnError;
+    const send = (row) => {
+        if (opts.sink)
+            return Promise.resolve(opts.sink(row));
+        return Promise.resolve(opts.supabase.schema('ops').from('usage').insert(row)).then((r) => {
+            if (r?.error)
+                throw r.error;
+        });
+    };
+    return { send, onError };
+}
+export function createRecorder(opts) {
+    const { send, onError } = createSender(opts);
+    // Never throws: a failure here must not break the caller's AI request.
+    return (m) => {
+        try {
+            const row = toRow(m, opts);
+            background(send(row).catch(onError));
+        }
+        catch (err) {
+            onError(err);
+        }
+    };
+}
+function toRow(m, opts) {
+    const { acc } = m;
+    const model = acc.model || modelFromParams(m.params) || 'unknown';
+    let input = acc.input;
+    let output = acc.output;
+    const estimated = !acc.final;
+    if (estimated) {
+        input = input || estimateTokens(promptText(m.params));
+        output = Math.max(output, estimateTokens(acc.text));
+    }
+    return {
+        user_id: opts.userId,
+        provider: opts.provider ?? m.provider,
+        model,
+        operation: m.operation,
+        input_tokens: input,
+        output_tokens: output,
+        cached_input_tokens: acc.cached,
+        cache_write_tokens: acc.cacheWrite,
+        cost_usd: cost(opts.prices, model, input, output, acc.cached, acc.cacheWrite),
+        estimated,
+        streamed: m.streamed,
+        aborted: m.aborted,
+        latency_ms: Date.now() - m.startedAt,
+        feature: opts.feature ?? null,
+        occurred_at: new Date(m.startedAt).toISOString(),
+    };
+}
+function modelFromParams(params) {
+    const model = params?.model;
+    return typeof model === 'string' ? model : '';
+}
+/** Longest matching price key wins, so 'gpt-4o-mini' is not priced as 'gpt-4o'. */
+export function cost(prices, model, input, output, cached, cacheWrite) {
+    if (!prices)
+        return null;
+    let key = '';
+    for (const k of Object.keys(prices))
+        if (model.startsWith(k) && k.length > key.length)
+            key = k;
+    if (!key)
+        return null;
+    const p = prices[key];
+    const fresh = Math.max(0, input - cached - cacheWrite);
+    const usd = fresh * p.input +
+        cached * (p.cachedInput ?? p.input) +
+        cacheWrite * (p.cacheWrite ?? p.input) +
+        output * p.output;
+    return usd / 1_000_000;
+}

package/dist/stream.d.ts

@@ -0,0 +1,27 @@
+export interface Tap<T> {
+    /** Sees each item. Return false to hide it from the caller. Exceptions are swallowed. */
+    onItem(item: T): boolean;
+    /** Called exactly once: on normal end (aborted=false), or on break/cancel/error (aborted=true). */
+    onDone(aborted: boolean): void;
+}
+export declare function tapIterator<T>(it: AsyncIterator<T>, tap: Tap<T>): AsyncIterableIterator<T>;
+/**
+ * Instruments an SDK stream object in place when possible.
+ *
+ * OpenAI and Anthropic SDK streams keep their source in an `iterator()` method that
+ * `[Symbol.asyncIterator]`, `tee()` and `toReadableStream()` all go through, so patching it covers
+ * every way the caller can consume the stream while keeping the original object (and its
+ * `controller`, `response`, etc.). Other async iterables get a thin proxy.
+ */
+export declare function tapSdkStream<S extends object>(stream: S, tap: Tap<any>): S;
+/** Object streams (e.g. AI SDK stream parts). Cancelling the result cancels the source. */
+export declare function tapReadable<T>(src: ReadableStream<T>, tap: Tap<T>): ReadableStream<T>;
+export interface SseEvent {
+    event: string;
+    data: string;
+}
+/**
+ * Byte-level Server-Sent Events pass-through. Splits on event boundaries and forwards each event's
+ * original text unchanged, unless `onItem` returns false for it.
+ */
+export declare function tapSse(body: ReadableStream<Uint8Array>, tap: Tap<SseEvent>): ReadableStream<Uint8Array>;

package/dist/stream.js

@@ -0,0 +1,199 @@
+// Pass-through wrappers that observe a stream without delaying or altering what the caller sees
+// (except for dropping items the caller never asked for, see `keep`).
+function safeKeep(tap, item) {
+    try {
+        return tap.onItem(item) !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export function tapIterator(it, tap) {
+    let finished = false;
+    const finish = (aborted) => {
+        if (finished)
+            return;
+        finished = true;
+        try {
+            tap.onDone(aborted);
+        }
+        catch {
+            // never surfaces to the caller
+        }
+    };
+    const wrapped = {
+        async next() {
+            try {
+                for (;;) {
+                    const r = await it.next();
+                    if (r.done) {
+                        finish(false);
+                        return r;
+                    }
+                    if (safeKeep(tap, r.value))
+                        return r;
+                }
+            }
+            catch (err) {
+                finish(true);
+                throw err;
+            }
+        },
+        async return(value) {
+            finish(true);
+            return it.return ? it.return(value) : { done: true, value: value };
+        },
+        async throw(err) {
+            finish(true);
+            if (it.throw)
+                return it.throw(err);
+            throw err;
+        },
+        [Symbol.asyncIterator]() {
+            return wrapped;
+        },
+    };
+    return wrapped;
+}
+/**
+ * Instruments an SDK stream object in place when possible.
+ *
+ * OpenAI and Anthropic SDK streams keep their source in an `iterator()` method that
+ * `[Symbol.asyncIterator]`, `tee()` and `toReadableStream()` all go through, so patching it covers
+ * every way the caller can consume the stream while keeping the original object (and its
+ * `controller`, `response`, etc.). Other async iterables get a thin proxy.
+ */
+export function tapSdkStream(stream, tap) {
+    const s = stream;
+    if (typeof s.iterator === 'function') {
+        const original = s.iterator.bind(s);
+        s.iterator = () => tapIterator(original(), tap);
+        return stream;
+    }
+    if (typeof s[Symbol.asyncIterator] === 'function') {
+        return new Proxy(stream, {
+            get(target, prop) {
+                if (prop === Symbol.asyncIterator) {
+                    return () => tapIterator(target[Symbol.asyncIterator](), tap);
+                }
+                const v = Reflect.get(target, prop, target);
+                return typeof v === 'function' ? v.bind(target) : v;
+            },
+        });
+    }
+    return stream;
+}
+/** Object streams (e.g. AI SDK stream parts). Cancelling the result cancels the source. */
+export function tapReadable(src, tap) {
+    const reader = src.getReader();
+    let finished = false;
+    const finish = (aborted) => {
+        if (finished)
+            return;
+        finished = true;
+        try {
+            tap.onDone(aborted);
+        }
+        catch {
+            // ignore
+        }
+    };
+    return new ReadableStream({
+        async pull(ctrl) {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        finish(false);
+                        ctrl.close();
+                        return;
+                    }
+                    if (safeKeep(tap, value)) {
+                        ctrl.enqueue(value);
+                        return;
+                    }
+                }
+            }
+            catch (err) {
+                finish(true);
+                ctrl.error(err);
+            }
+        },
+        cancel(reason) {
+            finish(true);
+            return reader.cancel(reason);
+        },
+    });
+}
+/**
+ * Byte-level Server-Sent Events pass-through. Splits on event boundaries and forwards each event's
+ * original text unchanged, unless `onItem` returns false for it.
+ */
+export function tapSse(body, tap) {
+    const reader = body.getReader();
+    const dec = new TextDecoder();
+    const enc = new TextEncoder();
+    let buf = '';
+    let finished = false;
+    const finish = (aborted) => {
+        if (finished)
+            return;
+        finished = true;
+        try {
+            tap.onDone(aborted);
+        }
+        catch {
+            // ignore
+        }
+    };
+    const boundary = /\r?\n\r?\n/;
+    return new ReadableStream({
+        async pull(ctrl) {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        buf += dec.decode();
+                        if (buf)
+                            ctrl.enqueue(enc.encode(buf));
+                        finish(false);
+                        ctrl.close();
+                        return;
+                    }
+                    buf += dec.decode(value, { stream: true });
+                    let out = '';
+                    for (let m = boundary.exec(buf); m; m = boundary.exec(buf)) {
+                        const end = m.index + m[0].length;
+                        const raw = buf.slice(0, end);
+                        buf = buf.slice(end);
+                        if (safeKeep(tap, parseSse(raw)))
+                            out += raw;
+                    }
+                    if (out) {
+                        ctrl.enqueue(enc.encode(out));
+                        return;
+                    }
+                }
+            }
+            catch (err) {
+                finish(true);
+                ctrl.error(err);
+            }
+        },
+        cancel(reason) {
+            finish(true);
+            return reader.cancel(reason);
+        },
+    });
+}
+function parseSse(raw) {
+    let event = '';
+    const data = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.startsWith('event:'))
+            event = line.slice(6).trim();
+        else if (line.startsWith('data:'))
+            data.push(line.slice(5).replace(/^ /, ''));
+    }
+    return { event, data: data.join('\n') };
+}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/** One row in the customer's `ops.usage` table. */
+export interface UsageRow {
+    user_id: string;
+    provider: string;
+    model: string;
+    /** Which API was called: 'chat.completions', 'responses', 'messages', 'fetch', 'ai-sdk'. */
+    operation: string;
+    /** Total input tokens, including cache reads and cache writes. */
+    input_tokens: number;
+    output_tokens: number;
+    cached_input_tokens: number;
+    cache_write_tokens: number;
+    /** Null when no price is known for the model; the database fills it from its price table. */
+    cost_usd: number | null;
+    /** True when the provider never reported usage (e.g. the stream was cut) and tokens were estimated. */
+    estimated: boolean;
+    streamed: boolean;
+    aborted: boolean;
+    latency_ms: number;
+    feature: string | null;
+    occurred_at: string;
+    /** Calls not measured in tokens (ops 0.17.0+): the amount and its unit, e.g. 742 'seconds'. */
+    units?: number | null;
+    unit?: string | null;
+}
+export type Sink = (row: UsageRow) => PromiseLike<unknown>;
+/** The slice of a supabase-js client we use. */
+export interface SupabaseLike {
+    schema(name: string): {
+        from(table: string): {
+            insert(row: UsageRow): PromiseLike<{
+                error: unknown;
+            }>;
+        };
+    };
+}
+/** USD per 1M tokens. Keys match a model id exactly or as a prefix (e.g. 'gpt-4o' matches 'gpt-4o-2024-08-06'). */
+export type Prices = Record<string, {
+    input: number;
+    output: number;
+    cachedInput?: number;
+    cacheWrite?: number;
+}>;
+export interface WrapOptions {
+    userId: string;
+    /** Rows go to `ops.usage` through this client. Either this or `sink` is required. */
+    supabase?: SupabaseLike;
+    sink?: Sink;
+    /** Overrides the provider label inferred from the client or URL. */
+    provider?: string;
+    /** Optional product-level tag, e.g. 'chat' or 'transcribe'. */
+    feature?: string;
+    prices?: Prices;
+    /**
+     * OpenAI-compatible streams only report usage when `stream_options.include_usage` is set, so it is
+     * added to streaming requests (and the extra usage-only chunk is hidden from the caller unless
+     * they asked for it). Defaults to true, except for Groq, which reports usage without it.
+     */
+    injectStreamUsage?: boolean;
+    /** Called when recording fails. Recording never throws into the caller. Defaults to one console.warn. */
+    onError?: (err: unknown) => void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cockpitify/node",
+  "version": "0.1.0",
+  "description": "Records each user's AI token usage and cost to your own Supabase project (Cockpitify).",
+  "license": "MIT",
+  "author": "Cockpitify",
+  "homepage": "https://cockpitify.app",
+  "keywords": [
+    "cockpitify",
+    "ai",
+    "llm",
+    "cost",
+    "openai",
+    "anthropic",
+    "supabase",
+    "deno"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "openai": "^7.27.0"
+  },
+  "scripts": {
+    "build": "node ../build.mjs",
+    "test": "node --experimental-strip-types --no-warnings --test \"test/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}