openai 7.9.0 → 7.12.1

package/src/client.ts

@@ -168,6 +168,7 @@ import { FineTuning } from './resources/fine-tuning/fine-tuning';
 import { Graders } from './resources/graders/graders';
 import { Realtime } from './resources/realtime/realtime';
 import { Responses } from './resources/responses/responses';
+import { Safety } from './resources/safety/safety';
 import {
   DeletedSkill,
   Skill,
@@ -848,11 +849,25 @@ export class OpenAI {
     return Errors.APIError.generate(status, normalizedError, message, headers);
   }
 
-  async _callApiKey(): Promise<boolean> {
-    if (this._provider) return false;
+  /**
+   * Resolves a function-based API key and retains the resolved value on this client.
+   * Returns whether a provider was invoked. Internal callers can capture this
+   * invocation's key before another request updates the shared `apiKey` property.
+   * Overrides should forward `capture` or invoke it with their own resolved key
+   * to preserve connection-local credentials in concurrent Realtime factories.
+   * @internal
+   */
+  async _callApiKey(capture?: (apiKey: string | null) => void): Promise<boolean> {
+    if (this._provider) {
+      capture?.(this.apiKey);
+      return false;
+    }
 
     const apiKey = this._options.apiKey;
-    if (typeof apiKey !== 'function') return false;
+    if (typeof apiKey !== 'function') {
+      capture?.(this.apiKey);
+      return false;
+    }
 
     let token: unknown;
     try {
@@ -872,6 +887,7 @@ export class OpenAI {
       );
     }
     this.apiKey = token;
+    capture?.(this.apiKey);
     return true;
   }
 
@@ -1534,7 +1550,7 @@ export class OpenAI {
     if (this._workloadIdentityAuth && !this.#x509Fetch && schemes.bearerAuth) {
       const headers = init.headers as Headers;
       const authHeader = headers.get('Authorization');
-      if (!authHeader || authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
+      if (authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
         const token = await this._workloadIdentityAuth.getToken();
         headers.set('Authorization', `Bearer ${token}`);
       }
@@ -1948,6 +1964,7 @@ export class OpenAI {
   fineTuning: API.FineTuning = new API.FineTuning(this);
   graders: API.Graders = new API.Graders(this);
   vectorStores: API.VectorStores = new API.VectorStores(this);
+  safety: API.Safety = new API.Safety(this);
   webhooks: API.Webhooks = new API.Webhooks(this);
   beta: API.Beta = new API.Beta(this);
   /**
@@ -1989,6 +2006,7 @@ OpenAI.Models = Models;
 OpenAI.FineTuning = FineTuning;
 OpenAI.Graders = Graders;
 OpenAI.VectorStores = VectorStores;
+OpenAI.Safety = Safety;
 OpenAI.Webhooks = Webhooks;
 OpenAI.Beta = Beta;
 OpenAI.Batches = Batches;
@@ -2234,6 +2252,8 @@ export declare namespace OpenAI {
     type VectorStoreSearchParams as VectorStoreSearchParams,
   };
 
+  export { Safety as Safety };
+
   export { Webhooks as Webhooks };
 
   export { Beta as Beta };

package/src/core/EventEmitter.ts

@@ -1,3 +1,5 @@
+import type { EmittedEventResult } from '../lib/EventEmitter';
+
 /** Listener callback associated with one event name in a typed event map. */
 type EventListener<Events, EventType extends keyof Events> = Events[EventType];
 
@@ -145,13 +147,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    */
   emitted<Event extends keyof EventTypes>(
     event: Event,
-  ): Promise<
-    EventParameters<EventTypes, Event> extends [infer Param]
-      ? Param
-      : EventParameters<EventTypes, Event> extends []
-        ? void
-        : EventParameters<EventTypes, Event>
-  > {
+  ): Promise<EmittedEventResult<EventParameters<EventTypes, Event>>> {
     return new Promise((resolve, reject) => {
       const listeners = {
         onError: (error: unknown) => {
@@ -193,7 +189,8 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
         for (const registration of listeners as any) {
           if (!registration.removed) {
             try {
-              registration.listener(...(args as any));
+              const { listener } = registration;
+              listener(...(args as any));
             } catch (error) {
               if (!listenerThrew) {
                 listenerThrew = true;

package/src/core/pagination.ts

@@ -309,7 +309,7 @@ export class NextCursorPage<Item> extends AbstractPage<Item> implements NextCurs
       return false;
     }
 
-    return super.hasNextPage();
+    return this.nextPageRequestOptions() != null;
   }
 
   nextPageRequestOptions(): PageRequestOptions | null {

package/src/core/streaming.ts

@@ -9,22 +9,34 @@ import type { OpenAI } from '../client';
 
 type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
 
+function isTransportAbortError(error: unknown): boolean {
+  return !(error instanceof APIError) && isAbortError(error);
+}
+
 type StreamTeeQueue<Item> = {
   readonly length: number;
+  readonly canceled: boolean;
   enqueue: (value: Promise<IteratorResult<Item>>) => void;
   dequeue: () => Promise<IteratorResult<Item>> | undefined;
+  cancel: () => void;
 };
 
 function createStreamTeeQueue<Item>(): StreamTeeQueue<Item> {
   let entries: (Promise<IteratorResult<Item>> | undefined)[] = [];
   let head = 0;
+  let canceled = false;
 
   return {
     get length() {
       return entries.length - head;
     },
+    get canceled() {
+      return canceled;
+    },
     enqueue(value) {
-      entries.push(value);
+      if (!canceled) {
+        entries.push(value);
+      }
     },
     dequeue() {
       if (head === entries.length) {
@@ -45,6 +57,11 @@ function createStreamTeeQueue<Item>(): StreamTeeQueue<Item> {
 
       return value;
     },
+    cancel() {
+      canceled = true;
+      entries.length = 0;
+      head = 0;
+    },
   };
 }
 
@@ -69,6 +86,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
   /** Abort controller for the underlying request and all branches created with `tee()`. */
   controller: AbortController;
   #client: OpenAI | undefined;
+  #isTeeBranch = false;
   private iterator: () => AsyncIterator<Item>;
 
   /** Wraps an asynchronous event iterator and the controller that owns its request. */
@@ -101,8 +119,17 @@ export class Stream<Item> implements AsyncIterable<Item> {
       consumed = true;
       let done = false;
       let receivedCompletionSentinel = false;
+      const messages = _iterSSEMessages(response, controller);
+      const closeMessages = messages.return.bind(messages);
+      messages.return = (value) => {
+        // Abort before nested iterator cleanup can wait on the response body's cancellation.
+        if (!receivedCompletionSentinel) {
+          controller.abort();
+        }
+        return closeMessages(value);
+      };
       try {
-        for await (const sse of _iterSSEMessages(response, controller)) {
+        for await (const sse of messages) {
           if (sse.data === '[DONE]') {
             receivedCompletionSentinel = true;
             break;
@@ -145,7 +172,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
         // Abort errors and cleanup failures after the completion sentinel are non-fatal.
         if (
           receivedCompletionSentinel ||
-          isAbortError(e) ||
+          isTransportAbortError(e) ||
           (controller.signal.aborted && e === controller.signal.reason)
         ) {
           return;
@@ -234,9 +261,6 @@ export class Stream<Item> implements AsyncIterable<Item> {
       let done = false;
       try {
         for await (const line of iterLines()) {
-          if (done) {
-            continue;
-          }
           if (line) {
             let data: Item;
             try {
@@ -278,14 +302,24 @@ export class Stream<Item> implements AsyncIterable<Item> {
   /**
    * Splits the stream into two streams which can be
    * independently read from at different speeds.
+   * Closing a branch discards its buffered events without stopping its sibling.
+   * Future reads on that branch finish immediately; previously issued `next()`
+   * promises remain shared with its sibling and may still resolve with events.
+   * Closing both branches invokes the source iterator's `return()` when available.
+   * For {@link Stream.fromReadableStream}, closing both branches before iteration
+   * starts does not cancel the supplied readable; cancel that readable directly.
    */
   tee(): [Stream<Item>, Stream<Item>] {
+    const { controller } = this;
     const left = createStreamTeeQueue<Item>();
     const right = createStreamTeeQueue<Item>();
     const iterator = this.iterator();
 
     const teeIterator = (queue: StreamTeeQueue<Item>): AsyncIterator<Item> => ({
       next: () => {
+        if (queue.canceled) {
+          return Promise.resolve({ value: undefined, done: true });
+        }
         if (queue.length === 0) {
           const result = iterator.next();
           left.enqueue(result);
@@ -293,20 +327,34 @@ export class Stream<Item> implements AsyncIterable<Item> {
         }
         return queue.dequeue()!;
       },
+      return: async () => {
+        if (!queue.canceled) {
+          queue.cancel();
+          if (left.canceled && right.canceled) {
+            await this.#cancelIterator(iterator, controller);
+          }
+        }
+        return { value: undefined, done: true };
+      },
     });
 
-    return [
-      new Stream(() => teeIterator(left), this.controller, this.#client),
-      new Stream(() => teeIterator(right), this.controller, this.#client),
-    ];
+    const branch = (queue: StreamTeeQueue<Item>) => {
+      const stream = new Stream(() => teeIterator(queue), controller, this.#client);
+      stream.#isTeeBranch = true;
+      return stream;
+    };
+    return [branch(left), branch(right)];
   }
 
   /**
    * Converts this stream to a newline-separated ReadableStream of
    * JSON stringified values in the stream
    * which can be turned back into a Stream with `Stream.fromReadableStream()`.
+   * Canceling a response-backed readable aborts its request. Canceling a tee
+   * branch discards its buffered events and leaves sibling consumers running.
    */
   toReadableStream(): ReadableStream {
+    const { controller } = this;
     let iter: AsyncIterator<Item>;
 
     return makeReadableStream({
@@ -327,11 +375,19 @@ export class Stream<Item> implements AsyncIterable<Item> {
           ctrl.error(err);
         }
       },
-      async cancel() {
-        await iter.return?.();
-      },
+      cancel: () => this.#cancelIterator(iter, controller),
     });
   }
+
+  async #cancelIterator(iterator: AsyncIterator<Item>, controller: AbortController): Promise<void> {
+    const returnMethod = iterator.return;
+    if (returnMethod) {
+      if (!this.#isTeeBranch) {
+        controller.abort();
+      }
+      await Reflect.apply(returnMethod, iterator, []);
+    }
+  }
 }
 
 function createAbortableSSESource(body: NonNullable<Response['body']>, signal: AbortSignal) {

package/src/helpers/audio.ts

@@ -24,7 +24,17 @@ const recordingProviders: Record<NodeJS.Platform, string> = {
 };
 
 function isResponse(stream: NodeJS.ReadableStream | Response | File): stream is Response {
-  return (stream as any).body !== undefined;
+  // Readables have event and flow-control methods, even after they have ended.
+  const nodeReadable =
+    'pipe' in stream &&
+    typeof stream.pipe === 'function' &&
+    'on' in stream &&
+    typeof stream.on === 'function' &&
+    'pause' in stream &&
+    typeof stream.pause === 'function' &&
+    'resume' in stream &&
+    typeof stream.resume === 'function';
+  return !nodeReadable && 'body' in stream && stream.body !== undefined;
 }
 
 function isFile(stream: NodeJS.ReadableStream | Response | File): stream is File {
@@ -57,10 +67,18 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
       ffplay.stderr?.resume();
       ffplay.on('error', reject);
 
+      // The player can exit before the input stream finishes its cleanup.
+      let inputFinished = false;
+      let processClosed = false;
       pipeline(source, ffplay.stdin, (error) => {
         if (error) {
           ffplay.kill();
           reject(error);
+          return;
+        }
+        inputFinished = true;
+        if (processClosed) {
+          resolve();
         }
       });
 
@@ -69,7 +87,10 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
           reject(new Error(`ffplay process exited with code ${code}`));
           return;
         }
-        resolve();
+        processClosed = true;
+        if (inputFinished) {
+          resolve();
+        }
       });
     } catch (error) {
       reject(error);
@@ -103,7 +124,7 @@ type RecordAudioOptions = {
   /** Stops recording when aborted; successful termination returns the captured audio. */
   signal?: AbortSignal;
 
-  /** Zero-based audio-input device number passed to FFmpeg; defaults to `0`. */
+  /** Zero-based audio-input index (ALSA card number on Linux); defaults to `0`. */
   device?: number;
 
   /** Positive recording duration in milliseconds; nonpositive values disable the timeout. */
@@ -137,7 +158,7 @@ function nodejsRecordAudio({ signal, device, timeout }: RecordAudioOptions = {})
       }
     };
     const stopRecording = () => {
-      if (!settled && ffmpeg) {
+      if (!settled && ffmpeg?.pid) {
         try {
           wasStopped ||= ffmpeg.kill('SIGTERM');
         } catch (error) {
@@ -223,7 +244,7 @@ function nodejsRecordAudio({ signal, device, timeout }: RecordAudioOptions = {})
           '-f',
           provider,
           '-i',
-          `:${device ?? 0}`, // default audio input device; adjust as needed
+          provider === 'alsa' ? `hw:${device ?? 0}` : `:${device ?? 0}`,
           '-ar',
           DEFAULT_SAMPLE_RATE.toString(),
           '-ac',
@@ -270,7 +291,7 @@ function nodejsRecordAudio({ signal, device, timeout }: RecordAudioOptions = {})
       }
 
       try {
-        if (!wasStopped) {
+        if (!wasStopped && ffmpeg?.pid) {
           ffmpeg?.kill('SIGTERM');
         }
       } catch {

package/src/helpers/zod.ts

@@ -82,11 +82,11 @@ function validateSchemaDefinitions(schemaDefinitions: ZodSchemaDefinitions | und
 
 function escapeSchemaDefinitionRefs<T extends object>(
   schema: T,
-  schemaDefinitions: ZodSchemaDefinitions | undefined,
+  definitionNames: ReadonlyMap<string, string>,
 ): T {
   const refReplacements = new Map(
-    Object.keys(schemaDefinitions ?? {}).map((name) => [
-      `#/definitions/${name}`,
+    [...definitionNames].map(([id, name]) => [
+      `#/definitions/${id}`,
       `#/definitions/${encodeSchemaDefinitionRefToken(name)}`,
     ]),
   );
@@ -147,7 +147,10 @@ function zodV3ToJsonSchema(
       : undefined),
   });
 
-  const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+  const escapedSchema = escapeSchemaDefinitionRefs(
+    jsonSchema,
+    new Map(Object.keys(options.schemaDefinitions ?? {}).map((name) => [name, name])),
+  );
   assertJSONSerializableSchema(escapedSchema);
   return escapedSchema;
 }
@@ -157,16 +160,29 @@ function zodV4ToJsonSchema(
   options: { schemaDefinitions?: ZodSchemaDefinitions | undefined } = {},
 ): Record<string, unknown> {
   const metadata = options.schemaDefinitions ? z4.registry<Record<string, unknown>>() : undefined;
+  const definitionNames = new Map<string, string>();
   for (const [name, definition] of Object.entries(options.schemaDefinitions ?? {})) {
-    metadata?.add(definition as unknown as z4.ZodType, { id: name });
+    // Avoid `/` and `~` so Zod versions that escape JSON Pointer tokens emit the same IDs.
+    const id = encodeURIComponent(name).replace(/~/g, '%7E');
+    definitionNames.set(id, name);
+    metadata?.add(definition as unknown as z4.ZodType, { id });
   }
 
   const jsonSchema = z4.toJSONSchema(schema, {
     target: 'draft-7',
     ...(metadata ? { metadata } : undefined),
-    override: ({ zodSchema, jsonSchema }) => {
+    override: ({ zodSchema, jsonSchema, path }) => {
       const def = zodSchema._zod.def;
 
+      if (def.type === 'object' && hasOwn(def.shape, '__proto__')) {
+        const propertyPath = [...path, 'properties', '__proto__']
+          .map((part) => encodeSchemaDefinitionRefToken(String(part)))
+          .join('/');
+        throw new Error(
+          `Zod field at \`#/${propertyPath}\` uses unsupported property name \`__proto__\`, which Zod omits from parsed output.`,
+        );
+      }
+
       if (def.type === 'union' && 'discriminator' in def && Array.isArray(jsonSchema.oneOf)) {
         if (jsonSchema.anyOf !== undefined) {
           throw new Error(
@@ -182,7 +198,15 @@ function zodV4ToJsonSchema(
     },
   }) as JSONSchema;
 
-  const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+  const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, definitionNames);
+  if (escapedSchema.definitions) {
+    escapedSchema.definitions = Object.fromEntries(
+      Object.entries(escapedSchema.definitions).map(([id, definition]) => [
+        definitionNames.get(id) ?? id,
+        definition,
+      ]),
+    );
+  }
 
   return toStrictJsonSchema(escapedSchema) as Record<string, unknown>;
 }
@@ -333,18 +357,8 @@ 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-facing settings and an optional execution callback for a Zod function tool. */
+interface ZodFunctionOptions<Parameters extends ZodTypeLike> {
   /** Model-visible function name used to identify matching tool calls. */
   name: string;
 
@@ -356,19 +370,53 @@ export function zodFunction<Parameters extends ZodTypeLike>(options: {
 
   /** Optional model-visible explanation of when and how the function should be used. */
   description?: string | undefined;
-}): AutoParseableTool<{
+}
+
+/** A Zod function tool retaining its inferred argument and callback types. */
+type ZodFunctionTool<
+  Parameters extends ZodTypeLike,
+  Callback extends ZodFunctionOptions<Parameters>['function'],
+> = 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 availability determines whether the tool can be executed. */
+  function: Callback;
+}>;
 
-  /** Callback signature associated with validated function-call arguments. */
-  function: (args: InferZodType<Parameters>) => unknown;
-}> {
-  const zodSchema = options.parameters as unknown as ZodSchema;
+/**
+ * Creates a chat completion `function` tool that can be invoked automatically
+ * by `.runTools()` or parsed by `.parse()` / `.stream()`.
+ *
+ * Arguments are converted to strict JSON Schema and validated with the supplied
+ * Zod schema before the callback receives them.
+ *
+ * @param options Model-visible function name, Zod parameter schema, description,
+ * and callback used by `chat.completions.runTools()`.
+ */
+export function zodFunction<Parameters extends ZodTypeLike>(
+  options: ZodFunctionOptions<Parameters> & {
+    /** Callback invoked with validated arguments by chat `runTools()`. */
+    function: NonNullable<ZodFunctionOptions<Parameters>['function']>;
+  },
+): ZodFunctionTool<Parameters, NonNullable<ZodFunctionOptions<Parameters>['function']>>;
+
+/**
+ * Creates a strict chat completion function tool for `.parse()` / `.stream()`.
+ * Without a guaranteed callback, the tool cannot be executed by `.runTools()`.
+ *
+ * @param options Model-visible function details and an optional callback.
+ */
+export function zodFunction<Parameters extends ZodTypeLike>(
+  options: ZodFunctionOptions<Parameters>,
+): ZodFunctionTool<Parameters, ZodFunctionOptions<Parameters>['function']>;
+
+/** Builds a strict Chat Completions function tool from the supplied Zod schema. */
+export function zodFunction<Parameters extends ZodTypeLike>(options: ZodFunctionOptions<Parameters>) {
+  const parameters = options.parameters;
+  const zodSchema = parameters as unknown as ZodSchema;
 
-  // @ts-expect-error TODO
   return makeParseableTool<any>(
     {
       type: 'function',
@@ -383,7 +431,7 @@ export function zodFunction<Parameters extends ZodTypeLike>(options: {
     },
     {
       callback: options.function,
-      parser: (args) => parseZodObject(options.parameters, args),
+      parser: (args) => parseZodObject(parameters, args),
     },
   );
 }
@@ -421,7 +469,8 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
   /** Callback signature associated with validated function-call arguments. */
   function: (args: InferZodType<Parameters>) => unknown;
 }> {
-  const zodSchema = options.parameters as unknown as ZodSchema;
+  const parameters = options.parameters;
+  const zodSchema = parameters as unknown as ZodSchema;
 
   return makeParseableResponseTool<any>(
     {
@@ -435,7 +484,7 @@ export function zodResponsesFunction<Parameters extends ZodTypeLike>(options: {
     },
     {
       callback: options.function,
-      parser: (args) => parseZodObject(options.parameters, args),
+      parser: (args) => parseZodObject(parameters, args),
     },
   );
 }