duck-poacher 0.6.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Lars Dreier
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# duck-poacher
+
+A Node.js library for image search via DuckDuckGo. Returns image and thumbnail
+URLs for a query, with optional filters for size, color, type, and more.
+
+It calls DuckDuckGo's image-search endpoints, which are not a public, versioned
+API. Response formats can change on DuckDuckGo's side and break the library.
+
+## Install
+
+```sh
+npm install duck-poacher
+```
+
+Requires Node.js 18 or newer. The package ships dual ESM/CJS and exposes both an
+`import` and a `require` entry through its `exports` map.
+
+## Usage
+
+`DuckDuckGo` is the client. Construct one and call `imageSearch` — it returns a
+parsed `ImageSearchResult[]` (objects with `imageUrl` / `thumbnailUrl`, not a raw
+string) and manages the per-session `vqd` token for you, so there is no token to
+pass.
+
+```ts
+import { DuckDuckGo, type DdgSearchOptions, type ImageSearchResult } from 'duck-poacher';
+
+const ddg = new DuckDuckGo();
+
+const options: DdgSearchOptions = {
+  size: 'Large',
+  layout: 'Square',
+  safeSearch: true,
+};
+const results: ImageSearchResult[] = await ddg.imageSearch('mountain landscape', options);
+
+for (const result of results) {
+  console.log(result.imageUrl, result.thumbnailUrl);
+}
+```
+
+Each call makes two live requests (mint the token, then search). There is no
+built-in multi-query, dedupe, or cap.
+
+## API
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `DuckDuckGo` | class | The client: `imageSearch(query, options?)`, token managed internally |
+| `ImageSearchResult` | class | Immutable value object `{ thumbnailUrl, imageUrl }` |
+| `DdgSearchOptions` | type | Filter options for `imageSearch` |
+| `DdgTime` `DdgSize` `DdgColor` `DdgType` `DdgLayout` `DdgLicense` | type | String-union option values |
+
+### `DuckDuckGo`
+
+- **`imageSearch(query: string, options?: DdgSearchOptions): Promise<ImageSearchResult[]>`**
+  — generates a per-session `vqd` token, runs the image search, and returns the
+  parsed results. Throws `Error('Unable to read token from DuckDuckGo response.')`
+  if the token cannot be scraped; a malformed response body throws.
+
+### `DdgSearchOptions`
+
+All fields are optional. `safeSearch` is a boolean; the rest are string unions:
+
+| Option | Type | Values |
+|--------|------|--------|
+| `time` | `DdgTime` | `Day` `Week` `Month` |
+| `size` | `DdgSize` | `Small` `Medium` `Large` `Wallpaper` |
+| `color` | `DdgColor` | `color` `Monochrome` |
+| `type` | `DdgType` | `photo` `clipart` `gif` `transparent` `line` |
+| `layout` | `DdgLayout` | `Square` `Tall` `Wide` |
+| `license` | `DdgLicense` | `Any` `Public` |
+| `safeSearch` | `boolean` | safe search on / off |
+
+## Error handling
+
+Errors are thrown rather than swallowed. `generateToken` throws if no token can
+be read from the response. HTTP failures (status ≥ 400, network errors,
+timeouts) reject from the underlying request and propagate to the caller.
+
+## Development
+
+| Command | Does |
+|---------|------|
+| `npm run build` | tsdown → dual ESM/CJS in `dist/` |
+| `npm test` | run all `test/**/*.test.ts` (hits the live DuckDuckGo API) |
+| `npm run typecheck` | `tsc --noEmit` over `src/` |
+| `npm run lint` / `lint:fix` | ESLint |
+| `npm run format` / `format:check` | dprint |
+| `npm run check:exports` | `attw` validates the published export map |
+
+The only runtime dependency is
+[`node-http-toolkit`](https://www.npmjs.com/package/node-http-toolkit), which
+provides the HTTP layer.
+
+The tests run against the live DuckDuckGo endpoints, so they require network
+access.
+
+## License
+
+ISC © Lars Dreier

package/dist/DuckDuckGo.cjs

@@ -0,0 +1,11 @@
+const require_ImageSearchClient = require("./image/ImageSearchClient.cjs");
+//#region src/DuckDuckGo.ts
+var DuckDuckGo = class {
+	_imageSearch = new require_ImageSearchClient.default();
+	async imageSearch(query, options) {
+		const token = await this._imageSearch.generateToken(query);
+		return this._imageSearch.imageSearch(query, token, options);
+	}
+};
+//#endregion
+exports.default = DuckDuckGo;

package/dist/DuckDuckGo.d.cts

@@ -0,0 +1,10 @@
+import { ImageSearchResult } from "./image/ImageSearchResult.cjs";
+import { DdgSearchOptions } from "./image/ImageSearchClient.cjs";
+
+//#region src/DuckDuckGo.d.ts
+declare class DuckDuckGo {
+  private readonly _imageSearch;
+  imageSearch(query: string, options?: DdgSearchOptions): Promise<ImageSearchResult[]>;
+}
+//#endregion
+export { DuckDuckGo };

package/dist/DuckDuckGo.d.mts

@@ -0,0 +1,10 @@
+import { ImageSearchResult } from "./image/ImageSearchResult.mjs";
+import { DdgSearchOptions } from "./image/ImageSearchClient.mjs";
+
+//#region src/DuckDuckGo.d.ts
+declare class DuckDuckGo {
+  private readonly _imageSearch;
+  imageSearch(query: string, options?: DdgSearchOptions): Promise<ImageSearchResult[]>;
+}
+//#endregion
+export { DuckDuckGo };

package/dist/DuckDuckGo.mjs

@@ -0,0 +1,11 @@
+import ImageSearchClient from "./image/ImageSearchClient.mjs";
+//#region src/DuckDuckGo.ts
+var DuckDuckGo = class {
+	_imageSearch = new ImageSearchClient();
+	async imageSearch(query, options) {
+		const token = await this._imageSearch.generateToken(query);
+		return this._imageSearch.imageSearch(query, token, options);
+	}
+};
+//#endregion
+export { DuckDuckGo as default };

package/dist/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1,23 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+exports.__toESM = __toESM;

package/dist/image/ImageSearchClient.cjs

@@ -0,0 +1,70 @@
+require("../_virtual/_rolldown/runtime.cjs");
+const require_ImageSearchParser = require("./ImageSearchParser.cjs");
+let node_http_toolkit = require("node-http-toolkit");
+//#region src/image/ImageSearchClient.ts
+var ImageSearchClient = class {
+	OPTION_NAMES = [
+		"time",
+		"size",
+		"color",
+		"type",
+		"layout",
+		"license"
+	];
+	TOKEN_HEADERS = { dnt: "1" };
+	SEARCH_HEADERS = {
+		dnt: "1",
+		"accept-encoding": "gzip, deflate, sdch, br",
+		"x-requested-with": "XMLHttpRequest",
+		"accept-language": "en-GB,en-US;q=0.8,en;q=0.6,ms;q=0.4",
+		"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36",
+		accept: "application/json, text/javascript, */*; q=0.01",
+		referer: "https://duckduckgo.com/",
+		authority: "duckduckgo.com"
+	};
+	TOKEN_REGEX = /vqd=(?<vqd>[\d-]+)/;
+	_parser = new require_ImageSearchParser.default();
+	async generateToken(query) {
+		const params = new URLSearchParams();
+		params.append("q", query);
+		params.append("atb", "v299-1");
+		params.append("iar", "images");
+		params.append("iax", "images");
+		params.append("ia", "images");
+		const url = `https://duckduckgo.com/?${params.toString()}`;
+		const vqd = (await this.get(url, this.TOKEN_HEADERS)).match(this.TOKEN_REGEX)?.groups?.["vqd"];
+		if (vqd == null) throw new Error("Unable to read token from DuckDuckGo response.");
+		return vqd;
+	}
+	async imageSearch(query, token, options) {
+		const searchOptions = options ?? {};
+		const url = this.createSearchUrl(query, token, searchOptions);
+		const responseText = await this.get(url, this.SEARCH_HEADERS);
+		return this._parser.parse(responseText);
+	}
+	async get(url, headers) {
+		const response = await new node_http_toolkit.AsyncResolvingHttpRequest(url, node_http_toolkit.HttpMethod.GET, headers).resolve();
+		return new node_http_toolkit.HttpResponseReader().readData(response);
+	}
+	createSearchUrl(query, token, options) {
+		const params = new URLSearchParams();
+		params.append("l", "de-de");
+		params.append("o", "json");
+		params.append("q", query);
+		params.append("vqd", token);
+		params.append("f", this.createImageSearchOptionsHeader(options));
+		params.append("p", options.safeSearch == true ? "1" : "-1");
+		return `https://duckduckgo.com/i.js?${params.toString()}`;
+	}
+	createImageSearchOptionsHeader(options) {
+		const optionValues = [];
+		for (const optionName of this.OPTION_NAMES) {
+			const optionValue = options[optionName]?.toString();
+			if (optionValue == null) optionValues.push("");
+			else optionValues.push(`${optionName}:${optionValue}`);
+		}
+		return optionValues.join(",");
+	}
+};
+//#endregion
+exports.default = ImageSearchClient;

package/dist/image/ImageSearchClient.d.cts

@@ -0,0 +1,18 @@
+//#region src/image/ImageSearchClient.d.ts
+type DdgTime = 'Day' | 'Week' | 'Month';
+type DdgSize = 'Small' | 'Medium' | 'Large' | 'Wallpaper';
+type DdgColor = 'color' | 'Monochrome';
+type DdgType = 'photo' | 'clipart' | 'gif' | 'transparent' | 'line';
+type DdgLayout = 'Square' | 'Tall' | 'Wide';
+type DdgLicense = 'Any' | 'Public';
+interface DdgSearchOptions {
+  time?: DdgTime;
+  size?: DdgSize;
+  color?: DdgColor;
+  type?: DdgType;
+  layout?: DdgLayout;
+  license?: DdgLicense;
+  safeSearch?: boolean;
+}
+//#endregion
+export { DdgColor, DdgLayout, DdgLicense, DdgSearchOptions, DdgSize, DdgTime, DdgType };

package/dist/image/ImageSearchClient.d.mts

@@ -0,0 +1,18 @@
+//#region src/image/ImageSearchClient.d.ts
+type DdgTime = 'Day' | 'Week' | 'Month';
+type DdgSize = 'Small' | 'Medium' | 'Large' | 'Wallpaper';
+type DdgColor = 'color' | 'Monochrome';
+type DdgType = 'photo' | 'clipart' | 'gif' | 'transparent' | 'line';
+type DdgLayout = 'Square' | 'Tall' | 'Wide';
+type DdgLicense = 'Any' | 'Public';
+interface DdgSearchOptions {
+  time?: DdgTime;
+  size?: DdgSize;
+  color?: DdgColor;
+  type?: DdgType;
+  layout?: DdgLayout;
+  license?: DdgLicense;
+  safeSearch?: boolean;
+}
+//#endregion
+export { DdgColor, DdgLayout, DdgLicense, DdgSearchOptions, DdgSize, DdgTime, DdgType };

package/dist/image/ImageSearchClient.mjs

@@ -0,0 +1,69 @@
+import ImageSearchParser from "./ImageSearchParser.mjs";
+import { AsyncResolvingHttpRequest, HttpMethod, HttpResponseReader } from "node-http-toolkit";
+//#region src/image/ImageSearchClient.ts
+var ImageSearchClient = class {
+	OPTION_NAMES = [
+		"time",
+		"size",
+		"color",
+		"type",
+		"layout",
+		"license"
+	];
+	TOKEN_HEADERS = { dnt: "1" };
+	SEARCH_HEADERS = {
+		dnt: "1",
+		"accept-encoding": "gzip, deflate, sdch, br",
+		"x-requested-with": "XMLHttpRequest",
+		"accept-language": "en-GB,en-US;q=0.8,en;q=0.6,ms;q=0.4",
+		"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36",
+		accept: "application/json, text/javascript, */*; q=0.01",
+		referer: "https://duckduckgo.com/",
+		authority: "duckduckgo.com"
+	};
+	TOKEN_REGEX = /vqd=(?<vqd>[\d-]+)/;
+	_parser = new ImageSearchParser();
+	async generateToken(query) {
+		const params = new URLSearchParams();
+		params.append("q", query);
+		params.append("atb", "v299-1");
+		params.append("iar", "images");
+		params.append("iax", "images");
+		params.append("ia", "images");
+		const url = `https://duckduckgo.com/?${params.toString()}`;
+		const vqd = (await this.get(url, this.TOKEN_HEADERS)).match(this.TOKEN_REGEX)?.groups?.["vqd"];
+		if (vqd == null) throw new Error("Unable to read token from DuckDuckGo response.");
+		return vqd;
+	}
+	async imageSearch(query, token, options) {
+		const searchOptions = options ?? {};
+		const url = this.createSearchUrl(query, token, searchOptions);
+		const responseText = await this.get(url, this.SEARCH_HEADERS);
+		return this._parser.parse(responseText);
+	}
+	async get(url, headers) {
+		const response = await new AsyncResolvingHttpRequest(url, HttpMethod.GET, headers).resolve();
+		return new HttpResponseReader().readData(response);
+	}
+	createSearchUrl(query, token, options) {
+		const params = new URLSearchParams();
+		params.append("l", "de-de");
+		params.append("o", "json");
+		params.append("q", query);
+		params.append("vqd", token);
+		params.append("f", this.createImageSearchOptionsHeader(options));
+		params.append("p", options.safeSearch == true ? "1" : "-1");
+		return `https://duckduckgo.com/i.js?${params.toString()}`;
+	}
+	createImageSearchOptionsHeader(options) {
+		const optionValues = [];
+		for (const optionName of this.OPTION_NAMES) {
+			const optionValue = options[optionName]?.toString();
+			if (optionValue == null) optionValues.push("");
+			else optionValues.push(`${optionName}:${optionValue}`);
+		}
+		return optionValues.join(",");
+	}
+};
+//#endregion
+export { ImageSearchClient as default };

package/dist/image/ImageSearchParser.cjs

@@ -0,0 +1,12 @@
+const require_ImageSearchResult = require("./ImageSearchResult.cjs");
+//#region src/image/ImageSearchParser.ts
+var ImageSearchParser = class {
+	parse(responseText) {
+		const parsedResults = JSON.parse(responseText).results;
+		const searchResults = [];
+		for (const result of parsedResults) searchResults.push(new require_ImageSearchResult.default(result.thumbnail, result.image));
+		return searchResults;
+	}
+};
+//#endregion
+exports.default = ImageSearchParser;

package/dist/image/ImageSearchParser.mjs

@@ -0,0 +1,12 @@
+import ImageSearchResult from "./ImageSearchResult.mjs";
+//#region src/image/ImageSearchParser.ts
+var ImageSearchParser = class {
+	parse(responseText) {
+		const parsedResults = JSON.parse(responseText).results;
+		const searchResults = [];
+		for (const result of parsedResults) searchResults.push(new ImageSearchResult(result.thumbnail, result.image));
+		return searchResults;
+	}
+};
+//#endregion
+export { ImageSearchParser as default };

package/dist/image/ImageSearchResult.cjs

@@ -0,0 +1,11 @@
+//#region src/image/ImageSearchResult.ts
+var ImageSearchResult = class {
+	thumbnailUrl;
+	imageUrl;
+	constructor(thumbnailUrl, imageUrl) {
+		this.thumbnailUrl = thumbnailUrl;
+		this.imageUrl = imageUrl;
+	}
+};
+//#endregion
+exports.default = ImageSearchResult;

package/dist/image/ImageSearchResult.d.cts

@@ -0,0 +1,8 @@
+//#region src/image/ImageSearchResult.d.ts
+declare class ImageSearchResult {
+  readonly thumbnailUrl: string;
+  readonly imageUrl: string;
+  constructor(thumbnailUrl: string, imageUrl: string);
+}
+//#endregion
+export { ImageSearchResult };

package/dist/image/ImageSearchResult.d.mts

@@ -0,0 +1,8 @@
+//#region src/image/ImageSearchResult.d.ts
+declare class ImageSearchResult {
+  readonly thumbnailUrl: string;
+  readonly imageUrl: string;
+  constructor(thumbnailUrl: string, imageUrl: string);
+}
+//#endregion
+export { ImageSearchResult };

package/dist/image/ImageSearchResult.mjs

@@ -0,0 +1,11 @@
+//#region src/image/ImageSearchResult.ts
+var ImageSearchResult = class {
+	thumbnailUrl;
+	imageUrl;
+	constructor(thumbnailUrl, imageUrl) {
+		this.thumbnailUrl = thumbnailUrl;
+		this.imageUrl = imageUrl;
+	}
+};
+//#endregion
+export { ImageSearchResult as default };

package/dist/index.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ImageSearchResult = require("./image/ImageSearchResult.cjs");
+const require_DuckDuckGo = require("./DuckDuckGo.cjs");
+exports.DuckDuckGo = require_DuckDuckGo.default;
+exports.ImageSearchResult = require_ImageSearchResult.default;

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+import { ImageSearchResult } from "./image/ImageSearchResult.cjs";
+import { DdgColor, DdgLayout, DdgLicense, DdgSearchOptions, DdgSize, DdgTime, DdgType } from "./image/ImageSearchClient.cjs";
+import { DuckDuckGo } from "./DuckDuckGo.cjs";
+export { type DdgColor, type DdgLayout, type DdgLicense, type DdgSearchOptions, type DdgSize, type DdgTime, type DdgType, DuckDuckGo, ImageSearchResult };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { ImageSearchResult } from "./image/ImageSearchResult.mjs";
+import { DdgColor, DdgLayout, DdgLicense, DdgSearchOptions, DdgSize, DdgTime, DdgType } from "./image/ImageSearchClient.mjs";
+import { DuckDuckGo } from "./DuckDuckGo.mjs";
+export { type DdgColor, type DdgLayout, type DdgLicense, type DdgSearchOptions, type DdgSize, type DdgTime, type DdgType, DuckDuckGo, ImageSearchResult };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import ImageSearchResult from "./image/ImageSearchResult.mjs";
+import DuckDuckGo from "./DuckDuckGo.mjs";
+export { DuckDuckGo, ImageSearchResult };

package/package.json

@@ -0,0 +1,80 @@
+{
+	"name": "duck-poacher",
+	"version": "0.6.0",
+	"description": "DuckDuckGo image search scraper for Node.js.",
+	"type": "module",
+	"types": "./dist/index.d.mts",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit",
+		"check:exports": "attw --pack .",
+		"prepublishOnly": "npm test && npm run typecheck && npm run build && npm run check:exports",
+		"dev": "tsdown --watch",
+		"test": "tsx --test \"test/**/*.test.ts\"",
+		"test:coverage": "tsx --test --experimental-test-coverage \"test/**/*.test.ts\"",
+		"test:watch": "tsx --test --watch \"test/**/*.test.ts\"",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"format": "dprint fmt",
+		"format:check": "dprint check"
+	},
+	"keywords": [
+		"duckduckgo",
+		"image-search",
+		"images",
+		"search",
+		"scraper",
+		"scraping"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lars-dreier/duck-poacher.git"
+	},
+	"bugs": {
+		"url": "https://github.com/lars-dreier/duck-poacher/issues"
+	},
+	"homepage": "https://github.com/lars-dreier/duck-poacher#readme",
+	"author": {
+		"name": "Lars Dreier",
+		"email": "ldreier@posteo.de"
+	},
+	"license": "ISC",
+	"engines": {
+		"node": ">=18"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "0.18.3",
+		"@eslint/js": "10.0.1",
+		"@types/node": "25.9.3",
+		"dprint": "0.54.0",
+		"eslint": "10.5.0",
+		"eslint-config-prettier": "10.1.8",
+		"globals": "17.6.0",
+		"tsdown": "0.22.2",
+		"tsx": "4.22.4",
+		"typescript": "6.0.3",
+		"typescript-eslint": "8.61.0"
+	},
+	"dependencies": {
+		"node-http-toolkit": "1.0.1"
+	}
+}