mcp-hydrocoder-image 1.0.0

package/dist/types/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/types/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsCH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA4B;IAC3D,MAAM;IACN,UAAU;IACV,SAAS;CACD,CAAA;AAEV;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,uDAAuD;IACvD,KAAK,EAAE,gCAAgC;IACvC,+CAA+C;IAC/C,GAAG,EAAE,4BAA4B;CACzB,CAAA"}

package/dist/types/result.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Result type for operations that may fail
+ * Provides type-safe error handling with discriminated unions
+ */
+/**
+ * Result type that represents either success with data or failure with error
+ */
+export type Result<T, E extends Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/**
+ * Helper function to create a successful Result
+ * @param data The data to wrap in a successful Result
+ * @returns A successful Result containing the data
+ */
+export declare function Ok<T>(data: T): Result<T, never>;
+/**
+ * Helper function to create an error Result
+ * @param error The error to wrap in a failed Result
+ * @returns A failed Result containing the error
+ */
+export declare function Err<E extends Error>(error: E): Result<never, E>;
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,IACjC;IACE,OAAO,EAAE,IAAI,CAAA;IACb,IAAI,EAAE,CAAC,CAAA;CACR,GACD;IACE,OAAO,EAAE,KAAK,CAAA;IACd,KAAK,EAAE,CAAC,CAAA;CACT,CAAA;AAEL;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAK/D"}

package/dist/types/result.js

@@ -0,0 +1,27 @@
+/**
+ * Result type for operations that may fail
+ * Provides type-safe error handling with discriminated unions
+ */
+/**
+ * Helper function to create a successful Result
+ * @param data The data to wrap in a successful Result
+ * @returns A successful Result containing the data
+ */
+export function Ok(data) {
+    return {
+        success: true,
+        data,
+    };
+}
+/**
+ * Helper function to create an error Result
+ * @param error The error to wrap in a failed Result
+ * @returns A failed Result containing the error
+ */
+export function Err(error) {
+    return {
+        success: false,
+        error,
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/types/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH;;;;GAIG;AACH,MAAM,UAAU,EAAE,CAAI,IAAO;IAC3B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI;KACL,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAkB,KAAQ;IAC3C,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK;KACN,CAAA;AACH,CAAC"}

package/dist/utils/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration management for MCP server
+ * Handles environment variables and configuration validation
+ */
+import type { ImageQuality } from '../types/mcp.js';
+import type { Result } from '../types/result.js';
+import { ConfigError } from './errors.js';
+/**
+ * Configuration interface
+ */
+export interface Config {
+    geminiApiKey: string;
+    imageOutputDir: string;
+    apiTimeout: number;
+    skipPromptEnhancement: boolean;
+    imageQuality: ImageQuality;
+}
+/**
+ * Validates the configuration
+ * @param config The configuration to validate
+ * @returns Result containing validated config or ConfigError
+ */
+export declare function validateConfig(config: Config): Result<Config, ConfigError>;
+/**
+ * Loads configuration from environment variables
+ * @returns Result containing config or ConfigError
+ */
+export declare function getConfig(): Result<Config, ConfigError>;
+//# sourceMappingURL=config.d.ts.map

package/dist/utils/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,qBAAqB,EAAE,OAAO,CAAA;IAC9B,YAAY,EAAE,YAAY,CAAA;CAC3B;AAUD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmD1E;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAUvD"}

package/dist/utils/config.js

@@ -0,0 +1,56 @@
+/**
+ * Configuration management for MCP server
+ * Handles environment variables and configuration validation
+ */
+import { IMAGE_QUALITY_VALUES } from '../types/mcp.js';
+import { Err, Ok } from '../types/result.js';
+import { ConfigError } from './errors.js';
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    imageOutputDir: './output',
+    apiTimeout: 30000, // 30 seconds
+};
+/**
+ * Validates the configuration
+ * @param config The configuration to validate
+ * @returns Result containing validated config or ConfigError
+ */
+export function validateConfig(config) {
+    // Validate GEMINI_API_KEY
+    if (!config.geminiApiKey || config.geminiApiKey.trim().length === 0) {
+        return Err(new ConfigError('GEMINI_API_KEY is required but not provided', 'Set GEMINI_API_KEY environment variable with your Google AI API key'));
+    }
+    if (config.geminiApiKey.length < 10) {
+        return Err(new ConfigError('GEMINI_API_KEY appears to be invalid - must be at least 10 characters', 'Set the GEMINI_API_KEY environment variable to your valid Google AI API key'));
+    }
+    // Validate apiTimeout
+    if (config.apiTimeout <= 0) {
+        return Err(new ConfigError('API timeout must be a positive number', 'Set a positive timeout value in milliseconds (e.g., 30000 for 30 seconds)'));
+    }
+    // Validate imageOutputDir (basic check - non-empty string)
+    if (!config.imageOutputDir || config.imageOutputDir.trim().length === 0) {
+        return Err(new ConfigError('IMAGE_OUTPUT_DIR cannot be empty', 'Set IMAGE_OUTPUT_DIR to a valid directory path'));
+    }
+    // Validate imageQuality
+    if (!IMAGE_QUALITY_VALUES.includes(config.imageQuality)) {
+        return Err(new ConfigError(`Invalid IMAGE_QUALITY value: "${config.imageQuality}". Valid options: ${IMAGE_QUALITY_VALUES.join(', ')}`, `Set IMAGE_QUALITY to one of: ${IMAGE_QUALITY_VALUES.join(', ')}`));
+    }
+    return Ok(config);
+}
+/**
+ * Loads configuration from environment variables
+ * @returns Result containing config or ConfigError
+ */
+export function getConfig() {
+    const config = {
+        geminiApiKey: process.env['GEMINI_API_KEY'] || '',
+        imageOutputDir: process.env['IMAGE_OUTPUT_DIR'] || DEFAULT_CONFIG.imageOutputDir,
+        apiTimeout: DEFAULT_CONFIG.apiTimeout,
+        skipPromptEnhancement: process.env['SKIP_PROMPT_ENHANCEMENT'] === 'true',
+        imageQuality: (process.env['IMAGE_QUALITY'] || 'fast'),
+    };
+    return validateConfig(config);
+}
+//# sourceMappingURL=config.js.map

package/dist/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAA;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAazC;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,cAAc,EAAE,UAAU;IAC1B,UAAU,EAAE,KAAK,EAAE,aAAa;CACxB,CAAA;AAEV;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,0BAA0B;IAC1B,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpE,OAAO,GAAG,CACR,IAAI,WAAW,CACb,6CAA6C,EAC7C,qEAAqE,CACtE,CACF,CAAA;IACH,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACpC,OAAO,GAAG,CACR,IAAI,WAAW,CACb,uEAAuE,EACvE,6EAA6E,CAC9E,CACF,CAAA;IACH,CAAC;IAED,sBAAsB;IACtB,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,GAAG,CACR,IAAI,WAAW,CACb,uCAAuC,EACvC,2EAA2E,CAC5E,CACF,CAAA;IACH,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,GAAG,CACR,IAAI,WAAW,CACb,kCAAkC,EAClC,gDAAgD,CACjD,CACF,CAAA;IACH,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,OAAO,GAAG,CACR,IAAI,WAAW,CACb,iCAAiC,MAAM,CAAC,YAAY,qBAAqB,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC1G,gCAAgC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClE,CACF,CAAA;IACH,CAAC;IAED,OAAO,EAAE,CAAC,MAAM,CAAC,CAAA;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAW;QACrB,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE;QACjD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,cAAc,CAAC,cAAc;QAChF,UAAU,EAAE,cAAc,CAAC,UAAU;QACrC,qBAAqB,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,KAAK,MAAM;QACxE,YAAY,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,MAAM,CAAiB;KACvE,CAAA;IAED,OAAO,cAAc,CAAC,MAAM,CAAC,CAAA;AAC/B,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Custom error classes for MCP server
+ * Provides specific error types with structured error codes and suggestions
+ */
+/**
+ * Structured error format for consistent error reporting
+ */
+export interface StructuredError {
+    code: string;
+    message: string;
+    suggestion: string;
+    timestamp: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Result type pattern for explicit error handling
+ */
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Base class for all application errors with structured error support
+ */
+export declare abstract class BaseError extends Error {
+    abstract readonly code: string;
+    abstract readonly suggestion: string;
+    readonly timestamp: string;
+    readonly context: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown>);
+    toStructuredError(): StructuredError;
+}
+/**
+ * Error for input validation failures
+ */
+export declare class InputValidationError extends BaseError {
+    readonly suggestion: string;
+    readonly code = "INPUT_VALIDATION_ERROR";
+    constructor(message: string, suggestion: string);
+}
+/**
+ * Error for file operation failures with intelligent suggestion system
+ */
+export declare class FileOperationError extends BaseError {
+    readonly code = "FILE_OPERATION_ERROR";
+    get suggestion(): string;
+}
+/**
+ * Error for Gemini API failures with intelligent suggestion system
+ */
+export declare class GeminiAPIError extends BaseError {
+    readonly code = "GEMINI_API_ERROR";
+    private customSuggestion?;
+    constructor(message: string, suggestionOrContext?: string | Record<string, unknown>, statusCodeOrContext?: number | Record<string, unknown>);
+    get suggestion(): string;
+}
+/**
+ * Error for network-related failures with intelligent suggestion system
+ */
+export declare class NetworkError extends BaseError {
+    readonly code = "NETWORK_ERROR";
+    private customSuggestion?;
+    constructor(message: string, suggestionOrContext?: string | Record<string, unknown>, causeOrContext?: Error | Record<string, unknown>);
+    get suggestion(): string;
+}
+/**
+ * Error for configuration failures
+ */
+export declare class ConfigError extends BaseError {
+    readonly suggestion: string;
+    readonly code = "CONFIG_ERROR";
+    constructor(message: string, suggestion: string);
+}
+/**
+ * Error for security violations and attacks with intelligent suggestion system
+ */
+export declare class SecurityError extends BaseError {
+    readonly code = "SECURITY_ERROR";
+    get suggestion(): string;
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAA;AAE3E;;GAEG;AACH,8BAAsB,SAAU,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAEzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9D,iBAAiB,IAAI,eAAe;CASrC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;aAK/B,UAAU,EAAE,MAAM;IAJpC,QAAQ,CAAC,IAAI,4BAA2B;gBAGtC,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM;CAIrC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,QAAQ,CAAC,IAAI,0BAAyB;IAEtC,IAAI,UAAU,IAAI,MAAM,CAgCvB;CACF;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,QAAQ,CAAC,IAAI,sBAAqB;IAClC,OAAO,CAAC,gBAAgB,CAAC,CAAQ;gBAG/B,OAAO,EAAE,MAAM,EACf,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBxD,IAAI,UAAU,IAAI,MAAM,CAmCvB;CACF;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,mBAAkB;IAC/B,OAAO,CAAC,gBAAgB,CAAC,CAAQ;gBAG/B,OAAO,EAAE,MAAM,EACf,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,cAAc,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBlD,IAAI,UAAU,IAAI,MAAM,CA2BvB;CACF;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,SAAS;aAKtB,UAAU,EAAE,MAAM;IAJpC,QAAQ,CAAC,IAAI,kBAAiB;gBAG5B,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM;CAIrC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,oBAAmB;IAEhC,IAAI,UAAU,IAAI,MAAM,CAwBvB;CACF"}

package/dist/utils/errors.js

@@ -0,0 +1,215 @@
+/**
+ * Custom error classes for MCP server
+ * Provides specific error types with structured error codes and suggestions
+ */
+import { GEMINI_MODELS } from '../types/mcp.js';
+/**
+ * Base class for all application errors with structured error support
+ */
+export class BaseError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.timestamp = new Date().toISOString();
+        this.context = context;
+    }
+    toStructuredError() {
+        return {
+            code: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+            timestamp: this.timestamp,
+            ...(this.context && { context: this.context }),
+        };
+    }
+}
+/**
+ * Error for input validation failures
+ */
+export class InputValidationError extends BaseError {
+    constructor(message, suggestion) {
+        super(message);
+        this.suggestion = suggestion;
+        this.code = 'INPUT_VALIDATION_ERROR';
+    }
+}
+/**
+ * Error for file operation failures with intelligent suggestion system
+ */
+export class FileOperationError extends BaseError {
+    constructor() {
+        super(...arguments);
+        this.code = 'FILE_OPERATION_ERROR';
+    }
+    get suggestion() {
+        const message = this.message.toLowerCase();
+        if (message.includes('permission') ||
+            message.includes('eacces') ||
+            message.includes('access denied')) {
+            return 'Check file and directory permissions for the output path';
+        }
+        if (message.includes('space') || message.includes('enospc') || message.includes('disk full')) {
+            return 'Free up disk space or choose a different output directory';
+        }
+        if (message.includes('enoent') ||
+            message.includes('no such file') ||
+            message.includes('not found')) {
+            return 'Ensure the output directory exists and is accessible';
+        }
+        if (message.includes('emfile') ||
+            message.includes('too many') ||
+            message.includes('file descriptor')) {
+            return 'Close unused files or restart the application to free file handles';
+        }
+        if (message.includes('readonly') || message.includes('read-only')) {
+            return 'Choose a writable directory for file output';
+        }
+        return 'Check file system permissions and available disk space';
+    }
+}
+/**
+ * Error for Gemini API failures with intelligent suggestion system
+ */
+export class GeminiAPIError extends BaseError {
+    constructor(message, suggestionOrContext, statusCodeOrContext) {
+        let context;
+        let statusCode;
+        // Handle backward compatibility with old constructor signature
+        if (typeof suggestionOrContext === 'string') {
+            // Old signature: (message, suggestion, statusCode?)
+            statusCode = typeof statusCodeOrContext === 'number' ? statusCodeOrContext : undefined;
+        }
+        else {
+            // New signature: (message, context?, statusCode?)
+            context = suggestionOrContext;
+            statusCode = typeof statusCodeOrContext === 'number' ? statusCodeOrContext : undefined;
+        }
+        super(message, context);
+        this.code = 'GEMINI_API_ERROR';
+        if (typeof suggestionOrContext === 'string') {
+            this.customSuggestion = suggestionOrContext;
+        }
+        Object.defineProperty(this, 'statusCode', { value: statusCode, writable: false });
+    }
+    get suggestion() {
+        // Use custom suggestion if provided (backward compatibility)
+        if (this.customSuggestion) {
+            return this.customSuggestion;
+        }
+        // Check if suggestion is in context
+        if (this.context &&
+            'suggestion' in this.context &&
+            typeof this.context['suggestion'] === 'string') {
+            return this.context['suggestion'];
+        }
+        // Otherwise use intelligent suggestion system
+        const message = this.message.toLowerCase();
+        if (message.includes('authentication') || message.includes('unauthorized')) {
+            return 'Check GEMINI_API_KEY environment variable and ensure it has proper permissions';
+        }
+        if (message.includes('rate limit') || message.includes('quota') || message.includes('429')) {
+            return 'Wait before retrying or upgrade API quota limits';
+        }
+        if (message.includes('model') || message.includes('access') || message.includes('permission')) {
+            return `Ensure you have access to the Gemini image generation models (${GEMINI_MODELS.FLASH} or ${GEMINI_MODELS.PRO})`;
+        }
+        if (message.includes('timeout') || message.includes('503') || message.includes('502')) {
+            return 'The service is temporarily unavailable. Please retry after a few moments';
+        }
+        if (message.includes('payload') || message.includes('request') || message.includes('400')) {
+            return 'Check request format and parameters according to API specification';
+        }
+        return 'Check API configuration and retry the request';
+    }
+}
+/**
+ * Error for network-related failures with intelligent suggestion system
+ */
+export class NetworkError extends BaseError {
+    constructor(message, suggestionOrContext, causeOrContext) {
+        let context;
+        let cause;
+        // Handle backward compatibility with old constructor signature
+        if (typeof suggestionOrContext === 'string') {
+            // Old signature: (message, suggestion, cause?)
+            cause = causeOrContext instanceof Error ? causeOrContext : undefined;
+        }
+        else {
+            // New signature: (message, context?, cause?)
+            context = suggestionOrContext;
+            cause = causeOrContext instanceof Error ? causeOrContext : undefined;
+        }
+        super(message, context);
+        this.code = 'NETWORK_ERROR';
+        if (typeof suggestionOrContext === 'string') {
+            this.customSuggestion = suggestionOrContext;
+        }
+        Object.defineProperty(this, 'cause', { value: cause, writable: false });
+    }
+    get suggestion() {
+        // Use custom suggestion if provided (backward compatibility)
+        if (this.customSuggestion) {
+            return this.customSuggestion;
+        }
+        // Otherwise use intelligent suggestion system
+        const message = this.message.toLowerCase();
+        const stack = this.stack?.toLowerCase() || '';
+        if (message.includes('timeout') || message.includes('etimedout')) {
+            return 'Check network connection stability and retry with higher timeout';
+        }
+        if (message.includes('dns') || message.includes('enotfound') || stack.includes('getaddrinfo')) {
+            return 'Check internet connection and DNS settings';
+        }
+        if (message.includes('econnrefused') || message.includes('connection refused')) {
+            return 'Service may be temporarily unavailable, please retry later';
+        }
+        if (message.includes('econnreset') || message.includes('connection reset')) {
+            return 'Network connection was interrupted, please retry';
+        }
+        if (message.includes('proxy') || message.includes('tunnel')) {
+            return 'Check proxy settings and firewall configuration';
+        }
+        return 'Check network connectivity and firewall settings';
+    }
+}
+/**
+ * Error for configuration failures
+ */
+export class ConfigError extends BaseError {
+    constructor(message, suggestion) {
+        super(message);
+        this.suggestion = suggestion;
+        this.code = 'CONFIG_ERROR';
+    }
+}
+/**
+ * Error for security violations and attacks with intelligent suggestion system
+ */
+export class SecurityError extends BaseError {
+    constructor() {
+        super(...arguments);
+        this.code = 'SECURITY_ERROR';
+    }
+    get suggestion() {
+        const message = this.message.toLowerCase();
+        if (message.includes('null byte')) {
+            return 'Ensure your request meets security requirements';
+        }
+        if (message.includes('path') || message.includes('traversal') || message.includes('..')) {
+            return 'Use valid file paths within allowed directories only';
+        }
+        if (message.includes('extension') ||
+            message.includes('filetype') ||
+            message.includes('format')) {
+            return 'Use supported file extensions: .png, .jpg, .jpeg, .webp';
+        }
+        if (message.includes('size') || message.includes('large') || message.includes('limit')) {
+            return 'Ensure file size is within allowed limits (max 10MB)';
+        }
+        if (message.includes('malicious') || message.includes('suspicious')) {
+            return 'The request contains potentially harmful content. Please review and try again';
+        }
+        return 'Ensure your request meets security requirements';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Logger utility for structured logging with sensitive data filtering
+ * Provides consistent logging format across the application
+ */
+/**
+ * Logger class for structured logging with sensitive data protection
+ */
+export declare class Logger {
+    private readonly sensitivePatterns;
+    private readonly urlPatterns;
+    private readonly filterPatterns;
+    private readonly keyBasedSensitivePatterns;
+    private currentTraceId?;
+    private currentSessionId?;
+    constructor();
+    /**
+     * Log a debug message (only in development mode)
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    debug(context: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an info message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    info(context: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    warn(context: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param error Optional error object
+     * @param metadata Optional metadata object
+     */
+    error(context: string, message: string, error?: Error, metadata?: Record<string, unknown>): void;
+    /**
+     * Core log writing method with structured format
+     */
+    private writeLog;
+    /**
+     * Sanitize string content by redacting sensitive information
+     * @param input String to sanitize
+     * @returns Sanitized string
+     */
+    private sanitizeString;
+    /**
+     * Sanitize metadata by redacting sensitive information
+     * @param metadata Metadata object to sanitize
+     * @returns Sanitized metadata object
+     */
+    private sanitizeMetadata;
+    /**
+     * Check if a key contains sensitive information
+     * @param key Object key to check
+     * @returns True if the key contains sensitive information
+     */
+    private isSensitiveKey;
+    /**
+     * Generate unique ID for trace/session tracking
+     */
+    private generateId;
+    /**
+     * Get or generate current trace ID
+     */
+    private getCurrentTraceId;
+    /**
+     * Get current session ID
+     */
+    private getCurrentSessionId;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAOjC;IAED,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE3B;IAED,OAAO,CAAC,QAAQ,CAAC,cAAc,CAK9B;IAED,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAQzC;IAED,OAAO,CAAC,cAAc,CAAC,CAAQ;IAC/B,OAAO,CAAC,gBAAgB,CAAC,CAAQ;;IAOjC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKjF;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhF;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhF;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAYhG;;OAEG;IACH,OAAO,CAAC,QAAQ;IAwBhB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA6BtB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAG5B"}