@taquito/http-utils 24.2.0 → 24.3.0-beta.1

package/README.md

@@ -5,7 +5,7 @@
 
 ## General Information
 
-The `HttpBackend` class contains a `createRequest` method which accepts options to be passed for the HTTP request (url, method, timeout, json, query, headers, mimeType). This method will help users interact with the RPC with a more familiar HTTP format.
+The `HttpBackend` class contains a `createRequest` method which accepts options to be passed for the HTTP request (url, method, timeout, json, query, headers). This method will help users interact with the RPC with a more familiar HTTP format.
 
 Parameters for `createRequest`:
 
@@ -14,8 +14,7 @@ Parameters for `createRequest`:
 `timeout`(number): request timeout 
 `json`(boolean): Parse response into JSON when set to `true`; defaults to `true`
 `query`(object): Query that we would like to pass as an HTTP request
-`headers`(object): HTTP request header 
-`mimeType`(string): Sets the MIME type of the request; see [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
+`headers`(object): HTTP request header
 
 
 ## Install
@@ -33,13 +32,23 @@ const httpBackend = new HttpBackend();
 const response = httpBackend.createRequest<string>({
     url: `/chains/${chain}/blocks/${block}/context/contracts/${address}/script`,
     method: 'GET',
-    mimeType: "text; charset=utf-8",
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
     json: false
 });
 
 ```
 
 ## Additional Info
+Taquito uses the built-in `globalThis.fetch` (requires Node.js >= 22 or a browser environment).
+
+For diagnostics, you can emit request timing logs with:
+
+`TAQUITO_HTTP_TRACE=true`
+
+Optionally adjust the slow-request threshold (milliseconds):
+
+`TAQUITO_HTTP_TRACE_SLOW_MS=1500`
+
 See the top-level https://github.com/ecadlabs/taquito file for details on reporting issues, contributing, and versioning.
 
 

package/dist/lib/errors.js

@@ -2,27 +2,77 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTimeoutError = exports.HttpResponseError = exports.HttpRequestFailed = void 0;
 const core_1 = require("@taquito/core");
+const MAX_CAUSE_DEPTH = 10;
+/** Walk the `.cause` chain and return the deepest Error (or object-shaped cause). */
+function deepestCause(err) {
+    let current = err;
+    let depth = 0;
+    for (;;) {
+        if (depth >= MAX_CAUSE_DEPTH)
+            break;
+        const next = current['cause'];
+        if (next instanceof Error) {
+            current = next;
+            depth++;
+            continue;
+        }
+        // Handle object-shaped causes (e.g. undici sometimes throws { message, code } objects)
+        if (typeof next === 'object' &&
+            next !== null &&
+            typeof next['message'] === 'string') {
+            const obj = next;
+            current = {
+                message: obj['message'],
+                code: typeof obj['code'] === 'string' ? obj['code'] : undefined,
+            };
+            break;
+        }
+        break;
+    }
+    return current;
+}
 /**
  *  @category Error
- *  @description Error that indicates a general failure in making the HTTP request
+ *  Error that indicates a general failure in making the HTTP request
  */
 class HttpRequestFailed extends core_1.NetworkError {
-    constructor(method, url, cause) {
+    constructor(
+    /** The HTTP method that was attempted. */
+    method, 
+    /** The URL that was requested. */
+    url, 
+    /** The underlying error that caused the request to fail. */
+    cause, transportError) {
         super();
         this.method = method;
         this.url = url;
         this.cause = cause;
         this.name = 'HttpRequestFailed';
-        this.message = `${method} ${url} ${String(cause)}`;
+        const rootCause = deepestCause(cause);
+        const rootCode = rootCause.code;
+        const detail = rootCause !== cause
+            ? `${rootCause.message}${rootCode ? ` [${rootCode}]` : ''}`
+            : cause.message;
+        const kindLabel = transportError ? ` (${transportError.kind})` : '';
+        this.message = `${method} ${url}${kindLabel}: ${detail}`;
+        this.transportError = transportError;
     }
 }
 exports.HttpRequestFailed = HttpRequestFailed;
 /**
  *  @category Error
- *  @description Error thrown when the endpoint returns an HTTP error to the client
+ *  Error thrown when the endpoint returns an HTTP error to the client
  */
 class HttpResponseError extends core_1.NetworkError {
-    constructor(message, status, statusText, body, url) {
+    constructor(message, 
+    /** The HTTP status code (e.g. 404, 500). */
+    status, 
+    /** The HTTP status text (e.g. "Not Found"). */
+    statusText, 
+    /** The raw response body text. */
+    body, 
+    /** The URL that was requested. */
+    url) {
         super();
         this.message = message;
         this.status = status;
@@ -35,10 +85,14 @@ class HttpResponseError extends core_1.NetworkError {
 exports.HttpResponseError = HttpResponseError;
 /**
  *  @category Error
- *  @description Error
+ *  Error thrown when an HTTP request exceeds its configured timeout duration.
  */
 class HttpTimeoutError extends core_1.NetworkError {
-    constructor(timeout, url) {
+    constructor(
+    /** The timeout duration in milliseconds that was exceeded. */
+    timeout, 
+    /** The URL that was requested. */
+    url) {
         super();
         this.timeout = timeout;
         this.url = url;

package/dist/lib/taquito-http-utils.js

@@ -17,48 +17,22 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpBackend = exports.HttpTimeoutError = exports.HttpResponseError = exports.HttpRequestFailed = exports.VERSION = void 0;
-let fetch = globalThis === null || globalThis === void 0 ? void 0 : globalThis.fetch;
-let createAgent;
-let useNodeFetchAgent = false;
-const isNode = typeof process !== 'undefined' && !!((_a = process === null || process === void 0 ? void 0 : process.versions) === null || _a === void 0 ? void 0 : _a.node);
-const isBrowserLike = typeof window !== 'undefined';
-// Use native fetch in browser-like environments (they have reliable native fetch)
-// Use node-fetch in pure Node.js CLI for better compatibility and keepAlive control
-if (isNode && !isBrowserLike) {
-    // Handle both ESM and CJS default export patterns for webpack compatibility
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const nodeFetch = require('node-fetch');
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const https = require('https');
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const http = require('http');
-    fetch = nodeFetch.default || nodeFetch;
-    useNodeFetchAgent = true;
-    if (Number(process.versions.node.split('.')[0]) >= 19) {
-        // we need agent with keepalive false for node 19 and above
-        createAgent = (url) => {
-            return url.startsWith('https')
-                ? new https.Agent({ keepAlive: false })
-                : new http.Agent({ keepAlive: false });
-        };
-    }
-}
-else if (typeof fetch !== 'function') {
-    throw new Error('No fetch implementation available');
+exports.HttpBackend = exports.classifyTransportError = exports.HttpTimeoutError = exports.HttpResponseError = exports.HttpRequestFailed = exports.VERSION = void 0;
+if (typeof globalThis.fetch !== 'function') {
+    throw new Error('No fetch implementation available. Requires Node.js >= 22 or a browser environment.');
 }
+const httpTraceEnabled = /^(1|true)$/i.test(process?.env?.TAQUITO_HTTP_TRACE ?? '') || process?.env?.RUNNER_DEBUG === '1';
+const parsedHttpRetryCount = Number(process?.env?.TAQUITO_HTTP_RETRY_COUNT ?? '1');
+const httpRetryCount = Number.isFinite(parsedHttpRetryCount) && parsedHttpRetryCount >= 0
+    ? Math.floor(parsedHttpRetryCount)
+    : 1;
+const parsedHttpRetryBaseMs = Number(process?.env?.TAQUITO_HTTP_RETRY_BASE_MS ?? '100');
+const httpRetryBaseMs = Number.isFinite(parsedHttpRetryBaseMs) && parsedHttpRetryBaseMs >= 0
+    ? parsedHttpRetryBaseMs
+    : 100;
 const errors_1 = require("./errors");
+const transport_errors_1 = require("./transport-errors");
 __exportStar(require("./status_code"), exports);
 var version_1 = require("./version");
 Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
@@ -66,10 +40,99 @@ var errors_2 = require("./errors");
 Object.defineProperty(exports, "HttpRequestFailed", { enumerable: true, get: function () { return errors_2.HttpRequestFailed; } });
 Object.defineProperty(exports, "HttpResponseError", { enumerable: true, get: function () { return errors_2.HttpResponseError; } });
 Object.defineProperty(exports, "HttpTimeoutError", { enumerable: true, get: function () { return errors_2.HttpTimeoutError; } });
+var transport_errors_2 = require("./transport-errors");
+Object.defineProperty(exports, "classifyTransportError", { enumerable: true, get: function () { return transport_errors_2.classifyTransportError; } });
+const normalizeTraceUrl = (url) => {
+    try {
+        const parsedUrl = new URL(url);
+        return `${parsedUrl.origin}${parsedUrl.pathname}`;
+    }
+    catch {
+        return url.split('?')[0];
+    }
+};
+const traceHttp = (payload) => {
+    if (!httpTraceEnabled) {
+        return;
+    }
+    // JSON logs make CI-side grepping and aggregation much easier.
+    console.log(`[taquito:http-trace] ${JSON.stringify(payload)}`);
+};
+const getCause = (err) => err['cause'];
+const getCode = (err) => {
+    const code = err['code'];
+    return typeof code === 'string' ? code : undefined;
+};
+const MAX_CAUSE_DEPTH = 10;
+const toErrorMessage = (error) => {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const parts = [`${error.name}: ${error.message}`];
+    let current = getCause(error);
+    let depth = 0;
+    while (depth < MAX_CAUSE_DEPTH) {
+        if (current instanceof Error) {
+            const code = getCode(current);
+            const codeSuffix = code ? ` [${code}]` : '';
+            parts.push(`${current.name}: ${current.message}${codeSuffix}`);
+            current = getCause(current);
+            depth++;
+            continue;
+        }
+        // Handle object-shaped causes (e.g. undici { message, code } objects)
+        if (typeof current === 'object' &&
+            current !== null &&
+            typeof current['message'] === 'string') {
+            const obj = current;
+            const code = typeof obj['code'] === 'string' ? obj['code'] : undefined;
+            const codeSuffix = code ? ` [${code}]` : '';
+            parts.push(`${obj['message']}${codeSuffix}`);
+        }
+        break;
+    }
+    return parts.join(' → ');
+};
+const isRetriableRequest = (method, url) => {
+    const normalizedMethod = method.toUpperCase();
+    if (normalizedMethod === 'GET') {
+        return true;
+    }
+    if (normalizedMethod !== 'POST') {
+        return false;
+    }
+    const normalizedUrl = normalizeTraceUrl(url);
+    return (normalizedUrl.endsWith('/helpers/forge/operations') ||
+        normalizedUrl.endsWith('/helpers/preapply/operations') ||
+        normalizedUrl.endsWith('/helpers/scripts/simulate_operation') ||
+        normalizedUrl.endsWith('/helpers/scripts/run_operation') ||
+        // Safe to retry: ops are content-addressed, mempool deduplicates identical bytes,
+        // and counter prevents replay. If the first request secretly succeeded but the
+        // connection dropped, the retry may get a 500 (async_injection_failed) which
+        // propagates to the caller via HttpResponseError (not retried). No silent corruption,
+        // but the caller may see an error despite the op being on-chain.
+        normalizedUrl.endsWith('/injection/operation'));
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * HTTP client used by Taquito to communicate with Tezos RPC nodes.
+ *
+ * Uses `globalThis.fetch` (Node.js >= 22 built-in or browser native).
+ * Retries retriable transport errors (socket resets, DNS, timeouts) with
+ * exponential backoff and jitter. Configure via environment variables:
+ *
+ * - `TAQUITO_HTTP_RETRY_COUNT` - max retries (default `1`)
+ * - `TAQUITO_HTTP_RETRY_BASE_MS` - base delay in ms (default `100`)
+ * - `TAQUITO_HTTP_TRACE` - emit JSON request logs when `true` or `1`
+ */
 class HttpBackend {
+    /**
+     * @param timeout - Default request timeout in milliseconds (default `30000`).
+     */
     constructor(timeout = 30000) {
         this.timeout = timeout;
     }
+    /** Serialize an object into a URL query string (including the leading `?`). */
     serialize(obj) {
         if (!obj) {
             return '';
@@ -78,9 +141,14 @@ class HttpBackend {
         for (const p in obj) {
             // eslint-disable-next-line no-prototype-builtins
             if (obj.hasOwnProperty(p) && typeof obj[p] !== 'undefined') {
-                const prop = typeof obj[p].toJSON === 'function' ? obj[p].toJSON() : obj[p];
+                const val = obj[p];
                 // query arguments can have no value so we need some way of handling that
                 // example https://domain.com/query?all
+                if (val === null) {
+                    str.push(encodeURIComponent(p));
+                    continue;
+                }
+                const prop = typeof val.toJSON === 'function' ? val.toJSON() : val;
                 if (prop === null) {
                     str.push(encodeURIComponent(p));
                     continue;
@@ -105,33 +173,64 @@ class HttpBackend {
         }
     }
     /**
+     * Send an HTTP request to the given URL, with automatic retries on transport errors.
      *
-     * @param options contains options to be passed for the HTTP request (url, method and timeout)
-     * @throws {@link HttpRequestFailed} | {@link HttpResponseError} | {@link HttpTimeoutError}
+     * @param options - Request configuration (URL, method, timeout, headers, etc.).
+     * @param data - Request body, serialized to JSON via `JSON.stringify`.
+     * @returns The parsed JSON response (or raw text when `json: false`).
+     * @throws {@link HttpResponseError} when the server returns HTTP status >= 400.
+     * @throws {@link HttpTimeoutError} when the request exceeds the configured timeout.
+     * @throws {@link HttpRequestFailed} for transport-level failures (network, DNS, socket, etc.).
      */
-    createRequest(_a, data_1) {
-        return __awaiter(this, arguments, void 0, function* ({ url, method, timeout = this.timeout, query, headers = {}, json = true }, data) {
-            // Serializes query params
-            const urlWithQuery = url + this.serialize(query);
-            // Adds default header entry if there aren't any Content-Type header
-            if (!headers['Content-Type']) {
-                headers['Content-Type'] = 'application/json';
-            }
+    async createRequest({ url, method, timeout = this.timeout, query, headers = {}, json = true }, data) {
+        // Serializes query params
+        const urlWithQuery = url + this.serialize(query);
+        const methodValue = String(method ?? 'GET');
+        // Adds default header entry if there aren't any Content-Type header
+        if (!headers['Content-Type']) {
+            headers['Content-Type'] = 'application/json';
+        }
+        // Serialized once on first attempt, reused on retries for byte-stable requests.
+        let body;
+        let bodySerialized = false;
+        for (let attempt = 0; attempt <= httpRetryCount; attempt++) {
             // Creates a new AbortController instance to handle timeouts
             const controller = new AbortController();
             const t = setTimeout(() => controller.abort(), timeout);
+            const requestStartedAt = Date.now();
             try {
-                const response = yield fetch(urlWithQuery, Object.assign({ keepalive: false, // Disable keepalive (keepalive defaults to true starting from Node 19 & 20)
+                if (!bodySerialized) {
+                    body = JSON.stringify(data);
+                    bodySerialized = true;
+                }
+                const response = await globalThis.fetch(urlWithQuery, {
                     method,
-                    headers, body: JSON.stringify(data), signal: controller.signal }, (useNodeFetchAgent && createAgent ? { agent: createAgent(urlWithQuery) } : {})));
+                    headers,
+                    body,
+                    signal: controller.signal,
+                });
                 if (typeof response === 'undefined') {
                     throw new Error('Response is undefined');
                 }
                 // Handle responses with status code >= 400
                 if (response.status >= 400) {
-                    const errorData = yield response.text();
+                    const errorData = await response.text();
+                    traceHttp({
+                        stage: 'response-error',
+                        method: methodValue,
+                        url: normalizeTraceUrl(urlWithQuery),
+                        status: response.status,
+                        elapsedMs: Date.now() - requestStartedAt,
+                    });
                     throw new errors_1.HttpResponseError(`Http error response: (${response.status}) ${errorData}`, response.status, response.statusText, errorData, urlWithQuery);
                 }
+                traceHttp({
+                    stage: 'response-ok',
+                    method: methodValue,
+                    url: normalizeTraceUrl(urlWithQuery),
+                    status: response.status,
+                    elapsedMs: Date.now() - requestStartedAt,
+                });
                 if (json) {
                     return response.json();
                 }
@@ -140,20 +239,70 @@ class HttpBackend {
                 }
             }
             catch (e) {
-                if (e instanceof Error && e.name === 'AbortError') {
-                    throw new errors_1.HttpTimeoutError(timeout, urlWithQuery);
-                }
-                else if (e instanceof errors_1.HttpResponseError) {
+                // HttpResponseError is an application-level error (status >= 400), not a transport error.
+                // Short-circuit before classification to prevent RPC body text (which may contain
+                // strings like "connection reset") from being misclassified as a transport error.
+                if (e instanceof errors_1.HttpResponseError) {
+                    traceHttp({
+                        stage: 'http-response-error',
+                        method: methodValue,
+                        url: normalizeTraceUrl(urlWithQuery),
+                        elapsedMs: Date.now() - requestStartedAt,
+                        status: e.status,
+                    });
                     throw e;
                 }
+                const classified = e instanceof Error ? (0, transport_errors_1.classifyTransportError)(e) : undefined;
+                const isRetriableTransport = classified !== undefined && classified.kind !== 'abort' && classified.kind !== 'tls';
+                const shouldRetry = attempt < httpRetryCount &&
+                    isRetriableRequest(methodValue, urlWithQuery) &&
+                    isRetriableTransport;
+                if (shouldRetry) {
+                    const exponential = httpRetryBaseMs * Math.pow(2, attempt);
+                    const jitter = Math.floor(Math.random() * httpRetryBaseMs);
+                    const retryDelayMs = exponential + jitter;
+                    traceHttp({
+                        stage: 'request-retry',
+                        method: methodValue,
+                        url: normalizeTraceUrl(urlWithQuery),
+                        elapsedMs: Date.now() - requestStartedAt,
+                        attempt: attempt + 1,
+                        maxAttempts: httpRetryCount + 1,
+                        retryDelayMs,
+                        error: toErrorMessage(e),
+                        transportKind: classified?.kind,
+                    });
+                    await sleep(retryDelayMs);
+                    continue;
+                }
+                if (classified?.kind === 'abort') {
+                    traceHttp({
+                        stage: 'timeout',
+                        method: methodValue,
+                        url: normalizeTraceUrl(urlWithQuery),
+                        elapsedMs: Date.now() - requestStartedAt,
+                        timeoutMs: timeout,
+                    });
+                    throw new errors_1.HttpTimeoutError(timeout, urlWithQuery);
+                }
                 else {
-                    throw new errors_1.HttpRequestFailed(String(method), urlWithQuery, e);
+                    traceHttp({
+                        stage: 'request-failed',
+                        method: methodValue,
+                        url: normalizeTraceUrl(urlWithQuery),
+                        elapsedMs: Date.now() - requestStartedAt,
+                        error: toErrorMessage(e),
+                        transportKind: classified?.kind,
+                    });
+                    const cause = e instanceof Error ? e : new Error(String(e));
+                    throw new errors_1.HttpRequestFailed(methodValue, urlWithQuery, cause, classified);
                 }
             }
             finally {
                 clearTimeout(t);
             }
-        });
+        }
+        throw new Error('Unexpected request retry flow');
     }
 }
 exports.HttpBackend = HttpBackend;

package/dist/lib/transport-errors.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Cross-runtime transport error classifier.
+ *
+ * Inspects structural properties first (err.code, err.cause.code, err.name),
+ * falls back to message substring matching only when structure isn't enough.
+ * Handles node-fetch FetchError, native fetch/undici TypeError + cause chain,
+ * browser TypeError, Deno, and Bun error shapes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyTransportError = classifyTransportError;
+const MAY_HAVE_REACHED = {
+    abort: false,
+    dns: false,
+    connect: false,
+    socket: true,
+    tls: false,
+    timeout: true,
+    network: true,
+};
+function extractCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const code = err['code'];
+    return typeof code === 'string' ? code : undefined;
+}
+function extractCause(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    return err['cause'];
+}
+function extractCauseCode(err) {
+    return extractCode(extractCause(err));
+}
+function extractCauseMessage(err) {
+    const cause = extractCause(err);
+    if (typeof cause === 'object' && cause !== null) {
+        const msg = cause['message'];
+        if (typeof msg === 'string')
+            return msg.toLowerCase();
+    }
+    return '';
+}
+function classify(kind, err) {
+    return { kind, mayHaveReachedServer: MAY_HAVE_REACHED[kind], original: err };
+}
+/**
+ * Classify a thrown value as a transport-level error.
+ *
+ * Inspects structural properties first (err.code, err.cause.code, err.name),
+ * then falls back to message substring matching. Handles node-fetch FetchError,
+ * native fetch/undici TypeError + cause chain, browser TypeError, Deno, and Bun.
+ *
+ * @returns the classification, or `undefined` if the error is not transport-related.
+ */
+function classifyTransportError(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const code = extractCode(err);
+    const causeCode = extractCauseCode(err);
+    const msg = err.message.toLowerCase();
+    const causeMsg = extractCauseMessage(err);
+    // 1. AbortError (our timeout or caller cancel)
+    if (err.name === 'AbortError') {
+        return classify('abort', err);
+    }
+    // 2. DNS resolution failure
+    if (code === 'ENOTFOUND' ||
+        code === 'EAI_AGAIN' ||
+        causeCode === 'ENOTFOUND' ||
+        causeCode === 'EAI_AGAIN' ||
+        msg.includes('enotfound') ||
+        msg.includes('eai_again')) {
+        return classify('dns', err);
+    }
+    // 3. Connection refused / connect timeout
+    if (code === 'ECONNREFUSED' ||
+        causeCode === 'ECONNREFUSED' ||
+        causeCode === 'UND_ERR_CONNECT_TIMEOUT' ||
+        msg.includes('econnrefused')) {
+        return classify('connect', err);
+    }
+    // 4. TLS errors (check before socket/timeout since TLS errors can also set ECONNRESET)
+    // Also inspect cause.message for native fetch which wraps TLS errors in TypeError("fetch failed")
+    if (msg.includes('certificate') ||
+        msg.includes('self signed') ||
+        msg.includes('ssl') ||
+        msg.includes('handshake') ||
+        causeMsg.includes('certificate') ||
+        causeMsg.includes('self signed') ||
+        causeMsg.includes('ssl') ||
+        causeMsg.includes('handshake')) {
+        return classify('tls', err);
+    }
+    // 5. TCP/connect timeout and undici header/body timeouts
+    if (code === 'ETIMEDOUT' ||
+        causeCode === 'ETIMEDOUT' ||
+        causeCode === 'UND_ERR_HEADERS_TIMEOUT' ||
+        causeCode === 'UND_ERR_BODY_TIMEOUT' ||
+        msg.includes('etimedout') ||
+        msg.includes('timed out')) {
+        return classify('timeout', err);
+    }
+    // 6. Socket-level errors (connection was established or partially established)
+    if (code === 'ECONNRESET' ||
+        causeCode === 'ECONNRESET' ||
+        causeCode === 'UND_ERR_SOCKET' ||
+        msg.includes('econnreset') ||
+        msg.includes('socket hang up') ||
+        msg.includes('other side closed') ||
+        msg.includes('closed unexpectedly') ||
+        msg.includes('connection reset')) {
+        return classify('socket', err);
+    }
+    // 7. Generic fetch failure (browser TypeError, undici wrapper)
+    // "terminated" is undici's wrapper for body-read failures (e.g. response.json() after socket drop)
+    if (err instanceof TypeError &&
+        (msg.includes('fetch failed') ||
+            msg.includes('failed to fetch') ||
+            msg.includes('network error') ||
+            msg.includes('error sending request') ||
+            msg === 'terminated')) {
+        return classify('network', err);
+    }
+    // 8. Remaining node-fetch FetchError.
+    // Transport types: 'system' (OS-level), 'request-timeout', 'body-timeout'.
+    // Non-transport types: 'invalid-json', 'no-redirect', 'max-size'.
+    if (err.name === 'FetchError') {
+        const fetchType = err['type'];
+        if (fetchType === 'request-timeout' || fetchType === 'body-timeout') {
+            return classify('timeout', err);
+        }
+        if (fetchType === 'system') {
+            return classify('network', err);
+        }
+        // Not a transport error (e.g. JSON parse failure on a 200 response)
+        return undefined;
+    }
+    // Not a transport error
+    return undefined;
+}

package/dist/lib/version.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // IMPORTANT: THIS FILE IS AUTO GENERATED! DO NOT MANUALLY EDIT!
 exports.VERSION = {
-    "commitHash": "105a7b15cfb862a0732c204e0e9741098d697775",
-    "version": "24.2.0"
+    "commitHash": "05df48fee92f846cba793920d6fa829afd6a1847",
+    "version": "24.3.0-beta.1"
 };