🦆 DuckDuckJS

DuckDuckJS is a lightweight JavaScript / TypeScript module designed to interact with DuckDuckGo’s AI chat and search APIs.
It supports multiple AI models such as GPT-4o-mini, Claude, LLaMA, and Mistral, offering real-time streaming responses and clean integration via async generators.

⚡ Features

• Conversational AI Chat
• Text-based Search via DuckDuckGo
• Streaming responses with for await...of
• Privacy-friendly learning tool
• Built with minimal dependencies

🛠 Installation

npm install duckduckjs

🚀 Usage

📥 Import DuckDuck Class

import { DuckDuck, CHAT_MODELS } from 'duckduckjs';

🛎 Initialize DuckDuck

const duckduck = new DuckDuck();

💬 Start a Chat

const messages = [{ role: 'user', content: 'Tell me a joke.' }];

for await (const response of duckduck.chatYield(messages, CHAT_MODELS['gpt-4o-mini'])) {
  console.log(response);
}

🔎 Perform a Text Search

const results = await duckduck.text('latest AI news');
console.log(results);

🧠 Supported Models

• gpt-4o-mini
• llama-3.3-70b
• claude-3-haiku
• o3-mini
• mistral-small-3

⚙️ Development Process

DuckDuckJS started as a minimal wrapper for DuckDuckGo’s endpoints. The journey looked like this:

1. Implemented basic HTTP requests for chat & search.
2. Discovered the VQD token requirement, added custom token logic.
3. Integrated async generators for real-time streaming responses.
4. Built a model abstraction layer to support multiple AI providers.
5. Refined the library to keep dependencies minimal and easy to extend.
6. Finally, open-sourced it to help students and developers experiment with unofficial AI APIs.

⚠️ Challenges & ✅ Solutions

🔒 Unofficial API Instability

DuckDuckGo doesn’t provide official documentation. ✔️ Wrote resilient request logic and token handling.

📡 Streaming Chat Responses

Needed to simulate live, token-by-token output. ✔️ Used async generators with for await...of.

🔑 Handling VQD Tokens

Fetching dynamic VQD tokens reliably was tricky. ✔️ Added a custom VQD token handler.

📚 Tech Stack

• TypeScript / JavaScript
• Node.js
• Async Generators
• Unofficial DuckDuckGo API

🚀 Key Learnings

1. Unofficial APIs are powerful but fragile — always prepare for sudden changes.
2. Streaming UX makes even a CLI tool feel interactive and modern.
3. Abstraction layers keep a codebase flexible and future-proof.

🔎 Troubleshooting

• Invalid_VQD Error: Re-run the chat or search function.

For issues or feature requests, check out the repo: 👉 DuckDuckJS GitHub

🧑‍💻 Author

Developed by Raj Dave. Inspired by deedy5/duckduckgo_search.

⚠️ Disclaimer

This library is not affiliated with DuckDuckGo and is for educational purposes only. It is not intended for commercial use or to violate DuckDuckGo’s Terms of Service.

Official DuckDuckGo website: https://duckduckgo.com