recker 1.0.26 → 1.0.27

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

@@ -0,0 +1,142 @@
+import { ReckerRequest, ReckerResponse } from '../types/index.js';
+export declare class ReckerError extends Error {
+    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' | 'webrtc-connect';
+export declare class TimeoutError extends ReckerError {
+    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);
+}
+export declare class AbortError extends ReckerError {
+    reason?: string;
+    constructor(reason?: string, request?: ReckerRequest);
+}
+export declare class ConnectionError extends ReckerError {
+    host?: string;
+    port?: number;
+    code?: string;
+    constructor(message: string, options?: {
+        host?: string;
+        port?: number;
+        code?: string;
+        retriable?: boolean;
+        request?: ReckerRequest;
+    });
+}
+export declare class AuthenticationError extends ReckerError {
+    authType?: string;
+    constructor(message: string, options?: {
+        authType?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class ProtocolError extends ReckerError {
+    protocol: string;
+    code?: string | number;
+    phase?: string;
+    constructor(message: string, options: {
+        protocol: string;
+        code?: string | number;
+        phase?: string;
+        retriable?: boolean;
+        request?: ReckerRequest;
+    });
+}
+export declare class NotFoundError extends ReckerError {
+    resource?: string;
+    constructor(message: string, options?: {
+        resource?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class StateError extends ReckerError {
+    expectedState?: string;
+    actualState?: string;
+    constructor(message: string, options?: {
+        expectedState?: string;
+        actualState?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class ValidationError extends ReckerError {
+    field?: string;
+    value?: unknown;
+    constructor(message: string, options?: {
+        field?: string;
+        value?: unknown;
+        request?: ReckerRequest;
+    });
+}
+export declare class ConfigurationError extends ReckerError {
+    configKey?: string;
+    constructor(message: string, options?: {
+        configKey?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class UnsupportedError extends ReckerError {
+    feature?: string;
+    constructor(message: string, options?: {
+        feature?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class ParseError extends ReckerError {
+    format?: string;
+    position?: number;
+    constructor(message: string, options?: {
+        format?: string;
+        position?: number;
+        request?: ReckerRequest;
+    });
+}
+export declare class QueueCancelledError extends ReckerError {
+    queueName?: string;
+    constructor(message?: string, options?: {
+        queueName?: string;
+        request?: ReckerRequest;
+    });
+}
+export declare class StreamError extends ReckerError {
+    streamType?: string;
+    constructor(message: string, options?: {
+        streamType?: string;
+        retriable?: boolean;
+        request?: ReckerRequest;
+    });
+}
+export declare class DownloadError extends ReckerError {
+    url?: string;
+    statusCode?: number;
+    constructor(message: string, options?: {
+        url?: string;
+        statusCode?: number;
+        retriable?: boolean;
+        request?: ReckerRequest;
+    });
+}

package/dist/browser/core/errors.js

@@ -0,0 +1,308 @@
+export class ReckerError extends Error {
+    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, ['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 {
+    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)',
+            'webrtc-connect': 'WebRTC peer connection timed out'
+        };
+        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) {
+        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);
+}
+export class AbortError extends ReckerError {
+    reason;
+    constructor(reason, request) {
+        super(reason || 'Request was aborted', request, undefined, [
+            'Check if the abort was intentional (user-triggered or timeout).',
+            'Increase timeout if the request needs more time to complete.',
+            'Ensure AbortController is not being triggered prematurely.'
+        ], true);
+        this.name = 'AbortError';
+        this.reason = reason;
+    }
+}
+export class ConnectionError extends ReckerError {
+    host;
+    port;
+    code;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Verify the host and port are correct and the service is running.',
+            'Check network connectivity and firewall rules.',
+            'Ensure the service is accepting connections on the specified port.'
+        ], options?.retriable ?? true);
+        this.name = 'ConnectionError';
+        this.host = options?.host;
+        this.port = options?.port;
+        this.code = options?.code;
+    }
+}
+export class AuthenticationError extends ReckerError {
+    authType;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Verify credentials (username/password, API key, or certificate).',
+            'Check if the account is active and has proper permissions.',
+            'Ensure the authentication method matches what the server expects.'
+        ], false);
+        this.name = 'AuthenticationError';
+        this.authType = options?.authType;
+    }
+}
+export class ProtocolError extends ReckerError {
+    protocol;
+    code;
+    phase;
+    constructor(message, options) {
+        const protocolSuggestions = {
+            ftp: [
+                'Ensure the FTP server is running and accessible.',
+                'Check file/directory permissions on the server.',
+                'Verify the path exists and is correct.'
+            ],
+            sftp: [
+                'Verify SSH credentials and key permissions.',
+                'Check that the SFTP subsystem is enabled on the server.',
+                'Ensure the target path exists and is accessible.'
+            ],
+            telnet: [
+                'Verify the Telnet service is running on the target host.',
+                'Check login credentials and terminal settings.',
+                'Ensure the expected prompts match the server output.'
+            ],
+            udp: [
+                'UDP is connectionless - verify the target is listening.',
+                'Check firewall rules for UDP traffic.',
+                'Ensure the message format matches what the server expects.'
+            ],
+            webrtc: [
+                'Verify the signaling server is reachable.',
+                'Check ICE server configuration (STUN/TURN).',
+                'Ensure both peers have compatible codecs and capabilities.'
+            ],
+            dns: [
+                'Verify the DNS server is reachable.',
+                'Check if the domain exists and has the requested record type.',
+                'Try an alternative DNS resolver.'
+            ],
+            tls: [
+                'Verify the certificate is valid and not expired.',
+                'Check that the hostname matches the certificate.',
+                'Ensure TLS version and cipher suites are compatible.'
+            ]
+        };
+        const suggestions = protocolSuggestions[options.protocol.toLowerCase()] || [
+            'Check the protocol-specific documentation.',
+            'Verify the server supports the requested operation.',
+            'Review the error code for specific guidance.'
+        ];
+        super(message, options.request, undefined, suggestions, options.retriable ?? false);
+        this.name = 'ProtocolError';
+        this.protocol = options.protocol;
+        this.code = options.code;
+        this.phase = options.phase;
+    }
+}
+export class NotFoundError extends ReckerError {
+    resource;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Verify the resource path or identifier is correct.',
+            'Check if the resource was deleted or moved.',
+            'Ensure you have permission to access this resource.'
+        ], false);
+        this.name = 'NotFoundError';
+        this.resource = options?.resource;
+    }
+}
+export class StateError extends ReckerError {
+    expectedState;
+    actualState;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Ensure the required setup/initialization step was performed.',
+            'Check that operations are called in the correct order.',
+            'Verify the connection or resource is still valid.'
+        ], false);
+        this.name = 'StateError';
+        this.expectedState = options?.expectedState;
+        this.actualState = options?.actualState;
+    }
+}
+export class ValidationError extends ReckerError {
+    field;
+    value;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Check the input format and constraints.',
+            'Refer to the API documentation for valid values.',
+            'Ensure required fields are provided.'
+        ], false);
+        this.name = 'ValidationError';
+        this.field = options?.field;
+        this.value = options?.value;
+    }
+}
+export class ConfigurationError extends ReckerError {
+    configKey;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Check the configuration file or environment variables.',
+            'Ensure all required configuration keys are set.',
+            'Verify the configuration values are in the correct format.'
+        ], false);
+        this.name = 'ConfigurationError';
+        this.configKey = options?.configKey;
+    }
+}
+export class UnsupportedError extends ReckerError {
+    feature;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Check if this feature is supported in the current context.',
+            'Refer to the documentation for supported operations.',
+            'Consider using an alternative approach.'
+        ], false);
+        this.name = 'UnsupportedError';
+        this.feature = options?.feature;
+    }
+}
+export class ParseError extends ReckerError {
+    format;
+    position;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Verify the input is in the expected format.',
+            'Check for malformed or corrupted data.',
+            'Ensure the encoding is correct (UTF-8, etc.).'
+        ], false);
+        this.name = 'ParseError';
+        this.format = options?.format;
+        this.position = options?.position;
+    }
+}
+export class QueueCancelledError extends ReckerError {
+    queueName;
+    constructor(message, options) {
+        super(message || 'Queue operation was cancelled', options?.request, undefined, [
+            'This is typically expected during shutdown.',
+            'Check if the queue was manually cleared.',
+            'Retry the operation if the queue is still active.'
+        ], true);
+        this.name = 'QueueCancelledError';
+        this.queueName = options?.queueName;
+    }
+}
+export class StreamError extends ReckerError {
+    streamType;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Check if the stream was prematurely closed.',
+            'Verify the data source is still available.',
+            'Ensure proper error handling for stream events.'
+        ], options?.retriable ?? false);
+        this.name = 'StreamError';
+        this.streamType = options?.streamType;
+    }
+}
+export class DownloadError extends ReckerError {
+    url;
+    statusCode;
+    constructor(message, options) {
+        super(message, options?.request, undefined, [
+            'Verify the URL is correct and accessible.',
+            'Check network connectivity.',
+            options?.statusCode
+                ? `HTTP ${options.statusCode} - check server response.`
+                : 'Retry the download if the error is transient.'
+        ], options?.retriable ?? true);
+        this.name = 'DownloadError';
+        this.url = options?.url;
+        this.statusCode = options?.statusCode;
+    }
+}

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

@@ -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/browser/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/browser/core/request-promise.d.ts

@@ -0,0 +1,23 @@
+import { ReckerResponse, SSEEvent, ProgressEvent } from '../types/index.js';
+import type { ZodSchema } from 'zod';
+export declare class RequestPromise<T = unknown> implements Promise<ReckerResponse<T>> {
+    private promise;
+    private abortController?;
+    constructor(promise: Promise<ReckerResponse<T>>, abortController?: AbortController);
+    get [Symbol.toStringTag](): string;
+    then<TResult1 = ReckerResponse<T>, TResult2 = never>(onfulfilled?: ((value: ReckerResponse<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<ReckerResponse<T> | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<ReckerResponse<T>>;
+    cancel(): void;
+    json<R = T>(): Promise<R>;
+    text(): Promise<string>;
+    cleanText(): Promise<string>;
+    blob(): Promise<Blob>;
+    read(): Promise<ReadableStream<Uint8Array> | null>;
+    write(path: string): Promise<void>;
+    parse<R>(schema: ZodSchema<R>): Promise<R>;
+    safe(): Promise<[boolean, Error | null, T | undefined]>;
+    sse(): AsyncGenerator<SSEEvent>;
+    download(): AsyncGenerator<ProgressEvent>;
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array>;
+}

package/dist/browser/core/request-promise.js

@@ -0,0 +1,82 @@
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { tryFn } from '../utils/try-fn.js';
+import { StreamError } from './errors.js';
+export class RequestPromise {
+    promise;
+    abortController;
+    constructor(promise, abortController) {
+        this.promise = promise;
+        this.abortController = abortController;
+    }
+    get [Symbol.toStringTag]() {
+        return 'RequestPromise';
+    }
+    then(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.promise.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.promise.finally(onfinally);
+    }
+    cancel() {
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+    }
+    async json() {
+        const response = await this.promise;
+        return response.json();
+    }
+    async text() {
+        const response = await this.promise;
+        return response.text();
+    }
+    async cleanText() {
+        const response = await this.promise;
+        return response.cleanText();
+    }
+    async blob() {
+        const response = await this.promise;
+        return response.blob();
+    }
+    async read() {
+        const response = await this.promise;
+        return response.read();
+    }
+    async write(path) {
+        const response = await this.promise;
+        const body = response.read();
+        if (!body) {
+            throw new StreamError('Response has no body to write', {
+                streamType: 'response',
+                retriable: true,
+            });
+        }
+        const nodeStream = Readable.fromWeb(body);
+        const fileStream = createWriteStream(path);
+        await pipeline(nodeStream, fileStream);
+    }
+    async parse(schema) {
+        const data = await this.json();
+        return schema.parse(data);
+    }
+    async safe() {
+        return tryFn(() => this.json());
+    }
+    async *sse() {
+        const response = await this.promise;
+        yield* response.sse();
+    }
+    async *download() {
+        const response = await this.promise;
+        yield* response.download();
+    }
+    async *[Symbol.asyncIterator]() {
+        const response = await this.promise;
+        yield* response;
+    }
+}

package/dist/browser/core/request.d.ts

@@ -0,0 +1,20 @@
+import { Method, ReckerRequest, RequestOptions, ProgressCallback, TimeoutOptions, RedirectInfo } from '../types/index.js';
+export declare class HttpRequest implements ReckerRequest {
+    readonly url: string;
+    readonly method: Method;
+    readonly headers: Headers;
+    readonly body: BodyInit | null;
+    readonly signal?: AbortSignal;
+    readonly throwHttpErrors?: boolean;
+    readonly timeout?: TimeoutOptions;
+    readonly onUploadProgress?: ProgressCallback;
+    readonly onDownloadProgress?: ProgressCallback;
+    readonly maxResponseSize?: number;
+    readonly beforeRedirect?: (info: RedirectInfo) => void | false | string | Promise<void | false | string>;
+    readonly maxRedirects?: number;
+    readonly followRedirects?: boolean;
+    readonly http2?: boolean;
+    constructor(url: string, options?: RequestOptions);
+    withHeader(name: string, value: string): ReckerRequest;
+    withBody(body: BodyInit): ReckerRequest;
+}

package/dist/browser/core/request.js

@@ -0,0 +1,76 @@
+function normalizeTimeout(timeout) {
+    if (timeout === undefined)
+        return undefined;
+    if (typeof timeout === 'number') {
+        return { request: timeout };
+    }
+    return timeout;
+}
+export class HttpRequest {
+    url;
+    method;
+    headers;
+    body;
+    signal;
+    throwHttpErrors;
+    timeout;
+    onUploadProgress;
+    onDownloadProgress;
+    maxResponseSize;
+    beforeRedirect;
+    maxRedirects;
+    followRedirects;
+    http2;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.method = options.method || 'GET';
+        this.headers = new Headers(options.headers);
+        this.body = options.body || null;
+        this.signal = options.signal;
+        this.throwHttpErrors = options.throwHttpErrors !== undefined ? options.throwHttpErrors : true;
+        this.timeout = normalizeTimeout(options.timeout);
+        this.onUploadProgress = options.onUploadProgress;
+        this.onDownloadProgress = options.onDownloadProgress;
+        this.maxResponseSize = options.maxResponseSize;
+        this.beforeRedirect = options.beforeRedirect;
+        this.maxRedirects = options.maxRedirects;
+        this.followRedirects = options.followRedirects;
+        this.http2 = options.http2;
+    }
+    withHeader(name, value) {
+        const newHeaders = new Headers(this.headers);
+        newHeaders.set(name, value);
+        return new HttpRequest(this.url, {
+            method: this.method,
+            headers: newHeaders,
+            body: this.body,
+            signal: this.signal,
+            throwHttpErrors: this.throwHttpErrors,
+            timeout: this.timeout,
+            onUploadProgress: this.onUploadProgress,
+            onDownloadProgress: this.onDownloadProgress,
+            maxResponseSize: this.maxResponseSize,
+            beforeRedirect: this.beforeRedirect,
+            maxRedirects: this.maxRedirects,
+            followRedirects: this.followRedirects,
+            http2: this.http2,
+        });
+    }
+    withBody(body) {
+        return new HttpRequest(this.url, {
+            method: this.method,
+            headers: this.headers,
+            body: body,
+            signal: this.signal,
+            throwHttpErrors: this.throwHttpErrors,
+            timeout: this.timeout,
+            onUploadProgress: this.onUploadProgress,
+            onDownloadProgress: this.onDownloadProgress,
+            maxResponseSize: this.maxResponseSize,
+            beforeRedirect: this.beforeRedirect,
+            maxRedirects: this.maxRedirects,
+            followRedirects: this.followRedirects,
+            http2: this.http2,
+        });
+    }
+}