openai 7.3.0 → 7.5.0

package/src/helpers/zod.ts

@@ -1,45 +1,61 @@
-import { ResponseFormatJSONSchema } from '../resources/index';
-import * as z3 from 'zod/v3';
+import type { ResponseFormatJSONSchema } from '../resources/index';
+import type * as z3 from 'zod/v3';
 import * as z4 from 'zod/v4';
 import type * as z4Mini from 'zod/v4-mini';
-import {
-  AutoParseableResponseFormat,
-  AutoParseableTextFormat,
-  AutoParseableTool,
-  makeParseableResponseFormat,
-  makeParseableTextFormat,
-  makeParseableTool,
-} from '../lib/parser';
+import type { AutoParseableResponseFormat, AutoParseableTextFormat, AutoParseableTool } from '../lib/parser';
+import { makeParseableResponseFormat, makeParseableTextFormat, makeParseableTool } from '../lib/parser';
 import { zodToJsonSchema as _zodToJsonSchema } from '../_vendor/zod-to-json-schema';
-import { AutoParseableResponseTool, makeParseableResponseTool } from '../lib/ResponsesParser';
-import { type ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
-import { type RealtimeFunctionTool } from '../resources/realtime/realtime';
-import { toStrictJsonSchema } from '../lib/transform';
-import { JSONSchema } from '../lib/jsonschema';
+import type { AutoParseableResponseTool } from '../lib/ResponsesParser';
+import { makeParseableResponseTool } from '../lib/ResponsesParser';
+import type { ResponseFormatTextJSONSchemaConfig } from '../resources/responses/responses';
+import type { RealtimeFunctionTool } from '../resources/realtime/realtime';
+import { forEachJSONSchemaChild, toStrictJsonSchema } from '../lib/transform';
+import type { JSONSchema } from '../lib/jsonschema';
+import { hasOwn } from '../internal/utils/values';
 
 type ZodV4Schema = z4.ZodType | z4Mini.ZodMiniType;
 type ZodSchema = z3.ZodType | ZodV4Schema;
 
 // The public helpers only need Zod's output type and, when available, parser. Using these small
 // structural shapes avoids expanding Zod's full v3/v4 type graphs in Deno.
+/** Minimal Zod v3, v4, or v4 Mini schema shape accepted by the public parsing helpers. */
 type ZodTypeLike = (
-  | { _output: unknown }
   | {
+      /** Inferred parsed-output type exposed by Zod v3 and compatible Zod schemas. */
+      _output: unknown;
+    }
+  | {
+      /** Zod v4 schema metadata that exposes the inferred parsed-output type. */
       _zod: {
+        /** Inferred value produced after successful schema validation. */
         output: unknown;
       };
     }
 ) & {
+  /** Synchronous schema parser when the validator exposes an instance-level parse method. */
   parse?: (data: unknown) => unknown;
 };
 
-type InferZodType<T extends ZodTypeLike> =
-  T extends { _output: infer Output } ? Output
-  : T extends { _zod: { output: infer Output } } ? Output
-  : never;
+/** Extracts the validated output type from a supported Zod schema. */
+type InferZodType<T extends ZodTypeLike> = T extends {
+  /** Parsed output type exposed directly by Zod v3 and compatible schemas. */
+  _output: infer Output;
+}
+  ? Output
+  : T extends {
+        /** Zod v4 schema metadata containing its inferred parsed-output type. */
+        _zod: {
+          /** Parsed value type inferred from the Zod v4 schema. */
+          output: infer Output;
+        };
+      }
+    ? Output
+    : never;
 
+/** Named reusable Zod schemas extracted into a generated JSON Schema definitions object. */
 type ZodSchemaDefinitions = Record<string, ZodTypeLike>;
 
+/** Optional model-visible metadata and reusable schema definitions for a chat response format. */
 type ZodResponseFormatProps = Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'> & {
   /**
    * Schemas to extract into the generated JSON Schema definitions.
@@ -53,7 +69,7 @@ function encodeSchemaDefinitionRefToken(token: string): string {
 }
 
 function validateSchemaDefinitions(schemaDefinitions: ZodSchemaDefinitions | undefined): void {
-  if (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, '__proto__')) {
+  if (schemaDefinitions && hasOwn(schemaDefinitions, '__proto__')) {
     throw new Error('schemaDefinitions cannot include "__proto__" as a definition name');
   }
 }
@@ -69,21 +85,27 @@ function escapeSchemaDefinitionRefs<T extends object>(
     ]),
   );
 
-  const visit = (value: unknown): void => {
-    if (!value || typeof value !== 'object') return;
+  if (refReplacements.size === 0) {
+    return schema;
+  }
 
-    if (Array.isArray(value)) {
-      for (const child of value) visit(child);
+  const visited = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || visited.has(value)) {
       return;
     }
 
+    visited.add(value);
     const record = value as Record<string, unknown>;
     const ref = record['$ref'];
     if (typeof ref === 'string') {
-      record['$ref'] = refReplacements.get(ref) ?? ref;
+      const replacement = refReplacements.get(ref);
+      if (replacement !== undefined && replacement !== ref) {
+        record['$ref'] = replacement;
+      }
     }
 
-    for (const child of Object.values(record)) visit(child);
+    forEachJSONSchemaChild(record, [], visit);
   };
 
   visit(schema);
@@ -91,8 +113,12 @@ function escapeSchemaDefinitionRefs<T extends object>(
 }
 
 function getZodV3RootName(name: string, schemaDefinitions: ZodSchemaDefinitions | undefined): string {
+  if (!schemaDefinitions) {
+    return name;
+  }
+
   let rootName = name;
-  while (schemaDefinitions && Object.prototype.hasOwnProperty.call(schemaDefinitions, rootName)) {
+  while (hasOwn(schemaDefinitions, rootName)) {
     rootName = `${rootName}_root`;
   }
   return rootName;
@@ -109,9 +135,9 @@ function zodV3ToJsonSchema(
     nameStrategy: 'duplicate-ref',
     $refStrategy: 'extract-to-root',
     nullableStrategy: 'property',
-    ...(options.schemaDefinitions ?
-      { definitions: options.schemaDefinitions as unknown as Record<string, z3.ZodType> }
-    : undefined),
+    ...(options.schemaDefinitions
+      ? { definitions: options.schemaDefinitions as unknown as Record<string, z3.ZodType> }
+      : undefined),
   });
 
   return escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
@@ -222,6 +248,12 @@ function parseZodObject<ZodInput extends ZodTypeLike>(
  *
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
+ *
+ * Supports schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini`.
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional response-format metadata and named reusable schema definitions.
  */
 export function zodResponseFormat<ZodInput extends ZodTypeLike>(
   zodObject: ZodInput,
@@ -239,9 +271,8 @@ export function zodResponseFormat<ZodInput extends ZodTypeLike>(
         ...responseFormatProps,
         name,
         strict: true,
-        schema:
-          isZodV4(zodSchema) ?
-            zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
+        schema: isZodV4(zodSchema)
+          ? zodV4ToJsonSchema(zodSchema, { schemaDefinitions })
           : zodV3ToJsonSchema(zodSchema, { name, schemaDefinitions }),
       },
     },
@@ -249,6 +280,27 @@ export function zodResponseFormat<ZodInput extends ZodTypeLike>(
   );
 }
 
+/**
+ * Creates a strict Responses API text format that validates output with a Zod schema.
+ *
+ * Pass the returned format as `text.format` to `client.responses.parse()` to
+ * populate `response.output_parsed` with the schema's inferred output type.
+ * Calling `responses.create()` with the same format does not enable automatic
+ * parsing. Schemas from `zod/v3`, `zod/v4`, and `zod/v4-mini` are supported.
+ *
+ * ```ts
+ * const response = await client.responses.parse({
+ *   model: 'gpt-5.5',
+ *   input: 'Describe the weather.',
+ *   text: { format: zodTextFormat(Weather, 'weather') },
+ * });
+ * console.log(response.output_parsed);
+ * ```
+ *
+ * @param zodObject Zod schema used to generate and validate structured model output.
+ * @param name Model-visible name of the generated strict JSON Schema.
+ * @param props Optional model-visible text-format metadata, such as a description.
+ */
 export function zodTextFormat<ZodInput extends ZodTypeLike>(
   zodObject: ZodInput,
   name: string,
@@ -272,15 +324,33 @@ export function zodTextFormat<ZodInput extends ZodTypeLike>(
  * Creates a chat completion `function` tool that can be invoked
  * automatically by the chat completion `.runTools()` method or automatically
  * parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the optional callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and optional callback used by `chat.completions.runTools()`.
  */
 export function zodFunction<Parameters extends ZodTypeLike>(options: {
+  /** Model-visible function name used to identify matching tool calls. */
   name: string;
+
+  /** Zod schema used to describe and validate the function's JSON arguments. */
   parameters: Parameters;
+
+  /** Optional callback invoked with validated arguments by chat `runTools()`. */
   function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
+
+  /** Optional model-visible explanation of when and how the function should be used. */
   description?: string | undefined;
 }): AutoParseableTool<{
+  /** Inferred argument type produced by the Zod parameter schema. */
   arguments: InferZodType<Parameters>;
+
+  /** Model-visible name used to match generated function calls. */
   name: string;
+
+  /** Callback signature associated with validated function-call arguments. */
   function: (args: InferZodType<Parameters>) => unknown;
 }> {
   const zodSchema = options.parameters as unknown as ZodSchema;
@@ -291,9 +361,8 @@ export function zodFunction<Parameters extends ZodTypeLike>(options: {
       type: 'function',
       function: {
         name: options.name,
-        parameters:
-          isZodV4(zodSchema) ?
-            zodV4ToJsonSchema(zodSchema)
+        parameters: isZodV4(zodSchema)
+          ? zodV4ToJsonSchema(zodSchema)
           : zodV3ToJsonSchema(zodSchema, { name: options.name }),
         strict: true,
         ...(options.description ? { description: options.description } : undefined),
@@ -306,14 +375,37 @@ export function zodFunction<Parameters extends ZodTypeLike>(options: {
   );
 }
 
+/**
+ * Creates a strict Responses API function tool with Zod-validated arguments.
+ *
+ * Passing this tool to `client.responses.parse()` populates
+ * `function_call.parsed_arguments` with the inferred schema output. Parsing a
+ * response does not invoke the optional callback or submit tool results; the
+ * application remains responsible for its function-execution loop.
+ *
+ * @param options Model-visible function name, Zod parameter schema, optional
+ * description, and optional callback metadata.
+ */
 export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
+  /** Model-visible function name used to identify matching tool calls. */
   name: string;
+
+  /** Zod schema used to describe and validate the function's JSON arguments. */
   parameters: Parameters;
+
+  /** Optional callback retained on the tool; `responses.parse()` does not execute it. */
   function?: ((args: InferZodType<Parameters>) => unknown | Promise<unknown>) | undefined;
+
+  /** Optional model-visible explanation of when and how the function should be used. */
   description?: string | undefined;
 }): AutoParseableResponseTool<{
+  /** Inferred argument type produced by the Zod parameter schema. */
   arguments: InferZodType<Parameters>;
+
+  /** Model-visible name used to match generated function calls. */
   name: string;
+
+  /** Callback signature associated with validated function-call arguments. */
   function: (args: InferZodType<Parameters>) => unknown;
 }> {
   const zodSchema = options.parameters as unknown as ZodSchema;
@@ -322,9 +414,8 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
     {
       type: 'function',
       name: options.name,
-      parameters:
-        isZodV4(zodSchema) ?
-          zodV4ToJsonSchema(zodSchema)
+      parameters: isZodV4(zodSchema)
+        ? zodV4ToJsonSchema(zodSchema)
         : zodV3ToJsonSchema(zodSchema, { name: options.name }),
       strict: true,
       ...(options.description ? { description: options.description } : undefined),
@@ -344,10 +435,17 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
  *
  * This helper only creates the tool definition. Parse function-call arguments
  * from Realtime events with the original Zod schema.
+ *
+ * @param options Model-visible function name, Zod parameter schema, and description.
  */
 export function zodRealtimeFunction<Parameters extends ZodTypeLike>(options: {
+  /** Model-visible function name used to identify Realtime function calls. */
   name: string;
+
+  /** Zod schema converted into the Realtime function's non-strict JSON Schema. */
   parameters: Parameters;
+
+  /** Optional model-visible explanation of when and how the function should be used. */
   description?: string | undefined;
 }): RealtimeFunctionTool {
   const zodSchema = options.parameters as unknown as ZodSchema;
@@ -355,9 +453,8 @@ export function zodRealtimeFunction<Parameters extends ZodTypeLike>(options: {
   return {
     type: 'function',
     name: options.name,
-    parameters:
-      isZodV4(zodSchema) ?
-        zodV4ToNonStrictJsonSchema(zodSchema)
+    parameters: isZodV4(zodSchema)
+      ? zodV4ToNonStrictJsonSchema(zodSchema)
       : zodV3ToNonStrictJsonSchema(zodSchema, { name: options.name }),
     ...(options.description ? { description: options.description } : undefined),
   };

package/src/index.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 export { OpenAI as default } from './client';
 
 export { type Uploadable, toFile, toStreamingFile } from './core/uploads';
@@ -25,5 +23,5 @@ export {
   SubjectTokenProviderError,
 } from './core/error';
 
-export { AzureOpenAI } from './azure';
+export { AzureOpenAI, type AzureClientOptions } from './azure';
 export { BedrockOpenAI, type BedrockClientOptions } from './bedrock';