metergraph 0.6.16 → 0.6.17

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
@@ -28,7 +28,7 @@ active; later explicit calls are ignored and produce one generic warning
28
28
  without option names, token values, or other secrets.
29
29
 
30
30
  ```ts
31
- import { init, wrap, route, trace, modelFor, recordOutcome, withSession } from "metergraph";
31
+ import { init, wrap, route, trace, modelFor, recordOutcome, withContext, withSession } from "metergraph";
32
32
  import OpenAI from "openai";
33
33
 
34
34
  init({ repository: "owner/repository" });
@@ -54,13 +54,37 @@ await withSession("ticket-123", async () => {
54
54
  });
55
55
  ```
56
56
 
57
- Use `withContext({ sessionId, tags }, fn)`, `withSession(sessionId, fn)`, or
57
+ Use `withContext({ userId, sessionId, metadata }, fn)`, `withSession(sessionId, fn)`, or
58
58
  `withTags(tags, fn)` for request and job identity. These callback scopes follow
59
59
  Node's asynchronous execution and isolate concurrent jobs. Legacy
60
60
  `setSession()` and `setTags()` remain available inside an active Metergraph
61
61
  scope, but warn and do nothing when called outside one. Use `setDefaultTags()`
62
62
  only for deliberate process-wide tags; sessions are always execution-scoped.
63
63
 
64
+ ```ts
65
+ await withContext({
66
+ userId: "user-123",
67
+ sessionId: "ticket-123",
68
+ metadata: { customer_id: "customer-123" },
69
+ }, async () => client.chat.completions.create({ model, messages: [] }));
70
+ ```
71
+
72
+ `setUser("user-123")` updates an active scope; `setUser()` clears it until that
73
+ scope exits. Omitted user/session arguments inherit. User identity is never
74
+ process-wide. `metadata` accepts flat string pairs and shares the existing
75
+ `tags` wire field. Valid local metadata overrides local tags and inherited or
76
+ default values; legacy tags still stringify. Captured calls hold copied maps.
77
+
78
+ Invalid attribution is omitted with one generic warning that contains no
79
+ submitted values. User IDs are nonblank strings of at most 512 Unicode code
80
+ points. Metadata keeps up to 32 valid pairs in Unicode key order, keys up to
81
+ 200 and values up to 1,000 code points, within 64 KiB compact UTF-8 JSON. NUL,
82
+ lone surrogates and credential-like keys are omitted. Attribution remains when
83
+ prompt capture is off and is not added to provider requests. Historical batch
84
+ downloads leave `user_id` unset because submission identity is unknown;
85
+ existing batch tags are unchanged. Deploy compatible ingestion before relying
86
+ on user attribution; older collectors may ignore the optional `user_id` field.
87
+
64
88
  ## OpenRouter
65
89
 
66
90
  Point an OpenAI client at `https://openrouter.ai/api/v1` and `wrap()` auto-detects
package/dist/capture.js CHANGED
@@ -680,7 +680,7 @@ class CaptureRuntime {
680
680
  provider,
681
681
  endpoint,
682
682
  request,
683
- context,
683
+ context: { ...context, tags: { ...context.tags } },
684
684
  started: performance.now(),
685
685
  ts: new Date().toISOString(),
686
686
  frames: frames(stack, this.options.appRoot, this.options.skipFrames, this.options.repoRoot),
@@ -833,6 +833,9 @@ class CaptureRuntime {
833
833
  stream_chunks: extra.evidenceChunks ?? extra.responseChunks, stream_complete: extra.stream === true && extra.error === undefined && extra.status !== "error" && extra.status !== "abandoned" }),
834
834
  session_id: state.context.sessionId,
835
835
  conversation_id: state.context.sessionId,
836
+ // Downloading historical batch results does not establish their owner.
837
+ ...(state.context.userId !== undefined && !state.endpoint.startsWith("batch.")
838
+ ? { user_id: state.context.userId } : {}),
836
839
  trace_id: state.traceId,
837
840
  span_id: state.spanId,
838
841
  parent_span_id: state.parentSpanId,
package/dist/context.d.ts CHANGED
@@ -3,6 +3,7 @@ export interface CaptureContext {
3
3
  /** "explicit" when the developer named the route, "derived" when filled in. */
4
4
  routeSource?: "explicit" | "derived";
5
5
  sessionId?: string;
6
+ userId?: string;
6
7
  tags: Record<string, string>;
7
8
  unitName?: string;
8
9
  unitCount?: number;
@@ -29,6 +30,8 @@ export interface ContextOptions {
29
30
  refusalSignal?: boolean;
30
31
  sessionId?: string;
31
32
  tags?: Record<string, unknown>;
33
+ userId?: string;
34
+ metadata?: Record<string, string>;
32
35
  }
33
36
  export declare function contextSnapshot(): CaptureContext;
34
37
  export declare function runWithContext<T>(context: CaptureContext, fn: () => T): T;
@@ -38,5 +41,6 @@ export declare function withTags<T>(tags: Record<string, unknown>, fn: () => T):
38
41
  export declare function setDefaultTags(tags: Record<string, unknown>): void;
39
42
  export declare function route<T>(name: string, fn: () => T | Promise<T>, options?: RouteOptions): Promise<T>;
40
43
  export declare function trace<T>(name: string, fn: () => T | Promise<T>, options?: TraceOptions): T | Promise<T>;
44
+ export declare function setUser(userId?: string): void;
41
45
  export declare function setSession(sessionId?: string): void;
42
46
  export declare function setTags(tags: Record<string, unknown>): void;
package/dist/context.js CHANGED
@@ -8,6 +8,7 @@ exports.withTags = withTags;
8
8
  exports.setDefaultTags = setDefaultTags;
9
9
  exports.route = route;
10
10
  exports.trace = trace;
11
+ exports.setUser = setUser;
11
12
  exports.setSession = setSession;
12
13
  exports.setTags = setTags;
13
14
  const node_async_hooks_1 = require("node:async_hooks");
@@ -16,8 +17,70 @@ const storage = new node_async_hooks_1.AsyncLocalStorage();
16
17
  let defaultTags = {};
17
18
  let warnedSessionOutsideScope = false;
18
19
  let warnedTagsOutsideScope = false;
20
+ let warnedUserOutsideScope = false;
21
+ let warnedAttribution = false;
22
+ const badText = /[\x00\uD800-\uDFFF]/u;
23
+ const credentialKey = /(?:accesskey|apikey|auth|authorization|bearer|clientsecret|cookie|credentials?|encryptionkey|jwt|passwd|password|privatekey|secretkey|secret|sessionkey|signingkey|token)$/;
24
+ // Python/hosted whitespace semantics, including U+0085 and excluding U+FEFF.
25
+ const whitespaceOnly = /^[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*$/u;
26
+ function omitted() {
27
+ if (!warnedAttribution) {
28
+ warnedAttribution = true;
29
+ console.warn("Metergraph omitted invalid or excess attribution; use bounded string identifiers and metadata.");
30
+ }
31
+ }
32
+ function user(value) {
33
+ if (typeof value === "string" && [...value].length <= 512 && !whitespaceOnly.test(value) && !badText.test(value))
34
+ return value;
35
+ if (value !== undefined)
36
+ omitted();
37
+ return undefined;
38
+ }
39
+ function tagValues(values, legacy = false) {
40
+ if (values == null)
41
+ return {};
42
+ if (typeof values !== "object" || Array.isArray(values)) {
43
+ omitted();
44
+ return {};
45
+ }
46
+ const entries = [];
47
+ for (const [key, raw] of Object.entries(values)) {
48
+ let value = raw;
49
+ if (legacy) {
50
+ try {
51
+ value = String(raw);
52
+ }
53
+ catch {
54
+ omitted();
55
+ continue;
56
+ }
57
+ }
58
+ if (key.length > 0 && [...key].length <= 200 && !badText.test(key)
59
+ && !credentialKey.test(key.toLowerCase().replace(/[^a-z0-9]/g, ""))
60
+ && typeof value === "string" && [...value].length <= 1000 && !badText.test(value))
61
+ entries.push([key, value]);
62
+ else
63
+ omitted();
64
+ }
65
+ return Object.fromEntries(entries);
66
+ }
67
+ function boundTags(values) {
68
+ const entries = [];
69
+ let size = 2;
70
+ // UTF-8 byte order equals Unicode codepoint order for valid strings.
71
+ for (const [key, value] of Object.entries(values).sort(([a], [b]) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
72
+ const added = Buffer.byteLength(JSON.stringify({ [key]: value })) - 2 + (entries.length ? 1 : 0);
73
+ if (entries.length === 32 || size + added > 65536) {
74
+ omitted();
75
+ break;
76
+ }
77
+ entries.push([key, value]);
78
+ size += added;
79
+ }
80
+ return Object.fromEntries(entries);
81
+ }
19
82
  function normalizeTags(tags) {
20
- return Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, String(value)]));
83
+ return tagValues(tags, true);
21
84
  }
22
85
  function contextSnapshot() {
23
86
  const value = storage.getStore() ?? { tags: defaultTags };
@@ -31,8 +94,9 @@ function withContext(options, fn) {
31
94
  const child = {
32
95
  ...parent,
33
96
  sessionId: options.sessionId ?? parent.sessionId,
97
+ userId: options.userId === undefined ? parent.userId : user(options.userId) ?? parent.userId,
34
98
  refusalSignal: options.refusalSignal ?? parent.refusalSignal,
35
- tags: { ...parent.tags, ...normalizeTags(options.tags ?? {}) },
99
+ tags: boundTags({ ...parent.tags, ...normalizeTags(options.tags ?? {}), ...tagValues(options.metadata) }),
36
100
  };
37
101
  return storage.run(child, fn);
38
102
  }
@@ -43,7 +107,7 @@ function withTags(tags, fn) {
43
107
  return withContext({ tags }, fn);
44
108
  }
45
109
  function setDefaultTags(tags) {
46
- defaultTags = normalizeTags(tags);
110
+ defaultTags = boundTags(normalizeTags(tags));
47
111
  }
48
112
  async function route(name, fn, options = {}) {
49
113
  const parent = contextSnapshot();
@@ -51,10 +115,10 @@ async function route(name, fn, options = {}) {
51
115
  ...parent,
52
116
  route: name,
53
117
  routeSource: "explicit",
54
- tags: {
118
+ tags: boundTags({
55
119
  ...parent.tags,
56
- ...Object.fromEntries(Object.entries(options.tags ?? {}).map(([key, value]) => [key, String(value)])),
57
- },
120
+ ...normalizeTags(options.tags ?? {}),
121
+ }),
58
122
  unitName: options.unit ?? parent.unitName,
59
123
  unitCount: options.unit ? (options.unitCount ?? 1) : parent.unitCount,
60
124
  captureText: options.captureText ?? parent.captureText,
@@ -75,6 +139,19 @@ function trace(name, fn, options = {}) {
75
139
  };
76
140
  return storage.run(child, fn);
77
141
  }
142
+ function setUser(userId) {
143
+ const store = storage.getStore();
144
+ if (!store) {
145
+ if (!warnedUserOutsideScope) {
146
+ warnedUserOutsideScope = true;
147
+ console.warn("Metergraph setUser() requires an active Metergraph context; use withContext().");
148
+ }
149
+ return;
150
+ }
151
+ const value = user(userId);
152
+ if (userId === undefined || value !== undefined)
153
+ storage.enterWith({ ...store, userId: value, tags: { ...store.tags } });
154
+ }
78
155
  function setSession(sessionId) {
79
156
  const store = storage.getStore();
80
157
  if (!store) {
@@ -95,5 +172,5 @@ function setTags(tags) {
95
172
  }
96
173
  return;
97
174
  }
98
- storage.enterWith({ ...store, tags: { ...store.tags, ...normalizeTags(tags) } });
175
+ storage.enterWith({ ...store, tags: boundTags({ ...store.tags, ...normalizeTags(tags) }) });
99
176
  }
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { route, setDefaultTags, setSession, setTags, trace, withContext, withSession, withTags, type ContextOptions, type RouteOptions, type TraceOptions } from "./context.js";
1
+ import { route, setDefaultTags, setSession, setUser, setTags, trace, withContext, withSession, withTags, type ContextOptions, type RouteOptions, type TraceOptions } from "./context.js";
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";
@@ -67,7 +67,7 @@ export declare const wrapClient: typeof wrap;
67
67
  */
68
68
  export declare function vercelAISDKMiddleware(options: MetergraphOptions & VercelAISDKMiddlewareVersionOptions): VercelAISDKMiddleware<"v2">;
69
69
  export declare function vercelAISDKMiddleware<TVersion extends VercelAISDKSpecificationVersion = "v3">(options?: MetergraphOptions & VercelAISDKMiddlewareSpecificationOptions<TVersion>): VercelAISDKMiddleware<TVersion>;
70
- export { route, setDefaultTags, setSession, setTags, trace, track, withContext, withSession, withTags, };
70
+ export { route, setDefaultTags, setSession, setUser, setTags, trace, track, withContext, withSession, withTags, };
71
71
  export type { ContextOptions, RouteOptions, TraceOptions, TransportMode, VercelAISDKMiddleware, VercelAISDKSpecificationVersion, WrapOptions, };
72
72
  /**
73
73
  * Explicit, opt-in batch-first execution over a provider's Batch API —
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BatchFirstIneligibleError = exports.batchFirst = exports.withTags = exports.withSession = exports.withContext = exports.track = exports.trace = exports.setTags = exports.setSession = exports.setDefaultTags = exports.route = exports.wrapClient = exports.DEFAULT_INGEST_URL = void 0;
3
+ exports.BatchFirstIneligibleError = exports.batchFirst = exports.withTags = exports.withSession = exports.withContext = exports.track = exports.trace = exports.setTags = exports.setUser = exports.setSession = exports.setDefaultTags = exports.route = exports.wrapClient = exports.DEFAULT_INGEST_URL = void 0;
4
4
  exports.init = init;
5
5
  exports.modelFor = modelFor;
6
6
  exports.recordOutcome = recordOutcome;
@@ -16,6 +16,7 @@ const context_js_1 = require("./context.js");
16
16
  Object.defineProperty(exports, "route", { enumerable: true, get: function () { return context_js_1.route; } });
17
17
  Object.defineProperty(exports, "setDefaultTags", { enumerable: true, get: function () { return context_js_1.setDefaultTags; } });
18
18
  Object.defineProperty(exports, "setSession", { enumerable: true, get: function () { return context_js_1.setSession; } });
19
+ Object.defineProperty(exports, "setUser", { enumerable: true, get: function () { return context_js_1.setUser; } });
19
20
  Object.defineProperty(exports, "setTags", { enumerable: true, get: function () { return context_js_1.setTags; } });
20
21
  Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return context_js_1.trace; } });
21
22
  Object.defineProperty(exports, "withContext", { enumerable: true, get: function () { return context_js_1.withContext; } });
package/dist/index.mjs CHANGED
@@ -12,6 +12,7 @@ const {
12
12
  route,
13
13
  setDefaultTags,
14
14
  setSession,
15
+ setUser,
15
16
  setTags,
16
17
  shutdown,
17
18
  trace,
@@ -37,6 +38,7 @@ export {
37
38
  route,
38
39
  setDefaultTags,
39
40
  setSession,
41
+ setUser,
40
42
  setTags,
41
43
  shutdown,
42
44
  trace,
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "0.6.16";
1
+ export declare const SDK_VERSION = "0.6.17";
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.16";
4
+ exports.SDK_VERSION = "0.6.17";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "metergraph",
3
- "version": "0.6.16",
3
+ "version": "0.6.17",
4
4
  "description": "Zero-dependency TypeScript SDK for function-level LLM cost attribution across major LLM providers and frameworks, including OpenAI, Anthropic, Gemini, and Vercel AI SDK.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",