metergraph 0.6.4 → 0.6.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -0
- package/dist/capture.d.ts +1 -0
- package/dist/capture.js +2 -0
- package/dist/gateway.d.ts +11 -0
- package/dist/gateway.js +97 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +2 -8
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/wrap.d.ts +10 -1
- package/dist/wrap.js +38 -7
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -46,6 +46,17 @@ Node's asynchronous execution and isolate concurrent jobs. Legacy
|
|
|
46
46
|
scope, but warn and do nothing when called outside one. Use `setDefaultTags()`
|
|
47
47
|
only for deliberate process-wide tags; sessions are always execution-scoped.
|
|
48
48
|
|
|
49
|
+
## OpenRouter
|
|
50
|
+
|
|
51
|
+
Point an OpenAI client at `https://openrouter.ai/api/v1` and `wrap()` auto-detects
|
|
52
|
+
the host, adding `served_model` and — when OpenRouter supplies a valid
|
|
53
|
+
`usage.cost` — `reported_cost_usd` to Chat Completions rows without changing the
|
|
54
|
+
requested model or the capture provider. A trusted custom domain uses
|
|
55
|
+
`wrap(client, { gateway: "openrouter" })`;
|
|
56
|
+
the existing `wrap(client, "openai")` form is unchanged. The runnable
|
|
57
|
+
[Node OpenRouter example](../examples/node-openrouter/) covers requested-vs-served
|
|
58
|
+
model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
|
|
59
|
+
|
|
49
60
|
## Vercel AI SDK
|
|
50
61
|
|
|
51
62
|
Use Metergraph as language-model middleware. It records each actual provider
|
package/dist/capture.d.ts
CHANGED
package/dist/capture.js
CHANGED
|
@@ -4,6 +4,7 @@ exports.CaptureRuntime = exports.DEFAULT_TEXT_MAX_BYTES = void 0;
|
|
|
4
4
|
exports.chunkText = chunkText;
|
|
5
5
|
const node_crypto_1 = require("node:crypto");
|
|
6
6
|
const context_js_1 = require("./context.js");
|
|
7
|
+
const gateway_js_1 = require("./gateway.js");
|
|
7
8
|
const template_js_1 = require("./template.js");
|
|
8
9
|
const version_js_1 = require("./version.js");
|
|
9
10
|
exports.DEFAULT_TEXT_MAX_BYTES = 1024 * 1024;
|
|
@@ -538,6 +539,7 @@ class CaptureRuntime {
|
|
|
538
539
|
provider: state.provider,
|
|
539
540
|
model: state.request.model,
|
|
540
541
|
...usage(response),
|
|
542
|
+
...(0, gateway_js_1.gatewayEvidence)(state.gateway, state.endpoint, response),
|
|
541
543
|
latency_ms: Math.round(performance.now() - state.started),
|
|
542
544
|
status,
|
|
543
545
|
status_code: statusCode,
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface GatewayContract {
|
|
2
|
+
name: string;
|
|
3
|
+
hosts: Set<string>;
|
|
4
|
+
qualifiedEndpoints: Set<string>;
|
|
5
|
+
costSource: string;
|
|
6
|
+
upstreamCostSource: string;
|
|
7
|
+
}
|
|
8
|
+
export declare const GATEWAYS: Record<string, GatewayContract>;
|
|
9
|
+
export declare function detectGateway(client: unknown): string | undefined;
|
|
10
|
+
export declare function resolveGateway(value: unknown): string;
|
|
11
|
+
export declare function gatewayEvidence(gateway: string | undefined, endpoint: string, response: unknown): Record<string, unknown>;
|
package/dist/gateway.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
// Generic OpenAI-compatible gateway detection and billing-evidence extraction.
|
|
3
|
+
// A gateway is described by trusted hosts, the endpoints whose responses are
|
|
4
|
+
// qualified for cost evidence, and fixed provenance strings. OpenRouter is the
|
|
5
|
+
// first qualified contract. The SDK only transports a small scalar allowlist
|
|
6
|
+
// from a response it already observes; it never computes cost, fetches catalog
|
|
7
|
+
// data, or infers a served provider.
|
|
8
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
9
|
+
exports.GATEWAYS = void 0;
|
|
10
|
+
exports.detectGateway = detectGateway;
|
|
11
|
+
exports.resolveGateway = resolveGateway;
|
|
12
|
+
exports.gatewayEvidence = gatewayEvidence;
|
|
13
|
+
const OPENROUTER = {
|
|
14
|
+
name: "openrouter",
|
|
15
|
+
hosts: new Set(["openrouter.ai"]),
|
|
16
|
+
qualifiedEndpoints: new Set(["chat.completions"]),
|
|
17
|
+
costSource: "openrouter.usage.cost",
|
|
18
|
+
upstreamCostSource: "openrouter.usage.cost_details.upstream_inference_cost",
|
|
19
|
+
};
|
|
20
|
+
exports.GATEWAYS = { [OPENROUTER.name]: OPENROUTER };
|
|
21
|
+
const MAX_IDENTIFIER_LEN = 512;
|
|
22
|
+
function get(value, key) {
|
|
23
|
+
return value && typeof value === "object" ? value[key] : undefined;
|
|
24
|
+
}
|
|
25
|
+
// Exact-hostname match over HTTPS, never substring. Paths do not affect it. The
|
|
26
|
+
// caller restricts auto-detection to OpenAI-compatible clients.
|
|
27
|
+
function detectGateway(client) {
|
|
28
|
+
const baseUrl = get(client, "baseURL") ?? get(client, "base_url");
|
|
29
|
+
if (typeof baseUrl !== "string" || !baseUrl.trim())
|
|
30
|
+
return undefined;
|
|
31
|
+
let url;
|
|
32
|
+
try {
|
|
33
|
+
url = new URL(baseUrl.trim());
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
if (url.protocol !== "https:")
|
|
39
|
+
return undefined;
|
|
40
|
+
for (const contract of Object.values(exports.GATEWAYS)) {
|
|
41
|
+
if (contract.hosts.has(url.hostname))
|
|
42
|
+
return contract.name;
|
|
43
|
+
}
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
// The caller value is never interpolated into the error: it may be a secret.
|
|
47
|
+
function resolveGateway(value) {
|
|
48
|
+
const name = String(value).trim().toLowerCase();
|
|
49
|
+
if (!(name in exports.GATEWAYS)) {
|
|
50
|
+
throw new Error("metergraph.wrap() received an unsupported gateway; supported gateways are: "
|
|
51
|
+
+ Object.keys(exports.GATEWAYS).sort().join(", "));
|
|
52
|
+
}
|
|
53
|
+
return name;
|
|
54
|
+
}
|
|
55
|
+
// Finite, non-negative number; booleans (typeof "boolean") and non-numbers are
|
|
56
|
+
// rejected, zero is preserved.
|
|
57
|
+
function billingAmount(value) {
|
|
58
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
|
|
59
|
+
return undefined;
|
|
60
|
+
return value;
|
|
61
|
+
}
|
|
62
|
+
// Identity (gateway, served_model) is emitted for any detected gateway call;
|
|
63
|
+
// cost evidence and its fixed sources only on the contract's qualified
|
|
64
|
+
// endpoints. A source appears only alongside the value it describes. The served
|
|
65
|
+
// provider is never inferred.
|
|
66
|
+
function gatewayEvidence(gateway, endpoint, response) {
|
|
67
|
+
try {
|
|
68
|
+
if (!gateway)
|
|
69
|
+
return {};
|
|
70
|
+
const contract = exports.GATEWAYS[gateway];
|
|
71
|
+
if (!contract)
|
|
72
|
+
return {};
|
|
73
|
+
const evidence = { gateway: contract.name };
|
|
74
|
+
const servedModel = get(response, "model");
|
|
75
|
+
if (typeof servedModel === "string" && servedModel.trim()) {
|
|
76
|
+
evidence.served_model = servedModel.slice(0, MAX_IDENTIFIER_LEN);
|
|
77
|
+
}
|
|
78
|
+
if (contract.qualifiedEndpoints.has(endpoint)) {
|
|
79
|
+
const usage = get(response, "usage");
|
|
80
|
+
const cost = billingAmount(get(usage, "cost"));
|
|
81
|
+
if (cost !== undefined) {
|
|
82
|
+
evidence.reported_cost_usd = cost;
|
|
83
|
+
evidence.reported_cost_source = contract.costSource;
|
|
84
|
+
}
|
|
85
|
+
const details = get(usage, "cost_details");
|
|
86
|
+
const upstream = billingAmount(get(details, "upstream_inference_cost"));
|
|
87
|
+
if (upstream !== undefined) {
|
|
88
|
+
evidence.reported_upstream_cost_usd = upstream;
|
|
89
|
+
evidence.reported_upstream_cost_source = contract.upstreamCostSource;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return evidence;
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return {};
|
|
96
|
+
}
|
|
97
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { route, setDefaultTags, setSession, setTags, trace, withContext, withSes
|
|
|
2
2
|
import { BatchFirstIneligibleError, batchFirst, type BatchFirstMetadata, type BatchFirstPolicy, type BatchFirstProvider, type BatchFirstRequest, type BatchFirstResult, type BatchFirstSource, type LateBatchInfo } from "./batch-first.js";
|
|
3
3
|
import { track } from "./track.js";
|
|
4
4
|
import { type TransportMode, type WaitUntil } from "./transport.js";
|
|
5
|
+
import { type WrapOptions } from "./wrap.js";
|
|
5
6
|
import { type VercelAISDKMiddleware, type VercelAISDKMiddlewareOptions as VercelAISDKCompatibilityOptions, type VercelAISDKMiddlewareSpecificationOptions, type VercelAISDKMiddlewareVersionOptions, type VercelAISDKSpecificationVersion } from "./vercel-ai.js";
|
|
6
7
|
export interface MetergraphOptions {
|
|
7
8
|
token?: string;
|
|
@@ -53,8 +54,11 @@ export declare function wrapHandler<TArgs extends unknown[], TResult>(handler: (
|
|
|
53
54
|
*
|
|
54
55
|
* Calls init() automatically, so with env-var configuration this is the
|
|
55
56
|
* only setup line needed. Call init(...) first to pass options in code.
|
|
57
|
+
* OpenAI-compatible clients pointed at OpenRouter are detected automatically;
|
|
58
|
+
* pass `{ gateway: "openrouter" }` to force it for a trusted custom domain.
|
|
56
59
|
*/
|
|
57
60
|
export declare function wrap<T extends Record<PropertyKey, any>>(client: T, provider?: "openai" | "anthropic" | "google"): T;
|
|
61
|
+
export declare function wrap<T extends Record<PropertyKey, any>>(client: T, options: WrapOptions): T;
|
|
58
62
|
export declare const wrapClient: typeof wrap;
|
|
59
63
|
/**
|
|
60
64
|
* Capture Vercel AI SDK language-model calls through its middleware API.
|
|
@@ -64,7 +68,7 @@ export declare const wrapClient: typeof wrap;
|
|
|
64
68
|
export declare function vercelAISDKMiddleware(options: MetergraphOptions & VercelAISDKMiddlewareVersionOptions): VercelAISDKMiddleware<"v2">;
|
|
65
69
|
export declare function vercelAISDKMiddleware<TVersion extends VercelAISDKSpecificationVersion = "v3">(options?: MetergraphOptions & VercelAISDKMiddlewareSpecificationOptions<TVersion>): VercelAISDKMiddleware<TVersion>;
|
|
66
70
|
export { route, setDefaultTags, setSession, setTags, trace, track, withContext, withSession, withTags, };
|
|
67
|
-
export type { ContextOptions, RouteOptions, TraceOptions, TransportMode, VercelAISDKMiddleware, VercelAISDKSpecificationVersion, };
|
|
71
|
+
export type { ContextOptions, RouteOptions, TraceOptions, TransportMode, VercelAISDKMiddleware, VercelAISDKSpecificationVersion, WrapOptions, };
|
|
68
72
|
/**
|
|
69
73
|
* Explicit, opt-in batch-first execution over a provider's Batch API —
|
|
70
74
|
* never enabled by wrap()/capture defaults or by an environment variable.
|
package/dist/index.js
CHANGED
|
@@ -197,16 +197,10 @@ function wrapHandler(handler) {
|
|
|
197
197
|
}
|
|
198
198
|
};
|
|
199
199
|
}
|
|
200
|
-
|
|
201
|
-
* Wrap an OpenAI, Anthropic, or Google client for capture.
|
|
202
|
-
*
|
|
203
|
-
* Calls init() automatically, so with env-var configuration this is the
|
|
204
|
-
* only setup line needed. Call init(...) first to pass options in code.
|
|
205
|
-
*/
|
|
206
|
-
function wrap(client, provider) {
|
|
200
|
+
function wrap(client, providerOrOptions) {
|
|
207
201
|
if (!initialized)
|
|
208
202
|
init();
|
|
209
|
-
return (0, wrap_js_1.wrap)(client,
|
|
203
|
+
return (0, wrap_js_1.wrap)(client, providerOrOptions);
|
|
210
204
|
}
|
|
211
205
|
exports.wrapClient = wrap;
|
|
212
206
|
function vercelAISDKMiddleware(options = {}) {
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const SDK_VERSION = "0.6.
|
|
1
|
+
export declare const SDK_VERSION = "0.6.5";
|
package/dist/version.js
CHANGED
package/dist/wrap.d.ts
CHANGED
|
@@ -12,6 +12,15 @@ export declare const OPENAI_SEAMS: Seam[];
|
|
|
12
12
|
export declare const ANTHROPIC_SEAMS: Seam[];
|
|
13
13
|
export declare const GOOGLE_SEAMS: Seam[];
|
|
14
14
|
export declare const SEAM_TABLES: Record<string, Seam[]>;
|
|
15
|
-
export
|
|
15
|
+
export type ProviderName = "openai" | "anthropic" | "google";
|
|
16
|
+
export type WrapOptions = {
|
|
17
|
+
provider?: ProviderName;
|
|
18
|
+
gateway?: never;
|
|
19
|
+
} | {
|
|
20
|
+
provider?: Extract<ProviderName, "openai">;
|
|
21
|
+
gateway: "openrouter";
|
|
22
|
+
};
|
|
23
|
+
export declare function wrap<T extends AnyRecord>(client: T, provider?: ProviderName): T;
|
|
24
|
+
export declare function wrap<T extends AnyRecord>(client: T, options: WrapOptions): T;
|
|
16
25
|
export declare const wrapClient: typeof wrap;
|
|
17
26
|
export {};
|
package/dist/wrap.js
CHANGED
|
@@ -6,6 +6,7 @@ exports.getCaptureRuntime = getCaptureRuntime;
|
|
|
6
6
|
exports.wrap = wrap;
|
|
7
7
|
const capture_js_1 = require("./capture.js");
|
|
8
8
|
const context_js_1 = require("./context.js");
|
|
9
|
+
const gateway_js_1 = require("./gateway.js");
|
|
9
10
|
let runtime;
|
|
10
11
|
const seenBatchItems = new Set();
|
|
11
12
|
// Tracks which resource *owners* (e.g. a specific chat.completions instance)
|
|
@@ -404,7 +405,7 @@ function preserveProviderPromise(target, complete, fail) {
|
|
|
404
405
|
},
|
|
405
406
|
});
|
|
406
407
|
}
|
|
407
|
-
function patch(owner, method, provider, endpoint) {
|
|
408
|
+
function patch(owner, method, provider, endpoint, gatewayName) {
|
|
408
409
|
if (!owner || typeof owner[method] !== "function")
|
|
409
410
|
return false;
|
|
410
411
|
if (owner[method].__metergraph__)
|
|
@@ -437,6 +438,7 @@ function patch(owner, method, provider, endpoint) {
|
|
|
437
438
|
let injectedUsage = false;
|
|
438
439
|
if (provider === "openai"
|
|
439
440
|
&& endpoint === "chat.completions"
|
|
441
|
+
&& !gatewayName // a gateway supplies its final usage event itself; no request mutation
|
|
440
442
|
&& incoming.stream === true
|
|
441
443
|
&& incoming.stream_options == null
|
|
442
444
|
&& patchUsage) {
|
|
@@ -444,6 +446,8 @@ function patch(owner, method, provider, endpoint) {
|
|
|
444
446
|
injectedUsage = true;
|
|
445
447
|
}
|
|
446
448
|
const state = startCapture(capture, provider, endpoint, requestFrom(args), new Error().stack);
|
|
449
|
+
if (state && gatewayName)
|
|
450
|
+
state.gateway = gatewayName;
|
|
447
451
|
if (!state) {
|
|
448
452
|
// start faulted: invoke the provider once, return its result unwrapped.
|
|
449
453
|
reentrantOwners.add(owner);
|
|
@@ -551,7 +555,7 @@ function resolveSeam(client, path) {
|
|
|
551
555
|
}
|
|
552
556
|
return obj;
|
|
553
557
|
}
|
|
554
|
-
function applySeams(client, provider) {
|
|
558
|
+
function applySeams(client, provider, gatewayName) {
|
|
555
559
|
const patched = [];
|
|
556
560
|
for (const seam of exports.SEAM_TABLES[provider] ?? []) {
|
|
557
561
|
let owner;
|
|
@@ -561,7 +565,7 @@ function applySeams(client, provider) {
|
|
|
561
565
|
catch {
|
|
562
566
|
continue; // a pathological client property must never break wrap()
|
|
563
567
|
}
|
|
564
|
-
if (owner !== undefined && patch(owner, seam.method, provider, seam.endpoint)) {
|
|
568
|
+
if (owner !== undefined && patch(owner, seam.method, provider, seam.endpoint, gatewayName)) {
|
|
565
569
|
patched.push(`${seam.path}.${seam.method}`);
|
|
566
570
|
}
|
|
567
571
|
}
|
|
@@ -579,16 +583,43 @@ function applyBatchExtras(client, provider) {
|
|
|
579
583
|
}
|
|
580
584
|
return patched;
|
|
581
585
|
}
|
|
582
|
-
|
|
586
|
+
// A gateway override requires the OpenAI-compatible contract, so a provider is
|
|
587
|
+
// accepted only when it is "openai". Unsupported/contradictory setup throws
|
|
588
|
+
// before any provider call, without echoing a URL or credential.
|
|
589
|
+
function validateGatewayConfig(client, provider, gateway) {
|
|
590
|
+
if (gateway === undefined)
|
|
591
|
+
return undefined;
|
|
592
|
+
const overrideGateway = (0, gateway_js_1.resolveGateway)(gateway);
|
|
593
|
+
if (provider !== undefined && String(provider).toLowerCase() !== "openai") {
|
|
594
|
+
throw new Error("metergraph.wrap() gateway requires an OpenAI-compatible provider");
|
|
595
|
+
}
|
|
596
|
+
if (detectProvider(client) !== "openai") {
|
|
597
|
+
throw new Error("metergraph.wrap() gateway requires an OpenAI-compatible client");
|
|
598
|
+
}
|
|
599
|
+
return overrideGateway;
|
|
600
|
+
}
|
|
601
|
+
function wrap(client, providerOrOptions) {
|
|
602
|
+
let provider;
|
|
603
|
+
let gateway;
|
|
604
|
+
if (typeof providerOrOptions === "string") {
|
|
605
|
+
provider = providerOrOptions;
|
|
606
|
+
}
|
|
607
|
+
else if (providerOrOptions && typeof providerOrOptions === "object") {
|
|
608
|
+
provider = providerOrOptions.provider;
|
|
609
|
+
gateway = providerOrOptions.gateway;
|
|
610
|
+
}
|
|
611
|
+
const overrideGateway = validateGatewayConfig(client, provider, gateway);
|
|
583
612
|
try {
|
|
584
613
|
const name = provider ?? detectProvider(client);
|
|
585
|
-
const
|
|
614
|
+
const gatewayName = overrideGateway ?? (name === "openai" ? (0, gateway_js_1.detectGateway)(client) : undefined);
|
|
615
|
+
const patched = applySeams(client, name, gatewayName);
|
|
586
616
|
const patchedCount = patched.length + applyBatchExtras(client, name);
|
|
617
|
+
const label = gatewayName ? `${gatewayName} gateway via ${name}` : name;
|
|
587
618
|
if (!patchedCount) {
|
|
588
|
-
console.warn(`Metergraph found no supported methods on ${
|
|
619
|
+
console.warn(`Metergraph found no supported methods on ${label} client`);
|
|
589
620
|
}
|
|
590
621
|
else {
|
|
591
|
-
console.info(`Metergraph patched ${patchedCount} seam(s) on ${
|
|
622
|
+
console.info(`Metergraph patched ${patchedCount} seam(s) on ${label} client: ${patched.join(", ") || "(batch-only)"}`);
|
|
592
623
|
}
|
|
593
624
|
}
|
|
594
625
|
catch (error) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "metergraph",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.5",
|
|
4
4
|
"description": "Fire-and-forget LLM spend capture for Metergraph",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"test": "npm run build && npm run test:types && npm run test:examples && node --test test/*.test.mjs",
|
|
23
23
|
"test:examples": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext test/ai-sdk-factories.types.ts",
|
|
24
24
|
"test:package": "npm run build && node --test test/package/packed-package.test.mjs",
|
|
25
|
-
"test:types": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext test/ai-sdk-current.types.ts"
|
|
25
|
+
"test:types": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext test/ai-sdk-current.types.ts test/wrap-gateway.types.ts"
|
|
26
26
|
},
|
|
27
27
|
"engines": {
|
|
28
28
|
"node": ">=18"
|