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 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
@@ -28,6 +28,7 @@ export interface CallState {
28
28
  spanId: string;
29
29
  parentSpanId?: string;
30
30
  traceName: string;
31
+ gateway?: string;
31
32
  done: boolean;
32
33
  }
33
34
  export declare function chunkText(chunk: unknown): string | undefined;
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>;
@@ -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, provider);
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.4";
1
+ export declare const SDK_VERSION = "0.6.5";
package/dist/version.js CHANGED
@@ -1,4 +1,4 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SDK_VERSION = void 0;
4
- exports.SDK_VERSION = "0.6.4";
4
+ exports.SDK_VERSION = "0.6.5";
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 declare function wrap<T extends AnyRecord>(client: T, provider?: "openai" | "anthropic" | "google"): T;
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
- function wrap(client, provider) {
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 patched = applySeams(client, name);
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 ${name} client`);
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 ${name} client: ${patched.join(", ") || "(batch-only)"}`);
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.4",
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"