@openclaw/duckduckgo-plugin 0.0.0 → 2026.8.1-beta.2

package/README.md

@@ -1,3 +1,12 @@
-# @openclaw/duckduckgo-plugin
+# OpenClaw DuckDuckGo Plugin
 
-Reserved placeholder for the official OpenClaw plugin package. Use a published release version instead.
+Official OpenClaw plugin for DuckDuckGo web search.
+
+Install from OpenClaw:
+
+```bash
+openclaw plugins install @openclaw/duckduckgo-plugin
+openclaw gateway restart
+```
+
+See <https://docs.openclaw.ai/tools/duckduckgo-search> for setup and configuration.

package/dist/ddg-client-CdJu902j.js

@@ -0,0 +1,152 @@
+import { decodeHtmlEntities } from "openclaw/plugin-sdk/html-entity-runtime";
+import { readProviderTextResponse } from "openclaw/plugin-sdk/provider-http";
+import { DEFAULT_CACHE_TTL_MINUTES, DEFAULT_SEARCH_COUNT, normalizeCacheKey, readCache, readResponseText, resolveCacheTtlMs, resolveSearchCount, resolveSiteName, resolveTimeoutSeconds, withTrustedWebSearchEndpoint, wrapWebContent, writeCache } from "openclaw/plugin-sdk/provider-web-search";
+import { normalizeLowercaseStringOrEmpty, normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/duckduckgo/src/config.ts
+const DEFAULT_DDG_SAFE_SEARCH = "moderate";
+function resolveDdgWebSearchConfig(config) {
+	const webSearch = (config?.plugins?.entries?.duckduckgo?.config)?.webSearch;
+	if (webSearch && typeof webSearch === "object" && !Array.isArray(webSearch)) return webSearch;
+}
+function resolveDdgRegion(config) {
+	return normalizeOptionalString(resolveDdgWebSearchConfig(config)?.region);
+}
+function resolveDdgSafeSearch(config) {
+	const safeSearch = resolveDdgWebSearchConfig(config)?.safeSearch;
+	const normalized = normalizeLowercaseStringOrEmpty(safeSearch);
+	if (normalized === "strict" || normalized === "off") return normalized;
+	return DEFAULT_DDG_SAFE_SEARCH;
+}
+//#endregion
+//#region extensions/duckduckgo/src/ddg-client.ts
+const DDG_HTML_ENDPOINT = "https://html.duckduckgo.com/html";
+const DEFAULT_TIMEOUT_SECONDS = 20;
+const DDG_HTML_ENTITY_RE = /&(?:lt|gt|quot|apos|#39|#x27|#x2F|nbsp|ndash|mdash|hellip|amp|#\d+|#x[0-9a-f]+);/gi;
+const DDG_ENTITY_TEXT = {
+	"\xA0": " ",
+	"–": "-",
+	"—": "--",
+	"…": "..."
+};
+const DDG_SAFE_SEARCH_PARAM = {
+	strict: "1",
+	moderate: "-1",
+	off: "-2"
+};
+const DDG_SEARCH_CACHE = /* @__PURE__ */ new Map();
+function decodeHtmlEntities$1(text) {
+	return text.replace(DDG_HTML_ENTITY_RE, (entity) => {
+		const decoded = decodeHtmlEntities(entity.startsWith("&#") ? entity : entity.toLowerCase());
+		return DDG_ENTITY_TEXT[decoded] ?? decoded;
+	});
+}
+function stripHtml(html) {
+	return html.replace(/<\/?b\b[^>]*>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+function decodeDuckDuckGoUrl(rawUrl) {
+	try {
+		const normalized = rawUrl.startsWith("//") ? `https:${rawUrl}` : rawUrl;
+		const uddg = new URL(normalized).searchParams.get("uddg");
+		if (uddg) return uddg;
+	} catch {}
+	return rawUrl;
+}
+function readHrefAttribute(tagAttributes) {
+	return /\bhref="([^"]*)"/i.exec(tagAttributes)?.[1] ?? "";
+}
+function isBotChallenge(html) {
+	if (/class="[^"]*\bresult__a\b[^"]*"/i.test(html)) return false;
+	return /g-recaptcha|are you a human|id="challenge-form"|name="challenge"/i.test(html);
+}
+async function readDuckDuckGoHtmlResponse(response) {
+	return await readProviderTextResponse(response, "DuckDuckGo search");
+}
+function parseDuckDuckGoHtml(html) {
+	const results = [];
+	const resultRegex = /<a\b(?=[^>]*\bclass="[^"]*\bresult__a\b[^"]*")([^>]*)>([\s\S]*?)<\/a>/gi;
+	const nextResultRegex = /<a\b(?=[^>]*\bclass="[^"]*\bresult__a\b[^"]*")[^>]*>/i;
+	const snippetRegex = /<a\b(?=[^>]*\bclass="[^"]*\bresult__snippet\b[^"]*")[^>]*>([\s\S]*?)<\/a>/i;
+	for (const match of html.matchAll(resultRegex)) {
+		const rawAttributes = match[1] ?? "";
+		const rawTitle = match[2] ?? "";
+		const rawUrl = readHrefAttribute(rawAttributes);
+		const matchEnd = (match.index ?? 0) + match[0].length;
+		const trailingHtml = html.slice(matchEnd);
+		const nextResultIndex = trailingHtml.search(nextResultRegex);
+		const scopedTrailingHtml = nextResultIndex >= 0 ? trailingHtml.slice(0, nextResultIndex) : trailingHtml;
+		const rawSnippet = snippetRegex.exec(scopedTrailingHtml)?.[1] ?? "";
+		const title = decodeHtmlEntities$1(stripHtml(rawTitle));
+		const url = decodeDuckDuckGoUrl(decodeHtmlEntities$1(rawUrl));
+		const snippet = decodeHtmlEntities$1(stripHtml(rawSnippet));
+		if (title && url) results.push({
+			title,
+			url,
+			snippet
+		});
+	}
+	return results;
+}
+async function runDuckDuckGoSearch(params) {
+	const count = resolveSearchCount(params.count, DEFAULT_SEARCH_COUNT);
+	const region = params.region ?? resolveDdgRegion(params.config);
+	const safeSearch = params.safeSearch === "strict" || params.safeSearch === "moderate" || params.safeSearch === "off" ? params.safeSearch : resolveDdgSafeSearch(params.config);
+	const timeoutSeconds = resolveTimeoutSeconds(params.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS);
+	const cacheTtlMs = resolveCacheTtlMs(params.cacheTtlMinutes, DEFAULT_CACHE_TTL_MINUTES);
+	const cacheKey = normalizeCacheKey(JSON.stringify({
+		provider: "duckduckgo",
+		query: params.query,
+		count,
+		region: region ?? "",
+		safeSearch
+	}));
+	const cached = readCache(DDG_SEARCH_CACHE, cacheKey);
+	if (cached) return {
+		...cached.value,
+		cached: true
+	};
+	const url = new URL(DDG_HTML_ENDPOINT);
+	url.searchParams.set("q", params.query);
+	if (region) url.searchParams.set("kl", region);
+	url.searchParams.set("kp", DDG_SAFE_SEARCH_PARAM[safeSearch]);
+	const startedAt = Date.now();
+	const results = await withTrustedWebSearchEndpoint({
+		url: url.toString(),
+		timeoutSeconds,
+		signal: params.signal,
+		init: {
+			method: "GET",
+			headers: { "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36" }
+		}
+	}, async (response) => {
+		if (!response.ok) {
+			const detail = (await readResponseText(response, { maxBytes: 64e3 })).text;
+			throw new Error(`DuckDuckGo search error (${response.status}): ${detail || response.statusText}`);
+		}
+		const html = await readDuckDuckGoHtmlResponse(response);
+		if (isBotChallenge(html)) throw new Error("DuckDuckGo returned a bot-detection challenge.");
+		return parseDuckDuckGoHtml(html).slice(0, count);
+	});
+	params.signal?.throwIfAborted();
+	const payload = {
+		query: params.query,
+		provider: "duckduckgo",
+		count: results.length,
+		tookMs: Date.now() - startedAt,
+		externalContent: {
+			untrusted: true,
+			source: "web_search",
+			provider: "duckduckgo",
+			wrapped: true
+		},
+		results: results.map((result) => ({
+			title: wrapWebContent(result.title, "web_search"),
+			url: result.url,
+			snippet: result.snippet ? wrapWebContent(result.snippet, "web_search") : "",
+			siteName: resolveSiteName(result.url) || void 0
+		}))
+	};
+	writeCache(DDG_SEARCH_CACHE, cacheKey, payload, cacheTtlMs);
+	return payload;
+}
+//#endregion
+export { runDuckDuckGoSearch };

package/dist/ddg-search-provider-gy4EJrPB.js

@@ -0,0 +1,55 @@
+import { t as createDuckDuckGoWebSearchProviderBase } from "./ddg-search-provider.shared-B2Y6U1WN.js";
+import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import { readPositiveIntegerParam, readStringParam } from "openclaw/plugin-sdk/param-readers";
+//#region extensions/duckduckgo/src/ddg-search-provider.ts
+const loadDuckDuckGoClientModule = createLazyRuntimeModule(() => import("./ddg-client-CdJu902j.js"));
+const DuckDuckGoSearchSchema = {
+	type: "object",
+	properties: {
+		query: {
+			type: "string",
+			description: "Search query string."
+		},
+		count: {
+			type: "integer",
+			description: "Number of results to return (1-10).",
+			minimum: 1,
+			maximum: 10
+		},
+		region: {
+			type: "string",
+			description: "Optional DuckDuckGo region code such as us-en, uk-en, or de-de."
+		},
+		safeSearch: {
+			type: "string",
+			description: "SafeSearch level: strict, moderate, or off."
+		}
+	},
+	additionalProperties: false
+};
+function createDuckDuckGoWebSearchProvider() {
+	return {
+		...createDuckDuckGoWebSearchProviderBase(),
+		createTool: (ctx) => ({
+			description: "Search the web using DuckDuckGo. Returns titles, URLs, and snippets with no API key required.",
+			parameters: DuckDuckGoSearchSchema,
+			execute: async (args, context) => {
+				context?.signal?.throwIfAborted();
+				const { runDuckDuckGoSearch } = await loadDuckDuckGoClientModule();
+				return await runDuckDuckGoSearch({
+					config: ctx.config,
+					query: readStringParam(args, "query", { required: true }),
+					count: readPositiveIntegerParam(args, "count", {
+						max: 10,
+						message: "count must be an integer from 1 to 10."
+					}),
+					region: readStringParam(args, "region"),
+					safeSearch: readStringParam(args, "safeSearch"),
+					...context?.signal ? { signal: context.signal } : {}
+				});
+			}
+		})
+	};
+}
+//#endregion
+export { createDuckDuckGoWebSearchProvider as t };

package/dist/ddg-search-provider.shared-B2Y6U1WN.js

@@ -0,0 +1,28 @@
+import { createWebSearchProviderContractFields } from "openclaw/plugin-sdk/provider-web-search-contract";
+//#region extensions/duckduckgo/src/ddg-search-provider.shared.ts
+const DUCKDUCKGO_ONBOARDING_SCOPES = ["text-inference"];
+function createDuckDuckGoWebSearchProviderBase() {
+	return {
+		id: "duckduckgo",
+		label: "DuckDuckGo Search (experimental)",
+		hint: "Free web search fallback with no API key required",
+		onboardingScopes: [...DUCKDUCKGO_ONBOARDING_SCOPES],
+		requiresCredential: false,
+		envVars: [],
+		placeholder: "(no key needed)",
+		signupUrl: "https://duckduckgo.com/",
+		docsUrl: "https://docs.openclaw.ai/tools/web",
+		autoDetectOrder: 100,
+		credentialPath: "",
+		...createWebSearchProviderContractFields({
+			credentialPath: "",
+			searchCredential: {
+				type: "scoped",
+				scopeId: "duckduckgo"
+			},
+			selectionPluginId: "duckduckgo"
+		})
+	};
+}
+//#endregion
+export { createDuckDuckGoWebSearchProviderBase as t };

package/dist/index.js

@@ -0,0 +1,13 @@
+import { t as createDuckDuckGoWebSearchProvider } from "./ddg-search-provider-gy4EJrPB.js";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+//#region extensions/duckduckgo/index.ts
+var duckduckgo_default = definePluginEntry({
+	id: "duckduckgo",
+	name: "DuckDuckGo Plugin",
+	description: "Official DuckDuckGo web search plugin",
+	register(api) {
+		api.registerWebSearchProvider(createDuckDuckGoWebSearchProvider());
+	}
+});
+//#endregion
+export { duckduckgo_default as default };

package/dist/web-search-contract-api.js

@@ -0,0 +1,10 @@
+import { t as createDuckDuckGoWebSearchProviderBase } from "./ddg-search-provider.shared-B2Y6U1WN.js";
+//#region extensions/duckduckgo/web-search-contract-api.ts
+function createDuckDuckGoWebSearchProvider() {
+	return {
+		...createDuckDuckGoWebSearchProviderBase(),
+		createTool: () => null
+	};
+}
+//#endregion
+export { createDuckDuckGoWebSearchProvider };

package/dist/web-search-provider.js

@@ -0,0 +1,2 @@
+import { t as createDuckDuckGoWebSearchProvider } from "./ddg-search-provider-gy4EJrPB.js";
+export { createDuckDuckGoWebSearchProvider };

package/openclaw.plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "duckduckgo",
+  "icon": "https://cdn.simpleicons.org/duckduckgo",
+  "activation": {
+    "onStartup": false
+  },
+  "uiHints": {
+    "webSearch.region": {
+      "label": "DuckDuckGo Region",
+      "help": "Optional DuckDuckGo region code such as us-en, uk-en, or de-de."
+    },
+    "webSearch.safeSearch": {
+      "label": "DuckDuckGo SafeSearch",
+      "help": "SafeSearch level for DuckDuckGo results."
+    }
+  },
+  "contracts": {
+    "webSearchProviders": ["duckduckgo"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "webSearch": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "region": {
+            "type": "string"
+          },
+          "safeSearch": {
+            "type": "string",
+            "enum": ["strict", "moderate", "off"]
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,14 +1,49 @@
 {
   "name": "@openclaw/duckduckgo-plugin",
-  "version": "0.0.0",
-  "description": "Reserved package name for an official OpenClaw plugin.",
-  "license": "MIT",
+  "version": "2026.8.1-beta.2",
+  "description": "OpenClaw DuckDuckGo plugin.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/openclaw/openclaw.git"
+    "url": "https://github.com/openclaw/openclaw"
   },
-  "publishConfig": {
-    "access": "public",
-    "tag": "placeholder"
-  }
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/duckduckgo-plugin",
+      "npmSpec": "@openclaw/duckduckgo-plugin",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.7.2"
+    },
+    "compat": {
+      "pluginApi": ">=2026.8.1-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.8.1-beta.2",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist/**",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.8.1-beta.2"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "bundledDependencies": []
 }