search-web-api 1.0.76 → 1.0.78

package/package.json

@@ -2,7 +2,7 @@
   "name": "search-web-api",
   "description": "70+ search engines across 10 categories and Scrape Extract API",
   "type": "module",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "author": "vtempest",
   "license": "rights.institute/PROSPER",
   "repository": {
@@ -12,10 +12,12 @@
   },
   "exports": {
     ".": {
+      "types": "./src/search.ts",
       "import": "./src/search.ts",
       "require": "./src/search.ts"
     },
     "./*": {
+      "types": "./src/*.ts",
       "import": "./src/*",
       "require": "./src/*"
     }
@@ -23,7 +25,8 @@
   "scripts": {
     "dev": "bun --watch demo/index.ts",
     "start": "bun demo/index.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",

package/src/search/__tests__/public-searxng.test.ts

@@ -1,16 +1,17 @@
 /**
  * @fileoverview Unit tests for SearXNG search functionality
  */
+import { beforeEach, describe, expect, it, vi, type MockedFunction } from "vitest";
 import { searchWeb, searchSearxng } from "../public-searxng";
 import grab from "grab-url";
 
 // Mock grab-url
-jest.mock("grab-url");
-const mockGrab = grab as jest.MockedFunction<typeof grab>;
+vi.mock("grab-url");
+const mockGrab = grab as MockedFunction<typeof grab>;
 
 describe("searchWeb", () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   describe("Private SearXNG instance (JSON)", () => {
@@ -223,7 +224,7 @@ describe("searchWeb", () => {
         infoboxes: [],
       };
 
-      const consoleSpy = jest.spyOn(console, "warn").mockImplementation();
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
       mockGrab.mockResolvedValueOnce(mockResults);
 
       const result = await searchWeb("test", {
@@ -316,15 +317,13 @@ describe("searchWeb", () => {
         </article>
       `;
 
-      const consoleSpy = jest.spyOn(console, "warn").mockImplementation();
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
       mockGrab.mockResolvedValueOnce(mockHtml);
 
       await searchWeb("test", { privateSearxng: false });
 
-      expect(consoleSpy).toHaveBeenCalledWith(
-        expect.stringContaining("domain-only"),
-        expect.any(String)
-      );
+      // The public-scrape path logs a single formatted message.
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("domain-only"));
       consoleSpy.mockRestore();
     });
   });
@@ -491,15 +490,16 @@ describe("searchWeb", () => {
 
 describe("searchSearxng", () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
-  it("should adapt options to searchWeb", async () => {
-    mockGrab.mockResolvedValueOnce({
-      results: [{ title: "Test", url: "https://example.com", content: "Content", score: 0.9 }],
-      suggestions: ["test1"],
-      infoboxes: [],
-    });
+  it("should adapt its options onto the underlying search request", async () => {
+    mockGrab.mockResolvedValueOnce(`
+      <article class="result">
+        <h3><a href="https://example.com/article">Test</a></h3>
+        <p class="content">Content</p>
+      </article>
+    `);
 
     const result = await searchSearxng("test query", {
       categories: ["news"],
@@ -507,10 +507,30 @@ describe("searchSearxng", () => {
       language: "fr",
     });
 
+    // searchSearxng maps categories[0] -> category, pageno -> page, language -> lang.
+    expect(mockGrab).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ category_news: 1, pageno: 2, language: "fr" })
+    );
     expect(result).toHaveProperty("results");
     expect(result).toHaveProperty("suggestions");
     expect(result.results).toHaveLength(1);
-    expect(result.suggestions).toHaveLength(1);
+  });
+
+  it("defaults category, page and language when no options are given", async () => {
+    mockGrab.mockResolvedValueOnce(`
+      <article class="result">
+        <h3><a href="https://example.com/article">Test</a></h3>
+        <p class="content">Content</p>
+      </article>
+    `);
+
+    await searchSearxng("test query");
+
+    expect(mockGrab).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ category_general: 1, pageno: 1, language: "en-US" })
+    );
   });
 
   it("should handle array results from searchWeb", async () => {

package/src/sources/academic/arxiv.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the arXiv API for academic paper search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/academic/core.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the CORE API for open-access academic papers (requires CORE_API_KEY).
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const core: EngineFunction = async (

package/src/sources/academic/crossref.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Crossref API for scholarly work metadata.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const crossref: EngineFunction = async (

package/src/sources/academic/doaj.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Directory of Open Access Journals (DOAJ) API.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const doaj: EngineFunction = async (

package/src/sources/academic/google_scholar.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Google Scholar search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/academic/openalex.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the OpenAlex API for scholarly works, reconstructing abstracts from their inverted index.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 function reconstructAbstract(

package/src/sources/academic/pubmed.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes PubMed search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/academic/semantic_scholar.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Semantic Scholar API for academic papers.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const semantic_scholar: EngineFunction = async (

package/src/sources/academic/wikidata.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Wikidata API for entity search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const wikidata: EngineFunction = async (

package/src/sources/general/baidu.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Baidu web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/bing.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Bing web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/brave.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Brave web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/duckduckgo.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes DuckDuckGo HTML search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/google.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Google web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/mojeek.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Mojeek web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/qwant.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Qwant search API.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const qwant: EngineFunction = async (

package/src/sources/general/startpage.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Startpage web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/yahoo.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Yahoo web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/general/yandex.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Yandex web search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/images/bing_images.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Bing Images search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/images/deviantart.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes DeviantArt search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/images/flickr.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Flickr API for photo search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const flickr: EngineFunction = async (

package/src/sources/images/google_images.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Google Images search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const google_images: EngineFunction = async (

package/src/sources/images/imgur.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Imgur search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/images/openclipart.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Openclipart search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/images/pixabay.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Pixabay API for image search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const pixabay: EngineFunction = async (

package/src/sources/images/unsplash.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Unsplash API for photo search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const unsplash: EngineFunction = async (

package/src/sources/images/wallhaven.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Wallhaven API for wallpaper search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const wallhaven: EngineFunction = async (

package/src/sources/it/crates.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the crates.io API for Rust package search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const crates: EngineFunction = async (

package/src/sources/it/dockerhub.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Docker Hub API for container image search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const dockerhub: EngineFunction = async (

package/src/sources/it/github.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the GitHub API for repository search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const github: EngineFunction = async (

package/src/sources/it/gitlab.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the GitLab API for project search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const gitlab: EngineFunction = async (

package/src/sources/it/npm.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the npm registry search API.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const npm: EngineFunction = async (

package/src/sources/it/packagist.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Packagist API for PHP package search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const packagist: EngineFunction = async (

package/src/sources/it/pypi.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes PyPI search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const pypi: EngineFunction = async (

package/src/sources/it/rubygems.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the RubyGems API for gem search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const rubygems: EngineFunction = async (

package/src/sources/it/stackoverflow.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Stack Exchange API for Stack Overflow question results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const stackoverflow: EngineFunction = async (

package/src/sources/maps/apple_maps.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Apple Maps API for place search results, with automatic access-token caching/renewal.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 // Token management for Apple Maps API

package/src/sources/maps/openstreetmap.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the OpenStreetMap Nominatim API for place search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const openstreetmap: EngineFunction = async (

package/src/sources/maps/photon.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Photon (Komoot) geocoding API for place search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const photon: EngineFunction = async (

package/src/sources/news/bing_news.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Bing News search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/news/google_news.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Google News search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/news/hackernews.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Hacker News (Algolia) API for story search results.
+ */
 import { EngineFunction } from "../../types/search-engine-interface.js";
 
 export const hackernews: EngineFunction = async (

package/src/sources/news/yahoo_news.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Yahoo News search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/shopping/ebay.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes eBay marketplace search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/social/mastodon.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Mastodon public API for post search results.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 export const mastodon: EngineFunction = async (

package/src/sources/social/medium.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Medium search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/social/reddit.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Reddit search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/social/soundcloud.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes SoundCloud search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/social/twitter.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Twitter/X search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/specialized/annas_archive.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Anna's Archive search results, trying multiple mirror domains.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/specialized/archive.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Internet Archive API for search results.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 export const archive: EngineFunction = async (

package/src/sources/specialized/genius.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Genius API for song/lyrics search results.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 export const genius: EngineFunction = async (

package/src/sources/specialized/goodreads.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes Goodreads search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/specialized/imdb.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes IMDb search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 

package/src/sources/specialized/openlibrary.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Open Library API for book search results.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 export const openlibrary: EngineFunction = async (

package/src/sources/specialized/wikipedia.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries the Wikipedia API for article search results.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 export const wikipedia: EngineFunction = async (

package/src/sources/specialized/wttr.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that queries wttr.in for weather data, mapping WWO condition codes to human-readable descriptions.
+ */
 import { EngineFunction, EngineResult } from "../../types/search-engine-interface.js";
 
 // Weather condition mapping

package/src/sources/torrents/1337x.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes 1337x torrent search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/torrents/eztv.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes EZTV torrent search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";
 

package/src/sources/torrents/kickass.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Engine adapter that scrapes KickassTorrents search results.
+ */
 import { parseHTML } from "linkedom";
 import { EngineFunction } from "../../types/search-engine-interface.js";