promidas 2.0.0

package/dist/fetcher/utils/create-client-fetch.js

@@ -0,0 +1,89 @@
+/**
+ * Client fetch function factory.
+ *
+ * This module provides a factory function that creates a customized fetch function
+ * by composing multiple fetch wrappers based on configuration:
+ * - Timeout wrapper (if timeoutMs is specified)
+ * - Header stripping wrapper (for browser compatibility)
+ * - Progress tracking wrapper (if progress features are enabled)
+ *
+ * @module
+ */
+import { createFetchWithTimeout } from '../client/fetch-with-timeout.js';
+import { selectCustomFetch } from '../client/select-custom-fetch.js';
+import { createFetchWithStrippedHeaders } from './create-fetch-with-stripped-headers.js';
+/**
+ * Create a customized fetch function with optional features.
+ *
+ * This function composes multiple fetch wrappers in the following order:
+ * 1. Timeout wrapper (if timeoutMs is specified)
+ * 2. Header stripping wrapper (if stripHeaders is specified)
+ * 3. Progress tracking wrapper (if enableProgressLog or progressCallback is specified)
+ *
+ * @param params - Configuration parameters for fetch customization
+ * @returns Customized fetch function, or undefined to use default fetch
+ *
+ * @example Basic usage with timeout
+ * ```typescript
+ * const customFetch = createClientFetch({
+ *   logger: myLogger,
+ *   enableProgressLog: false,
+ *   progressCallback: undefined,
+ *   timeoutMs: 30000,
+ *   providedFetch: undefined,
+ * });
+ * ```
+ *
+ * @example With progress tracking
+ * ```typescript
+ * const customFetch = createClientFetch({
+ *   logger: myLogger,
+ *   enableProgressLog: true,
+ *   progressCallback: (event) => {
+ *     if (event.type === 'download-progress') {
+ *       console.log(`Progress: ${event.percentage}%`);
+ *     }
+ *   },
+ *   timeoutMs: undefined,
+ *   providedFetch: undefined,
+ * });
+ * ```
+ */
+export function createClientFetch(params) {
+    const { logger, enableProgressLog, progressCallback, timeoutMs, providedFetch, stripHeaders, } = params;
+    const timeoutWrappedFetch = typeof timeoutMs === 'number'
+        ? createFetchWithTimeout({
+            timeoutMs,
+            baseFetch: providedFetch,
+        })
+        : providedFetch;
+    const shouldStripHeaders = Array.isArray(stripHeaders) && stripHeaders.length > 0;
+    const baseFetchForStripping = shouldStripHeaders
+        ? (timeoutWrappedFetch ??
+            (typeof globalThis.fetch === 'function'
+                ? globalThis.fetch
+                : undefined))
+        : undefined;
+    const strippedFetch = shouldStripHeaders
+        ? baseFetchForStripping !== undefined
+            ? createFetchWithStrippedHeaders({
+                baseFetch: baseFetchForStripping,
+                headerNames: stripHeaders,
+            })
+            : undefined
+        : timeoutWrappedFetch;
+    // If user provides a custom fetch, wrap it with progress tracking.
+    // Otherwise, progress tracking wraps the global fetch.
+    const selected = selectCustomFetch({
+        logger,
+        enableProgressLog,
+        ...(strippedFetch !== undefined && {
+            baseFetch: strippedFetch,
+        }),
+        ...(progressCallback !== undefined && {
+            onProgressEvent: progressCallback,
+        }),
+    });
+    return selected;
+}
+//# sourceMappingURL=create-client-fetch.js.map

package/dist/fetcher/utils/create-client-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client-fetch.js","sourceRoot":"","sources":["../../../lib/fetcher/utils/create-client-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAGrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAczF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA+B;IAE/B,MAAM,EACJ,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,YAAY,GACb,GAAG,MAAM,CAAC;IAEX,MAAM,mBAAmB,GACvB,OAAO,SAAS,KAAK,QAAQ;QAC3B,CAAC,CAAC,sBAAsB,CAAC;YACrB,SAAS;YACT,SAAS,EAAE,aAAa;SACzB,CAAC;QACJ,CAAC,CAAC,aAAa,CAAC;IAEpB,MAAM,kBAAkB,GACtB,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAEzD,MAAM,qBAAqB,GAA6B,kBAAkB;QACxE,CAAC,CAAC,CAAC,mBAAmB;YACpB,CAAC,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU;gBACrC,CAAC,CAAE,UAAU,CAAC,KAAsB;gBACpC,CAAC,CAAC,SAAS,CAAC,CAAC;QACjB,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,aAAa,GAA6B,kBAAkB;QAChE,CAAC,CAAC,qBAAqB,KAAK,SAAS;YACnC,CAAC,CAAC,8BAA8B,CAAC;gBAC7B,SAAS,EAAE,qBAAqB;gBAChC,WAAW,EAAE,YAAY;aAC1B,CAAC;YACJ,CAAC,CAAC,SAAS;QACb,CAAC,CAAC,mBAAmB,CAAC;IAExB,mEAAmE;IACnE,uDAAuD;IACvD,MAAM,QAAQ,GAAG,iBAAiB,CAAC;QACjC,MAAM;QACN,iBAAiB;QACjB,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI;YACjC,SAAS,EAAE,aAAa;SACzB,CAAC;QACF,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI;YACpC,eAAe,EAAE,gBAAgB;SAClC,CAAC;KACH,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/fetcher/utils/create-fetch-with-stripped-headers.d.ts

@@ -0,0 +1,6 @@
+export type CreateFetchWithStrippedHeadersParams = {
+    baseFetch: typeof fetch;
+    headerNames: string[];
+};
+export declare function createFetchWithStrippedHeaders(params: CreateFetchWithStrippedHeadersParams): typeof fetch;
+//# sourceMappingURL=create-fetch-with-stripped-headers.d.ts.map

package/dist/fetcher/utils/create-fetch-with-stripped-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-fetch-with-stripped-headers.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/utils/create-fetch-with-stripped-headers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oCAAoC,GAAG;IACjD,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AASF,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,oCAAoC,GAC3C,OAAO,KAAK,CAuCd"}

package/dist/fetcher/utils/create-fetch-with-stripped-headers.js

@@ -0,0 +1,40 @@
+function toLowerCaseHeaderNames(headerNames) {
+    return headerNames
+        .map((value) => value.trim())
+        .filter((value) => value !== '')
+        .map((value) => value.toLowerCase());
+}
+export function createFetchWithStrippedHeaders(params) {
+    const { baseFetch } = params;
+    const headerNames = toLowerCaseHeaderNames(params.headerNames);
+    return async (input, init) => {
+        if (headerNames.length === 0) {
+            return baseFetch(input, init);
+        }
+        if (typeof Request !== 'undefined' && input instanceof Request) {
+            const headers = new Headers(input.headers);
+            if (init?.headers !== undefined) {
+                const initHeaders = new Headers(init.headers);
+                initHeaders.forEach((value, key) => {
+                    headers.set(key, value);
+                });
+            }
+            for (const headerName of headerNames) {
+                headers.delete(headerName);
+            }
+            const strippedRequest = new Request(input, { headers });
+            return init !== undefined
+                ? baseFetch(strippedRequest, { ...init, headers })
+                : baseFetch(strippedRequest);
+        }
+        if (init?.headers !== undefined) {
+            const headers = new Headers(init.headers);
+            for (const headerName of headerNames) {
+                headers.delete(headerName);
+            }
+            return baseFetch(input, { ...init, headers });
+        }
+        return baseFetch(input, init);
+    };
+}
+//# sourceMappingURL=create-fetch-with-stripped-headers.js.map

package/dist/fetcher/utils/create-fetch-with-stripped-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-fetch-with-stripped-headers.js","sourceRoot":"","sources":["../../../lib/fetcher/utils/create-fetch-with-stripped-headers.ts"],"names":[],"mappings":"AAKA,SAAS,sBAAsB,CAAC,WAAqB;IACnD,OAAO,WAAW;SACf,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC;SAC/B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,MAA4C;IAE5C,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAC7B,MAAM,WAAW,GAAG,sBAAsB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAE/D,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,KAAK,YAAY,OAAO,EAAE,CAAC;YAC/D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAE3C,IAAI,IAAI,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;gBAChC,MAAM,WAAW,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC9C,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;oBACjC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC1B,CAAC,CAAC,CAAC;YACL,CAAC;YAED,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACrC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC7B,CAAC;YAED,MAAM,eAAe,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACxD,OAAO,IAAI,KAAK,SAAS;gBACvB,CAAC,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC;gBAClD,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QACjC,CAAC;QAED,IAAI,IAAI,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1C,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACrC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO,SAAS,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/fetcher/utils/errors/handler.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module protopedia/utils/errors/handler
+ *
+ * Error handling utilities for ProtoPedia API calls.
+ *
+ * This module provides the central error handler that transforms various
+ * error scenarios into a consistent {@link FetchPrototypesResult} failure
+ * shape. HTTP normalization is limited to ProtoPedia API errors; all other
+ * errors are classified as network/timeout/abort/unknown.
+ *
+ * Key responsibilities:
+ * - Mapping `PromidasTimeoutError` (timeout) to a TIMEOUT failure.
+ * - Detecting `AbortError` (caller-driven abort) and mapping it to an ABORTED failure.
+ * - Normalizing {@link ProtoPediaApiError} into HTTP failures with status/statusText.
+ * - Preserving network error codes (ENOTFOUND, ECONNREFUSED, etc.) when available.
+ * - Classifying opaque fetch failures (TypeError with well-known messages) as CORS_BLOCKED.
+ * - Ensuring all API errors are normalized into {@link FetchPrototypesResult}
+ *   without throwing exceptions.
+ */
+import { ProtoPediaApiError } from 'protopedia-api-v2-client';
+import type { FetchPrototypesResult } from '../../types/result.types.js';
+/**
+ * Normalize a {@link ProtoPediaApiError} into a fetcher HTTP failure result.
+ *
+ * @param error - ProtoPedia API client error containing status and metadata
+ * @returns Failure result with kind 'http' and mapped FetcherErrorCode
+ */
+export declare function handleProtoPediaApiError(error: ProtoPediaApiError): FetchPrototypesResult;
+/**
+ * Normalize non-ProtoPedia errors into fetcher failure results.
+ *
+ * Paths:
+ * - PromidasTimeoutError → timeout/TIMEOUT (no HTTP status)
+ * - AbortError → abort/ABORTED (caller-driven abort, no HTTP status)
+ * - Network-ish errors with code → network/<code>
+ * - Opaque fetch (known TypeError messages) → cors/CORS_BLOCKED
+ * - Fallback → unknown/UNKNOWN
+ *
+ * Notes:
+ * - Do not trust arbitrary error.status; do not treat non-ProtoPedia errors as HTTP.
+ * - If details.res.code exists, classify as network; otherwise choose cors/unknown.
+ */
+export declare function handleNotProtoPediaApiError(error: unknown): FetchPrototypesResult;
+/**
+ * Normalize any error thrown during ProtoPedia API calls into a
+ * {@link FetchPrototypesResult} failure object.
+ *
+ * Delegation:
+ * - ProtoPediaApiError → {@link handleProtoPediaApiError} (HTTP, preserves status/statusText)
+ * - Others → {@link handleNotProtoPediaApiError} (timeout/abort/network/cors/unknown)
+ *
+ * Notes:
+ * - Only ProtoPediaApiError is treated as trusted HTTP (status/statusText retained).
+ * - If a network code is available, store it in details.res.code and return kind 'network'.
+ * - Known opaque fetch messages (TypeError) are classified as CORS_BLOCKED.
+ */
+export declare function handleApiError(error: unknown): FetchPrototypesResult;
+//# sourceMappingURL=handler.d.ts.map

package/dist/fetcher/utils/errors/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../lib/fetcher/utils/errors/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAI9D,OAAO,KAAK,EAGV,qBAAqB,EAEtB,MAAM,6BAA6B,CAAC;AAyIrC;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,GACxB,qBAAqB,CAgBvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,qBAAqB,CAiEvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAQpE"}

package/dist/fetcher/utils/errors/handler.js

@@ -0,0 +1,243 @@
+/**
+ * @module protopedia/utils/errors/handler
+ *
+ * Error handling utilities for ProtoPedia API calls.
+ *
+ * This module provides the central error handler that transforms various
+ * error scenarios into a consistent {@link FetchPrototypesResult} failure
+ * shape. HTTP normalization is limited to ProtoPedia API errors; all other
+ * errors are classified as network/timeout/abort/unknown.
+ *
+ * Key responsibilities:
+ * - Mapping `PromidasTimeoutError` (timeout) to a TIMEOUT failure.
+ * - Detecting `AbortError` (caller-driven abort) and mapping it to an ABORTED failure.
+ * - Normalizing {@link ProtoPediaApiError} into HTTP failures with status/statusText.
+ * - Preserving network error codes (ENOTFOUND, ECONNREFUSED, etc.) when available.
+ * - Classifying opaque fetch failures (TypeError with well-known messages) as CORS_BLOCKED.
+ * - Ensuring all API errors are normalized into {@link FetchPrototypesResult}
+ *   without throwing exceptions.
+ */
+import { ProtoPediaApiError } from 'protopedia-api-v2-client';
+import { PromidasTimeoutError } from '../../errors/fetcher-error.js';
+/**
+ * Standard error names used in error detection.
+ */
+const ERROR_NAMES = {
+    ABORT: 'AbortError',
+};
+/**
+ * Standard error messages for common failure scenarios.
+ */
+const ERROR_MESSAGES = {
+    ABORTED: 'Upstream request aborted',
+    TIMEOUT: 'Upstream request timed out',
+    UNKNOWN: 'Failed to fetch prototypes',
+};
+/**
+ * Default error code for network failures where the runtime does not provide
+ * a more specific code (e.g. browser fetch TypeError("Failed to fetch")).
+ */
+const DEFAULT_NETWORK_ERROR_CODE = 'NETWORK_ERROR';
+/**
+ * A small set of well-known fetch network error messages.
+ *
+ * Browsers commonly surface CORS/network failures as a generic TypeError with
+ * a short message (e.g. "Failed to fetch"), without any structured error code.
+ */
+const KNOWN_FETCH_NETWORK_ERROR_MESSAGES = new Set([
+    'Failed to fetch',
+    'fetch failed',
+    'Load failed',
+    'NetworkError when attempting to fetch resource.',
+]);
+const STATUS_CODE_MAP = {
+    400: 'CLIENT_BAD_REQUEST',
+    401: 'CLIENT_UNAUTHORIZED',
+    403: 'CLIENT_FORBIDDEN',
+    404: 'CLIENT_NOT_FOUND',
+    405: 'CLIENT_METHOD_NOT_ALLOWED',
+    408: 'CLIENT_TIMEOUT',
+    429: 'CLIENT_RATE_LIMITED',
+    500: 'SERVER_INTERNAL_ERROR',
+    502: 'SERVER_BAD_GATEWAY',
+    503: 'SERVER_SERVICE_UNAVAILABLE',
+    504: 'SERVER_GATEWAY_TIMEOUT',
+};
+/**
+ * Type guard to check if an error is an AbortError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a DOMException with name 'AbortError'
+ */
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === ERROR_NAMES.ABORT;
+}
+/**
+ * Type guard to check if an error has a code property.
+ *
+ * This intentionally uses a broad `error is object` type guard to handle
+ * nested error structures flexibly. Node.js native fetch wraps network
+ * error codes in `error.cause.code`:
+ *
+ * @example
+ * ```ts
+ * const error = new Error('fetch failed');
+ * error.cause = { code: 'ENOTFOUND' };
+ * // hasErrorCode(error) returns true, allowing us to check error.cause.code
+ * ```
+ *
+ * A more specific type guard like `error is { code: string }` would reject
+ * errors that only have `cause.code`, preventing extraction of nested codes.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an object that might contain code information
+ */
+function hasErrorCode(error) {
+    return error !== null && typeof error === 'object';
+}
+/**
+ * Create the common portion of a FetchPrototypesFailure.
+ *
+ * @param error - Error message string
+ * @param details - Additional error details (always required, use {} if no metadata)
+ * @param status - HTTP status code (undefined for network errors without server response)
+ * @returns A partial FetchPrototypesFailure without kind/code
+ */
+function createFailureResult(error, details, status) {
+    const result = {
+        ok: false,
+        origin: 'fetcher',
+        error,
+        details,
+    };
+    if (status !== undefined) {
+        result.status = status;
+    }
+    return result;
+}
+function mapHttpStatusToCode(status) {
+    if (status === undefined)
+        return 'UNKNOWN';
+    const mapped = STATUS_CODE_MAP[status];
+    if (mapped !== undefined) {
+        return mapped;
+    }
+    if (status >= 500 && status < 600)
+        return 'SERVER_ERROR';
+    if (status >= 400 && status < 500)
+        return 'CLIENT_ERROR';
+    return 'UNKNOWN';
+}
+function finalize(base, kind, code) {
+    return {
+        ...base,
+        kind,
+        code,
+    };
+}
+/**
+ * Normalize a {@link ProtoPediaApiError} into a fetcher HTTP failure result.
+ *
+ * @param error - ProtoPedia API client error containing status and metadata
+ * @returns Failure result with kind 'http' and mapped FetcherErrorCode
+ */
+export function handleProtoPediaApiError(error) {
+    const result = createFailureResult(error.message, {
+        req: {
+            url: error.req.url,
+            method: error.req.method,
+        },
+        res: {
+            statusText: error.statusText,
+        },
+    }, error.status);
+    return finalize(result, 'http', mapHttpStatusToCode(error.status));
+}
+/**
+ * Normalize non-ProtoPedia errors into fetcher failure results.
+ *
+ * Paths:
+ * - PromidasTimeoutError → timeout/TIMEOUT (no HTTP status)
+ * - AbortError → abort/ABORTED (caller-driven abort, no HTTP status)
+ * - Network-ish errors with code → network/<code>
+ * - Opaque fetch (known TypeError messages) → cors/CORS_BLOCKED
+ * - Fallback → unknown/UNKNOWN
+ *
+ * Notes:
+ * - Do not trust arbitrary error.status; do not treat non-ProtoPedia errors as HTTP.
+ * - If details.res.code exists, classify as network; otherwise choose cors/unknown.
+ */
+export function handleNotProtoPediaApiError(error) {
+    /**
+     * Handle explicit timeout errors (distinguishable from AbortError).
+     * These are fetcher-level timeouts, not HTTP 408 responses.
+     */
+    // Handle explicit timeout errors (distinguishable from AbortError)
+    if (error instanceof PromidasTimeoutError) {
+        const result = createFailureResult(ERROR_MESSAGES.TIMEOUT, {
+            res: {
+                code: 'TIMEOUT',
+            },
+        });
+        return finalize(result, 'timeout', 'TIMEOUT');
+    }
+    // Handle AbortError (caller-driven abort) - network error, no status
+    if (isAbortError(error)) {
+        const result = createFailureResult(ERROR_MESSAGES.ABORTED, {
+            res: {
+                code: 'ABORTED',
+            },
+        });
+        return finalize(result, 'abort', 'ABORTED');
+    }
+    const message = error instanceof Error ? error.message : ERROR_MESSAGES.UNKNOWN;
+    const details = {};
+    // Extract network error code from error.code or error.cause.code
+    // (Node.js native fetch wraps ENOTFOUND etc. in error.cause)
+    if (hasErrorCode(error)) {
+        const errorObj = error;
+        const code = errorObj.code ?? errorObj.cause?.code;
+        if (code !== undefined) {
+            details.res ??= {};
+            details.res.code = code;
+        }
+    }
+    const isOpaqueFetchError = error instanceof TypeError &&
+        KNOWN_FETCH_NETWORK_ERROR_MESSAGES.has(message);
+    if (details.res?.code === undefined && isOpaqueFetchError) {
+        // Keep diagnostics (use generic network code) but classify as CORS_BLOCKED.
+        details.res ??= {};
+        details.res.code = DEFAULT_NETWORK_ERROR_CODE;
+        const result = createFailureResult(message, details);
+        return finalize(result, 'cors', 'CORS_BLOCKED');
+    }
+    if (details.res?.code !== undefined) {
+        const result = createFailureResult(message, details);
+        const code = details.res.code;
+        return finalize(result, 'network', code);
+    }
+    const result = createFailureResult(message, details);
+    return finalize(result, 'unknown', 'UNKNOWN');
+}
+/**
+ * Normalize any error thrown during ProtoPedia API calls into a
+ * {@link FetchPrototypesResult} failure object.
+ *
+ * Delegation:
+ * - ProtoPediaApiError → {@link handleProtoPediaApiError} (HTTP, preserves status/statusText)
+ * - Others → {@link handleNotProtoPediaApiError} (timeout/abort/network/cors/unknown)
+ *
+ * Notes:
+ * - Only ProtoPediaApiError is treated as trusted HTTP (status/statusText retained).
+ * - If a network code is available, store it in details.res.code and return kind 'network'.
+ * - Known opaque fetch messages (TypeError) are classified as CORS_BLOCKED.
+ */
+export function handleApiError(error) {
+    // Handle ProtoPediaApiError specifically - HTTP error with status
+    if (error instanceof ProtoPediaApiError) {
+        return handleProtoPediaApiError(error);
+    }
+    // Handle all non-ProtoPediaApiError cases (network/abort/timeout/unknown)
+    return handleNotProtoPediaApiError(error);
+}
+//# sourceMappingURL=handler.js.map

package/dist/fetcher/utils/errors/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../../lib/fetcher/utils/errors/handler.ts"],"names":[],"mappings":"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"}

package/dist/fetcher/utils/errors/messages.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module protopedia/utils/errors/messages
+ *
+ * Message formatting utilities for ProtoPedia API errors.
+ *
+ * This module provides helpers to extract and format error messages
+ * from various error types into user-friendly display strings.
+ */
+import type { NetworkFailure } from '../../types/prototype-api.types.js';
+/**
+ * Resolve an unknown error value into a readable string message.
+ *
+ * This helper provides a safe way to extract error messages from various
+ * error types that may be thrown by network calls or API clients.
+ *
+ * @param value - The error value to resolve. Can be an `Error`, a string,
+ *   or any other value.
+ * @returns A string message. If `value` is an `Error`, returns its
+ *   `message` property. If `value` is a non-empty string, returns it as-is.
+ *   Otherwise, returns a generic fallback message.
+ *
+ * @example
+ * ```ts
+ * resolveErrorMessage(new Error('Network timeout'));
+ * // => 'Network timeout'
+ *
+ * resolveErrorMessage('Custom error');
+ * // => 'Custom error'
+ *
+ * resolveErrorMessage(null);
+ * // => 'Unknown error occurred.'
+ * ```
+ */
+export declare const resolveErrorMessage: (value: unknown) => string;
+/**
+ * Construct a user-friendly display message from a network failure object.
+ *
+ * This function builds a comprehensive error message by combining:
+ * 1. A prefix from `details.statusText` (e.g., "Not Found") or
+ *    `details.code` (e.g., "ENOTFOUND").
+ * 2. The resolved error message from {@link resolveErrorMessage}.
+ * 3. The HTTP status code appended in parentheses (e.g., "(404)") if
+ *    status is defined. For network errors without a status, the code
+ *    is omitted.
+ *
+ * The result is suitable for displaying to users or logging.
+ *
+ * @param failure - The {@link NetworkFailure} object containing status,
+ *   error, and optional details.
+ * @returns A formatted error message string.
+ *
+ * @example
+ * ```ts
+ * // HTTP error with status
+ * const httpFailure: NetworkFailure = {
+ *   status: 404,
+ *   error: new Error('Resource not found'),
+ *   details: { res: { statusText: 'Not Found' } },
+ * };
+ *
+ * constructDisplayMessage(httpFailure);
+ * // => 'Not Found: Resource not found (404)'
+ *
+ * // Network error without status
+ * const networkFailure: NetworkFailure = {
+ *   error: new Error('Connection refused'),
+ *   details: { res: { code: 'ECONNREFUSED' } },
+ * };
+ *
+ * constructDisplayMessage(networkFailure);
+ * // => 'ECONNREFUSED: Connection refused'
+ * ```
+ */
+export declare const constructDisplayMessage: (failure: NetworkFailure) => string;
+//# sourceMappingURL=messages.d.ts.map

package/dist/fetcher/utils/errors/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../../lib/fetcher/utils/errors/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,MAUpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,cAAc,KAAG,MAiBjE,CAAC"}

package/dist/fetcher/utils/errors/messages.js

@@ -0,0 +1,88 @@
+/**
+ * Resolve an unknown error value into a readable string message.
+ *
+ * This helper provides a safe way to extract error messages from various
+ * error types that may be thrown by network calls or API clients.
+ *
+ * @param value - The error value to resolve. Can be an `Error`, a string,
+ *   or any other value.
+ * @returns A string message. If `value` is an `Error`, returns its
+ *   `message` property. If `value` is a non-empty string, returns it as-is.
+ *   Otherwise, returns a generic fallback message.
+ *
+ * @example
+ * ```ts
+ * resolveErrorMessage(new Error('Network timeout'));
+ * // => 'Network timeout'
+ *
+ * resolveErrorMessage('Custom error');
+ * // => 'Custom error'
+ *
+ * resolveErrorMessage(null);
+ * // => 'Unknown error occurred.'
+ * ```
+ */
+export const resolveErrorMessage = (value) => {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    return 'Unknown error occurred.';
+};
+/**
+ * Construct a user-friendly display message from a network failure object.
+ *
+ * This function builds a comprehensive error message by combining:
+ * 1. A prefix from `details.statusText` (e.g., "Not Found") or
+ *    `details.code` (e.g., "ENOTFOUND").
+ * 2. The resolved error message from {@link resolveErrorMessage}.
+ * 3. The HTTP status code appended in parentheses (e.g., "(404)") if
+ *    status is defined. For network errors without a status, the code
+ *    is omitted.
+ *
+ * The result is suitable for displaying to users or logging.
+ *
+ * @param failure - The {@link NetworkFailure} object containing status,
+ *   error, and optional details.
+ * @returns A formatted error message string.
+ *
+ * @example
+ * ```ts
+ * // HTTP error with status
+ * const httpFailure: NetworkFailure = {
+ *   status: 404,
+ *   error: new Error('Resource not found'),
+ *   details: { res: { statusText: 'Not Found' } },
+ * };
+ *
+ * constructDisplayMessage(httpFailure);
+ * // => 'Not Found: Resource not found (404)'
+ *
+ * // Network error without status
+ * const networkFailure: NetworkFailure = {
+ *   error: new Error('Connection refused'),
+ *   details: { res: { code: 'ECONNREFUSED' } },
+ * };
+ *
+ * constructDisplayMessage(networkFailure);
+ * // => 'ECONNREFUSED: Connection refused'
+ * ```
+ */
+export const constructDisplayMessage = (failure) => {
+    const { error, status, details } = failure;
+    const statusText = details?.res?.statusText;
+    const code = details?.res?.code;
+    let message = resolveErrorMessage(error);
+    const prefix = statusText || code;
+    if (prefix) {
+        // Prepend prefix if not already present
+        if (!message.startsWith(prefix)) {
+            message = `${prefix}: ${message}`;
+        }
+    }
+    // Only append status code if it's defined (HTTP errors have status, network errors don't)
+    return status !== undefined ? `${message} (${status})` : message;
+};
+//# sourceMappingURL=messages.js.map

package/dist/fetcher/utils/errors/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../../lib/fetcher/utils/errors/messages.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAAU,EAAE;IAC5D,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,yBAAyB,CAAC;AACnC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAuB,EAAU,EAAE;IACzE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;IAChC,IAAI,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,UAAU,IAAI,IAAI,CAAC;IAElC,IAAI,MAAM,EAAE,CAAC;QACX,wCAAwC;QACxC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,OAAO,GAAG,GAAG,MAAM,KAAK,OAAO,EAAE,CAAC;QACpC,CAAC;IACH,CAAC;IAED,0FAA0F;IAC1F,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACnE,CAAC,CAAC"}

package/dist/fetcher/utils/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module protopedia/utils
+ *
+ * Utility functions for ProtoPedia API data processing.
+ */
+export { splitPipeSeparatedString } from './string-parsers.js';
+export { normalizePrototype } from './normalize-prototype.js';
+export type { UpstreamPrototype } from '../types/prototype-api.types.js';
+export { normalizeProtoPediaTimestamp } from './normalize-protopedia-timestamp.js';
+export { handleApiError } from './errors/handler.js';
+export { PromidasTimeoutError } from '../errors/fetcher-error.js';
+export { resolveErrorMessage, constructDisplayMessage, } from './errors/messages.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/fetcher/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,OAAO,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC"}