promidas 2.0.0

package/dist/fetcher/index.js

@@ -0,0 +1,70 @@
+/**
+ * ProtoPedia API Client and Data Fetching Utilities.
+ *
+ * This module provides a complete fetcher layer for interacting with the
+ * ProtoPedia API, including client creation, data fetching, normalization,
+ * and error handling. It can be used as a standalone module for custom
+ * data pipelines or integrated with the repository layer.
+ *
+ * ## Core Components
+ *
+ * - {@link ProtopediaApiCustomClient} — Class-based client with managed logger and high-level methods.
+ * - {@link ProtopediaApiCustomClientConfig} — Configuration options including logger and SDK client settings.
+ *
+ * ### Dependencies
+ *
+ * Types from `protopedia-api-v2-client` should be imported directly from the package:
+ * - `ProtoPediaApiClientOptions` — SDK client options.
+ * - `ListPrototypesParams` — Query parameters for listing prototypes.
+ *
+ * ### Data Fetching & Normalization
+ *
+ * - {@link FetchPrototypesResult} — Discriminated union result type for fetch operations.
+ * - {@link normalizePrototype} — Transform raw API data to {@link NormalizedPrototype}.
+ * - {@link UpstreamPrototype} — Raw API response type from protopedia-api-v2-client.
+ * - {@link NormalizedPrototype} — Standardized, type-safe prototype data model.
+ *
+ * ### Logging
+ *
+ * - {@link Logger} — Logger interface compatible with protopedia-api-v2-client.
+ * - {@link LogLevel} — Log level type for controlling logger verbosity.
+ *
+ * ## Standalone Usage
+ *
+ * This module is designed to work independently, allowing you to:
+ * - Create custom API clients with specific configurations
+ * - Build custom data processing pipelines
+ * - Integrate with different runtime environments (Node.js, Next.js, etc.)
+ *
+ * ## API Client Version Compatibility
+ *
+ * This library supports `protopedia-api-v2-client` v3.0.0 and later.
+ *
+ * @example
+ * ```typescript
+ * import { ProtopediaApiCustomClient } from 'promidas/fetcher';
+ *
+ * const client = new ProtopediaApiCustomClient({
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   logLevel: 'debug',
+ * });
+ *
+ * const result = await client.fetchPrototypes({ limit: 10 });
+ *
+ * if (result.ok) {
+ *   console.log(`Fetched ${result.data.length} prototypes`);
+ * }
+ * ```
+ *
+ * @module
+ * @see {@link ../repository/index.js} for high-level repository integration
+ */
+// API Client
+export { ProtopediaApiCustomClient } from './client/protopedia-api-custom-client.js';
+// Errors
+export { PromidasTimeoutError } from './errors/fetcher-error.js';
+// Utilities
+export { normalizePrototype } from './utils/normalize-prototype.js';
+//# sourceMappingURL=index.js.map

package/dist/fetcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/fetcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAQH,aAAa;AACb,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AAMrF,SAAS;AACT,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAYjE,YAAY;AACZ,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the fetcher module.
+ *
+ * @module
+ */
+export type { FetchProgressEvent, FetchProgressRequestStartEvent, FetchProgressResponseReceivedEvent, FetchProgressDownloadProgressEvent, FetchProgressCompleteEvent, FetchProgressErrorEvent, } from './progress-event.types.js';
+export type { UpstreamPrototype, NetworkFailure, } from './prototype-api.types.js';
+export type { FetchPrototypesResult, FetchPrototypesSuccess, FetchPrototypesFailure, FetchFailureKind, FetcherErrorCode, } from './result.types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,kBAAkB,EAClB,8BAA8B,EAC9B,kCAAkC,EAClC,kCAAkC,EAClC,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/fetcher/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the fetcher module.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/fetcher/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/fetcher/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/fetcher/types/progress-event.types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Progress event types for fetch operations.
+ *
+ * This module defines event types for tracking the complete lifecycle
+ * of HTTP requests, from initiation to completion.
+ *
+ * @module
+ */
+/**
+ * Event fired when a fetch request starts.
+ *
+ * This event occurs immediately before the `fetch()` call is made,
+ * marking the beginning of the request lifecycle.
+ *
+ * @example
+ * ```typescript
+ * if (event.type === 'request-start') {
+ *   console.log('Request initiated...');
+ * }
+ * ```
+ */
+export type FetchProgressRequestStartEvent = {
+    type: 'request-start';
+};
+/**
+ * Event fired when response headers are received.
+ *
+ * This event occurs after the server responds with headers but before
+ * the response body download begins. It includes timing information
+ * for the preparation phase and estimated download size.
+ *
+ * @example
+ * ```typescript
+ * if (event.type === 'response-received') {
+ *   console.log(`Headers received in ${event.prepareTimeMs}ms`);
+ *   console.log(`Estimated download: ${event.estimatedTotal} bytes`);
+ * }
+ * ```
+ */
+export type FetchProgressResponseReceivedEvent = {
+    type: 'response-received';
+    /**
+     * Time spent from request start to header reception (milliseconds).
+     */
+    prepareTimeMs: number;
+    /**
+     * Estimated total download size in bytes.
+     * Derived from Content-Length header or URL parameters.
+     */
+    estimatedTotal: number;
+    /**
+     * Number of items being fetched (from URL limit parameter).
+     * 0 if limit parameter is not present.
+     */
+    limit: number;
+};
+/**
+ * Event fired during response body download.
+ *
+ * This event provides real-time progress updates as data is received.
+ * Events are throttled to occur at most once every 500ms to avoid overhead.
+ *
+ * @example
+ * ```typescript
+ * if (event.type === 'download-progress') {
+ *   console.log(`Progress: ${event.percentage.toFixed(1)}%`);
+ *   console.log(`${event.received} / ${event.total} bytes`);
+ * }
+ * ```
+ */
+export type FetchProgressDownloadProgressEvent = {
+    type: 'download-progress';
+    /**
+     * Number of bytes received so far.
+     */
+    received: number;
+    /**
+     * Total number of bytes to download.
+     * May be 0 if Content-Length header is missing.
+     */
+    total: number;
+    /**
+     * Download progress as a percentage (0-100).
+     * 0 if total is unknown.
+     */
+    percentage: number;
+};
+/**
+ * Event fired when download completes successfully.
+ *
+ * This event marks the successful completion of the entire request lifecycle,
+ * including both preparation and download phases.
+ *
+ * @example
+ * ```typescript
+ * if (event.type === 'complete') {
+ *   console.log(`Downloaded ${event.received} bytes`);
+ *   console.log(`Total time: ${event.totalTimeMs}ms`);
+ *   console.log(`Download time: ${event.downloadTimeMs}ms`);
+ * }
+ * ```
+ */
+export type FetchProgressCompleteEvent = {
+    type: 'complete';
+    /**
+     * Total number of bytes actually received.
+     */
+    received: number;
+    /**
+     * Estimated total size in bytes (from headers or URL parameters).
+     */
+    estimatedTotal: number;
+    /**
+     * Time spent downloading the response body (milliseconds).
+     */
+    downloadTimeMs: number;
+    /**
+     * Total time from request start to completion (milliseconds).
+     * Includes both preparation and download time.
+     */
+    totalTimeMs: number;
+};
+/**
+ * Event fired when an error occurs during stream reading.
+ *
+ * This event is emitted when an error is thrown while reading the
+ * response body stream, such as network errors, timeout errors,
+ * or authentication failures (e.g., 401 Unauthorized).
+ *
+ * @example
+ * ```typescript
+ * if (event.type === 'error') {
+ *   console.error(`Download failed: ${event.error}`);
+ *   console.log(`Received ${event.received} bytes before error`);
+ *   console.log(`Failed after ${event.totalTimeMs}ms`);
+ * }
+ * ```
+ */
+export type FetchProgressErrorEvent = {
+    type: 'error';
+    /**
+     * Error message describing what went wrong.
+     */
+    error: string;
+    /**
+     * Number of bytes successfully received before the error occurred.
+     */
+    received: number;
+    /**
+     * Estimated total size in bytes (from headers or URL parameters).
+     */
+    estimatedTotal: number;
+    /**
+     * Time spent on download attempt before error (milliseconds).
+     */
+    downloadTimeMs: number;
+    /**
+     * Total time from request start to error (milliseconds).
+     * Includes both preparation and download time.
+     */
+    totalTimeMs: number;
+};
+/**
+ * Discriminated union of all fetch progress events.
+ *
+ * This type represents all possible events that can occur during
+ * a fetch request lifecycle. TypeScript's discriminated union feature
+ * enables type-safe event handling based on the `type` property.
+ *
+ * ## Event Lifecycle
+ *
+ * **Success flow:**
+ * 1. `request-start` → Request initiated
+ * 2. `response-received` → Headers received
+ * 3. `download-progress` (multiple, throttled) → Body streaming
+ * 4. `complete` → Download finished successfully
+ *
+ * **Error flow (stream reading failure):**
+ * 1. `request-start` → Request initiated
+ * 2. `response-received` → Headers received
+ * 3. `download-progress` (optional) → Partial data received
+ * 4. `error` → Stream reading failed (e.g., network error, auth failure)
+ *
+ * Note: `download-progress` events may occur before `error` if some chunks
+ * were successfully read before the failure.
+ *
+ * @example Basic usage
+ * ```typescript
+ * function handleProgressEvent(event: FetchProgressEvent) {
+ *   switch (event.type) {
+ *     case 'request-start':
+ *       console.log('Starting request...');
+ *       break;
+ *     case 'response-received':
+ *       console.log(`Headers received (${event.prepareTimeMs}ms)`);
+ *       break;
+ *     case 'download-progress':
+ *       console.log(`Progress: ${event.percentage}%`);
+ *       break;
+ *     case 'complete':
+ *       console.log(`Complete (${event.totalTimeMs}ms)`);
+ *       break;
+ *     case 'error':
+ *       console.error(`Error: ${event.error}`);
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @example Type narrowing
+ * ```typescript
+ * function handleEvent(event: FetchProgressEvent) {
+ *   if (event.type === 'download-progress') {
+ *     // TypeScript knows event has percentage, received, total properties
+ *     updateProgressBar(event.percentage);
+ *   }
+ * }
+ * ```
+ */
+export type FetchProgressEvent = FetchProgressRequestStartEvent | FetchProgressResponseReceivedEvent | FetchProgressDownloadProgressEvent | FetchProgressCompleteEvent | FetchProgressErrorEvent;
+//# sourceMappingURL=progress-event.types.d.ts.map

package/dist/fetcher/types/progress-event.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-event.types.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/types/progress-event.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,eAAe,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,UAAU,CAAC;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,OAAO,CAAC;IACd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,MAAM,kBAAkB,GAC1B,8BAA8B,GAC9B,kCAAkC,GAClC,kCAAkC,GAClC,0BAA0B,GAC1B,uBAAuB,CAAC"}

package/dist/fetcher/types/progress-event.types.js

@@ -0,0 +1,10 @@
+/**
+ * Progress event types for fetch operations.
+ *
+ * This module defines event types for tracking the complete lifecycle
+ * of HTTP requests, from initiation to completion.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=progress-event.types.js.map

package/dist/fetcher/types/progress-event.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-event.types.js","sourceRoot":"","sources":["../../../lib/fetcher/types/progress-event.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/fetcher/types/prototype-api.types.d.ts

@@ -0,0 +1,106 @@
+import type { ResultOfListPrototypesApiResponse } from 'protopedia-api-v2-client';
+/**
+ * Alias for the upstream prototype shape returned by the ProtoPedia SDK.
+ *
+ * This type represents a single prototype object as delivered by the
+ * `listPrototypes` API response. It is the input to normalization functions.
+ *
+ * **Important:** This is a direct re-export of the SDK's response type.
+ * If `protopedia-api-v2-client` changes its response shape in a future
+ * version, this type will automatically reflect those changes. The
+ * following areas may be affected:
+ *
+ * - Normalization function implementation (field mappings)
+ * - {@link NormalizedPrototype} type definition (may need updates)
+ * - Normalization tests (may need new test cases)
+ * - Helper functions (pipe-separated string parsing, timestamp normalization)
+ *
+ * **When upgrading `protopedia-api-v2-client`:**
+ * 1. Review the SDK's changelog for new or changed fields
+ * 2. Run tests - field coverage tests will fail if new fields are not normalized
+ * 3. Update normalization logic to handle new fields
+ * 4. Update {@link NormalizedPrototype} type if needed
+ * 5. Add test cases for new field transformations
+ */
+export type UpstreamPrototype = ResultOfListPrototypesApiResponse;
+/**
+ * Structure for network failure responses in Result-type patterns.
+ *
+ * This type represents error data for Result-type patterns (`{ ok: false, ... }`),
+ * distinct from the {@link ProtoPediaApiError} exception class from
+ * protopedia-api-v2-client. The structure is designed to be compatible with
+ * {@link FetchPrototypesFailure} and maintains consistency with error
+ * information from {@link ProtoPediaApiError}.
+ *
+ * ## Relationship with ProtoPediaApiError
+ *
+ * **NetworkFailure** is a plain data object, while **ProtoPediaApiError** is an
+ * Error subclass:
+ * - NetworkFailure: Used in Result types for functional error handling
+ * - ProtoPediaApiError: Thrown as exceptions by protopedia-api-v2-client
+ * - NetworkFailure: Can represent errors from any source (API, timeout, unexpected)
+ * - ProtoPediaApiError: Specifically represents HTTP errors from ProtoPedia API
+ *
+ * The `details` structure mirrors request/response metadata from
+ * {@link ProtoPediaApiError} (`req.url`, `req.method`, `statusText`) to maintain
+ * compatibility when converting API exceptions to Result types.
+ *
+ * ## Details Field
+ *
+ * The `details` object is always present and may contain:
+ * - Empty object `{}` for errors without metadata (AbortError, unexpected errors)
+ * - `req` object with URL and HTTP method from the request
+ * - `res` object with HTTP status text and optional error code
+ *
+ * @example
+ * ```ts
+ * // From ProtoPediaApiError (v2.0.0) - HTTP error with status
+ * const failure: NetworkFailure = {
+ *   status: 404,
+ *   error: 'Prototype not found',
+ *   details: {
+ *     req: { url: 'https://protopedia.cc/api/prototypes/123', method: 'GET' },
+ *     res: { statusText: 'Not Found' }
+ *   }
+ * };
+ *
+ * // Network error (ECONNREFUSED) - no status
+ * const networkError: NetworkFailure = {
+ *   error: 'connect ECONNREFUSED',
+ *   details: {
+ *     res: { code: 'ECONNREFUSED' }
+ *   }
+ * };
+ * ```
+ */
+export type NetworkFailure = {
+    /** Error message from Error.message or fallback string */
+    error: unknown;
+    /**
+     * HTTP status code from server response (e.g., 404, 500).
+     * Undefined for network errors where no server response was received
+     * (e.g., ENOTFOUND, ECONNREFUSED, AbortError).
+     */
+    status?: number;
+    /**
+     * Additional error details from request and response.
+     * Always present, but may be an empty object for errors without metadata.
+     */
+    details: {
+        /** Request information (compatible with ProtoPediaApiError.req from v2.0.0) */
+        req?: {
+            /** HTTP method (e.g., "GET", "POST") */
+            method?: string;
+            /** Request URL */
+            url?: string;
+        };
+        /** Response information (compatible with ProtoPediaApiError metadata) */
+        res?: {
+            /** HTTP status text (e.g., "Not Found", "Internal Server Error") */
+            statusText?: string;
+            /** Error code from the API (e.g., "RESOURCE_NOT_FOUND") */
+            code?: string;
+        };
+    };
+};
+//# sourceMappingURL=prototype-api.types.d.ts.map

package/dist/fetcher/types/prototype-api.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototype-api.types.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/types/prototype-api.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,iBAAiB,GAAG,iCAAiC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE;QACP,+EAA+E;QAC/E,GAAG,CAAC,EAAE;YACJ,wCAAwC;YACxC,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,kBAAkB;YAClB,GAAG,CAAC,EAAE,MAAM,CAAC;SACd,CAAC;QACF,yEAAyE;QACzE,GAAG,CAAC,EAAE;YACJ,oEAAoE;YACpE,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,2DAA2D;YAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC;CACH,CAAC"}

package/dist/fetcher/types/prototype-api.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prototype-api.types.js.map

package/dist/fetcher/types/prototype-api.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototype-api.types.js","sourceRoot":"","sources":["../../../lib/fetcher/types/prototype-api.types.ts"],"names":[],"mappings":""}

package/dist/fetcher/types/result.types.d.ts

@@ -0,0 +1,75 @@
+import type { NormalizedPrototype } from '../../types/index.js';
+import type { NetworkFailure } from './prototype-api.types.js';
+/**
+ * Coarse-grained discriminant for fetcher failures.
+ *
+ * - http: HTTP response was received (status is available)
+ * - cors: Browser returned an opaque response (no status/code observable)
+ * - network: Network/socket error without HTTP response (ENOTFOUND, ECONNREFUSED, etc.)
+ * - timeout: Fetcher-level timeout (no HTTP response)
+ * - abort: Caller-driven abort (AbortController)
+ * - unknown: Classification failed; fall back to code UNKNOWN
+ */
+export type FetchFailureKind = 'http' | 'cors' | 'network' | 'timeout' | 'abort' | 'unknown';
+/**
+ * Canonical error codes exposed by the fetcher.
+ *
+ * HTTP (4xx): CLIENT_UNAUTHORIZED / CLIENT_FORBIDDEN / CLIENT_NOT_FOUND /
+ * CLIENT_RATE_LIMITED / CLIENT_BAD_REQUEST / CLIENT_METHOD_NOT_ALLOWED /
+ * CLIENT_TIMEOUT / CLIENT_ERROR (other 4xx)
+ * HTTP (5xx): SERVER_INTERNAL_ERROR / SERVER_BAD_GATEWAY /
+ * SERVER_GATEWAY_TIMEOUT / SERVER_SERVICE_UNAVAILABLE / SERVER_ERROR (other 5xx)
+ * Network: NETWORK_ERROR / ECONNREFUSED / ENOTFOUND / ETIMEDOUT
+ * Control: TIMEOUT (fetcher timeout), ABORTED (AbortController)
+ * CORS: CORS_BLOCKED (opaque response; status/code not observable)
+ * Fallback: UNKNOWN
+ */
+export type FetcherErrorCode = 'CLIENT_UNAUTHORIZED' | 'CLIENT_FORBIDDEN' | 'CLIENT_NOT_FOUND' | 'CLIENT_RATE_LIMITED' | 'CLIENT_BAD_REQUEST' | 'CLIENT_METHOD_NOT_ALLOWED' | 'CLIENT_TIMEOUT' | 'CLIENT_ERROR' | 'SERVER_INTERNAL_ERROR' | 'SERVER_BAD_GATEWAY' | 'SERVER_GATEWAY_TIMEOUT' | 'SERVER_SERVICE_UNAVAILABLE' | 'SERVER_ERROR' | 'NETWORK_ERROR' | 'ECONNREFUSED' | 'ENOTFOUND' | 'ETIMEDOUT' | 'TIMEOUT' | 'ABORTED' | 'CORS_BLOCKED' | 'UNKNOWN';
+/**
+ * Successful response from fetchPrototypes containing an array of prototypes.
+ */
+export type FetchPrototypesSuccess = {
+    ok: true;
+    data: NormalizedPrototype[];
+};
+/**
+ * Failed response from fetchPrototypes with error details.
+ */
+export type FetchPrototypesFailure = {
+    ok: false;
+    /** Always fetcher-originated. */
+    origin: 'fetcher';
+    /** Coarse-grained classification of the failure cause. */
+    kind: FetchFailureKind;
+    /** Canonicalized error code (in addition to details.res.code). */
+    code: FetcherErrorCode;
+    /** Human-readable error message. */
+    error: string;
+} & Omit<NetworkFailure, 'error'>;
+/**
+ * Result type for fetchPrototypes function - either success with data or failure with error.
+ */
+export type FetchPrototypesResult = FetchPrototypesSuccess | FetchPrototypesFailure;
+/**
+ * Successful response from fetchRandomPrototype containing a single prototype.
+ */
+export type FetchRandomPrototypeSuccess = {
+    ok: true;
+    data: NormalizedPrototype;
+};
+/**
+ * Failed response from fetchRandomPrototype (same as FetchPrototypesFailure).
+ */
+export type FetchRandomPrototypeFailure = FetchPrototypesFailure;
+/**
+ * Result type for fetchRandomPrototype function - either success with single prototype or failure.
+ */
+export type FetchRandomPrototypeResult = FetchRandomPrototypeSuccess | FetchRandomPrototypeFailure;
+/**
+ * Result type for fetchPrototypeById function - either success with single prototype or failure.
+ */
+export type FetchPrototypeByIdResult = {
+    ok: true;
+    data: NormalizedPrototype;
+} | FetchPrototypesFailure;
+//# sourceMappingURL=result.types.d.ts.map

package/dist/fetcher/types/result.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.types.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/types/result.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,SAAS,GACT,SAAS,GACT,OAAO,GACP,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,GACpB,2BAA2B,GAC3B,gBAAgB,GAChB,cAAc,GACd,uBAAuB,GACvB,oBAAoB,GACpB,wBAAwB,GACxB,4BAA4B,GAC5B,cAAc,GACd,eAAe,GACf,cAAc,GACd,WAAW,GACX,WAAW,GACX,SAAS,GACT,SAAS,GACT,cAAc,GACd,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,mBAAmB,EAAE,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,iCAAiC;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,0DAA0D;IAC1D,IAAI,EAAE,gBAAgB,CAAC;IACvB,kEAAkE;IAClE,IAAI,EAAE,gBAAgB,CAAC;IACvB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,2BAA2B,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACvC,sBAAsB,CAAC"}

package/dist/fetcher/types/result.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=result.types.js.map

package/dist/fetcher/types/result.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.types.js","sourceRoot":"","sources":["../../../lib/fetcher/types/result.types.ts"],"names":[],"mappings":""}

package/dist/fetcher/utils/create-client-fetch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { Logger } from '../../logger/index.js';
+import type { FetchProgressEvent } from '../types/progress-event.types.js';
+/**
+ * Parameters for creating a customized fetch function.
+ */
+export type CreateClientFetchParams = {
+    logger: Logger;
+    enableProgressLog: boolean;
+    progressCallback: ((event: FetchProgressEvent) => void) | undefined;
+    timeoutMs: number | undefined;
+    providedFetch: typeof fetch | undefined;
+    stripHeaders?: string[] | undefined;
+};
+/**
+ * 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 declare function createClientFetch(params: CreateClientFetchParams): typeof fetch | undefined;
+//# sourceMappingURL=create-client-fetch.d.ts.map

package/dist/fetcher/utils/create-client-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client-fetch.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/utils/create-client-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,CAAC,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACpE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,uBAAuB,GAC9B,OAAO,KAAK,GAAG,SAAS,CAmD1B"}