margin-meter 0.1.0 → 0.2.0

package/dist/providers.js

@@ -0,0 +1,397 @@
+/**
+ * Read the measured economics of one LLM call straight off a provider response.
+ *
+ * The TS twin of `margin_meter.providers`: given the object an OpenAI /
+ * Anthropic / Gemini JS client returns, recover the `(provider, model, tokens)`
+ * a Margin call row needs — so auto-instrumentation is a few lines with no
+ * manual token bookkeeping.
+ *
+ * Dependency-free and duck-typed on purpose: it never imports the provider SDKs,
+ * reading fields by shape so it works on a real SDK object, a plain object (the
+ * shape a mocked provider returns in tests), or JSON. The three shapes, as the
+ * current JS SDKs publish them:
+ *
+ *  - **OpenAI** — `model`; `usage.prompt_tokens` / `completion_tokens`; cached
+ *    reads at `usage.prompt_tokens_details.cached_tokens` (Responses API:
+ *    `usage.input_tokens` / `output_tokens` / `input_tokens_details.cached_tokens`).
+ *  - **Anthropic** — `model`; `usage.input_tokens` / `output_tokens`; cached
+ *    reads at `usage.cache_read_input_tokens`; cache WRITES at
+ *    `usage.cache_creation_input_tokens` (a ~1.25x premium bucket).
+ *  - **Gemini** (`@google/generative-ai`) — `response.usageMetadata` (the
+ *    `generateContent` result nests it under `.response`), with
+ *    `promptTokenCount` / `candidatesTokenCount` / `cachedContentTokenCount`, plus
+ *    `thoughtsTokenCount` (thinking tokens, billed as output and folded in).
+ *    The model does not ride the response, so the caller passes it.
+ *  - **Cohere** (v2 `/chat`) — billed counts nest under `usage.billed_units`
+ *    (what is charged; raw `usage.tokens` is the fallback), each with
+ *    `input_tokens` / `output_tokens`. Cohere publishes no chat prompt-cache
+ *    discount, so cache reads bill as ordinary input (`cacheReadTokens` stays 0);
+ *    the model does not ride the response, so the caller passes it.
+ *  - **AWS Bedrock** (`@aws-sdk/client-bedrock-runtime`, Converse) — usage rides
+ *    `usage.inputTokens` / `outputTokens` in camelCase, with ADDITIVE cache
+ *    buckets `cacheReadInputTokens` / `cacheWriteInputTokens` (AWS documents
+ *    `totalTokens = inputTokens + outputTokens + cacheReadInputTokens +
+ *    cacheWriteInputTokens`), so the three input-side buckets are disjoint and
+ *    each reads verbatim, no subtraction. The Converse response omits the model
+ *    id, so the caller passes it (`instrumentBedrock` reads it off the command's
+ *    `input.modelId`); its gateway form (`us.anthropic.claude-…-v1:0`) prices
+ *    through the server's `normalize_model`.
+ *
+ * Numbers are read verbatim — never inflated. A field the provider didn't report
+ * reads 0; an unrecognised shape throws `UsageExtractionError` rather than
+ * emitting a silently-zero (free-looking) call.
+ */
+export const OPENAI = "openai";
+export const ANTHROPIC = "anthropic";
+export const GOOGLE = "google";
+export const COHERE = "cohere";
+export const BEDROCK = "bedrock";
+/** The response object matched no provider shape we can meter. */
+export class UsageExtractionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageExtractionError";
+    }
+}
+/** Read `obj.name` from an object OR undefined — duck-typed, null-safe. */
+function get(obj, name) {
+    if (obj === null || obj === undefined)
+        return undefined;
+    if (typeof obj !== "object")
+        return undefined;
+    return obj[name];
+}
+/** Walk a chain of field names, tolerating a missing hop. */
+function getPath(obj, ...names) {
+    let cur = obj;
+    for (const name of names) {
+        cur = get(cur, name);
+        if (cur === null || cur === undefined)
+            return undefined;
+    }
+    return cur;
+}
+/** Coerce a reported token count to a non-negative int; missing → 0. Reads
+ *  verbatim — never rounds a real count up or invents one. */
+function asInt(value) {
+    if (value === null || value === undefined)
+        return 0;
+    const n = Math.trunc(Number(value));
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return n;
+}
+/** The Gemini `generateContent` result nests usage under `.response`; unwrap it. */
+function usageMetadata(response) {
+    const direct = get(response, "usageMetadata");
+    if (direct !== undefined)
+        return direct;
+    return getPath(response, "response", "usageMetadata");
+}
+/**
+ * Best-effort provider inference from a response's shape. Prefers unambiguous
+ * signals: Gemini exposes `usageMetadata`; Anthropic's usage carries
+ * `input_tokens` while OpenAI's carries `prompt_tokens`. Returns undefined when
+ * nothing distinguishes it — the caller must then name the provider (the
+ * instrumenter always does).
+ */
+export function detectProvider(response) {
+    if (usageMetadata(response) !== undefined)
+        return GOOGLE;
+    const usage = get(response, "usage");
+    if (usage !== undefined && usage !== null) {
+        // Cohere nests billed counts under `billed_units` — a key no other provider
+        // carries, so it is an unambiguous signal. Checked before Anthropic so its
+        // NESTED input_tokens is never read as Anthropic's top-level one.
+        if (get(usage, "billed_units") !== undefined)
+            return COHERE;
+        // Bedrock's Converse usage is camelCase (`inputTokens`/`outputTokens`) — a
+        // shape every other provider spells snake_case, so it is unambiguous (like
+        // Cohere's `billed_units`). Checked before the snake_case branches so its
+        // camelCase keys are never read as a missing OpenAI/Anthropic usage.
+        if (get(usage, "inputTokens") !== undefined || get(usage, "outputTokens") !== undefined) {
+            return BEDROCK;
+        }
+        if (get(usage, "prompt_tokens") !== undefined || get(usage, "completion_tokens") !== undefined) {
+            return OPENAI;
+        }
+        if (get(usage, "input_tokens") !== undefined || get(usage, "output_tokens") !== undefined) {
+            return ANTHROPIC;
+        }
+    }
+    return undefined;
+}
+function extractOpenAI(response, model) {
+    const usage = get(response, "usage");
+    if (usage === undefined || usage === null) {
+        throw new UsageExtractionError("openai response carries no .usage");
+    }
+    const inputRaw = get(usage, "prompt_tokens") ?? get(usage, "input_tokens");
+    const outputRaw = get(usage, "completion_tokens") ?? get(usage, "output_tokens");
+    // DeepSeek-direct is OpenAI-compatible, so instrument reaches it through the same
+    // client — but it reports cache hits in its own prompt_cache_hit_tokens field, not
+    // prompt_tokens_details.cached_tokens, and prompt_tokens is inclusive of them. A
+    // genuine OpenAI/Azure response never carries this field (reads 0), so the direct
+    // path is unchanged; reading it captures DeepSeek's cache discount. Consulted last,
+    // so a provider reporting both is never double-counted.
+    const cachedRaw = getPath(usage, "prompt_tokens_details", "cached_tokens") ??
+        getPath(usage, "input_tokens_details", "cached_tokens") ??
+        get(usage, "prompt_cache_hit_tokens");
+    const cached = asInt(cachedRaw);
+    // prompt_tokens is INCLUSIVE of cached — split so cache reads are not
+    // double-billed as fresh input (the server bills the two separately).
+    const freshInput = asInt(inputRaw) - cached;
+    // A reasoning model (o-series, gpt-5) reports the hidden-thinking share under
+    // completion_tokens_details.reasoning_tokens — a BREAKDOWN of completion_tokens,
+    // not an addition. outputTokens already counts it; carry it only for the
+    // reasoning-share detector, clamped to output so the subset never exceeds the
+    // whole. 0 on a non-reasoning response.
+    const out = asInt(outputRaw);
+    const reasoning = asInt(getPath(usage, "completion_tokens_details", "reasoning_tokens"));
+    return {
+        provider: OPENAI,
+        model: model ?? get(response, "model"),
+        inputTokens: freshInput > 0 ? freshInput : 0,
+        outputTokens: out,
+        cacheReadTokens: cached,
+        cacheCreationTokens: 0,
+        reasoningTokens: Math.min(reasoning, out),
+    };
+}
+function extractAnthropic(response, model) {
+    const usage = get(response, "usage");
+    if (usage === undefined || usage === null) {
+        throw new UsageExtractionError("anthropic response carries no .usage");
+    }
+    // Anthropic's input_tokens EXCLUDES both cache reads and cache writes (each a
+    // separate field) — read them verbatim, no subtraction. Cache creation
+    // (cache_creation_input_tokens) is the write-premium bucket AGGREGATE. When a
+    // request pins a 1-hour TTL, Anthropic breaks that down under usage.cache_creation
+    // into ephemeral_5m/ephemeral_1h — the 1-hour writes bill ~2x input (vs 5-minute
+    // ~1.25x), so split them out. The 1-hour portion goes in its own bucket and the
+    // 5-minute bucket is the remainder; no breakdown → 1h is 0 and the whole aggregate
+    // stays 5-minute, byte-identical to before.
+    const totalCreation = asInt(get(usage, "cache_creation_input_tokens"));
+    const creation1h = asInt(getPath(usage, "cache_creation", "ephemeral_1h_input_tokens"));
+    const creation5m = totalCreation - creation1h;
+    return {
+        provider: ANTHROPIC,
+        model: model ?? get(response, "model"),
+        inputTokens: asInt(get(usage, "input_tokens")),
+        outputTokens: asInt(get(usage, "output_tokens")),
+        cacheReadTokens: asInt(get(usage, "cache_read_input_tokens")),
+        // Never let a malformed breakdown push the 5-minute remainder negative.
+        cacheCreationTokens: creation5m > 0 ? creation5m : 0,
+        cacheCreation1hTokens: creation1h,
+    };
+}
+function extractGemini(response, model) {
+    const meta = usageMetadata(response);
+    if (meta === undefined || meta === null) {
+        throw new UsageExtractionError("gemini response carries no usageMetadata");
+    }
+    const cached = asInt(get(meta, "cachedContentTokenCount"));
+    const prompt = asInt(get(meta, "promptTokenCount"));
+    // promptTokenCount is INCLUSIVE of cached content — split it out.
+    const freshInput = prompt - cached;
+    // Gemini bills THINKING tokens (thoughtsTokenCount) at the output rate but
+    // reports them in a field DISJOINT from candidatesTokenCount (the visible
+    // completion). Billed output = candidates + thoughts, which also equals
+    // totalTokenCount - promptTokenCount. Take the max so a thinking-enabled call
+    // is never under-counted, whichever fields the response populates.
+    const candidates = asInt(get(meta, "candidatesTokenCount"));
+    const thoughts = asInt(get(meta, "thoughtsTokenCount"));
+    const total = asInt(get(meta, "totalTokenCount"));
+    const outputTokens = Math.max(candidates + thoughts, total ? total - prompt : 0);
+    return {
+        provider: GOOGLE,
+        model,
+        inputTokens: freshInput > 0 ? freshInput : 0,
+        outputTokens,
+        cacheReadTokens: cached,
+        cacheCreationTokens: 0,
+        // thoughts already sit inside outputTokens (billed at the output rate);
+        // carried here only for the reasoning-share detector, never above output.
+        reasoningTokens: Math.min(thoughts, outputTokens),
+    };
+}
+function extractCohere(response, model) {
+    const usage = get(response, "usage");
+    if (usage === undefined || usage === null) {
+        throw new UsageExtractionError("cohere response carries no .usage");
+    }
+    // Cohere v2 /chat reports billed counts under `billed_units` (what is charged),
+    // with a raw `tokens` mirror as the fallback. input_tokens is read VERBATIM:
+    // Cohere publishes no chat prompt-cache discount, so a cache read bills at the
+    // input rate and is already inside billed_units.input — folding it into input
+    // (cacheReadTokens 0) is cost-exact and never over-states a caching win.
+    const units = get(usage, "billed_units") ?? get(usage, "tokens");
+    if (units === undefined || units === null) {
+        throw new UsageExtractionError("cohere usage carries no billed_units/tokens");
+    }
+    return {
+        provider: COHERE,
+        model: model ?? get(response, "model"),
+        inputTokens: asInt(get(units, "input_tokens")),
+        outputTokens: asInt(get(units, "output_tokens")),
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+    };
+}
+function extractBedrock(response, model) {
+    const usage = get(response, "usage");
+    if (usage === undefined || usage === null) {
+        throw new UsageExtractionError("bedrock response carries no .usage");
+    }
+    // Bedrock's Converse usage is camelCase and — like Anthropic native —
+    // `inputTokens` EXCLUDES the cache buckets: AWS documents `totalTokens =
+    // inputTokens + outputTokens + cacheReadInputTokens + cacheWriteInputTokens`,
+    // so the three input-side buckets are disjoint and each reads verbatim, no
+    // subtraction. `cacheWriteInputTokens` is the write bucket (a cache-creation
+    // premium); `cacheReadInputTokens` the discounted hit. Both absent (→ 0) on a
+    // no-cache call. The response omits the model id, so the caller supplies it.
+    return {
+        provider: BEDROCK,
+        model: model ?? get(response, "model"),
+        inputTokens: asInt(get(usage, "inputTokens")),
+        outputTokens: asInt(get(usage, "outputTokens")),
+        cacheReadTokens: asInt(get(usage, "cacheReadInputTokens")),
+        cacheCreationTokens: asInt(get(usage, "cacheWriteInputTokens")),
+    };
+}
+const EXTRACTORS = {
+    [OPENAI]: extractOpenAI,
+    [ANTHROPIC]: extractAnthropic,
+    [GOOGLE]: extractGemini,
+    [COHERE]: extractCohere,
+    [BEDROCK]: extractBedrock,
+};
+/**
+ * Recover the metered `Usage` of one call from its provider response. `provider`
+ * forces the shape (the instrumenter always knows which client it patched);
+ * omit it and the provider is inferred from the response's shape. `model`
+ * overrides a response that omits its model (Gemini). Throws
+ * `UsageExtractionError` when the shape matches no known provider or carries no
+ * usage block, so a silently-free call is never emitted.
+ */
+export function extractUsage(response, opts = {}) {
+    const prov = (opts.provider ?? detectProvider(response));
+    const extractor = prov ? EXTRACTORS[prov] : undefined;
+    if (!extractor) {
+        throw new UsageExtractionError(`unknown or undetectable provider ${String(opts.provider)}; ` +
+            "pass provider: 'openai' | 'anthropic' | 'google' | 'cohere' | 'bedrock'");
+    }
+    return extractor(response, opts.model);
+}
+// --------------------------------------------------------------------------- //
+// Streaming — reunite the usage of one STREAMED call across its chunks.
+//
+// A `stream: true` call resolves to an async-iterable of chunks, not a `.usage`
+// response, so `extractUsage` on the resolved value throws and the call would be
+// dropped. Streaming is the DEFAULT mode for interactive JS agents (the Vercel
+// AI SDK, LangChain.js, chat UIs), so that is a whole class of spend going
+// unmetered. These primitives are the TS twin of `margin_meter.providers`'
+// `StreamUsageAccumulator`: read whatever usage each chunk carries, max-merge it
+// across the stream, and finalize to one `Usage` — or `undefined` when the stream
+// carried no usage at all (never a fabricated zero-token, free-looking row).
+// --------------------------------------------------------------------------- //
+/**
+ * Read whatever usage ONE streaming chunk/event carries, or `undefined`.
+ *
+ * The three streamed shapes differ in WHERE (and whether) a chunk carries usage:
+ *
+ *  - **OpenAI** (needs `stream_options: { include_usage: true }`): every content
+ *    chunk has `usage: null`; only the FINAL chunk carries the full `.usage`.
+ *  - **Gemini**: every chunk carries a CUMULATIVE `usageMetadata` — the last is
+ *    authoritative, and the running max keeps it.
+ *  - **Anthropic**: no single event is complete — `message_start` carries the
+ *    input + cache counts nested under `event.message.usage`, while `message_delta`
+ *    carries the final `event.usage.output_tokens`. This reads BOTH carriers so the
+ *    merge can reunite them.
+ *
+ * Returns `undefined` (never throws) for a chunk with no usage, so an ordinary
+ * content chunk is skipped, not treated as an error.
+ */
+export function usageFromStreamChunk(chunk, provider, model) {
+    // Straightforward carriers: a top-level `usage` (OpenAI final chunk, Anthropic
+    // message_delta) or `usageMetadata` (Gemini) — extractUsage reads either.
+    try {
+        return extractUsage(chunk, { provider, model });
+    }
+    catch {
+        /* not a complete-usage chunk — try the nested Anthropic carrier below */
+    }
+    // Anthropic's message_start nests the input/cache counts under
+    // `event.message.usage`; extractUsage on the event itself misses them, so read
+    // the nested message carrier directly (its usage IS the top-level shape).
+    const message = get(chunk, "message");
+    if (message !== undefined && message !== null && get(message, "usage") !== undefined) {
+        try {
+            return extractUsage(message, { provider: provider ?? ANTHROPIC, model });
+        }
+        catch {
+            /* not a readable message_start either */
+        }
+    }
+    return undefined;
+}
+/**
+ * Merge two per-chunk usages, taking the MAX of each token bucket.
+ *
+ * Every streamed token count is monotonic within one call — cumulative (Gemini),
+ * or populated exactly once (OpenAI's final chunk; Anthropic's input-here /
+ * output-there split) — so the running max reconstructs the final total no matter
+ * which chunk carried which field. The max never invents a token; it only keeps
+ * the largest REAL count each field reached.
+ */
+export function mergeStreamUsage(a, b) {
+    return {
+        provider: a.provider ?? b.provider,
+        model: a.model ?? b.model,
+        inputTokens: Math.max(a.inputTokens, b.inputTokens),
+        outputTokens: Math.max(a.outputTokens, b.outputTokens),
+        cacheReadTokens: Math.max(a.cacheReadTokens, b.cacheReadTokens),
+        cacheCreationTokens: Math.max(a.cacheCreationTokens, b.cacheCreationTokens),
+        cacheCreation1hTokens: Math.max(a.cacheCreation1hTokens ?? 0, b.cacheCreation1hTokens ?? 0),
+        reasoningTokens: Math.max(a.reasoningTokens ?? 0, b.reasoningTokens ?? 0),
+    };
+}
+/**
+ * Accumulates the metered usage of one STREAMING call across its chunks.
+ *
+ * Feed every chunk to `observe` as the host iterates the stream, then call
+ * `finalize` once the stream is exhausted (or closed) to get the single `Usage`
+ * for the whole call — or `undefined` when the stream never carried a usage block
+ * (e.g. an OpenAI stream opened without `include_usage`, where there is genuinely
+ * no count to meter and inventing one would be a lie). Provider-agnostic: the
+ * per-chunk read + max-merge handles OpenAI, Anthropic and Gemini streams alike.
+ */
+export class StreamUsageAccumulator {
+    provider;
+    model;
+    usage = undefined;
+    // Explicit assignment (not constructor parameter properties) so the source is
+    // erasable TypeScript — `node --experimental-strip-types` runs it with no build.
+    constructor(provider, model) {
+        this.provider = provider;
+        this.model = model;
+    }
+    /** Fold one chunk's usage (if any) into the running total. Never throws. */
+    observe(chunk) {
+        let u;
+        try {
+            u = usageFromStreamChunk(chunk, this.provider, this.model);
+        }
+        catch {
+            return; // a malformed chunk must never break the host's stream
+        }
+        if (u === undefined)
+            return;
+        this.usage = this.usage === undefined ? u : mergeStreamUsage(this.usage, u);
+    }
+    /** The accumulated usage, or `undefined` if the stream carried no usage. */
+    finalize() {
+        return this.usage;
+    }
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"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"}

package/dist/substrate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The SUBSTRATE a call travelled through to reach a model — the TypeScript twin
+ * of `margin_meter/substrate.py`.
+ *
+ * `provider` says who owns the model and who bills for it. `substrate` says which
+ * path the request actually took: the vendor's own API, a router like OpenRouter,
+ * a cloud reseller like Bedrock or Azure. The two are orthogonal, and comparing
+ * the same work across paths is the thing a single-substrate router structurally
+ * cannot do.
+ *
+ * Detection is EVIDENCE, not inference. A JS client carries the endpoint it will
+ * call (`baseURL` on the OpenAI and Anthropic SDKs), so an OpenAI client pointed
+ * at `openrouter.ai` is recorded as OpenRouter because that is literally where
+ * the request goes. Nothing is defaulted: a client whose endpoint cannot be read
+ * records NO path, which is the honest reading of an unmeasured dimension.
+ *
+ * Keep the host tables in step with the Python SDK and `margin/substrates.py`.
+ * Three copies of one rule is a real cost, and the alternative — a JS estate that
+ * cannot join the comparison at all — costs more.
+ */
+export declare const DIRECT = "direct";
+export declare const OPENROUTER = "openrouter";
+export declare const LITELLM = "litellm";
+export declare const AZURE = "azure";
+export declare const BEDROCK = "bedrock";
+export declare const VERTEX = "vertex";
+export declare const GATEWAY = "gateway";
+export type Substrate = "direct" | "openrouter" | "litellm" | "azure" | "bedrock" | "vertex" | "gateway";
+/**
+ * Map a client's base URL to a substrate, or `undefined` if unreadable.
+ *
+ * Accepts anything stringable (the OpenAI SDK carries a string, others a `URL`).
+ * An unparseable value returns `undefined` rather than a default — no evidence,
+ * no claim. A host we cannot name reads `gateway`, which says the path was not
+ * the vendor's own without inventing a vendor for it.
+ */
+export declare function fromBaseUrl(baseUrl: unknown): Substrate | undefined;
+/**
+ * Detect the substrate from a live SDK client or one of its resources.
+ *
+ * The JS instrumenters patch a method on a specific client INSTANCE, so the
+ * endpoint is in hand at patch time — a process holding a vendor client and a
+ * router client instruments each separately and each reports correctly. Both
+ * `baseURL` (the JS SDKs' spelling) and `base_url` are read, and the resource's
+ * private `_client` is tried before the object itself so a patched
+ * `chat.completions` resolves as well as a bare client. Every lookup is
+ * defensive: a shape change in a vendor SDK must degrade to "no substrate
+ * recorded", never break the host's call.
+ */
+export declare function fromClient(obj: unknown): Substrate | undefined;
+//# sourceMappingURL=substrate.d.ts.map

package/dist/substrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substrate.d.ts","sourceRoot":"","sources":["../src/substrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,KAAK,UAAU,CAAC;AAC7B,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAoCd;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAuBnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAgB9D"}

package/dist/substrate.js

@@ -0,0 +1,132 @@
+/**
+ * The SUBSTRATE a call travelled through to reach a model — the TypeScript twin
+ * of `margin_meter/substrate.py`.
+ *
+ * `provider` says who owns the model and who bills for it. `substrate` says which
+ * path the request actually took: the vendor's own API, a router like OpenRouter,
+ * a cloud reseller like Bedrock or Azure. The two are orthogonal, and comparing
+ * the same work across paths is the thing a single-substrate router structurally
+ * cannot do.
+ *
+ * Detection is EVIDENCE, not inference. A JS client carries the endpoint it will
+ * call (`baseURL` on the OpenAI and Anthropic SDKs), so an OpenAI client pointed
+ * at `openrouter.ai` is recorded as OpenRouter because that is literally where
+ * the request goes. Nothing is defaulted: a client whose endpoint cannot be read
+ * records NO path, which is the honest reading of an unmeasured dimension.
+ *
+ * Keep the host tables in step with the Python SDK and `margin/substrates.py`.
+ * Three copies of one rule is a real cost, and the alternative — a JS estate that
+ * cannot join the comparison at all — costs more.
+ */
+export const DIRECT = "direct";
+export const OPENROUTER = "openrouter";
+export const LITELLM = "litellm";
+export const AZURE = "azure";
+export const BEDROCK = "bedrock";
+export const VERTEX = "vertex";
+export const GATEWAY = "gateway";
+/** The vendors' own API hosts. A base URL on one of these is the direct path. */
+const DIRECT_HOSTS = [
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+];
+/**
+ * Host patterns that name a substrate outright, most specific first. The third
+ * element allows a REGIONAL PREFIX joined by a hyphen — Vertex serves from
+ * `us-central1-aiplatform.googleapis.com`, a sibling label rather than a
+ * subdomain. Granted per entry, and only where the vendor controls the parent
+ * domain end to end.
+ */
+const HOST_SUBSTRATES = [
+    ["openrouter.ai", OPENROUTER, false],
+    ["openai.azure.com", AZURE, false],
+    ["azure.com", AZURE, false],
+    ["amazonaws.com", BEDROCK, false],
+    ["aiplatform.googleapis.com", VERTEX, true],
+];
+/**
+ * True when `host` IS `domain` or a subdomain of it — never a substring.
+ * `api.openrouter.ai` matches `openrouter.ai`; `openrouter.ai.evil.test` does
+ * not. Substring matching would let any host anyone can register be recorded as
+ * a trusted substrate, corrupting the exact comparison this dimension exists to
+ * make.
+ */
+function hostMatches(host, domain, regionalPrefix) {
+    if (host === domain || host.endsWith("." + domain))
+        return true;
+    return regionalPrefix && host.endsWith("-" + domain);
+}
+/**
+ * Map a client's base URL to a substrate, or `undefined` if unreadable.
+ *
+ * Accepts anything stringable (the OpenAI SDK carries a string, others a `URL`).
+ * An unparseable value returns `undefined` rather than a default — no evidence,
+ * no claim. A host we cannot name reads `gateway`, which says the path was not
+ * the vendor's own without inventing a vendor for it.
+ */
+export function fromBaseUrl(baseUrl) {
+    if (baseUrl == null)
+        return undefined;
+    let raw;
+    try {
+        raw = String(baseUrl).trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw)
+        return undefined;
+    let host;
+    try {
+        host = new URL(raw).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    if (!host)
+        return undefined;
+    for (const [domain, name, regionalPrefix] of HOST_SUBSTRATES) {
+        if (hostMatches(host, domain, regionalPrefix))
+            return name;
+    }
+    for (const domain of DIRECT_HOSTS) {
+        if (hostMatches(host, domain, false))
+            return DIRECT;
+    }
+    return GATEWAY;
+}
+/**
+ * Detect the substrate from a live SDK client or one of its resources.
+ *
+ * The JS instrumenters patch a method on a specific client INSTANCE, so the
+ * endpoint is in hand at patch time — a process holding a vendor client and a
+ * router client instruments each separately and each reports correctly. Both
+ * `baseURL` (the JS SDKs' spelling) and `base_url` are read, and the resource's
+ * private `_client` is tried before the object itself so a patched
+ * `chat.completions` resolves as well as a bare client. Every lookup is
+ * defensive: a shape change in a vendor SDK must degrade to "no substrate
+ * recorded", never break the host's call.
+ */
+export function fromClient(obj) {
+    if (obj == null)
+        return undefined;
+    const o = obj;
+    for (const candidate of [o._client, o.client, o]) {
+        if (candidate == null)
+            continue;
+        let base;
+        try {
+            const c = candidate;
+            base = c.baseURL ?? c.base_url;
+        }
+        catch {
+            continue;
+        }
+        const found = fromBaseUrl(base);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+//# sourceMappingURL=substrate.js.map

package/dist/substrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substrate.js","sourceRoot":"","sources":["../src/substrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AACvC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAC;AAC7B,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AAWjC,iFAAiF;AACjF,MAAM,YAAY,GAAG;IACnB,gBAAgB;IAChB,mBAAmB;IACnB,mCAAmC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,eAAe,GAAwC;IAC3D,CAAC,eAAe,EAAE,UAAU,EAAE,KAAK,CAAC;IACpC,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,CAAC;IAClC,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC;IAC3B,CAAC,eAAe,EAAE,OAAO,EAAE,KAAK,CAAC;IACjC,CAAC,2BAA2B,EAAE,MAAM,EAAE,IAAI,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,MAAc,EAAE,cAAuB;IACxE,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO,cAAc,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACtC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,eAAe,EAAE,CAAC;QAC7D,IAAI,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7D,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAClC,IAAI,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAClC,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,KAAK,MAAM,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;QACjD,IAAI,SAAS,IAAI,IAAI;YAAE,SAAS;QAChC,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,SAAoC,CAAC;YAC/C,IAAI,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "margin-meter",
-  "version": "0.1.0",
-  "description": "Tiny dependency-free client that emits LLM call + outcome economics to a Margin ingest API.",
+  "version": "0.2.0",
+  "description": "Tiny dependency-free client that auto-instruments OpenAI/Anthropic/Gemini and emits LLM call + outcome economics to a Margin ingest API.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",