@tanstack/openai-base 0.1.0

package/src/tools/image-generation-tool.ts

@@ -0,0 +1,51 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type ImageGenerationToolConfig = OpenAI.Responses.Tool.ImageGeneration
+
+/** @deprecated Renamed to `ImageGenerationToolConfig`. Will be removed in a future release. */
+export type ImageGenerationTool = ImageGenerationToolConfig
+
+const validatePartialImages = (value: number | undefined) => {
+  if (value !== undefined && (value < 0 || value > 3)) {
+    throw new Error('partial_images must be between 0 and 3')
+  }
+}
+
+/**
+ * Converts a standard Tool to OpenAI ImageGenerationTool format. Spread
+ * `metadata` first, then force `type: 'image_generation'` last — otherwise a
+ * `metadata.type` snuck in by a hand-built tool would shadow the literal and
+ * the dispatcher (which routed by `tool.name`) would emit a tool whose
+ * runtime `type` doesn't match `image_generation`.
+ */
+export function convertImageGenerationToolToAdapterFormat(
+  tool: Tool,
+): ImageGenerationToolConfig {
+  const metadata = tool.metadata as Omit<ImageGenerationToolConfig, 'type'>
+  return {
+    ...metadata,
+    type: 'image_generation',
+  }
+}
+
+/**
+ * Creates a standard Tool from ImageGenerationTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function imageGenerationTool(
+  toolData: Omit<ImageGenerationToolConfig, 'type'>,
+): Tool {
+  validatePartialImages(toolData.partial_images)
+  return {
+    name: 'image_generation',
+    description: 'Generate images based on text descriptions',
+    metadata: {
+      ...toolData,
+    },
+  }
+}
+
+export { validatePartialImages }

package/src/tools/index.ts

@@ -0,0 +1,41 @@
+import type { ApplyPatchToolConfig } from './apply-patch-tool'
+import type { CodeInterpreterToolConfig } from './code-interpreter-tool'
+import type { ComputerUseToolConfig } from './computer-use-tool'
+import type { CustomToolConfig } from './custom-tool'
+import type { FileSearchToolConfig } from './file-search-tool'
+import type { FunctionToolConfig } from './function-tool'
+import type { ImageGenerationToolConfig } from './image-generation-tool'
+import type { LocalShellToolConfig } from './local-shell-tool'
+import type { MCPToolConfig } from './mcp-tool'
+import type { ShellToolConfig } from './shell-tool'
+import type { WebSearchPreviewToolConfig } from './web-search-preview-tool'
+import type { WebSearchToolConfig } from './web-search-tool'
+
+export type OpenAITool =
+  | ApplyPatchToolConfig
+  | CodeInterpreterToolConfig
+  | ComputerUseToolConfig
+  | CustomToolConfig
+  | FileSearchToolConfig
+  | FunctionToolConfig
+  | ImageGenerationToolConfig
+  | LocalShellToolConfig
+  | MCPToolConfig
+  | ShellToolConfig
+  | WebSearchPreviewToolConfig
+  | WebSearchToolConfig
+
+export * from './apply-patch-tool'
+export * from './code-interpreter-tool'
+export * from './computer-use-tool'
+export * from './custom-tool'
+export * from './file-search-tool'
+export * from './function-tool'
+export * from './image-generation-tool'
+export * from './local-shell-tool'
+export * from './mcp-tool'
+export * from './shell-tool'
+export * from './tool-choice'
+export * from './tool-converter'
+export * from './web-search-preview-tool'
+export * from './web-search-tool'

package/src/tools/local-shell-tool.ts

@@ -0,0 +1,32 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type LocalShellToolConfig = OpenAI.Responses.Tool.LocalShell
+
+/** @deprecated Renamed to `LocalShellToolConfig`. Will be removed in a future release. */
+export type LocalShellTool = LocalShellToolConfig
+
+/**
+ * Converts a standard Tool to OpenAI LocalShellTool format
+ */
+export function convertLocalShellToolToAdapterFormat(
+  _tool: Tool,
+): LocalShellToolConfig {
+  return {
+    type: 'local_shell',
+  }
+}
+
+/**
+ * Creates a standard Tool from LocalShellTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function localShellTool(): Tool {
+  return {
+    name: 'local_shell',
+    description: 'Execute local shell commands',
+    metadata: {},
+  }
+}

package/src/tools/mcp-tool.ts

@@ -0,0 +1,47 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type MCPToolConfig = OpenAI.Responses.Tool.Mcp
+
+/** @deprecated Renamed to `MCPToolConfig`. Will be removed in a future release. */
+export type MCPTool = MCPToolConfig
+
+export function validateMCPtool(tool: MCPToolConfig) {
+  if (!tool.server_url && !tool.connector_id) {
+    throw new Error('Either server_url or connector_id must be provided.')
+  }
+  if (tool.connector_id && tool.server_url) {
+    throw new Error('Only one of server_url or connector_id can be provided.')
+  }
+}
+
+/**
+ * Converts a standard Tool to OpenAI MCPTool format
+ */
+export function convertMCPToolToAdapterFormat(tool: Tool): MCPToolConfig {
+  const metadata = tool.metadata as Omit<MCPToolConfig, 'type'>
+
+  const mcpTool: MCPToolConfig = {
+    ...metadata,
+    type: 'mcp',
+  }
+
+  validateMCPtool(mcpTool)
+  return mcpTool
+}
+
+/**
+ * Creates a standard Tool from MCPTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function mcpTool(toolData: Omit<MCPToolConfig, 'type'>): Tool {
+  validateMCPtool({ ...toolData, type: 'mcp' })
+
+  return {
+    name: 'mcp',
+    description: toolData.server_description || '',
+    metadata: toolData,
+  }
+}

package/src/tools/shell-tool.ts

@@ -0,0 +1,30 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type ShellToolConfig = OpenAI.Responses.FunctionShellTool
+
+/** @deprecated Renamed to `ShellToolConfig`. Will be removed in a future release. */
+export type ShellTool = ShellToolConfig
+
+/**
+ * Converts a standard Tool to OpenAI ShellTool format
+ */
+export function convertShellToolToAdapterFormat(_tool: Tool): ShellToolConfig {
+  return {
+    type: 'shell',
+  }
+}
+
+/**
+ * Creates a standard Tool from ShellTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function shellTool(): Tool {
+  return {
+    name: 'shell',
+    description: 'Execute shell commands',
+    metadata: {},
+  }
+}

package/src/tools/tool-choice.ts

@@ -0,0 +1,31 @@
+interface MCPToolChoice {
+  type: 'mcp'
+  server_label: string
+}
+
+interface FunctionToolChoice {
+  type: 'function'
+  name: string
+}
+
+interface CustomToolChoice {
+  type: 'custom'
+  name: string
+}
+
+interface HostedToolChoice {
+  type:
+    | 'file_search'
+    | 'web_search_preview'
+    | 'computer_use_preview'
+    | 'code_interpreter'
+    | 'image_generation'
+    | 'shell'
+    | 'apply_patch'
+}
+
+export type ToolChoice =
+  | MCPToolChoice
+  | FunctionToolChoice
+  | CustomToolChoice
+  | HostedToolChoice

package/src/tools/tool-converter.ts

@@ -0,0 +1,68 @@
+import { convertApplyPatchToolToAdapterFormat } from './apply-patch-tool'
+import { convertCodeInterpreterToolToAdapterFormat } from './code-interpreter-tool'
+import { convertComputerUseToolToAdapterFormat } from './computer-use-tool'
+import { convertCustomToolToAdapterFormat } from './custom-tool'
+import { convertFileSearchToolToAdapterFormat } from './file-search-tool'
+import { convertFunctionToolToAdapterFormat } from './function-tool'
+import { convertImageGenerationToolToAdapterFormat } from './image-generation-tool'
+import { convertLocalShellToolToAdapterFormat } from './local-shell-tool'
+import { convertMCPToolToAdapterFormat } from './mcp-tool'
+import { convertShellToolToAdapterFormat } from './shell-tool'
+import { convertWebSearchPreviewToolToAdapterFormat } from './web-search-preview-tool'
+import { convertWebSearchToolToAdapterFormat } from './web-search-tool'
+import type { OpenAITool } from './index'
+import type { Tool } from '@tanstack/ai'
+
+const SPECIAL_TOOL_NAMES = new Set([
+  'apply_patch',
+  'code_interpreter',
+  'computer_use_preview',
+  'file_search',
+  'image_generation',
+  'local_shell',
+  'mcp',
+  'shell',
+  'web_search_preview',
+  'web_search',
+  'custom',
+])
+
+/**
+ * Converts an array of standard Tools to OpenAI-specific format
+ */
+export function convertToolsToProviderFormat(
+  tools: Array<Tool>,
+): Array<OpenAITool> {
+  return tools.map((tool) => {
+    const toolName = tool.name
+
+    if (SPECIAL_TOOL_NAMES.has(toolName)) {
+      switch (toolName) {
+        case 'apply_patch':
+          return convertApplyPatchToolToAdapterFormat(tool)
+        case 'code_interpreter':
+          return convertCodeInterpreterToolToAdapterFormat(tool)
+        case 'computer_use_preview':
+          return convertComputerUseToolToAdapterFormat(tool)
+        case 'file_search':
+          return convertFileSearchToolToAdapterFormat(tool)
+        case 'image_generation':
+          return convertImageGenerationToolToAdapterFormat(tool)
+        case 'local_shell':
+          return convertLocalShellToolToAdapterFormat(tool)
+        case 'mcp':
+          return convertMCPToolToAdapterFormat(tool)
+        case 'shell':
+          return convertShellToolToAdapterFormat(tool)
+        case 'web_search_preview':
+          return convertWebSearchPreviewToolToAdapterFormat(tool)
+        case 'web_search':
+          return convertWebSearchToolToAdapterFormat(tool)
+        case 'custom':
+          return convertCustomToolToAdapterFormat(tool)
+      }
+    }
+
+    return convertFunctionToolToAdapterFormat(tool)
+  })
+}

package/src/tools/web-search-preview-tool.ts

@@ -0,0 +1,39 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type WebSearchPreviewToolConfig = OpenAI.Responses.WebSearchPreviewTool
+
+/** @deprecated Renamed to `WebSearchPreviewToolConfig`. Will be removed in a future release. */
+export type WebSearchPreviewTool = WebSearchPreviewToolConfig
+
+/**
+ * Converts a standard Tool to OpenAI WebSearchPreviewTool format. Force the
+ * literal `type: 'web_search_preview'` instead of trusting `metadata.type`,
+ * since a hand-authored tool with a missing or wrong `type` would emit a
+ * malformed payload while the dispatcher already routed by `tool.name`.
+ */
+export function convertWebSearchPreviewToolToAdapterFormat(
+  tool: Tool,
+): WebSearchPreviewToolConfig {
+  const metadata = tool.metadata as Omit<WebSearchPreviewToolConfig, 'type'>
+  return {
+    ...metadata,
+    type: 'web_search_preview',
+  }
+}
+
+/**
+ * Creates a standard Tool from WebSearchPreviewTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function webSearchPreviewTool(
+  toolData: WebSearchPreviewToolConfig,
+): Tool {
+  return {
+    name: 'web_search_preview',
+    description: 'Search the web (preview version)',
+    metadata: toolData,
+  }
+}

package/src/tools/web-search-tool.ts

@@ -0,0 +1,38 @@
+import type OpenAI from 'openai'
+import type { Tool } from '@tanstack/ai'
+
+export type WebSearchToolConfig = OpenAI.Responses.WebSearchTool
+
+/** @deprecated Renamed to `WebSearchToolConfig`. Will be removed in a future release. */
+export type WebSearchTool = WebSearchToolConfig
+
+/**
+ * Converts a standard Tool to OpenAI WebSearchTool format. Spread `metadata`
+ * first, then force `type: 'web_search'` last to keep the runtime `type`
+ * matching the discriminator the dispatcher routed by — otherwise a tool
+ * authored by hand with a different `metadata.type` would emit a malformed
+ * payload.
+ */
+export function convertWebSearchToolToAdapterFormat(
+  tool: Tool,
+): WebSearchToolConfig {
+  const metadata = tool.metadata as Omit<WebSearchToolConfig, 'type'>
+  return {
+    ...metadata,
+    type: 'web_search',
+  }
+}
+
+/**
+ * Creates a standard Tool from WebSearchTool parameters.
+ *
+ * Base (non-branded) factory. Providers that need branded return types should
+ * re-wrap this in their own package.
+ */
+export function webSearchTool(toolData: WebSearchToolConfig): Tool {
+  return {
+    name: 'web_search',
+    description: 'Search the web',
+    metadata: toolData,
+  }
+}

package/src/types/config.ts

@@ -0,0 +1,5 @@
+import type { ClientOptions } from 'openai'
+
+export interface OpenAICompatibleClientConfig extends ClientOptions {
+  apiKey: string
+}

package/src/utils/client.ts

@@ -0,0 +1,8 @@
+import OpenAI from 'openai'
+import type { OpenAICompatibleClientConfig } from '../types/config'
+
+export function createOpenAICompatibleClient(
+  config: OpenAICompatibleClientConfig,
+): OpenAI {
+  return new OpenAI(config)
+}

package/src/utils/request-options.ts

@@ -0,0 +1,16 @@
+/**
+ * Extract `headers` and `signal` from a `Request | RequestInit` for the OpenAI
+ * SDK's per-call `RequestOptions`. `Request` exposes `headers` as a `Headers`
+ * instance (HeadersInit-compatible) while `RequestInit` exposes `HeadersInit`
+ * directly — this helper accepts either shape so callers don't need to cast.
+ *
+ * Always returns an object (possibly empty) rather than `undefined` so test
+ * assertions that match the second argument shape via `expect.anything()` /
+ * `expect.objectContaining()` keep working when no request override was set.
+ */
+export function extractRequestOptions(
+  request: Request | RequestInit | undefined,
+): { headers?: HeadersInit; signal?: AbortSignal | null } {
+  if (!request) return {}
+  return { headers: request.headers, signal: request.signal ?? undefined }
+}

package/src/utils/schema-converter.ts

@@ -0,0 +1,89 @@
+/**
+ * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
+ * OpenAI requires:
+ * - All properties must be in the `required` array
+ * - Optional fields should have null added to their type union
+ * - additionalProperties must be false for objects
+ *
+ * @param schema - JSON schema to transform
+ * @param originalRequired - Original required array (to know which fields were optional)
+ * @returns Transformed schema compatible with OpenAI structured output
+ */
+export function makeStructuredOutputCompatible(
+  schema: Record<string, any>,
+  originalRequired?: Array<string>,
+): Record<string, any> {
+  const result = { ...schema }
+  const required =
+    originalRequired ?? (Array.isArray(result.required) ? result.required : [])
+
+  if (result.type === 'object' && result.properties) {
+    const properties = { ...result.properties }
+    const allPropertyNames = Object.keys(properties)
+
+    for (const propName of allPropertyNames) {
+      let prop = properties[propName]
+      const wasOptional = !required.includes(propName)
+
+      // Step 1: Recurse into nested structures
+      if (prop.type === 'object' && prop.properties) {
+        prop = makeStructuredOutputCompatible(prop, prop.required || [])
+      } else if (prop.type === 'array' && prop.items) {
+        prop = {
+          ...prop,
+          items: makeStructuredOutputCompatible(
+            prop.items,
+            prop.items.required || [],
+          ),
+        }
+      } else if (prop.anyOf) {
+        prop = makeStructuredOutputCompatible(prop, prop.required || [])
+      } else if (prop.oneOf) {
+        throw new Error(
+          'oneOf is not supported in OpenAI structured output schemas. Check the supported outputs here: https://platform.openai.com/docs/guides/structured-outputs#supported-types',
+        )
+      }
+
+      // Step 2: Apply null-widening for optional properties (after recursion)
+      if (wasOptional) {
+        if (prop.anyOf) {
+          // For anyOf, add a null variant if not already present
+          if (!prop.anyOf.some((v: any) => v.type === 'null')) {
+            prop = { ...prop, anyOf: [...prop.anyOf, { type: 'null' }] }
+          }
+        } else if (prop.type && !Array.isArray(prop.type)) {
+          prop = { ...prop, type: [prop.type, 'null'] }
+        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {
+          prop = { ...prop, type: [...prop.type, 'null'] }
+        }
+      }
+
+      properties[propName] = prop
+    }
+
+    result.properties = properties
+    result.required = allPropertyNames
+    result.additionalProperties = false
+  }
+
+  if (result.type === 'array' && result.items) {
+    result.items = makeStructuredOutputCompatible(
+      result.items,
+      result.items.required || [],
+    )
+  }
+
+  if (result.anyOf && Array.isArray(result.anyOf)) {
+    result.anyOf = result.anyOf.map((variant) =>
+      makeStructuredOutputCompatible(variant, variant.required || []),
+    )
+  }
+
+  if (result.oneOf) {
+    throw new Error(
+      'oneOf is not supported in OpenAI structured output schemas. Check the supported outputs here: https://platform.openai.com/docs/guides/structured-outputs#supported-types',
+    )
+  }
+
+  return result
+}