Support and compatibility

ddg-kit is a community-maintained compatibility client. This document explains what the project can verify and what information helps the project maintain the client.

Evidence levels

Use these terms when you describe support:

Level	Meaning
Implemented	The public API, offline fixtures, and package-consumer checks pass locally.
Canary verified	A named downstream project builds or passes focused tests with ddg-kit.
Maintainer accepted	A downstream maintainer has reviewed and merged a focused migration.
Not verified	The project has no current evidence for this environment, provider path, or workload.

These levels are separate from provider availability. DuckDuckGo does not provide a supported public contract for the endpoints used by this package. The project therefore does not promise a service-level agreement, a result ranking, or uninterrupted live access.

Report provider breakage

Use the provider breakage issue form when a known Web or News operation changes behavior.

Include:

• the ddg-kit version and Node.js version;
• the operation and representation, when known;
• the observed DdgError code and HTTP status, when available;
• a short reproduction sequence that does not expose private data;
• the expected result and the observed result.

Do not include response bodies, cookies, signed URLs, VQD tokens, proxy credentials, or private queries. Use invented values or describe the query shape when a query detail is necessary.

The maintainer will classify the report as one of these cases:

1. a provider change that needs a new fixture and parser update;
2. a package defect that needs a focused regression test;
3. a downstream compatibility issue that belongs in a migration guide;
4. an unsupported request that needs a compatibility proposal; or
5. an incomplete report that needs more safe, reproducible evidence.

Challenges, rate limits, and access controls are provider behavior. The project will classify them and fail closed. It will not add bypasses or turn uncertain responses into empty success.

Request a new compatibility surface

Use the compatibility request issue form for Images, Videos, autocomplete, VQD helpers, spice endpoints, or a result field that is outside the current compatibility claim.

A request is ready for design review when it names:

• a real downstream consumer or a concrete integration need;
• the imports, options, result fields, and failure behavior that the consumer needs;
• the compatibility cost and any semantics that cannot be preserved;
• a synthetic fixture plan;
• a packed ESM/CommonJS consumer check; and
• a downstream canary and rollback plan.

Download counts can help rank requests. They do not replace a reproducible contract or downstream evidence.

Contribute a fix

For a focused fix, start with a synthetic fixture and a public-interface test. Keep the change inside the existing Web/News boundary unless a compatibility proposal has been reviewed. The pull request should state the behavior under review, the checks that passed, known limitations, and the rollback path.

Read CONTRIBUTING.md for repository rules. Read SECURITY.md for vulnerability reports.

Read GOVERNANCE.md for the distinction between local verification, independent review, downstream acceptance, and long-term maintenance evidence.

Community maintenance means that the repository provides a transparent maintenance path. It does not mean that the repository owns duck-duck-scrape, represents DuckDuckGo, or guarantees that every downstream surface will be implemented.