openai 6.32.0 → 6.34.0

package/src/auth/workload-identity-auth.ts

@@ -0,0 +1,118 @@
+import type { WorkloadIdentity, TokenExchangeResponse } from './types';
+import type { Fetch } from '../internal/builtin-types';
+import * as Shims from '../internal/shims';
+import { APIError, OAuthError } from '../core/error';
+
+interface CachedToken {
+  token: string;
+  expiresAt: number;
+}
+
+const SUBJECT_TOKEN_TYPES: Record<string, string> = {
+  jwt: 'urn:ietf:params:oauth:token-type:jwt',
+  id: 'urn:ietf:params:oauth:token-type:id_token',
+};
+
+const TOKEN_EXCHANGE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+
+export class WorkloadIdentityAuth {
+  private cachedToken: CachedToken | null = null;
+  private refreshPromise: Promise<string> | null = null;
+  private readonly config: WorkloadIdentity;
+  private readonly tokenExchangeUrl: string = 'https://auth.openai.com/oauth/token';
+  private readonly fetch: Fetch;
+
+  constructor(config: WorkloadIdentity, fetch?: Fetch) {
+    this.config = config;
+    this.fetch = fetch ?? Shims.getDefaultFetch();
+  }
+
+  async getToken(): Promise<string> {
+    if (!this.cachedToken || this.isTokenExpired(this.cachedToken)) {
+      if (this.refreshPromise) {
+        return await this.refreshPromise;
+      }
+
+      this.refreshPromise = this.refreshToken();
+
+      try {
+        const token = await this.refreshPromise;
+        return token;
+      } finally {
+        this.refreshPromise = null;
+      }
+    }
+
+    if (this.needsRefresh(this.cachedToken) && !this.refreshPromise) {
+      this.refreshPromise = this.refreshToken().finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+
+    return this.cachedToken.token;
+  }
+
+  private async refreshToken(): Promise<string> {
+    const subjectToken = await this.config.provider.getToken();
+
+    const response = await this.fetch(this.tokenExchangeUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+        client_id: this.config.clientId,
+        subject_token: subjectToken,
+        subject_token_type: SUBJECT_TOKEN_TYPES[this.config.provider.tokenType],
+        identity_provider_id: this.config.identityProviderId,
+        service_account_id: this.config.serviceAccountId,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let body: any = undefined;
+
+      try {
+        body = JSON.parse(errorText);
+      } catch {}
+
+      if (response.status === 400 || response.status === 401 || response.status === 403) {
+        throw new OAuthError(response.status as 400 | 401 | 403, body, response.headers);
+      }
+      throw APIError.generate(
+        response.status,
+        body,
+        `Token exchange failed with status ${response.status}`,
+        response.headers,
+      );
+    }
+
+    const tokenResponse = (await response.json()) as TokenExchangeResponse;
+    const expiresIn = tokenResponse.expires_in || 3600;
+    const expiresAt = Date.now() + expiresIn * 1000;
+
+    this.cachedToken = {
+      token: tokenResponse.access_token,
+      expiresAt,
+    };
+
+    return tokenResponse.access_token;
+  }
+
+  private isTokenExpired(cachedToken: CachedToken): boolean {
+    return Date.now() >= cachedToken.expiresAt;
+  }
+
+  private needsRefresh(cachedToken: CachedToken): boolean {
+    const bufferSeconds = this.config.refreshBufferSeconds ?? 1200;
+    const bufferMs = bufferSeconds * 1000;
+    return Date.now() >= cachedToken.expiresAt - bufferMs;
+  }
+
+  invalidateToken(): void {
+    this.cachedToken = null;
+    this.refreshPromise = null;
+  }
+}

package/src/azure.ts

@@ -4,7 +4,8 @@ import { buildHeaders } from './internal/headers';
 import * as Errors from './error';
 import { FinalRequestOptions } from './internal/request-options';
 import { isObj, readEnv } from './internal/utils';
-import { ClientOptions, OpenAI } from './client';
+import { OpenAI } from './client';
+import type { ClientOptions } from './client';
 
 /** API Client for interfacing with the Azure OpenAI API. */
 export interface AzureClientOptions extends ClientOptions {

package/src/client.ts

@@ -15,6 +15,9 @@ import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
+import type { WorkloadIdentity } from './auth/types';
+import { WorkloadIdentityAuth } from './auth/workload-identity-auth';
+import { OAuthError, SubjectTokenProviderError } from './core/error';
 import {
   AbstractPage,
   type ConversationCursorPageParams,
@@ -238,6 +241,8 @@ import {
 } from './internal/utils/log';
 import { isEmptyObj } from './internal/utils/values';
 
+const WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER = 'workload-identity-auth';
+
 export type ApiKeySetter = () => Promise<string>;
 
 export interface ClientOptions {
@@ -251,8 +256,10 @@ export interface ClientOptions {
    * - The function must return a non-empty string; otherwise an OpenAIError is thrown.
    * - If the function throws, the error is wrapped in an OpenAIError with the original
    *   error available as `cause`.
+   * - Mutually exclusive with `workloadIdentity`.
    */
   apiKey?: string | ApiKeySetter | undefined;
+
   /**
    * Defaults to process.env['OPENAI_ORG_ID'].
    */
@@ -285,6 +292,7 @@ export interface ClientOptions {
    * @unit milliseconds
    */
   timeout?: number | undefined;
+
   /**
    * Additional `RequestInit` options to be passed to `fetch` calls.
    * Properties will be overridden by per-request `fetchOptions`.
@@ -341,6 +349,12 @@ export interface ClientOptions {
    * Defaults to globalThis.console.
    */
   logger?: Logger | undefined;
+
+  /**
+   * Workload identity configuration for OAuth2 token exchange authentication.
+   * Mutually exclusive with `apiKey`.
+   */
+  workloadIdentity?: WorkloadIdentity | undefined;
 }
 
 /**
@@ -363,6 +377,7 @@ export class OpenAI {
   #encoder: Opts.RequestEncoder;
   protected idempotencyHeader?: string;
   protected _options: ClientOptions;
+  private _workloadIdentityAuth?: WorkloadIdentityAuth;
 
   /**
    * API Client for interfacing with the OpenAI API.
@@ -386,11 +401,19 @@ export class OpenAI {
     organization = readEnv('OPENAI_ORG_ID') ?? null,
     project = readEnv('OPENAI_PROJECT_ID') ?? null,
     webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
+    workloadIdentity,
     ...opts
   }: ClientOptions = {}) {
-    if (apiKey === undefined) {
+    if (workloadIdentity) {
+      if (apiKey && apiKey !== WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER) {
+        throw new Errors.OpenAIError(
+          'The `apiKey` and `workloadIdentity` arguments are mutually exclusive; only one can be passed at a time.',
+        );
+      }
+      apiKey = WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER;
+    } else if (apiKey === undefined) {
       throw new Errors.OpenAIError(
-        'Missing credentials. Please pass an `apiKey`, or set the `OPENAI_API_KEY` environment variable.',
+        'Missing credentials. Please pass an `apiKey`, `workloadIdentity`, or set the `OPENAI_API_KEY` environment variable.',
       );
     }
 
@@ -399,6 +422,7 @@ export class OpenAI {
       organization,
       project,
       webhookSecret,
+      workloadIdentity,
       ...opts,
       baseURL: baseURL || `https://api.openai.com/v1`,
     };
@@ -426,6 +450,10 @@ export class OpenAI {
 
     this._options = options;
 
+    if (workloadIdentity) {
+      this._workloadIdentityAuth = new WorkloadIdentityAuth(workloadIdentity, this.fetch);
+    }
+
     this.apiKey = typeof apiKey === 'string' ? apiKey : 'Missing Key';
     this.organization = organization;
     this.project = project;
@@ -446,6 +474,7 @@ export class OpenAI {
       fetch: this.fetch,
       fetchOptions: this.fetchOptions,
       apiKey: this.apiKey,
+      workloadIdentity: this._options.workloadIdentity,
       organization: this.organization,
       project: this.project,
       webhookSecret: this.webhookSecret,
@@ -640,7 +669,7 @@ export class OpenAI {
     }
 
     const controller = new AbortController();
-    const response = await this.fetchWithTimeout(url, req, timeout, controller).catch(castToError);
+    const response = await this.fetchWithAuth(url, req, timeout, controller).catch(castToError);
     const headersTime = Date.now();
 
     if (response instanceof globalThis.Error) {
@@ -682,6 +711,9 @@ export class OpenAI {
           message: response.message,
         }),
       );
+      if (response instanceof OAuthError || response instanceof SubjectTokenProviderError) {
+        throw response;
+      }
       if (isTimeout) {
         throw new Errors.APIConnectionTimeoutError();
       }
@@ -697,6 +729,28 @@ export class OpenAI {
     } with status ${response.status} in ${headersTime - startTime}ms`;
 
     if (!response.ok) {
+      if (
+        response.status === 401 &&
+        this._workloadIdentityAuth &&
+        !options.__metadata?.['hasStreamingBody'] &&
+        !options.__metadata?.['workloadIdentityTokenRefreshed']
+      ) {
+        await Shims.CancelReadableStream(response.body);
+        this._workloadIdentityAuth.invalidateToken();
+
+        return this.makeRequest(
+          {
+            ...options,
+            __metadata: {
+              ...options.__metadata,
+              workloadIdentityTokenRefreshed: true,
+            },
+          },
+          retriesRemaining,
+          retryOfRequestLogID ?? requestLogID,
+        );
+      }
+
       const shouldRetry = await this.shouldRetry(response);
       if (retriesRemaining && shouldRetry) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
@@ -785,6 +839,26 @@ export class OpenAI {
     return new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
   }
 
+  protected async fetchWithAuth(
+    url: RequestInfo,
+    init: RequestInit,
+    timeout: number,
+    controller: AbortController,
+  ): Promise<Response> {
+    if (this._workloadIdentityAuth) {
+      const headers = init.headers as Headers;
+      const authHeader = headers.get('Authorization');
+      if (!authHeader || authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
+        const token = await this._workloadIdentityAuth.getToken();
+        headers.set('Authorization', `Bearer ${token}`);
+      }
+    }
+
+    const response = await this.fetchWithTimeout(url, init, timeout, controller);
+
+    return response;
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -908,7 +982,15 @@ export class OpenAI {
     const url = this.buildURL(path!, query as Record<string, unknown>, defaultBaseURL);
     if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
-    const { bodyHeaders, body } = this.buildBody({ options });
+    const { bodyHeaders, body, isStreamingBody } = this.buildBody({ options });
+
+    if (isStreamingBody) {
+      inputOptions.__metadata = {
+        ...inputOptions.__metadata,
+        hasStreamingBody: true,
+      };
+    }
+
     const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
 
     const req: FinalizedRequestInit = {
@@ -973,11 +1055,26 @@ export class OpenAI {
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
+    isStreamingBody: boolean;
   } {
     if (!body) {
-      return { bodyHeaders: undefined, body: undefined };
+      return { bodyHeaders: undefined, body: undefined, isStreamingBody: false };
     }
     const headers = buildHeaders([rawHeaders]);
+
+    const isReadableStream =
+      typeof (globalThis as any).ReadableStream !== 'undefined' &&
+      body instanceof (globalThis as any).ReadableStream;
+
+    const isRetryableBody =
+      !isReadableStream &&
+      (typeof body === 'string' ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        (typeof (globalThis as any).Blob !== 'undefined' && body instanceof (globalThis as any).Blob) ||
+        body instanceof URLSearchParams ||
+        body instanceof FormData);
+
     if (
       // Pass raw type verbatim
       ArrayBuffer.isView(body) ||
@@ -993,15 +1090,19 @@ export class OpenAI {
       // `URLSearchParams` -> `application/x-www-form-urlencoded`
       body instanceof URLSearchParams ||
       // Send chunked stream (each chunk has own `length`)
-      ((globalThis as any).ReadableStream && body instanceof (globalThis as any).ReadableStream)
+      isReadableStream
     ) {
-      return { bodyHeaders: undefined, body: body as BodyInit };
+      return { bodyHeaders: undefined, body: body as BodyInit, isStreamingBody: !isRetryableBody };
     } else if (
       typeof body === 'object' &&
       (Symbol.asyncIterator in body ||
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
-      return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+      return {
+        bodyHeaders: undefined,
+        body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>),
+        isStreamingBody: true,
+      };
     } else if (
       typeof body === 'object' &&
       headers.values.get('content-type') === 'application/x-www-form-urlencoded'
@@ -1009,9 +1110,10 @@ export class OpenAI {
       return {
         bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
         body: this.stringifyQuery(body),
+        isStreamingBody: false,
       };
     } else {
-      return this.#encoder({ body, headers });
+      return { ...this.#encoder({ body, headers }), isStreamingBody: false };
     }
   }
 
@@ -1361,6 +1463,7 @@ export declare namespace OpenAI {
   export type FunctionDefinition = API.FunctionDefinition;
   export type FunctionParameters = API.FunctionParameters;
   export type Metadata = API.Metadata;
+  export type OAuthErrorCode = API.OAuthErrorCode;
   export type Reasoning = API.Reasoning;
   export type ReasoningEffort = API.ReasoningEffort;
   export type ResponseFormatJSONObject = API.ResponseFormatJSONObject;

package/src/core/error.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { castToError } from '../internal/errors';
+import type { OAuthErrorCode } from '../resources/shared';
 
 export class OpenAIError extends Error {}
 
@@ -158,3 +159,42 @@ export class InvalidWebhookSignatureError extends Error {
     super(message);
   }
 }
+
+/**
+ * Error thrown by the API server during OAuth token exchange.
+ * Can have status codes 400, 401, or 403.
+ * Other status codes from OAuth endpoints are raised as normal APIError types.
+ */
+export class OAuthError extends APIError<400 | 401 | 403, Headers> {
+  readonly error_code: OAuthErrorCode | undefined;
+
+  constructor(status: 400 | 401 | 403, error: Object | undefined, headers: Headers) {
+    let finalMessage = 'OAuth2 authentication error';
+    let error_code: OAuthErrorCode | undefined = undefined;
+
+    if (error && typeof error === 'object') {
+      const errorData = error as Record<string, any>;
+      error_code = errorData['error'];
+      const description = errorData['error_description'];
+      if (description && typeof description === 'string') {
+        finalMessage = description;
+      } else if (error_code) {
+        finalMessage = error_code;
+      }
+    }
+
+    super(status, error, finalMessage, headers);
+    this.error_code = error_code;
+  }
+}
+
+export class SubjectTokenProviderError extends OpenAIError {
+  readonly provider: string;
+  readonly cause: Error | undefined;
+
+  constructor(message: string, provider: string, cause?: Error) {
+    super(message);
+    this.provider = provider;
+    this.cause = cause;
+  }
+}

package/src/index.ts

@@ -21,6 +21,8 @@ export {
   PermissionDeniedError,
   UnprocessableEntityError,
   InvalidWebhookSignatureError,
+  OAuthError,
+  SubjectTokenProviderError,
 } from './core/error';
 
 export { AzureOpenAI } from './azure';

package/src/resources/conversations/conversations.ts

@@ -170,6 +170,14 @@ export interface Message {
    * The type of the message. Always set to `message`.
    */
   type: 'message';
+
+  /**
+   * Labels an `assistant` message as intermediate commentary (`commentary`) or the
+   * final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when
+   * sending follow-up requests, preserve and resend phase on all assistant messages
+   * — dropping it can degrade performance. Not used for user messages.
+   */
+  phase?: 'commentary' | 'final_answer' | null;
 }
 
 export namespace Message {

package/src/resources/conversations/items.ts

@@ -91,6 +91,7 @@ export type ConversationItem =
   | ResponsesAPI.ResponseToolSearchCall
   | ResponsesAPI.ResponseToolSearchOutputItem
   | ResponsesAPI.ResponseReasoningItem
+  | ResponsesAPI.ResponseCompactionItem
   | ResponsesAPI.ResponseCodeInterpreterToolCall
   | ConversationItem.LocalShellCall
   | ConversationItem.LocalShellCallOutput

package/src/resources/realtime/calls.ts

@@ -172,8 +172,9 @@ export interface CallAcceptParams {
 
   /**
    * Realtime API can write session traces to the
-   * [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once
-   * tracing is enabled for a session, the configuration cannot be modified.
+   * [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+   * disable tracing. Once tracing is enabled for a session, the configuration cannot
+   * be modified.
    *
    * `auto` will create a trace for the session with default values for the workflow
    * name, group id, and metadata.

package/src/resources/realtime/client-secrets.ts

@@ -153,8 +153,9 @@ export interface RealtimeSessionCreateResponse {
 
   /**
    * Realtime API can write session traces to the
-   * [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once
-   * tracing is enabled for a session, the configuration cannot be modified.
+   * [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+   * disable tracing. Once tracing is enabled for a session, the configuration cannot
+   * be modified.
    *
    * `auto` will create a trace for the session with default values for the workflow
    * name, group id, and metadata.

package/src/resources/realtime/realtime.ts

@@ -3136,8 +3136,9 @@ export interface RealtimeSessionCreateRequest {
 
   /**
    * Realtime API can write session traces to the
-   * [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once
-   * tracing is enabled for a session, the configuration cannot be modified.
+   * [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+   * disable tracing. Once tracing is enabled for a session, the configuration cannot
+   * be modified.
    *
    * `auto` will create a trace for the session with default values for the workflow
    * name, group id, and metadata.
@@ -3349,8 +3350,9 @@ export namespace RealtimeToolsConfigUnion {
 
 /**
  * Realtime API can write session traces to the
- * [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once
- * tracing is enabled for a session, the configuration cannot be modified.
+ * [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+ * disable tracing. Once tracing is enabled for a session, the configuration cannot
+ * be modified.
  *
  * `auto` will create a trace for the session with default values for the workflow
  * name, group id, and metadata.

package/src/resources/responses/api.md

@@ -51,7 +51,9 @@ Types:
 - <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCall</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCallInputDeltaEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCallInputDoneEvent</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCallItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCallOutput</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ResponseCustomToolCallOutputItem</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseError</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseErrorEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ResponseFailedEvent</a></code>

package/src/resources/responses/internal-base.ts

@@ -2,11 +2,15 @@
 
 import * as ResponsesAPI from './responses';
 import { OpenAI } from '../../client';
-
 import { EventEmitter } from '../../core/EventEmitter';
 import { OpenAIError } from '../../core/error';
 import { stringifyQuery } from '../../internal/utils';
 
+export type ResponsesStreamMessage =
+  | { type: 'connecting' | 'open' | 'closing' | 'close' }
+  | { type: 'message'; message: ResponsesAPI.ResponsesServerEvent }
+  | { type: 'error'; error: WebSocketError };
+
 export class WebSocketError extends OpenAIError {
   /**
    * The error data that the API sent back in an error event.