Compatibility status

Date: 2026-08-02 Release line: 0.1.0

P0 freeze

The Web and News compatibility interface is frozen as of 2026-08-02.

The freeze allows provider parser fixes, failure-classification fixes, security fixes, documentation, tests, and release metadata. It does not allow new public search surfaces, new result contracts, aggregation, ranking, or Images/Videos implementation in the P0 release line.

P0 remains frozen until the project has a meaningful maintenance release, independent maintainer-run verification, and repeated downstream use across more than one release. A P1 proposal must use the compatibility request process and must not change the P0 contract silently.

Public compatibility matrix

This matrix describes the public interface that ddg-kit@0.1.x supports. It separates direct compatibility from deliberate mappings and unsupported legacy surfaces. “Supported” means that the interface and its observable behavior are covered by repository tests and packed-consumer checks. It does not promise continuous DuckDuckGo availability or a service-level agreement.

Exports and runtime

Legacy surface or use	ddg-kit@0.1.x	Status	Notes
Named search export	search	Supported	Web search result mapping
Named searchNews export	searchNews	Supported	News result mapping
SafeSearchType	SafeSearchType	Supported	Values STRICT=0, MODERATE=-1, OFF=-2
SearchTimeType	SearchTimeType	Supported	Values ALL, DAY, WEEK, MONTH, YEAR are preserved
Namespace import	Namespace exports	Supported with mapping	The supported Web/News exports are covered by packed ESM fixtures
Default namespace import	Frozen default namespace	Supported with mapping	Contains the P0 exports only
Dynamic ESM import	Package exports	Supported with mapping	The supported Web/News exports are covered by packed ESM fixtures
CommonJS require	Conditional package export	Supported with mapping	Runtime use is covered in 0.1.0; Node16 TypeScript CommonJS declarations require 0.1.1 or later
npm alias under the legacy dependency name	"duck-duck-scrape": "npm:ddg-kit@0.1.1"	Supported with restriction	Keeps source imports unchanged for P0-only consumers; use 0.1.1 or later for Node16 TypeScript CommonJS projects
Node.js runtime	Node.js >=18.17	Supported	Node 18, 20, and 22 packed matrix recorded

Options, results, and errors

Legacy contract	ddg-kit@0.1.x behavior	Status	Migration note
Web query and options	search(query, options?, request?)	Supported	Query, safe search, time, locale, region, offset, VQD, and max results are validated
News query and options	searchNews(query, options?, request?)	Supported	News keeps its own request and result path; it does not fall back to Web
Web result fields	hostname, url, title, description, rawDescription, icon, optional bang	Supported	Values are normalized from the supported representations
News result fields	date, excerpt, image?, relativeTime, syndicate, title, url, isOld	Supported	Provider field names are mapped to the public camel-case result shape
noResults, vqd, and results	Same core response fields	Supported	A valid parsed empty response remains an empty success
Optional Web news and related modules	Not populated by the P0 implementation	Not promised	Do not depend on these optional legacy fields
Third request argument	signal, timeoutMs, and proxy	Supported with mapping	Arbitrary Needle options are not accepted
Provider failures	DdgError with code, retryable, status?, and cooldownMs?	Deliberate change	Handle error codes; do not parse error messages
Web representation selection	Internal preload → HTML → Lite policy	Not caller-selectable	Callers cannot depend on provider representation details
Caller-provided Web VQD	Preserved only when it matches the signed preload	Supported with restriction	The client rejects fallback that cannot preserve the VQD

Legacy surfaces outside P0

Legacy surface	Status in ddg-kit@0.1.x	Current path
searchImages	Unsupported	Keep duck-duck-scrape for this operation
searchVideos	Unsupported	Keep duck-duck-scrape for this operation
Autocomplete	Unsupported	No P0 compatibility claim
Public VQD or bootstrap helpers	Unsupported	Bootstrap details remain inside the deep module
Spice APIs such as stocks, weather, currency, and dictionary	Unsupported	No P0 compatibility claim
Search aggregation, ranking, or multi-provider routing	Out of scope	Belongs in a higher-level product, not this client

Evidence and change rule

The public interface is the test surface. A change to an export, option, result field, default, error code, retry rule, supported Node version, or fallback invariant must update this matrix and its corresponding public or packed-consumer test in the same change.

Provider changes must stay behind the internal transport and representation seams. A provider repair can change the implementation without widening the public interface. New public surfaces require a compatibility proposal, independent fixtures, packed ESM/CommonJS checks, a downstream canary, and a rollback path.

Verified locally

• public Web/News types and compatibility enum values
• named, namespace, default, dynamic ESM, and CommonJS runtime imports
• type-only TypeScript consumption from an installed tarball
• packed runtime consumption on Node 18.17.0, 20.20.2, and 22.23.1
• Web preload parsing with exact HTTPS host/path validation
• Web → HTML and HTML 202 → Lite representation policy
• News bootstrap/VQD path and provided-News-VQD path
• query and option validation, result truncation, and structured errors
• one total logical-query deadline
• caller abort preservation
• explicit proxy selection and credential-safe failures
• bounded client-local challenge cooldown
• response-size limits
• one explicit live no-result logical query completed with a valid VQD and no challenge on 2026-07-28
• HTML/Lite challenge responses classified as BOT_CHALLENGE instead of empty success
• local one-search-mcp migration tests and build
• local OpenCandle Web/News provider tests and one live News query with three mapped results
• local beeai-framework related tests, TypeScript checks, and CJS/ESM bundling
• local @ericthered926/duckduckgo-mcp-server typecheck, ESLint, MCP tests, and initialize handshake
• local duckduckgo-mcp-server lockfile policy, TypeScript compile, and MCP initialize handshake
• local @devs30/local-deep-researcher typecheck, 186 tests, ESM/DTS build, and source/test ESLint
• packed no-source alias installation, ESM/CommonJS resolution, and TypeScript consumption, plus compilation in three downstream consumers
• one direct News E2E pass through the Eric MCP server with 3 mapped results
• one downstream Web E2E pass through the local-deep-researcher fallback chain; the returning backend was not isolated

All default tests are offline. Provider fixtures are synthetic and frozen in the repository.

Not verified

• Linux and macOS runtime behavior
• authenticated or enterprise proxies
• long-running production traffic
• all locale/region combinations
• live non-empty Web result mapping through the current candidate
• live behavior under real rate limiting or challenge cooldown
• independent downstream builds outside the listed canaries and maintainer-reviewed pull requests
• beeai-framework full DTS build after its worker exceeded the local heap limit
• npm trusted publishing, provenance attestations, or installation from the public registry
• Image and video search APIs, including their provider parsers and typed filter options

Known limitations

• DuckDuckGo does not provide a supported public contract for these endpoints.
• Current Web preload parsing depends on provider-emitted page and JavaScript structures and can fail closed with PARSE_ERROR.
• Web fallback cannot preserve a caller-provided VQD. The client rejects that fallback instead of silently ignoring the VQD.
• Web result enrichment fields such as embedded image/video modules are outside P0.
• Image and video search are planned for P1. Version 0.1.0 does not export or promise those APIs.
• Default CI does not contact DuckDuckGo.

Evidence status

The local suite and downstream canaries remain author-run evidence. A separate reviewer accepted the frozen RC2 candidate after isolated artifact, package, failure-case, and clean-checkout verification. OpenCandle PR #145 and intercept-mcp PR #6 later merged focused Web/News migrations; those merges provide downstream maintainer acceptance for those specific changes. None of this evidence proves broad production adoption or provider stability.

Version 0.1.0 promotes the accepted RC2 runtime code. The stable release delta contains documentation, repository metadata, package version metadata, and the publish workflow. It does not change runtime behavior.