@tanstack/openai-base 0.5.0 → 0.6.0

package/dist/esm/usage.js

@@ -0,0 +1,83 @@
+import { buildBaseUsage } from "@tanstack/ai";
+function buildChatCompletionsUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const completionDetails = usage.completion_tokens_details;
+  const completionTokensDetails = {
+    ...completionDetails?.reasoning_tokens ? { reasoningTokens: completionDetails.reasoning_tokens } : {},
+    ...completionDetails?.audio_tokens ? { audioTokens: completionDetails.audio_tokens } : {}
+  };
+  const promptDetails = usage.prompt_tokens_details;
+  const promptTokensDetails = {
+    ...promptDetails?.cached_tokens ? { cachedTokens: promptDetails.cached_tokens } : {},
+    ...promptDetails?.audio_tokens ? { audioTokens: promptDetails.audio_tokens } : {}
+  };
+  if (Object.keys(completionTokensDetails).length > 0) {
+    result.completionTokensDetails = completionTokensDetails;
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails;
+  }
+  const providerUsageDetails = {
+    ...completionDetails?.accepted_prediction_tokens ? {
+      acceptedPredictionTokens: completionDetails.accepted_prediction_tokens
+    } : {},
+    ...completionDetails?.rejected_prediction_tokens ? {
+      rejectedPredictionTokens: completionDetails.rejected_prediction_tokens
+    } : {}
+  };
+  if (Object.keys(providerUsageDetails).length > 0) {
+    result.providerUsageDetails = providerUsageDetails;
+  }
+  return result;
+}
+function buildResponsesUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const cachedTokens = usage.input_tokens_details?.cached_tokens;
+  if (cachedTokens && cachedTokens > 0) {
+    result.promptTokensDetails = {
+      ...result.promptTokensDetails,
+      cachedTokens
+    };
+  }
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens;
+  if (reasoningTokens && reasoningTokens > 0) {
+    result.completionTokensDetails = {
+      ...result.completionTokensDetails,
+      reasoningTokens
+    };
+  }
+  return result;
+}
+function buildImagesUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const inputDetails = usage.input_tokens_details;
+  const promptTokensDetails = {
+    ...inputDetails?.text_tokens ? { textTokens: inputDetails.text_tokens } : {},
+    ...inputDetails?.image_tokens ? { imageTokens: inputDetails.image_tokens } : {}
+  };
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails;
+  }
+  return result;
+}
+export {
+  buildChatCompletionsUsage,
+  buildImagesUsage,
+  buildResponsesUsage
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type OpenAI from 'openai'\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI-compatible Chat\n * Completions `usage` object.\n *\n * Shared by every provider that routes through\n * {@link OpenAIBaseChatCompletionsTextAdapter} (OpenAI Chat Completions, Grok,\n * Groq). Surfaces cached prompt tokens and reasoning/audio detail tokens when\n * the provider reports them. Returns `undefined` when the provider reported no\n * usage object, so callers omit the field rather than fabricating zeroed totals.\n */\nexport function buildChatCompletionsUsage(\n  usage: OpenAI.Chat.Completions.ChatCompletion['usage'] | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.prompt_tokens || 0,\n    completionTokens: usage.completion_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  const completionDetails = usage.completion_tokens_details\n  const completionTokensDetails = {\n    ...(completionDetails?.reasoning_tokens\n      ? { reasoningTokens: completionDetails.reasoning_tokens }\n      : {}),\n    ...(completionDetails?.audio_tokens\n      ? { audioTokens: completionDetails.audio_tokens }\n      : {}),\n  }\n\n  const promptDetails = usage.prompt_tokens_details\n  const promptTokensDetails = {\n    ...(promptDetails?.cached_tokens\n      ? { cachedTokens: promptDetails.cached_tokens }\n      : {}),\n    ...(promptDetails?.audio_tokens\n      ? { audioTokens: promptDetails.audio_tokens }\n      : {}),\n  }\n\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n\n  // Predicted Outputs accepted/rejected counts have no canonical TokenUsage\n  // slot but are still billed (rejected tokens included), so surface them under\n  // providerUsageDetails — matching how the OpenRouter adapter exposes them.\n  const providerUsageDetails = {\n    ...(completionDetails?.accepted_prediction_tokens\n      ? {\n          acceptedPredictionTokens:\n            completionDetails.accepted_prediction_tokens,\n        }\n      : {}),\n    ...(completionDetails?.rejected_prediction_tokens\n      ? {\n          rejectedPredictionTokens:\n            completionDetails.rejected_prediction_tokens,\n        }\n      : {}),\n  }\n  if (Object.keys(providerUsageDetails).length > 0) {\n    result.providerUsageDetails = providerUsageDetails\n  }\n\n  return result\n}\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI Responses API\n * `ResponseUsage` object.\n *\n * Shared by every provider that routes through\n * {@link OpenAIBaseResponsesTextAdapter}. Surfaces cached prompt tokens and\n * reasoning detail tokens when present. Returns `undefined` when the provider\n * reported no usage object, so callers omit the field rather than fabricating\n * zeroed totals.\n */\nexport function buildResponsesUsage(\n  usage: OpenAI.Responses.ResponseUsage | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.input_tokens || 0,\n    completionTokens: usage.output_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  // Despite the SDK types marking these required, they can be undefined at runtime.\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const cachedTokens = usage.input_tokens_details?.cached_tokens\n  if (cachedTokens && cachedTokens > 0) {\n    result.promptTokensDetails = {\n      ...result.promptTokensDetails,\n      cachedTokens,\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens\n  if (reasoningTokens && reasoningTokens > 0) {\n    result.completionTokensDetails = {\n      ...result.completionTokensDetails,\n      reasoningTokens,\n    }\n  }\n\n  return result\n}\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI Images API `usage` object.\n *\n * Shared by every provider that generates images through the OpenAI Images SDK\n * (OpenAI, Grok). Token-billed image models (e.g. gpt-image-1) report an input\n * breakdown of text vs image tokens, which is surfaced on `promptTokensDetails`.\n * Models that don't return usage (e.g. DALL·E) yield `undefined` so callers can\n * omit the field rather than emit zeroed totals.\n */\nexport function buildImagesUsage(\n  usage: OpenAI.Images.ImagesResponse['usage'] | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.input_tokens || 0,\n    completionTokens: usage.output_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  // The SDK types input_tokens_details (and its numeric fields) as required, but\n  // real responses — e.g. from DALL·E or other non-token-billed models — can\n  // omit them, so treat the breakdown as optional.\n  const inputDetails = usage.input_tokens_details as\n    | { text_tokens?: number; image_tokens?: number }\n    | undefined\n  const promptTokensDetails = {\n    ...(inputDetails?.text_tokens\n      ? { textTokens: inputDetails.text_tokens }\n      : {}),\n    ...(inputDetails?.image_tokens\n      ? { imageTokens: inputDetails.image_tokens }\n      : {}),\n  }\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n\n  return result\n}\n"],"names":[],"mappings":";AAcO,SAAS,0BACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,iBAAiB;AAAA,IACrC,kBAAkB,MAAM,qBAAqB;AAAA,IAC7C,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAED,QAAM,oBAAoB,MAAM;AAChC,QAAM,0BAA0B;AAAA,IAC9B,GAAI,mBAAmB,mBACnB,EAAE,iBAAiB,kBAAkB,iBAAA,IACrC,CAAA;AAAA,IACJ,GAAI,mBAAmB,eACnB,EAAE,aAAa,kBAAkB,aAAA,IACjC,CAAA;AAAA,EAAC;AAGP,QAAM,gBAAgB,MAAM;AAC5B,QAAM,sBAAsB;AAAA,IAC1B,GAAI,eAAe,gBACf,EAAE,cAAc,cAAc,cAAA,IAC9B,CAAA;AAAA,IACJ,GAAI,eAAe,eACf,EAAE,aAAa,cAAc,aAAA,IAC7B,CAAA;AAAA,EAAC;AAGP,MAAI,OAAO,KAAK,uBAAuB,EAAE,SAAS,GAAG;AACnD,WAAO,0BAA0B;AAAA,EACnC;AACA,MAAI,OAAO,KAAK,mBAAmB,EAAE,SAAS,GAAG;AAC/C,WAAO,sBAAsB;AAAA,EAC/B;AAKA,QAAM,uBAAuB;AAAA,IAC3B,GAAI,mBAAmB,6BACnB;AAAA,MACE,0BACE,kBAAkB;AAAA,IAAA,IAEtB,CAAA;AAAA,IACJ,GAAI,mBAAmB,6BACnB;AAAA,MACE,0BACE,kBAAkB;AAAA,IAAA,IAEtB,CAAA;AAAA,EAAC;AAEP,MAAI,OAAO,KAAK,oBAAoB,EAAE,SAAS,GAAG;AAChD,WAAO,uBAAuB;AAAA,EAChC;AAEA,SAAO;AACT;AAYO,SAAS,oBACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,gBAAgB;AAAA,IACpC,kBAAkB,MAAM,iBAAiB;AAAA,IACzC,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAID,QAAM,eAAe,MAAM,sBAAsB;AACjD,MAAI,gBAAgB,eAAe,GAAG;AACpC,WAAO,sBAAsB;AAAA,MAC3B,GAAG,OAAO;AAAA,MACV;AAAA,IAAA;AAAA,EAEJ;AAGA,QAAM,kBAAkB,MAAM,uBAAuB;AACrD,MAAI,mBAAmB,kBAAkB,GAAG;AAC1C,WAAO,0BAA0B;AAAA,MAC/B,GAAG,OAAO;AAAA,MACV;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAWO,SAAS,iBACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,gBAAgB;AAAA,IACpC,kBAAkB,MAAM,iBAAiB;AAAA,IACzC,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAKD,QAAM,eAAe,MAAM;AAG3B,QAAM,sBAAsB;AAAA,IAC1B,GAAI,cAAc,cACd,EAAE,YAAY,aAAa,YAAA,IAC3B,CAAA;AAAA,IACJ,GAAI,cAAc,eACd,EAAE,aAAa,aAAa,aAAA,IAC5B,CAAA;AAAA,EAAC;AAEP,MAAI,OAAO,KAAK,mBAAmB,EAAE,SAAS,GAAG;AAC/C,WAAO,sBAAsB;AAAA,EAC/B;AAEA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/openai-base",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared OpenAI SDK base adapters for TanStack AI providers using Chat Completions and Responses APIs.",
   "author": "",
   "license": "MIT",
@@ -39,13 +39,13 @@
     "@tanstack/ai-utils": "0.2.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.24.0"
+    "@tanstack/ai": "^0.25.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.24.0"
+    "@tanstack/ai": "0.25.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/chat-completions-text.ts

@@ -7,6 +7,7 @@ import {
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../utils/request-options'
 import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import { buildChatCompletionsUsage } from '../usage'
 import { convertToolsToChatCompletionsFormat } from './chat-completions-tool-converter'
 import type OpenAI from 'openai'
 import type {
@@ -506,11 +507,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         timestamp,
         finishReason: 'stop',
         ...(lastUsage && {
-          usage: {
-            promptTokens: lastUsage.prompt_tokens,
-            completionTokens: lastUsage.completion_tokens,
-            totalTokens: lastUsage.total_tokens,
-          },
+          usage: buildChatCompletionsUsage(lastUsage),
         }),
       }
     } catch (error: unknown) {
@@ -1063,11 +1060,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
           model: lastModel || options.model,
           timestamp: Date.now(),
           ...(lastUsage && {
-            usage: {
-              promptTokens: lastUsage.prompt_tokens || 0,
-              completionTokens: lastUsage.completion_tokens || 0,
-              totalTokens: lastUsage.total_tokens || 0,
-            },
+            usage: buildChatCompletionsUsage(lastUsage),
           }),
           finishReason,
         }

package/src/adapters/responses-text.ts

@@ -7,6 +7,7 @@ import {
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../utils/request-options'
 import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import { buildResponsesUsage } from '../usage'
 import { convertToolsToResponsesFormat } from './responses-tool-converter'
 import type OpenAI from 'openai'
 import type {
@@ -598,11 +599,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         timestamp,
         finishReason: 'stop',
         ...(usage && {
-          usage: {
-            promptTokens: usage.input_tokens,
-            completionTokens: usage.output_tokens,
-            totalTokens: usage.total_tokens,
-          },
+          usage: buildResponsesUsage(usage),
         }),
       }
     } catch (error: unknown) {
@@ -1511,11 +1508,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             threadId: aguiState.threadId,
             model: model || options.model,
             timestamp: Date.now(),
-            usage: {
-              promptTokens: chunk.response.usage?.input_tokens || 0,
-              completionTokens: chunk.response.usage?.output_tokens || 0,
-              totalTokens: chunk.response.usage?.total_tokens || 0,
-            },
+            // Omit usage entirely when the provider reported none rather than
+            // emitting fabricated zeros (also satisfies exactOptionalPropertyTypes).
+            ...(chunk.response.usage && {
+              usage: buildResponsesUsage(chunk.response.usage),
+            }),
             finishReason,
           }
           runFinishedEmitted = true

package/src/index.ts

@@ -1,4 +1,9 @@
 export { makeStructuredOutputCompatible } from './utils/schema-converter'
+export {
+  buildChatCompletionsUsage,
+  buildResponsesUsage,
+  buildImagesUsage,
+} from './usage'
 export * from './tools/index'
 export { OpenAIBaseChatCompletionsTextAdapter } from './adapters/chat-completions-text'
 export {

package/src/usage.ts

@@ -0,0 +1,159 @@
+import { buildBaseUsage } from '@tanstack/ai'
+import type { TokenUsage } from '@tanstack/ai'
+import type OpenAI from 'openai'
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI-compatible Chat
+ * Completions `usage` object.
+ *
+ * Shared by every provider that routes through
+ * {@link OpenAIBaseChatCompletionsTextAdapter} (OpenAI Chat Completions, Grok,
+ * Groq). Surfaces cached prompt tokens and reasoning/audio detail tokens when
+ * the provider reports them. Returns `undefined` when the provider reported no
+ * usage object, so callers omit the field rather than fabricating zeroed totals.
+ */
+export function buildChatCompletionsUsage(
+  usage: OpenAI.Chat.Completions.ChatCompletion['usage'] | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  const completionDetails = usage.completion_tokens_details
+  const completionTokensDetails = {
+    ...(completionDetails?.reasoning_tokens
+      ? { reasoningTokens: completionDetails.reasoning_tokens }
+      : {}),
+    ...(completionDetails?.audio_tokens
+      ? { audioTokens: completionDetails.audio_tokens }
+      : {}),
+  }
+
+  const promptDetails = usage.prompt_tokens_details
+  const promptTokensDetails = {
+    ...(promptDetails?.cached_tokens
+      ? { cachedTokens: promptDetails.cached_tokens }
+      : {}),
+    ...(promptDetails?.audio_tokens
+      ? { audioTokens: promptDetails.audio_tokens }
+      : {}),
+  }
+
+  if (Object.keys(completionTokensDetails).length > 0) {
+    result.completionTokensDetails = completionTokensDetails
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails
+  }
+
+  // Predicted Outputs accepted/rejected counts have no canonical TokenUsage
+  // slot but are still billed (rejected tokens included), so surface them under
+  // providerUsageDetails — matching how the OpenRouter adapter exposes them.
+  const providerUsageDetails = {
+    ...(completionDetails?.accepted_prediction_tokens
+      ? {
+          acceptedPredictionTokens:
+            completionDetails.accepted_prediction_tokens,
+        }
+      : {}),
+    ...(completionDetails?.rejected_prediction_tokens
+      ? {
+          rejectedPredictionTokens:
+            completionDetails.rejected_prediction_tokens,
+        }
+      : {}),
+  }
+  if (Object.keys(providerUsageDetails).length > 0) {
+    result.providerUsageDetails = providerUsageDetails
+  }
+
+  return result
+}
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI Responses API
+ * `ResponseUsage` object.
+ *
+ * Shared by every provider that routes through
+ * {@link OpenAIBaseResponsesTextAdapter}. Surfaces cached prompt tokens and
+ * reasoning detail tokens when present. Returns `undefined` when the provider
+ * reported no usage object, so callers omit the field rather than fabricating
+ * zeroed totals.
+ */
+export function buildResponsesUsage(
+  usage: OpenAI.Responses.ResponseUsage | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  // Despite the SDK types marking these required, they can be undefined at runtime.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const cachedTokens = usage.input_tokens_details?.cached_tokens
+  if (cachedTokens && cachedTokens > 0) {
+    result.promptTokensDetails = {
+      ...result.promptTokensDetails,
+      cachedTokens,
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens
+  if (reasoningTokens && reasoningTokens > 0) {
+    result.completionTokensDetails = {
+      ...result.completionTokensDetails,
+      reasoningTokens,
+    }
+  }
+
+  return result
+}
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI Images API `usage` object.
+ *
+ * Shared by every provider that generates images through the OpenAI Images SDK
+ * (OpenAI, Grok). Token-billed image models (e.g. gpt-image-1) report an input
+ * breakdown of text vs image tokens, which is surfaced on `promptTokensDetails`.
+ * Models that don't return usage (e.g. DALL·E) yield `undefined` so callers can
+ * omit the field rather than emit zeroed totals.
+ */
+export function buildImagesUsage(
+  usage: OpenAI.Images.ImagesResponse['usage'] | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  // The SDK types input_tokens_details (and its numeric fields) as required, but
+  // real responses — e.g. from DALL·E or other non-token-billed models — can
+  // omit them, so treat the breakdown as optional.
+  const inputDetails = usage.input_tokens_details as
+    | { text_tokens?: number; image_tokens?: number }
+    | undefined
+  const promptTokensDetails = {
+    ...(inputDetails?.text_tokens
+      ? { textTokens: inputDetails.text_tokens }
+      : {}),
+    ...(inputDetails?.image_tokens
+      ? { imageTokens: inputDetails.image_tokens }
+      : {}),
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails
+  }
+
+  return result
+}