usage field may contain null, but the TypeScript type definition does not reflect this

[kakasoo]

Confirm this is a Node library issue and not an underlying OpenAI API issue

• This is an issue with the Node library

Describe the bug

Issue Title

usage field may contain null, but its type does not reflect this

Issue Description

The usage field in the response is described in the documentation as follows:

When present, it contains a null value except for the last chunk, which contains the token usage statistics for the entire request.

However, the TypeScript type definition does not include null as a possible value:

usage?: CompletionsAPI.CompletionUsage;

Since the field explicitly states that it can be null in most cases (except for the last chunk), the correct type definition should be:

usage?: CompletionsAPI.CompletionUsage | null;

This mismatch may cause issues in TypeScript projects that rely on strict type checking.

• openai-node/src/resources/chat/completions/completions.ts

  Lines 377 to 386 in 20e97a4

  	/**
  	* An optional field that will only be present when you set
  	* `stream_options: {"include_usage": true}` in your request. When present, it
  	* contains a null value **except for the last chunk** which contains the token
  	* usage statistics for the entire request.
  	*
  	* **NOTE:** If the stream is interrupted or cancelled, you may not receive the
  	* final usage chunk which contains the total token usage for the request.
  	*/
  	usage?: CompletionsAPI.CompletionUsage;

To Reproduce

This is a clear bug since the comments and the actual code do not match.

Code snippets

OS

macOS

Node version

Node v22.3.0

Library version

4.87.4

[kakasoo]

This is a clear bug since the comments and the actual code do not match. We discovered this issue while working on our open-source project, Agentica, where it is reproducible. Please let us know if you have any questions or need further details!

[sunrabbit123]

represent solution

just use streaming with openai sdk
and you can get usage: null, but openai sdk type is not to present null

[sunrabbit123]

it's break change pr

#1391

it's api docs
https://platform.openai.com/docs/api-reference/chat-streaming/streaming

[Specy]

I found this issue also in RealtimeClientEvent for the beta of the realtime api