openai 7.16.0 → 7.17.0

package/src/lib/parser.ts

@@ -77,7 +77,9 @@ export function makeParseableResponseFormat<ParsedT>(
 ): AutoParseableResponseFormat<ParsedT> {
   const obj = { ...response_format, type: 'json_schema' as const };
   obj.json_schema = { ...obj.json_schema };
-  delete (obj as { toJSON?: unknown }).toJSON;
+  // SAFETY: The fresh copy may retain a caller-provided toJSON property; deleting it prevents serialization from replacing the validated schema.
+  delete (obj as typeof obj & { toJSON?: unknown }).toJSON;
+  // SAFETY: The fresh copy may retain a caller-provided toJSON property; deleting it prevents serialization from replacing the validated schema.
   delete (obj.json_schema as { toJSON?: unknown }).toJSON;
 
   Object.defineProperties(obj, {
@@ -91,6 +93,7 @@ export function makeParseableResponseFormat<ParsedT>(
     },
   });
 
+  // SAFETY: Object.defineProperties installed the parser brand and callbacks required by the returned helper type.
   return obj as AutoParseableResponseFormat<ParsedT>;
 }
 
@@ -111,7 +114,8 @@ export function makeParseableTextFormat<ParsedT>(
   parser: (content: string) => ParsedT,
 ): AutoParseableTextFormat<ParsedT> {
   const obj = { ...response_format, type: 'json_schema' as const };
-  delete (obj as { toJSON?: unknown }).toJSON;
+  // SAFETY: The fresh copy may retain a caller-provided toJSON property; deleting it prevents serialization from replacing the validated schema.
+  delete (obj as typeof obj & { toJSON?: unknown }).toJSON;
 
   Object.defineProperties(obj, {
     $brand: {
@@ -124,6 +128,7 @@ export function makeParseableTextFormat<ParsedT>(
     },
   });
 
+  // SAFETY: Object.defineProperties installed the parser brand and callbacks required by the returned helper type.
   return obj as AutoParseableTextFormat<ParsedT>;
 }
 
@@ -150,6 +155,7 @@ export function isAutoParsableResponseFormat<ParsedT>(
  * {@link ExtractParsedContentFromParams} cannot drift apart.
  */
 export function isParseableResponseFormat(format: unknown): boolean {
+  // SAFETY: Only the optional discriminator is read; arbitrary input is not treated as a validated response-format schema.
   return isAutoParsableResponseFormat(format) || (format as { type?: string } | null)?.type === 'json_schema';
 }
 
@@ -170,10 +176,12 @@ export function parseResponseFormatContent<ParsedT>(format: unknown, content: st
     '$parseRaw' in format &&
     typeof format.$parseRaw === 'function'
   ) {
+    // SAFETY: The format's captured parser owns the ParsedT output contract; this function forwards its result without coercion.
     return format.$parseRaw(content) as ParsedT;
   }
 
   try {
+    // SAFETY: ParsedT represents the caller's response schema; JSON syntax is checked here and schema validation remains with the configured format.
     return JSON.parse(content) as ParsedT;
   } catch (error) {
     if (error instanceof SyntaxError) {
@@ -197,6 +205,7 @@ type ToolOptions = {
 /** A Chat Completions function tool with an argument parser and optional executable callback. */
 export type AutoParseableTool<
   OptionsT extends ToolOptions,
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- This public conditional type detects any callable callback without constraining its return type.
   HasFunction = OptionsT['function'] extends (...args: never[]) => unknown ? true : false,
 > = ChatCompletionFunctionTool & {
   /** Type-only marker for parsed tool arguments; this property does not exist at runtime. */
@@ -268,6 +277,7 @@ export function makeParseableTool<OptionsT extends ToolOptions>(
     },
   });
 
+  // SAFETY: Object.defineProperties installed the parser brand and callbacks required by the returned helper type.
   return obj as AutoParseableTool<OptionsT, boolean>;
 }
 
@@ -366,16 +376,19 @@ function parseToolCall<Params extends ChatCompletionCreateParams>(
   }
 
   if (toolCall.type !== 'function') {
+    // SAFETY: This branch handles unsupported JavaScript discriminators that the current TypeScript union excludes; the value is only used in the error.
     const unsupportedType = (toolCall as { type: string }).type;
     throw new OpenAIError(
       `Currently only \`function\` and \`custom\` tool calls are supported; Received \`${unsupportedType}\``,
     );
   }
 
+  // SAFETY: The find predicate checks the function-tool discriminator before matching its name; the cast retains that narrowing through find.
   const inputTool = params.tools?.find(
     (inputTool) =>
       isChatCompletionFunctionTool(inputTool) && inputTool.function?.name === toolCall.function.name,
   ) as ChatCompletionFunctionTool | undefined; // TS doesn't narrow based on isChatCompletionTool
+  // oxlint-disable-next-line anti-slop/no-known-value-widening -- The parser callback may return any value; null only represents an unparsed tool call.
   let parsedArguments: unknown = null;
   if (isAutoParsableTool(inputTool)) {
     parsedArguments = inputTool.$parseRaw(toolCall.function.arguments);
@@ -460,6 +473,7 @@ export function validateInputTools(tools: ChatCompletionCreateParamsBase['tools'
     }
 
     if (tool.type !== 'function') {
+      // SAFETY: This branch handles unsupported JavaScript discriminators that the current TypeScript union excludes; the value is only used in the error.
       const unsupportedType = (tool as { type: string }).type;
       throw new OpenAIError(
         `Currently only \`function\` and \`custom\` tool types are supported; Received \`${unsupportedType}\``,

package/src/lib/responses/ResponseInputItems.ts

@@ -70,13 +70,16 @@ export function toResponseInputItem(item: ResponseInputItemLike): ResponseInputI
       if (item.role !== 'developer') {
         return null;
       }
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       return stripCreatedBy(item) as ResponseAdditionalToolsInputItem;
     }
 
     case 'shell_call_output': {
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       const output: ResponseShellCallOutputInputItem['output'] = item.output.map(
         (chunk) => stripCreatedBy(chunk) as ResponseFunctionShellCallOutputContent,
       );
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       return {
         ...(stripCreatedBy(item) as ResponseShellCallOutputInputItem),
         output,
@@ -84,12 +87,14 @@ export function toResponseInputItem(item: ResponseInputItemLike): ResponseInputI
     }
 
     case 'computer_call_output': {
+      // SAFETY: Runtime API items may contain the output-only created_by field; this view permits removing it without changing the declared input type.
       const { created_by: _createdBy, ...withoutCreatedBy } = item as typeof item & {
         created_by?: string;
       };
       if (withoutCreatedBy.status === 'failed') {
         return null;
       }
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       return withoutCreatedBy as ResponseComputerCallOutputInputItem;
     }
 
@@ -97,11 +102,13 @@ export function toResponseInputItem(item: ResponseInputItemLike): ResponseInputI
       if ('status' in item && item.status !== 'completed') {
         return null;
       }
+      // SAFETY: Runtime API items may contain the output-only created_by field; this view permits removing it without changing the declared input type.
       const {
         created_by: _createdBy,
         status: _status,
         ...inputItem
       } = item as typeof item & { created_by?: string; status?: string };
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       return inputItem as ResponseCustomToolCallOutputInputItem;
     }
 
@@ -132,6 +139,7 @@ export function toResponseInputItem(item: ResponseInputItemLike): ResponseInputI
     case 'web_search_call':
     case null:
     case undefined: {
+      // SAFETY: The item discriminator selects its matching input type; removing output-only provenance fields preserves the remaining wire input fields.
       return stripCreatedBy(item) as ResponseInputItem;
     }
 
@@ -146,11 +154,14 @@ function stripCreatedBy<T extends object>(item: T): T {
     return item;
   }
 
+  // SAFETY: Runtime API items may contain the output-only created_by field; this view permits removing it without changing the declared input type.
   const { created_by: _createdBy, ...rest } = item as T & { created_by?: string };
+  // SAFETY: Only the optional output provenance property was removed; every field belonging to the generic input contract remains.
   return rest as T;
 }
 
 function assertNever(value: never): never {
+  // SAFETY: This always-throwing path reports a runtime discriminator outside the current TypeScript union without accepting it as a valid item.
   const type = (value as { type?: unknown }).type;
   throw new TypeError(`Unsupported response item type: ${String(type)}`);
 }

package/src/lib/responses/ResponseStream.ts

@@ -8,7 +8,7 @@ import type {
 } from '../../resources/responses/responses';
 import type { RequestOptions } from '../../internal/request-options';
 import type { ReadableStream } from '../../internal/shim-types';
-import { APIError, APIUserAbortError, OpenAIError } from '../../error';
+import { APIError, OpenAIError } from '../../error';
 import type OpenAI from '../../index';
 import { EventStream } from '../EventStream';
 import type { BaseEvents } from '../EventStream';
@@ -110,6 +110,7 @@ export class ResponseStream<ParsedT = null>
     params: ResponseStreamParams,
     options?: RequestOptions,
   ): ResponseStream<ParsedT> {
+    // SAFETY: The runner's request path forces stream: true; the constructor retains the same caller parameters for parsing metadata.
     const runner = new ResponseStream<ParsedT>(params as ResponseCreateParamsStreaming);
     runner._run(() =>
       runner._createOrRetrieveResponse(client, params, {
@@ -142,6 +143,7 @@ export class ResponseStream<ParsedT = null>
 
     const maybeEmit = (name: string, event: ResponseStreamEvent & { snapshot?: string }) => {
       if (starting_after == null || event.sequence_number > starting_after) {
+        // SAFETY: The caller derives the event name from the dispatched event discriminator; this bridge preserves the corresponding payload.
         this._emit(name as any, event);
       }
     };
@@ -150,6 +152,7 @@ export class ResponseStream<ParsedT = null>
       // First-party providers nest their error payload; retain flat compatibility for
       // serialized events matching the currently published event schema.
       const error =
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- An error event can contain malformed server data; validate its container before extracting error details.
         'error' in event && typeof event.error === 'object' && event.error !== null ? event.error : event;
       throw new APIError(undefined, error, event.message, undefined);
     }
@@ -263,7 +266,7 @@ export class ResponseStream<ParsedT = null>
       this.#addEvent(event, starting_after);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
     return this.#endRequest();
   }
@@ -280,7 +283,7 @@ export class ResponseStream<ParsedT = null>
       this.#addEvent(event, null);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
     return this.#endRequest();
   }