ddg-kit

A focused, community-maintained compatibility client and maintenance path for the Web and News APIs used by duck-duck-scrape.

ddg-kit provides a maintained migration path for applications that depend on the observed duck-duck-scrape Web and News API. It preserves familiar function names, options, enums, and result shapes while adding typed provider failures, cancellation, one query deadline, and explicit proxy control.

The code is a greenfield rewrite. ddg-kit is not an official duck-duck-scrape release and is not affiliated with DuckDuckGo.

Current release: 0.1.0 supports Web and News only. Images, video, autocomplete, public VQD/bootstrap helpers, and spice endpoints are outside the current compatibility claim.

Relationship to duck-duck-scrape

ddg-kit occupies the community-maintained compatibility role for downstream applications that use the Web and News surface of duck-duck-scrape. We maintain the greenfield client, compatibility fixtures, release artifacts, failure semantics, and migration guidance for that surface.

We do not maintain the duck-duck-scrape repository, own its npm package, or represent its maintainers. ddg-kit is not an official fork, package transfer, or DuckDuckGo integration. Its compatibility target is the observed downstream API, not an upstream promise.

Applications can migrate Web and News to ddg-kit while keeping duck-duck-scrape for endpoints that are not yet supported here. This staged path is intentional: it gives downstream maintainers a maintained compatibility option without requiring an all-at-once dependency replacement.

Installation

npm install ddg-kit

Requirements:

• Node.js 18.17 or newer
• ESM or CommonJS

No API key is required. DuckDuckGo does not publish a supported contract for the endpoints used by this package. Provider changes can therefore cause typed failures until the package adapts.

Quick start

Web search

import { SafeSearchType, search } from "ddg-kit";

const response = await search("Node.js AbortSignal", {
  maxResults: 5,
  safeSearch: SafeSearchType.MODERATE,
});

for (const result of response.results) {
  console.log(result.title, result.url);
}

News search

import { SearchTimeType, searchNews } from "ddg-kit";

const response = await searchNews("semiconductor earnings", {
  maxResults: 5,
  time: SearchTimeType.WEEK,
});

for (const result of response.results) {
  console.log(result.title, result.url);
}

CommonJS consumers can use the same named API:

const { search, searchNews } = require("ddg-kit");

Why this package exists

Many existing duck-duck-scrape consumers need a maintained migration path. That path must not turn uncertain provider responses into successful empty results. DuckDuckGo can return a challenge page, an HTTP error, or a changed payload. ddg-kit rejects those responses with DdgError.

The package keeps the useful part of the prior Web/News contract:

• search, searchNews, SafeSearchType, and SearchTimeType
• familiar Web and News result fields
• named, namespace, default, dynamic, ESM, and CommonJS imports

This release also adds:

• structured errors for challenges, limits, timeouts, HTTP failures, response limits, and parse changes
• one total deadline across fallback attempts
• AbortSignal cancellation
• explicit proxy selection and credential-safe failures
• tests against the packed npm artifact

Public API

Export	Purpose
search(query, options?, request?)	Run a Web search
searchNews(query, options?, request?)	Run a News search
createDdgClient(options?)	Create a configured client
DdgError	Inspect a typed provider or transport failure
SafeSearchType	Select strict, moderate, or disabled safe search
SearchTimeType	Select day, week, month, year, or all time

Common search options:

Option	Web	News	Purpose
safeSearch	Yes	Yes	Select content filtering
time	Yes	Yes	Restrict results by age
locale	Yes	Yes	Select the request locale
region, marketRegion	Yes	No	Select Web result regions
offset	Yes	Yes	Request a result offset
vqd	Yes	Yes	Supply an existing DuckDuckGo query token
maxResults	Yes	Yes	Bound the returned result count

The third argument accepts signal, timeoutMs, and proxy. It does not accept arbitrary Needle options.

Handle failures by code

import { DdgError, search } from "ddg-kit";

try {
  const response = await search("example query");
  console.log(response.results);
} catch (error) {
  if (!(error instanceof DdgError)) {
    throw error;
  }

  if (error.code === "BOT_CHALLENGE") {
    console.error("DuckDuckGo returned a challenge", error.cooldownMs);
  } else if (error.retryable) {
    console.error("Search can be retried later", error.code);
  } else {
    console.error("Search failed", error.code);
  }
}

Code	Meaning
INVALID_INPUT	The query or option value is invalid.
UNSUPPORTED_OPTION	The package cannot preserve the requested semantics.
TIMEOUT	The total query deadline expired.
RATE_LIMITED	DuckDuckGo returned a rate limit.
BOT_CHALLENGE	DuckDuckGo returned a bot or anomaly challenge.
UPSTREAM_4XX	DuckDuckGo returned a client HTTP error.
UPSTREAM_5XX	DuckDuckGo returned a server HTTP error.
PARSE_ERROR	A provider response no longer matches the parser contract.
RESPONSE_TOO_LARGE	A response crossed the configured safety limit.
UNKNOWN	The transport failed without a more specific classification.

Check error.retryable before retrying. Respect error.cooldownMs after a bot challenge.

Request control

Create a client when several calls share the same policy:

import { createDdgClient } from "ddg-kit";

const client = createDdgClient({
  timeoutMs: 10_000,
  proxy: "http://127.0.0.1:8080",
  challengeCooldownMs: 60_000,
});

const controller = new AbortController();

const response = await client.search(
  "example query",
  { maxResults: 10 },
  {
    signal: controller.signal,
    timeoutMs: 5_000,
  },
);

Pass proxy, set DUCKDUCKGO_PROXY_URL, or opt in with USE_PROXY=true and PROXY_URL. The package ignores ambient HTTP_PROXY and HTTPS_PROXY settings.

Compatibility and scope

Many Web and News consumers can migrate by changing the package name:

- import { search, SafeSearchType } from "duck-duck-scrape";
+ import { search, SafeSearchType } from "ddg-kit";

Review the third request argument during migration:

await search("query", searchOptions, {
  signal,
  timeoutMs: 10_000,
  proxy: false,
});

Supported in 0.1.0	Planned or outside the current scope
Web and News search	Images, video, and autocomplete
search, searchNews, createDdgClient	Public VQD or bootstrap helpers
Safe search, time, locale, region, offset, max results	Spice endpoints
ESM and CommonJS	MCP server behavior
Timeout, cancellation, cooldown, explicit proxy	Aggregation and ranking

Web representation fallback is internal. Callers cannot select Web preload, HTML, or Lite parsing paths. Read MIGRATION.md for deliberate differences, VQD behavior, and rollback guidance.

The public compatibility matrix is the source for the current Web/News P0 contract. It records supported exports, deliberate option mappings, structured failure behavior, and legacy surfaces that remain outside the release line.

ddg-kit does not bypass rate limits, bot challenges, CAPTCHAs, or access controls. Applications that need a supported service-level agreement should use an official search API.

Planned compatibility (P1)

Images and video search are planned for P1. They are not part of the 0.1.0 public compatibility claim. These endpoints have different request filters and result schemas from Web and News, so P1 will add separate typed APIs and parsers. It will not alias image or video results to Web results.

P1 must add frozen fixtures for successful, empty, challenged, malformed, timed-out, and paginated responses. It must pass the packed ESM/CommonJS matrix and a downstream canary before consumers remove their remaining duck-duck-scrape dependency. Until then, applications that need Images or video should keep that dependency for those operations. They may migrate Web and News to ddg-kit independently.

Verification

Version 0.1.0 promotes the runtime code accepted in v0.1.0-rc.2. Changes after RC2 cover documentation and release metadata, not runtime behavior.

The project records each type of evidence separately:

• Package checks: 27 tests, type checking, build, and packed-consumer tests
• Runtime matrix: packed ESM and CommonJS consumers on Node 18.17, 20, and 22
• Failure behavior: synthetic fixtures for challenges, limits, timeouts, HTTP errors, parse changes, and response limits
• Independent review: RC1 was rejected after a clean-checkout failure; RC2 was accepted after the fix
• Migration evidence: downstream canaries and maintainer-reviewed merged pull requests record focused Web/News adoption and unresolved limits

Read the RC1 rejection report, the RC2 acceptance report, and the compatibility status.

Local canaries do not prove production adoption, downstream maintainer approval, Linux or macOS runtime behavior, or long-running provider stability. The canary index records the current evidence. The adoption index separates local canaries from downstream maintainer acceptance.

Recent downstream evidence includes OpenCandle PR #145 and intercept-mcp PR #6. Both merged focused Web/News migrations. These merges show maintainer review and acceptance of a narrow compatibility change; they do not provide a production SLA or prove broad provider stability.

Maintenance and contributions

You can open a focused pull request for:

• reproducible Web or News fixes with synthetic fixtures
• error, timeout, cancellation, proxy, redaction, or package compatibility fixes
• documentation corrections and focused tests

Open a proposal before changing the public API, result contract, retry policy, runtime dependencies, supported Node versions, or Web/News product boundary.

The project does not accept provider-control bypasses, live response bodies, credentials, private queries, silent semantic changes, or unrelated search aggregation work. Read CONTRIBUTING.md and SECURITY.md before submitting a change. Use the support and compatibility guide to report provider breakage or request a new compatibility surface. GOVERNANCE.md describes the maintenance and adoption signals behind trust claims.

Development

npm ci
npm run check

Run the packed Node matrix when a change affects the public API, runtime compatibility, build, or package contents:

npm run test:matrix

Default tests stay offline. The opt-in live E2E runner uses one Web request and one News request with automatic retries disabled. A provider challenge is recorded as blocked evidence, not as a successful empty result.

Release integrity

Each release binds one source commit to one annotated Git tag, GitHub Release, npm package, and recorded tarball hash. The publish workflow requests npm provenance from GitHub Actions.

See CHANGELOG.md, the release checklist, and the code provenance record.

License

Apache-2.0. See docs/PROVENANCE.md for the greenfield code origin and dependency license review.