TS2416 importing the SDK with TypeScript 6.0.3 and @types/node 24.19.1 #1206

Importing @openrouter/sdk@1.4.25 produces TS2416 with TypeScript 6.0.3 and @types/node@24.19.1 when declaration checking is enabled. The reproduction uses the exact target and lib settings recommended in RUNTIMES.md. It requires no credentials or API requests.

Reproduction

Verified with Node.js 24.21.0 and pnpm 10.26.0 on macOS arm64. Create these three files in an empty directory.

package.json:

{
  "name": "openrouter-node-types-repro",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.26.0",
  "scripts": {
    "typecheck": "tsc --project tsconfig.json --pretty false"
  },
  "dependencies": {
    "@openrouter/sdk": "1.4.25"
  },
  "devDependencies": {
    "@types/node": "24.19.1",
    "typescript": "6.0.3"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": false,
    "noEmit": true
  },
  "files": ["index.ts"]
}

index.ts:

import { OpenRouter } from '@openrouter/sdk'

void OpenRouter

Run:

pnpm install --ignore-scripts
pnpm run typecheck

Actual result

The compiler exits with code 2:

node_modules/@openrouter/sdk/esm/lib/event-streams.d.ts(21,5): error TS2416: Property '[Symbol.asyncIterator]' in type 'EventStream<T>' is not assignable to the same property in base type 'ReadableStream<T>'.
  Type '() => { next(): Promise<IteratorResult<T, undefined>>; throw?(e?: unknown): Promise<IteratorResult<T, undefined>>; return?(): Promise<...>; [Symbol.asyncIterator](): any; }' is not assignable to type '{ (options?: ReadableStreamIteratorOptions | undefined): ReadableStreamAsyncIterator<T>; (): { next(): Promise<IteratorResult<...>>; throw?(e?: unknown): Promise<...>; return?(): Promise<...>; [Symbol.asyncIterator](): any; }; }'.
    Property '[Symbol.asyncDispose]' is missing in type '{ next(): Promise<IteratorResult<T, undefined>>; throw?(e?: unknown): Promise<IteratorResult<T, undefined>>; return?(): Promise<...>; [Symbol.asyncIterator](): any; }' but required in type 'ReadableStreamAsyncIterator<T>'.

Expected result

The public SDK import should typecheck with these compiler options and versions. If TypeScript 6 is outside the SDK's supported range, please clarify the range and whether support for this combination is planned.

Version comparison

These checks use the unmodified SDK 1.4.25, the same import, and the compiler options above. The compiler and Node type package versions were varied as shown below; Node.js remains 24.21.0.

A control that uses standard Request, Headers, fetch, and ReadableStream types without importing the SDK also passes with TypeScript 6.0.3 and @types/node@24.19.1.

Declaration conflict and tested workaround

The SDK augments the global ReadableStream interface with an iterator overload that lacks [Symbol.asyncDispose]. EventStream<T> declares its iterator return type as ReturnType<ReadableStream<T>[typeof Symbol.asyncIterator]>. In the failing environment, that resolves to the added overload and conflicts with the standard stream iterator type.

Deleting only that augmentation from the published declaration makes the reproduction pass. The remaining EventStream signature uses the standard iterator type. SDK JavaScript is unchanged.

--- a/esm/lib/event-streams.d.ts
+++ b/esm/lib/event-streams.d.ts
@@ -1,13 +1,3 @@
-declare global {
-    interface ReadableStream<R = any> {
-        [Symbol.asyncIterator](): {
-            next(): Promise<IteratorResult<R, undefined>>;
-            throw?(e?: unknown): Promise<IteratorResult<R, undefined>>;
-            return?(): Promise<IteratorResult<R, undefined>>;
-            [Symbol.asyncIterator](): any;
-        };
-    }
-}
 export type SseMessage<T> = {
     data?: T | undefined;
     event?: string | null | undefined;

With TypeScript 6.0.3 and @types/node@24.19.1, the patched declaration preserves event-value types in for await loops: an intentional assignment of a string field to a number still fails with TS2322. On Node.js 24.21.0, separate runtime checks confirm that SSE iteration returns values and releases the stream lock, and native iterator disposal cancels the upstream stream and releases the lock. These checks make no network requests.

Compatibility limit: the deletion is a workaround for the tested TypeScript 6 environment. With TypeScript 5.8.3 and @types/node@24.19.1, it causes TS2538 at the remaining iterator signature: Type 'unique symbol' cannot be used as an index type. An upstream fix needs to preserve support for older compilers.

Could the iterator declarations be updated to support this TypeScript 6 / Node 24 types combination while retaining older compiler compatibility?