SearXNG TypeScript SDK

A strongly-typed TypeScript client for interacting with SearXNG, a privacy-focused metasearch engine.

Features

• Fully TypeScript: Type-safe API with proper TypeScript definitions
• Zod Validation: Runtime validation of API responses
• Fluent Interface: Chainable methods for configuring search requests
• Complete API Coverage: Support for all SearXNG search parameters
• Modern: Uses native fetch API and modern ES features
• Flexible: Works in Node.js, browsers and other JavaScript runtimes

Installation

npm install @eleven-am/searxng-sdk

Quick Start

import { SearXNGClient } from '@eleven-am/searxng-sdk';

// Initialize with your SearXNG instance URL
const searx = new SearXNGClient('https://your-searxng-instance.org');

// Perform a simple search
async function searchExample() {
  try {
    const results = await searx.search('privacy tools');
    console.log(`Found ${results.results.length} results`);
    
    // Results are typed!
    results.results.forEach(result => {
      console.log(`${result.title}: ${result.url}`);
    });
  } catch (error) {
    console.error('Search failed:', error);
  }
}

searchExample();

Advanced Usage

Configuring Searches

import { SearXNGClient, Format, TimeRange, SafeSearchLevel } from '@eleven-am/searxng-sdk';

const searx = new SearXNGClient('https://your-searxng-instance.org');

async function advancedSearch() {
  const results = await searx
    .setLanguage('en')
    .setSafeSearch(SafeSearchLevel.MODERATE)
    .setTimeRange(TimeRange.MONTH)
    .setCategories(['general', 'science'])
    .setEngines(['google', 'bing', 'duckduckgo'])
    .setPage(1)
    .setFormat(Format.JSON)
    .search('climate change research');
    
  // Process results
  console.log(`Found ${results.results.length} results`);
}

Custom Headers

searx.setHeaders({
  'User-Agent': 'My Custom App/1.0',
  'Authorization': 'Bearer token123'
});

Working with Plugins

// Enable specific plugins
searx.enablePlugins(['Hash_plugin', 'Tracker_URL_remover']);

// Disable specific plugins
searx.disablePlugins(['Vim-like_hotkeys']);

API Reference

Method Parameters

| Method | Parameters | Description | |---------------------|--------------------------------------|---------------------------------------------------| | constructor | baseUrl: string | Base URL of the SearXNG instance | | | defaultOptions?: SearXNGOptions | Default options for all requests | | search | query: string | The search query | | | options?: SearXNGOptions | Additional options for this specific search | | setHeaders | headers: Record<string, string> | Custom HTTP headers for requests | | setLanguage | language: string | Language code (e.g., 'en', 'fr', 'de') | | setSafeSearch | level: SafeSearchLevel | Safe search level (0=off, 1=moderate, 2=strict) | | setTimeRange | timeRange: TimeRange | Time range ('day', 'month', 'year') | | setPage | pageNumber: number | Page number (starts at 1) | | setCategories | categories: string \| string[] | Category or list of categories | | setEngines | engines: string \| string[] | Engine name or list of engine names | | enablePlugins | plugins: string \| string[] | Plugin name or list of plugin names | | disablePlugins | plugins: string \| string[] | Plugin name or list of plugin names | | setFormat | format: Format | Output format ('json', 'csv', 'rss') |

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

GPL-3.0