refactor(openai-base, ai-utils, ai-openai, ai-grok): address PR #409 review feedback

- Eliminate `toCompatibleConfig` casts: `OpenAIClientConfig`/`GrokClientConfig`
  extend `OpenAICompatibleClientConfig` directly; ai-grok keeps a
  `withGrokDefaults()` helper for its xAI baseURL default.
- Fix tool-call streaming bugs:
  - chat-completions-text: track `emittedAnyToolCallEnd` at outer scope so a
    `tool_calls` finish_reason without a started/ended pair downgrades to `stop`.
  - responses-text: guard `function_call_arguments.delta` with
    `metadata?.started` to match the `.done` handler.
- Schema converter: `originalRequired` is optional and falls back to
  `schema.required`; adapters now pass the unmodified array (not `|| []`)
  so root-level required fields are no longer silently widened to `null`.
- Forward request options: shared `extractRequestOptions` helper threads
  `headers`/`signal` from `Request | RequestInit` into both Chat Completions
  and Responses SDK calls without per-call casts.
- Restore logger calls dropped during the refactor: `logger.request` before
  every SDK call (image/summarize/transcription/tts/video/responses-text/
  chat-completions-text), `logger.provider` per-chunk in both streaming
  adapters, and try/catch + `logger.errors` around `summarize`,
  `summarizeStream`, and `createVideoJob`.
- Move base64 helpers into `@tanstack/ai-utils` (`arrayBufferToBase64`,
  `base64ToArrayBuffer`) with `Uint8Array.toBase64`/`fromBase64` fast paths
  and `Buffer`/`atob`/`btoa` fallbacks; remove the per-adapter copies.
- Add `warnIfLargeMediaBuffer` in video.ts to surface base64-encoding-an-
  unbounded-blob OOM risks on Workers/Lambda.
- Replace `client as any` in video.ts with a typed `getVideosClient()`
  accessor; drop the arbitrary 1-10 cap in base `validateNumberOfImages`.
- Delete dead code: `openai-base/src/types/message-metadata.ts`,
  `provider-options.ts`, and the unused `defineModelMeta` in ai-utils.
- Brand-via-base: every ai-openai tool factory now delegates to its
  `@tanstack/openai-base` counterpart and brands the result, removing ten
  duplicate function bodies.
- `satisfies` instead of `as` for the structured-output response narrow.
- Add `@types/node` dev dep on ai-utils so `process` typechecks.
- Tests: new `media-adapters.test.ts` (image / summarize / transcription /
  tts / video) in openai-base, new `base64.test.ts` (incl. 1.5 MiB
  roundtrip) in ai-utils.

All test suites green: ai-utils 18, openai-base 71, ai-groq 17,
ai-openai 131, ai-grok 53. `test:types`, `test:eslint`, and `build`
clean for every affected package.

Author: AlemTuzlak

packages/typescript/ai-grok/src/adapters/image.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleImageAdapter } from '@tanstack/openai-base'
-import { getGrokApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import {
   validateImageSize,
   validateNumberOfImages,
@@ -41,7 +41,7 @@ export class GrokImageAdapter<
   readonly name = 'grok' as const
 
   constructor(config: GrokImageConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'grok')
+    super(withGrokDefaults(config), model, 'grok')
   }
 
   protected override validatePrompt(options: {

packages/typescript/ai-grok/src/adapters/text.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleChatCompletionsTextAdapter } from '@tanstack/openai-base'
-import { getGrokApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import type {
   GROK_CHAT_MODELS,
   GrokChatModelToolCapabilitiesByName,
@@ -56,7 +56,7 @@ export class GrokTextAdapter<
   readonly name = 'grok' as const
 
   constructor(config: GrokTextConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'grok')
+    super(withGrokDefaults(config), model, 'grok')
   }
 }
 

packages/typescript/ai-grok/src/utils/client.ts

@@ -1,10 +1,7 @@
 import { getApiKeyFromEnv } from '@tanstack/ai-utils'
 import type { OpenAICompatibleClientConfig } from '@tanstack/openai-base'
-import type { ClientOptions } from 'openai'
 
-export interface GrokClientConfig extends ClientOptions {
-  apiKey: string
-}
+export interface GrokClientConfig extends OpenAICompatibleClientConfig {}
 
 /**
  * Gets Grok API key from environment variables
@@ -21,14 +18,14 @@ export function getGrokApiKeyFromEnv(): string {
 }
 
 /**
- * Converts a GrokClientConfig to OpenAICompatibleClientConfig.
- * Sets the default xAI base URL if not already set.
+ * Returns a Grok client config with the default xAI base URL applied
+ * when not already set.
  */
-export function toCompatibleConfig(
+export function withGrokDefaults(
   config: GrokClientConfig,
 ): OpenAICompatibleClientConfig {
   return {
     ...config,
     baseURL: config.baseURL || 'https://api.x.ai/v1',
-  } as unknown as OpenAICompatibleClientConfig
+  }
 }

packages/typescript/ai-grok/src/utils/index.ts

@@ -1,7 +1,7 @@
 export { generateId } from '@tanstack/ai-utils'
 export {
   getGrokApiKeyFromEnv,
-  toCompatibleConfig,
+  withGrokDefaults,
   type GrokClientConfig,
 } from './client'
 export {

packages/typescript/ai-openai/src/adapters/image.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleImageAdapter } from '@tanstack/openai-base'
-import { getOpenAIApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import {
   validateImageSize,
   validateNumberOfImages,
@@ -41,7 +41,7 @@ export class OpenAIImageAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAIImageConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'openai')
+    super(config, model, 'openai')
   }
 
   protected override validatePrompt(options: {

packages/typescript/ai-openai/src/adapters/summarize.ts

@@ -1,7 +1,6 @@
 import { OpenAICompatibleSummarizeAdapter } from '@tanstack/openai-base'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import { OpenAITextAdapter } from './text'
-import type { ChatStreamCapable } from '@tanstack/openai-base'
 import type { OpenAIChatModel } from '../model-meta'
 import type { OpenAIClientConfig } from '../utils/client'
 
@@ -36,16 +35,7 @@ export class OpenAISummarizeAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAISummarizeConfig, model: TModel) {
-    // The text adapter accepts richer provider options than the summarize adapter needs,
-    // but we only pass basic options (model, messages, systemPrompts, etc.) at call time.
-    super(
-      new OpenAITextAdapter(
-        config,
-        model,
-      ) as unknown as ChatStreamCapable<OpenAISummarizeProviderOptions>,
-      model,
-      'openai',
-    )
+    super(new OpenAITextAdapter(config, model), model, 'openai')
   }
 }
 

packages/typescript/ai-openai/src/adapters/text.ts

@@ -1,7 +1,7 @@
 import { OpenAICompatibleResponsesTextAdapter } from '@tanstack/openai-base'
 import { validateTextProviderOptions } from '../text/text-provider-options'
 import { convertToolsToProviderFormat } from '../tools'
-import { getOpenAIApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import type {
   OPENAI_CHAT_MODELS,
   OpenAIChatModel,
@@ -89,7 +89,7 @@ export class OpenAITextAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAITextConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'openai')
+    super(config, model, 'openai')
   }
 
   /**
@@ -99,18 +99,13 @@ export class OpenAITextAdapter<
    * and to apply OpenAI-specific provider option validation.
    */
   protected override mapOptionsToRequest(
-    options: TextOptions,
+    options: TextOptions<TProviderOptions>,
   ): Omit<OpenAI_SDK.Responses.ResponseCreateParams, 'stream'> {
+    // The structural type the validator expects is broader than what
+    // `TProviderOptions` is bound to per-model, so narrow via the internal
+    // shape rather than re-exposing it on the public override signature.
     const modelOptions = options.modelOptions as
-      | Omit<
-          InternalTextProviderOptions,
-          | 'max_output_tokens'
-          | 'tools'
-          | 'metadata'
-          | 'temperature'
-          | 'input'
-          | 'top_p'
-        >
+      | InternalTextProviderOptions
       | undefined
     const input = this.convertMessagesToInput(options.messages)
     if (modelOptions) {

packages/typescript/ai-openai/src/adapters/transcription.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleTranscriptionAdapter } from '@tanstack/openai-base'
-import { getOpenAIApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import type { OpenAITranscriptionModel } from '../model-meta'
 import type { OpenAITranscriptionProviderOptions } from '../audio/transcription-provider-options'
 import type { OpenAIClientConfig } from '../utils/client'
@@ -31,7 +31,7 @@ export class OpenAITranscriptionAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAITranscriptionConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'openai')
+    super(config, model, 'openai')
   }
 
   protected override shouldDefaultToVerbose(model: string): boolean {

packages/typescript/ai-openai/src/adapters/tts.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleTTSAdapter } from '@tanstack/openai-base'
-import { getOpenAIApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import {
   validateAudioInput,
   validateInstructions,
@@ -31,7 +31,7 @@ export class OpenAITTSAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAITTSConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'openai')
+    super(config, model, 'openai')
   }
 
   protected override validateAudioInput(text: string): void {

packages/typescript/ai-openai/src/adapters/video.ts

@@ -1,5 +1,5 @@
 import { OpenAICompatibleVideoAdapter } from '@tanstack/openai-base'
-import { getOpenAIApiKeyFromEnv, toCompatibleConfig } from '../utils/client'
+import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import {
   toApiSeconds,
   validateVideoSeconds,
@@ -48,7 +48,7 @@ export class OpenAIVideoAdapter<
   readonly name = 'openai' as const
 
   constructor(config: OpenAIVideoConfig, model: TModel) {
-    super(toCompatibleConfig(config), model, 'openai')
+    super(config, model, 'openai')
   }
 
   protected override validateVideoSize(model: string, size?: string): void {