promidas 2.0.0

package/dist/fetcher/client/protopedia-api-custom-client.d.ts

@@ -0,0 +1,141 @@
+/**
+ * ProtopediaApiCustomClient class implementation.
+ *
+ * This module provides a class-based wrapper around the official
+ * protopedia-api-v2-client with integrated logger management,
+ * event-driven progress tracking, and high-level helper methods.
+ *
+ * Features:
+ * - Fastify-style logger configuration (logger + logLevel)
+ * - Event-driven progress tracking with type-safe discriminated unions
+ * - Automatic data normalization and validation
+ * - Result type for type-safe error handling
+ *
+ * @module
+ */
+import { type ListPrototypesParams } from 'protopedia-api-v2-client';
+import type { FetchPrototypesResult } from '../types/result.types.js';
+import type { ProtopediaApiCustomClientConfig } from './config.js';
+/**
+ * Custom API client that wraps protopedia-api-v2-client with enhanced features.
+ *
+ * This class manages:
+ * - Logger configuration (Fastify-style with logger + logLevel)
+ * - Integration with protopedia-api-v2-client
+ * - Event-driven progress tracking for download operations
+ * - High-level fetchPrototypes helper with normalization and error handling
+ *
+ * @example Basic usage
+ * ```typescript
+ * 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(result.data);
+ * }
+ * ```
+ *
+ * @example With progress tracking
+ * ```typescript
+ * const client = new ProtopediaApiCustomClient({
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   progressCallback: (event) => {
+ *     switch (event.type) {
+ *       case 'request-start':
+ *         console.log('Starting request...');
+ *         break;
+ *       case 'download-progress':
+ *         console.log(`Progress: ${event.percentage.toFixed(1)}%`);
+ *         break;
+ *       case 'complete':
+ *         console.log(`Complete in ${event.totalTimeMs}ms`);
+ *         break;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export declare class ProtopediaApiCustomClient {
+    #private;
+    /**
+     * Create a new ProtopediaApiCustomClient instance.
+     *
+     * @param config - Configuration options for the client
+     * @param config.protoPediaApiClientOptions - Options for protopedia-api-v2-client
+     * @param config.protoPediaApiClientOptions.timeoutMs - Optional request timeout in milliseconds
+     * @param config.protoPediaApiClientOptions.fetch - Optional custom fetch implementation
+     * @param config.logger - Custom logger instance
+     * @param config.logLevel - Log level for default logger or to update existing logger
+     * @param config.progressLog - Enable download progress logging (default: true)
+     * @param config.progressCallback - Event handler for download progress lifecycle events
+     *
+     * @throws {unknown} If the underlying protopedia-api-v2-client initialization fails
+     *
+     * @example Basic usage with progress logging
+     * ```typescript
+     * const client = new ProtopediaApiCustomClient({
+     *   protoPediaApiClientOptions: { token: process.env.TOKEN },
+     *   logLevel: 'info', // Shows progress logs
+     * });
+     * ```
+     *
+     * @example With custom event handler
+     * ```typescript
+     * const client = new ProtopediaApiCustomClient({
+     *   protoPediaApiClientOptions: { token: process.env.TOKEN },
+     *   progressLog: false, // Disable automatic logging
+     *   progressCallback: (event) => {
+     *     if (event.type === 'download-progress') {
+     *       updateProgressBar(event.percentage);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    constructor(config?: ProtopediaApiCustomClientConfig | null);
+    /**
+     * Fetch prototypes using the configured client, normalize them,
+     * and return a structured result.
+     *
+     * This high-level helper combines API fetching, normalization, and
+     * error handling into a single call. It uses the logger configured
+     * during construction for error diagnostics.
+     *
+     * @param params - Query parameters for listing prototypes
+     * @returns A {@link FetchPrototypesResult} with normalized data or error details
+     *
+     * @example
+     * ```typescript
+     * const result = await client.fetchPrototypes({ offset: 0, limit: 100 });
+     * if (result.ok) {
+     *   console.log(`Fetched ${result.data.length} prototypes`);
+     * } else {
+     *   console.error(result.error, result.status);
+     * }
+     * ```
+     */
+    fetchPrototypes(params: ListPrototypesParams): Promise<FetchPrototypesResult>;
+    /**
+     * Direct access to the underlying protopedia-api-v2-client's listPrototypes method.
+     *
+     * Use this when you need the raw API response without normalization.
+     *
+     * @param params - Query parameters for listing prototypes
+     * @returns Raw API response from protopedia-api-v2-client
+     *
+     * @example
+     * ```typescript
+     * const rawResult = await client.listPrototypes({ limit: 10 });
+     * console.log(rawResult.results);
+     * ```
+     */
+    listPrototypes(params: ListPrototypesParams): Promise<import("protopedia-api-v2-client").ListPrototypesApiResponse>;
+}
+//# sourceMappingURL=protopedia-api-custom-client.d.ts.map

package/dist/fetcher/client/protopedia-api-custom-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protopedia-api-custom-client.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/client/protopedia-api-custom-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAclC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAMtE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,yBAAyB;;IAgBpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;gBACS,MAAM,CAAC,EAAE,+BAA+B,GAAG,IAAI;IA6I3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,CACnB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,qBAAqB,CAAC;IAIjC;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,MAAM,EAAE,oBAAoB;CAGlD"}

package/dist/fetcher/client/protopedia-api-custom-client.js

@@ -0,0 +1,268 @@
+/**
+ * ProtopediaApiCustomClient class implementation.
+ *
+ * This module provides a class-based wrapper around the official
+ * protopedia-api-v2-client with integrated logger management,
+ * event-driven progress tracking, and high-level helper methods.
+ *
+ * Features:
+ * - Fastify-style logger configuration (logger + logLevel)
+ * - Event-driven progress tracking with type-safe discriminated unions
+ * - Automatic data normalization and validation
+ * - Result type for type-safe error handling
+ *
+ * @module
+ */
+import { createProtoPediaClient, } from 'protopedia-api-v2-client';
+import { ConsoleLogger, } from '../../logger/index.js';
+import { sanitizeDataForLogging } from '../../utils/index.js';
+import { VERSION } from '../../version.js';
+import { createClientFetch } from '../utils/create-client-fetch.js';
+import { handleApiError } from '../utils/errors/handler.js';
+import { logTimestampNormalizationWarnings } from '../utils/log-timestamp-normalization-warnings.js';
+import { normalizePrototype } from '../utils/normalize-prototype.js';
+/**
+ * Custom API client that wraps protopedia-api-v2-client with enhanced features.
+ *
+ * This class manages:
+ * - Logger configuration (Fastify-style with logger + logLevel)
+ * - Integration with protopedia-api-v2-client
+ * - Event-driven progress tracking for download operations
+ * - High-level fetchPrototypes helper with normalization and error handling
+ *
+ * @example Basic usage
+ * ```typescript
+ * 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(result.data);
+ * }
+ * ```
+ *
+ * @example With progress tracking
+ * ```typescript
+ * const client = new ProtopediaApiCustomClient({
+ *   protoPediaApiClientOptions: {
+ *     token: process.env.PROTOPEDIA_API_TOKEN,
+ *   },
+ *   progressCallback: (event) => {
+ *     switch (event.type) {
+ *       case 'request-start':
+ *         console.log('Starting request...');
+ *         break;
+ *       case 'download-progress':
+ *         console.log(`Progress: ${event.percentage.toFixed(1)}%`);
+ *         break;
+ *       case 'complete':
+ *         console.log(`Complete in ${event.totalTimeMs}ms`);
+ *         break;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export class ProtopediaApiCustomClient {
+    /**
+     * Underlying protopedia-api-v2-client instance.
+     */
+    #client;
+    /**
+     * Logger instance for this client.
+     */
+    #logger;
+    /**
+     * Log level for this client.
+     */
+    #logLevel;
+    /**
+     * Create a new ProtopediaApiCustomClient instance.
+     *
+     * @param config - Configuration options for the client
+     * @param config.protoPediaApiClientOptions - Options for protopedia-api-v2-client
+     * @param config.protoPediaApiClientOptions.timeoutMs - Optional request timeout in milliseconds
+     * @param config.protoPediaApiClientOptions.fetch - Optional custom fetch implementation
+     * @param config.logger - Custom logger instance
+     * @param config.logLevel - Log level for default logger or to update existing logger
+     * @param config.progressLog - Enable download progress logging (default: true)
+     * @param config.progressCallback - Event handler for download progress lifecycle events
+     *
+     * @throws {unknown} If the underlying protopedia-api-v2-client initialization fails
+     *
+     * @example Basic usage with progress logging
+     * ```typescript
+     * const client = new ProtopediaApiCustomClient({
+     *   protoPediaApiClientOptions: { token: process.env.TOKEN },
+     *   logLevel: 'info', // Shows progress logs
+     * });
+     * ```
+     *
+     * @example With custom event handler
+     * ```typescript
+     * const client = new ProtopediaApiCustomClient({
+     *   protoPediaApiClientOptions: { token: process.env.TOKEN },
+     *   progressLog: false, // Disable automatic logging
+     *   progressCallback: (event) => {
+     *     if (event.type === 'download-progress') {
+     *       updateProgressBar(event.percentage);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    constructor(config) {
+        const { protoPediaApiClientOptions = {}, logger, logLevel, progressLog = true, progressCallback, } = config ?? {};
+        const { timeoutMs, fetch: providedFetch, ...sdkOptions } = protoPediaApiClientOptions;
+        // Fastify-style logger configuration
+        if (logger) {
+            this.#logger = logger;
+            this.#logLevel = logLevel ?? 'info';
+            // If logLevel is specified, update logger's level property (if mutable)
+            if (logLevel !== undefined && 'level' in logger) {
+                logger.level = logLevel;
+            }
+        }
+        else {
+            const resolvedLogLevel = logLevel ?? 'info';
+            this.#logger = new ConsoleLogger(resolvedLogLevel);
+            this.#logLevel = resolvedLogLevel;
+        }
+        this.#logger.info('ProtopediaApiCustomClient constructor called', sanitizeDataForLogging(config));
+        const hasWindow = typeof globalThis.window !== 'undefined';
+        const hasDocument = typeof globalThis.document !== 'undefined';
+        const isBrowserRuntime = hasWindow && hasDocument;
+        // Determine User-Agent header
+        const userAgent = sdkOptions.userAgent ?? `ProtopediaApiCustomClient/${VERSION} (promidas)`;
+        // Issue #55 (browser CORS): `protopedia-api-v2-client` adds
+        // `x-client-user-agent` by design. In browsers, custom request headers
+        // trigger a CORS preflight and the request may be blocked because the
+        // server may not allow that header.
+        //
+        // Mitigation (promidas-side): In browser runtimes, strip
+        // `x-client-user-agent` from the outgoing request in our fetch wrapper.
+        // Server-side Node.js execution is not affected.
+        // Determine headers to strip based on runtime environment
+        const stripHeaders = isBrowserRuntime ? ['x-client-user-agent'] : undefined;
+        const customFetch = createClientFetch({
+            logger: this.#logger,
+            enableProgressLog: progressLog,
+            progressCallback,
+            timeoutMs,
+            providedFetch: providedFetch,
+            stripHeaders,
+        });
+        // Create underlying protopedia-api-v2-client
+        // Note: SDK client logging is controlled via protoPediaApiClientOptions
+        this.#client = createProtoPediaClient({
+            ...sdkOptions,
+            userAgent,
+            ...(customFetch !== undefined && { fetch: customFetch }),
+        });
+    }
+    /**
+     * Fetch and normalize ProtoPedia prototypes.
+     *
+     * This helper calls the underlying client's listPrototypes method,
+     * normalizes each item into a {@link NormalizedPrototype}, and wraps
+     * the result in a {@link FetchPrototypesResult} discriminated union.
+     *
+     * This method never throws; all errors are caught and converted into
+     * failure results by {@link handleApiError}.
+     *
+     * @param params - Query parameters for the upstream listPrototypes call
+     * @returns A {@link FetchPrototypesResult} with normalized data or error details
+     *
+     * @private
+     */
+    async #fetchAndNormalizePrototypes(params) {
+        try {
+            const upstream = await this.#client.listPrototypes(params);
+            let data = [];
+            if (!Array.isArray(upstream.results)) {
+                this.#logger.warn('Upstream API response "results" is not an array. Returning empty data.', {
+                    upstreamResults: upstream.results,
+                    params,
+                });
+                // data remains empty array as initialized
+            }
+            else {
+                data = upstream.results.map((value, index) => {
+                    const original = value;
+                    const normalized = normalizePrototype(original);
+                    logTimestampNormalizationWarnings({
+                        logger: this.#logger,
+                        original,
+                        normalized,
+                        index,
+                    });
+                    return normalized;
+                });
+            }
+            this.#logger.debug(`Successfully fetched ${data.length} prototypes.`, {
+                params,
+            });
+            return { ok: true, data };
+        }
+        catch (error) {
+            const errorResult = handleApiError(error);
+            // Log based on the errorResult (always an error result from handleApiError)
+            if (!errorResult.ok) {
+                const sanitizedError = sanitizeDataForLogging(errorResult);
+                if (errorResult.status === undefined || errorResult.status >= 500) {
+                    this.#logger.error(errorResult.error, sanitizedError);
+                }
+                else {
+                    this.#logger.warn(errorResult.error, sanitizedError);
+                }
+            }
+            return errorResult;
+        }
+    }
+    /**
+     * Fetch prototypes using the configured client, normalize them,
+     * and return a structured result.
+     *
+     * This high-level helper combines API fetching, normalization, and
+     * error handling into a single call. It uses the logger configured
+     * during construction for error diagnostics.
+     *
+     * @param params - Query parameters for listing prototypes
+     * @returns A {@link FetchPrototypesResult} with normalized data or error details
+     *
+     * @example
+     * ```typescript
+     * const result = await client.fetchPrototypes({ offset: 0, limit: 100 });
+     * if (result.ok) {
+     *   console.log(`Fetched ${result.data.length} prototypes`);
+     * } else {
+     *   console.error(result.error, result.status);
+     * }
+     * ```
+     */
+    async fetchPrototypes(params) {
+        return this.#fetchAndNormalizePrototypes(params);
+    }
+    /**
+     * Direct access to the underlying protopedia-api-v2-client's listPrototypes method.
+     *
+     * Use this when you need the raw API response without normalization.
+     *
+     * @param params - Query parameters for listing prototypes
+     * @returns Raw API response from protopedia-api-v2-client
+     *
+     * @example
+     * ```typescript
+     * const rawResult = await client.listPrototypes({ limit: 10 });
+     * console.log(rawResult.results);
+     * ```
+     */
+    async listPrototypes(params) {
+        return this.#client.listPrototypes(params);
+    }
+}
+//# sourceMappingURL=protopedia-api-custom-client.js.map

package/dist/fetcher/client/protopedia-api-custom-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protopedia-api-custom-client.js","sourceRoot":"","sources":["../../../lib/fetcher/client/protopedia-api-custom-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,aAAa,GAGd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAM3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,iCAAiC,EAAE,MAAM,kDAAkD,CAAC;AACrG,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAIrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,OAAO,yBAAyB;IACpC;;OAEG;IACM,OAAO,CAAsB;IAEtC;;OAEG;IACM,OAAO,CAAS;IAEzB;;OAEG;IACM,SAAS,CAAW;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,YAAY,MAA+C;QACzD,MAAM,EACJ,0BAA0B,GAAG,EAAE,EAC/B,MAAM,EACN,QAAQ,EACR,WAAW,GAAG,IAAI,EAClB,gBAAgB,GACjB,GAAG,MAAM,IAAI,EAAE,CAAC;QAEjB,MAAM,EACJ,SAAS,EACT,KAAK,EAAE,aAAa,EACpB,GAAG,UAAU,EACd,GAAG,0BAA0B,CAAC;QAE/B,qCAAqC;QACrC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;YACtB,IAAI,CAAC,SAAS,GAAG,QAAQ,IAAI,MAAM,CAAC;YACpC,wEAAwE;YACxE,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;gBAC/C,MAA8B,CAAC,KAAK,GAAG,QAAQ,CAAC;YACnD,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,gBAAgB,GAAG,QAAQ,IAAI,MAAM,CAAC;YAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,gBAAgB,CAAC,CAAC;YACnD,IAAI,CAAC,SAAS,GAAG,gBAAgB,CAAC;QACpC,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CACf,8CAA8C,EAC9C,sBAAsB,CAAC,MAAM,CAAC,CAC/B,CAAC;QAEF,MAAM,SAAS,GACb,OAAQ,UAAmC,CAAC,MAAM,KAAK,WAAW,CAAC;QACrE,MAAM,WAAW,GACf,OAAQ,UAAqC,CAAC,QAAQ,KAAK,WAAW,CAAC;QACzE,MAAM,gBAAgB,GAAG,SAAS,IAAI,WAAW,CAAC;QAElD,8BAA8B;QAC9B,MAAM,SAAS,GACb,UAAU,CAAC,SAAS,IAAI,6BAA6B,OAAO,aAAa,CAAC;QAE5E,4DAA4D;QAC5D,uEAAuE;QACvE,sEAAsE;QACtE,oCAAoC;QACpC,EAAE;QACF,yDAAyD;QACzD,wEAAwE;QACxE,iDAAiD;QAEjD,0DAA0D;QAC1D,MAAM,YAAY,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE5E,MAAM,WAAW,GAAG,iBAAiB,CAAC;YACpC,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,iBAAiB,EAAE,WAAW;YAC9B,gBAAgB;YAChB,SAAS;YACT,aAAa,EAAE,aAAyC;YACxD,YAAY;SACb,CAAC,CAAC;QAEH,6CAA6C;QAC7C,wEAAwE;QACxE,IAAI,CAAC,OAAO,GAAG,sBAAsB,CAAC;YACpC,GAAG,UAAU;YACb,SAAS;YACT,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;SACzD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,4BAA4B,CAChC,MAA4B;QAE5B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAE3D,IAAI,IAAI,GAA0B,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CACf,wEAAwE,EACxE;oBACE,eAAe,EAAE,QAAQ,CAAC,OAAO;oBACjC,MAAM;iBACP,CACF,CAAC;gBACF,0CAA0C;YAC5C,CAAC;iBAAM,CAAC;gBACN,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBAC3C,MAAM,QAAQ,GAAG,KAA0B,CAAC;oBAC5C,MAAM,UAAU,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;oBAEhD,iCAAiC,CAAC;wBAChC,MAAM,EAAE,IAAI,CAAC,OAAO;wBACpB,QAAQ;wBACR,UAAU;wBACV,KAAK;qBACN,CAAC,CAAC;oBAEH,OAAO,UAAU,CAAC;gBACpB,CAAC,CAAC,CAAC;YACL,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,wBAAwB,IAAI,CAAC,MAAM,cAAc,EAAE;gBACpE,MAAM;aACP,CAAC,CAAC;YAEH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YAC1C,4EAA4E;YAC5E,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC;gBACpB,MAAM,cAAc,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;gBAC3D,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,IAAI,WAAW,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;oBAClE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;gBACxD,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;gBACvD,CAAC;YACH,CAAC;YACD,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,eAAe,CACnB,MAA4B;QAE5B,OAAO,IAAI,CAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,cAAc,CAAC,MAA4B;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/fetcher/client/select-custom-fetch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom fetch selector function.
+ *
+ * This module provides a function to select the appropriate custom fetch
+ * implementation based on configuration. It evaluates various feature flags
+ * and returns the corresponding custom fetch function, or undefined to use
+ * the default fetch implementation.
+ *
+ * @module
+ */
+import type { Logger } from '../../logger/index.js';
+import type { FetchProgressEvent } from '../types/progress-event.types.js';
+/**
+ * Configuration for custom fetch selection.
+ */
+export interface CustomFetchConfig {
+    /**
+     * Logger instance for custom fetch implementations.
+     */
+    logger: Logger;
+    /**
+     * Whether to enable progress logging.
+     */
+    enableProgressLog: boolean;
+    /**
+     * Base fetch function to wrap with progress tracking.
+     * If not provided, uses global fetch.
+     */
+    baseFetch?: typeof fetch;
+    /**
+     * Optional callback for progress events.
+     */
+    onProgressEvent?: (event: FetchProgressEvent) => void;
+}
+/**
+ * Select appropriate custom fetch function based on configuration.
+ *
+ * This function evaluates the provided configuration and returns the appropriate
+ * custom fetch function. If no custom features are needed, it returns undefined
+ * to allow the default fetch implementation to be used.
+ *
+ * @param config - Configuration for custom fetch selection
+ * @returns Custom fetch function or undefined for default behavior
+ *
+ * @example
+ * ```typescript
+ * const customFetch = selectCustomFetch({
+ *   logger: myLogger,
+ *   enableProgressLog: true,
+ * });
+ *
+ * const client = createProtoPediaClient({
+ *   fetch: customFetch, // undefined uses default fetch
+ * });
+ * ```
+ */
+export declare function selectCustomFetch(config: CustomFetchConfig): typeof fetch | undefined;
+//# sourceMappingURL=select-custom-fetch.d.ts.map

package/dist/fetcher/client/select-custom-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-custom-fetch.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/client/select-custom-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAEzB;;OAEG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB,OAAO,KAAK,GAAG,SAAS,CA4B1B"}

package/dist/fetcher/client/select-custom-fetch.js

@@ -0,0 +1,58 @@
+/**
+ * Custom fetch selector function.
+ *
+ * This module provides a function to select the appropriate custom fetch
+ * implementation based on configuration. It evaluates various feature flags
+ * and returns the corresponding custom fetch function, or undefined to use
+ * the default fetch implementation.
+ *
+ * @module
+ */
+import { createFetchWithProgress } from './fetch-with-progress.js';
+/**
+ * Select appropriate custom fetch function based on configuration.
+ *
+ * This function evaluates the provided configuration and returns the appropriate
+ * custom fetch function. If no custom features are needed, it returns undefined
+ * to allow the default fetch implementation to be used.
+ *
+ * @param config - Configuration for custom fetch selection
+ * @returns Custom fetch function or undefined for default behavior
+ *
+ * @example
+ * ```typescript
+ * const customFetch = selectCustomFetch({
+ *   logger: myLogger,
+ *   enableProgressLog: true,
+ * });
+ *
+ * const client = createProtoPediaClient({
+ *   fetch: customFetch, // undefined uses default fetch
+ * });
+ * ```
+ */
+export function selectCustomFetch(config) {
+    const { logger, enableProgressLog, baseFetch, onProgressEvent } = config;
+    // Check if progress tracking is needed
+    const needsProgressTracking = enableProgressLog || onProgressEvent !== undefined;
+    if (needsProgressTracking) {
+        return createFetchWithProgress({
+            logger,
+            enableProgressLog,
+            ...(baseFetch !== undefined && { baseFetch }),
+            ...(onProgressEvent !== undefined && { onProgressEvent }),
+        });
+    }
+    // Future: Add other custom fetch implementations here
+    // Example:
+    // if (config.retryEnabled) {
+    //   return createFetchWithRetry({ baseFetch, ... });
+    // }
+    //
+    // if (config.cacheEnabled) {
+    //   return createFetchWithCache({ baseFetch, ... });
+    // }
+    // If no custom features needed, return the base fetch or undefined
+    return baseFetch;
+}
+//# sourceMappingURL=select-custom-fetch.js.map

package/dist/fetcher/client/select-custom-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-custom-fetch.js","sourceRoot":"","sources":["../../../lib/fetcher/client/select-custom-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AA4BnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAyB;IAEzB,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC;IAEzE,uCAAuC;IACvC,MAAM,qBAAqB,GACzB,iBAAiB,IAAI,eAAe,KAAK,SAAS,CAAC;IAErD,IAAI,qBAAqB,EAAE,CAAC;QAC1B,OAAO,uBAAuB,CAAC;YAC7B,MAAM;YACN,iBAAiB;YACjB,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,eAAe,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IAED,sDAAsD;IACtD,WAAW;IACX,6BAA6B;IAC7B,qDAAqD;IACrD,IAAI;IACJ,EAAE;IACF,6BAA6B;IAC7B,qDAAqD;IACrD,IAAI;IAEJ,mEAAmE;IACnE,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/fetcher/errors/fetcher-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error classes for fetcher operations.
+ *
+ * @module
+ */
+export declare class PromidasTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, message?: string);
+}
+//# sourceMappingURL=fetcher-error.d.ts.map

package/dist/fetcher/errors/fetcher-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher-error.d.ts","sourceRoot":"","sources":["../../../lib/fetcher/errors/fetcher-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAMhD"}

package/dist/fetcher/errors/fetcher-error.js

@@ -0,0 +1,15 @@
+/**
+ * Error classes for fetcher operations.
+ *
+ * @module
+ */
+export class PromidasTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, message) {
+        super(message ?? `Upstream request timed out after ${timeoutMs}ms`);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'PromidasTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+//# sourceMappingURL=fetcher-error.js.map

package/dist/fetcher/errors/fetcher-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher-error.js","sourceRoot":"","sources":["../../../lib/fetcher/errors/fetcher-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,SAAS,CAAS;IAE3B,YAAY,SAAiB,EAAE,OAAgB;QAC7C,KAAK,CAAC,OAAO,IAAI,oCAAoC,SAAS,IAAI,CAAC,CAAC;QACpE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}

package/dist/fetcher/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+export type { NormalizedPrototype } from '../types/index.js';
+export type { Logger, LogLevel } from '../logger/index.js';
+export { ProtopediaApiCustomClient } from './client/protopedia-api-custom-client.js';
+export type { ProtopediaApiCustomClientConfig } from './client/config.js';
+export type { FetchProgressEvent } from './types/progress-event.types.js';
+export { PromidasTimeoutError } from './errors/fetcher-error.js';
+export type { FetchPrototypesResult, FetchFailureKind, FetcherErrorCode, } from './types/result.types.js';
+export type { UpstreamPrototype } from './types/prototype-api.types.js';
+export { normalizePrototype } from './utils/normalize-prototype.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/fetcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAGH,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,YAAY,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAG1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAG1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGjE,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}