domain-search-mcp 1.0.0

package/dist/utils/cache.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * TTL-based In-Memory Cache.
+ *
+ * Simple but effective caching for domain availability and pricing.
+ * Reduces API calls and improves response times.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tldCache = exports.pricingCache = exports.domainCache = exports.TtlCache = void 0;
+exports.domainCacheKey = domainCacheKey;
+exports.tldCacheKey = tldCacheKey;
+exports.getOrCompute = getOrCompute;
+const config_js_1 = require("../config.js");
+const logger_js_1 = require("./logger.js");
+/**
+ * Default maximum cache size to prevent memory exhaustion.
+ * With ~1KB per entry average, 10000 entries ≈ 10MB max.
+ */
+const DEFAULT_MAX_CACHE_SIZE = 10000;
+/**
+ * Generic TTL cache with automatic expiration and size limits.
+ *
+ * SECURITY: Implements max size to prevent memory DoS attacks.
+ * When at capacity, evicts least-recently-used (LRU) entries.
+ */
+class TtlCache {
+    cache = new Map();
+    defaultTtlMs;
+    maxSize;
+    cleanupInterval = null;
+    constructor(defaultTtlSeconds = 300, maxSize = DEFAULT_MAX_CACHE_SIZE) {
+        this.defaultTtlMs = defaultTtlSeconds * 1000;
+        this.maxSize = maxSize;
+        // Clean up expired entries every minute
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+    }
+    /**
+     * Get a value from cache if it exists and hasn't expired.
+     * Updates lastAccessedAt for LRU tracking.
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        const now = Date.now();
+        // Check if expired
+        if (now > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Update last accessed time for LRU
+        entry.lastAccessedAt = now;
+        logger_js_1.logger.debug('Cache hit', { key, age_ms: now - entry.createdAt });
+        return entry.value;
+    }
+    /**
+     * Set a value in cache with optional custom TTL.
+     * Implements LRU eviction when cache is at capacity.
+     */
+    set(key, value, ttlMs) {
+        const now = Date.now();
+        const expiresAt = now + (ttlMs ?? this.defaultTtlMs);
+        // If key already exists, just update it
+        if (this.cache.has(key)) {
+            this.cache.set(key, {
+                value,
+                expiresAt,
+                createdAt: now,
+                lastAccessedAt: now,
+            });
+            return;
+        }
+        // If at capacity, evict least recently used entries
+        if (this.cache.size >= this.maxSize) {
+            this.evictLRU();
+        }
+        this.cache.set(key, {
+            value,
+            expiresAt,
+            createdAt: now,
+            lastAccessedAt: now,
+        });
+        logger_js_1.logger.debug('Cache set', {
+            key,
+            ttl_ms: expiresAt - now,
+            size: this.cache.size,
+        });
+    }
+    /**
+     * Evict least recently used entry.
+     * Called when cache is at capacity.
+     */
+    evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            if (entry.lastAccessedAt < oldestTime) {
+                oldestTime = entry.lastAccessedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            logger_js_1.logger.debug('Cache LRU eviction', { evicted_key: oldestKey });
+        }
+    }
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key) {
+        const value = this.get(key);
+        return value !== undefined;
+    }
+    /**
+     * Delete a specific key.
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries.
+     */
+    clear() {
+        this.cache.clear();
+        logger_js_1.logger.debug('Cache cleared');
+    }
+    /**
+     * Get the number of entries in cache.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Remove expired entries.
+     */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this.cache) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            logger_js_1.logger.debug('Cache cleanup', { removed, remaining: this.cache.size });
+        }
+    }
+    /**
+     * Stop the cleanup interval (for testing/shutdown).
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+    }
+}
+exports.TtlCache = TtlCache;
+/**
+ * Generate a cache key for domain availability.
+ */
+function domainCacheKey(domain, source) {
+    return `domain:${domain.toLowerCase()}:${source}`;
+}
+/**
+ * Generate a cache key for TLD info.
+ */
+function tldCacheKey(tld) {
+    return `tld:${tld.toLowerCase()}`;
+}
+/**
+ * Global cache instances.
+ */
+exports.domainCache = new TtlCache(config_js_1.config.cache.availabilityTtl);
+exports.pricingCache = new TtlCache(config_js_1.config.cache.pricingTtl);
+exports.tldCache = new TtlCache(86400); // 24 hours for TLD info
+/**
+ * Get or compute a domain result.
+ */
+async function getOrCompute(cache, key, compute, ttlMs) {
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+        return { value: cached, fromCache: true };
+    }
+    const value = await compute();
+    cache.set(key, value, ttlMs);
+    return { value, fromCache: false };
+}
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

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

package/dist/utils/errors.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Custom Error Classes for Domain Search MCP.
+ *
+ * These errors are designed to be:
+ * 1. User-friendly (clear messages for non-developers)
+ * 2. Actionable (suggest what to do next)
+ * 3. Informative (include context for debugging)
+ */
+/**
+ * Base error class for all domain search errors.
+ */
+export declare class DomainSearchError extends Error {
+    /** Machine-readable error code */
+    readonly code: string;
+    /** User-friendly message */
+    readonly userMessage: string;
+    /** Can this operation be retried? */
+    readonly retryable: boolean;
+    /** Suggested action for the user */
+    readonly suggestedAction?: string;
+    constructor(code: string, message: string, userMessage: string, options?: {
+        retryable?: boolean;
+        suggestedAction?: string;
+        cause?: Error;
+    });
+    /**
+     * Convert to a plain object for JSON responses.
+     */
+    toJSON(): object;
+}
+/**
+ * Error when a domain name is invalid.
+ */
+export declare class InvalidDomainError extends DomainSearchError {
+    constructor(domain: string, reason: string);
+}
+/**
+ * Error when a TLD is not supported.
+ */
+export declare class UnsupportedTldError extends DomainSearchError {
+    constructor(tld: string, availableTlds: string[]);
+}
+/**
+ * Error when an API rate limit is hit.
+ */
+export declare class RateLimitError extends DomainSearchError {
+    /** When to retry (Unix timestamp) */
+    readonly retryAfter?: number;
+    constructor(registrar: string, retryAfterSeconds?: number);
+}
+/**
+ * Error when a registrar API fails.
+ */
+export declare class RegistrarApiError extends DomainSearchError {
+    /** HTTP status code if available */
+    readonly statusCode?: number;
+    constructor(registrar: string, message: string, statusCode?: number, cause?: Error);
+}
+/**
+ * Error when API credentials are missing or invalid.
+ */
+export declare class AuthenticationError extends DomainSearchError {
+    constructor(registrar: string, reason?: string);
+}
+/**
+ * Error when no data source is available.
+ */
+export declare class NoSourceAvailableError extends DomainSearchError {
+    constructor(domain: string, triedSources: string[]);
+}
+/**
+ * Error when a network request times out.
+ */
+export declare class TimeoutError extends DomainSearchError {
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Error when a required configuration is missing.
+ */
+export declare class ConfigurationError extends DomainSearchError {
+    constructor(missing: string, howToFix: string);
+}
+/**
+ * Convert any error to a DomainSearchError.
+ */
+export declare function wrapError(error: unknown): DomainSearchError;
+//# 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;;;;;;;GAOG;AAEH;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;gBAGhC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,KAAK,CAAC;KACf;IAaH;;OAEG;IACH,MAAM,IAAI,MAAM;CAQjB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;gBAC3C,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAa3C;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;gBAC5C,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE;CAiBjD;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,iBAAiB;IACnD,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,SAAS,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM;CAiB1D;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;IACtD,oCAAoC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,KAAK;CAqBhB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;gBAC5C,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAY/C;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;gBAC/C,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE;CAanD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,iBAAiB;gBACrC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAYjD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;gBAC3C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAY9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CA2B3D"}

package/dist/utils/errors.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Custom Error Classes for Domain Search MCP.
+ *
+ * These errors are designed to be:
+ * 1. User-friendly (clear messages for non-developers)
+ * 2. Actionable (suggest what to do next)
+ * 3. Informative (include context for debugging)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationError = exports.TimeoutError = exports.NoSourceAvailableError = exports.AuthenticationError = exports.RegistrarApiError = exports.RateLimitError = exports.UnsupportedTldError = exports.InvalidDomainError = exports.DomainSearchError = void 0;
+exports.wrapError = wrapError;
+/**
+ * Base error class for all domain search errors.
+ */
+class DomainSearchError extends Error {
+    /** Machine-readable error code */
+    code;
+    /** User-friendly message */
+    userMessage;
+    /** Can this operation be retried? */
+    retryable;
+    /** Suggested action for the user */
+    suggestedAction;
+    constructor(code, message, userMessage, options) {
+        super(message);
+        this.name = 'DomainSearchError';
+        this.code = code;
+        this.userMessage = userMessage;
+        this.retryable = options?.retryable ?? false;
+        this.suggestedAction = options?.suggestedAction;
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+    }
+    /**
+     * Convert to a plain object for JSON responses.
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.userMessage,
+            retryable: this.retryable,
+            suggestedAction: this.suggestedAction,
+        };
+    }
+}
+exports.DomainSearchError = DomainSearchError;
+/**
+ * Error when a domain name is invalid.
+ */
+class InvalidDomainError extends DomainSearchError {
+    constructor(domain, reason) {
+        super('INVALID_DOMAIN', `Invalid domain: ${domain} - ${reason}`, `The domain "${domain}" is not valid: ${reason}`, {
+            retryable: false,
+            suggestedAction: 'Check the domain name for typos or invalid characters.',
+        });
+        this.name = 'InvalidDomainError';
+    }
+}
+exports.InvalidDomainError = InvalidDomainError;
+/**
+ * Error when a TLD is not supported.
+ */
+class UnsupportedTldError extends DomainSearchError {
+    constructor(tld, availableTlds) {
+        const suggestion = availableTlds.length > 0
+            ? `Try one of these: ${availableTlds.slice(0, 5).join(', ')}`
+            : 'Contact support for TLD availability.';
+        super('UNSUPPORTED_TLD', `TLD not supported: .${tld}`, `The TLD ".${tld}" is not supported for searching.`, {
+            retryable: false,
+            suggestedAction: suggestion,
+        });
+        this.name = 'UnsupportedTldError';
+    }
+}
+exports.UnsupportedTldError = UnsupportedTldError;
+/**
+ * Error when an API rate limit is hit.
+ */
+class RateLimitError extends DomainSearchError {
+    /** When to retry (Unix timestamp) */
+    retryAfter;
+    constructor(registrar, retryAfterSeconds) {
+        super('RATE_LIMIT', `Rate limit hit for ${registrar}`, `Too many requests to ${registrar}. Please slow down.`, {
+            retryable: true,
+            suggestedAction: retryAfterSeconds
+                ? `Wait ${retryAfterSeconds} seconds before trying again.`
+                : 'Wait a moment and try again, or check fewer domains at once.',
+        });
+        this.name = 'RateLimitError';
+        if (retryAfterSeconds) {
+            this.retryAfter = Date.now() + retryAfterSeconds * 1000;
+        }
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Error when a registrar API fails.
+ */
+class RegistrarApiError extends DomainSearchError {
+    /** HTTP status code if available */
+    statusCode;
+    constructor(registrar, message, statusCode, cause) {
+        const isServerError = statusCode !== undefined && statusCode >= 500;
+        super('REGISTRAR_API_ERROR', `${registrar} API error: ${message}`, isServerError
+            ? `${registrar} is experiencing issues. We'll try another source.`
+            : `Could not check with ${registrar}: ${message}`, {
+            retryable: isServerError,
+            suggestedAction: isServerError
+                ? 'The system will automatically try alternative sources.'
+                : `Check your ${registrar} API configuration.`,
+            cause,
+        });
+        this.name = 'RegistrarApiError';
+        this.statusCode = statusCode;
+    }
+}
+exports.RegistrarApiError = RegistrarApiError;
+/**
+ * Error when API credentials are missing or invalid.
+ */
+class AuthenticationError extends DomainSearchError {
+    constructor(registrar, reason) {
+        super('AUTH_ERROR', `Authentication failed for ${registrar}: ${reason || 'Invalid credentials'}`, `Could not authenticate with ${registrar}.`, {
+            retryable: false,
+            suggestedAction: `Check your ${registrar.toUpperCase()}_API_KEY and ${registrar.toUpperCase()}_API_SECRET in your .env file.`,
+        });
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Error when no data source is available.
+ */
+class NoSourceAvailableError extends DomainSearchError {
+    constructor(domain, triedSources) {
+        super('NO_SOURCE_AVAILABLE', `No source available for ${domain}. Tried: ${triedSources.join(', ')}`, `Could not check availability for "${domain}". All sources failed.`, {
+            retryable: true,
+            suggestedAction: 'Try again in a few minutes, or check the domain manually at a registrar website.',
+        });
+        this.name = 'NoSourceAvailableError';
+    }
+}
+exports.NoSourceAvailableError = NoSourceAvailableError;
+/**
+ * Error when a network request times out.
+ */
+class TimeoutError extends DomainSearchError {
+    constructor(operation, timeoutMs) {
+        super('TIMEOUT', `Operation timed out: ${operation} (${timeoutMs}ms)`, `The request took too long to complete.`, {
+            retryable: true,
+            suggestedAction: 'Try again - this might be a temporary network issue.',
+        });
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Error when a required configuration is missing.
+ */
+class ConfigurationError extends DomainSearchError {
+    constructor(missing, howToFix) {
+        super('CONFIG_ERROR', `Missing configuration: ${missing}`, `Server configuration is incomplete.`, {
+            retryable: false,
+            suggestedAction: howToFix,
+        });
+        this.name = 'ConfigurationError';
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Convert any error to a DomainSearchError.
+ */
+function wrapError(error) {
+    if (error instanceof DomainSearchError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new DomainSearchError('UNKNOWN_ERROR', error.message, 'An unexpected error occurred.', {
+            retryable: true,
+            suggestedAction: 'Try again or contact support if the issue persists.',
+            cause: error,
+        });
+    }
+    return new DomainSearchError('UNKNOWN_ERROR', String(error), 'An unexpected error occurred.', {
+        retryable: true,
+        suggestedAction: 'Try again or contact support if the issue persists.',
+    });
+}
+//# 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":";AAAA;;;;;;;GAOG;;;AAmOH,8BA2BC;AA5PD;;GAEG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IAC1C,kCAAkC;IACzB,IAAI,CAAS;IACtB,4BAA4B;IACnB,WAAW,CAAS;IAC7B,qCAAqC;IAC5B,SAAS,CAAU;IAC5B,oCAAoC;IAC3B,eAAe,CAAU;IAElC,YACE,IAAY,EACZ,OAAe,EACf,WAAmB,EACnB,OAIC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,eAAe,CAAC;QAChD,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC7B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,WAAW;YACzB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC;IACJ,CAAC;CACF;AA1CD,8CA0CC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,iBAAiB;IACvD,YAAY,MAAc,EAAE,MAAc;QACxC,KAAK,CACH,gBAAgB,EAChB,mBAAmB,MAAM,MAAM,MAAM,EAAE,EACvC,eAAe,MAAM,mBAAmB,MAAM,EAAE,EAChD;YACE,SAAS,EAAE,KAAK;YAChB,eAAe,EACb,wDAAwD;SAC3D,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAdD,gDAcC;AAED;;GAEG;AACH,MAAa,mBAAoB,SAAQ,iBAAiB;IACxD,YAAY,GAAW,EAAE,aAAuB;QAC9C,MAAM,UAAU,GACd,aAAa,CAAC,MAAM,GAAG,CAAC;YACtB,CAAC,CAAC,qBAAqB,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAC7D,CAAC,CAAC,uCAAuC,CAAC;QAE9C,KAAK,CACH,iBAAiB,EACjB,uBAAuB,GAAG,EAAE,EAC5B,aAAa,GAAG,mCAAmC,EACnD;YACE,SAAS,EAAE,KAAK;YAChB,eAAe,EAAE,UAAU;SAC5B,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAlBD,kDAkBC;AAED;;GAEG;AACH,MAAa,cAAe,SAAQ,iBAAiB;IACnD,qCAAqC;IAC5B,UAAU,CAAU;IAE7B,YAAY,SAAiB,EAAE,iBAA0B;QACvD,KAAK,CACH,YAAY,EACZ,sBAAsB,SAAS,EAAE,EACjC,wBAAwB,SAAS,qBAAqB,EACtD;YACE,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,iBAAiB;gBAChC,CAAC,CAAC,QAAQ,iBAAiB,+BAA+B;gBAC1D,CAAC,CAAC,8DAA8D;SACnE,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,iBAAiB,EAAE,CAAC;YACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,iBAAiB,GAAG,IAAI,CAAC;QAC1D,CAAC;IACH,CAAC;CACF;AArBD,wCAqBC;AAED;;GAEG;AACH,MAAa,iBAAkB,SAAQ,iBAAiB;IACtD,oCAAoC;IAC3B,UAAU,CAAU;IAE7B,YACE,SAAiB,EACjB,OAAe,EACf,UAAmB,EACnB,KAAa;QAEb,MAAM,aAAa,GAAG,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,GAAG,CAAC;QAEpE,KAAK,CACH,qBAAqB,EACrB,GAAG,SAAS,eAAe,OAAO,EAAE,EACpC,aAAa;YACX,CAAC,CAAC,GAAG,SAAS,oDAAoD;YAClE,CAAC,CAAC,wBAAwB,SAAS,KAAK,OAAO,EAAE,EACnD;YACE,SAAS,EAAE,aAAa;YACxB,eAAe,EAAE,aAAa;gBAC5B,CAAC,CAAC,wDAAwD;gBAC1D,CAAC,CAAC,cAAc,SAAS,qBAAqB;YAChD,KAAK;SACN,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AA7BD,8CA6BC;AAED;;GAEG;AACH,MAAa,mBAAoB,SAAQ,iBAAiB;IACxD,YAAY,SAAiB,EAAE,MAAe;QAC5C,KAAK,CACH,YAAY,EACZ,6BAA6B,SAAS,KAAK,MAAM,IAAI,qBAAqB,EAAE,EAC5E,+BAA+B,SAAS,GAAG,EAC3C;YACE,SAAS,EAAE,KAAK;YAChB,eAAe,EAAE,cAAc,SAAS,CAAC,WAAW,EAAE,gBAAgB,SAAS,CAAC,WAAW,EAAE,gCAAgC;SAC9H,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAbD,kDAaC;AAED;;GAEG;AACH,MAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,YAAY,MAAc,EAAE,YAAsB;QAChD,KAAK,CACH,qBAAqB,EACrB,2BAA2B,MAAM,YAAY,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACtE,qCAAqC,MAAM,wBAAwB,EACnE;YACE,SAAS,EAAE,IAAI;YACf,eAAe,EACb,kFAAkF;SACrF,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAdD,wDAcC;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,iBAAiB;IACjD,YAAY,SAAiB,EAAE,SAAiB;QAC9C,KAAK,CACH,SAAS,EACT,wBAAwB,SAAS,KAAK,SAAS,KAAK,EACpD,wCAAwC,EACxC;YACE,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,sDAAsD;SACxE,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAbD,oCAaC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,iBAAiB;IACvD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CACH,cAAc,EACd,0BAA0B,OAAO,EAAE,EACnC,qCAAqC,EACrC;YACE,SAAS,EAAE,KAAK;YAChB,eAAe,EAAE,QAAQ;SAC1B,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAbD,gDAaC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,KAAc;IACtC,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,iBAAiB,CAC1B,eAAe,EACf,KAAK,CAAC,OAAO,EACb,+BAA+B,EAC/B;YACE,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,qDAAqD;YACtE,KAAK,EAAE,KAAK;SACb,CACF,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,iBAAiB,CAC1B,eAAe,EACf,MAAM,CAAC,KAAK,CAAC,EACb,+BAA+B,EAC/B;QACE,SAAS,EAAE,IAAI;QACf,eAAe,EAAE,qDAAqD;KACvE,CACF,CAAC;AACJ,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility Exports.
+ */
+export * from './logger.js';
+export * from './errors.js';
+export * from './cache.js';
+export * from './validators.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Utility Exports.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./cache.js"), exports);
+__exportStar(require("./validators.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,8CAA4B;AAC5B,8CAA4B;AAC5B,6CAA2B;AAC3B,kDAAgC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Structured JSON Logger with Secret Masking.
+ *
+ * - Outputs JSON for easy parsing
+ * - Masks API keys and secrets automatically
+ * - Includes request IDs for tracing
+ */
+/**
+ * Generate a unique request ID.
+ */
+export declare function generateRequestId(): string;
+export declare function setRequestId(id: string): void;
+export declare function clearRequestId(): void;
+/**
+ * Logger instance with convenience methods.
+ */
+export declare const logger: {
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    /**
+     * Log an error with stack trace.
+     */
+    logError: (message: string, error: Error, data?: Record<string, unknown>) => void;
+};
+//# 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;;;;;;GAMG;AAiFH;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAOD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAgCD;;GAEG;AACH,eAAO,MAAM,MAAM;qBACA,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBAEvC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBAEtC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;qBAErC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAGvD;;OAEG;wBACiB,MAAM,SAAS,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQzE,CAAC"}