SearXNG SDK

An enterprise-grade TypeScript SDK for integrating with SearXNG search engine.

Features

• Type-safe API with full TypeScript support
• Comprehensive error handling
• Page content retrieval
• Configurable search parameters
• Result processing utilities
• Enterprise-grade implementation with timeout handling, retries, and rate limiting awareness

Installation

npm install searxng-sdk

Quick Start

import { createSearXNGClient } from 'searxng-sdk';

// Create a client instance
const searxng = createSearXNGClient({
  baseUrl: 'http://localhost:8888',  // Your local SearXNG instance URL
});

// Perform a search
async function search() {
  try {
    const results = await searxng.search({
      query: 'typescript AI projects',
      limit: 10,
      fetchContent: true  // Retrieve full page content
    });
    
    console.log(`Found ${results.totalResults} results`);
    
    results.items.forEach(item => {
      console.log(`- ${item.title} (${item.url})`);
      if (item.content) {
        console.log(`  Content length: ${item.content.length} characters`);
      }
    });
  } catch (error) {
    console.error('Search failed:', error);
  }
}

search();

Advanced Usage

Custom Configuration

const searxng = createSearXNGClient({
  baseUrl: 'http://localhost:8888',
  timeout: 60000,  // 60 seconds
  headers: {
    'X-Custom-Header': 'value'
  },
  defaultSearchOptions: {
    language: 'en-US',
    safesearch: 0,  // Disable safe search
    limit: 20
  }
});

Processing Search Results

import { ResultProcessor } from 'searxng-sdk';

// After performing a search:
const results = await searxng.search({ query: 'machine learning', fetchContent: true });

// Extract text from HTML content
const textContent = ResultProcessor.extractTextFromHtml(results.items[0].content || '');

// Summarize content
const summary = ResultProcessor.summarizeContent(results.items[0]);

// Extract keywords from results
const keywords = ResultProcessor.extractKeywords(results.items);

// Categorize results by domain
const domainCounts = ResultProcessor.categorizeByDomain(results.items);

Fetching Content for a Specific URL

const content = await searxng.fetchContentForUrl('https://example.com');
console.log('Page content:', content);

Error Handling

The SDK uses custom error types to make error handling more predictable:

import { SearchErrorType } from 'searxng-sdk';

try {
  const results = await searxng.search({ query: 'example' });
} catch (error) {
  if (error instanceof SearchError) {
    switch (error.type) {
      case SearchErrorType.NETWORK_ERROR:
        console.error('Network connection issue:', error.message);
        break;
      case SearchErrorType.RATE_LIMIT:
        console.error('Rate limit reached:', error.message);
        break;
      case SearchErrorType.SERVER_ERROR:
        console.error('SearXNG server error:', error.message);
        break;
      // Handle other error types...
      default:
        console.error('Unknown error occurred:', error.message);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

License

MIT