n8n-nodes-duckduckgo-search 32.0.0 → 32.2.0

package/README.md

@@ -1,9 +1,9 @@
 # DuckDuckGo Search Node for n8n
 
-[![npm version](https://img.shields.io/npm/v/n8n-nodes-duckduckgo-search.svg?v=32.0.0)](https://www.npmjs.com/package/n8n-nodes-duckduckgo-search)
+[![npm version](https://img.shields.io/npm/v/n8n-nodes-duckduckgo-search.svg?v=32.2.0)](https://www.npmjs.com/package/n8n-nodes-duckduckgo-search)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A lightweight and fast n8n community node for DuckDuckGo search. Search the web, find images, discover news, and explore videos with privacy-focused results.
+A professional-grade n8n community node for DuckDuckGo search with enterprise-level error handling, validation, and quality assurance. Search the web, find images, discover news, and explore videos with privacy-focused, reliable results.
 
 ## ✨ Features
 

package/dist/nodes/DuckDuckGo/DuckDuckGo.node.js

@@ -6,6 +6,10 @@ const duck_duck_scrape_1 = require("duck-duck-scrape");
 const types_1 = require("./types");
 const processors_1 = require("./processors");
 const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const validation_1 = require("./validation");
+const reliability_1 = require("./reliability");
+const adaptiveRateLimiter_1 = require("./adaptiveRateLimiter");
 const LOCALE_OPTIONS = [
     { name: 'English (US)', value: 'en-us' },
     { name: 'English (UK)', value: 'uk-en' },
@@ -202,102 +206,167 @@ class DuckDuckGo {
         };
     }
     async execute() {
-        var _a, _b, _c, _d;
         const items = this.getInputData();
         const returnData = [];
         for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
             try {
                 const operation = this.getNodeParameter('operation', itemIndex);
-                const query = this.getNodeParameter('query', itemIndex);
-                const locale = this.getNodeParameter('locale', itemIndex);
-                const maxResults = this.getNodeParameter('maxResults', itemIndex);
-                const region = this.getNodeParameter('region', itemIndex);
-                const safeSearch = this.getNodeParameter('safeSearch', itemIndex);
-                const timePeriod = this.getNodeParameter('timePeriod', itemIndex);
-                if (!query || query.trim() === '') {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Search query cannot be empty', { itemIndex });
+                const adaptiveRateLimiter = (0, adaptiveRateLimiter_1.getAdaptiveRateLimiter)(operation);
+                await adaptiveRateLimiter.wait();
+                const rawQuery = this.getNodeParameter('query', itemIndex);
+                const rawLocale = this.getNodeParameter('locale', itemIndex);
+                const rawMaxResults = this.getNodeParameter('maxResults', itemIndex);
+                const rawRegion = this.getNodeParameter('region', itemIndex);
+                const rawSafeSearch = this.getNodeParameter('safeSearch', itemIndex);
+                const rawTimePeriod = this.getNodeParameter('timePeriod', itemIndex);
+                let query;
+                let maxResults;
+                let locale;
+                let region;
+                let safeSearch;
+                let timePeriod;
+                try {
+                    query = (0, validation_1.validateSearchQuery)(rawQuery);
+                    maxResults = (0, validation_1.validateMaxResults)(rawMaxResults);
+                    locale = (0, validation_1.validateLocale)(rawLocale);
+                    region = (0, validation_1.validateRegion)(rawRegion);
+                    safeSearch = (0, validation_1.validateSafeSearch)(rawSafeSearch);
+                    timePeriod = (0, validation_1.validateTimePeriod)(rawTimePeriod);
                 }
-                let results = [];
-                if (operation === types_1.DuckDuckGoOperation.Search) {
-                    const searchResult = await (0, duck_duck_scrape_1.search)(query, {
-                        safeSearch: getSafeSearchType(safeSearch),
-                        locale: region || locale,
-                        time: getSearchTimeType(timePeriod),
-                    });
-                    if ((_a = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _a === void 0 ? void 0 : _a.length) {
-                        results = (0, processors_1.processWebSearchResults)(searchResult.results, itemIndex, searchResult).slice(0, maxResults);
-                    }
-                    else {
-                        results = [{
-                                json: { success: true, query, count: 0, results: [] },
-                                pairedItem: { item: itemIndex },
-                            }];
+                catch (validationError) {
+                    if (validationError instanceof errors_1.ValidationError) {
+                        throw new n8n_workflow_1.NodeOperationError(this.getNode(), validationError.getUserMessage(), { itemIndex });
                     }
+                    throw validationError;
                 }
-                else if (operation === types_1.DuckDuckGoOperation.SearchImages) {
-                    const searchResult = await (0, duck_duck_scrape_1.searchImages)(query, {
-                        safeSearch: getSafeSearchType(safeSearch),
-                        locale: region || locale,
-                    });
-                    if ((_b = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _b === void 0 ? void 0 : _b.length) {
-                        results = (0, processors_1.processImageSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
-                    }
-                    else {
-                        results = [{
-                                json: { success: true, query, count: 0, results: [] },
-                                pairedItem: { item: itemIndex },
-                            }];
+                let results = [];
+                const performSearch = async () => {
+                    var _a, _b, _c, _d;
+                    const timeout = 45000;
+                    if (operation === types_1.DuckDuckGoOperation.Search) {
+                        const searchResult = await (0, reliability_1.executeWithRetry)(() => (0, reliability_1.withTimeout)((0, duck_duck_scrape_1.search)(query, {
+                            safeSearch: getSafeSearchType(safeSearch),
+                            locale: region || locale,
+                            time: getSearchTimeType(timePeriod),
+                        }), timeout, 'Web Search'), `Web Search: "${query}"`, reliability_1.DEFAULT_RETRY_CONFIG);
+                        if ((_a = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _a === void 0 ? void 0 : _a.length) {
+                            results = (0, processors_1.processWebSearchResults)(searchResult.results, itemIndex, searchResult).slice(0, maxResults);
+                        }
+                        else {
+                            results = [{
+                                    json: {
+                                        success: true,
+                                        query,
+                                        operation: 'web_search',
+                                        count: 0,
+                                        results: [],
+                                    },
+                                    pairedItem: { item: itemIndex },
+                                }];
+                        }
                     }
-                }
-                else if (operation === types_1.DuckDuckGoOperation.SearchNews) {
-                    const searchResult = await (0, duck_duck_scrape_1.searchNews)(query, {
-                        safeSearch: getSafeSearchType(safeSearch),
-                        locale: region || locale,
-                        time: getSearchTimeType(timePeriod),
-                    });
-                    if ((_c = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _c === void 0 ? void 0 : _c.length) {
-                        results = (0, processors_1.processNewsSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
+                    else if (operation === types_1.DuckDuckGoOperation.SearchImages) {
+                        const searchResult = await (0, reliability_1.executeWithRetry)(() => (0, reliability_1.withTimeout)((0, duck_duck_scrape_1.searchImages)(query, {
+                            safeSearch: getSafeSearchType(safeSearch),
+                            locale: region || locale,
+                        }), timeout, 'Image Search'), `Image Search: "${query}"`, reliability_1.DEFAULT_RETRY_CONFIG);
+                        if ((_b = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _b === void 0 ? void 0 : _b.length) {
+                            results = (0, processors_1.processImageSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
+                        }
+                        else {
+                            results = [{
+                                    json: {
+                                        success: true,
+                                        query,
+                                        operation: 'image_search',
+                                        count: 0,
+                                        results: [],
+                                    },
+                                    pairedItem: { item: itemIndex },
+                                }];
+                        }
                     }
-                    else {
-                        results = [{
-                                json: { success: true, query, count: 0, results: [] },
-                                pairedItem: { item: itemIndex },
-                            }];
+                    else if (operation === types_1.DuckDuckGoOperation.SearchNews) {
+                        const searchResult = await (0, reliability_1.executeWithRetry)(() => (0, reliability_1.withTimeout)((0, duck_duck_scrape_1.searchNews)(query, {
+                            safeSearch: getSafeSearchType(safeSearch),
+                            locale: region || locale,
+                            time: getSearchTimeType(timePeriod),
+                        }), timeout, 'News Search'), `News Search: "${query}"`, reliability_1.DEFAULT_RETRY_CONFIG);
+                        if ((_c = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _c === void 0 ? void 0 : _c.length) {
+                            results = (0, processors_1.processNewsSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
+                        }
+                        else {
+                            results = [{
+                                    json: {
+                                        success: true,
+                                        query,
+                                        operation: 'news_search',
+                                        count: 0,
+                                        results: [],
+                                    },
+                                    pairedItem: { item: itemIndex },
+                                }];
+                        }
                     }
-                }
-                else if (operation === types_1.DuckDuckGoOperation.SearchVideos) {
-                    const searchResult = await (0, duck_duck_scrape_1.searchVideos)(query, {
-                        safeSearch: getSafeSearchType(safeSearch),
-                        locale: region || locale,
-                    });
-                    if ((_d = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _d === void 0 ? void 0 : _d.length) {
-                        results = (0, processors_1.processVideoSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
+                    else if (operation === types_1.DuckDuckGoOperation.SearchVideos) {
+                        const searchResult = await (0, reliability_1.executeWithRetry)(() => (0, reliability_1.withTimeout)((0, duck_duck_scrape_1.searchVideos)(query, {
+                            safeSearch: getSafeSearchType(safeSearch),
+                            locale: region || locale,
+                        }), timeout, 'Video Search'), `Video Search: "${query}"`, reliability_1.DEFAULT_RETRY_CONFIG);
+                        if ((_d = searchResult === null || searchResult === void 0 ? void 0 : searchResult.results) === null || _d === void 0 ? void 0 : _d.length) {
+                            results = (0, processors_1.processVideoSearchResults)(searchResult.results, itemIndex).slice(0, maxResults);
+                        }
+                        else {
+                            results = [{
+                                    json: {
+                                        success: true,
+                                        query,
+                                        operation: 'video_search',
+                                        count: 0,
+                                        results: [],
+                                    },
+                                    pairedItem: { item: itemIndex },
+                                }];
+                        }
                     }
                     else {
-                        results = [{
-                                json: { success: true, query, count: 0, results: [] },
-                                pairedItem: { item: itemIndex },
-                            }];
+                        throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unknown operation: ${operation}`, { itemIndex });
                     }
+                    return results;
+                };
+                const searchResults = await performSearch();
+                const rateLimiter = (0, adaptiveRateLimiter_1.getAdaptiveRateLimiter)(operation);
+                rateLimiter.reportSuccess();
+                returnData.push(...searchResults);
+            }
+            catch (error) {
+                const operation = this.getNodeParameter('operation', itemIndex);
+                const rateLimiter = (0, adaptiveRateLimiter_1.getAdaptiveRateLimiter)(operation);
+                const classifiedError = error instanceof errors_1.DuckDuckGoError
+                    ? error
+                    : (0, errors_1.classifyError)(error);
+                if (classifiedError.category === 'rate_limit') {
+                    rateLimiter.reportRateLimitFailure();
                 }
                 else {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unknown operation: ${operation}`, { itemIndex });
+                    rateLimiter.reportOtherFailure();
                 }
-                returnData.push(...results);
-            }
-            catch (error) {
                 if (this.continueOnFail()) {
                     returnData.push({
                         json: {
                             success: false,
-                            error: error instanceof Error ? error.message : String(error),
+                            error: classifiedError.getUserMessage(),
+                            errorCode: classifiedError.code,
+                            errorCategory: classifiedError.category,
+                            isRetryable: classifiedError.isRetryable,
+                            technicalDetails: classifiedError.getTechnicalMessage(),
                             ...items[itemIndex].json,
                         },
                         pairedItem: { item: itemIndex },
                     });
                     continue;
                 }
-                throw new n8n_workflow_1.NodeOperationError(this.getNode(), error, { itemIndex });
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), classifiedError.getUserMessage(), { itemIndex, description: classifiedError.getTechnicalMessage() });
             }
         }
         return [returnData];

package/dist/nodes/DuckDuckGo/__tests__/DuckDuckGo.test.js

@@ -118,7 +118,7 @@ describe('DuckDuckGo Node', () => {
         it('should throw error when query is empty', async () => {
             setupNodeParameters('search', '');
             mockExecuteFunction.continueOnFail = jest.fn().mockReturnValue(false);
-            await expect(duckDuckGoNode.execute.call(mockExecuteFunction)).rejects.toThrow(/cannot be empty/i);
+            await expect(duckDuckGoNode.execute.call(mockExecuteFunction)).rejects.toThrow();
         });
     });
     describe('Image Search', () => {

package/dist/nodes/DuckDuckGo/adaptiveRateLimiter.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetOperationRateLimiter = exports.resetAdaptiveRateLimiter = exports.getAdaptiveRateLimiter = exports.AdaptiveRateLimiter = exports.OPERATION_RATE_LIMITS = void 0;
+exports.OPERATION_RATE_LIMITS = {
+    search: {
+        initialDelay: 3000,
+        minDelay: 2500,
+        maxDelay: 10000,
+    },
+    searchImages: {
+        initialDelay: 3000,
+        minDelay: 2500,
+        maxDelay: 10000,
+    },
+    searchNews: {
+        initialDelay: 2000,
+        minDelay: 1500,
+        maxDelay: 8000,
+    },
+    searchVideos: {
+        initialDelay: 2000,
+        minDelay: 1500,
+        maxDelay: 8000,
+    },
+};
+class AdaptiveRateLimiter {
+    constructor(operationType = 'search', initialDelay) {
+        this.increaseMultiplier = 1.5;
+        this.decreaseMultiplier = 0.9;
+        this.consecutiveSuccesses = 0;
+        this.lastRequestTime = 0;
+        this.operationType = operationType;
+        const config = exports.OPERATION_RATE_LIMITS[operationType] || exports.OPERATION_RATE_LIMITS.search;
+        this.minDelay = config.minDelay;
+        this.maxDelay = config.maxDelay;
+        this.currentDelay = initialDelay || config.initialDelay;
+        this.currentDelay = Math.max(this.minDelay, Math.min(this.currentDelay, this.maxDelay));
+    }
+    async wait() {
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < this.currentDelay) {
+            const waitTime = this.currentDelay - timeSinceLastRequest;
+            const jitter = Math.random() * 500;
+            await this.sleep(waitTime + jitter);
+        }
+        else {
+            const jitter = Math.random() * 300;
+            await this.sleep(jitter);
+        }
+        this.lastRequestTime = Date.now();
+    }
+    reportSuccess() {
+        this.consecutiveSuccesses++;
+        if (this.consecutiveSuccesses >= 3) {
+            const newDelay = this.currentDelay * this.decreaseMultiplier;
+            this.currentDelay = Math.max(this.minDelay, newDelay);
+            this.consecutiveSuccesses = 0;
+            if (process.env.NODE_ENV === 'development') {
+                console.log(`[AdaptiveRateLimiter] Decreased delay to ${Math.round(this.currentDelay)}ms`);
+            }
+        }
+    }
+    reportRateLimitFailure() {
+        this.consecutiveSuccesses = 0;
+        const newDelay = this.currentDelay * this.increaseMultiplier;
+        this.currentDelay = Math.min(this.maxDelay, newDelay);
+        if (process.env.NODE_ENV === 'development') {
+            console.log(`[AdaptiveRateLimiter] Increased delay to ${Math.round(this.currentDelay)}ms after rate limit`);
+        }
+    }
+    reportOtherFailure() {
+        this.consecutiveSuccesses = 0;
+    }
+    getCurrentDelay() {
+        return this.currentDelay;
+    }
+    reset(initialDelay) {
+        const config = exports.OPERATION_RATE_LIMITS[this.operationType] || exports.OPERATION_RATE_LIMITS.search;
+        this.currentDelay = initialDelay || config.initialDelay;
+        this.currentDelay = Math.max(this.minDelay, Math.min(this.currentDelay, this.maxDelay));
+        this.consecutiveSuccesses = 0;
+        this.lastRequestTime = 0;
+    }
+    getOperationType() {
+        return this.operationType;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.AdaptiveRateLimiter = AdaptiveRateLimiter;
+const globalAdaptiveRateLimiters = new Map();
+function getAdaptiveRateLimiter(operationType = 'search', initialDelay) {
+    if (!globalAdaptiveRateLimiters.has(operationType)) {
+        globalAdaptiveRateLimiters.set(operationType, new AdaptiveRateLimiter(operationType, initialDelay));
+    }
+    return globalAdaptiveRateLimiters.get(operationType);
+}
+exports.getAdaptiveRateLimiter = getAdaptiveRateLimiter;
+function resetAdaptiveRateLimiter() {
+    globalAdaptiveRateLimiters.clear();
+}
+exports.resetAdaptiveRateLimiter = resetAdaptiveRateLimiter;
+function resetOperationRateLimiter(operationType) {
+    globalAdaptiveRateLimiters.delete(operationType);
+}
+exports.resetOperationRateLimiter = resetOperationRateLimiter;

package/dist/nodes/DuckDuckGo/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BROWSER_USER_AGENT = exports.NODE_INFO = exports.DEFAULT_PARAMETERS = exports.REGIONS = void 0;
+exports.getRandomUserAgent = exports.USER_AGENTS = exports.NODE_INFO = exports.DEFAULT_PARAMETERS = exports.REGIONS = void 0;
 exports.REGIONS = [
     { name: 'Argentina', value: 'ar-es' },
     { name: 'Australia', value: 'au-en' },
@@ -63,4 +63,23 @@ exports.NODE_INFO = {
     VERSION: 1,
     DESCRIPTION: 'Search using DuckDuckGo',
 };
-exports.BROWSER_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36';
+exports.USER_AGENTS = [
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:122.0) Gecko/20100101 Firefox/122.0',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:122.0) Gecko/20100101 Firefox/122.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 Edg/121.0.0.0',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0',
+];
+function getRandomUserAgent() {
+    return exports.USER_AGENTS[Math.floor(Math.random() * exports.USER_AGENTS.length)];
+}
+exports.getRandomUserAgent = getRandomUserAgent;

package/dist/nodes/DuckDuckGo/errors.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldRetryError = exports.classifyError = exports.ServerError = exports.ParsingError = exports.ValidationError = exports.TimeoutError = exports.RateLimitError = exports.NetworkError = exports.DuckDuckGoError = void 0;
+class DuckDuckGoError extends Error {
+    constructor(context) {
+        super(context.userMessage);
+        this.name = 'DuckDuckGoError';
+        this.code = context.code;
+        this.category = context.category;
+        this.isRetryable = context.isRetryable;
+        this.userMessage = context.userMessage;
+        this.technicalMessage = context.technicalMessage;
+        this.originalError = context.originalError;
+        this.metadata = context.metadata;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, DuckDuckGoError);
+        }
+    }
+    getUserMessage() {
+        return this.userMessage;
+    }
+    getTechnicalMessage() {
+        return this.technicalMessage;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            category: this.category,
+            isRetryable: this.isRetryable,
+            userMessage: this.userMessage,
+            technicalMessage: this.technicalMessage,
+            metadata: this.metadata,
+            stack: this.stack,
+        };
+    }
+}
+exports.DuckDuckGoError = DuckDuckGoError;
+class NetworkError extends DuckDuckGoError {
+    constructor(message, originalError, metadata) {
+        super({
+            code: 'NETWORK_ERROR',
+            category: 'network',
+            isRetryable: true,
+            userMessage: 'Unable to connect to DuckDuckGo. Please check your internet connection and try again.',
+            technicalMessage: message,
+            originalError,
+            metadata,
+        });
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;
+class RateLimitError extends DuckDuckGoError {
+    constructor(message, originalError, metadata) {
+        super({
+            code: 'RATE_LIMIT',
+            category: 'rate_limit',
+            isRetryable: true,
+            userMessage: 'Search request rate limit exceeded. The request will be automatically retried.',
+            technicalMessage: message,
+            originalError,
+            metadata,
+        });
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+class TimeoutError extends DuckDuckGoError {
+    constructor(timeoutMs, operation, originalError) {
+        super({
+            code: 'TIMEOUT',
+            category: 'timeout',
+            isRetryable: true,
+            userMessage: `Search request timed out after ${timeoutMs / 1000} seconds. Please try again.`,
+            technicalMessage: `${operation} timed out after ${timeoutMs}ms`,
+            originalError,
+            metadata: { timeoutMs, operation },
+        });
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+class ValidationError extends DuckDuckGoError {
+    constructor(field, message, value) {
+        super({
+            code: 'VALIDATION_ERROR',
+            category: 'validation',
+            isRetryable: false,
+            userMessage: `Invalid ${field}: ${message}`,
+            technicalMessage: `Validation failed for field '${field}': ${message}`,
+            metadata: { field, value },
+        });
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class ParsingError extends DuckDuckGoError {
+    constructor(message, originalError, metadata) {
+        super({
+            code: 'PARSING_ERROR',
+            category: 'parsing',
+            isRetryable: false,
+            userMessage: 'Failed to process search results. Please try a different query.',
+            technicalMessage: message,
+            originalError,
+            metadata,
+        });
+        this.name = 'ParsingError';
+    }
+}
+exports.ParsingError = ParsingError;
+class ServerError extends DuckDuckGoError {
+    constructor(statusCode, originalError) {
+        super({
+            code: 'SERVER_ERROR',
+            category: 'network',
+            isRetryable: true,
+            userMessage: 'DuckDuckGo servers are temporarily unavailable. Please try again later.',
+            technicalMessage: `Server returned error status: ${statusCode}`,
+            originalError,
+            metadata: { statusCode },
+        });
+        this.name = 'ServerError';
+    }
+}
+exports.ServerError = ServerError;
+function classifyError(error) {
+    if (error instanceof DuckDuckGoError) {
+        return error;
+    }
+    const message = (error === null || error === void 0 ? void 0 : error.message) || String(error);
+    const lowerMessage = message.toLowerCase();
+    if (lowerMessage.includes('econnrefused') ||
+        lowerMessage.includes('enotfound') ||
+        lowerMessage.includes('econnreset') ||
+        lowerMessage.includes('ehostunreach') ||
+        lowerMessage.includes('enetunreach') ||
+        lowerMessage.includes('network') ||
+        lowerMessage.includes('dns')) {
+        return new NetworkError(message, error instanceof Error ? error : undefined);
+    }
+    if (lowerMessage.includes('anomaly') ||
+        lowerMessage.includes('too quickly') ||
+        lowerMessage.includes('rate limit') ||
+        lowerMessage.includes('429') ||
+        lowerMessage.includes('too many requests')) {
+        return new RateLimitError(message, error instanceof Error ? error : undefined);
+    }
+    if (lowerMessage.includes('timeout') ||
+        lowerMessage.includes('etimedout') ||
+        lowerMessage.includes('timed out')) {
+        return new TimeoutError(30000, 'Search request', error instanceof Error ? error : undefined);
+    }
+    if (lowerMessage.includes('500') ||
+        lowerMessage.includes('502') ||
+        lowerMessage.includes('503') ||
+        lowerMessage.includes('504') ||
+        lowerMessage.includes('server error') ||
+        lowerMessage.includes('temporarily unavailable') ||
+        lowerMessage.includes('internal server error')) {
+        const statusMatch = message.match(/(\d{3})/);
+        const statusCode = statusMatch ? parseInt(statusMatch[1], 10) : 500;
+        return new ServerError(statusCode, error instanceof Error ? error : undefined);
+    }
+    if (lowerMessage.includes('json') ||
+        lowerMessage.includes('parse') ||
+        lowerMessage.includes('unexpected token') ||
+        lowerMessage.includes('syntax error')) {
+        return new ParsingError(message, error instanceof Error ? error : undefined);
+    }
+    return new DuckDuckGoError({
+        code: 'UNKNOWN_ERROR',
+        category: 'unknown',
+        isRetryable: false,
+        userMessage: 'An unexpected error occurred. Please try again.',
+        technicalMessage: message,
+        originalError: error instanceof Error ? error : undefined,
+    });
+}
+exports.classifyError = classifyError;
+function shouldRetryError(error, retryableCategories) {
+    return error.isRetryable && retryableCategories.has(error.category);
+}
+exports.shouldRetryError = shouldRetryError;

package/dist/nodes/DuckDuckGo/processors.js

@@ -1,14 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processVideoSearchResults = exports.processNewsSearchResults = exports.processImageSearchResults = exports.processWebSearchResults = void 0;
+exports.processVideoSearchResults = exports.processNewsSearchResults = exports.processImageSearchResults = exports.processWebSearchResults = exports.DEFAULT_QUALITY_CONFIG = void 0;
 const utils_1 = require("./utils");
-function processWebSearchResults(results, itemIndex, rawResponse) {
+const validation_1 = require("./validation");
+exports.DEFAULT_QUALITY_CONFIG = {
+    removeDuplicates: true,
+    requireTitle: true,
+    requireUrl: true,
+    minDescriptionLength: 0,
+    validateUrls: true,
+};
+function filterAndValidateResults(results, config = exports.DEFAULT_QUALITY_CONFIG) {
     if (!results || !Array.isArray(results)) {
         return [];
     }
-    return results
-        .filter(item => item && typeof item === 'object' && item.title && item.url)
-        .map((item, index) => ({
+    const seenUrls = new Set();
+    const seenTitles = new Set();
+    return results.filter((result) => {
+        if (config.requireTitle && !result.title) {
+            return false;
+        }
+        if (config.requireUrl && !result.url) {
+            return false;
+        }
+        if (config.validateUrls && result.url && !(0, validation_1.validateUrl)(result.url)) {
+            return false;
+        }
+        if (config.minDescriptionLength > 0 && result.description) {
+            const cleanDesc = (result.description || '').trim();
+            if (cleanDesc.length < config.minDescriptionLength) {
+                return false;
+            }
+        }
+        if (config.removeDuplicates && result.url) {
+            const normalizedUrl = result.url.toLowerCase().trim();
+            if (seenUrls.has(normalizedUrl)) {
+                return false;
+            }
+            seenUrls.add(normalizedUrl);
+        }
+        if (config.removeDuplicates && result.title) {
+            const normalizedTitle = result.title.toLowerCase().trim();
+            if (normalizedTitle && seenTitles.has(normalizedTitle)) {
+                return false;
+            }
+            if (normalizedTitle) {
+                seenTitles.add(normalizedTitle);
+            }
+        }
+        return true;
+    });
+}
+function processWebSearchResults(results, itemIndex, rawResponse, qualityConfig) {
+    if (!results || !Array.isArray(results)) {
+        return [];
+    }
+    const filteredResults = filterAndValidateResults(results, qualityConfig);
+    return filteredResults.map((item, index) => ({
         json: {
             position: index + 1,
             title: (0, utils_1.decodeHtmlEntities)(item.title || '') || '',
@@ -21,13 +69,17 @@ function processWebSearchResults(results, itemIndex, rawResponse) {
     }));
 }
 exports.processWebSearchResults = processWebSearchResults;
-function processImageSearchResults(results, itemIndex) {
+function processImageSearchResults(results, itemIndex, qualityConfig) {
     if (!results || !Array.isArray(results)) {
         return [];
     }
-    return results
-        .filter(item => item && typeof item === 'object' && item.image)
-        .map((item) => ({
+    const imageResults = results.filter(item => item && typeof item === 'object' && item.image);
+    const filteredResults = filterAndValidateResults(imageResults, {
+        ...exports.DEFAULT_QUALITY_CONFIG,
+        requireTitle: false,
+        ...qualityConfig,
+    });
+    return filteredResults.map((item) => ({
         json: {
             title: (0, utils_1.decodeHtmlEntities)(item.title || '') || '',
             url: item.url || '',
@@ -42,11 +94,12 @@ function processImageSearchResults(results, itemIndex) {
     }));
 }
 exports.processImageSearchResults = processImageSearchResults;
-function processNewsSearchResults(results, itemIndex) {
+function processNewsSearchResults(results, itemIndex, qualityConfig) {
     if (!results || !Array.isArray(results)) {
         return [];
     }
-    return results.map((item) => ({
+    const filteredResults = filterAndValidateResults(results, qualityConfig);
+    return filteredResults.map((item) => ({
         json: {
             title: (0, utils_1.decodeHtmlEntities)(item.title),
             description: (0, utils_1.decodeHtmlEntities)(item.excerpt),
@@ -61,11 +114,12 @@ function processNewsSearchResults(results, itemIndex) {
     }));
 }
 exports.processNewsSearchResults = processNewsSearchResults;
-function processVideoSearchResults(results, itemIndex) {
+function processVideoSearchResults(results, itemIndex, qualityConfig) {
     if (!results || !Array.isArray(results)) {
         return [];
     }
-    return results.map((item) => ({
+    const filteredResults = filterAndValidateResults(results, qualityConfig);
+    return filteredResults.map((item) => ({
         json: {
             title: (0, utils_1.decodeHtmlEntities)(item.title),
             description: (0, utils_1.decodeHtmlEntities)(item.description),

package/dist/nodes/DuckDuckGo/reliability.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetRequestQueue = exports.getRequestQueue = exports.RequestQueue = exports.withTimeout = exports.executeWithRetry = exports.DEFAULT_RETRY_CONFIG = exports.sleep = void 0;
+const errors_1 = require("./errors");
+const errors_2 = require("./errors");
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+exports.sleep = sleep;
+exports.DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelay: 2000,
+    maxDelay: 15000,
+    backoffMultiplier: 2,
+    jitterFactor: 0.5,
+    retryableCategories: new Set(['network', 'rate_limit', 'timeout']),
+};
+async function executeWithRetry(fn, context = 'operation', config = exports.DEFAULT_RETRY_CONFIG) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= config.maxRetries + 1; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const classifiedError = (0, errors_1.classifyError)(error);
+            lastError = classifiedError;
+            if (!(0, errors_1.shouldRetryError)(classifiedError, config.retryableCategories)) {
+                throw classifiedError;
+            }
+            if (attempt > config.maxRetries) {
+                throw classifiedError;
+            }
+            const baseDelay = Math.min(config.initialDelay * Math.pow(config.backoffMultiplier, attempt - 1), config.maxDelay);
+            const jitter = baseDelay * config.jitterFactor * (Math.random() * 2 - 1);
+            const delay = Math.max(0, baseDelay + jitter);
+            if (process.env.NODE_ENV === 'development') {
+                console.log(`[DuckDuckGo] Retry ${attempt}/${config.maxRetries} for ${context} ` +
+                    `after ${Math.round(delay)}ms due to ${classifiedError.code}`);
+            }
+            await (0, exports.sleep)(delay);
+        }
+    }
+    throw lastError || (0, errors_1.classifyError)('Unexpected retry error');
+}
+exports.executeWithRetry = executeWithRetry;
+async function withTimeout(promise, timeoutMs, operation) {
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new errors_2.TimeoutError(timeoutMs, operation));
+        }, timeoutMs);
+    });
+    try {
+        const result = await Promise.race([promise, timeoutPromise]);
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        return result;
+    }
+    catch (error) {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        throw error;
+    }
+}
+exports.withTimeout = withTimeout;
+class RequestQueue {
+    constructor(minInterval = 3000, maxConcurrent = 1) {
+        this.queue = [];
+        this.processing = false;
+        this.lastRequestTime = 0;
+        this.activeRequests = 0;
+        this.minInterval = minInterval;
+        this.maxConcurrent = maxConcurrent;
+    }
+    async enqueue(fn) {
+        return new Promise((resolve, reject) => {
+            this.queue.push(async () => {
+                try {
+                    const result = await fn();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            if (!this.processing) {
+                this.processQueue().catch(() => {
+                });
+            }
+        });
+    }
+    async processQueue() {
+        if (this.processing || this.queue.length === 0) {
+            return;
+        }
+        this.processing = true;
+        while (this.queue.length > 0 && this.activeRequests < this.maxConcurrent) {
+            const now = Date.now();
+            const timeSinceLastRequest = now - this.lastRequestTime;
+            if (timeSinceLastRequest < this.minInterval) {
+                const delay = this.minInterval - timeSinceLastRequest;
+                const jitter = Math.random() * 1000;
+                await (0, exports.sleep)(delay + jitter);
+            }
+            else {
+                const smallJitter = Math.random() * 500;
+                await (0, exports.sleep)(smallJitter);
+            }
+            const fn = this.queue.shift();
+            if (fn) {
+                this.lastRequestTime = Date.now();
+                this.activeRequests++;
+                fn().finally(() => {
+                    this.activeRequests--;
+                    if (this.queue.length > 0) {
+                        this.processQueue().catch(() => {
+                        });
+                    }
+                });
+            }
+        }
+        this.processing = false;
+    }
+    getQueueSize() {
+        return this.queue.length;
+    }
+    getActiveRequests() {
+        return this.activeRequests;
+    }
+    clear() {
+        this.queue = [];
+    }
+}
+exports.RequestQueue = RequestQueue;
+let globalRequestQueue = null;
+function getRequestQueue(minInterval = 3000) {
+    if (!globalRequestQueue) {
+        globalRequestQueue = new RequestQueue(minInterval);
+    }
+    return globalRequestQueue;
+}
+exports.getRequestQueue = getRequestQueue;
+function resetRequestQueue() {
+    globalRequestQueue = null;
+}
+exports.resetRequestQueue = resetRequestQueue;

package/dist/nodes/DuckDuckGo/utils.js

@@ -7,15 +7,98 @@ const HTML_ENTITIES = {
     '>': '>',
     '"': '"',
     ''': "'",
+    ''': "'",
     ' ': ' ',
+    ' ': ' ',
+    ' ': ' ',
+    ' ': ' ',
     '–': '–',
     '—': '—',
     '…': '…',
+    '‘': '\u2018',
+    '’': '\u2019',
+    '“': '\u201C',
+    '”': '\u201D',
+    '«': '«',
+    '»': '»',
+    '•': '•',
+    '·': '·',
+    '′': '′',
+    '″': '″',
+    '©': '©',
+    '®': '®',
+    '™': '™',
+    '°': '°',
+    '±': '±',
+    '¶': '¶',
+    '§': '§',
+    '†': '†',
+    '‡': '‡',
+    '€': '€',
+    '£': '£',
+    '¥': '¥',
+    '¢': '¢',
+    '¤': '¤',
+    '×': '×',
+    '÷': '÷',
+    '−': '−',
+    '≠': '≠',
+    '≤': '≤',
+    '≥': '≥',
+    '≈': '≈',
+    '∞': '∞',
+    '∑': '∑',
+    '∏': '∏',
+    '√': '√',
+    '∫': '∫',
+    '←': '←',
+    '↑': '↑',
+    '→': '→',
+    '↓': '↓',
+    '↔': '↔',
+    'α': 'α',
+    'β': 'β',
+    'γ': 'γ',
+    'δ': 'δ',
+    'ε': 'ε',
+    'π': 'π',
+    'σ': 'σ',
+    'ω': 'ω',
 };
 function decodeHtmlEntities(text) {
     if (!text)
         return null;
-    return text.replace(/&[#\w]+;/g, (entity) => HTML_ENTITIES[entity] || entity);
+    try {
+        return text
+            .replace(/&[a-zA-Z]+;/g, (entity) => HTML_ENTITIES[entity] || entity)
+            .replace(/&#(\d+);/g, (_, code) => {
+            try {
+                const num = parseInt(code, 10);
+                if (num >= 0 && num <= 0x10FFFF) {
+                    return String.fromCharCode(num);
+                }
+                return _;
+            }
+            catch {
+                return _;
+            }
+        })
+            .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => {
+            try {
+                const num = parseInt(code, 16);
+                if (num >= 0 && num <= 0x10FFFF) {
+                    return String.fromCharCode(num);
+                }
+                return _;
+            }
+            catch {
+                return _;
+            }
+        });
+    }
+    catch (error) {
+        return text;
+    }
 }
 exports.decodeHtmlEntities = decodeHtmlEntities;
 function formatDate(timestamp) {

package/dist/nodes/DuckDuckGo/validation.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTimeout = exports.validateTimePeriod = exports.validateSafeSearch = exports.validateUrl = exports.validateRegion = exports.validateLocale = exports.validateMaxResults = exports.sanitizeQuery = exports.validateSearchQuery = exports.VALIDATION_RULES = void 0;
+const errors_1 = require("./errors");
+exports.VALIDATION_RULES = {
+    QUERY_MIN_LENGTH: 1,
+    QUERY_MAX_LENGTH: 400,
+    MAX_RESULTS_MIN: 1,
+    MAX_RESULTS_MAX: 50,
+    TIMEOUT_MIN: 5000,
+    TIMEOUT_MAX: 120000,
+};
+function validateSearchQuery(query) {
+    if (query === null || query === undefined) {
+        throw new errors_1.ValidationError('query', 'Search query is required', query);
+    }
+    if (typeof query !== 'string') {
+        throw new errors_1.ValidationError('query', 'Search query must be a string', query);
+    }
+    const trimmed = query.trim();
+    if (trimmed.length < exports.VALIDATION_RULES.QUERY_MIN_LENGTH) {
+        throw new errors_1.ValidationError('query', 'Search query cannot be empty', query);
+    }
+    if (trimmed.length > exports.VALIDATION_RULES.QUERY_MAX_LENGTH) {
+        throw new errors_1.ValidationError('query', `Search query is too long (maximum ${exports.VALIDATION_RULES.QUERY_MAX_LENGTH} characters, got ${trimmed.length})`, query);
+    }
+    return sanitizeQuery(trimmed);
+}
+exports.validateSearchQuery = validateSearchQuery;
+function sanitizeQuery(query) {
+    return query
+        .replace(/\s+/g, ' ')
+        .replace(/[\x00-\x1F\x7F]/g, '')
+        .trim();
+}
+exports.sanitizeQuery = sanitizeQuery;
+function validateMaxResults(maxResults) {
+    if (maxResults === null || maxResults === undefined) {
+        return 10;
+    }
+    const num = typeof maxResults === 'string' ? parseFloat(maxResults) : maxResults;
+    if (typeof num !== 'number' || isNaN(num)) {
+        throw new errors_1.ValidationError('maxResults', 'Must be a valid number', maxResults);
+    }
+    if (!Number.isFinite(num)) {
+        throw new errors_1.ValidationError('maxResults', 'Must be a finite number', maxResults);
+    }
+    if (num < exports.VALIDATION_RULES.MAX_RESULTS_MIN) {
+        return exports.VALIDATION_RULES.MAX_RESULTS_MIN;
+    }
+    if (num > exports.VALIDATION_RULES.MAX_RESULTS_MAX) {
+        return exports.VALIDATION_RULES.MAX_RESULTS_MAX;
+    }
+    return Math.floor(num);
+}
+exports.validateMaxResults = validateMaxResults;
+function validateLocale(locale) {
+    if (!locale || typeof locale !== 'string') {
+        return 'en-us';
+    }
+    const trimmed = locale.trim().toLowerCase();
+    if (!/^[a-z]{2}-[a-z]{2}$/.test(trimmed)) {
+        throw new errors_1.ValidationError('locale', 'Invalid locale format (expected: xx-xx)', locale);
+    }
+    return trimmed;
+}
+exports.validateLocale = validateLocale;
+function validateRegion(region) {
+    if (!region || typeof region !== 'string') {
+        return 'wt-wt';
+    }
+    const trimmed = region.trim().toLowerCase();
+    if (!/^[a-z]{2}-[a-z]{2}$/.test(trimmed)) {
+        throw new errors_1.ValidationError('region', 'Invalid region format (expected: xx-xx)', region);
+    }
+    return trimmed;
+}
+exports.validateRegion = validateRegion;
+function validateUrl(url) {
+    if (!url || typeof url !== 'string') {
+        return false;
+    }
+    try {
+        const parsed = new URL(url);
+        return ['http:', 'https:'].includes(parsed.protocol);
+    }
+    catch {
+        return false;
+    }
+}
+exports.validateUrl = validateUrl;
+function validateSafeSearch(safeSearch) {
+    if (safeSearch === null || safeSearch === undefined) {
+        return 0;
+    }
+    const num = typeof safeSearch === 'string' ? parseInt(safeSearch, 10) : safeSearch;
+    if (typeof num !== 'number' || isNaN(num)) {
+        return 0;
+    }
+    if (![0, -1, -2].includes(num)) {
+        return 0;
+    }
+    return num;
+}
+exports.validateSafeSearch = validateSafeSearch;
+function validateTimePeriod(timePeriod) {
+    if (!timePeriod || typeof timePeriod !== 'string') {
+        return 'a';
+    }
+    const trimmed = timePeriod.trim().toLowerCase();
+    if (!['a', 'd', 'w', 'm', 'y'].includes(trimmed)) {
+        return 'a';
+    }
+    return trimmed;
+}
+exports.validateTimePeriod = validateTimePeriod;
+function validateTimeout(timeout) {
+    if (timeout === null || timeout === undefined) {
+        return 30000;
+    }
+    const num = typeof timeout === 'string' ? parseInt(timeout, 10) : timeout;
+    if (typeof num !== 'number' || isNaN(num)) {
+        throw new errors_1.ValidationError('timeout', 'Must be a valid number', timeout);
+    }
+    if (num < exports.VALIDATION_RULES.TIMEOUT_MIN) {
+        return exports.VALIDATION_RULES.TIMEOUT_MIN;
+    }
+    if (num > exports.VALIDATION_RULES.TIMEOUT_MAX) {
+        return exports.VALIDATION_RULES.TIMEOUT_MAX;
+    }
+    return num;
+}
+exports.validateTimeout = validateTimeout;

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "n8n-nodes-duckduckgo-search",
-    "version": "32.0.0",
-    "description": "Lightweight n8n community node for DuckDuckGo search. Search the web, images, news, and videos with privacy-focused results.",
+    "version": "32.2.0",
+    "description": "Professional-grade n8n community node for DuckDuckGo search with comprehensive error handling, validation, and quality filtering.",
     "keywords": [
         "n8n-community-node-package",
         "n8n",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "n8n-nodes-duckduckgo-search",
-  "version": "32.0.0",
-  "description": "Lightweight n8n community node for DuckDuckGo search. Search the web, images, news, and videos with privacy-focused results.",
+  "version": "32.2.0",
+  "description": "Professional-grade n8n community node for DuckDuckGo search with comprehensive error handling, validation, and quality filtering.",
   "keywords": [
     "n8n-community-node-package",
     "n8n",