@x12i/provider-metadata 1.1.0 → 1.2.1

package/README.md

@@ -4,6 +4,8 @@ Pack and open one metadata record. The keys are whatever the caller stored.
 
 `packMetadata` writes the same object for every provider. `openMetadata` reads that object back. A reader passes the log object and gets every stored pair, for any provider and any set of keys.
 
+Repeating concepts are normalized to one canonical key. Vendor prefixes may stay (`openrouter.api_key_name`), and the shared key is always available (`api_key_name`). Grow `METADATA_NORMALIZATION_MAP` as more aliases appear.
+
 The package runs on Node 20 or newer and publishes ESM and CommonJS from the same entry.
 
 ## Install
@@ -30,6 +32,27 @@ const record = openMetadata(wire);
 
 `record` is the full string map. Another caller map, with different keys, packs and opens the same way.
 
+## Normalization
+
+Use `normalizeMetadata` on provider logs, OTLP attribute bags, or nested vendor objects. Known aliases are promoted to canonical keys. The vendor key remains when it was present.
+
+```ts
+import { METADATA_NORMALIZATION_MAP, normalizeMetadata } from "@x12i/provider-metadata";
+
+const record = normalizeMetadata({
+  "trace.metadata.openrouter.api_key_name": "prod-key",
+  "trace.metadata.tenant": "acme"
+});
+// { api_key_name: "prod-key", "openrouter.api_key_name": "prod-key", tenant: "acme" }
+
+record.api_key_name;
+METADATA_NORMALIZATION_MAP.api_key_name; // ["openrouter.api_key_name", ...]
+```
+
+`packMetadata` and `openMetadata` apply the same map. Nested objects under known provider namespaces (for example `openrouter`) are flattened onto the wire. Other nested objects stay off the wire.
+
+Current canonical keys include `api_key_name`, `provider_slug`, `provider_name`, `entity_id`, `user_id`, `finish_reason`, `input_unit_price`, `output_unit_price`, `source`, and `session_id`.
+
 ## Automatic trim
 
 Writers create one packer at initialization. `pack` keeps the record inside 4096 base64 characters. It drops the lowest-priority pair, then the next, and reports every key it removed.
@@ -60,7 +83,7 @@ const record = openMetadata(packed.wire);
 
 `packMetadata` does not drop keys. A record that does not fit throws `METADATA_RECORD_TOO_LARGE`.
 
-`packMetadata(...layers)` accepts `Record<string, unknown> | undefined`. Later layers win on the same key. String, number, and boolean values are stored. A number becomes its decimal string, and a boolean becomes `"true"` or `"false"`. Objects and arrays are omitted. When a later value is an object or array, the earlier scalar for that key stays. An empty result is `undefined`.
+`packMetadata(...layers)` accepts `Record<string, unknown> | undefined`. Later layers win on the same key. String, number, and boolean values are stored. A number becomes its decimal string, and a boolean becomes `"true"` or `"false"`. Nested objects under known provider namespaces are flattened and normalized. Other objects and arrays are omitted. When a later value is an object or array for a non-provider key, the earlier scalar for that key stays. An empty result is `undefined`.
 
 ## Wire object
 
@@ -73,7 +96,7 @@ The stored value is UTF-8 JSON of the string map, with keys sorted, then base64.
 
 The limit is 4096 base64 characters. `createMetadataPacker` drops pairs until the record fits. `packMetadata` throws `METADATA_RECORD_TOO_LARGE` instead.
 
-`openMetadata` joins `m.0`, `m.1`, … in order, decodes the base64, and returns every string in that JSON object. A missing record, or a value that is not an object, returns `{}`.
+`openMetadata` joins `m.0`, `m.1`, … in order, decodes the base64, and returns every string in that JSON object. Pass the wire object, or the JSON string of that object (Cloudflare `cf-aig-metadata`). A missing record, invalid JSON, or a value that is not an object returns `{}`.
 
 These provider slots hold that same object:
 
@@ -82,6 +105,6 @@ These provider slots hold that same object:
 | OpenRouter | Body `metadata` |
 | OpenAI | Responses body `metadata` |
 | Bedrock | `requestMetadata` |
-| Cloudflare | Body `metadata` and the `cf-aig-metadata` header |
+| Cloudflare | Body `metadata` and the `cf-aig-metadata` header (JSON string) |
 
 `@x12i/ai-dispatcher` creates one packer for the caller. The caller sends one map on the request. The dispatcher writes this object onto the provider that runs the call.

package/dist/index.cjs

@@ -20,15 +20,125 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  METADATA_NORMALIZATION_MAP: () => METADATA_NORMALIZATION_MAP,
   METADATA_RECORD_TRIMMED: () => METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE: () => PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS: () => PROVIDER_METADATA_MAX_CHUNKS,
+  canonicalMetadataKey: () => canonicalMetadataKey,
   createMetadataPacker: () => createMetadataPacker,
   metadataTrimWarning: () => metadataTrimWarning,
+  normalizeMetadata: () => normalizeMetadata,
   openMetadata: () => openMetadata,
   packMetadata: () => packMetadata
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/normalize.ts
+var METADATA_NORMALIZATION_MAP = {
+  api_key_name: ["openrouter.api_key_name"],
+  provider_slug: ["openrouter.provider_slug"],
+  provider_name: ["openrouter.provider_name", "gen_ai.provider.name"],
+  entity_id: ["openrouter.entity_id"],
+  user_id: ["openrouter.user_id", "user.id", "cf.user_id"],
+  finish_reason: ["openrouter.finish_reason", "gen_ai.response.finish_reason"],
+  input_unit_price: ["openrouter.input_unit_price"],
+  output_unit_price: ["openrouter.output_unit_price"],
+  source: ["openrouter.source"],
+  session_id: ["session.id"]
+};
+var TRACE_METADATA_PREFIX = "trace.metadata.";
+var SPAN_METADATA_PREFIX = "span.metadata.";
+var ALIAS_TO_CANONICAL = buildAliasIndex(METADATA_NORMALIZATION_MAP);
+var KNOWN_PROVIDER_NAMESPACES = new Set(
+  Object.values(METADATA_NORMALIZATION_MAP).flatMap(
+    (aliases) => aliases.map((alias) => alias.split(".")[0]).filter((part) => Boolean(part))
+  )
+);
+function normalizeMetadata(input) {
+  return promoteCanonicalKeys(flattenMetadataInput(input));
+}
+function collectNormalizedStrings(layers) {
+  const map = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      const asString = asMetadataString(value);
+      if (asString !== void 0) {
+        map[key] = asString;
+        continue;
+      }
+      if (!isRecord(value) || !KNOWN_PROVIDER_NAMESPACES.has(key)) continue;
+      for (const [childKey, childValue] of Object.entries(value)) {
+        if (!childKey) continue;
+        const childString = asMetadataString(childValue);
+        if (childString !== void 0) map[`${key}.${childKey}`] = childString;
+      }
+    }
+  }
+  return promoteCanonicalKeys(map);
+}
+function canonicalMetadataKey(key) {
+  return ALIAS_TO_CANONICAL.get(key) ?? key;
+}
+function promoteCanonicalKeys(flat) {
+  const out = { ...flat };
+  for (const [canonical, aliases] of Object.entries(METADATA_NORMALIZATION_MAP)) {
+    if (Object.prototype.hasOwnProperty.call(out, canonical)) continue;
+    for (const alias of aliases) {
+      const value = out[alias];
+      if (value !== void 0) {
+        out[canonical] = value;
+        break;
+      }
+    }
+  }
+  return out;
+}
+function flattenMetadataInput(input) {
+  if (!isRecord(input)) return {};
+  const flat = {};
+  for (const [rawKey, value] of Object.entries(input)) {
+    const key = stripObservabilityPrefix(rawKey);
+    if (!key) continue;
+    collectFlat(flat, key, value);
+  }
+  return flat;
+}
+function collectFlat(out, key, value) {
+  const asString = asMetadataString(value);
+  if (asString !== void 0) {
+    out[key] = asString;
+    return;
+  }
+  if (!isRecord(value)) return;
+  for (const [childKey, childValue] of Object.entries(value)) {
+    if (!childKey) continue;
+    collectFlat(out, `${key}.${childKey}`, childValue);
+  }
+}
+function stripObservabilityPrefix(key) {
+  if (key.startsWith(TRACE_METADATA_PREFIX)) return key.slice(TRACE_METADATA_PREFIX.length);
+  if (key.startsWith(SPAN_METADATA_PREFIX)) return key.slice(SPAN_METADATA_PREFIX.length);
+  return key;
+}
+function asMetadataString(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildAliasIndex(map) {
+  const index = /* @__PURE__ */ new Map();
+  for (const [canonical, aliases] of Object.entries(map)) {
+    for (const alias of aliases) index.set(alias, canonical);
+  }
+  return index;
+}
+
+// src/index.ts
 var PROVIDER_METADATA_CHUNK_SIZE = 256;
 var PROVIDER_METADATA_MAX_CHUNKS = 16;
 var MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;
@@ -42,7 +152,7 @@ function createMetadataPacker(options) {
   }
   return {
     pack(...layers) {
-      const map = collectStrings(layers);
+      const map = collectNormalizedStrings(layers);
       const dropped = [];
       let encoded = encodeProviderRecord(map);
       while (encoded.tooLarge) {
@@ -68,7 +178,7 @@ function metadataTrimWarning(dropped) {
   };
 }
 function packMetadata(...layers) {
-  const encoded = encodeProviderRecord(collectStrings(layers));
+  const encoded = encodeProviderRecord(collectNormalizedStrings(layers));
   if (encoded.tooLarge) {
     throw new Error(
       `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
@@ -77,32 +187,32 @@ function packMetadata(...layers) {
   return encoded.wire;
 }
 function openMetadata(wire) {
-  if (!isRecord(wire)) return {};
+  const object = coerceWireObject(wire);
+  if (!object) return {};
   const parts = [];
   for (let index = 0; ; index += 1) {
-    const chunk = wire[`m.${index}`];
+    const chunk = object[`m.${index}`];
     if (typeof chunk !== "string") break;
     parts.push(chunk);
   }
   if (!parts.length) return {};
   const parsed = JSON.parse(Buffer.from(parts.join(""), "base64").toString("utf8"));
-  if (!isRecord(parsed)) return {};
+  if (!isRecord2(parsed)) return {};
   const record = {};
   for (const [key, value] of Object.entries(parsed)) {
     if (typeof value === "string") record[key] = value;
   }
-  return record;
+  return normalizeMetadata(record);
 }
-function collectStrings(layers) {
-  const map = {};
-  for (const layer of layers) {
-    if (!layer) continue;
-    for (const [key, value] of Object.entries(layer)) {
-      const asString = asMetadataString(value);
-      if (asString !== void 0) map[key] = asString;
-    }
+function coerceWireObject(wire) {
+  if (isRecord2(wire)) return wire;
+  if (typeof wire !== "string") return void 0;
+  try {
+    const parsed = JSON.parse(wire);
+    return isRecord2(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
   }
-  return map;
 }
 function encodeProviderRecord(map) {
   const keys = Object.keys(map).sort();
@@ -141,22 +251,19 @@ function leastImportantKey(map, rank, unlistedRank) {
   }
   return chosen;
 }
-function asMetadataString(value) {
-  if (typeof value === "string") return value;
-  if (typeof value === "boolean") return value ? "true" : "false";
-  if (typeof value === "number" && Number.isFinite(value)) return String(value);
-  return void 0;
-}
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  METADATA_NORMALIZATION_MAP,
   METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS,
+  canonicalMetadataKey,
   createMetadataPacker,
   metadataTrimWarning,
+  normalizeMetadata,
   openMetadata,
   packMetadata
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction collectStrings(layers: Array<Record<string, unknown> | undefined>): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return map;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/normalize.ts"],"sourcesContent":["export {\r\n  METADATA_NORMALIZATION_MAP,\r\n  canonicalMetadataKey,\r\n  normalizeMetadata,\r\n  type NormalizedMetadataKey\r\n} from \"./normalize\";\r\n\r\nimport { collectNormalizedStrings, normalizeMetadata } from \"./normalize\";\r\n\r\nexport const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectNormalizedStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form.\r\n * Nested objects under known provider namespaces (for example `openrouter`) are\r\n * flattened, and known aliases are promoted to canonical keys\r\n * (`openrouter.api_key_name` also becomes `api_key_name`). Other objects and\r\n * arrays are omitted from the wire record.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectNormalizedStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Accepts the wire object or its JSON string (for example Cloudflare `cf-aig-metadata`).\r\n * Returns every stored pair with known aliases promoted to canonical keys.\r\n * A missing or unreadable record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  const object = coerceWireObject(wire);\r\n  if (!object) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = object[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return normalizeMetadata(record);\r\n}\r\n\r\n/** Wire object, or the JSON string Cloudflare stores in `cf-aig-metadata`. */\r\nfunction coerceWireObject(wire: unknown): Record<string, unknown> | undefined {\r\n  if (isRecord(wire)) return wire;\r\n  if (typeof wire !== \"string\") return undefined;\r\n  try {\r\n    const parsed: unknown = JSON.parse(wire);\r\n    return isRecord(parsed) ? parsed : undefined;\r\n  } catch {\r\n    return undefined;\r\n  }\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n","/**\r\n * Canonical metadata keys shared across providers.\r\n * Each entry lists known provider-namespaced aliases that mean the same thing.\r\n * Prefer the canonical key when reading or writing. Provider aliases may remain.\r\n *\r\n * Grow this map as repeating fields appear under a vendor prefix\r\n * (for example `openrouter.api_key_name` → `api_key_name`).\r\n */\r\nexport const METADATA_NORMALIZATION_MAP = {\r\n  api_key_name: [\"openrouter.api_key_name\"],\r\n  provider_slug: [\"openrouter.provider_slug\"],\r\n  provider_name: [\"openrouter.provider_name\", \"gen_ai.provider.name\"],\r\n  entity_id: [\"openrouter.entity_id\"],\r\n  user_id: [\"openrouter.user_id\", \"user.id\", \"cf.user_id\"],\r\n  finish_reason: [\"openrouter.finish_reason\", \"gen_ai.response.finish_reason\"],\r\n  input_unit_price: [\"openrouter.input_unit_price\"],\r\n  output_unit_price: [\"openrouter.output_unit_price\"],\r\n  source: [\"openrouter.source\"],\r\n  session_id: [\"session.id\"]\r\n} as const satisfies Record<string, readonly string[]>;\r\n\r\nexport type NormalizedMetadataKey = keyof typeof METADATA_NORMALIZATION_MAP;\r\n\r\nconst TRACE_METADATA_PREFIX = \"trace.metadata.\";\r\nconst SPAN_METADATA_PREFIX = \"span.metadata.\";\r\n\r\nconst ALIAS_TO_CANONICAL = buildAliasIndex(METADATA_NORMALIZATION_MAP);\r\n\r\n/** First path segments that may nest provider-specific metadata objects. */\r\nconst KNOWN_PROVIDER_NAMESPACES = new Set(\r\n  Object.values(METADATA_NORMALIZATION_MAP).flatMap((aliases) =>\r\n    aliases.map((alias) => alias.split(\".\")[0]).filter((part): part is string => Boolean(part))\r\n  )\r\n);\r\n\r\n/**\r\n * Flattens a metadata bag and promotes known provider aliases to canonical keys.\r\n *\r\n * Accepts:\r\n * - flat string maps (`{ api_key_name: \"prod\" }`)\r\n * - dotted provider keys (`{ \"openrouter.api_key_name\": \"prod\" }`)\r\n * - nested provider objects (`{ openrouter: { api_key_name: \"prod\" } }`)\r\n * - OTLP attribute bags (`{ \"trace.metadata.openrouter.api_key_name\": \"prod\" }`)\r\n *\r\n * Provider-namespaced keys stay when present. Canonical keys are added when an\r\n * alias is known and the canonical key is missing. An explicit canonical value wins.\r\n */\r\nexport function normalizeMetadata(input: unknown): Record<string, string> {\r\n  return promoteCanonicalKeys(flattenMetadataInput(input));\r\n}\r\n\r\n/**\r\n * Pack-time collection: scalar pairs plus known provider namespaces.\r\n * Arbitrary nested objects stay off the wire (caller response metadata keeps them).\r\n * Known aliases are promoted to canonical keys.\r\n */\r\nexport function collectNormalizedStrings(\r\n  layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) {\r\n        map[key] = asString;\r\n        continue;\r\n      }\r\n      if (!isRecord(value) || !KNOWN_PROVIDER_NAMESPACES.has(key)) continue;\r\n      for (const [childKey, childValue] of Object.entries(value)) {\r\n        if (!childKey) continue;\r\n        const childString = asMetadataString(childValue);\r\n        if (childString !== undefined) map[`${key}.${childKey}`] = childString;\r\n      }\r\n    }\r\n  }\r\n  return promoteCanonicalKeys(map);\r\n}\r\n\r\n/** Returns the canonical key for a known alias, or the key itself. */\r\nexport function canonicalMetadataKey(key: string): string {\r\n  return ALIAS_TO_CANONICAL.get(key) ?? key;\r\n}\r\n\r\nfunction promoteCanonicalKeys(flat: Record<string, string>): Record<string, string> {\r\n  const out: Record<string, string> = { ...flat };\r\n  for (const [canonical, aliases] of Object.entries(METADATA_NORMALIZATION_MAP)) {\r\n    if (Object.prototype.hasOwnProperty.call(out, canonical)) continue;\r\n    for (const alias of aliases) {\r\n      const value = out[alias];\r\n      if (value !== undefined) {\r\n        out[canonical] = value;\r\n        break;\r\n      }\r\n    }\r\n  }\r\n  return out;\r\n}\r\n\r\nfunction flattenMetadataInput(input: unknown): Record<string, string> {\r\n  if (!isRecord(input)) return {};\r\n  const flat: Record<string, string> = {};\r\n  for (const [rawKey, value] of Object.entries(input)) {\r\n    const key = stripObservabilityPrefix(rawKey);\r\n    if (!key) continue;\r\n    collectFlat(flat, key, value);\r\n  }\r\n  return flat;\r\n}\r\n\r\nfunction collectFlat(out: Record<string, string>, key: string, value: unknown): void {\r\n  const asString = asMetadataString(value);\r\n  if (asString !== undefined) {\r\n    out[key] = asString;\r\n    return;\r\n  }\r\n  if (!isRecord(value)) return;\r\n  for (const [childKey, childValue] of Object.entries(value)) {\r\n    if (!childKey) continue;\r\n    collectFlat(out, `${key}.${childKey}`, childValue);\r\n  }\r\n}\r\n\r\nfunction stripObservabilityPrefix(key: string): string {\r\n  if (key.startsWith(TRACE_METADATA_PREFIX)) return key.slice(TRACE_METADATA_PREFIX.length);\r\n  if (key.startsWith(SPAN_METADATA_PREFIX)) return key.slice(SPAN_METADATA_PREFIX.length);\r\n  return key;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n\r\nfunction buildAliasIndex(map: Record<string, readonly string[]>): Map<string, string> {\r\n  const index = new Map<string, string>();\r\n  for (const [canonical, aliases] of Object.entries(map)) {\r\n    for (const alias of aliases) index.set(alias, canonical);\r\n  }\r\n  return index;\r\n}\r\n"],"mappings":"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","names":["isRecord"]}

package/dist/index.d.cts

@@ -1,3 +1,40 @@
+/**
+ * Canonical metadata keys shared across providers.
+ * Each entry lists known provider-namespaced aliases that mean the same thing.
+ * Prefer the canonical key when reading or writing. Provider aliases may remain.
+ *
+ * Grow this map as repeating fields appear under a vendor prefix
+ * (for example `openrouter.api_key_name` → `api_key_name`).
+ */
+declare const METADATA_NORMALIZATION_MAP: {
+    readonly api_key_name: readonly ["openrouter.api_key_name"];
+    readonly provider_slug: readonly ["openrouter.provider_slug"];
+    readonly provider_name: readonly ["openrouter.provider_name", "gen_ai.provider.name"];
+    readonly entity_id: readonly ["openrouter.entity_id"];
+    readonly user_id: readonly ["openrouter.user_id", "user.id", "cf.user_id"];
+    readonly finish_reason: readonly ["openrouter.finish_reason", "gen_ai.response.finish_reason"];
+    readonly input_unit_price: readonly ["openrouter.input_unit_price"];
+    readonly output_unit_price: readonly ["openrouter.output_unit_price"];
+    readonly source: readonly ["openrouter.source"];
+    readonly session_id: readonly ["session.id"];
+};
+type NormalizedMetadataKey = keyof typeof METADATA_NORMALIZATION_MAP;
+/**
+ * Flattens a metadata bag and promotes known provider aliases to canonical keys.
+ *
+ * Accepts:
+ * - flat string maps (`{ api_key_name: "prod" }`)
+ * - dotted provider keys (`{ "openrouter.api_key_name": "prod" }`)
+ * - nested provider objects (`{ openrouter: { api_key_name: "prod" } }`)
+ * - OTLP attribute bags (`{ "trace.metadata.openrouter.api_key_name": "prod" }`)
+ *
+ * Provider-namespaced keys stay when present. Canonical keys are added when an
+ * alias is known and the canonical key is missing. An explicit canonical value wins.
+ */
+declare function normalizeMetadata(input: unknown): Record<string, string>;
+/** Returns the canonical key for a known alias, or the key itself. */
+declare function canonicalMetadataKey(key: string): string;
+
 declare const PROVIDER_METADATA_CHUNK_SIZE = 256;
 declare const PROVIDER_METADATA_MAX_CHUNKS = 16;
 declare const METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
@@ -35,7 +72,11 @@ declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWa
 /**
  * Packs caller maps into one provider metadata object.
  * Later layers win on the same key. String, number, and boolean values are stored.
- * Numbers and booleans are stored as their string form. Objects and arrays are omitted.
+ * Numbers and booleans are stored as their string form.
+ * Nested objects under known provider namespaces (for example `openrouter`) are
+ * flattened, and known aliases are promoted to canonical keys
+ * (`openrouter.api_key_name` also becomes `api_key_name`). Other objects and
+ * arrays are omitted from the wire record.
  * An empty result is `undefined`.
  * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.
  * Writers that should drop pairs instead use `createMetadataPacker`.
@@ -44,8 +85,10 @@ declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWa
 declare function packMetadata(...layers: Array<Record<string, unknown> | undefined>): Record<string, string> | undefined;
 /**
  * Opens the `m.0`, `m.1`, ... object from a provider log.
- * Returns every stored pair. A missing record returns `{}`.
+ * Accepts the wire object or its JSON string (for example Cloudflare `cf-aig-metadata`).
+ * Returns every stored pair with known aliases promoted to canonical keys.
+ * A missing or unreadable record returns `{}`.
  */
 declare function openMetadata(wire: unknown): Record<string, string>;
 
-export { METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, createMetadataPacker, metadataTrimWarning, openMetadata, packMetadata };
+export { METADATA_NORMALIZATION_MAP, METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, type NormalizedMetadataKey, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, canonicalMetadataKey, createMetadataPacker, metadataTrimWarning, normalizeMetadata, openMetadata, packMetadata };

package/dist/index.d.ts

@@ -1,3 +1,40 @@
+/**
+ * Canonical metadata keys shared across providers.
+ * Each entry lists known provider-namespaced aliases that mean the same thing.
+ * Prefer the canonical key when reading or writing. Provider aliases may remain.
+ *
+ * Grow this map as repeating fields appear under a vendor prefix
+ * (for example `openrouter.api_key_name` → `api_key_name`).
+ */
+declare const METADATA_NORMALIZATION_MAP: {
+    readonly api_key_name: readonly ["openrouter.api_key_name"];
+    readonly provider_slug: readonly ["openrouter.provider_slug"];
+    readonly provider_name: readonly ["openrouter.provider_name", "gen_ai.provider.name"];
+    readonly entity_id: readonly ["openrouter.entity_id"];
+    readonly user_id: readonly ["openrouter.user_id", "user.id", "cf.user_id"];
+    readonly finish_reason: readonly ["openrouter.finish_reason", "gen_ai.response.finish_reason"];
+    readonly input_unit_price: readonly ["openrouter.input_unit_price"];
+    readonly output_unit_price: readonly ["openrouter.output_unit_price"];
+    readonly source: readonly ["openrouter.source"];
+    readonly session_id: readonly ["session.id"];
+};
+type NormalizedMetadataKey = keyof typeof METADATA_NORMALIZATION_MAP;
+/**
+ * Flattens a metadata bag and promotes known provider aliases to canonical keys.
+ *
+ * Accepts:
+ * - flat string maps (`{ api_key_name: "prod" }`)
+ * - dotted provider keys (`{ "openrouter.api_key_name": "prod" }`)
+ * - nested provider objects (`{ openrouter: { api_key_name: "prod" } }`)
+ * - OTLP attribute bags (`{ "trace.metadata.openrouter.api_key_name": "prod" }`)
+ *
+ * Provider-namespaced keys stay when present. Canonical keys are added when an
+ * alias is known and the canonical key is missing. An explicit canonical value wins.
+ */
+declare function normalizeMetadata(input: unknown): Record<string, string>;
+/** Returns the canonical key for a known alias, or the key itself. */
+declare function canonicalMetadataKey(key: string): string;
+
 declare const PROVIDER_METADATA_CHUNK_SIZE = 256;
 declare const PROVIDER_METADATA_MAX_CHUNKS = 16;
 declare const METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
@@ -35,7 +72,11 @@ declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWa
 /**
  * Packs caller maps into one provider metadata object.
  * Later layers win on the same key. String, number, and boolean values are stored.
- * Numbers and booleans are stored as their string form. Objects and arrays are omitted.
+ * Numbers and booleans are stored as their string form.
+ * Nested objects under known provider namespaces (for example `openrouter`) are
+ * flattened, and known aliases are promoted to canonical keys
+ * (`openrouter.api_key_name` also becomes `api_key_name`). Other objects and
+ * arrays are omitted from the wire record.
  * An empty result is `undefined`.
  * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.
  * Writers that should drop pairs instead use `createMetadataPacker`.
@@ -44,8 +85,10 @@ declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWa
 declare function packMetadata(...layers: Array<Record<string, unknown> | undefined>): Record<string, string> | undefined;
 /**
  * Opens the `m.0`, `m.1`, ... object from a provider log.
- * Returns every stored pair. A missing record returns `{}`.
+ * Accepts the wire object or its JSON string (for example Cloudflare `cf-aig-metadata`).
+ * Returns every stored pair with known aliases promoted to canonical keys.
+ * A missing or unreadable record returns `{}`.
  */
 declare function openMetadata(wire: unknown): Record<string, string>;
 
-export { METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, createMetadataPacker, metadataTrimWarning, openMetadata, packMetadata };
+export { METADATA_NORMALIZATION_MAP, METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, type NormalizedMetadataKey, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, canonicalMetadataKey, createMetadataPacker, metadataTrimWarning, normalizeMetadata, openMetadata, packMetadata };

package/dist/index.js

@@ -1,3 +1,108 @@
+// src/normalize.ts
+var METADATA_NORMALIZATION_MAP = {
+  api_key_name: ["openrouter.api_key_name"],
+  provider_slug: ["openrouter.provider_slug"],
+  provider_name: ["openrouter.provider_name", "gen_ai.provider.name"],
+  entity_id: ["openrouter.entity_id"],
+  user_id: ["openrouter.user_id", "user.id", "cf.user_id"],
+  finish_reason: ["openrouter.finish_reason", "gen_ai.response.finish_reason"],
+  input_unit_price: ["openrouter.input_unit_price"],
+  output_unit_price: ["openrouter.output_unit_price"],
+  source: ["openrouter.source"],
+  session_id: ["session.id"]
+};
+var TRACE_METADATA_PREFIX = "trace.metadata.";
+var SPAN_METADATA_PREFIX = "span.metadata.";
+var ALIAS_TO_CANONICAL = buildAliasIndex(METADATA_NORMALIZATION_MAP);
+var KNOWN_PROVIDER_NAMESPACES = new Set(
+  Object.values(METADATA_NORMALIZATION_MAP).flatMap(
+    (aliases) => aliases.map((alias) => alias.split(".")[0]).filter((part) => Boolean(part))
+  )
+);
+function normalizeMetadata(input) {
+  return promoteCanonicalKeys(flattenMetadataInput(input));
+}
+function collectNormalizedStrings(layers) {
+  const map = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      const asString = asMetadataString(value);
+      if (asString !== void 0) {
+        map[key] = asString;
+        continue;
+      }
+      if (!isRecord(value) || !KNOWN_PROVIDER_NAMESPACES.has(key)) continue;
+      for (const [childKey, childValue] of Object.entries(value)) {
+        if (!childKey) continue;
+        const childString = asMetadataString(childValue);
+        if (childString !== void 0) map[`${key}.${childKey}`] = childString;
+      }
+    }
+  }
+  return promoteCanonicalKeys(map);
+}
+function canonicalMetadataKey(key) {
+  return ALIAS_TO_CANONICAL.get(key) ?? key;
+}
+function promoteCanonicalKeys(flat) {
+  const out = { ...flat };
+  for (const [canonical, aliases] of Object.entries(METADATA_NORMALIZATION_MAP)) {
+    if (Object.prototype.hasOwnProperty.call(out, canonical)) continue;
+    for (const alias of aliases) {
+      const value = out[alias];
+      if (value !== void 0) {
+        out[canonical] = value;
+        break;
+      }
+    }
+  }
+  return out;
+}
+function flattenMetadataInput(input) {
+  if (!isRecord(input)) return {};
+  const flat = {};
+  for (const [rawKey, value] of Object.entries(input)) {
+    const key = stripObservabilityPrefix(rawKey);
+    if (!key) continue;
+    collectFlat(flat, key, value);
+  }
+  return flat;
+}
+function collectFlat(out, key, value) {
+  const asString = asMetadataString(value);
+  if (asString !== void 0) {
+    out[key] = asString;
+    return;
+  }
+  if (!isRecord(value)) return;
+  for (const [childKey, childValue] of Object.entries(value)) {
+    if (!childKey) continue;
+    collectFlat(out, `${key}.${childKey}`, childValue);
+  }
+}
+function stripObservabilityPrefix(key) {
+  if (key.startsWith(TRACE_METADATA_PREFIX)) return key.slice(TRACE_METADATA_PREFIX.length);
+  if (key.startsWith(SPAN_METADATA_PREFIX)) return key.slice(SPAN_METADATA_PREFIX.length);
+  return key;
+}
+function asMetadataString(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildAliasIndex(map) {
+  const index = /* @__PURE__ */ new Map();
+  for (const [canonical, aliases] of Object.entries(map)) {
+    for (const alias of aliases) index.set(alias, canonical);
+  }
+  return index;
+}
+
 // src/index.ts
 var PROVIDER_METADATA_CHUNK_SIZE = 256;
 var PROVIDER_METADATA_MAX_CHUNKS = 16;
@@ -12,7 +117,7 @@ function createMetadataPacker(options) {
   }
   return {
     pack(...layers) {
-      const map = collectStrings(layers);
+      const map = collectNormalizedStrings(layers);
       const dropped = [];
       let encoded = encodeProviderRecord(map);
       while (encoded.tooLarge) {
@@ -38,7 +143,7 @@ function metadataTrimWarning(dropped) {
   };
 }
 function packMetadata(...layers) {
-  const encoded = encodeProviderRecord(collectStrings(layers));
+  const encoded = encodeProviderRecord(collectNormalizedStrings(layers));
   if (encoded.tooLarge) {
     throw new Error(
       `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
@@ -47,32 +152,32 @@ function packMetadata(...layers) {
   return encoded.wire;
 }
 function openMetadata(wire) {
-  if (!isRecord(wire)) return {};
+  const object = coerceWireObject(wire);
+  if (!object) return {};
   const parts = [];
   for (let index = 0; ; index += 1) {
-    const chunk = wire[`m.${index}`];
+    const chunk = object[`m.${index}`];
     if (typeof chunk !== "string") break;
     parts.push(chunk);
   }
   if (!parts.length) return {};
   const parsed = JSON.parse(Buffer.from(parts.join(""), "base64").toString("utf8"));
-  if (!isRecord(parsed)) return {};
+  if (!isRecord2(parsed)) return {};
   const record = {};
   for (const [key, value] of Object.entries(parsed)) {
     if (typeof value === "string") record[key] = value;
   }
-  return record;
+  return normalizeMetadata(record);
 }
-function collectStrings(layers) {
-  const map = {};
-  for (const layer of layers) {
-    if (!layer) continue;
-    for (const [key, value] of Object.entries(layer)) {
-      const asString = asMetadataString(value);
-      if (asString !== void 0) map[key] = asString;
-    }
+function coerceWireObject(wire) {
+  if (isRecord2(wire)) return wire;
+  if (typeof wire !== "string") return void 0;
+  try {
+    const parsed = JSON.parse(wire);
+    return isRecord2(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
   }
-  return map;
 }
 function encodeProviderRecord(map) {
   const keys = Object.keys(map).sort();
@@ -111,21 +216,18 @@ function leastImportantKey(map, rank, unlistedRank) {
   }
   return chosen;
 }
-function asMetadataString(value) {
-  if (typeof value === "string") return value;
-  if (typeof value === "boolean") return value ? "true" : "false";
-  if (typeof value === "number" && Number.isFinite(value)) return String(value);
-  return void 0;
-}
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export {
+  METADATA_NORMALIZATION_MAP,
   METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS,
+  canonicalMetadataKey,
   createMetadataPacker,
   metadataTrimWarning,
+  normalizeMetadata,
   openMetadata,
   packMetadata
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction collectStrings(layers: Array<Record<string, unknown> | undefined>): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return map;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":";AAAO,IAAM,+BAA+B;AACrC,IAAM,+BAA+B;AAE5C,IAAM,qBAAqB,+BAA+B;AAEnD,IAAM,0BAA0B;AAgChC,SAAS,qBAAqB,SAAiD;AACpF,QAAM,WAAW,CAAC,GAAI,SAAS,YAAY,CAAC,CAAE;AAC9C,QAAM,OAAO,oBAAI,IAAoB;AACrC,WAAS,QAAQ,GAAG,QAAQ,SAAS,QAAQ,SAAS,GAAG;AACvD,UAAM,MAAM,SAAS,KAAK;AAC1B,QAAI,QAAQ,UAAa,CAAC,KAAK,IAAI,GAAG,EAAG,MAAK,IAAI,KAAK,KAAK;AAAA,EAC9D;AAEA,SAAO;AAAA,IACL,QAAQ,QAAQ;AACd,YAAM,MAAM,eAAe,MAAM;AACjC,YAAM,UAAoB,CAAC;AAC3B,UAAI,UAAU,qBAAqB,GAAG;AACtC,aAAO,QAAQ,UAAU;AACvB,cAAM,SAAS,kBAAkB,KAAK,MAAM,SAAS,MAAM;AAC3D,YAAI,CAAC,OAAQ;AACb,eAAO,IAAI,MAAM;AACjB,gBAAQ,KAAK,MAAM;AACnB,kBAAU,qBAAqB,GAAG;AAAA,MACpC;AACA,aAAO;AAAA,QACL,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAAA,QAC7C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAGO,SAAS,oBAAoB,SAA6D;AAC/F,MAAI,CAAC,QAAQ,OAAQ,QAAO;AAC5B,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,sDAAsD,QAAQ,KAAK,IAAI,CAAC;AAAA,IACjF,SAAS,EAAE,SAAS,CAAC,GAAG,OAAO,EAAE;AAAA,EACnC;AACF;AAWO,SAAS,gBACX,QACiC;AACpC,QAAM,UAAU,qBAAqB,eAAe,MAAM,CAAC;AAC3D,MAAI,QAAQ,UAAU;AACpB,UAAM,IAAI;AAAA,MACR,mDAAmD,QAAQ,aAAa,sCAAsC,kBAAkB;AAAA,IAClI;AAAA,EACF;AACA,SAAO,QAAQ;AACjB;AAMO,SAAS,aAAa,MAAuC;AAClE,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,CAAC;AAC7B,QAAM,QAAkB,CAAC;AACzB,WAAS,QAAQ,KAAK,SAAS,GAAG;AAChC,UAAM,QAAQ,KAAK,KAAK,KAAK,EAAE;AAC/B,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,KAAK,KAAK;AAAA,EAClB;AACA,MAAI,CAAC,MAAM,OAAQ,QAAO,CAAC;AAC3B,QAAM,SAAkB,KAAK,MAAM,OAAO,KAAK,MAAM,KAAK,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,CAAC;AACzF,MAAI,CAAC,SAAS,MAAM,EAAG,QAAO,CAAC;AAC/B,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,OAAO,UAAU,SAAU,QAAO,GAAG,IAAI;AAAA,EAC/C;AACA,SAAO;AACT;AAEA,SAAS,eAAe,QAA4E;AAClG,QAAM,MAA8B,CAAC;AACrC,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,MAAO;AACZ,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,YAAM,WAAW,iBAAiB,KAAK;AACvC,UAAI,aAAa,OAAW,KAAI,GAAG,IAAI;AAAA,IACzC;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,qBAAqB,KAI5B;AACA,QAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,MAAI,CAAC,KAAK,OAAQ,QAAO,EAAE,eAAe,GAAG,UAAU,MAAM;AAC7D,QAAM,UAAkC,CAAC;AACzC,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,GAAG;AACrB,QAAI,UAAU,OAAW,SAAQ,GAAG,IAAI;AAAA,EAC1C;AACA,QAAM,UAAU,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,QAAQ;AAC9E,MAAI,KAAK,KAAK,QAAQ,SAAS,4BAA4B,IAAI,8BAA8B;AAC3F,WAAO,EAAE,eAAe,QAAQ,QAAQ,UAAU,KAAK;AAAA,EACzD;AACA,QAAM,OAA+B,CAAC;AACtC,WAAS,QAAQ,GAAG,QAAQ,KAAK,KAAK,QAAQ,SAAS,4BAA4B,GAAG,SAAS,GAAG;AAChG,SAAK,KAAK,KAAK,EAAE,IAAI,QAAQ;AAAA,MAC3B,QAAQ;AAAA,OACP,QAAQ,KAAK;AAAA,IAChB;AAAA,EACF;AACA,SAAO,EAAE,MAAM,eAAe,QAAQ,QAAQ,UAAU,MAAM;AAChE;AAEA,SAAS,kBACP,KACA,MACA,cACoB;AACpB,MAAI;AACJ,MAAI,aAAa;AACjB,MAAI,aAAa;AACjB,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC9C,UAAM,UAAU,KAAK,IAAI,GAAG,KAAK;AACjC,UAAM,OAAO,MAAM;AACnB,UAAM,gBAAgB,WAAW,UAC5B,UAAU,cACT,YAAY,cAAc,OAAO,cACjC,YAAY,cAAc,SAAS,cAAc,MAAM;AAC7D,QAAI,eAAe;AACjB,eAAS;AACT,mBAAa;AACb,mBAAa;AAAA,IACf;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAoC;AAC5D,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,SAAS;AACxD,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,OAAO,KAAK;AAC5E,SAAO;AACT;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;","names":[]}
+{"version":3,"sources":["../src/normalize.ts","../src/index.ts"],"sourcesContent":["/**\r\n * Canonical metadata keys shared across providers.\r\n * Each entry lists known provider-namespaced aliases that mean the same thing.\r\n * Prefer the canonical key when reading or writing. Provider aliases may remain.\r\n *\r\n * Grow this map as repeating fields appear under a vendor prefix\r\n * (for example `openrouter.api_key_name` → `api_key_name`).\r\n */\r\nexport const METADATA_NORMALIZATION_MAP = {\r\n  api_key_name: [\"openrouter.api_key_name\"],\r\n  provider_slug: [\"openrouter.provider_slug\"],\r\n  provider_name: [\"openrouter.provider_name\", \"gen_ai.provider.name\"],\r\n  entity_id: [\"openrouter.entity_id\"],\r\n  user_id: [\"openrouter.user_id\", \"user.id\", \"cf.user_id\"],\r\n  finish_reason: [\"openrouter.finish_reason\", \"gen_ai.response.finish_reason\"],\r\n  input_unit_price: [\"openrouter.input_unit_price\"],\r\n  output_unit_price: [\"openrouter.output_unit_price\"],\r\n  source: [\"openrouter.source\"],\r\n  session_id: [\"session.id\"]\r\n} as const satisfies Record<string, readonly string[]>;\r\n\r\nexport type NormalizedMetadataKey = keyof typeof METADATA_NORMALIZATION_MAP;\r\n\r\nconst TRACE_METADATA_PREFIX = \"trace.metadata.\";\r\nconst SPAN_METADATA_PREFIX = \"span.metadata.\";\r\n\r\nconst ALIAS_TO_CANONICAL = buildAliasIndex(METADATA_NORMALIZATION_MAP);\r\n\r\n/** First path segments that may nest provider-specific metadata objects. */\r\nconst KNOWN_PROVIDER_NAMESPACES = new Set(\r\n  Object.values(METADATA_NORMALIZATION_MAP).flatMap((aliases) =>\r\n    aliases.map((alias) => alias.split(\".\")[0]).filter((part): part is string => Boolean(part))\r\n  )\r\n);\r\n\r\n/**\r\n * Flattens a metadata bag and promotes known provider aliases to canonical keys.\r\n *\r\n * Accepts:\r\n * - flat string maps (`{ api_key_name: \"prod\" }`)\r\n * - dotted provider keys (`{ \"openrouter.api_key_name\": \"prod\" }`)\r\n * - nested provider objects (`{ openrouter: { api_key_name: \"prod\" } }`)\r\n * - OTLP attribute bags (`{ \"trace.metadata.openrouter.api_key_name\": \"prod\" }`)\r\n *\r\n * Provider-namespaced keys stay when present. Canonical keys are added when an\r\n * alias is known and the canonical key is missing. An explicit canonical value wins.\r\n */\r\nexport function normalizeMetadata(input: unknown): Record<string, string> {\r\n  return promoteCanonicalKeys(flattenMetadataInput(input));\r\n}\r\n\r\n/**\r\n * Pack-time collection: scalar pairs plus known provider namespaces.\r\n * Arbitrary nested objects stay off the wire (caller response metadata keeps them).\r\n * Known aliases are promoted to canonical keys.\r\n */\r\nexport function collectNormalizedStrings(\r\n  layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) {\r\n        map[key] = asString;\r\n        continue;\r\n      }\r\n      if (!isRecord(value) || !KNOWN_PROVIDER_NAMESPACES.has(key)) continue;\r\n      for (const [childKey, childValue] of Object.entries(value)) {\r\n        if (!childKey) continue;\r\n        const childString = asMetadataString(childValue);\r\n        if (childString !== undefined) map[`${key}.${childKey}`] = childString;\r\n      }\r\n    }\r\n  }\r\n  return promoteCanonicalKeys(map);\r\n}\r\n\r\n/** Returns the canonical key for a known alias, or the key itself. */\r\nexport function canonicalMetadataKey(key: string): string {\r\n  return ALIAS_TO_CANONICAL.get(key) ?? key;\r\n}\r\n\r\nfunction promoteCanonicalKeys(flat: Record<string, string>): Record<string, string> {\r\n  const out: Record<string, string> = { ...flat };\r\n  for (const [canonical, aliases] of Object.entries(METADATA_NORMALIZATION_MAP)) {\r\n    if (Object.prototype.hasOwnProperty.call(out, canonical)) continue;\r\n    for (const alias of aliases) {\r\n      const value = out[alias];\r\n      if (value !== undefined) {\r\n        out[canonical] = value;\r\n        break;\r\n      }\r\n    }\r\n  }\r\n  return out;\r\n}\r\n\r\nfunction flattenMetadataInput(input: unknown): Record<string, string> {\r\n  if (!isRecord(input)) return {};\r\n  const flat: Record<string, string> = {};\r\n  for (const [rawKey, value] of Object.entries(input)) {\r\n    const key = stripObservabilityPrefix(rawKey);\r\n    if (!key) continue;\r\n    collectFlat(flat, key, value);\r\n  }\r\n  return flat;\r\n}\r\n\r\nfunction collectFlat(out: Record<string, string>, key: string, value: unknown): void {\r\n  const asString = asMetadataString(value);\r\n  if (asString !== undefined) {\r\n    out[key] = asString;\r\n    return;\r\n  }\r\n  if (!isRecord(value)) return;\r\n  for (const [childKey, childValue] of Object.entries(value)) {\r\n    if (!childKey) continue;\r\n    collectFlat(out, `${key}.${childKey}`, childValue);\r\n  }\r\n}\r\n\r\nfunction stripObservabilityPrefix(key: string): string {\r\n  if (key.startsWith(TRACE_METADATA_PREFIX)) return key.slice(TRACE_METADATA_PREFIX.length);\r\n  if (key.startsWith(SPAN_METADATA_PREFIX)) return key.slice(SPAN_METADATA_PREFIX.length);\r\n  return key;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n\r\nfunction buildAliasIndex(map: Record<string, readonly string[]>): Map<string, string> {\r\n  const index = new Map<string, string>();\r\n  for (const [canonical, aliases] of Object.entries(map)) {\r\n    for (const alias of aliases) index.set(alias, canonical);\r\n  }\r\n  return index;\r\n}\r\n","export {\r\n  METADATA_NORMALIZATION_MAP,\r\n  canonicalMetadataKey,\r\n  normalizeMetadata,\r\n  type NormalizedMetadataKey\r\n} from \"./normalize\";\r\n\r\nimport { collectNormalizedStrings, normalizeMetadata } from \"./normalize\";\r\n\r\nexport const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectNormalizedStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form.\r\n * Nested objects under known provider namespaces (for example `openrouter`) are\r\n * flattened, and known aliases are promoted to canonical keys\r\n * (`openrouter.api_key_name` also becomes `api_key_name`). Other objects and\r\n * arrays are omitted from the wire record.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectNormalizedStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Accepts the wire object or its JSON string (for example Cloudflare `cf-aig-metadata`).\r\n * Returns every stored pair with known aliases promoted to canonical keys.\r\n * A missing or unreadable record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  const object = coerceWireObject(wire);\r\n  if (!object) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = object[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return normalizeMetadata(record);\r\n}\r\n\r\n/** Wire object, or the JSON string Cloudflare stores in `cf-aig-metadata`. */\r\nfunction coerceWireObject(wire: unknown): Record<string, unknown> | undefined {\r\n  if (isRecord(wire)) return wire;\r\n  if (typeof wire !== \"string\") return undefined;\r\n  try {\r\n    const parsed: unknown = JSON.parse(wire);\r\n    return isRecord(parsed) ? parsed : undefined;\r\n  } catch {\r\n    return undefined;\r\n  }\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":"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","names":["isRecord"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x12i/provider-metadata",
-  "version": "1.1.0",
-  "description": "Pack and open one provider metadata record. The same wire object for every provider.",
+  "version": "1.2.1",
+  "description": "Pack, open, and normalize one provider metadata record. The same wire object for every provider.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",