docs(http2): clarify transport comments and drop stale undici references

Addresses PR review:

- Clarify the `src/lib/http2-transport.ts` header: explain that transport
  selection matters only on Node (its default `node-fetch` speaks HTTP/1.1),
  while browsers/Deno/Bun already negotiate HTTP/2 via the platform fetch.
- Clarify the `http2` option JSDoc: "Node.js only" distinguishes it from other
  JS runtimes, where the option has no effect.
- Remove stale undici references now that the H2 transport is native
  `node:http2`: the `makeHttp2Fetch` shim docs (Node = `node:http2`, arg is
  H2FetchOptions), the web/Deno no-op comments, the "Replaces undici" note, and
  the undici-based rationale in the README requirements.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Reflex

README.md

@@ -398,7 +398,7 @@ TypeScript >= 4.5 is supported.
 The following runtimes are supported:
 
 - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 20.18.1 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions. (Raised from 18 because the SDK now depends on undici 7 on Node; the HTTP/2 transport needs the undici >= 7.23.0 crash fix, and the package pins `^7.26.0`.)
+- Node.js 20.18.1 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
 - Deno v1.28.0 or higher.
 - Bun 1.0 or later.
 - Cloudflare Workers.

src/_shims/index-deno.ts

@@ -10,8 +10,8 @@ type _fetch = typeof fetch;
 export { _fetch as fetch };
 
 // The platform `fetch` already negotiates HTTP/2 at the transport layer, so
-// `{ http2: ... }` is a no-op on Deno — reuse the global fetch and ignore any passed
-// dispatcher (undici dispatchers are a Node-only concept).
+// `{ http2: ... }` is a no-op on Deno — reuse the global fetch and ignore any
+// passed pool options (the `node:http2` transport is Node-only).
 export const makeHttp2Fetch = () => _fetch;
 
 const _Request = Request;

src/_shims/index.d.ts

@@ -17,12 +17,12 @@ export const fetch: SelectType<typeof manual.fetch, typeof auto.fetch>;
 
 /**
  * Build an HTTP/2-capable `fetch`, used when the client is constructed with
- * `{ http2: ... }`. In Node this is the undici adapter (`Agent({ allowH2: true })`);
- * the optional `dispatcher` lets the caller pass a configured undici `Dispatcher`
- * (the `http2: <Dispatcher>` passthrough), defaulting to the SDK's bounded pool. On
- * the web it returns the platform `fetch`, which already negotiates HTTP/2.
+ * `{ http2: ... }`. On Node this is the native `node:http2` transport; the
+ * optional `options` tune its connection pool (the `http2: <H2FetchOptions>`
+ * passthrough), defaulting to the SDK's shared bounded pool. On the web it
+ * returns the platform `fetch`, which already negotiates HTTP/2.
  */
-export function makeHttp2Fetch(dispatcher?: any): typeof fetch;
+export function makeHttp2Fetch(options?: any): typeof fetch;
 
 // @ts-ignore
 export type Request = SelectType<manual.Request, auto.Request>;

src/_shims/registry.ts

@@ -8,12 +8,12 @@ export interface Shims {
   fetch: any;
   /**
    * Build an HTTP/2-capable `fetch`, used when the client is constructed with
-   * `{ http2: ... }`. In Node this is the undici adapter (`Agent({ allowH2: true })`);
-   * the optional `dispatcher` lets the caller pass a configured undici `Dispatcher`
-   * (the `http2: <Dispatcher>` passthrough), defaulting to the SDK's bounded pool. On
-   * the web the platform `fetch` already negotiates HTTP/2, so the argument is ignored.
+   * `{ http2: ... }`. On Node this is the native `node:http2` transport; the
+   * optional `options` tune its connection pool (the `http2: <H2FetchOptions>`
+   * passthrough), defaulting to the SDK's shared bounded pool. On the web the
+   * platform `fetch` already negotiates HTTP/2, so the argument is ignored.
    */
-  makeHttp2Fetch: (dispatcher?: any) => any;
+  makeHttp2Fetch: (options?: any) => any;
   Request: any;
   Response: any;
   Headers: any;

src/_shims/web-runtime.ts

@@ -36,8 +36,8 @@ export function getRuntime({ manuallyImported }: { manuallyImported?: boolean }
     kind: 'web',
     fetch: _fetch,
     // The platform `fetch` already negotiates HTTP/2 at the transport layer, so
-    // `{ http2: ... }` is a no-op on the web — reuse the global fetch and ignore any
-    // passed dispatcher (undici dispatchers are a Node-only concept).
+    // `{ http2: ... }` is a no-op on the web — reuse the global fetch and ignore
+    // any passed pool options (the `node:http2` transport is Node-only).
     makeHttp2Fetch: () => _fetch,
     Request: _Request,
     Response: _Response,

src/index.ts

@@ -361,7 +361,7 @@ export class Runloop extends Core.APIClient {
    * @param {number} [opts.timeout=30 seconds] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
    * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
-   * @param {boolean | H2FetchOptions} [opts.http2=true] - Send requests over HTTP/2 (Node only; ignored when `fetch` is provided). Enabled by default; pass `false` to use HTTP/1.1, or H2FetchOptions to tune the pool.
+   * @param {boolean | H2FetchOptions} [opts.http2=true] - Send requests over HTTP/2. Enabled by default on Node.js; pass `false` to use HTTP/1.1, or H2FetchOptions to tune the pool. Has no effect on browsers/Deno/Bun (their platform `fetch` already uses HTTP/2) or when a custom `fetch` is provided.
    * @param {number} [opts.maxRetries=5] - The maximum number of times the client will retry a request.
    * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
    * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.

src/lib/h2-transport/index.ts

@@ -1,10 +1,10 @@
 /**
  * A high-performance HTTP/2 fetch adapter built on Node's native `node:http2`.
  *
- * Replaces undici for HTTP/2 transport. Manages a pool of persistent H2 sessions
- * per origin, multiplexing requests as concurrent streams. Each session handles up
- * to the server-advertised MAX_CONCURRENT_STREAMS; the pool auto-scales between
- * minConnections and maxConnections as load requires.
+ * Manages a pool of persistent H2 sessions per origin, multiplexing requests as
+ * concurrent streams. Each session handles up to the server-advertised
+ * MAX_CONCURRENT_STREAMS; the pool auto-scales between minConnections and
+ * maxConnections as load requires.
  *
  * Usage:
  *   const fetch = createH2Fetch({ maxConnections: 20 });

src/lib/http2-transport.ts

@@ -3,11 +3,15 @@ import { type Fetch } from '../core';
 import type { H2FetchOptions } from './h2-transport';
 
 /**
- * Transport-selection logic for the client. Kept out of the generated
- * `src/index.ts` so the generated file only holds a one-line call-site hook.
+ * Transport-selection logic for the client, kept out of the generated
+ * `src/index.ts` (which holds only a one-line call-site hook).
  *
- * HTTP/2 is the default on Node. The web/Deno shims make {@link makeHttp2Fetch}
- * a no-op that returns the platform `fetch`, so this is effectively Node-only.
+ * This selection matters only on Node.js. There the SDK's default transport is
+ * `node-fetch`, which speaks HTTP/1.1, so using HTTP/2 means swapping in the
+ * dedicated `node:http2` transport that {@link makeHttp2Fetch} builds. On
+ * browsers, Deno, and Bun the platform `fetch` already negotiates HTTP/2, so the
+ * shim's {@link makeHttp2Fetch} simply returns that platform `fetch` and this
+ * whole resolution is effectively a no-op.
  */
 
 // A single HTTP/2 transport shared by every client that uses the default pool,