TypeScript Type Issues in OpenAI Node.js SDK v4.88.0. Headers Type Mismatch.

[JustSmileGG]

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

I am encountering TypeScript type issues with the OpenAI Node.js SDK version 4.88.0. The main issues are:

1. Headers Type Mismatch:

Type '{ [x: string]: string; } | { append(name: string, value: string): void; delete(name: string): void; get(name: string): string; getSetCookie(): string[]; has(name: string): boolean; set(name: string, value: string): void; forEach(callbackfn: (value: string, key: string, parent: Headers) => void, thisArg?: any): void; }' is not assignable to type 'Record<string, string>'.

Environment

• Node.js version: >=22.11.0
• TypeScript version: ^5.8.2
• OpenAI SDK version: 4.88.0
• NestJS version: 11.0.5

Additional Context

• I am using the SDK in a NestJS application
• The issues occur during the build process
• I have skipLibCheck: true in the tsconfig.json.

To Reproduce

Steps to Reproduce

1. Create a new NestJS project
2. Install OpenAI SDK v4.88.0
3. Create a service that uses the OpenAI client
4. Try to use the chat completions API with proper typing

Code snippets

private openAIClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

OS

macOS

Node version

v22.11.0

Library version

"openai": "^4.88.0"

[RobertCraigie]

Thanks for the report, can you share the full error? what line is reporting for?

[JustSmileGG]

@RobertCraigie Hey, thank you for your response!

Yes, no problem.

node_modules/openai/src/core.ts:433:9- error TS2322: Type '{ [x: string]: string; } | { append(name: string, value: string): void; delete(name: string): void; get(name: string): string; getSetCookie(): string[]; has(name: string): boolean; set(name: string, value: string): void; forEach(callbackfn: (value: string, key: string, parent: Headers) => void, thisArg?: any): void; }' is not assignable to type 'Record<string, string>'.
  Type '{ append(name: string, value: string): void; delete(name: string): void; get(name: string): string | null; getSetCookie(): string[]; has(name: string): boolean; set(name: string, value: string): void; forEach(callbackfn: (value: string, key: string, parent: globalThis.Headers) => void, thisArg?: any): void; }' is not assignable to type 'Record<string, string>'.
    Property 'append' is incompatible with index signature.
      Type '(name: string, value: string) => void' is not assignable to type 'string'.

433       : { ...headers }

Found 1 error(s).

[RobertCraigie]

I couldn't reproduce this but I believe it should be fixed in the next release, v4.89.1, #1409

[vm-vhryschenko]

I couldn't reproduce this but I believe it should be fixed in the next release, v4.89.1, #1409

Thank you so much! I will test and give feedback!
Thanks for your quick and amazing job!

[rhoun]

I had the same issue today and found that it happens when you import types from the "wrong" place:

import { ChatCompletionCreateParamsNonStreaming } from "openai/src/resources/chat/completions/completions.js"; //error
import { ChatCompletionCreateParamsNonStreaming } from "openai/resources"; //works`