venym-search

TypeScript SDK for the Venym Search API. Zero runtime dependencies — uses native fetch.

Install

npm install venym-search

Setup

import { VenymSearch } from "venym-search";

const client = new VenymSearch({ apiKey: "sk_live_..." });
// Or custom base URL:
// const client = new VenymSearch({ apiKey: "sk_live_...", baseUrl: "https://your-instance.com/api/v1" });

Methods

client.search({ query, max_results?, auto_scrape_top?, include_contacts?, include_social? })

Search + optional auto-scraping, contacts, and social profiles.

const res = await client.search({
  query: "best AI tools 2026",
  max_results: 10,
  auto_scrape_top: 3,
  include_contacts: true,
  include_social: true,
});

console.log(res.search_results);  // [{title, link, snippet, position, date}]
console.log(res.scraped_content); // [{url, title, text, links, images, metadata, error}]
console.log(res.contacts);        // [{type, value, source_url, source_title}]
console.log(res.social_profiles); // [{platform, url, username, source_url, source_title}]
console.log(res.credits_used, res.remaining_credits);

client.scrape({ url, extract?, wait_for?, timeout?, use_browser? })

Scrape a single URL.

const res = await client.scrape({
  url: "https://example.com",
  extract: ["h1", ".main-content"],
  wait_for: "article.loaded",
  timeout: 30,
  use_browser: false,
});

console.log(res.title, res.text);
console.log(res.credits_used);

client.batchScrape({ urls, extract?, timeout?, use_browser? })

Scrape multiple URLs in one request.

const results = await client.batchScrape({
  urls: ["https://example.com", "https://other.com"],
  timeout: 30,
});

client.health()

Check API status.

const { status } = await client.health();

Error Handling

import { VenymSearchError, RateLimitError, AuthenticationError } from "venym-search";

try {
  await client.search({ query: "test" });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid API key
  } else if (err instanceof RateLimitError) {
    // 429 — back off
  } else if (err instanceof VenymSearchError) {
    console.log(err.status, err.message);
  }
}

Backwards Compatibility

The SDK supports imports under the old SearchHive names:

import { SearchHive } from "venym-search"; // deprecated alias for VenymSearch

Old branded method names still work but are deprecated:

| Deprecated | Use Instead | |------------|-------------| | client.swiftSearch() | client.search() | | client.scrapeForge() | client.scrape() | | client.batchScrape() | (unchanged) |

Old type names are aliased: SwiftSearchParams → SearchParams, ScrapeForgeResponse → ScrapeResponse, etc.

License

MIT