recker 1.0.2-0 → 1.0.4

package/dist/core/client.js

@@ -1,9 +1,9 @@
+import { consoleLogger } from '../types/index.js';
 import { HttpRequest } from './request.js';
 import { UndiciTransport } from '../transport/undici.js';
 import { RequestPromise } from './request-promise.js';
-import { HttpError } from '../core/errors.js';
-import { getLogger } from '../utils/logger.js';
-import { processBody } from '../utils/body.js';
+import { HttpError, MaxSizeExceededError, ReckerError } from '../core/errors.js';
+import { processBody, createFormData, isPlainObject } from '../utils/body.js';
 import { AgentManager } from '../utils/agent-manager.js';
 import { RequestPool } from '../utils/request-pool.js';
 import { normalizeConcurrency } from '../utils/concurrency.js';
@@ -14,11 +14,14 @@ import { cache } from '../plugins/cache.js';
 import { dedup } from '../plugins/dedup.js';
 import { createXSRFMiddleware } from '../plugins/xsrf.js';
 import { createCompressionMiddleware } from '../plugins/compression.js';
+import { serializeXML } from '../plugins/xml.js';
 import { MemoryStorage } from '../cache/memory-storage.js';
 import { FileStorage } from '../cache/file-storage.js';
 import { RequestRunner } from '../runner/request-runner.js';
 import { ReckerWebSocket } from '../websocket/client.js';
 import { whois as performWhois, isDomainAvailable } from '../utils/whois.js';
+import { MemoryCookieJar } from '../cookies/memory-cookie-jar.js';
+import { scrape as scrapeHelper } from '../plugins/scrape.js';
 export class Client {
     baseUrl;
     middlewares;
@@ -33,6 +36,9 @@ export class Client {
     agentManager;
     concurrencyConfig;
     requestPool;
+    maxResponseSize;
+    cookieJar;
+    cookieIgnoreInvalid = false;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || '';
         this.middlewares = options.middlewares || [];
@@ -49,9 +55,13 @@ export class Client {
         };
         this.defaultParams = options.defaults?.params || {};
         this.paginationConfig = options.pagination;
+        this.maxResponseSize = options.maxResponseSize;
         this.debugEnabled = options.debug === true;
         if (this.debugEnabled) {
-            this.logger = getLogger();
+            this.logger = options.logger ?? consoleLogger;
+        }
+        else if (options.logger) {
+            this.logger = options.logger;
         }
         this.concurrencyConfig = normalizeConcurrency({
             concurrency: options.concurrency,
@@ -75,11 +85,18 @@ export class Client {
                 proxy: options.proxy,
                 http2: http2Options,
                 dns: options.dns,
-                agent: this.agentManager
+                agent: this.agentManager,
+                socketPath: options.socketPath,
+                tls: options.tls,
+                observability: options.observability
             });
         }
         else {
-            throw new Error('baseUrl is required for default UndiciTransport, or provide a custom transport.');
+            throw new ReckerError('baseUrl is required for default UndiciTransport, or provide a custom transport.', undefined, undefined, [
+                'Set baseUrl when using the built-in Undici transport.',
+                'Pass an absolute URL to each request.',
+                'Provide a custom transport if you need to handle relative paths differently.'
+            ]);
         }
         if (options.retry) {
             retry(options.retry)(this);
@@ -91,13 +108,13 @@ export class Client {
                 interval: this.concurrencyConfig.interval
             });
             this.middlewares.unshift(this.requestPool.asMiddleware());
-            if (this.debugEnabled) {
-                console.log(`[Recker] Global concurrency limit: ${this.concurrencyConfig.max} concurrent requests`);
+            if (this.debugEnabled && this.logger) {
+                this.logger.debug(`Global concurrency limit: ${this.concurrencyConfig.max} concurrent requests`);
             }
         }
         else {
-            if (this.debugEnabled) {
-                console.log('[Recker] No global concurrency limit (allows unlimited parallel batches)');
+            if (this.debugEnabled && this.logger) {
+                this.logger.debug('No global concurrency limit (allows unlimited parallel batches)');
             }
         }
         if (options.dedup) {
@@ -134,6 +151,12 @@ export class Client {
                 this.middlewares.push(xsrfMiddleware);
             }
         }
+        if (options.cookies) {
+            this.setupCookieJar(options.cookies);
+        }
+        if (this.maxResponseSize !== undefined) {
+            this.middlewares.push(this.createMaxSizeMiddleware(this.maxResponseSize));
+        }
         if (this.debugEnabled && this.logger) {
             this.middlewares.unshift(this.createLoggingMiddleware(this.logger));
         }
@@ -143,18 +166,107 @@ export class Client {
     createLoggingMiddleware(logger) {
         return async (req, next) => {
             const startTime = Date.now();
-            logger.logRequest(req);
+            logger.debug({ type: 'request', method: req.method, url: req.url }, `→ ${req.method} ${req.url}`);
             try {
                 const response = await next(req);
-                logger.logResponse(req, response, startTime);
+                const duration = Date.now() - startTime;
+                logger.debug({
+                    type: 'response',
+                    method: req.method,
+                    url: req.url,
+                    status: response.status,
+                    duration,
+                    timings: response.timings,
+                }, `← ${response.status} ${req.method} ${req.url} (${duration}ms)`);
                 return response;
             }
             catch (error) {
-                logger.logError(req, error);
+                const duration = Date.now() - startTime;
+                const err = error;
+                logger.error({
+                    type: 'error',
+                    method: req.method,
+                    url: req.url,
+                    error: err.message,
+                    errorName: err.name,
+                    duration,
+                }, `✖ ${req.method} ${req.url} - ${err.message}`);
                 throw error;
             }
         };
     }
+    createMaxSizeMiddleware(globalMaxSize) {
+        return async (req, next) => {
+            const response = await next(req);
+            const limit = req.maxResponseSize ?? globalMaxSize;
+            if (limit === undefined)
+                return response;
+            const contentLength = response.headers.get('Content-Length');
+            if (contentLength) {
+                const size = parseInt(contentLength, 10);
+                if (!isNaN(size) && size > limit) {
+                    throw new MaxSizeExceededError(limit, size, req);
+                }
+            }
+            return response;
+        };
+    }
+    setupCookieJar(options) {
+        if (options === true) {
+            this.cookieJar = new MemoryCookieJar();
+        }
+        else if (typeof options === 'object') {
+            if (options.jar === true) {
+                this.cookieJar = new MemoryCookieJar();
+            }
+            else if (options.jar && typeof options.jar === 'object') {
+                this.cookieJar = options.jar;
+            }
+            this.cookieIgnoreInvalid = options.ignoreInvalid ?? false;
+        }
+        if (this.cookieJar) {
+            this.middlewares.push(this.createCookieMiddleware());
+        }
+    }
+    createCookieMiddleware() {
+        return async (req, next) => {
+            const jar = this.cookieJar;
+            try {
+                const cookieString = await jar.getCookieString(req.url);
+                if (cookieString) {
+                    const existingCookie = req.headers.get('cookie');
+                    const newCookie = existingCookie
+                        ? `${existingCookie}; ${cookieString}`
+                        : cookieString;
+                    req.headers.set('cookie', newCookie);
+                }
+            }
+            catch (error) {
+                if (!this.cookieIgnoreInvalid) {
+                    throw error;
+                }
+            }
+            const response = await next(req);
+            const setCookieHeader = response.headers.get('set-cookie');
+            if (setCookieHeader) {
+                const cookies = this.splitSetCookieHeader(setCookieHeader);
+                for (const cookie of cookies) {
+                    try {
+                        await jar.setCookie(cookie, req.url);
+                    }
+                    catch (error) {
+                        if (!this.cookieIgnoreInvalid) {
+                            throw error;
+                        }
+                    }
+                }
+            }
+            return response;
+        };
+    }
+    splitSetCookieHeader(header) {
+        return header.split(/,(?=\s*[a-zA-Z0-9_-]+=)/g).map(s => s.trim());
+    }
     composeMiddlewares() {
         const chain = [...this.middlewares];
         const transportDispatch = this.transport.dispatch.bind(this.transport);
@@ -204,7 +316,7 @@ export class Client {
     };
     httpErrorMiddleware = async (req, next) => {
         const response = await next(req);
-        if (req.throwHttpErrors !== false && !response.ok) {
+        if (req.throwHttpErrors !== false && !response.ok && response.status !== 304) {
             throw new HttpError(response, req);
         }
         return response;
@@ -242,8 +354,13 @@ export class Client {
         const hasRequestParams = requestParams && Object.keys(requestParams).length > 0;
         const hasDefaultParams = Object.keys(this.defaultParams).length > 0;
         if (!hasRequestParams && !hasDefaultParams) {
-            if (this.baseUrl && !path.startsWith('http')) {
-                return new URL(path, this.baseUrl).toString();
+            if (path.startsWith('http://') || path.startsWith('https://')) {
+                return path;
+            }
+            if (this.baseUrl) {
+                const base = this.baseUrl.endsWith('/') ? this.baseUrl.slice(0, -1) : this.baseUrl;
+                const p = path.startsWith('/') ? path : '/' + path;
+                return base + p;
             }
             return path;
         }
@@ -254,60 +371,92 @@ export class Client {
             finalPath = finalPath.replace(/:([a-zA-Z0-9_]+)/g, (match, paramName) => {
                 if (mergedParams && paramName in mergedParams) {
                     usedParams.add(paramName);
-                    return String(mergedParams[paramName]);
+                    return encodeURIComponent(String(mergedParams[paramName]));
                 }
-                throw new Error(`Missing required path parameter: ${paramName}`);
+                throw new ReckerError(`Missing required path parameter: ${paramName}`, undefined, undefined, [
+                    `Provide '${paramName}' in request params or defaults.`,
+                    'Ensure the path template matches the provided params.',
+                    'If optional, remove the placeholder from the path.'
+                ]);
             });
         }
-        let finalUrl = finalPath;
-        if (this.baseUrl && !finalPath.startsWith('http://') && !finalPath.startsWith('https://')) {
-            finalUrl = new URL(finalPath, this.baseUrl).toString();
+        let finalUrl;
+        if (finalPath.startsWith('http://') || finalPath.startsWith('https://')) {
+            finalUrl = finalPath;
         }
-        else if (!this.baseUrl && !finalPath.startsWith('http://') && !finalPath.startsWith('https://')) {
-            throw new Error('Relative path provided without a baseUrl or explicit transport.');
+        else if (this.baseUrl) {
+            const base = this.baseUrl.endsWith('/') ? this.baseUrl.slice(0, -1) : this.baseUrl;
+            const p = finalPath.startsWith('/') ? finalPath : '/' + finalPath;
+            finalUrl = base + p;
+        }
+        else {
+            throw new ReckerError('Relative path provided without a baseUrl or explicit transport.', undefined, undefined, [
+                'Set baseUrl when creating the client.',
+                'Use an absolute URL in request().',
+                'Provide a custom transport that resolves relative paths.'
+            ]);
         }
         const remainingKeys = Object.keys(mergedParams).filter((k) => !usedParams.has(k));
         if (remainingKeys.length > 0) {
-            const urlObj = new URL(finalUrl);
-            remainingKeys.forEach((key) => {
-                urlObj.searchParams.append(key, String(mergedParams[key]));
-            });
-            return urlObj.toString();
+            const queryParts = remainingKeys.map(key => `${encodeURIComponent(key)}=${encodeURIComponent(String(mergedParams[key]))}`);
+            const separator = finalUrl.includes('?') ? '&' : '?';
+            return finalUrl + separator + queryParts.join('&');
         }
         return finalUrl;
     }
     request(path, options = {}) {
         const url = this.buildUrl(path, options.params);
-        let mergedHeaders = this.defaultHeaders;
+        let mergedHeaders;
         if (options.headers) {
-            mergedHeaders = new Headers(this.defaultHeaders);
-            new Headers(options.headers).forEach((value, key) => mergedHeaders.append(key, value));
+            mergedHeaders = this.defaultHeaders instanceof Headers
+                ? new Headers(this.defaultHeaders)
+                : new Headers(this.defaultHeaders);
+            const optHeaders = options.headers instanceof Headers
+                ? options.headers
+                : new Headers(options.headers);
+            optHeaders.forEach((value, key) => mergedHeaders.append(key, value));
         }
-        else if (!(mergedHeaders instanceof Headers)) {
-            mergedHeaders = new Headers(mergedHeaders);
+        else {
+            mergedHeaders = this.defaultHeaders instanceof Headers
+                ? this.defaultHeaders
+                : new Headers(this.defaultHeaders);
         }
-        const controller = new AbortController();
-        let signal = controller.signal;
+        const needsController = options.timeout || options.signal;
+        let controller;
+        let signal = options.signal;
         let timeoutId;
         let externalAbortCleanup;
-        if (options.signal) {
-            const externalSignal = options.signal;
-            const abortHandler = () => controller.abort(externalSignal.reason);
-            if (externalSignal.aborted) {
-                abortHandler();
+        if (needsController) {
+            controller = new AbortController();
+            signal = controller.signal;
+            if (options.signal) {
+                const externalSignal = options.signal;
+                const abortHandler = () => controller.abort(externalSignal.reason);
+                if (externalSignal.aborted) {
+                    abortHandler();
+                }
+                else {
+                    externalSignal.addEventListener('abort', abortHandler, { once: true });
+                    externalAbortCleanup = () => externalSignal.removeEventListener('abort', abortHandler);
+                }
             }
-            else {
-                externalSignal.addEventListener('abort', abortHandler, { once: true });
-                externalAbortCleanup = () => externalSignal.removeEventListener('abort', abortHandler);
+            const timeout = options.timeout;
+            if (timeout) {
+                const totalTimeout = typeof timeout === 'number' ? timeout : timeout.request;
+                if (totalTimeout) {
+                    timeoutId = setTimeout(() => controller.abort(new ReckerError('Request timed out (total timeout reached)', req, undefined, [
+                        'Increase the timeout value for long-running requests.',
+                        'Check upstream performance or network latency.',
+                        'Use per-phase timeouts to pinpoint where the delay occurs.'
+                    ])), totalTimeout);
+                }
             }
         }
-        if (options.timeout) {
-            timeoutId = setTimeout(() => controller.abort(new Error('Request timed out')), options.timeout);
-        }
         const req = new HttpRequest(url, {
             ...options,
             headers: mergedHeaders,
             signal,
+            maxResponseSize: options.maxResponseSize ?? this.maxResponseSize
         });
         const responsePromise = this.handler(req);
         if (timeoutId || externalAbortCleanup) {
@@ -315,6 +464,7 @@ export class Client {
                 if (timeoutId)
                     clearTimeout(timeoutId);
                 externalAbortCleanup?.();
+            }).catch(() => {
             });
         }
         return new RequestPromise(responsePromise, controller);
@@ -339,13 +489,53 @@ export class Client {
     multi(requests, options = {}) {
         return this.batch(requests, options);
     }
-    requestWithBody(method, path, body, options = {}) {
-        const { body: processedBody, contentType } = processBody(body);
-        const headers = new Headers(options.headers);
-        if (contentType && !headers.has('Content-Type')) {
-            headers.set('Content-Type', contentType);
+    requestWithBody(method, path, bodyOrOptions, options) {
+        let actualBody = bodyOrOptions;
+        let actualOptions = options;
+        const isOptionsEmpty = actualOptions === undefined ||
+            (typeof actualOptions === 'object' && actualOptions !== null && Object.keys(actualOptions).length === 0);
+        if (isOptionsEmpty && isPlainObject(bodyOrOptions)) {
+            const potentialOptions = bodyOrOptions;
+            if (potentialOptions.json !== undefined ||
+                potentialOptions.form !== undefined ||
+                potentialOptions.xml !== undefined ||
+                potentialOptions.body !== undefined ||
+                potentialOptions.headers !== undefined ||
+                potentialOptions.timeout !== undefined ||
+                potentialOptions.retry !== undefined ||
+                potentialOptions.hooks !== undefined ||
+                potentialOptions.searchParams !== undefined ||
+                potentialOptions.params !== undefined) {
+                actualOptions = bodyOrOptions;
+                actualBody = undefined;
+            }
         }
-        return this.request(path, { ...options, method, body: processedBody, headers });
+        actualOptions = actualOptions || {};
+        const { json, form, xml, ...restOptions } = actualOptions;
+        let finalBody = actualBody;
+        let explicitContentType;
+        if (form !== undefined) {
+            finalBody = createFormData(form);
+            explicitContentType = undefined;
+        }
+        else if (json !== undefined) {
+            finalBody = JSON.stringify(json);
+            explicitContentType = 'application/json';
+        }
+        else if (xml !== undefined) {
+            finalBody = '<?xml version="1.0" encoding="UTF-8"?>\n' + serializeXML(xml);
+            explicitContentType = 'application/xml';
+        }
+        else if (restOptions.body !== undefined) {
+            finalBody = restOptions.body;
+        }
+        const { body: processedBody, contentType } = processBody(finalBody);
+        const headers = new Headers(restOptions.headers);
+        const finalContentType = explicitContentType ?? contentType;
+        if (finalContentType && !headers.has('Content-Type')) {
+            headers.set('Content-Type', finalContentType);
+        }
+        return this.request(path, { ...restOptions, method, body: processedBody, headers });
     }
     post(path, body, options = {}) {
         return this.requestWithBody('POST', path, body, options);
@@ -401,6 +591,11 @@ export class Client {
     unlink(path, body, options = {}) {
         return this.requestWithBody('UNLINK', path, body, options);
     }
+    scrape(path, options = {}) {
+        const method = options.method || 'GET';
+        const requestPromise = this.request(path, { ...options, method });
+        return scrapeHelper(requestPromise);
+    }
     paginate(path, options = {}) {
         const { getItems, getNextUrl, maxPages, pageParam, limitParam, resultsPath, nextCursorPath, ...reqOptions } = options;
         const paginationOpts = {
@@ -448,7 +643,11 @@ export class Client {
             wsUrl = new URL(path, base).toString();
         }
         else {
-            throw new Error('WebSocket requires either a full ws:// URL or a baseUrl');
+            throw new ReckerError('WebSocket requires either a full ws:// URL or a baseUrl', undefined, undefined, [
+                'Pass a full ws:// or wss:// URL to websocket().',
+                'Configure baseUrl so relative websocket paths can be resolved.',
+                'Ensure the baseUrl uses http/https so it can be converted to ws/wss.'
+            ]);
         }
         const headersObj = {};
         if (this.defaultHeaders) {

package/dist/core/errors.d.ts

@@ -2,18 +2,34 @@ import { ReckerRequest, ReckerResponse } from '../types/index.js';
 export declare class ReckerError extends Error {
     request?: ReckerRequest;
     response?: ReckerResponse;
-    constructor(message: string, request?: ReckerRequest, response?: ReckerResponse);
+    suggestions: string[];
+    retriable: boolean;
+    constructor(message: string, request?: ReckerRequest, response?: ReckerResponse, suggestions?: string[], retriable?: boolean);
 }
 export declare class HttpError extends ReckerError {
     status: number;
     statusText: string;
     constructor(response: ReckerResponse, request?: ReckerRequest);
 }
+export type TimeoutPhase = 'lookup' | 'connect' | 'secureConnect' | 'socket' | 'send' | 'response' | 'request';
 export declare class TimeoutError extends ReckerError {
-    constructor(request?: ReckerRequest);
+    phase: TimeoutPhase;
+    timeout: number;
+    elapsed?: number;
+    event: string;
+    constructor(request?: ReckerRequest, options?: {
+        phase?: TimeoutPhase;
+        timeout?: number;
+        elapsed?: number;
+    });
 }
 export declare class NetworkError extends ReckerError {
     code?: string;
     constructor(message: string, code?: string, request?: ReckerRequest);
 }
+export declare class MaxSizeExceededError extends ReckerError {
+    maxSize: number;
+    actualSize?: number;
+    constructor(maxSize: number, actualSize?: number, request?: ReckerRequest);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElE,qBAAa,WAAY,SAAQ,KAAK;IACpC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,cAAc;CAMhF;AAED,qBAAa,SAAU,SAAQ,WAAW;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;gBAEP,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa;CAM9D;AAED,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,CAAC,EAAE,aAAa;CAIpC;AAED,qBAAa,YAAa,SAAQ,WAAW;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa;CAKpE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElE,qBAAa,WAAY,SAAQ,KAAK;IACpC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;gBAGjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,EACvB,QAAQ,CAAC,EAAE,cAAc,EACzB,WAAW,GAAE,MAAM,EAAO,EAC1B,SAAS,UAAQ;CASpB;AAED,qBAAa,SAAU,SAAQ,WAAW;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;gBAEP,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa;CAY9D;AAKD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,SAAS,GACT,eAAe,GACf,QAAQ,GACR,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAMd,qBAAa,YAAa,SAAQ,WAAW;IAI3C,KAAK,EAAE,YAAY,CAAC;IAKpB,OAAO,EAAE,MAAM,CAAC;IAKhB,OAAO,CAAC,EAAE,MAAM,CAAC;IAKjB,KAAK,EAAE,MAAM,CAAC;gBAGZ,OAAO,CAAC,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;CAqCJ;AAED,qBAAa,YAAa,SAAQ,WAAW;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa;CAUpE;AAED,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAER,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa;CAmB1E"}

package/dist/core/errors.js

@@ -1,34 +1,95 @@
 export class ReckerError extends Error {
     request;
     response;
-    constructor(message, request, response) {
+    suggestions;
+    retriable;
+    constructor(message, request, response, suggestions = [], retriable = false) {
         super(message);
         this.name = 'ReckerError';
         this.request = request;
         this.response = response;
+        this.suggestions = suggestions;
+        this.retriable = retriable;
     }
 }
 export class HttpError extends ReckerError {
     status;
     statusText;
     constructor(response, request) {
-        super(`Request failed with status code ${response.status} ${response.statusText}`, request, response);
+        super(`Request failed with status code ${response.status} ${response.statusText}`, request, response, ['Check the upstream service response body for error details.', 'Inspect request headers/body to ensure they match the API contract.', 'Retry if this is a transient 5xx/429 error.'], isRetryableStatus(response.status));
         this.name = 'HttpError';
         this.status = response.status;
         this.statusText = response.statusText;
     }
 }
 export class TimeoutError extends ReckerError {
-    constructor(request) {
-        super('Request timed out', request);
+    phase;
+    timeout;
+    elapsed;
+    event;
+    constructor(request, options) {
+        const phase = options?.phase || 'request';
+        const timeout = options?.timeout;
+        const elapsed = options?.elapsed;
+        const phaseMessages = {
+            lookup: 'DNS lookup timed out',
+            connect: 'TCP connection timed out',
+            secureConnect: 'TLS handshake timed out',
+            socket: 'Socket assignment timed out (connection pool exhausted)',
+            send: 'Request body upload timed out',
+            response: 'Waiting for response timed out (TTFB)',
+            request: 'Request timed out (total time exceeded)'
+        };
+        let message = phaseMessages[phase];
+        if (timeout !== undefined) {
+            message += ` after ${timeout}ms`;
+        }
+        if (elapsed !== undefined && elapsed !== timeout) {
+            message += ` (elapsed: ${Math.round(elapsed)}ms)`;
+        }
+        const suggestions = [
+            'Verify network connectivity and DNS resolution for the target host.',
+            'Increase the specific timeout phase or optimize the upstream response time.',
+            'Reduce concurrent requests if the connection pool is exhausted.'
+        ];
+        super(message, request, undefined, suggestions, true);
         this.name = 'TimeoutError';
+        this.phase = phase;
+        this.timeout = timeout ?? 0;
+        this.elapsed = elapsed;
+        this.event = `timeout:${phase}`;
     }
 }
 export class NetworkError extends ReckerError {
     code;
     constructor(message, code, request) {
-        super(message, request);
+        const suggestions = [
+            'Confirm the host and port are reachable from this environment.',
+            'Check proxy/VPN/firewall settings that might block the request.',
+            'Retry the request or switch transport if this is transient.'
+        ];
+        super(message, request, undefined, suggestions, true);
         this.name = 'NetworkError';
         this.code = code;
     }
 }
+export class MaxSizeExceededError extends ReckerError {
+    maxSize;
+    actualSize;
+    constructor(maxSize, actualSize, request) {
+        const sizeInfo = actualSize
+            ? `${actualSize} bytes (max: ${maxSize} bytes)`
+            : `${maxSize} bytes`;
+        super(`Response size exceeded maximum allowed: ${sizeInfo}`, request, undefined, [
+            'Increase maxResponseSize if the larger payload is expected.',
+            'Add pagination/streaming to reduce payload size.',
+            'Ensure the upstream is not returning unexpected large responses.'
+        ], false);
+        this.name = 'MaxSizeExceededError';
+        this.maxSize = maxSize;
+        this.actualSize = actualSize;
+    }
+}
+function isRetryableStatus(status) {
+    return [408, 425, 429, 500, 502, 503, 504].includes(status);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from './client.js';
+export * from './errors.js';
+export * from './request-promise.js';
+export * from './request.js';
+export * from './response.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export * from './client.js';
+export * from './errors.js';
+export * from './request-promise.js';
+export * from './request.js';
+export * from './response.js';

package/dist/core/request-promise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-promise.d.ts","sourceRoot":"","sources":["../../src/core/request-promise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAMhC,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAE9B,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,EAAE,eAAe;IAKlF,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAEvB;IAED,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,EACjD,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EACrF,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GACtE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAI/B,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GACpE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAIvC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAKpE,MAAM,IAAI,IAAI;IAMR,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC;IAKzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAK5B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IAKlD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAalC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK1C,IAAI,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;IAKtD,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC;IAK/B,QAAQ,IAAI,cAAc,CAAC,aAAa,CAAC;IAKzC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;CAI5D"}
+{"version":3,"file":"request-promise.d.ts","sourceRoot":"","sources":["../../src/core/request-promise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAOhC,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAE9B,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,EAAE,eAAe;IAKlF,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAEvB;IAED,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,EACjD,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EACrF,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,GACtE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAI/B,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GACpE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAIvC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAKpE,MAAM,IAAI,IAAI;IAMR,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC;IAKzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAK5B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IAKlD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK1C,IAAI,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;IAKtD,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC;IAK/B,QAAQ,IAAI,cAAc,CAAC,aAAa,CAAC;IAKzC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC;CAI5D"}

package/dist/core/request-promise.js

@@ -2,6 +2,7 @@ import { createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { tryFn } from '../utils/try-fn.js';
+import { ReckerError } from './errors.js';
 export class RequestPromise {
     promise;
     abortController;
@@ -49,8 +50,13 @@ export class RequestPromise {
     async write(path) {
         const response = await this.promise;
         const body = response.read();
-        if (!body)
-            throw new Error('Response has no body');
+        if (!body) {
+            throw new ReckerError('Response has no body to write', undefined, response, [
+                'Ensure the request returned a body (avoid HEAD/204).',
+                'Check if the request was aborted before the body streamed.',
+                'Verify upstream is not sending an empty response.'
+            ]);
+        }
         const nodeStream = Readable.fromWeb(body);
         const fileStream = createWriteStream(path);
         await pipeline(nodeStream, fileStream);